boranfurkan/direção-de-cena

Direção de cena

Ao pedir "um site 3D imersivo", um modelo constrói a média de todas as demonstrações 3D que já viu: uma orbe que respira em uma noite roxa, um globo pontilhado com arcos, um produto cinza em um chão cinza, ou o mesmo layout dividido e organizado em cada seção. Os sites que ganham prêmios fazem outra coisa: uma ideia do assunto, um mundo ao redor de seu próprio objeto, uma câmera que muda de plano a cada batida da história, luz com uma fonte e um acabamento graduado, tipografia com voz, uma coisa para interagir, e o chrome de um site real. E eles funcionam perfeitamente em um telefone.

Esta habilidade fornece uma direção distribuída, uma biblioteca de ativos, um template inicial com o pipeline completo de acabamento e uma verificação que renderiza sua página como um visitante e um júri a veriam. Ela assume o controle da direção 3D. Se habilidades de design de página (taste-skill, impeccable, hallmark), habilidades de API three.js (cloudai-x/threejs-skills) ou as habilidades oficiais GSAP estiverem instaladas, use-as para essas partes.

<skill> abaixo é a pasta desta habilidade. Execute os scripts a partir da pasta do projeto.

A execução

1. Inventário. Liste o que é real: o nome do assunto, o que ele faz ou vende, seu lugar, seus números, seus artefatos e qualquer modelo ou imagem fornecida. Um modelo fornecido é o herói (references/object.md).
2. Distribua a direção. Se deixado sozinho, você escolherá o padrão da categoria, então deixe o script distribuir:

   node <skill>/scripts/draw.mjs --kind <pessoa|fabricante|produto|lugar|marca|evento|...> --brief "<uma linha>"
   node <skill>/scripts/draw.mjs --direction <id escolhido> --brief "<uma linha>" --scenes <n>
   

   Escolha o dos três que pode carregar algo que apenas este assunto tem, não o mais familiar. O segundo comando escreve .scene-direction/sheet.md no projeto: o clima, o mundo, a luz, o acabamento, os ativos a procurar, os terrenos, as fontes e um posicionamento de plano e cópia para cada cena. Adote-o. Redesenhe apenas por um motivo que você possa declarar, e diga isso no relatório.
3. Ideia e coisa viva (references/idea-and-devices.md). Neste site, [uma coisa que pertence ao assunto] se torna [o mundo ou dispositivo da direção]. Deve falhar no teste do concorrente. Adicione a única coisa viva. Leia references/tells.md.
4. Obtenha os ativos (references/assets.md). Execute os comandos assets.mjs da ficha: o HDRI e, na fidelidade da ficha, os adereços e superfícies para o mundo ao redor do assunto. Olhe as folhas de contato antes de escolher, então get eles para assets/.
5. Construa a partir de <skill>/assets/starter.html. É infraestrutura, não um layout: canvas de sangria total cujo fundo é o solo CSS, a cadeia de acabamento (HDRI, AO, bloom, vinheta, mapeamento de tons, SMAA), SHOTS para a câmera, posicionamento de cópia por cena com scrims, um relógio (gsap.ticker + Lenis), revelações de linha, uma introdução curta, o cabeçalho, índice e rodapé, desvio do ponteiro, movimento reduzido e etapas de qualidade. Preencha seu FINISH a partir da ficha e data-ground, data-shot, data-copy e data-chapter de cada seção. Substitua o texto, título e descrição do espaço reservado. No Vite ou Next.js, porte suas peças.
6. Crie o mundo e o objeto (references/object.md, colour-world.md, finish.md). Modele a própria coisa do assunto de acordo com a barra em object.md, então coloque-a em algum lugar: os adereços e superfícies que você buscou, uma sala, um vale, a coleção. Ilumine-a com o rig da ficha e uma fonte dentro do quadro.
7. História, planos e movimento (references/scenes-and-motion.md, motion-and-type.md). Cada cena recebe uma batida, o plano da ficha e uma declaração na fonte de exibição. Para um lugar, a câmera viaja pelo mundo ao longo de uma rota (cenas path), nunca ao redor de um diorama. Planeje a viagem da câmera, a versão para telefone e o movimento reduzido. Vista o chrome na linguagem do assunto (references/chrome.md).
8. Verifique.

   node <skill>/scripts/check.mjs <pasta-ou-url> --out scene-check     # adicione --click "Enter" para um portão de introdução
   

   Precisa de Playwright (npm i -D playwright && npx playwright install chromium, em uma pasta separada se o projeto não deve obter a dependência). Ele filma cada cena em seu ponto de repouso no desktop e celular (scene-check/film-desktop.png, film-phone.png), carrega a página novamente com movimento reduzido e relata o tempo de quadro, peso da página e quanto tempo a introdução leva. Leia cada imagem que ele escreve.
