primocode 11.3.3 → 11.5.0

package/kits/3d/LICENSES/README.md

@@ -0,0 +1,11 @@
+# Licenças das peças 3D (kits/3d)
+
+Todas as peças desta biblioteca são **código nosso** (Three.js, formas procedurais): personagem,
+animações, cenário e máquinas. Não há modelo, textura nem imagem de terceiros.
+
+Pacotes CC0 (Kenney, Quaternius) **ainda não foram usados**. Se um entrar, o arquivo de licença dele
+fica nesta pasta, com o link de origem, antes do commit.
+
+O pack do vídeo de referência (de outra pessoa) **não entra**.
+
+Dependência de código: three (MIT), em `LICENSES/three-MIT.txt` na raiz do repo.

package/kits/3d/animacoes.js

@@ -0,0 +1,87 @@
+/* animacoes.js — as animações universais do boneco. Cada uma é (p, t, op) e só
+ * escreve rotações: nada guarda estado. Serve em qualquer personagem.
+ *   parado · andar · correr · apontar · pensar · comemorar · surpreso · falar */
+import { clamp } from './base.js';
+
+const S = Math.sin;
+export const piscar = (t) => { const c = t % 3.1; return c < 0.12 ? 0.1 : 1; };
+
+function respirar(p, t) {
+    p.torso.rotation.x = S(t * 2) * 0.015; p.torso.position.y = S(t * 2) * 0.006;
+    p.cabeca.rotation.y = S(t * 0.7) * 0.08;
+}
+
+function ciclo(p, t, vel, amp, bracoAmp, inclina) {
+    const f = t * vel;
+    p.bracoE.coxa.rotation.x = S(f) * amp;           p.bracoD.coxa.rotation.x = -S(f) * amp;
+    p.bracoE.joelho.rotation.x = Math.max(0, -S(f)) * amp * 1.2; p.bracoD.joelho.rotation.x = Math.max(0, S(f)) * amp * 1.2;
+    p.bracoE.ombro.rotation.x = -S(f) * bracoAmp;    p.bracoD.ombro.rotation.x = S(f) * bracoAmp;
+    p.bracoE.cot.rotation.x = -0.4 - Math.max(0, S(f)) * bracoAmp * 0.6; p.bracoD.cot.rotation.x = -0.4 - Math.max(0, -S(f)) * bracoAmp * 0.6;
+    p.quadril.position.y = p.brancoY + Math.abs(S(f)) * 0.05 * (amp / 0.6);
+    p.torso.rotation.x = inclina; p.torso.rotation.y = S(f) * 0.12;
+}
+
+export const ANIMACOES = {
+    parado(p, t) { respirar(p, t); },
+
+    andar(p, t, op) { ciclo(p, t, (op.vel || 1) * 7, 0.55, 0.5, 0.05); p.cabeca.rotation.x = -0.03; },
+
+    correr(p, t, op) { ciclo(p, t, (op.vel || 1) * 11, 0.95, 1.0, 0.28); p.cabeca.rotation.x = -0.2; },
+
+    /** Braço direito estica para frente (o corpo já está virado para o alvo). */
+    apontar(p, t) {
+        respirar(p, t);
+        p.bracoD.ombro.rotation.x = -1.45 + S(t * 3) * 0.04; p.bracoD.ombro.rotation.z = -0.1; p.bracoD.cot.rotation.x = -0.1;
+        p.bracoE.ombro.rotation.x = 0.1; p.torso.rotation.y = -0.18; p.cabeca.rotation.y = 0.2;
+    },
+
+    /** Mão no queixo, cabeça de lado, balança de leve. */
+    pensar(p, t) {
+        respirar(p, t);
+        p.bracoD.ombro.rotation.x = -0.9; p.bracoD.ombro.rotation.z = 0.5; p.bracoD.cot.rotation.x = -1.9;
+        p.cabeca.rotation.z = 0.14 + S(t * 1.4) * 0.03; p.cabeca.rotation.x = -0.1; p.torso.rotation.y = 0.1;
+    },
+
+    /** Pula com os dois braços para cima. */
+    comemorar(p, t) {
+        const s = Math.abs(S(t * 6));
+        p.quadril.position.y = p.brancoY + s * 0.22;
+        p.bracoE.ombro.rotation.z = 2.5 + S(t * 12) * 0.2; p.bracoD.ombro.rotation.z = -2.5 - S(t * 12) * 0.2;
+        p.bracoE.cot.rotation.z = -0.15; p.bracoD.cot.rotation.z = 0.15;
+        p.bracoE.coxa.rotation.x = -s * 0.5; p.bracoD.coxa.rotation.x = -s * 0.5; p.bracoE.joelho.rotation.x = s * 0.8; p.bracoD.joelho.rotation.x = s * 0.8;
+        p.cabeca.rotation.x = -0.25; p.torso.rotation.y = S(t * 6) * 0.12;
+    },
+
+    /** Dá um pulinho para trás, mãos erguidas, boca em "o". */
+    surpreso(p, t) {
+        const k = clamp(t * 6), tremor = S(t * 40) * 0.01 * (1 - k * 0.5);
+        p.quadril.position.y = p.brancoY + S(k * Math.PI) * 0.15; p.quadril.position.z = -0.12 * k + tremor;
+        p.torso.rotation.x = -0.2 * k;
+        p.bracoE.ombro.rotation.x = -0.9 * k; p.bracoD.ombro.rotation.x = -0.9 * k; p.bracoE.ombro.rotation.z = 0.5 * k; p.bracoD.ombro.rotation.z = -0.5 * k;
+        p.bracoE.cot.rotation.x = -0.8 * k; p.bracoD.cot.rotation.x = -0.8 * k;
+        p.boca.scale.set(0.8, 0.9, 0.6); p.cabeca.rotation.x = -0.12 * k;
+    },
+
+    /** Corpo de quem conversa: gesto nas mãos e cabeça viva. A boca vem de `op.boca` (voz) ou de uma sílaba falsa. */
+    falar(p, t, op) {
+        respirar(p, t);
+        const g = S(t * 2.3), g2 = S(t * 3.1 + 1);
+        p.bracoD.ombro.rotation.x = -0.5 + g * 0.35; p.bracoD.cot.rotation.x = -0.9 + g2 * 0.4;
+        p.bracoE.ombro.rotation.x = -0.25 + g2 * 0.2; p.bracoE.cot.rotation.x = -0.6;
+        p.cabeca.rotation.x = S(t * 4.7) * 0.05; p.cabeca.rotation.y = S(t * 1.1) * 0.12;
+        if (op.boca == null) p.boca.scale.set(1.1, 0.12 + Math.abs(S(t * 13) * S(t * 5.3)) * 0.8, 0.5);
+    },
+};
+
+/** Abertura da boca (0..1) num instante, dadas as palavras [{de, ate}] (s). Cada palavra abre e fecha em sílabas. */
+export function bocaDe(t, palavras) {
+    for (const w of palavras || []) {
+        if (t >= w.de && t <= w.ate) {
+            const u = (t - w.de) / Math.max(0.05, w.ate - w.de), n = Math.max(1, Math.round((w.ate - w.de) / 0.17));
+            return 0.25 + 0.75 * Math.abs(S(u * Math.PI * n));
+        }
+    }
+    return 0;
+}
+
+export const NOMES_ANIMACAO = Object.keys(ANIMACOES);

