projectbraf/braf
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
07e7f053adad812aa2b7d1b4f8228248935a88e7
braf/README.md
T
rarantes 07e7f053ad
Deploy DEV Workshop / deploy-dev-workshop (push) Successful in 50s
Details
docs(repo): expand Arma 3 development guide
2026-08-02 17:48:30 -03:00

24 KiB
Raw Blame History

Brazilian Armed Forces (BRAF) Mod

BRAF Mod

Repositório de desenvolvimento do Brazilian Armed Forces (BRAF) Mod, uma modificação para Arma 3 inspirada nas Forças Armadas Brasileiras.

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.

Dependências e compatibilidade

CBA

O BRAF requer o Community Base Addons (CBA) como dependência de projeto. O código existente usa padrões e APIs do CBA, incluindo:

  • macros comuns e script_xeh.hpp;
  • CBA_fnc_compileFunction;
  • CBA Extended Event Handlers;
  • CBA_weaponEvents;
  • eventos e sistemas de armas compartilhados.

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.

ACE

O 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.

Ao adicionar compatibilidade ACE:

  • 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.

Organização do repositório

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.

Á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

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.

Estrutura de um addon

Um addon BRAF normalmente possui um config.cpp na raiz e pode incluir arquivos de configuração, funções, modelos e assets:

braf_example/
├── config.cpp
├── *.hpp
├── functions/
│   └── fn_example.sqf
├── data/
│   ├── *.paa
│   └── *.rvmat
├── model.cfg
└── *.p3d

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.

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.

CfgPatches

Todo addon deve possuir uma classe CfgPatches coerente com o conteúdo que fornece. Ela informa, entre outras coisas:

  • nome da classe de patch;
  • requiredVersion;
  • requiredAddons[];
  • units[];
  • weapons[];
  • metadados como autor e URL.

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.

Exemplo de padrão para conteúdo novo BRAF:

class CfgPatches
{
    class braf_example
    {
        author = "BRAF_TEAM";
        requiredVersion = 0.1;
        requiredAddons[] = {"A3_Weapons_F", "braf_main"};
        units[] = {};
        weapons[] = {};
    };
};

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.

Herança de classes

Arma 3 usa herança de configuração. Antes de derivar uma classe, confirme:

  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.

Use o Config Viewer, os arquivos locais de referência e a documentação oficial de Class Inheritance. Não copie uma classe pai apenas por semelhança textual.

Cadeia de conteúdo de armas

Ao alterar armamentos, verifique toda a cadeia:

CfgWeapons
    └── magazines[] / pylonWeapon
            └── CfgMagazines
                    └── ammo
                            └── CfgAmmo

Também confira muzzles, modos de fogo, sons, efeitos, hardpoints, pylon stores, velocidades, alcance, hit, indirectHit, penetração, rastreadores e compatibilidade com plataformas existentes.

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.

Funções SQF e CfgFunctions

Funções públicas devem ser registradas em CfgFunctions e ter um arquivo real no caminho declarado. No BRAF existem exemplos como:

  • 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.

Ao criar ou alterar uma função:

  • 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.

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.

Multiplayer, localidade e JIP

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.

Antes de implementar código de rede, identifique:

  • 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.

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, os controles de CfgRemoteExec e os efeitos de localidade em 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 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 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 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 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 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:

    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

Projeto e contribuição

Antes de abrir uma alteração, leia 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 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.

Reference in New Issue View Git Blame Copy Permalink