9. Olhe e corrija: os três principais, até três rodadas (references/critique.md). Pontue a rubrica a partir das imagens, corrija as três coisas mais fracas, verifique e olhe novamente. Corrija as descobertas com a menor alteração que mantenha o design. Se uma descoberta for deliberada (tipografia em camadas, um corte deliberado, um objeto subindo de baixo da dobra), mantenha-a e nomeie-a.
10. Relatório. Dê a direção, a frase da ideia, a coisa viva, os ativos que você usou, o resultado da verificação, suas pontuações e o que você manteve intencionalmente.

Ambição, não moderação

Em testes cegos, um juiz preferiu a página rica e atmosférica com um pequeno defeito à página arrumada e segura sem nenhum, toda vez que houve uma escolha entre elas. Remover defeitos é metade do trabalho. A outra metade é substância:

• Sangria total. O 3D domina a tela. A cópia fica sobre ela com um scrim, ou ao lado do objeto enquanto a renderização se afasta dele.
• Um plano diferente a cada cena. Não use a mesma câmera com a cópia trocada. A verificação sinaliza uma página que mostra um ou dois planos em toda a rolagem.
• Um grande herói. Na primeira tela, o objeto ou mundo preenche a maior parte do quadro, ao lado do nome definido em tamanho grande.
• Um mundo, não um objeto em um vazio. A sala, a mesa, a terra, a coleção, os adereços que pertencem ao assunto, em escala real.
• Atmosfera e acabamento. Luz com uma hora do dia e uma direção, uma fonte dentro da cena que brilha, sombras de contato, um quadro graduado. Rico, não leitoso: cada quadro tem um escuro verdadeiro e uma cor saturada; névoa apenas para distância em um mundo, nunca sobre o assunto.
• Tipografia com voz. A fonte de exibição da ficha em tamanhos de exibição, com palavras e números reais do inventário, chegando linha por linha.
• Um site, não uma demonstração. Um cabeçalho, um índice, um rodapé com um contato real, uma introdução de cerca de 2 segundos.

O mínimo: nunca envie estes

• Um ERROR da verificação: uma falha, uma tela em branco, uma carga falhada (também com movimento reduzido).
• O assunto cortado acidentalmente ou minúsculo na primeira tela do telefone.
• Uma declaração que você não consegue ler no ponto de repouso de sua cena, ou trechos da rolagem sem palavras.
• Um layout mais largo que o telefone.
• Um cursor nativo oculto, um título, descrição ou h1 ausente, ou cópia de espaço reservado.
• Uma introdução que mantém o visitante esperando por mais de alguns segundos, ou quadros mais lentos que 40 fps na GPU da verificação.
• Uma versão desatualizada ou incompatível do three.js. Use a versão do projeto ou as abaixo.

Correção por tag

