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

40 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 de asa rotativa braf_air, braf_sar, braf_optics_air Helicópteros, variantes de transporte, armadas e SAR, EFS, guincho e sistemas associados
Aviação de asa fixa braf_air2 Aeronaves de asa fixa, incluindo A-29, Gripen e seus armamentos, magazines e sistemas de cabine
Blindados sobre lagartas source\braf_tracked Fonte do addon braf_tracked, incluindo M113, M41 e armamentos, munições e ópticas de veículos rastreados
Blindados sobre rodas braf_armored Viaturas blindadas sobre rodas e suas variantes, configurações, armamentos e integrações
Embarcações pequenas e médias braf_boat Barcos e embarcações de pequeno e médio porte, com comprimento de até 15 m segundo a divisão interna do BRAF
Navios e submarinos braf_ships Navios de maior porte e submarinos; o addon compartilhado de armas navais é braf_weapons_naval
Veículos, estruturas e armas estáticas braf_soft, braf_static, braf_structures, braf_structures_land, braf_structures_ammoboxes Veículos não blindados, armas estáticas, estruturas, superfícies 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 e outros projetos. Com exceção do CBA, nenhum material presente em libs deve ser tratado por presunção como dependência obrigatória, compatibilidade opcional, referência técnica, biblioteca reutilizável com licença compatível ou material desconhecido. Essa classificação só deve ser feita no contexto de uma reutilização planejada, depois de verificar origem, licença, versão, finalidade, dependências e compatibilidade com o BRAF. Até essa análise, o material é apenas referência protegida e não pode ser copiado para produçã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. Um modelo não é apenas a malha visível: os LODs determinam renderização, visão, colisão, penetração, PhysX, flutuação, navegação, sombras e pontos de integração com a configuração. Uma malha que parece correta pode continuar sem colisão, deixar a IA enxergar através dela, tornar a tripulação invulnerável ou falhar na água.

O Object Builder é parte do Arma 3 Tools, sucessor do Oxygen 2, e cria, edita e grava P3D não binarizado (MLOD). Ele não é uma ferramenta para editar um P3D binarizado de release. No BRAF, modelos, texturas, materiais e animações existentes continuam protegidos: esta documentação explica o fluxo, mas não autoriza substituir, recriar ou sobrescrever um binário sem escopo explícito.

Contrato entre P3D, model.cfg e config.cpp

Camada Define Deve coincidir com
.p3d LODs, seleções nomeadas, eixos, proxies, materiais, pontos do Memory LOD e geometria nomes usados por model.cfg, hiddenSelections[], memoryPoint*, torres, hitpoints e efeitos
model.cfg CfgSkeletons, CfgModels, seções, ossos e animações do modelo nome do P3D sem extensão, seleções, eixos e controladores reais
config.cpp / .hpp model =, classe de veículo, AnimationSources, hiddenSelections[], posições de entrada, turrets, hitpoints, efeitos e User Actions caminhos, seleção, ponto de memória e fonte de animação existentes no modelo
.rvmat / .paa material e aparência visual; material de dano no Fire Geometry faces e seleções do LOD correto, além de caminhos com capitalização real

CfgModels é a interface entre o P3D e a engine: a classe deve usar o nome do arquivo do modelo sem .p3d, declarar suas sections[], associar o skeletonName e conter as Animations. CfgSkeletons descreve cada osso e sua relação pai/filho. Já AnimationSources pertence à classe do objeto em config.cpp: ela fornece controladores nativos ou fontes user para as animações declaradas no model.cfg. A referência oficial de Model Config detalha essa separação entre trabalho de arte e configuração.

O repositório aplica esse contrato em várias famílias — braf_air, braf_air2, braf_armored, braf_boat, braf_ships e source\braf_tracked têm model.cfg. Um exemplo pequeno e útil é braf_boat\BRAF_VLPV: o model.cfg define esqueleto, propeller, rudder, drivewheel e hatch; VLPV_base.hpp declara a fonte openhatch, as seleções de textura e os pontos de água, motor, carga e entrada. Use-o para entender o vínculo entre os arquivos, não para copiar nomes ou propriedades para outro veículo.

