> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fivenetwork.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# animals

> Animais de estimação (companheiros): invoque um cão/gato a partir de um item do inventário, faça-o seguir você, guardá-lo e colocá-lo/retirá-lo de veículos pelo menu dinâmico ("Domésticos").

O **animals** gerencia animais de estimação (companheiros). Invoque um cão ou gato a partir de um item do inventário, faça-o seguir você, guarde-o e coloque-o ou retire-o de veículos pelo menu dinâmico "Domésticos".

Cada jogador mantém um único animal de companhia. O animal é invocado ao usar um item do inventário (ex.: `a_c_husky`), que dispara `animals:Spawn` no cliente com o modelo. O ped é criado à frente do jogador, invencível, sem ragdoll, e por padrão o segue (`TaskFollowToOffsetOfEntity`).

O servidor mantém o `NetworkId` por passaporte (`Animal[Passport]`), garantindo apenas um ativo. O ped é removido ao guardar, ao tentar reinvocar (bloqueado) e ao desconectar.

<Info>
  **Interações pelo menu dinâmico:** Ficar/Seguir, Guardar, Colocar/Remover do banco do motorista (em veículo que não seja moto, assento livre).
</Info>

***

## Dependências

<CardGroup cols={2}>
  <Card title="vrp" icon="gears">
    `vRP.Passport` e API base.
  </Card>

  <Card title="dynamic" icon="list">
    Monta o menu dinâmico "Domésticos".
  </Card>

  <Card title="inventory" icon="box">
    Itens que disparam `animals:Spawn`.
  </Card>
</CardGroup>

***

## Eventos

### Recebidos no servidor

| Evento             | Descrição                                                          |
| ------------------ | ------------------------------------------------------------------ |
| `animals:Register` | Armazena o `NetworkId` do ped por passaporte (`Animal[Passport]`). |
| `animals:Cleaner`  | Limpa o registro do animal do jogador.                             |
| `animals:Delete`   | Remove o ped/registro de um passaporte.                            |
| `Disconnect`       | Ao sair, remove o ped e o registro.                                |

### Cliente

| Evento              | Descrição                                                                               |
| ------------------- | --------------------------------------------------------------------------------------- |
| `animals:Dynamic`   | Monta o menu dinâmico "Domésticos" (Ficar/Seguir, Guardar, Colocar/Remover do veículo). |
| `animals:Spawn`     | Recebe `Model` e cria o ped à frente do jogador (invencível, seguindo).                 |
| `animals:Functions` | Recebe `Mode` (`Seguir`/`Deletar`/`Colocar`/`Remover`) e executa a ação.                |
| `animals:Delete`    | Zera as variáveis locais do animal.                                                     |

***

## Customização

* **Raças/modelos:** definidos pelos itens em `inventory/server-side/itens.lua` (`a_c_cat_01`, `a_c_husky`, `a_c_poodle`, `a_c_pug`, `a_c_retriever`, `a_c_rottweiler`, `a_c_shepherd`, `a_c_westy`). Adicionar = mapear um item que dispare `animals:Spawn` com o hash.
* **Comportamento:** parâmetros de spawn em `client-side/core.lua` (handler `animals:Spawn`).

<Note>
  Totalmente em Lua: sem NUI, config, comandos, exports ou persistência (vínculo só em memória).
</Note>