SDKs e revisões

SDK Câmera

Câmera de ombro, terceira pessoa e primeira pessoa para jogos em three.js. Não conhece nenhum jogo: recebe o alvo e uma função de colisão.

const rig = CameraModosSDK.criar(THREE, { chave: 'meu-jogo-camera', nomes: { ombro: 'ombro (Q troca)' } });
rig.seletor(document.querySelector('#menu'), 'Câmera');      // seletor pronto, opcional
// a cada quadro
rig.atualiza(camera, { x, y, z, yaw, pitch, mira, agachado }, dt,
  (ox, oy, oz, dx, dy, dz, max) => distanciaAteParede ?? null,  // colisão (opcional)
  (x, z, y) => alturaDoTeto);                                   // teto (opcional)
if (rig.primeiraPessoa()) { rig.viewmodel(grupoDaArma, camera); /* esconda o corpo do jogador */ }
rig.ciclar();  rig.trocaLado();  rig.setModo('terceira');  rig.aoMudar(m => ...);

Convenções: yaw 0 olha para -z; pitch positivo olha para baixo; a arma tem o cano em +z. Tudo que é número (distâncias, alturas, posição do viewmodel) se ajusta em criar(THREE, { ombro: {...}, terceira: {...}, primeira: {...}, viewmodel: {...} }).

No ZombiAdA o adaptador é implementacao/jogo-web/src/91-camera.js (tecla O, seletor no menu, esconde o corpo em primeira pessoa).

SDK Modo livre (ferramenta de teste)

