From 07e7f053adad812aa2b7d1b4f8228248935a88e7 Mon Sep 17 00:00:00 2001 From: Arantes83 Date: Sun, 2 Aug 2026 17:48:30 -0300 Subject: [PATCH] docs(repo): expand Arma 3 development guide --- README.md | 470 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 361 insertions(+), 109 deletions(-) diff --git a/README.md b/README.md index 7f0e6c1..a9d4755 100644 --- a/README.md +++ b/README.md @@ -1,159 +1,411 @@ -# **Brazilian Armed Forces (BRAF) Mod** +# Brazilian Armed Forces (BRAF) Mod ![BRAF Mod](https://i.imgur.com/Fe7obui.png "BRAF Mod") -Aqui consta o repositório do BRAF Mod, modificação para a plataforma Arma 3 inspiranda nas Forças Armadas Brasileiras, a ser utilizado por seus desenvolvedores procurando seguir boas práticas de programação. o versionamento do repositório é feito através do GIT utilizando o seguinte repositório: -> +Repositório de desenvolvimento do **Brazilian Armed Forces (BRAF) Mod**, uma modificação para **Arma 3** inspirada nas Forças Armadas Brasileiras. -## Checklist de Asset por LODs +- Jogo-alvo: Arma 3 +- Engine: Real Virtuality 4 +- Plataforma de código: SQF, `config.cpp`, `.hpp`, `.ext`, `.fsm` e `model.cfg` +- Autor de mods e addons BRAF: `BRAF_TEAM` +- Repositório: [git.valmo.dev/projectbraf/braf](https://git.valmo.dev/projectbraf/braf) +- Licença e regras de distribuição: [LICENSE.md](LICENSE.md) e [LICENSE_PT-BR.md](LICENSE_PT-BR.md) -### LODs de distância +Este é um repositório de **fonte**. O checkout contém configurações, scripts, modelos, texturas, materiais, sons, animações, documentação, ferramentas e referências usadas para desenvolver os addons. O jogo carrega addons por meio de PBOs, mas a validação do código-fonte e dos assets deve ser feita antes de qualquer processo de release. -- LOD 1..n - QUALQUER ASSET DEVE TER LODs DE DISTÂNCIA -- Usar modificador decimate (Blender) em 0.5 como fator entre um LOD e outro além de retirar partes pequenas de acordo com cada LOD de distância -- Utilizar somente um mapa UV, checar no Blender E no Object Builder o nº de mapas UV. -- Deve possuir as seguintes *Named Properties:* (Object Builder): - - *lodnoshadow = 1*; - Caso o modelo não possua LOD de sombra, seu valor deve ser 0 e devemos usar a seguinte named property no Geometry LOD: - - *sbsource = visualex* - - Utilizável somente em props e prédios em geral, nada que tenha View Pilot. +## Dependências e compatibilidade -### View Pilot +### CBA -- O que é visto por piloto/motorista quando se trata de veículos -- O que é visto em primeira pessoa quando se trata de uniformes, peças de vestuário ou armas. +O BRAF requer o [Community Base Addons (CBA)](https://github.com/CBATeam/CBA_A3) como dependência de projeto. O código existente usa padrões e APIs do CBA, incluindo: -### View Gunner +- macros comuns e `script_xeh.hpp`; +- `CBA_fnc_compileFunction`; +- CBA Extended Event Handlers; +- `CBA_weaponEvents`; +- eventos e sistemas de armas compartilhados. -- O que é visto por atirador em veículos ou lançadores estáticos. +Não remova CBA de `requiredAddons[]`, macros ou eventos como uma otimização. Antes de criar um novo evento, verifique se o addon já usa um Event Handler nativo ou um CBA Extended Event Handler. -### View Commander +### ACE -- O que é visto por comandante em veículos. +O [ACE3](https://github.com/acemod/ACE3) é tratado normalmente como **compatibilidade opcional**, não como dependência obrigatória de todos os addons BRAF. O repositório possui propriedades e integrações ACE em áreas como balística, aquecimento de armas, audição, cargo, reabastecimento e sobrepressão. -### View Cargo +Ao adicionar compatibilidade ACE: -- O que é visto por tripulação que não seja FFV (Firing from Vehicles), esta última vira ViewGunner. +- preserve a separação entre conteúdo BRAF e compatibilidade; +- não adicione ACE a `requiredAddons[]` sem evidência do addon afetado; +- não invente funções, propriedades ou classes ACE; +- confirme se a integração já existe em outro addon BRAF; +- preserve a possibilidade de carregar o conteúdo sem ACE quando a integração for opcional. -### Geometry +## Organização do repositório -- É usado para ter colisão na engine do arma entre personagens e veículos contra objetos estáticos como árvore, casa e outras props de cenário. -- O modelo deve ser fechado, com geometria convexa, triangulado e com sharp edges. -- Uma vez importado para o Object Builder, selecione o objeto todo, vá em Structures -> Topology -> Find Components, em seguida adicione uma massa em kilogramas, condizente com o objeto real e no mínimo de 10kg. -- O nº de componentes criado no passo anterior não deve ultrapassar 400 componentes, e cada componente não pode ter mais de 255 triângulos. -- Não pode ter um segundo mapa UV. -- Pressupondo que o objeto esta no centro da cena, deve ter no máximo 200x200 metros, mais do que isso ele não calcula colisão, não existe limite para altura. -- Deve possuir as seguintes *Named Properties:*, todas em letras mínuscula (Object Builder): - - *autocenter = 1*; - - Caso você queira centralizar o objeto na cena. - - *reversed = 1*; - - Caso você queira mudar a orientação do objeto. - - *map = ????*; - - [Variados valores disponíveis aqui](https://community.bistudio.com/wiki/Arma_3:_Named_Properties#map), essa propriedade só é relevante para assets que irão em um mapa, permite que sejam mostrados os ícones no mapa 2D do jogo. - - *buoyancy = 1*; - - 1 -> objeto boiará. - - 0 -> objeto não boiará. - - *aicovers = 1*; - - 1 -> IA vai usar o objeto como cobertura; - - 0 -> Não vai usar; - - *canbeoccluded = 1*; - - 1 -> O objeto não será renderizado quando estiver atrás de objetosmaiores; - - 0 -> Será renderizado; - - *canocclude = 1* - - 1 -> O objeto irá impedir o que estiver atrás de ser renderizado,conforme propriedade acima; - - 0 -> Não impedirá; - - *damage/dammage = ???* - - engine -> O objeto explode quando destruído. - - building -> O objeto irá afundar no solo e ser substituído por ummodelo em ruínas. - - wreck -> O objeto será substituído por um modelo destruído,referenciado no LOD wreck. - - tree -> O objeto irá tombar numa direção aleatória. - - tent -> O objeto irá colapsar, chapado no chão. - - wall -> O objeto irá tombar na direção do choque. - - *sbsource = shadowvolume* - - shadowvolume -> O objeto irá gerar sombra utilizando o LOD ShadowVolume. - - visualex -> O objeto irá gerar sombra utilizando os LOD visuais, muito mais pesados, portanto utilizado somente em objetos estáticos. +O BRAF é dividido por responsabilidade e por tipo de conteúdo. Cada diretório de addon deve ser tratado como uma unidade de configuração e carregamento, sem presumir que todos os diretórios tenham a mesma estrutura interna. -### Fire Geometry +| Área | Exemplos no repositório | Responsabilidade | +|---|---|---| +| Base e sistemas compartilhados | `braf_main`, `braf_weapons_core`, `braf_damage`, `braf_hurt` | Facções, funções comuns, munições, dano e estados relacionados | +| Aviação e resgate | `braf_air`, `braf_air2`, `braf_sar`, `braf_optics_air` | Helicópteros, aeronaves, armamento aéreo, interfaces, EFS e guincho | +| Naval | `braf_boat`, `braf_ships`, `braf_weapons_naval` | Embarcações, navios e armas navais; o addon compartilhado de armas navais é `braf_weapons_naval` | +| Veículos terrestres e estáticos | `braf_armored`, `braf_soft`, `braf_static`, `braf_structures`, `braf_structures_land`, `braf_structures_ammoboxes` | Blindados, veículos leves, armas estáticas, estruturas e caixas | +| Personagens e equipamentos | `braf_characters_*`, `braf_insignia` | Unidades, uniformes, coletes, mochilas, capacetes, óculos, aviação e insígnias | +| Armamentos | `braf_weapons_*` | Fuzis, metralhadoras, pistolas, submetralhadoras, lançadores, miras, muzzle attachments e sons | +| Código de origem | `source` | Áreas de origem, componentes e staging que devem ser entendidos antes de qualquer integração | +| Referências externas | `libs` | Material técnico de terceiros; é somente leitura e não é uma dependência automática | +| Ferramentas | `make` | Ferramentas auxiliares de desenvolvimento e release; devem ser inspecionadas antes de serem executadas | +| Testes | `tests` | Testes focados e validações estruturais do repositório | +| Instruções e skills | `AGENTS.md`, `.agents` | Regras persistentes do projeto e skill local de Arma 3 | -- Utilizado para detectar colisão e efeitos de colisão entre projetis e qualquer tipo de objeto. -- Segue as mesmas regras gerais do LOD de Geometry, com a exceção de que não precisa ter massa e precisa ter o material de penetração (RVMAT) localizado em /a3/data_f/penetration/ aplicado a fim de calcular a balística intermediária do objeto quando atingido. -- precisam ter os proxies dos ocupantes do veículo, do contrário, não irão sofrer dano. +`libs` contém, entre outros materiais, referências de CBA, ACE, HAFM, USAF, WMO e outros projetos. O material deve ser classificado como dependência obrigatória, compatibilidade opcional, referência técnica, biblioteca reutilizável com licença compatível ou material desconhecido antes de qualquer reutilização. -### View Geometry +## Estrutura de um addon -- Utilizado para cálculo de oclusão (a engine não renderizará o que estiver atrás do objeto), além disso é utilizado para fazer com que a IA do jogo enxergue ou não outras entidades em jogo. -- precisam ter os proxies dos ocupantes do veículo, do contrário, não serão atacados pela IA. -- Precisa ter menos de 3500 vértices em cada objeto. +Um addon BRAF normalmente possui um `config.cpp` na raiz e pode incluir arquivos de configuração, funções, modelos e assets: -### Geometry PhysX +```text +braf_example/ +├── config.cpp +├── *.hpp +├── functions/ +│ └── fn_example.sqf +├── data/ +│ ├── *.paa +│ └── *.rvmat +├── model.cfg +└── *.p3d +``` -- Tipo de geometria especial utilizado para detecção e cálculo de colisão entre veículos em geral. -- Também seguem as regras gerais do Geometry, porém devem ser o mais simples possível, e com o menor nº de componentes possível (max 3 em geral) e sem massa. +Nem todos os addons possuem todos esses itens. A estrutura real do diretório, os includes e os caminhos configurados têm prioridade sobre este exemplo. -### Geometry Buoyancy +O `config.cpp` é o ponto de entrada de configuração do addon. A documentação oficial de criação de addons explica que o jogo usa esse arquivo para processar veículos, armas, sons, funções e os demais dados do addon: [Creating an Addon](https://community.bohemia.net/wiki/Arma_3%3A_Creating_an_Addon). -- Tipo de geometria especial utilizada para cálculo de volume de deslocamento em veículos aquáticos ou objetos que boiam na água. -- Também segue as regras gerais do Geometry e caso tenha mais de um componente, os mesmos não devem se intersectar. -- É relacionado com a massa definida no Geometry (e que também pode ser alterada via script). +### `CfgPatches` -### Roadway +Todo addon deve possuir uma classe `CfgPatches` coerente com o conteúdo que fornece. Ela informa, entre outras coisas: -- É um tipo de superfície que permite que unidades caminhem sobre os objetos, sejam estáticos ou não. -- É representado por planos sobrepostos ao LOD de Geometry do objeto e utiliza uma textura localizada em /a3/data_f/surfaces/ para o efeito visual e sonoro ao caminhar sobre o objeto. -- Pressupondo que o objeto esta no centro da cena, pode ter no máximo 72x72 metros. +- nome da classe de patch; +- `requiredVersion`; +- `requiredAddons[]`; +- `units[]`; +- `weapons[]`; +- metadados como autor e URL. -### Memory +`requiredAddons[]` é informação de **dependência e ordem de carregamento**, não uma lista de todos os mods instalados. Declare somente dependências necessárias e confirme o nome real da classe `CfgPatches` fornecida por cada addon. -- Define pontos de luz, direção de armas de fogo, direção de faróis, direção de escapamento, direção de efeitos de fumaça, pivôs de rotação, eixos de translação, e demais pontos de controle em geral. +Exemplo de padrão para conteúdo novo BRAF: -### Shadow Volume +```cpp +class CfgPatches +{ + class braf_example + { + author = "BRAF_TEAM"; + requiredVersion = 0.1; + requiredAddons[] = {"A3_Weapons_F", "braf_main"}; + units[] = {}; + weapons[] = {}; + }; +}; +``` -- Modelo 3D utilizado para o cast de sombra caso o sbsource do LOD Geometry seja diferente de visualex, e também possui n LODs de distância. -- O modelo deve ser fechado e triangulado, e deve ter sharp edges. +O repositório possui nomes históricos com capitalização diferente. Para classes existentes, preserve a capitalização e as interfaces públicas. Para classes novas, use o padrão BRAF correspondente ao addon e evite criar aliases ou nomes concorrentes sem necessidade de compatibilidade. -### Hitpoints +### Herança de classes -- Define onde certas partes destrutíveis do objeto estão, como rodas, vidros, motor, etc. -- Referência: [Arma 3 - Hitpoints](https://community.bistudio.com/wiki/Arma_3:_Hitpoints) +Arma 3 usa herança de configuração. Antes de derivar uma classe, confirme: -### Wreck +1. o nome exato da classe pai; +2. o addon que fornece a classe pai; +3. o `requiredAddons[]` necessário; +4. quais propriedades são herdadas e quais precisam ser redefinidas; +5. se `scope`, `displayName`, `model`, `magazines`, `weapons`, torres e Event Handlers continuam coerentes. -- Modelo 3D utilizado para representar o objeto destruído quando o LOD Geometry possui a named property damage = wreck. +Use o Config Viewer, os arquivos locais de referência e a documentação oficial de [Class Inheritance](https://community.bohemia.net/wiki/Class_Inheritance). Não copie uma classe pai apenas por semelhança textual. -### Path +### Cadeia de conteúdo de armas -- LOD importante para a IA definir o caminho em seu interior (prédios), não requerido em objetos que a IA não precise desviar de obstáculos. -- Vértices onde a IA pode parar precisam ser definidos por uma named selection do tipo "posXX" (XX é um número de 00 a 99). -- Os paths funcionam melhor quando posicionados 10 cm acima da superfície do Roadway. +Ao alterar armamentos, verifique toda a cadeia: -### Display Picture +```text +CfgWeapons + └── magazines[] / pylonWeapon + └── CfgMagazines + └── ammo + └── CfgAmmo +``` -- Imagem com fundo transparente e tamanho em potência de 2 (como qualquer arquivo .paa, Ex: 128x128px ou 64x128px) que será utilizada para representar o objeto na lista do editor de missões. -- Veículos também devem produzir uma displaypicture em tamanho 1x2 (128x256px por exemplo) para ser utilizado no arsenal ou na ORBAT. +Também confira muzzles, modos de fogo, sons, efeitos, hardpoints, pylon stores, velocidades, alcance, `hit`, `indirectHit`, penetração, rastreadores e compatibilidade com plataformas existentes. -## Config de Assets +Veículos podem consumir várias armas, magazines e munições de addons diferentes. Uma configuração estruturalmente válida ainda pode falhar no jogo se o parent, o pylon, o memory point, o modelo ou o caminho de asset não existir. -Os Mods no Arma 3 são um conjunto de PBO's (Public Bank of Files), que são nada mais do que pastas compactadas, que contém os arquivos de configuração e os assets do mod centralizadas no arquivo config.cpp na raíz da pasta em questão, todos os PBOs do BRAF comelam com o prefixo "braf_" para facilitar a identificação. +## Funções SQF e `CfgFunctions` -## Padronização de Nomenclaturas +Funções públicas devem ser registradas em `CfgFunctions` e ter um arquivo real no caminho declarado. No BRAF existem exemplos como: -Todas as classes do mod e nomes de arquivos deverão ser precedidas pelo prefixo "braf" e seguir o padrão [snake_case](https://en.wikipedia.org/wiki/Snake_case), onde todas as letras são em minúsculo e as palavras, não poderão haver carateres especiais como "ç" ou acentos como "í", mantendo de preferência em inglês, separadas por subtraços (" _ "), o motivo é que a engine/mikero por si só já transforma todas as classnames para este padrão, os nomes dos pbos também seguirão este padrão. - **Exemplo:** -> "braf_uniform_rolledup_gloves" +- funções comuns de uniforme e identidade em `braf_main`; +- `BRAF_fnc_efs` e `BRAF_fnc_hoist` em `braf_sar`; +- `BRAF_fnc_ASMEngineSmoke` em `braf_weapons_naval`. -- Classname da farda com manga dobrada e luvas +Ao criar ou alterar uma função: -> "braf_static" +- use `params` para validar argumentos; +- declare variáveis locais com `private`; +- documente retorno, máquina de execução e localidade; +- diferencie ambiente agendado de não agendado; +- não use `sleep` em código não agendado; +- preserve o nome público e a capitalização usados pelos consumidores; +- confirme inicialização, JIP, idempotência e comportamento em erro; +- prefira uma função registrada a `call` ou `spawn` remoto arbitrário. -- Classname do PBO de armamentos estáticos +O caminho em `CfgFunctions` e o nome do arquivo precisam corresponder exatamente ao checkout. Uma ocorrência textual do nome da função não prova que ela está registrada ou que o arquivo existe. -## Fechando o PBO +## Multiplayer, localidade e JIP -- Existem 2 maneiras de compactar uma pasta em um arquivo PBO, a primeira é pelo Addon Builder, disponível pelo Arma 3 Tools, que cumpre a missão de gerar um PBO a partir de uma pasta, porém testa o código muito grosseiramente. A segunda é pelo PBOProject ([Mikero's Tools](https://mikero.bytex.digital/)), que além de compactar a pasta em um PBO, também testa o código e o obfusca, garantindo mais segurança e testagem ao mod, o BRAF utiliza o Mikero e sempre que possível, obfusca o PBO. +Arma 3 é uma engine cliente-servidor. Código que funciona em Singleplayer pode falhar em servidor dedicado, Hosted Server, Headless Client ou para um jogador que entra no meio da missão. -- Um maior número de PBOs facilita a correção de bugs porém pode tornar o modo confuso, portanto tenta-se manter uma organização quanto ao tipo e juntar os assets que se relacionam em um mesmo PBO. +Antes de implementar código de rede, identifique: -- ### Obfuscado x Não Obfuscado +- máquina autoritativa; +- dono atual do objeto (`local`); +- diferença entre efeito local e global; +- comportamento de servidor dedicado e servidor hospedado; +- comportamento de cliente, Headless Client e JIP; +- possibilidade de migração de localidade; +- inicialização pré-init, post-init, object init e mission init; +- duplicação de Event Handlers e mensagens; +- necessidade de persistência JIP; +- permissões e validação de argumentos. - - A obfuscação do PBOProject (Mikero), garante mais uma camada de segurança e de testagem ao mod, porém implica limitações, nenhum arquivo poderá conter acentos ou caracteres especiais em seu nome e todas as texturas que forem chamadas após a criação do asset, como via script ou texturas de dado, deverão ficar em um pbo a parte. Mesmo quando não obfuscado, é recomendando usar o Mikero pois ele testa o código e aponta erros de sintaxe queo Addon Builder deixa passar, o que facilita a correção de bugs. **Todos os PBOs do BRAF são binarizados, independente de serem ou não obfuscados**. +Use `isServer`, `isDedicated`, `hasInterface`, `isMultiplayer`, `didJIP` e `local` de acordo com a operação real. `isServer` também retorna verdadeiro em Singleplayer, portanto não deve ser usado isoladamente quando a distinção entre Singleplayer e servidor dedicado for importante. + +### `remoteExec` e `CfgRemoteExec` + +`remoteExec` e `remoteExecCall` devem ser usados somente após verificar a localidade e a configuração de segurança. O fluxo recomendado é: + +1. criar uma função registrada com argumentos explícitos; +2. validar os argumentos na máquina que recebe a chamada; +3. configurar `CfgRemoteExec` quando o modo de whitelist exigir; +4. escolher alvos e JIP conscientemente; +5. testar servidor dedicado, Hosted Server e JIP. + +Não execute `call` ou `spawn` arbitrariamente por rede. A documentação oficial cobre o [Remote Execution](https://community.bohemia.net/wiki/Arma_3%3A_Remote_Execution), os controles de [CfgRemoteExec](https://community.bohemia.net/wiki/CfgRemoteExec) e os efeitos de localidade em [Multiplayer Scripting](https://community.bohemia.net/wiki/Multiplayer_Scripting). + +## CBA Extended Event Handlers e Event Handlers + +Event Handlers nativos são executados na máquina onde foram adicionados, salvo as propriedades específicas de cada evento. Isso deve ser considerado antes de registrar dano, disparo, entrada em veículo, animação, localidade ou inicialização. + +No BRAF: + +- preserve os padrões CBA existentes; +- não sobrescreva um Event Handler de outro addon; +- use Extended Event Handlers quando a arquitetura do addon já depender deles; +- evite registrar o mesmo comportamento várias vezes em JIP; +- mantenha as condições, ações e transições públicas dos veículos quando uma implementação for refatorada. + +Consulte a referência oficial de [Event Handlers](https://community.bohemia.net/wiki/Arma_3%3A_Event_Handlers) e compare o comportamento com as macros CBA existentes em `braf_weapons_core`. + +## Modelos, LODs e Object Builder + +O BRAF usa modelos `.p3d`, materiais `.rvmat`, texturas `.paa` e animações `.rtm`. A geometria visual não substitui automaticamente as geometrias de colisão, visão, balística, física ou navegação. + +O [Object Builder](https://community.bohemia.net/wiki/Object_Builder) faz parte do Arma 3 Tools e é utilizado para editar modelos, configurar LODs, propriedades nomeadas, materiais e visualizar o resultado com Buldozer. + +### LODs principais + +| LOD | Função | Cuidados principais | +|---|---|---| +| Resolution | Geometria visível em diferentes distâncias | Use LODs realmente diferentes e remova detalhes pequenos progressivamente; cópias idênticas não trazem ganho | +| View Pilot | Visão de piloto ou motorista | Deve refletir o que o ocupante realmente vê | +| View Gunner | Visão do atirador | Verifique torre, óptica, arma e animações relacionadas | +| View Commander | Visão do comandante | Verifique posição, escotilhas e instrumentos | +| View Cargo | Visão de passageiros | Verifique proxies e visibilidade dos ocupantes | +| Geometry | Colisão geral e interação com objetos sem PhysX | Componentes fechados, convexos e simples; a massa e o centro de massa importam | +| Fire Geometry | Colisão com projéteis e foguetes | Use geometria simplificada, materiais de penetração e proxies necessários para ocupantes | +| View Geometry | Oclusão e linha de visão | Deve bloquear corretamente visão do jogador e percepção da IA | +| Geometry PhysX | Colisão e simulação física de veículos | Mantenha simples; massa e distribuição de massa afetam diretamente o comportamento | +| Geometry Buoyancy | Volume de deslocamento de objetos flutuantes | Componentes convexos, simples e não intersectados; requer teste em água | +| Roadway | Superfície onde unidades caminham ou ficam | Não sobreponha Geometry; use superfície compatível e divida objetos muito grandes | +| Memory | Pontos de controle | Inclui armas, faróis, fumaça, escapamento, luzes, eixos e pivôs | +| LandContact | Pontos de contato com o solo | Essencial para veículos e comportamento de contato | +| Hit-points | Pontos de partes destrutíveis | Deve corresponder aos hitpoints declarados na configuração | +| Paths | Navegação da IA em interiores | Use pontos e seleções adequados ao espaço navegável | +| Shadow Volume | Sombra dedicada | Mantenha fechado, triangulado e separado por complexidade adequada | +| Wreck | Modelo ou geometria após destruição | Deve corresponder à propriedade de dano e à configuração do objeto | + +A documentação oficial de [LOD](https://community.bohemia.net/wiki/LOD) descreve os tipos, limitações e fallback entre LODs. Os valores abaixo são orientações de trabalho, não substituem validação: + +- mantenha um único UV map quando a ferramenta e o asset exigirem isso; +- não trate `decimate = 0.5` como regra universal: preserve a silhueta e a função de cada LOD; +- use componentes `ComponentXX` fechados e convexos onde a engine exige geometria válida; +- a massa e a distribuição da massa são importantes para objetos PhysX; +- Fire Geometry precisa de material de dano/penetração apropriado; +- proxies de ocupantes devem existir nos LODs relevantes para evitar ocupantes invulneráveis ou invisíveis à IA; +- não presuma que Geometry, View Geometry e Fire Geometry podem compartilhar exatamente a mesma malha; +- valide o modelo no Object Builder/Buldozer e depois no jogo. + +### Named Properties + +Named Properties são configuradas no Object Builder e normalmente devem ser escritas em minúsculas; a documentação de [Arma 3 Named Properties](https://community.bohemia.net/wiki/Arma_3%3A_Named_Properties) explica o comportamento da ferramenta e do binarizador. + +Propriedades comuns incluem: + +- `lodnoshadow` para controlar sombra em LODs de resolução; +- `canocclude` e `canbeoccluded` para oclusão; +- `sbsource` para a fonte de sombra; +- `autocenter` e `reversed` quando o asset realmente precisa dessas propriedades; +- `aicovers` quando o objeto deve ser considerado cobertura pela IA; +- `buoyancy = 1` no Geometry LOD de objetos flutuantes. + +Não adicione propriedades apenas por copiar outro modelo. Uma propriedade como `autocenter`, especialmente em veículos aquáticos, pode alterar o comportamento físico. O resultado só é considerado validado após teste do modelo no jogo. + +### Geometry Buoyancy, Roadway e navios + +Para embarcações e veículos anfíbios: + +- o Geometry LOD deve conter a propriedade `buoyancy = 1` quando o objeto deve flutuar; +- o Geometry Buoyancy deve ser simples, convexo e sem interseções entre componentes; +- a massa do Geometry e a configuração do veículo devem ser coerentes; +- o PhysX Geometry e o Roadway devem ser testados separadamente; +- o Roadway não deve atravessar o Geometry de forma a causar tremores; +- navios longos podem precisar ser divididos em segmentos ou child P3Ds, cada um com geometria e roadway válidos; +- proxies visuais não substituem automaticamente a geometria física do objeto principal. + +Use as [Ships Config Guidelines](https://community.bohemia.net/wiki/Arma_3%3A_Ships_Config_Guidelines) junto com a inspeção dos P3Ds reais. Packing ou binarização não provam que flutuação, colisão, roadway ou ocupantes estão corretos. + +## Texturas, materiais, sons e caminhos + +Ao referenciar assets: + +- use caminhos coerentes com o prefixo real do addon; +- confirme a existência e a capitalização do caminho; +- confirme a relação entre `.paa`, `.rvmat`, seleções e `hiddenSelectionsTextures[]`; +- não substitua P3D, PAA, RVMAT, RTM ou sons por arquivos vazios; +- preserve licenças e atribuição de material de terceiros; +- mantenha nomes de arquivos sem acentos ou caracteres especiais quando a ferramenta de release ou o pipeline exigirem isso; +- valide caminhos relativos no checkout e no contexto em que o PBO será montado. + +Falha de textura, material, som ou animação é frequentemente um problema de caminho, case, prefixo do addon ou dependência, não apenas de configuração da classe. + +## Convenções de nomes e metadados + +Para conteúdo novo: + +- prefira nomes em inglês, minúsculos e em `snake_case` para arquivos e diretórios; +- use o prefixo `braf_` em nomes públicos quando a convenção do addon permitir; +- preserve classes públicas existentes, mesmo quando a capitalização histórica não seguir o padrão novo; +- use `braf_fnc_` ou a interface pública BRAF já estabelecida; +- não crie `braf_ship_weapons`; o nome correto do addon naval compartilhado é `braf_weapons_naval`; +- use exatamente `author = "BRAF_TEAM"` em metadados de mods e addons pertencentes ao BRAF; +- não altere atribuição de conteúdo externo dentro de `libs`. + +Nomes de classe e nomes de arquivo são contratos de compatibilidade. Renomear um recurso pode quebrar missões, scripts, dependências ou referências de modelo mesmo quando o novo nome parece mais correto. + +## Validação e fluxo de desenvolvimento + +### Antes de editar + +1. Confirme a raiz do repositório e leia `AGENTS.md` e a skill em `.agents`. +2. Identifique o addon proprietário do recurso. +3. Localize a declaração, a classe pai, os includes, os consumidores e os caminhos de asset. +4. Inspecione addons relacionados e `requiredAddons[]`. +5. Verifique se a mudança envolve localidade, JIP, CBA, ACE, P3D ou binário protegido. + +### Depois de editar + +1. Faça validação textual e estrutural não destrutiva. +2. Execute testes focados conhecidos como estáticos. +3. Use o validador local quando disponível: + + ```powershell + python .agents\skills\arma3-mod-development\scripts\run_validation.py P:\braf + ``` + +4. Revise o diff completo e execute `git diff --check`. +5. Confirme que nenhum asset protegido foi deletado, movido, renomeado ou sobrescrito. +6. Confirme que `libs` e `P:\a3` não foram modificados. +7. Separe evidência de fonte, Config Viewer, runtime, modelo, multiplayer e release. + +Validação estática pode encontrar includes ausentes, caminhos inválidos, classes duplicadas, referências de função inexistentes e inconsistências de `CfgPatches`. Ela não prova que o addon carregou, que uma aeronave voa, que um navio flutua, que um míssil funciona no pylon, que um LOD está correto ou que uma função funciona em multiplayer. + +### Teste mínimo recomendado + +Para uma mudança de configuração ou asset, teste de acordo com o risco: + +- Config Viewer: classe, herança, propriedades e dependências; +- Eden Editor: criação, preview, display picture e facção; +- Singleplayer: inicialização e ações básicas; +- Hosted Server: sincronização básica e localidade; +- Servidor dedicado: ausência de dependências acidentais de interface; +- JIP: inicialização tardia e persistência de estado; +- Headless Client: comportamento de IA quando aplicável; +- Object Builder/Buldozer: LODs, named selections, materiais, proxies e animações; +- água e colisão: Geometry, PhysX, Buoyancy, Roadway e Memory LODs separadamente; +- armas: relação weapon-magazine-ammo, muzzle, pylon, sons, modos e efeitos. + +## PBO e release + +Um PBO é o pacote que o Arma 3 carrega como addon. A criação do PBO, binarização, assinatura, obfuscação e publicação são operações de release e não substituem a inspeção da fonte. + +As regras operacionais deste repositório são: + +- não usar PBO como validação automática; +- não executar `pboProject`, Addon Builder, Binarize, MakePbo, HEMTT de build/release/dev, ferramentas de assinatura ou scripts de publicação nesta rotina de desenvolvimento; +- não afirmar que um addon foi empacotado, binarizado, assinado ou testado no jogo sem essa evidência real; +- quando um mantenedor autorizado realizar o release, registrar separadamente a ferramenta, o resultado, os logs e os testes executados. + +O diretório `make` contém ferramentas que podem incluir etapas de empacotamento ou Workshop. Inspecione-as apenas para entender o pipeline; não as execute automaticamente durante uma alteração de fonte. + +## Diagnóstico rápido + +### O addon não aparece + +Verifique a existência do `config.cpp`, a classe `CfgPatches`, o `requiredAddons[]`, `scope`, `units[]`, `weapons[]`, o caminho do PBO e a capitalização de todos os caminhos. + +### A função está indefinida + +Confirme a classe `CfgFunctions`, o caminho `file`, o nome gerado (`PREFIX_fnc_function`), a dependência do addon e se o arquivo `.sqf` existe no checkout. + +### O veículo existe, mas o armamento não funciona + +Trace a cadeia `CfgVehicles` → `CfgWeapons` → `CfgMagazines` → `CfgAmmo`. Verifique muzzle, magazine, pylon, hardpoint, parent class, `requiredAddons[]`, memória do modelo e modos de fogo. + +### O ocupante não recebe dano + +Inspecione Fire Geometry, materiais de penetração e proxies. Depois confirme a relação entre hitpoints, configuração do veículo e teste de impacto real. + +### O objeto colide, flutua ou permite caminhar de forma errada + +Separe o diagnóstico de Geometry, Geometry PhysX, Geometry Buoyancy, Roadway, LandContact, Memory e configuração. Um packing bem-sucedido não prova nenhum desses comportamentos. + +### A função funciona localmente, mas falha no multiplayer + +Revise máquina autoritativa, `local`, `isServer`, `hasInterface`, JIP, Event Handlers, `remoteExec`, `CfgRemoteExec`, argumentos e ownership migration. + +### A textura ou o material não aparece + +Confirme o caminho do asset, case, prefixo do addon, extensão, `hiddenSelections[]`, `hiddenSelectionsTextures[]`, `hiddenSelectionsMaterials[]` e dependências do RVMAT. + +## Referências oficiais de Arma 3 + +- [Creating an Addon](https://community.bohemia.net/wiki/Arma_3%3A_Creating_an_Addon) +- [CfgFunctions](https://community.bohemia.net/wiki/Arma_3_CfgFunctions) +- [Functions Library](https://community.bohemia.net/wiki/Arma_3%3A_Functions_Library) +- [Class Inheritance](https://community.bohemia.net/wiki/Class_Inheritance) +- [LOD](https://community.bohemia.net/wiki/LOD) +- [Arma 3 Named Properties](https://community.bohemia.net/wiki/Arma_3%3A_Named_Properties) +- [Ships Config Guidelines](https://community.bohemia.net/wiki/Arma_3%3A_Ships_Config_Guidelines) +- [Object Builder](https://community.bohemia.net/wiki/Object_Builder) +- [Event Handlers](https://community.bohemia.net/wiki/Arma_3%3A_Event_Handlers) +- [Multiplayer Scripting](https://community.bohemia.net/wiki/Multiplayer_Scripting) +- [Remote Execution](https://community.bohemia.net/wiki/Arma_3%3A_Remote_Execution) +- [CfgRemoteExec](https://community.bohemia.net/wiki/CfgRemoteExec) +- [Addon Builder](https://community.bohemia.net/wiki/Addon_Builder) — referência da ferramenta; não é executado pelo agente neste projeto +- [CBA_A3](https://github.com/CBATeam/CBA_A3) +- [ACE3](https://github.com/acemod/ACE3) + +## Projeto e contribuição + +Antes de abrir uma alteração, leia [AGENTS.md](AGENTS.md), a skill local em `.agents\skills\arma3-mod-development\SKILL.md`, as instruções do addon afetado e os arquivos relacionados. Mantenha alterações pequenas, preserve interfaces públicas e não misture mudanças de asset, configuração, documentação e release sem escopo explícito. + +Registre no [CHANGELOG.md](CHANGELOG.md) as alterações de comportamento relevantes quando o fluxo da tarefa exigir. Para alterações de código, informe o caminho, dependências, validação realizada, limitações e o teste de Arma 3 recomendado.