Fluxo seguro no Object Builder

  1. Confirme que abriu a fonte MLOD correta e identifique o addon proprietário, o model.cfg, a classe de veículo e todos os consumidores antes de alterar qualquer seleção.
  2. Trabalhe por LOD. Não use a Resolution LOD como substituta automática para Geometry, Fire Geometry, View Geometry, PhysX, Buoyancy ou Roadway.
  3. Crie e mantenha seleções nomeadas para partes móveis, retexturáveis, hitpoints, proxies e eixos. Trate o nome como contrato: preserve grafia e capitalização já usadas pelo modelo e pela configuração.
  4. Em LODs físicos, valide topologia antes de adicionar proxies: Structure > Topology > Find Non-Closed, Close, Structure > Convexities > Find Non-Convexities e Component Convex Hull; depois use Structure > Check Faces para localizar faces ou texturas inválidas. A referência de Validating Geometries descreve essas verificações.
  5. Revise massa e distribuição de massa no Geometry LOD; em objetos PhysX elas afetam inércia, contato e estabilidade.
  6. Use Buldozer como prévia visual de LODs, materiais, proxies e animações. Ele é configurado pelo Arma 3 Tools/P drive; a documentação oficial registra que iniciar o Object Builder diretamente pela Steam pode impedir a conexão com Buldozer.
  7. Teste no jogo cada comportamento físico e de gameplay. Um P3D abrir no Object Builder ou renderizar no Buldozer não prova colisão, dano, PhysX, flutuação, Roadway, IA ou multiplayer.

O Object Builder aceita P3D MLOD e outros formatos de importação, mas sua saída é P3D não binarizado. Não use isso como atalho para editar um asset de runtime, nem use packing ou binarização como teste de comportamento neste projeto.

LODs de visualização e interior

O valor numérico de uma Resolution LOD não escolhe uma distância fixa no Arma 3. A engine seleciona LODs conforme distância, qualidade gráfica, carga e outras condições. Portanto, forneça níveis com complexidade realmente decrescente; cópias idênticas aumentam tamanho, memória e carregamento sem ganho. Proxies precisam existir em cada Resolution LOD onde devam aparecer, e uma seleção vazia usada por animação ou pela engine pode causar falha quando o LOD se torna ativo. Consulte LOD para o comportamento de seleção.

LOD Responsabilidade Verificação obrigatória
Resolution Modelo externo visível; a Resolution LOD de maior detalhe deve preservar silhueta, materiais, seleções e proxies necessários detalhe cai progressivamente, não há cópias idênticas, UV/material e proxies permanecem válidos
View Pilot Interior visto por piloto/motorista painel, visibilidade, mãos/controles, portas e partes ocultas não invadem a câmera
View Gunner Interior e partes vistas pelo atirador torre, arma, óptica, miras e eixos acompanham a posição do gunner
View Commander Interior da posição do comandante escotilhas, ópticas e instrumentos respeitam a câmera e a animação
View Cargo Interior visto por passageiros proxies de carga, posições, abertura de portas e visibilidade por assento
View Pilot/Gunner/Commander/Cargo Geometry e Fire Geometry Geometria específica das posições internas quando a proteção, oclusão ou dano diferir por ocupante teste primeiro pessoa, dano recebido e linha de visão em cada assento afetado
Shadow Volume / Shadow Buffer Sombra dedicada nas resoluções próprias não duplique LODs de mesma resolução, mantenha a forma simples e revise artefatos em luz forte
Wreck representação após destruição, quando a classe/configuração a usar modelo, material, hitpoints e transição de dano correspondem ao comportamento configurado

LodNoShadow = 1 é a propriedade documentada para Resolution LODs. Para transparências que recebam sombras ambientais de modo incorreto, a BIKI indica Forcenotalpha = 1 no Geometry LOD — nunca como correção automática para qualquer material alfa. Use a grafia da propriedade documentada ou já empregada pelo asset; não normalize propriedades por estética.