package/kits/3d/base.js

@@ -0,0 +1,44 @@
+/* base.js — ferramentas comuns da biblioteca 3D (Three.js puro, peça 100% nossa).
+ * Estilo: low-poly fofinho. Formas arredondadas, cor chapada, sem textura. */
+import * as THREE from 'three';
+import { RoundedBoxGeometry } from 'three/examples/jsm/geometries/RoundedBoxGeometry.js';
+
+export { THREE };
+
+const mats = new Map();
+/** Material chapado, guardado por cor: 200 peças dividem poucos materiais. */
+export function mat(cor, { rough = 0.85, emissive = 0 } = {}) {
+    const k = `${cor}|${rough}|${emissive}`;
+    if (!mats.has(k)) {
+        const m = new THREE.MeshStandardMaterial({ color: cor, roughness: rough, metalness: 0.02, flatShading: true });
+        if (emissive) { m.emissive = new THREE.Color(cor); m.emissiveIntensity = emissive; }
+        mats.set(k, m);
+    }
+    return mats.get(k);
+}
+
+function malha(geo, cor, opts) {
+    const m = new THREE.Mesh(geo, cor && cor.isMaterial ? cor : mat(cor, opts));
+    m.castShadow = true; m.receiveShadow = true;
+    return m;
+}
+
+/** Caixa de cantos arredondados (o "fofinho"). */
+export const caixa = (w, h, d, cor, r = Math.min(w, h, d) * 0.22, opts) => malha(new RoundedBoxGeometry(w, h, d, 2, r), cor, opts);
+export const esfera = (r, cor, opts) => malha(new THREE.SphereGeometry(r, 14, 10), cor, opts);
+export const cilindro = (rt, rb, h, cor, seg = 14, opts) => malha(new THREE.CylinderGeometry(rt, rb, h, seg), cor, opts);
+export const cone = (r, h, cor, seg = 8) => malha(new THREE.ConeGeometry(r, h, seg), cor);
+export const capsula = (r, len, cor) => malha(new THREE.CapsuleGeometry(r, len, 3, 8), cor);
+
+/** Põe `m` dentro de um grupo e o desloca; devolve o grupo (pivô na origem). */
+export function em(m, x = 0, y = 0, z = 0) { m.position.set(x, y, z); return m; }
+export const grupo = (...filhos) => { const g = new THREE.Group(); filhos.forEach((f) => f && g.add(f)); return g; };
+
+export const clamp = (x, a = 0, b = 1) => Math.max(a, Math.min(b, x));
+export const lerp = (a, b, k) => a + (b - a) * k;
+/** Suavização padrão: começa e termina devagar. */
+export const suave = (x) => { const t = clamp(x); return t * t * (3 - 2 * t); };
+/** Saída com um leve estouro, para peça que "pula" na cena. */
+export const pop = (x) => { const t = clamp(x); return t >= 1 ? 1 : 1 - Math.pow(1 - t, 3) * Math.cos(t * 9) ; };
+/** Ruído determinístico 0..1 (a cena é função do tempo: nada de Math.random). */
+export const ruido = (n) => { const s = Math.sin(n * 127.1 + 311.7) * 43758.5453; return s - Math.floor(s); };

package/kits/3d/catalogo.js

