# Car Town — oficina para navegador

Reconstrução independente do Car Town original do Facebook. Mundo 3D em **Babylon.js**, módulos TypeScript, build Vite e veículos autorais produzidos no Blender e carregados como GLB. **Não é o jogo original recuperado nem uma reprodução completa de todos os seus sistemas.**

## Executar

Na raiz do projeto:

```sh
aube install --frozen-lockfile
aube run dev
```

- **Jogo:** http://127.0.0.1:4173/
- **Laboratório de referências:** http://127.0.0.1:4173/lab.html
- **Cenário determinístico para agentes:** http://127.0.0.1:4173/?debug=1

Encerrar o servidor com `Ctrl+C`. O jogo depende do Vite para os módulos da engine; não usar o antigo servidor Python para executá-lo. Para gerar a distribuição: `aube run build`; para conferir o resultado: `aube run preview` em **http://127.0.0.1:4175/**. Servidores locais vinculados a loopback; publicar somente os arquivos de `dist/`, não o repositório inteiro. É necessário navegador com WebGL 2.

## Jogar

1. Clique em um cliente na rua: ele já chega com um **pedido de serviço**. Escolha uma estação livre e atenda aquele pedido; não é possível trocar o serviço por outro arbitrariamente.
2. O custo é debitado ao iniciar. O carro ocupa a estação até terminar **e ser entregue**, recebendo moedas e XP uma única vez.
3. Evolua os serviços até o nível 3: melhorias aumentam a recompensa e reduzem o prazo. Trabalhos já iniciados mantêm o orçamento original.
4. Amplie a garagem em etapas: **8 × 8, 10 × 10, 12 × 12, 14 × 14 e 16 × 16**, com capacidade para até **10 estações**. Moedas e nível desbloqueiam as etapas.
5. Instale ferramentas, sala de espera e cabine de pintura. As instalações aparecem na cena e têm efeitos reais em velocidade, pagamentos ou serviços disponíveis.
6. Escolha entre **mecânico geral, especialista em estética, borracheiro, autoeletricista, pintor/restaurador e recepcionista**. Atribua profissionais às estações e treine-os; especialistas priorizam sua área e trabalham mais rápido nela. A recepção entrega os trabalhos com a automação ligada.
7. Colecione nove modelos, incluindo conversível, sedã, picape e SUV. Pintura, rodas, organização e rotação continuam disponíveis. Objetivos sucessivos recompensam a progressão.

**Custo de materiais não é preço ao cliente.** Cada pedido mostra o gasto inicial, o pagamento recebido na entrega e o lucro do serviço. Por exemplo, novos pedidos de dados no retrovisor custam 10 em material e pagam 35: lucro de 25 antes de melhorias. Não é um serviço grátis.

Sem saldo? A **Inspeção visual** não consome materiais, mas o cliente paga pela avaliação. Dispense pedidos que não pode pagar para abrir espaço a outros clientes. Contratar e treinar têm custos explícitos, sem cobrança recorrente de salários.

São **24 trabalhos em seis categorias**: estética/cuidados, pneus/direção, mecânica, elétrica, pintura/acabamento e restauração. Há aspiração, vidros, polimento, higienização, alinhamento, balanceamento, suspensão, escapamento, transmissão, bateria, faróis, diagnóstico, ar-condicionado, envelopamento e funilaria, além dos serviços anteriores. Os desbloqueios dependem de nível e instalações. Preços, prazos e efeitos são **balanceamento experimental**, não valores históricos comprovados. Não há compras reais.

## Projetos, carreira e atividades

- **Projetos e peças:** inspecione ofertas de carros usados antes de comprar, escolha fornecedor e grade das peças e recupere carroceria, mecânica, elétrica e acabamento. Cada etapa ocupa uma estação até a coleta; o carro sai de sua vaga e aparece no elevador. A condição altera ferrugem/brilho e desempenho.
- **Orçamento e revenda:** peças usadas/padrão/premium/performance recuperam até 70/84/93/100 de condição. O investimento registra aquisição, inspeção, mão de obra, personalização e o custo efetivamente pago pelas peças consumidas. Descontos e peças gratuitas são considerados; a revenda não garante lucro. Não é possível vender o último carro nem um carro ocupado.
- **Preparação:** motor, câmbio e pneus podem receber três níveis. Potência, aderência e faixa de troca têm efeitos nas arrancadas; a avaliação do carro também pode ultrapassar o teto de uma categoria.
- **Corridas:** quatro eventos, cada um com quatro rivais NPC e tempos de referência publicados. Espere o verde e use os botões ou **Espaço** para largar e trocar as quatro marchas na zona ideal. Reação e trocas influenciam o resultado; largar cedo perde a prova. Repetir uma vitória paga 40% do prêmio. Não são adversários humanos nem multiplayer.
- **Carreira:** sete capítulos e 20 contratos, entre autorais e repetíveis. Aceite antes de executar o trabalho; os objetivos comuns contam ações posteriores à aceitação. Coleções são conquistas finitas e seus objetivos contam o total permanente, inclusive o obtido antes do contrato. Prazos opcionais contam tempo de página visível, não o período fechado.
- **Equipe:** escolha um talento por profissional produtivo: ritmo reduz 10% do prazo, economia reduz 10% do custo, acabamento aumenta em quatro pontos o alvo de condição de projetos, até 100. A primeira escolha é gratuita; retreinar custa 500 moedas e exige estação desocupada.
- **Automação:** em Carreira, defina reserva de caixa, estação reservada para projetos e categoria prioritária. Essas regras restringem a automação, não as ações manuais.
- **Mapa:** cinco rotas usam carga, conforto, capacidade fora de estrada e condição do veículo. Combustível, recompensa e desgaste aparecem antes da partida. O carro fica indisponível até retornar e coletar a viagem.
- **Shows e desafios:** quatro concursos têm pontuação objetiva e visível. Quatro coleções registram conjuntos de vitórias, rotas e exposições; seus prêmios são permanentes e resgatáveis uma vez. Quatro desafios se renovam por rodada.