LODs físicos, dano e visibilidade

LOD Responsabilidade Regras práticas e riscos
Geometry Colisão quando pelo menos um objeto não é PhysX; por exemplo, contato soldado-veículo use ComponentXX consecutivos, componentes fechados e convexos, massa válida e espessura física suficiente; a engine usa massa e distribuição para inércia
Geometry PhysX Malha de simulação física do veículo mantenha muito simples, triangulada e coerente com o centro de massa; não a trate como cópia de alta fidelidade do visual
Geometry Buoyancy Volume de deslocamento para embarcações e anfíbios poucos componentes convexos, fechados, triangulados e sem interseções; volume e posição alteram a flutuação
Fire Geometry Impacto de balas, foguetes e penetração componentes fechados/convexos, material de dano/penetração aplicado, complexidade baixa; se ausente, a engine recorre a View Geometry e depois Geometry
View Geometry Oclusão visual e linha de visão da IA deve representar volumes que realmente bloqueiam visão; se ausente, Geometry é usada como fallback
Hit-points vértices nomeados não conectados que localizam partes destruíveis nomes, posição e espaçamento devem corresponder a HitPoints da classe e ao Fire Geometry
LandContact vértices únicos de contato com solo cada ponto precisa apoiar o veículo conforme sua simulação; não confunda com flutuação naval

Para Geometry e Fire Geometry, a validação de convexidade não é opcional. O Object Builder pode gerar ComponentXX por Structure > Topology > Find Components; valide antes de inserir proxies. A BIKI também recomenda manter o Geometry LOD dentro do limite de tamanho: a referência histórica aponta instabilidade em torno de 50–60 m a partir da origem para a geometria, com variação por contexto. Não use esse número como limite garantido; trate-o como gatilho para testar e, quando necessário, dividir a composição.

Fire Geometry requer atenção adicional:

  • inclua proxies de motorista e passageiros nesse LOD quando a tripulação deve receber dano; sem eles, ocupantes podem se tornar invulneráveis;
  • aplique material físico de dano/penetração, não apenas o .rvmat visual;
  • mantenha faces e componentes simples; a referência BIKI cita menos de 3.500 pontos como orientação;
  • evite placas de Fire Geometry quase sobrepostas: o passo de simulação do projétil pode ignorar a segunda camada.

View Geometry não é decoração. Ela impede jogador e IA de enxergarem através do objeto. canocclude e canbeoccluded são propriedades de Geometry/View Geometry para casos específicos de oclusão; use-as somente quando a forma de oclusão não representar a forma visível, como vegetação perfurada. A página de Named Properties deve prevalecer sobre valores copiados de outro modelo.

Memory, Roadway, Paths e proxies

LOD/elemento Uso Contrato de integração
Memory pontos de arma, escapamento, fumaça, luz, efeito de água, entrada/saída, carga, câmera, PIP, eixo e ação o texto em memoryPoint*, memoryPoints*, posição de User Action, torre ou efeito deve ser o nome da seleção do Memory LOD
Eixo no Memory dois vértices com uma seleção nomeada formam eixo de rotação/translação axis = de model.cfg deve apontar para essa seleção quando memory = 1; com memory = 0, o eixo pertence ao LOD do modelo
Roadway superfície onde unidades ficam em pé e caminham não pode sobrepor Geometry, ou o personagem oscila; é necessário abaixo de pontos de escada; textura da superfície também influencia o efeito sonoro de passos
Paths rede de navegação de IA em interiores/estruturas malha conectada, posXX para paradas e inXX para entradas; deixe folga de paredes e mantenha os caminhos cerca de 10 cm acima da superfície caminhável
Proxy referência a outro P3D, ocupante, arma ou acessório inclua-o nos LODs visuais em que deve aparecer e nos LODs físicos que realmente exigem sua presença; proxy visual não garante colisão, Roadway, dano ou PhysX