@@ -0,0 +1,38 @@
+/* catalogo.js — o cardápio de peças. A IA escolhe daqui por `tipo`; o montador
+ * chama `criar(tipo, params)`. Peça nova entra aqui e some do "não existe". */
+import { criarPersonagem } from './personagem.js';
+import { NOMES_ANIMACAO } from './animacoes.js';
+import { terreno, arvore, casa, predio, rua, cruzamento, cone_, brita, pista } from './cenario.js';
+import { caminhao, guindaste, rolo } from './maquinas.js';
+
+export const CATALOGO = {
+    personagem: { fabrica: criarPersonagem, categoria: 'personagem', params: 'pele roupa calca capacete cabelo escala', api: 'animar(nome,t) falar(0..1)', desc: 'boneco articulado, qualquer papel' },
+    terreno: { fabrica: terreno, categoria: 'cenario', params: 'w d cor', desc: 'chão de terra' },
+    arvore: { fabrica: arvore, categoria: 'cenario', params: 'forma(redonda|pinheiro) escala cor', desc: 'árvore' },
+    casa: { fabrica: casa, categoria: 'cenario', params: 'cor telhado escala', desc: 'casa com telhado' },
+    predio: { fabrica: predio, categoria: 'cenario', params: 'andares cor larg escala', api: 'subir(0..1)', desc: 'prédio que pode subir andar por andar' },
+    rua: { fabrica: rua, categoria: 'cenario', params: 'comp larg faixa', desc: 'pedaço de rua (encaixa pelas pontas, eixo z)' },
+    cruzamento: { fabrica: cruzamento, categoria: 'cenario', params: 'larg braco', desc: 'cruzamento com faixas de pedestre' },
+    cone: { fabrica: cone_, categoria: 'cenario', params: 'escala', desc: 'cone de obra' },
+    brita: { fabrica: brita, categoria: 'processo', params: 'cor raio', api: 'encher(0..1)', desc: 'pilha de brita que cresce' },
+    pista: { fabrica: pista, categoria: 'processo', params: 'comp larg', api: 'base(k) massa(k) compactar(0..2) faixas(k)', desc: 'pista em obra com as camadas do asfalto' },
+    caminhao: { fabrica: caminhao, categoria: 'maquina', params: 'cor carga cargaCheia', api: 'despejar(0..1) rolar(m)', desc: 'caminhão basculante: a caçamba levanta e a carga cai' },
+    guindaste: { fabrica: guindaste, categoria: 'maquina', params: 'cor escala', api: 'girar(rad) lanca(0..1) cabo(m) carga(0|1)', desc: 'guindaste de esteira' },
+    rolo: { fabrica: rolo, categoria: 'maquina', params: 'cor', api: 'rolar(m)', desc: 'rolo compactador' },
+};
+
+export const ANIMACOES_UNIVERSAIS = NOMES_ANIMACAO;
+
+export function criar(tipo, params = {}) {
+    const c = CATALOGO[tipo];
+    if (!c) throw new Error(`peça "${tipo}" não existe no catálogo (${Object.keys(CATALOGO).join(', ')})`);
+    const o = c.fabrica(params);
+    o.userData.tipo = tipo; o.userData.categoria = c.categoria;
+    return o;
+}
+
+/** O cardápio em texto curto, para o prompt da IA que monta a cena. */
+export function cardapio() {
+    return Object.entries(CATALOGO).map(([k, c]) => `- ${k} [${c.categoria}] (${c.params})${c.api ? ` api: ${c.api}` : ''}: ${c.desc}`).join('\n')
+        + `\nanimações de personagem: ${NOMES_ANIMACAO.join(', ')}`;
+}

package/kits/3d/cenario.js