Arquivo: modo-livre.js. Genérico, não conhece nenhum jogo. O build.py do jogo inclui tudo de sdk/*/*.js antes do src/.

const ML = ModoLivreSDK.criar(THREE, {
  chaveMarcas: 'meujogo-marcas', arquivo: 'marcas.txt', equipes: [['mapa','Mapa']],
  area: (x, z) => 'nome da área', hora: () => '12:00', msg: (texto, s) => {},
  pos: () => ({ x, y, z, yaw, pitch }), limites: { x: [-500, 500], y: [0.4, 260], z: [-500, 500] },
  pausa: aberto => {},          // true ao abrir painel (soltar mouse, pausar), false ao fechar
});
ML.chave('id', 'Rótulo', get, set)   // liga/desliga no painel (set devolve true para fechar o painel)
  .acao('id', 'Rótulo', fn)          // botão (fn devolve true para manter o painel aberto)
  .horasDoDia([['Manhã', 0.3]], setHora)
  .lugares(() => [['Grupo', [['Nome', ir]]]])
  .etiquetasDe(cam => [{ x, y, z, texto, cor }])
  .cenarios(lista, aplicar, checar);  // checar(c) -> { critério: { ok, nota } }
ML.irPara = (x, y, z, yaw, pitch) => {};
// a cada quadro: ML.voa(dt, yaw, pitch, { frente, lado, sobe, rapido }) e ML.cameraVoo(camera, yaw, pitch) quando ML.voo;
// ML.atualiza(dt, camera, visivel). Teclas ficam no jogo: ML.abre('form' | 'lista'), ML.fecha().
ML.expoe(); // window.__cenario, __cenCheck, __cenLista, __modoLivre para Playwright

Marcas: salvas no banco do artifact (db, coleção marcas) quando houver, senão no localStorage, com copiar e baixar. Exemplo de adaptador: implementacao/jogo-web/ferramentas/92-explorar.js (ZombiAdA).

PlantasSDK

SDK genérico, sem nada de jogo específico, para plantas de casas e lotes. As posições dos móveis são gravadas (slots) e os itens são sorteados nelas com semente, então nenhuma casa repete o mesmo padrão. JS puro, sem imports: plantas.js é um IIFE que define const PlantasSDK.

Coordenadas

• u corre ao longo da fachada (0..w); v vai da rua para os fundos (0..d). A sala fica na frente.
• Lote: v < 0 é o recuo frontal (jardim/garagem), v > d é o quintal, u < 0 e u > w são as laterais.
• Retângulos são [u0, v0, u1, v1]. Nos móveis, x == u e z == v (centro). Medidas em metros.
• A frente do móvel é o vetor (fu, fv). ry = atan2(fu, fv), igual ao olha(du, dv) do jogo com inw = 1. Se a rua do jogo estiver invertida, use ry = atan2(fu, inw * fv).

API

• PlantasSDK.gerar(template, {w, d, semente, estilo, andar}) devolve {comodos, paredes, portas, janelas, moveis, fachada, lote, andares, faltando}. Mesmo template, medidas e semente dão o mesmo resultado.
  • moveis[]: {id, tipo, categoria, x, z, ry, w, d, h, y, fu, fv, comodo, andar, externo, slot, sobre, modo, aabb, liga?}. y é a altura da base (itens sobre outro). externo marca itens do lote (andar -1). liga marca a escada entre andares.
  • paredes[]: segmentos com lados (cômodo de cada lado ou 'fora'), ext, tipo (parede ou guardacorpo), andar. As portas já abrem o vão; a verga é do jogo.
  • portas[]: {u, v, eixo, larg, a, b, abre, ext, modelo: folha|dupla|aco, folhas, zonas}.
  • janelas[]: {u, v, eixo, larg, y0, y1, comodo, lado}.
  • fachada: {cor:{nome,hex}, acabamento: reboco|chapisco, grades, telhado: colonial|fibrocimento|laje, sacada, portaAco}.
  • lote: {rect, zonas, perimetro, portoes, caminhos, piscina}. Cada perimetro[] tem tipo (muro|cerca|grade), material, altura, topo (nada|caco|concertina|grade) e alturaTotal: é o que as regras de escalada usam. portoes[]: {tipo: social|garagem|carga, modelo: pedestre|basculante|correr, u, v, larg, altura, para}. caminhos[]: faixas reservadas do portão até a porta (pedestre) ou até a vaga/garagem (veículo).
  • faltando: slots obrigatórios que não coube colocar (deve vir vazio).
• PlantasSDK.slots(template, {w, d}): as posições gravadas, para revisão. Cada slot tem x, z, w, d, aabb, fu, fv, ry, âncora, cats, obrigatorio, prob, folga, frente, grupo, requer, sobre, valido e motivo (quando inválido).
• PlantasSDK.validar(res) devolve erros em português. listarTemplates(), catalogo, biblioteca, estilos, templates.
• registrarTemplate(t), registrarItem(def), registrarBiblioteca(tipo, fnOuLista).

Estilo (estilo: 'popular' | 'nobre' | 'comercial')

Muda alturas e topos dos muros, tipos de portão, paleta e materiais da fachada. O padrão vem do template. Tudo fica em PlantasSDK.estilos (dados). Popular: muro de bloco 1,8 m, portão de ferro, grades nas janelas. Nobre: muro 2,8 m com concertina ou grade. Comercial: porta de aço, sem jardim, fundos de serviço.

Regras de colocação

Nenhum móvel invade 0,9 m em frente a portas e portões; itens altos (h > 1,0) ou com janela:false nunca ficam em frente a janelas; sem sobreposição; há caminho em grade da porta (ou portão) ao centro do cômodo; frente voltada para dentro; folga na frente do móvel; piscina com aro livre de 1,2 m. Os caminhos reservados entre portão e porta ficam livres. Um slot de parede pode deslizar até 2 m ao longo da parede para escapar de porta e janela. tapete é plano e não colide.

Como adicionar

• Item: PlantasSDK.registrarItem({tipo:'sofa4', categoria:'sofa', w:2.2, d:0.95, h:0.85, frente:'+z', janela:false, baixo:false}). O tipo é o que o jogo mapeia para a malha.
• Slot: em Biblioteca[tipoDoComodo] (ou registrarBiblioteca), com os construtores: P(id, lado, pos, [w,d], {categoria:peso}, opções) parede (lado: esq|dir|frente|fundo|qualquer), C(id, 'fundo-esq', ...) canto (aceita qualquer), Z(id, fx, fz, ...) centro (fração do cômodo, com dx, dz em metros), J(id, ...) sob janela, SB(id, paiSlot, ...) sobre outro item, DT(...) dentro. Opções: obrigatorio, prob, folga, frente (centro, porta, alvo + alvo:'slot', ou u+ u- v+ v-), grupo (alternativas: só uma é usada), requer. O cômodo pode ajustar por ajustes:{slot:{...}} (ou null para remover), sem:[ids], extras:[...], lib:'outraBiblioteca'.
• Template: registrarTemplate({id, nome, estilo, limites:{w:[a,b], d:[a,b]}, padrao:{w,d}, lote:(w,d)=>cfg|null, andares:[{nome, pe, abertos, comodos(w,d), portas(w,d), janelas(w,d)}]}). Cômodos: {id, tipo, nome, r:[u0,v0,u1,v1], partes:[...] (cômodo em L)}. Portas: {a, b:'fora'|id, lado, c, larg, abre, aco}; sem c, centraliza na parede comum. Janelas: {comodo, lado, c | n, larg, y0, y1}. lote devolve {rf, ml, mr, qf, vaga, garagem, social, carga, piscina, libs}.

Templates

casaA (4 cômodos), sobrado (2 andares, 13 cômodos), mercado (5), farmacia (5), apartamento (7, sem lote, andar opcional) e mansao (10, com piscina e jardim grande).

Como o jogo se pluga

1. Concatene plantas.js no módulo e chame const r = PlantasSDK.gerar('casaA', {w: b.w, d: b.d, semente: b.id}).
2. Converta (u, v) para o mundo: X = b.x + u, Z = front + inw * v. Para a frente use ry = Math.atan2(m.fu, inw * m.fv).
3. Mapeie m.tipo para a sua malha (um mapa tipo -> fábrica). Use m.w, m.d, m.h como pegada, m.y para itens sobre outros e m.categoria para o loot.
4. Monte paredes de r.paredes (altura do andar em r.andares[i].pe), vergas sobre r.portas, janelas de r.janelas, e o perímetro de r.lote.perimetro com altura/topo.
5. Para revisar as posições gravadas use PlantasSDK.slots(...) ou o visor-plantas.html.

Arquivos

plantas.js (SDK), teste.mjs (node teste.mjs), visor-plantas.html (visor offline; node montar-visor.mjs reembute o plantas.js), shots.mjs (capturas com Playwright).

Revisão final ZombiAdA: checklist de consistência e orçamento de desempenho

Rascunho de trabalho da revisão final (22/10/2026). O relatório consolidado sai como página quando os times terminarem. Fontes lidas: briefs de zumbis (Bestiário v12), veículos, mapa (fatia Jardim Aurora), personagens, guia de estilo do corpo, sobreviventes/destino, VFX, explosões, Arsenal (página).

PC alvo: GTX 1060 6 GB / RX 580, Ryzen 5 2600 (6 núcleos/12 threads), 16 GB RAM, 1080p médio. Host é jogador e servidor ao mesmo tempo.

1. Inconsistências encontradas (primeira passada)

Bloqueadoras (precisam de uma decisão única antes de codar)

Importantes

2. Orçamento por quadro (host, 60 FPS = 16,6 ms)

CPU (o host é servidor e cliente)

GPU (GTX 1060)

Geometria e chamadas

3. Orçamento de rede (por cliente, 30 Hz)

Upload do host com 8 jogadores ≈ 190 KB/s (1,6 Mbps), sem problema em LAN. Cosmético nunca vai pela rede (semente).

4. Relevância única (mapa vivo + hordas)

• Histerese de 10 m para zumbis e 20 m para NPCs, como nos briefs.
• Teto global de materializados (R0–R1): 2.000 zumbis. Com jogadores espalhados, o teto se divide pela área de cada um; a horda que passa do teto fica em R2 como grupo e vai sendo materializada pela borda.
• População do mundo em R3: dados por bloco (≈40 B por bloco, 250 mil blocos = 10 MB). A migração semanal de 1.000+ é um grupo R3 que só materializa perto de jogador.
• Mapa vivo (eventos, clima, animais) roda no mesmo relógio: eventos são dados em R3 e só viram entidades em R0–R1.

5. NPCs vivos e histórias

• Até 13 bases × 8 moradores = 104 NPCs, mais nascimentos (bebê é dado, não agente, até virar criança jogável fora do build).
• Tick diário de destino (pontos de virada, risco, luto, relações cruzadas, nascimentos) ≤2 ms no total, fatiado em quadros.
• LOD completo ≤20 NPCs ao mesmo tempo; o resto em simplificado (decisão a cada 2 s) ou abstrato.
• Fofoca e memória: 30 entradas × 104 NPCs, cabe em memória sem custo.

6. Próximos passos

1. Acompanhar os times que ainda trabalham (Zumbis, Mapa, Armas, Veículos, Personagens, Sobreviventes, Fluidos, Cena de teste) e revisar cada entrega no navegador.
2. Mandar as correções B1–B8 e I1–I12 às threads donas.
3. Relatório consolidado em página.
4. Marco 1: teste de estresse de 2.000 zumbis + bloco do mapa vivo medindo FPS (protótipo three.js agora; engine depois da decisão).

7. Situação em 22/10, 06h

• Relatório consolidado publicado como documento: ../jogo/revisao-final-fatia-jogavel.html
• Fatia jogável na versão 7: ../jogo/zombiada-jardim-aurora.html
• Mapa alinhou B1, B5, B7, I1, I2, I8, I9 e I11 (documento v8).
• Abertos: 9 mm (30 × 35), Corredor 5,5 × 6,0 em Personagens e a folga do aceite M1 (14 m declarados, ~11 m na conta: 6,96 × 6,46 m/s por 7,7 s).

Regras de documentação e prévias do ZombiAdA

Regra pedida pelo Anderson em 22/10/2026: pode publicar online, mas sempre existe uma cópia local atualizada na pasta do projeto.

A regra

1. Toda documentação, prévia, protótipo ou página publicada online (artifact do claude.ai, Claude Doc) tem uma cópia em docs/offline/, na pasta do time.
2. A cópia é atualizada no mesmo turno em que a versão online muda. Publicou uma versão nova, regrave a cópia local logo em seguida.
3. A cópia abre com dois cliques, sem internet, e não perde nada: 3D, animações, interações, sons e fontes.
   • three.js, addons (OrbitControls etc.), fontes e todo o código vão embutidos no próprio HTML. Nada de CDN, Google Fonts ou <script src> externo.
   • Páginas com <script type="module"> + importmap não carregam módulos externos em file://: o three.module.js vai embutido dentro do próprio módulo (o build_offline.py já faz isso).
   • Página com vários arquivos (ex.: Garagem) vira um HTML só.
   • Claude Docs são exportados para HTML.
4. Links entre páginas apontam para as cópias locais, em caminho relativo. O link para a versão online fica só no índice.
5. Toda página nova entra no índice docs/offline/index.html e no Portal das Equipes (portal/fonte/portal.html, entrada ["offline", "docs/offline/..."] em files, depois rodar python3 portal/fonte/build.py e republicar o portal).
6. Antes de dar por pronto: abrir a cópia com a rede bloqueada e conferir que não há erro no console nem requisição externa.

Onde fica cada coisa

Como regenerar

docs/offline/ferramentas/build_offline.py converte a página publicada numa cópia offline:

1. Baixe a versão publicada de cada página para ferramentas/raw/<nome>/index.html (o nome de cada pasta está na tabela PAGES do script).
2. Rode python3 ferramentas/build_offline.py docs/offline (precisa de internet só para buscar as fontes do Google uma vez; o three.js está em ferramentas/lib/).
3. Teste aberto sem rede.