Thinking Goblins

Agent-native tactical forest game prototype.

The current slice focuses on the authored world and authoritative Go runtime:

• maps/goblin-forest-v1/map.ts composes the map from authored regional modules in maps/goblin-forest-v1/regions/.
• A generator builds one canonical map artifact with grid cells plus the agent-facing map output.
• pnpm map:preview renders PixiJS screenshots into labs/map-preview/previews/.
• A React/PixiJS lab renders the generated map.
• /dev/visual-lab replays static and captured render-state clips for cinematic tuning.
• labs/README.md indexes the local design labs and their generated artifacts.
• The Go backend owns the authoritative match runtime.

Run Locally

Build the map package:

pnpm map:build

Render map preview PNGs:

pnpm map:preview

Run formatting, type checks, map DSL tests, and Go tests:

pnpm check

Start the web map lab:

pnpm dev:battlefield

Open:

http://localhost:5173

Visual Lab:

http://localhost:5173/dev/visual-lab

Optional Go server shell:

pnpm dev:server

pnpm dev:server enables development-only routes and pprof with TG_IS_DEVELOPMENT=1. Without that environment variable, the backend does not register /api/dev/* routes or start pprof.

Replay diagnostics:

docs/diagnostic-replay-cli.md

It currently exposes:

GET /api/health
GET /api/maps/goblin-forest-v1
GET /debug/pprof/ on localhost:6060 in development mode

CLI

Show rules:

pnpm --silent cli rules

Show the generated agent map:

pnpm --silent cli map

Map Package

Main package:

maps/goblin-forest-v1/
  map.ts
  regions/
  generated/

Generated preview outputs live under labs/, not inside the map package.

Development Rules

• Author map geometry through the map DSL and regional source modules. Do not manually edit generated map artifacts.
• Map DSL diagnostics are collected and reported as a batch. Preserve that behavior when adding validation.
• Verify map changes with pnpm map:build and the PNGs produced by pnpm map:preview. Use the browser only when testing the interactive frontend, not for ordinary geometry review.
• This is a new project without compatibility obligations. Prefer a clean source-model change over legacy coordinates, migration helpers, compatibility adapters, placeholder tags, or temporary translation layers.
• Every authored tag and field must have a real generator or runtime meaning. Do not add metadata merely to preserve an obsolete representation.
• Keep formatting repository-wide and run pnpm check after structural changes.

Hero Runtime Modules

The Go runtime keeps concrete heroes and shared runtime mechanics in the same runtime package while their contracts are evolving.

• Every concrete hero uses one primary hero_<name>.go file containing its stats, abilities, hero-specific state, calculations, and interaction exceptions.
• Concrete hero tests use the matching hero_<name>_test.go file name. Shared runtime tests keep shared names such as runtime_orders_test.go, interactions_test.go, or support_links_test.go.
• Only concrete hero files use the hero_ prefix. Shared mechanics use names such as registry.go, contracts.go, attacks.go, and movement.go.
• Move logic into a shared helper only when multiple heroes genuinely use the same mechanic. Keep hero-specific behavior in its owning hero file.
• Hero modules own their runtime extension points through heroModule hooks for tick phases, active abilities, and toggles. Shared files should ask the registry for hooks instead of adding new hero-specific switches.
• tick.go should stay an explicit phase order. Put larger phase bodies in semantic files such as tick_heroes.go, orders_objectives.go, or combat_projectiles.go as those areas grow.
• Use typed ids, capabilities, and interfaces internally instead of ad hoc string comparisons.
• Assemble hero modules through one explicit registry. Avoid hidden registration, speculative factories, compatibility adapters, and abstractions that do not remove current duplication.
• Shared interaction contracts own world invariants and confirmed defaults. Unhandled fallbacks must be visible in technical logs and checker output.

Runtime files stay in one Go package but use semantic feature names:

• runtime.go, runtime_api.go, profiles.go, playground.go, and match_runtime.go own process lifecycle, profiles, and public runtime API.
• tick.go owns the phase order only; phase bodies live in files such as tick_heroes.go, tick_support.go, and vision_memory.go.
• movement*.go, airlift.go, orders*.go, abilities_common.go, combat*.go, and views*.go own their feature areas.
• api_types.go contains exported API/view/order shapes. state_types.go contains internal mutable runtime state.

The complete design is documented in docs/archival/hero-runtime-architecture.md.

Layout

• backend/main.go: process startup and shutdown wiring.
• backend/runtime/: authoritative match runtime and hero modules.
• backend/server/: Fiber API.
• maps/: code-driven source and generated map packages.
• tools/mapgen.ts: map generator entrypoint.
• tools/mapgen/: map DSL and output builders.
• tools/cli.ts: agent-facing CLI helpers.
• assets/stickers/source/: original sticker image sources.
• apps/battlefield/: Vite app with the PixiJS map lab.