@@ -0,0 +1,162 @@
+/* cenario.js — o cenário que encaixa: terreno, casa, prédio, árvore, rua em
+ * pedaços, cruzamento, a pista de obra (com as camadas do asfalto) e a pilha de
+ * brita. Tudo feito em código, tudo no mesmo estilo fofinho.
+ *
+ * Convenção: chão em y=0, eixo da rua em z, peças centradas na origem.
+ * Peça que tem processo (prédio subindo, massa espalhando) expõe `userData.api`. */
+import { THREE, mat, caixa, esfera, cilindro, cone, grupo, em, clamp, lerp, suave, ruido } from './base.js';
+
+export function terreno({ w = 60, d = 60, cor = '#b99362' } = {}) {
+    const g = grupo(em(caixa(w, 0.6, d, cor, 0.05), 0, -0.3, 0));
+    for (let i = 0; i < 14; i++) {   // moitas de terra e pedrinhas, só para não ficar um prato liso
+        const m = esfera(0.25 + ruido(i) * 0.3, i % 3 ? '#a98253' : '#9b9b9b'); m.scale.y = 0.45;
+        g.add(em(m, (ruido(i + 40) - 0.5) * w * 0.9, 0.04, (ruido(i + 90) - 0.5) * d * 0.9));
+    }
+    return g;
+}
+
+export function arvore({ forma = 'redonda', escala = 1, cor = '#4caf50' } = {}) {
+    const g = grupo(em(cilindro(0.14, 0.2, 1.2, '#7b5233', 8), 0, 0.6, 0));
+    if (forma === 'pinheiro') {
+        [0, 1, 2].forEach((i) => g.add(em(cone(1.0 - i * 0.28, 1.3, '#2e7d4f', 8), 0, 1.5 + i * 0.75, 0)));
+    } else {
+        g.add(em(esfera(0.95, cor), 0, 1.9, 0)); g.add(em(esfera(0.65, cor), 0.55, 1.5, 0.2)); g.add(em(esfera(0.6, '#5cc060'), -0.5, 1.55, -0.2));
+    }
+    g.scale.setScalar(escala);
+    return g;
+}
+
+export function casa({ cor = '#f4d9a8', telhado = '#d1493f', escala = 1 } = {}) {
+    const g = grupo(em(caixa(3.2, 2.0, 2.8, cor, 0.08), 0, 1.0, 0));
+    const t = cone(2.6, 1.5, telhado, 4); t.rotation.y = Math.PI / 4; t.scale.set(1, 1, 0.88);
+    g.add(em(t, 0, 2.7, 0));
+    g.add(em(caixa(0.7, 1.2, 0.08, '#7b5233', 0.03), -0.6, 0.6, 1.42));
+    [0.9, 2.2].forEach((x) => g.add(em(caixa(0.7, 0.6, 0.08, '#9ed8f5', 0.03), x - 0.5, 1.2, 1.42)));
+    g.add(em(caixa(0.4, 0.9, 0.4, '#a9553f', 0.04), 1.0, 3.0, -0.5));
+    g.scale.setScalar(escala);
+    return g;
+}
+
+/** Prédio de andares. `api.subir(k)`: de 0 a 1, os andares aparecem de baixo para cima (a obra sobe). */
+export function predio({ andares = 6, cor = '#cfd8e3', larg = 3.4, escala = 1 } = {}) {
+    const g = new THREE.Group(), fl = [];
+    for (let i = 0; i < andares; i++) {
+        const f = grupo(em(caixa(larg, 1.0, larg, i % 2 ? cor : '#bcc8d6', 0.05), 0, 0.5, 0));
+        for (let j = -1; j <= 1; j++) {
+            f.add(em(caixa(0.7, 0.5, 0.06, '#8fd3ff', 0.02), j * 1.0, 0.55, larg / 2 + 0.01));
+            f.add(em(caixa(0.7, 0.5, 0.06, '#8fd3ff', 0.02), j * 1.0, 0.55, -larg / 2 - 0.01));
+        }
+        f.position.y = i; g.add(f); fl.push(f);
+    }
+    g.add(em(caixa(larg + 0.3, 0.18, larg + 0.3, '#8895a7', 0.04), 0, andares + 0.09, 0));
+    const topo = g.children[g.children.length - 1];
+    const api = {
+        subir(k) {
+            const n = k * andares;
+            fl.forEach((f, i) => { const a = clamp(n - i); f.visible = a > 0; f.scale.set(1, Math.max(a, 0.001), 1); });
+            topo.position.y = Math.min(n, andares) + 0.09; topo.visible = k > 0;
+        },
+    };
+    api.subir(1);
+    g.userData.api = api; g.scale.setScalar(escala);
+    return g;
+}
+
+const ASFALTO = '#3a3d44', CALCADA = '#c9c6bd';
+
+/** Um pedaço de rua reto (eixo z). Encaixa pelas pontas: `comp` de comprimento. */
+export function rua({ comp = 10, larg = 4, faixa = true } = {}) {
+    const g = grupo(em(caixa(larg, 0.12, comp, ASFALTO, 0.02), 0, 0.06, 0));
+    [-1, 1].forEach((s) => g.add(em(caixa(0.9, 0.2, comp, CALCADA, 0.03), s * (larg / 2 + 0.45), 0.1, 0)));
+    if (faixa) for (let z = -comp / 2 + 0.8; z < comp / 2 - 0.4; z += 1.6) g.add(em(caixa(0.14, 0.02, 0.8, '#f3d34a', 0.005), 0, 0.125, z));
+    return g;
+}
+
+/** Cruzamento em cruz: duas pistas e as faixas de pedestre. */
+export function cruzamento({ larg = 4, braco = 5 } = {}) {
+    const g = grupo(em(caixa(larg, 0.12, larg + braco * 2, ASFALTO, 0.02), 0, 0.06, 0), em(caixa(larg + braco * 2, 0.12, larg, ASFALTO, 0.02), 0, 0.065, 0));
+    for (const [sx, sz] of [[1, 0], [-1, 0], [0, 1], [0, -1]]) {
+        for (let i = -3; i <= 3; i++) {
+            const f = caixa(sx ? 0.5 : 0.35, 0.02, sx ? 0.35 : 0.5, '#f4f4f0', 0.005);
+            g.add(em(f, sx * (larg / 2 + 0.7) + (sz ? i * 0.5 : 0), 0.13, sz * (larg / 2 + 0.7) + (sx ? i * 0.5 : 0)));
+        }
+    }
+    [[1, 1], [1, -1], [-1, 1], [-1, -1]].forEach(([x, z]) => g.add(em(caixa(braco, 0.2, braco, CALCADA, 0.03), x * (larg / 2 + braco / 2), 0.1, z * (larg / 2 + braco / 2))));
+    return g;
+}
+
+/** Cone de obra. */
+export function cone_({ escala = 1 } = {}) {
+    const g = grupo(em(caixa(0.45, 0.06, 0.45, '#2b2b2b', 0.02), 0, 0.03, 0), em(cone(0.17, 0.6, '#ff7a1a', 12), 0, 0.36, 0), em(cilindro(0.1, 0.12, 0.08, '#ffffff', 12), 0, 0.33, 0));
+    g.scale.setScalar(escala);
+    return g;
+}
+
+/** Pilha de brita. `api.encher(k)`: a pilha cresce de 0 a 1. */
+export function brita({ cor = '#8d8a86', raio = 1.3 } = {}) {
+    const g = new THREE.Group(), pedras = [];
+    for (let i = 0; i < 26; i++) {
+        const a = ruido(i) * Math.PI * 2, r = Math.sqrt(ruido(i + 7)) * raio * 0.9;
+        const m = esfera(0.18 + ruido(i + 3) * 0.14, ruido(i + 5) > 0.5 ? cor : '#a09c97'); m.scale.y = 0.75;
+        m.position.set(Math.cos(a) * r, Math.max(0.08, (1 - r / raio) * raio * 0.55) , Math.sin(a) * r);
+        g.add(m); pedras.push(m);
+    }
+    g.userData.api = { encher(k) { g.scale.set(lerp(0.2, 1, suave(k)), Math.max(0.001, suave(k)), lerp(0.2, 1, suave(k))); g.visible = k > 0.001; } };
+    g.userData.api.encher(1);
+    return g;
+}
+
+/**
+ * A pista em obra, de ponta a ponta no eixo z (de -comp/2 a +comp/2), com as
+ * camadas do asfalto, cada uma controlada por uma api de 0 a 1:
+ *   leito (terra batida, sempre) · base(k) brita · massa(k) a massa quente
+ *   espalhando de -z para +z · compactar(p) o rolo: p 0..1 vai, p 1..2 volta ·
+ *   faixas(k) pintura. A massa solta vapor enquanto está quente.
+ */
+export function pista({ comp = 16, larg = 4 } = {}) {
+    const N = 20, g = new THREE.Group(), lw = comp / N;
+    g.add(em(caixa(larg + 0.4, 0.06, comp, '#8a6a45', 0.02), 0, 0.03, 0));
+    const camadaBase = caixa(larg, 0.1, comp, '#9a9690', 0.02); camadaBase.position.set(0, 0.11, 0); g.add(camadaBase);
+    const fatias = [];
+    for (let i = 0; i < N; i++) {
+        const m = new THREE.Mesh(new THREE.BoxGeometry(larg, 1, lw * 1.01), new THREE.MeshStandardMaterial({ color: '#4a3b2f', roughness: 0.95, flatShading: true }));
+        m.castShadow = m.receiveShadow = true; g.add(m); fatias.push(m);
+    }
+    const dashes = [];
+    for (let i = 0; i < 10; i++) { const d = caixa(0.14, 0.02, 0.9, '#f3d34a', 0.005); d.position.set(0, 0.3, -comp / 2 + (i + 0.5) * comp / 10); g.add(d); dashes.push(d); }
+    const borda = [-1, 1].map((s) => { const b = caixa(0.1, 0.02, comp, '#f4f4f0', 0.005); b.position.set(s * (larg / 2 - 0.2), 0.3, 0); g.add(b); return b; });
+    const vapor = []; for (let i = 0; i < 16; i++) { const v = esfera(0.3, new THREE.MeshBasicMaterial({ color: '#ffffff', transparent: true, opacity: 0, depthWrite: false })); v.castShadow = false; g.add(v); vapor.push(v); }
+
+    const est = { massa: 0, comp: 0 };
+    const cor0 = new THREE.Color('#4a3b2f'), cor1 = new THREE.Color('#25272c');
+    const aplicar = () => {
+        fatias.forEach((m, i) => {
+            const zn = (i + 0.5) / N;
+            const cobre = clamp((est.massa - i / N) * N);
+            const c = clamp(clamp((est.comp - zn) * 6) * 0.6 + clamp((est.comp - 1 - (1 - zn)) * 6) * 0.4);
+            const h = lerp(0.24, 0.1, c);
+            m.visible = cobre > 0; m.scale.y = Math.max(0.001, h * Math.min(1, cobre * 2));
+            m.position.set(0, 0.16 + m.scale.y / 2, -comp / 2 + zn * comp);
+            m.material.color.copy(cor0).lerp(cor1, c);
+            m.userData.c = c;
+        });
+    };
+    const api = {
+        base(k) { k = clamp(k); camadaBase.scale.z = Math.max(0.001, k); camadaBase.position.z = -comp / 2 + comp * k / 2; camadaBase.visible = k > 0; },
+        massa(k) { est.massa = clamp(k); aplicar(); },
+        compactar(p) { est.comp = clamp(p, 0, 2); aplicar(); },
+        faixas(k) { dashes.forEach((d, i) => { d.visible = k * 10 > i; }); borda.forEach((b) => { b.visible = k > 0.05; b.scale.z = Math.max(0.001, clamp(k * 1.2)); }); },
+        atualizar(t) {
+            vapor.forEach((v, i) => {
+                const zn = ruido(i * 3.1), u = (t * 0.35 + ruido(i)) % 1;
+                const idx = Math.min(N - 1, Math.floor(zn * N)), f = fatias[idx];
+                const quente = f.visible ? 1 - (f.userData.c || 0) : 0;
+                v.position.set((ruido(i + 20) - 0.5) * larg * 0.8, 0.4 + u * 1.6, -comp / 2 + zn * comp);
+                v.scale.setScalar(0.4 + u * 1.1); v.material.opacity = quente * (1 - u) * 0.38;
+            });
+        },
+    };
+    api.base(0); api.massa(0); api.faixas(0);
+    g.userData.api = api; g.userData.comp = comp;
+    return g;
+}

