Direção técnica

Regra separada da apresentação, nome em vez de coordenada, e nada entra sem portão.

O jogo 3D é um único projeto Godot 4.7.2 Standard, em GDScript e renderer Forward+, aberto na raiz do seu repositório e funcionando sem outro checkout. Modelos GLB e áudio WAV usam Git LFS; os parâmetros .import e .gd.uid versionados preservam a identidade dos recursos. As regras de jogo que vieram do 2D moram em scripts/compartilhado/ (inventário, fôlego, vida, talentos, fé, cartas, coleção, receitas, obras, venda, afinidade, salvamento), sem citar um único tipo 2D; os serviços do vale em scripts/autoload/; as telas em scripts/ui/.

A migração do 2D para o 3D, medida arquivo a arquivo em 29/09/2026, mostrou que quase tudo aproveita, porque o 2D sempre guardou regra em autoload e desenho em cena: dos 30 autoloads de lógica, 25 não citavam um tipo 2D. O que prende uma regra ao 2D quase nunca é o tipo, é a entrada (qual tecla aciona) — e isso se separa. A regra que manda em tudo: o 3D não é reescrito. Migrar quer dizer acrescentar, nunca refazer o que já está de pé.

10 princípios

O que não se negocia

Um projeto, uma engine, LFS para o que pesa

Godot 4.7.2 Standard, GDScript e Forward+ (com modo Compatibility para GPUs que não suportem o perfil); o project.godot da raiz registra os 40 autoloads e abre inicio.tscn. Não se migra de engine nem se atualiza a engine no meio da jam sem necessidade comprovada. GLB, FBX históricos e WAV em Git LFS; caches, builds, arquivos brutos e credenciais ficam fora do Git; o jogo não precisa de chaves para rodar.

Regra separada da apresentação

O que a ação faz atravessa; qual tecla aciona e que telas bloqueiam a tecla ficam no projeto de cada jogo. Foi assim que a tecla da mão saiu do Inventario e foi para o controle de entrada, e que as telas do 2D (CanvasLayer e Control) desenham por cima do 3D sem saber que ele é 3D. Texto de jogador nasce em dado (JSON), nunca em constante de GDScript, porque constante não traduz.

O 3D não é reescrito

Asset 3D nunca é trocado por arte 2D (sprite não substitui GLB; a arte do 2D só entra na interface, como ícone). Mecânica que já funciona no 3D continua dona do assunto dela: o relógio é o Dia, quem narra é o GuiaPedro, o HUD é o prototype_hud, o mapa é o mapa_jogo. Só nasce do zero o que o 3D não tem. Se a fatia apaga, refaz ou aposenta o que já roda, ela está errada e precisa ser recortada de outro jeito.

O nome é o contrato; a âncora é a implementação

O autoload Lugares traduz nome de lugar em posição — Vector2 no 2D, Vector3 no 3D — e quem chama não vê a diferença. Nome que o vale ainda não tem devolve NENHUM e nada quebra: a missão abre sem bússola, o sistema roda com o lugar ausente, e no dia em que a região crescer o nome passa a resolver sem tocar em missão nenhuma. Anotação de tipo é acoplamento tão real quanto chamada de função, e não aparece em busca por nome.

Nada entra sem portão

Cada fatia acrescenta ou ajusta um teste de comportamento em tests/ e mostra que ele detecta o defeito (falsificação). O runner tools/prototipo_3d/testar.ps1 roda a bateria com perfil isolado por portão, teto de tempo e conferência de erros de compilação: erro de compilação e travamento reprovam, e código de saída zero sozinho não demonstra que o jogo abriu. Só os PIDs levantados pelo runner podem ser encerrados. Em 02/10/2026 a bateria tinha 51 portões passando.

Dívida declarada, não dívida esquecida

O que falta mora em listas com a razão escrita: FALTAM_NO_VALE no Lugares (a lagoa), FALTAM_TRADUCAO no portão de idiomas, a fila do telhado no 2D, as peças Tripo ainda não exportadas no catálogo. O portão lê essas listas para cobrar que ninguém esteja escrito errado, e o sistema continua rodando com a peça ausente — a mesma escolha do catálogo de assets.

Desempenho medido no computador de referência, não estimado

GeForce GTX 1660 Ti (Max-Q) é a referência. Medições que mudaram decisões: texturas sem compressão a 2,49 GB de VRAM → 0,74 GB com VRAM Compressed; a mata em uma MultiMesh por espécie que nunca saía do quadro → blocos de 40 unidades com LOD por distância (17,33 M → 5,65 M de triângulos na vista de longe); a montagem do vale de ~29 s para ~5 s trocando a medida de cada ponto contra todos os segmentos por grades de células, com resultado idêntico bit a bit.

Dados em res://, save em user://, uma fonte para a versão

Os dados são lidos de res://data/ e o save usa user:// no diretório próprio MythsValleyPrototype3D, separado do 2D. O formato do save é variante do Godot (guarda Vector3 com naturalidade), com escrita atômica e migração em escada; campo público novo entra em O_QUE_GUARDAR ou em FORA_DO_SAVE com a razão escrita, e o portão cobra os dois. A versão e o build são declarados uma vez, em data/historico_3d.json, e tanto o rodapé do menu quanto o carimbo do save leem de lá.

