docs: gameplay & mechanics guide with frontend tour

[colinisme]

What

Adds docs/gameplay.md — an authoritative, Chinese-language guide to Gravity Town's gameplay and mechanics. It fills the gap between skill.md (agent-facing system prompt) and docs/arena-guide.md (player-facing Arena cheatsheet): a single doc that explains both gameplay layers and how the key mechanics actually work at the contract level, with every claim cited to file:line.

Contents

• Main world (GameEngine.sol): identity & spawn, the ore economy, buildings, the happiness decay formula and over-expansion penalty, the Tullock combat contest (success = rand < attackPower ⇒ win-chance = attackPower/total), rebellion & comeback, social systems (boards / inbox / debate / chronicle / world bible), scoring.
• Arena (ArenaEngine.sol) — the centerpiece, answering "how does matching work / who triggers it / what are the limits":
  • tier system (_tierFor, thresholds), submit/pool rules, pool cap
  • runMatchmaking is permissionless — anyone can call it; the keeper is just a public off-chain heartbeat (any funded address), not a privileged party
  • Fisher-Yates pairing, per-tier rate-limiting, match locking
  • settlement (settleMatch, also permissionless + idempotent), deterministic combat replay, symmetric-K=32 ELO
  • a "matchmaking limits" summary table
• Frontend tour with screenshots: hex map, agent detail, location board, arena leaderboard/replay, deck/inventory.
• Local-run instructions and an MCP tool-reference pointer.

Two mermaid diagrams (architecture + arena match lifecycle) — both validated to render. README links to the doc from the intro and the Game Mechanics section.

Notes

• Screenshots were captured against a populated local anvil world (buildings, captures, memories, board posts, chronicles, a debate) so each panel shows real content. Images live in docs/images/ (~1.1 MB total).
• Line citations reflect main at the time of writing; if ArenaEngine.sol / GameEngine.sol are refactored, the file:line references should be re-checked.
• Doc is in Chinese to match the audience and docs/arena-guide.md; happy to add an English version if useful.

Test plan

• Mermaid blocks parse without error (validated via mermaid.parse in a headless browser).
• All five image paths resolve under docs/images/.
• Contract line references spot-checked against current main source.
• Reviewer skim for tone/terminology and any mechanic you'd phrase differently.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
gravity-town	Ready	Preview, Comment	Jun 4, 2026 7:42pm