package/kits/3d/exemplos/asfalto.mjs

@@ -0,0 +1,91 @@
+/* Maquete "como se faz asfalto": 6 etapas, cada uma mostra o processo. Peças do catálogo, nada mais.
+ * A pista corre no eixo z, de -9 a +9. Caminhão e rolo andam EM CIMA dela, na velocidade em que a camada
+ * se forma, por isso mover e api usam a mesma duração e ease linear. */
+const VOZ = [[0.0, 4.625], [4.745, 9.82], [9.94, 16.39], [16.51, 21.81], [21.93, 26.33], [26.45, 32.35]];
+const TEXTOS = [
+    'Toda rua começa assim: terra nivelada e firme.',
+    'Primeiro, a brita. Ela é a base que segura o peso.',
+    'A caçamba levanta e a massa quente, a mais de 100 graus, escorre.',
+    'O rolo compactador passa por cima e aperta a massa.',
+    'Cada passada deixa a pista mais lisa e mais escura.',
+    'Esfriou, pintou as faixas: a rua está pronta.',
+];
+const TITULOS = ['Terreno', 'Base de brita', 'Massa quente', 'Rolo compactador', 'Mais uma passada', 'Faixas e pronto'];
+const dur = VOZ.map(([a, b]) => Math.round((b - a + 0.9) * 10) / 10);
+const COMP = 18, Z0 = -COMP / 2;                 // início da pista
+const zCacamba = (k) => Z0 + COMP * k + 2.4;     // a traseira fica na borda da camada que nasce
+const gente = { eng: { roupa: '#ff7a1a', capacete: '#ffd23f', pele: '#e8b48a' }, op: { roupa: '#7bd13a', capacete: '#f4f4f4', pele: '#b9825a', calca: '#22385c' } };
+
+export const roteiro = {
+    ceu: ['#8fd0ff', '#d8efff'],
+    etapas: [
+        { id: 'terreno', dur: dur[0], titulo: TITULOS[0], legenda: TEXTOS[0], voz: { de: VOZ[0][0], ate: VOZ[0][1] },
+          camera: { de: [7, 7, -25], para: [5, 3.6, -15], alvo: [0, 1, 0], alvoPara: [0, 1.4, -2], fov: 46 },
+          pecas: [
+              { id: 'chao', tipo: 'terreno', w: 70, d: 70 },
+              { id: 'pista', tipo: 'pista', comp: COMP, larg: 4.2 },
+              { id: 'casa1', tipo: 'casa', pos: [-23, 0, -4], giro: 0.7, escala: 1.2 },
+              { id: 'casa2', tipo: 'casa', pos: [23, 0, 2], giro: -0.8, escala: 1.1, cor: '#bfe3f2', telhado: '#6b7bd1' },
+              { id: 'predio', tipo: 'predio', andares: 8, pos: [-21, 0, 11] },
+              { id: 'guind', tipo: 'guindaste', pos: [21, 0, 12], giro: -2.3, escala: 0.8 },
+              { id: 'a1', tipo: 'arvore', pos: [15, 0, -10] }, { id: 'a2', tipo: 'arvore', pos: [-14, 0, 4], escala: 1.2 },
+              { id: 'a3', tipo: 'arvore', pos: [14, 0, 7], escala: 0.9 }, { id: 'a4', tipo: 'arvore', pos: [-13, 0, -10], escala: 1.1 },
+              { id: 'cone1', tipo: 'cone', pos: [-2.6, 0, -9.6], escala: 1.3 }, { id: 'cone2', tipo: 'cone', pos: [2.6, 0, -9.6], escala: 1.3 },
+              { id: 'eng', tipo: 'personagem', ...gente.eng, pos: [3.6, 0, -6], giro: -1.1 },
+              { id: 'op', tipo: 'personagem', ...gente.op, pos: [-3.6, 0, -6], giro: 1.2 },
+          ],
+          acoes: [
+              { em: 0.8, dur: 3.6, quem: 'eng', faz: 'anim', nome: 'apontar' },
+              { em: 0, dur: dur[0], quem: 'op', faz: 'anim', nome: 'pensar' },
+              { em: 0, dur: dur[0], quem: 'guind', faz: 'api', metodo: 'girar', de: -2.3, para: -1.2, ease: 'linear' },
+              { em: 0, dur: dur[0], quem: 'guind', faz: 'api', metodo: 'cabo', de: 2.5, para: 6 },
+              { em: 0, dur: dur[0], quem: 'predio', faz: 'api', metodo: 'subir', de: 0.85, para: 1, ease: 'linear' },
+          ] },
+        { id: 'brita', dur: dur[1], titulo: TITULOS[1], legenda: TEXTOS[1], voz: { de: VOZ[1][0], ate: VOZ[1][1] },
+          camera: { de: [-17, 7.5, -14], para: [-17, 7.8, 6], alvo: 'cb', fov: 44 },
+          pecas: [{ id: 'cb', tipo: 'caminhao', cor: '#e8b100', carga: '#8d8a86', pos: [0, 0, -34], sai: dur[1] }],
+          acoes: [
+              { em: 0, dur: 2.0, quem: 'cb', faz: 'mover', para: [0, zCacamba(0)] },
+              { em: 2.1, dur: 3.4, quem: 'cb', faz: 'mover', para: [0, zCacamba(1)], ease: 'linear' },
+              { em: 2.1, dur: 3.4, quem: 'cb', faz: 'api', metodo: 'despejar', de: 0, para: 1, ease: 'linear' },
+              { em: 2.1, dur: 3.4, quem: 'pista', faz: 'api', metodo: 'base', de: 0, para: 1, ease: 'linear' },
+          ] },
+        { id: 'massa', dur: dur[2], titulo: TITULOS[2], legenda: TEXTOS[2], voz: { de: VOZ[2][0], ate: VOZ[2][1] },
+          camera: { de: [16, 6.5, -13], para: [16, 7, 7], alvo: 'cm', fov: 44 },
+          pecas: [{ id: 'cm', tipo: 'caminhao', cor: '#e8590c', carga: '#1f1a16', pos: [0, 0, -34], sai: dur[2] }],
+          acoes: [
+              { em: 0, dur: 2.2, quem: 'cm', faz: 'mover', para: [0, zCacamba(0)] },
+              { em: 2.4, dur: 4.2, quem: 'cm', faz: 'mover', para: [0, zCacamba(1)], ease: 'linear' },
+              { em: 2.4, dur: 4.2, quem: 'cm', faz: 'api', metodo: 'despejar', de: 0, para: 1, ease: 'linear' },
+              { em: 2.4, dur: 4.2, quem: 'pista', faz: 'api', metodo: 'massa', de: 0, para: 1, ease: 'linear' },
+              { em: 0, dur: dur[2], quem: 'eng', faz: 'anim', nome: 'apontar' },
+          ] },
+        { id: 'rolo1', dur: dur[3], titulo: TITULOS[3], legenda: TEXTOS[3], voz: { de: VOZ[3][0], ate: VOZ[3][1] },
+          camera: { de: [-13, 5.6, -15], para: [-13, 5.4, 4], alvo: 'r1', fov: 44 },
+          pecas: [{ id: 'r1', tipo: 'rolo', pos: [0, 0, -34] }],
+          acoes: [
+              { em: 0, dur: 1.5, quem: 'r1', faz: 'mover', para: [0, Z0 - 1.15] },
+              { em: 1.6, dur: 3.9, quem: 'r1', faz: 'mover', para: [0, Z0 - 1.15 + COMP], ease: 'linear' },
+              { em: 1.6, dur: 3.9, quem: 'pista', faz: 'api', metodo: 'compactar', de: 0, para: 1, ease: 'linear' },
+              { em: 0, dur: dur[3], quem: 'op', faz: 'anim', nome: 'surpreso' },
+          ] },
+        { id: 'rolo2', dur: dur[4], titulo: TITULOS[4], legenda: TEXTOS[4], voz: { de: VOZ[4][0], ate: VOZ[4][1] },
+          camera: { de: [9, 3.2, 9], para: [9, 3.2, -9], alvo: 'r1', fov: 40 },
+          pecas: [],
+          acoes: [
+              { em: 0.2, dur: 3.9, quem: 'r1', faz: 'mover', para: [0, Z0 - 1.15], reversa: true, ease: 'linear' },
+              { em: 0.2, dur: 3.9, quem: 'pista', faz: 'api', metodo: 'compactar', de: 1, para: 2, ease: 'linear' },
+          ] },
+        { id: 'fim', dur: dur[5], titulo: TITULOS[5], legenda: TEXTOS[5], voz: { de: VOZ[5][0], ate: VOZ[5][1] },
+          camera: { de: [6, 4.4, -16], para: [11, 9, -23], alvo: [0, 0.8, 0], alvoPara: [0, 1.2, 2], fov: 46 },
+          pecas: [{ id: 'carro', tipo: 'caminhao', cor: '#3b82f6', cargaCheia: false, pos: [0, 0, -40], sai: dur[5] }],
+          acoes: [
+              { em: 0, dur: 1.0, quem: 'op', faz: 'mover', para: [0.0, Z0 + 0.4], anim: 'correr' },
+              { em: 1.1, dur: 3.2, quem: 'op', faz: 'mover', para: [0.0, Z0 + COMP - 0.4], anim: 'andar', ease: 'linear', vel: 1.5 },
+              { em: 1.1, dur: 3.2, quem: 'pista', faz: 'api', metodo: 'faixas', de: 0, para: 1, ease: 'linear' },
+              { em: 4.4, dur: 3, quem: 'op', faz: 'anim', nome: 'comemorar' },
+              { em: 4.0, dur: 3, quem: 'eng', faz: 'anim', nome: 'comemorar' },
+              { em: 3.6, dur: 3.2, quem: 'carro', faz: 'mover', para: [-1.1, 34], ease: 'linear' },
+          ] },
+    ],
+};