O Roadway torna uma superfície caminhável para unidades. Não deixe Roadway e Geometry ocuparem o mesmo volume; isso causa oscilação. A BIKI relata instabilidade para componentes do Roadway a aproximadamente 36 m da origem, variando com mapa/célula, e limite menor quando o Roadway contém elementos animados. Para plataformas, pontes e navios extensos, teste cada segmento e prefira uma composição de P3Ds menores quando a superfície exceder esse comportamento estável.

Memory LOD é também a origem de muitas falhas aparentemente "de configuração". No BRAF, a classe de VLPV, por exemplo, aponta para pontos de efeito de água e motor, carga sling e entrada de piloto/carga. Um nome ausente ou em outra grafia resulta em efeito, entrada ou interação ausente. Partículas e certos pontos de arma podem ignorar deslocamento animado e usar a posição padrão do Memory LOD; confirme no jogo, não apenas no Buldozer.

model.cfg, esqueleto e animações

Elemento Papel
CfgSkeletons declara ossos e hierarquia pai/filho em skeletonBones[]; o filho acompanha a transformação do pai
CfgModels associa o modelo ao skeletonName, declara sections[]/sectionsInherit e contém class Animations
selection parte móvel ou osso/seleção existente no P3D
axis, begin e end eixo local ou pontos que definem direção da animação; normalmente um eixo de dois pontos no Memory LOD
source controlador nativo ou fonte declarada em AnimationSources no config.cpp
memory informa se o eixo está no Memory LOD; o padrão documentado é verdadeiro
minValue, maxValue, angle0, angle1 mapeiam entrada do controlador para fase, rotação ou deslocamento
sourceAddress define como entrada fora do intervalo é tratada, como loop, clamp ou espelhamento

Os tipos usuais são rotation, rotationX/Y/Z, translation, translationX/Y/Z, hide e direct. Para uma porta, torre, leme, hélice ou trem de pouso, confirme na sequência: seleção existe no LOD visível; a seleção física acompanha a animação quando necessário; eixo está no lugar e orientação corretos; model.cfg aponta para ambos; a fonte existe em AnimationSources ou é um controlador nativo; a ação, script ou sistema do veículo altera a mesma fonte.

Se uma animação muda colisão ou proteção, copie a seleção para os LODs físicos atingidos, especialmente Geometry e Fire Geometry. Para animações de personagem, não trate model.cfg como substituto de .rtm, CfgMoves e CfgGestures: a referência de Animations – Arma 3 separa animações simples de modelo das animações de estado de personagens.

Propriedades nomeadas

Named Properties pertencem ao LOD, não à classe de veículo. Adicione somente uma propriedade com comportamento conhecido e aplicável ao tipo de asset.

Propriedade LOD usual Uso correto
LodNoShadow = 1 Resolution controla contribuição de sombra da Resolution LOD; não pertence a Shadow Volume
Forcenotalpha = 1 Geometry correção específica para artefato de sombra ambiente através de material alfa
canocclude / canbeoccluded Geometry e View Geometry ajusta participação na oclusão; útil apenas para formas cuja oclusão não representa o objeto visível
buoyancy = 1 Geometry, não Geometry Buoyancy habilita o uso de Geometry Buoyancy para barcos e anfíbios
autocenter Geometry, quando o tipo de modelo exigir altera referência/origem física; nunca defina 0 ou 1 por cópia, nem use como solução genérica de flutuação
aicovers, sbsource, reversed e outras somente no LOD e caso documentados para o asset mantenha a semântica existente e confirme na BIKI/vanilla antes de introduzir

Não existe conjunto universal de properties para todos os modelos. Em especial, propriedades de origem e massa podem ter efeitos opostos entre acessórios, veículos terrestres, aeronaves, barcos e estruturas. Uma alteração de autocenter, buoyancy, material físico ou componentes de Geometry exige inspeção do P3D real e teste no jogo.

Embarcações, anfíbios e navios