A **rodada do mercado** renova ofertas e estoque dos fornecedores mediante custo explícito. A **rodada de eventos** é independente: para avançar gratuitamente, conclua e resgate ao menos um desafio da rodada atual. Avançar descarta os desafios parciais e prêmios ainda não resgatados daquela rodada; coleções permanentes são preservadas. Não há exigência de login diário.

O botão de sair da pista preserva a corrida para retomar ou receber o resultado, mas o relógio da prova continua correndo. Restaurações e viagens usam prazo absoluto e aguardam coleta ao voltar; não geram cadeias de renda offline.

## Progresso local

O navegador salva mudanças em `localStorage`, mantendo a chave `car-town-garage-v1`. O conteúdo usa a versão 4; saves válidos das versões 1, 2 e 3 são migrados preservando moedas, coleção, posições, XP, piso, expansão, equipe e trabalhos em andamento. Carros antigos recebem condição íntegra e preparação padrão; as cotações antigas continuam valendo mesmo quando o catálogo muda. Os novos sistemas são validados antes de carregar; não substituem progresso inválido silenciosamente.

Não há conta ou sincronização entre dispositivos. Limpar os dados do site remove o progresso. Se um save não puder ser validado, o conteúdo é preservado e as alterações ficam bloqueadas até a recuperação explícita pelo botão de nova garagem. Falhas de escrita são apresentadas na tela. Se outra aba alterar o save, a aba antiga bloqueia escrita e pede recarga.

A automação inicia pedidos nas estações com mecânico atribuído e entrega trabalhos prontos quando há recepcionista. Ela executa ciclos **enquanto a página está aberta** e retoma ao abrir novamente; não inventa ciclos de renda durante o período fechado. Serviços já iniciados continuam contando pelo horário absoluto. Desativar a automação não cancela esses trabalhos.

## Feedback rápido para agentes

O modo `?debug=1` **não lê nem escreve o progresso normal** e expõe:

```js
carTownDebug.snapshot()         // cópia JSON do estado + relógio/seleção/edição
carTownDebug.reset('default')   // default | occupied | ready | poor | progression
carTownDebug.advanceTime(10000) // avança o relógio usado pela lógica real
carTownDebug.projectEntity('car-1') // coordenadas de tela para clique real no carro
carTownDebug.projectTile(1, 5)     // coordenadas de uma casa do piso
carTownDebug.renderer()           // estatísticas reais da engine e cache de prévias
```

O relógio de debug fica parado até avançar explicitamente, **exceto durante o palco de corrida**, quando acompanha os segundos reais para permitir largada e trocas jogáveis. Normalmente usa-se o tempo real. `applyAction` processa os cliques e `advanceSimulation` executa a mesma automação nos dois modos. A fixture `progression` oferece moedas e XP para testar melhorias pelos controles reais; não compra instalações, funcionários ou conquistas automaticamente. Resetar cancela o palco e seus efeitos. Não há API de debug no modo normal.

O mundo usa ray picking de meshes no canvas `#garage-canvas`; projeções de debug permitem mover o mouse para o objeto e clicar de verdade, sem disparar callbacks artificialmente. Rótulos visíveis e controles nativos preservam operação por teclado. O jogo só habilita interação após carregar os GLBs e preparar a engine. Inspeção de estado e estatísticas não substituem verificar a imagem.

```sh
# TypeScript e distribuição da engine.
aube run build

# Domínio: economia, projetos, corridas, carreira, migrações e conflitos de ocupação.
aube run test

# Com servidor aberto: fluxo real do jogo e persistência em navegador isolado.
python3 tools/game_smoke.py
python3 tools/game_smoke.py --screenshots .artifacts/game

# Expansão: projetos, campanha, corrida por teclado, rotas, shows e novos saves.
python3 tools/expansion_smoke.py --url http://127.0.0.1:4173
python3 tools/expansion_smoke.py --screenshots .artifacts/expansion

# Laboratório: cinco referências, upload, sobreposição, remoção e imagem inválida.
python3 tools/smoke.py
python3 tools/smoke.py --screenshot .artifacts/lab.png
```