package/kits/3d/maquinas.js

@@ -0,0 +1,97 @@
+/* maquinas.js — máquinas articuladas: caminhão basculante, guindaste e rolo
+ * compactador. A frente de cada uma aponta para +z. Cada articulação é uma
+ * função da api (0..1 ou metros), por isso o montador só diz "levanta a
+ * caçamba 0→1" e a peça se mexe. */
+import { THREE, mat, caixa, esfera, cilindro, grupo, em, clamp, lerp, suave, ruido } from './base.js';
+
+function roda(r, larg, cor = '#26282d') {
+    const pivo = grupo(), pneu = cilindro(r, r, larg, cor, 16), cubo = cilindro(r * 0.5, r * 0.5, larg + 0.02, '#c9ccd2', 10);
+    pneu.rotation.z = cubo.rotation.z = Math.PI / 2;
+    pivo.add(pneu, cubo);
+    return pivo;
+}
+
+/** Caminhão basculante. api: despejar(k) levanta a caçamba e solta a carga; rolar(m) gira as rodas. */
+export function caminhao({ cor = '#f2a900', carga = '#4a3b2f', cargaCheia = true } = {}) {
+    const g = new THREE.Group(), rodas = [];
+    g.add(em(caixa(1.4, 0.3, 3.7, '#3d4048', 0.05), 0, 0.62, 0));
+    g.add(em(caixa(1.45, 0.95, 1.15, cor, 0.16), 0, 1.3, 1.35));
+    g.add(em(caixa(1.3, 0.45, 0.06, '#9ed8f5', 0.03), 0, 1.5, 1.93));
+    g.add(em(caixa(1.2, 0.2, 0.15, '#2b2b2b', 0.04), 0, 0.72, 2.0));
+    [-0.5, 0.5].forEach((x) => g.add(em(esfera(0.1, '#fff4c2', { emissive: 0.6 }), x, 0.8, 2.0)));
+    for (const [z, s] of [[1.35, 1], [-0.7, 1], [-1.45, 1]]) for (const x of [-0.78, 0.78]) { const r = roda(0.4, 0.3); r.position.set(x * s, 0.4, z); g.add(r); rodas.push(r); }
+
+    // caçamba: pivô na traseira (z = -1.8); levantar = girar para trás
+    const cacamba = grupo(); cacamba.position.set(0, 0.85, -1.8);
+    cacamba.add(em(caixa(1.6, 0.12, 2.7, cor, 0.04), 0, 0, 1.35));
+    cacamba.add(em(caixa(0.1, 0.7, 2.7, cor, 0.04), -0.78, 0.35, 1.35), em(caixa(0.1, 0.7, 2.7, cor, 0.04), 0.78, 0.35, 1.35), em(caixa(1.6, 0.9, 0.1, cor, 0.04), 0, 0.45, 2.7));
+    const monte = em(esfera(1, carga), 0, 0.1, 1.3); monte.scale.set(0.72, 0.5, 1.25); cacamba.add(monte);
+    g.add(cacamba);
+    const gotas = []; for (let i = 0; i < 20; i++) { const b = esfera(0.17, carga); b.visible = false; g.add(b); gotas.push(b); }
+
+    const est = { k: 0 };
+    const api = {
+        despejar(k) {
+            est.k = clamp(k);
+            const sobe = suave(clamp(k / 0.35)) * (k > 0.88 ? 1 - (k - 0.88) / 0.12 : 1);
+            cacamba.rotation.x = -sobe * 0.72;
+            const resto = cargaCheia ? 1 - clamp((k - 0.3) / 0.55) : 0;
+            monte.visible = resto > 0.02; monte.scale.set(0.72 * (0.5 + resto * 0.5), 0.5 * resto, 1.25 * (0.4 + resto * 0.6));
+            monte.position.z = 1.3 - (1 - resto) * 0.55 * sobe;
+            est.cai = sobe > 0.6 && resto > 0.03;
+        },
+        rolar(m) { rodas.forEach((r) => { r.rotation.x = m / 0.4; }); },
+        atualizar(t) {
+            gotas.forEach((b, i) => {
+                const u = (t * 1.7 + i / gotas.length) % 1, voando = est.cai && u < 0.5;
+                b.visible = !!voando;
+                if (voando) { b.position.set((ruido(i) - 0.5) * 1.1, 1.05 - 3.4 * u * u, -2.3 - u * 0.5); b.scale.setScalar(1 - u * 0.5); }
+            });
+        },
+    };
+    api.despejar(0);
+    g.userData.api = api;
+    return g;
+}
+
+/** Guindaste de esteira. api: girar(rad) · lanca(0..1) · cabo(m) · carga(0|1). */
+export function guindaste({ cor = '#f5c518', escala = 1 } = {}) {
+    const g = new THREE.Group();
+    g.add(em(caixa(2.4, 0.6, 3.4, '#34373d', 0.1), 0, 0.4, 0));
+    [-1.1, 1.1].forEach((x) => g.add(em(caixa(0.5, 0.7, 3.6, '#202226', 0.2), x, 0.38, 0)));
+    const torre = grupo(); torre.position.y = 0.8; g.add(torre);
+    torre.add(em(caixa(2.0, 0.5, 2.2, cor, 0.1), 0, 0.25, 0), em(caixa(1.0, 0.9, 1.0, cor, 0.1), 0, 0.95, 0.6), em(caixa(0.9, 0.5, 0.06, '#9ed8f5', 0.03), 0, 1.0, 1.12));
+    torre.add(em(caixa(0.5, 0.7, 0.9, '#444850', 0.08), 0, 0.6, -0.9));
+    torre.add(em(caixa(0.4, 6, 0.4, cor, 0.08), 0, 3.3, -0.2));
+    const lanca = grupo(); lanca.position.set(0, 6.2, -0.2); torre.add(lanca);
+    lanca.add(em(caixa(0.32, 0.32, 8, cor, 0.06), 0, 0, 4));
+    const pont = grupo(); pont.position.z = 8; lanca.add(pont);
+    const cabo = cilindro(0.03, 0.03, 1, '#222', 6); cabo.castShadow = false; pont.add(cabo);
+    const gancho = grupo(em(caixa(0.3, 0.3, 0.3, '#d33', 0.06), 0, -0.15, 0)); pont.add(gancho);
+    const carga = em(caixa(1.2, 0.7, 1.2, '#7fb069', 0.1), 0, -0.9, 0); gancho.add(carga);
+    const est = { a: 0.9 };
+    const api = {
+        girar(r) { torre.rotation.y = r; },
+        lanca(k) { est.a = lerp(0.35, 1.15, clamp(k)); lanca.rotation.x = -est.a; pont.rotation.x = est.a; },
+        cabo(m) { const c = Math.max(0.2, m); cabo.scale.y = c; cabo.position.y = -c / 2; gancho.position.y = -c; },
+        carga(v) { carga.visible = v > 0.5; },
+    };
+    api.lanca(0.5); api.cabo(3); api.carga(0);
+    g.userData.api = api; g.scale.setScalar(escala);
+    return g;
+}
+
+/** Rolo compactador. api: rolar(m) gira o cilindro e as rodas. */
+export function rolo({ cor = '#ffd23f' } = {}) {
+    const g = new THREE.Group();
+    const tambor = cilindro(0.62, 0.62, 1.8, '#7d8590', 20); tambor.rotation.z = Math.PI / 2;
+    const frente = grupo(tambor); frente.position.set(0, 0.62, 1.15); g.add(frente);
+    [-0.98, 0.98].forEach((x) => g.add(em(caixa(0.14, 0.18, 1.0, '#454a52', 0.04), x, 1.05, 0.95)));
+    g.add(em(caixa(1.4, 0.7, 2.0, cor, 0.16), 0, 1.0, -0.4));
+    g.add(em(caixa(1.0, 0.5, 0.9, cor, 0.12), 0, 1.5, -0.7));
+    g.add(em(caixa(1.2, 0.08, 1.2, '#2c3038', 0.03), 0, 2.2, -0.7));
+    [[-0.5, 0.5], [0.5, 0.5], [-0.5, -1.9], [0.5, -1.9]].forEach(([x, z]) => g.add(em(cilindro(0.04, 0.04, 0.7, '#2c3038', 6), x, 1.85, z * 0.5 - 0.2)));
+    const traseiras = [-0.85, 0.85].map((x) => { const r = roda(0.52, 0.5, '#26282d'); r.position.set(x, 0.52, -1.0); g.add(r); return r; });
+    g.userData.api = { rolar(m) { frente.rotation.x = m / 0.62; traseiras.forEach((r) => { r.rotation.x = m / 0.52; }); } };
+    return g;
+}