> For the complete documentation index, see [llms.txt](https://docs.basetnet.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.basetnet.com.br/core/readme.md).

# tNet Core

**tNet** é o framework oficial da **Trigueiro Network** para FiveM. É composto pelo runtime `tnet_core` e uma suíte de 70+ resources pensados para trabalhar em conjunto.

Esta é a **documentação técnica** para quem vai escrever scripts em cima do tNet.

***

## Estrutura

O framework é dividido em três camadas:

**`tnet_core`** — o runtime. Carrega antes de tudo, expõe o namespace `tNet`, as classes `character` / `user` / `group`, e os utilitários compartilhados (callback, roles, groups, hooks, money, locale, routing buckets). Todo resource que importa `@tnet_core/library.lua` herda esse contexto.

**Resources oficiais** — 70+ scripts que entregam as features do servidor: inventário, HUD, target, job system, veículos, banco, empresas, imóveis, minigames, minimap, rádio, e por aí. Cada um é autônomo mas compartilha convenções e APIs com o core.

**Sua camada** — scripts customizados que consomem a API pública do tNet: exports, eventos, callbacks, hooks. A doc serve para que você saiba o que está disponível e como integrar sem reinventar nada.

***

## Performance

Pontos onde o framework foi pensado para escalar:

* **OneSync-first**: entidades server-side, statebags para sync de flags, entity ownership consistente.
* **Cache em memória** de grupos, contas bancárias e personagens ativos — queries pesadas rodam no boot, não a cada request.
* **Prepared statements** (`oxmysql`) em toda query server-side.
* **Hooks cronometrados**: callbacks de hook que passam de 100ms recebem warning no console com `resource:event:hookId` para diagnóstico rápido.
* **Scope events**: envio de eventos limitado a jogadores no mesmo scope network, reduzindo banda em eventos de ambiente.
* **Protect anti-spam**: sistema de cooldown por (jogador, evento) com limpeza automática no disconnect.
* **Lua 5.4** — safe navigation (`?.`), `goto`, `<const>`, integer division.

***

## Instalação no seu resource

Adicione no `fxmanifest.lua`:

{% tabs %}
{% tab title="fxmanifest (recomendado)" %}

```lua
dependencies {
    'tnet_core'
}

shared_scripts {
    '@tnet_core/library.lua'
}
```

O namespace `tNet` e as classes `character`, `user`, `group` ficam disponíveis imediatamente.
{% endtab %}

{% tab title="exports (alternativo)" %}

```lua
local tNet = exports.tnet_core:getSharedObject()
```

Útil quando você não controla o `fxmanifest`.
{% endtab %}
{% endtabs %}

Configurações globais do core ficam em `tnet_core/shared/config.lua`.

***

## Como navegar na doc

* [**Core**](/core/readme/client.md) — API do `tnet_core` (client, server, classes).
* **Resources** — uma página por resource no índice lateral, com exports, eventos e receitas de integração.
* **Glossário de statebags** — [conventions/statebags-glossary.md](/conventions/statebags-glossary.md).

### Notação usada

* **Tipos**: `string`, `number`, `boolean`, `table`, `array<T>`, `dict<K,V>`, `vec3`, unions com `|`. `?` = parâmetro opcional.
* **Hints** `{% hint %}`: `danger` para o que **não** fazer, `warning` para efeitos colaterais, `info` para notas úteis.
* **Exemplos**: todo export público tem pelo menos um exemplo Lua que compila.