• [errors]: corrija o primeiro erro antes de qualquer outra coisa. Causas comuns são argumentos de construtor trocados, um let/const usado antes de sua declaração, URLs de addon em outra versão, uma entrada de mapa de importação ausente, 404s e texturas bloqueadas por CORS.
• [framing]: enquadre por plano para a proporção de aspecto atual (references/framing.md).
• [ambition]: dê a cada cena seu próprio plano da ficha (references/scenes-and-motion.md).
• [story]: quadros sem declaração. Mantenha as palavras de cada cena na tela enquanto sua cena estiver na tela e desapareça-as apenas na transição (o loop do template inicial faz isso).
• [labels]: texto e rótulos sobrepostos ou cortados; barras de ferramentas em telefones (references/labels.md).
• [legibility]: acalme a cena atrás do texto ou fortaleça o scrim antes de mover qualquer coisa (references/legibility.md). Superfícies claras que brilham são muito brilhantes: diminua as luzes, não o limite.
• [usability]: o básico do júri: cursor nativo, título, descrição, idioma, um h1, texto alternativo, movimento reduzido (references/chrome.md).
• [performance]: proporção de pixels, tamanho do mapa de sombra, qualidade AO, menos adereços, texturas menores (references/finish.md §7).

Versões fixadas

Verificado no npm e jsDelivr em 2026-11-03 (o mapa de importação do template inicial):

{ "three": "https://cdn.jsdelivr.net/npm/[email protected]/build/three.module.js",
  "three/addons/": "https://cdn.jsdelivr.net/npm/[email protected]/examples/jsm/",
  "three/examples/jsm/": "https://cdn.jsdelivr.net/npm/[email protected]/examples/jsm/",
  "postprocessing": "https://cdn.jsdelivr.net/npm/[email protected]/build/index.js",
  "n8ao": "https://cdn.jsdelivr.net/npm/[email protected]/dist/N8AO.js",
  "gsap": "https://cdn.jsdelivr.net/npm/[email protected]/index.js",
  "gsap/": "https://cdn.jsdelivr.net/npm/[email protected]/",
  "lenis": "https://cdn.jsdelivr.net/npm/[email protected]/dist/lenis.mjs" }

n8ao importa three/examples/jsm/…, então mantenha essa entrada. postprocessing 6.39 suporta three até r187. Notas do r187: PCFSoftShadowMap foi removido (use PCFShadowMap com shadow.radius); HDRLoader substitui RGBELoader; outputEncoding/sRGBEncoding foram removidos. GSAP 3.13+ inclui SplitText (gsap/SplitText.js).

Referências

Arquivo	Leia quando
references/idea-and-devices.md	passo 3: a frase da ideia, dispositivos, a coisa viva
references/tells.md	passo 3, e novamente antes de relatar
references/assets.md	passo 4: fidelidade, encontrar e colocar adereços, superfícies, orçamento
references/object.md	passo 6: modelos fornecidos (incluindo variantes de cores), a barra para objetos construídos em código, detalhes, materiais
references/colour-world.md	passo 6: paleta para fundo, luzes e materiais; mapeamento de tons; névoa; grão
references/finish.md	passo 6: rigs de luz, o HDRI, sombras de contato e AO, a cadeia de pós-processamento, desempenho
references/scenes-and-motion.md	passo 7: batidas, o vocabulário de planos, viagem da câmera, caminhos, o telefone
references/motion-and-type.md	passo 7: um relógio, easing e durações, revelações, a introdução, escala de tipografia, movimento reduzido
references/chrome.md	passo 7: cabeçalho, índice, rodapé, cursor, marcação, som
references/critique.md	passo 9: a rubrica e o loop de olhar-e-corrigir
references/framing.md, labels.md, legibility.md	corrigir uma descoberta com essa tag
references/example-furkanboran.md	para ver a barra: um site real analisado
library/directions.json	as doze direções que o script distribui

Créditos

As direções distribuídas, a frase da ideia, o teste do concorrente, "uma coisa viva", o loop de olhar-e-corrigir e o aviso de que a moderação sozinha parece vazia são adaptados de taste-skill (MIT). A assinatura e a rotação das direções vêm de hallmark (MIT), o Modo Experiência de impeccable (Apache-2.0) e o vocabulário de arquétipos de awwwards-3d (MIT). Modelos, texturas e HDRIs vêm de Poly Haven (CC0). O exemplo trabalhado e os padrões adaptados dele são de furkanboran.info por Furkan Boran. Veja README.md.