Segredos fora do repositório; geração só com pedido

Credenciais ficam em arquivos locais lidos por tools/comum/chaves.ps1 e no perfil local do Tripo; nenhuma chave entra no repositório, no executável nem na build. Geração de arte e áudio consome crédito e só acontece com pedido explícito, com cada asset mantendo origem e créditos. Para a conversa por LLM prevista, a chave do provedor fica como secret num serviço, nunca no cliente, e um segredo escondido no jogo não é autenticação.

Três reservas e uma interação em foco

Vigor sustenta esforço, corrida e salto; fôlego sustenta o nado; vida recebe o dano. O E atua sobre um alvo de cada vez, à frente do corpo; conversas e avisos pausam o relógio. A Build 9 reduziu a carga, a sombra, a mata e o trabalho de física, e o minimapa passou a usar uma foto estática.

9 regras

Na prática, no dia a dia

Antes de implementar, ler a issue e o portão do assunto e conferir o código atual: issues antigas podem descrever como ausente algo que já foi incorporado.
Cada fatia: implementar, acrescentar ou ajustar a verificação de comportamento, mostrar que ela detecta o defeito, rodar a bateria com perfil isolado, registrar no CHANGELOG_3D e citar a issue no corpo do commit. Trabalho novo em feature/<nome> e PR para main.
Bateria: .\tools\prototipo_3d\testar.ps1 (ou -Teste salvamento). A bateria roda headless; capturas e testes que dependem de mouse (smoke_opening, mapa_fluxo, smoke_test) usam o renderer normal.
git lfs pull antes da primeira importação: o pré-voo reprova modelos ou WAVs que ainda sejam ponteiros LFS.
Exportação Windows por export_presets.cfg para build/windows/ (criar a pasta antes), com os templates da mesma versão do Godot.
Teclas em código, não no Input Map: teclas_movimento.gd (WASD, setas ou ambos) e atalhos.gd (letras remapeáveis com swap; W, A, S e D reservadas), salvas em user://controles.cfg.
Regra compartilhada é cópia conferida byte a byte por portão; a lista de arquivos bifurcados (catalogo, inventario, equipamento, mochila, em 01/10/2026) espera decisão do autor antes de qualquer sincronização.
Posições e decisões visuais não ficam em Vector3 dentro do world_builder: o gerador lê a composição salva.
Depuração: JOGAR_3D.cmd -Lugar igreja começa num lugar do vale; -Compatibility troca o renderer; -Godot CAMINHO.exe aponta outro executável.

Onde isso aparece

O tamanho do código
Scripts de jogo, testes e ferramentas vivem em pastas próprias. As contagens de arquivos e linhas, autoloads, cenas, shaders e dados JSON são medidas no snapshot Git registrado nas estatísticas; a página do projeto mostra os números atuais de código, testes e dados.
O Salvamento que atravessou sem adaptação
Parecia o mais emaranhado e atravessou sem uma linha mudada, porque usa get_node_or_null em toda parte e degrada sozinho onde um sistema não existe; só o Versao precisou nascer local, lendo do historico_3d.json.
CadernoDoVale e CadeiaDeMissoes
O mecanismo próprio de missão do vale: uma linha de andamento por missão e cadeias ligadas aos moradores, lendo seus arquivos de dados. As metas incluem material, entrega, conversa, evento, contagem, obra, visita e oferenda; os portões verificam a cadeia e os recursos necessários para cumpri-la.
O portão do minimapa
O alvo da missão apontava para quem tinha acabado de falar, não para o que o jogador fixou no painel — e durou porque o minimapa nunca tinha tido portão. Tem agora, com sete perguntas.
O sobrevoo do menu
Planejado offline contra os triângulos reais do vale, gravado em data/sobrevoo_menu.json e conferido quadro a quadro por tests/sobrevoo_livre.gd; se as âncoras ou a escala mudarem, o menu avisa e volta à elipse antiga.

De onde vem

Os documentos desta área

As orientações acima resumem estes documentos de direção do jogo.

Arquitetura — cenas, autoloads e catálogos do jogo
Visão do jogo — o que o jogo é e o que ele reúne
Validação — como o projeto é conferido depois de importado
Plano do 3D — o rumo do jogo e as próximas etapas
Apresentação do jogo — o resumo do Myths' Valley 3D
Histórico do desenvolvimento — as etapas antes do repositório próprio
Decisões do protótipo 3D — o que foi decidido e quando
O vale vivo — dia e noite, moradores e som do vale
Changelog do 3D — o que mudou em cada build
Lugares — o nome de cada lugar e onde ele fica
Versão do jogo — o número que carimba cada build
Atalhos de teclado — as teclas que o jogador pode trocar

Outras áreas

Direção visual Arte 3D e o fluxo com o Tripo Direção de mundo Direção sonora Direção histórica e narrativa Decisões de projeto

Próxima: Decisões de projeto