Cada smoke usa e fecha uma sessão exclusiva do `agent-browser`; não inicia nem encerra o servidor. O smoke do jogo verifica cliques reais, foco por teclado, fixtures e tempo real com recarga, além de uma segunda aba limpando o storage, bloqueio de sobrescrita e recuperação explícita de conteúdo corrompido. `.artifacts/` é saída local ignorada. Screenshots registram aparência; o teste não atribui nota automática de fidelidade.

Para exploração manual:

```sh
agent-browser --help
agent-browser skills get core
SESSION="$(agent-browser session id --scope worktree --prefix car-town)"
agent-browser --session "$SESSION" open 'http://127.0.0.1:4173/?debug=1'
agent-browser --session "$SESSION" snapshot -i
# Interagir com os controles ou com o canvas usando as coordenadas projetadas.
agent-browser --session "$SESSION" eval 'carTownDebug.snapshot()'
agent-browser --session "$SESSION" errors
agent-browser --session "$SESSION" close
```

## Estrutura e referências

- `game/catalogs.mjs`: catálogo, balanceamento, requisitos e efeitos derivados das melhorias.
- `game/model.mjs`: transações, pedidos, equipe, automação e migração/validação de saves; sem DOM ou storage.
- `game/world.ts`: cena Babylon, câmera, iluminação, seleção, recursos GPU e prévias reais dos modelos.
- `game/improvements.ts`: geometria das instalações funcionais; a cena controla sua vida útil.
- `game/projects.mjs`: mercado, peças e base de custo, condição, restauração, preparação e revenda.
- `game/activities.mjs`: simulação das arrancadas, viagens, concursos, coleções e desafios.
- `game/career.mjs`: contratos, capítulos, reputação, talentos e políticas.
- `game/layout.mjs`: posicionamento compartilhado por compras e estações.
- `game/race-view.ts`: pista 3D na engine existente, sem criar outro contexto WebGL.
- `game/journey-ui.mjs`: telas da expansão e controles/telemetria da corrida.
- `game/view-types.ts`: contrato tipado entre estado/interface e renderizador.
- `assets/vehicles/`: fonte editável e geração dos carros no Blender.
- `public/assets/cars/`: GLBs usados pela engine, separados das referências históricas.
- `game/app.mjs`: interface, seleção, relógio, persistência e ferramentas de debug.
- `game/game.css`: HUD, janelas, controles e layout responsivo.
- `lab.html`, `lab.js`, `lab.css`: comparação de captura local por opacidade; sem envio de imagens.
- [Investigação e procedência](docs/research.md), [pipeline](docs/pipeline.md) e [instruções para agentes](AGENTS.md).

As cinco imagens em `references/images/` são material de pesquisa do TechTudo e do guia oficial arquivado. **Não são carregadas como arte do jogo.** O Car Down indicado pelo usuário também é referência, não fonte de assets importados. A procedência e as diferenças conhecidas estão na investigação.

Ainda não implementados: contratação de amigos reais, multiplayer, cidade aberta dirigível, adesivos/templates, áudio ou backend. O mercado de projetos usa ofertas fixas por rodada, não um leilão com lances. As novas atividades são uma adaptação autoral inspirada nas fontes, não uma recuperação integral dos sistemas históricos. Não há alegação de fidelidade pixel a pixel.

## Blender e ferramentas do agente

O Blender foi instalado pelo Homebrew (`brew install --cask blender`) e está disponível como `blender`. A ferramenta adicional aprovada é `blender-ctl`, em `~/.agents/bin`, executando `blender-cli` 0.8.1 fixo em `~/.agents/tools/blender-cli`; ela não faz parte do bundle do jogo.

```sh
blender-ctl --help
blender-ctl doctor
blender-ctl scene --blend assets/vehicles/vehicles.blend
blender-ctl snapshot --blend assets/vehicles/vehicles.blend --out .artifacts/vehicles-views.png
```

Foram exercitados abertura, importação, inspeção JSON, quatro vistas e exportação GLB com releitura no Blender 5.3. A ferramenta declara matriz de testes 4.3/5.2; outros comandos precisam de verificação própria. Não foram instalados add-ons, servidores ou instruções de agentes automaticamente. Scripts têm acesso local; o modo safe não é sandbox garantida.

Para reconstruir a arte procedural e gerar uma vista de avaliação:

```sh
# Substitui vehicles.blend e os nove GLBs; não usar sobre edições humanas.
blender-ctl run assets/vehicles/build.py
CAR_BUILD_MODE=preview CAR_BUILD_PREVIEW=coupe \
  blender-ctl run assets/vehicles/build.py --blend assets/vehicles/vehicles.blend
```

A imagem de avaliação sai em `.artifacts/vehicle-coupe.png`. O render do Blender ajuda a revisar formas; a aprovação final deve ocorrer na câmera e nos materiais do navegador.

Conservar os `.blend` para edição humana. A geração pode substituir arquivos exportados: não regenerar por cima de alterações humanas sem verificar. Exportações para o jogo devem preservar geometria, nomes dos materiais de pintura/rodas, eixos, escala e pivô de contato com o piso. Ver o contrato de arte na pipeline.
