Gristmill — Design Spec

Data: 2026-07-20 (rev 2026-07-21: controle híbrido com avatar) · Status: em implementação
Repo: github.com/kodama1/gristmill (privado) · Local: C:\Users\User\gristmill

Visão

Colony sim coop (2-8 amigos) no browser, estilo visual GoGo Town (low-poly fofo, pastel saturado), tema medieval/fantasia. Mundo persistente e cruel 24/7 — invernos e raids acontecem mesmo offline. Diferencial: todo colono é um visitante gerado por IA, com nome, lore, traços únicos e quest de recrutamento contextual à cidade. Produto monetizável (v2: premium = expansão + cosméticos, zero pay-to-win).

Controle (GoGo Town-like, híbrido)

Cada jogador tem um avatar que anda pela cidade com WASD (câmera segue), coleta recursos dos nodes do mapa (árvores→madeira, pedras→pedra; tecla E, validação de proximidade no server, nodes esgotam e respawnam) e constrói apontando no grid. Avatar é client-driven com clamp de velocidade no server (anti-teleport); colonos NPC são server-driven.

Arquitetura

• Server autoritativo — Bun + Elysia + WebSocket no VPS Hermes. Client (Vite + three.js + React) envia intents (place_building, move, harvest, assign_job), recebe snapshot/deltas/events.
• Room = colônia em memória, tick 3/s com gente online; snapshot jsonb no Postgres (Drizzle) a cada 2min; unload após 5min vazia.
• Simulação determinística (RNG seedado + tick fixo) → catch-up offline: simulateOffline(state, elapsedTicks) fast-forward ao carregar. "Roda 24/7" sem CPU 24/7.
• Monorepo: apps/web, apps/server, packages/shared (tipos, protocolo, balance).

Visual

• Low-poly flat-shaded, paleta pastel própria. Assets CC0 glTF: Kenney Fantasy Town Kit, Quaternius Medieval Village MegaKit, personagens chibi KayKit/Quaternius (animados).
• Blender MCP só pra recolorir paleta e modelar gaps.
• three.js: MeshToon/flat lambert, InstancedMesh, sombras soft. Mapa grid 64×64.

Gameplay

• Recursos: nodes no mapa (madeira/pedra via avatar) + T2 processado em prédios (serraria madeira→tábua, padaria comida→pão) → T3 v2 + ouro v2.
• Loop: coletar → construir → recrutar visitantes → colonos NPC automatizam → otimizar → defender → XP desbloqueia.
• Inverno cíclico (~3 dias reais): sem estoque, colonos famintos ficam lentos e vão embora (nunca morrem/game over).
• Raids goblins agendadas, visíveis com antecedência → notificação Discord → defende ao vivo ou auto-battle determinístico.
• Coop: colônia compartilhada; quests da colônia; anti-grief v1 = log + só fundador demole em massa/expulsa.

Visitantes AI (único caminho pra colonos novos)

• Chegadas agendadas (pacing), espera 24h reais na taverna, fila pré-gerada (buffer 2-3).
• Claude Haiku, structured output, server-side. Input = resumo da cidade → lore + quest contextuais.
• IA gera flavor + parâmetros, nunca mecânica: quest type de catálogo (deliver | build | stockpile | survive_raid | population), quantidades min/max por etapa, appearance só assets existentes, traits de catálogo. Validação reprova → regenera.
• Server verifica quest por tick → recruta. ~centavos/colônia/dia.

Dados (Postgres/Drizzle)

users (better-auth) · colonies (seed, last_sim_at, state jsonb+version) · colony_members · colony_events · scheduled_raids (cron → Discord) · visitor_queue.

Status implementação (2026-07-21)

• ✅ Monorepo + shared (tipos/protocolo/balance) + sim determinística (5 golden tests) + rooms WS + client three.js (avatar WASD, coleta E, nodes com respawn, ghost de construção, colonos NPC interpolados, HUD)
• ⏳ Próximo: persistência Postgres + catch-up → visitantes AI → inverno/raids → assets → auth → deploy

MVP

Auth + convite por link · grid 64×64 com 8 prédios + estradas · avatar WASD + coleta · visitantes AI (deliver/build, job_bonus) · T1+T2 + inverno + 1 raid com auto-battle · persistência + catch-up + coop 2-8 · Discord.
Fora: T3, esteiras/carroças, ouro/caravanas, monetização, skins, quirks, mobile.