Para braf_boat, braf_ships e qualquer veículo anfíbio:

  • coloque buoyancy = 1 no Geometry LOD, não no Geometry Buoyancy;
  • modele Geometry Buoyancy com poucas faces, componentes convexos e fechados, triangulação válida e sem volumes internos, interseções ou contatos desnecessários entre componentes submersos;
  • faça a forma e o volume do LOD de buoyancy se aproximarem do casco que desloca água; massa e centro de massa do Geometry precisam ser coerentes com esse deslocamento;
  • mantenha Geometry PhysX separado da geometria visual e teste massa, estabilidade, contato, inclinação e dano em água;
  • mantenha efeitos de motor abaixo da linha d'água quando a configuração do veículo assim exigir; pontos de água, propulsão e esteira também são Memory points que precisam coincidir com a configuração;
  • não use LandContact como evidência de que o navio flutua: o comportamento na água depende de Geometry, PhysX e Buoyancy;
  • trate cada seção de uma embarcação modular como unidade física própria. Proxies podem resolver a aparência, mas não substituem Geometry, Fire Geometry, View Geometry ou Roadway válidos em cada área onde esses comportamentos são necessários.

A documentação de Ships Config Guidelines alerta que navios grandes pressionam limites de tamanho, vértices, luzes, PhysX e Roadway. Como orientação, uma embarcação acima de aproximadamente 100 m pode exigir divisão em P3Ds/componentes menores. Isso não é uma licença para fragmentar qualquer modelo: primeiro defina a responsabilidade de cada seção, suas origens, LODs físicos e critérios de teste. Nunca conclua que uma composição funciona apenas porque o visual aparece.

Diagnóstico por sintoma

Sintoma Camada a investigar primeiro
modelo aparece, mas pessoa atravessa ou colide de forma errada Geometry, componentes convexos, massa, Geometry PhysX e tamanho/origem
bala atravessa blindagem ou ocupante não recebe dano Fire Geometry, material de penetração, proxies de ocupante, Hit-points e configuração de dano
jogador ou IA enxerga através do objeto View Geometry, canocclude/canbeoccluded e LOD de visão da posição afetada
personagem cai, vibra ou não caminha no convés Roadway, sobreposição com Geometry, distância da origem, escadas e Paths
porta, torre, leme ou hélice não anima corretamente seleção, eixo, memory, CfgSkeletons, CfgModels, AnimationSources e fonte usada pela classe
luz, fumaça, entrada, arma ou efeito de água está ausente seleção no Memory LOD e string exata da propriedade memoryPoint*/memoryPoints*
barco afunda, inclina ou muda comportamento após dano buoyancy = 1, Geometry Buoyancy, massa/distribuição, Geometry PhysX, volumes intersectados e configuração naval
textura variante não troca seleção no P3D, sections[] do model.cfg, hiddenSelections[], material e caminho real do asset

Validação mínima antes de considerar um modelo pronto

  1. Mapa de contratos: confirme caminho do P3D, classe CfgModels, skeletonName, seções, seleções, eixos, proxies, AnimationSources, memoryPoint*, hitpoints e materiais.
  2. Object Builder: revise LOD por LOD, named properties, massa, componentes, faces e topologia. Valide Geometry e Fire Geometry antes de inserir proxies.
  3. Buldozer: percorra Resolution, todas as câmeras internas, sombras, materiais, proxies e cada fase de animação.
  4. Jogo: teste colisão soldado/veículo, impacto e dano da tripulação, linha de visão da IA, assentos, torres, portas, efeitos, hitpoints, Roadway, Paths e, quando aplicável, PhysX, água e flutuação.
  5. Relato honesto: diferencie checagem textual, validação estrutural no Object Builder, prévia no Buldozer e evidência no jogo. Binarização, packing ou geração de PBO não provam nenhum desses comportamentos — e não são executados como validação neste repositório.

Referências oficiais: Object Builder, LOD, LOD resolutions, Model Config, Animations – Arma 3, Named Properties – Arma 3, Validating Geometries e Ships Config Guidelines.

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