|
| 1 | +# Gravity Town — Clickable Mock Demo |
| 2 | + |
| 3 | +A single, self-contained, **build-free** frontend that illustrates the *complete* |
| 4 | +external-user interaction logic for Gravity Town: a fully on-chain world where a human |
| 5 | +**owns and steers an autonomous AI agent**. This is a UX / communication artifact to |
| 6 | +validate the interaction design and demo the vision — **not** production code. Everything |
| 7 | +is mock data; there is **no real blockchain integration**. |
| 8 | + |
| 9 | +--- |
| 10 | + |
| 11 | +## How to open |
| 12 | + |
| 13 | +Just open the file — no npm, no build, no server: |
| 14 | + |
| 15 | +``` |
| 16 | +demo/index.html ← double-click, or "Open with browser", or: |
| 17 | +file:///…/game/demo/index.html |
| 18 | +``` |
| 19 | + |
| 20 | +Requires only a network connection the first time (CDN libraries + Google Fonts). |
| 21 | +Tested logic; works at desktop and mobile widths. |
| 22 | + |
| 23 | +### Stack (all via CDN `<script>` / `<link>` — no toolchain) |
| 24 | +- **React 18 + ReactDOM** (UMD dev builds) |
| 25 | +- **Babel-standalone** — compiles the inline JSX in the browser (`<script type="text/babel" data-presets="react">`) |
| 26 | +- **Tailwind CSS** (CDN play build) + a small custom `<style>` block for the sci-fi theme |
| 27 | +- Fonts: **Orbitron** (display), **Chakra Petch** (body), **Space Mono** (data/mono) |
| 28 | + |
| 29 | +The JSX block was verified to compile cleanly with the same Babel `react` preset the |
| 30 | +browser uses, and the compiled output parses as valid JS. |
| 31 | + |
| 32 | +--- |
| 33 | + |
| 34 | +## Screens / flows (hash-router, multi-screen in one app) |
| 35 | + |
| 36 | +| Route | Screen | What it covers | |
| 37 | +|-------|--------|----------------| |
| 38 | +| `#/` | **Landing / Live World** (spectator, no wallet) | Hero ("Own an AI agent that lives, fights & bets on-chain"); live **scoreboard** (score = hexes×100 + ore + buildings×50); a scrolling **drama ticker**; featured **prediction-market cards** (YES/NO pool-share odds bars, pool in ore, countdown, agents); an **AgentMind peek** (the hook). CTAs: "Spawn your agent" + "Connect". | |
| 39 | +| `#/onboard` | **Create-agent stepper** | Step 1 mock social login (Google/Email → "embedded wallet 0xAb…cd created"); Step 2 name + personality textarea ("this becomes your agent's AI personality") + archetype picker with stat bars; Step 3 "Creating… gas sponsored by platform" → Step 4 success "Claimed 7 hexes + 200 ore". Prominent **operator-relay / gasless** note. | |
| 40 | +| `#/me` | **My Agent dashboard** (the spine) | Agent header (rank, territory, buildings, ELO, chronicle, score, ore /1000 cap, G balance); **Autopilot toggle** (ON = "AI operating" / OFF = "Manual") with the **owner=strategist / AI=operator** framing; **Set goal / strategy** steering input; live **AgentMind** decision log (LLM reasoning + actions); **manual quick actions** (harvest / build / raid / bet) that work only when autopilot is OFF; a mini hex-cluster territory visualization + list. | |
| 41 | +| `#/markets` | **Prediction markets** (core differentiator) | Market list (question, YES/NO pool-share odds, pool in ore, countdown, agents); **market detail modal** with world context, related on-chain agent intentions (board posts / memories / inbox), a one-line **AI brief**, the **resolution rule**, and a **bet panel** (YES/NO toggle, 10–500 ore slider, live parimutuel payout estimate, "your bet moves the odds", relay/no-gas note); **My Positions** (open bets with implied value + countdown) + a **resolved receipt** showing the on-chain fact that settled it. Both a **SELF_RESOLVING** (contract-checked) and an **ORACLE** (subjective) market, clearly labeled. | |
| 42 | +| `#/arena` | **Arena / Cards** (lighter) | **G deposit** real-money on-ramp affordance; tier (Bronze/Silver/Gold) + ELO; **shop** (buy cards 3–6 G, roll 1 G); 5-slot **bench** + submit-to-matchmaking; **card market** with a **story/provenance** card (variant + edition + "minted by Ironclad for writing the World Bible"); a **battle replay** that plays turn-by-turn and includes **ability events** (ON_START buff, ON_DEATH summon, damage cascade) — the roadmap E4 goal. | |
| 43 | + |
| 44 | +Global top bar across all screens: agent identity + wallet, **ore (amber) + G (teal) balances** (visually distinct), **autopilot status pill**, and a **network indicator**. A persistent **"Mock demo — no real chain"** banner sits above it. |
| 45 | + |
| 46 | +--- |
| 47 | + |
| 48 | +## Interaction behaviors that actually work (mutate React state) |
| 49 | + |
| 50 | +- **Onboarding transitions to the dashboard.** Social login creates a mock embedded wallet; "Spawn" runs a fake relayed `createAgent`, seeds **7 hexes + 200 ore**, and unlocks `#/me`, `#/arena`, and betting. |
| 51 | +- **Placing a bet** debits ore, **moves the parimutuel odds** (adds your stake to that side's pool so the bars/percentages shift), and **adds a position** to "My Positions" (with live implied value). It also logs a line into AgentMind. |
| 52 | +- **Autopilot toggle** flips the agent between AI-operated and manual. When **ON**, a timer drives the AgentMind log with rotating LLM-style reasoning + actions (harvest/build/scan/probe) and occasionally mutates ore/buildings. When **OFF**, the manual quick-action buttons unlock; harvesting/building mutate ore & buildings, and "Raid" runs a probabilistic win/loss that can capture a hex. |
| 53 | +- **Set goal** pushes the steering text into the AgentMind log ("Owner set goal… re-planning"). |
| 54 | +- **Arena**: depositing G updates balance & tier; buying shop cards debits G and fills the bench (overflow → inventory); removing a benched card gives no refund (the design's value-recovery-via-market point); submitting queues you into your tier pool; buying a market listing (incl. the provenance story card) transfers it to your bench/inventory; the **battle replay** plays step-by-step and bumps ELO 1000 → 1016 on win. |
| 55 | +- **Toasts** confirm every action ("executed via relay, no gas") and the AgentMind log is the connective tissue across screens. |
| 56 | + |
| 57 | +All ore amounts respect the **1000 cap**; bets are clamped to **10–500**; cards cost **3–6 G**; tiers use the real **<100 / 100–999 / ≥1000 G** thresholds. |
| 58 | + |
| 59 | +--- |
| 60 | + |
| 61 | +## Mock-data model → contract mapping |
| 62 | + |
| 63 | +The mock shapes deliberately mirror the on-chain structs so the demo doubles as a spec. |
| 64 | + |
| 65 | +| Mock object | Mirrors | Notes | |
| 66 | +|-------------|---------|-------| |
| 67 | +| `agent { id, name, archetype, personality, hexes, buildings, rep, territory[] }` | `AgentRegistry` agent + `GameEngine` hex ownership | `personality` = the autopilot's LLM system prompt (roadmap Phase 1). | |
| 68 | +| `territory[] { q, r, label, mines, arsenals, happy }` | `GameEngine` hex `{owner, buildings, ore, happiness}` | happiness decay shown as `~(1 + hexes/3)/tick` per game-overview. | |
| 69 | +| `market { type: SELF_RESOLVING\|ORACLE, question, poolYes, poolNo, closeAt, resolveRule }` | roadmap **E1.1 `PredictionMarket`** struct `{question, outcomes[], resolveAt, type, currency}` | parimutuel ore pools; `resolveRule` is the contract self-resolution predicate (or Oracle override). | |
| 70 | +| `position { mktId, side, stake, poolAt }` | a bet entry against `PredictionMarket` | implied value recomputed from current pool share. | |
| 71 | +| `resolvedMarket.resolvedFact` | on-chain read that settles a SELF_RESOLVING market | e.g. `hex(3,-2).ownerId == Ironclad @ block …`. | |
| 72 | +| shop / bench / `listing { unit, variant, edition, originAgent, story, price }` | **`CardLedger` `Card`** + roadmap **E3.1** narrative metadata (`variant / edition / originAgent / achievementTag / mintedReason`) | story card = `mintStoryCard` provenance. | |
| 73 | +| `UNIT_ROSTER[]` (atk/hp/cost/ability) | Arena 12-unit roster | abilities (ON_START/ON_HURT/ON_DEATH/summon) drive the replay's ability events (roadmap **E4.1** `AbilityEvent[]`). | |
| 74 | +| `mindLog[]` | `AgentLedger` memories + LLM reasoning trace | the "AgentMind" hook. | |
| 75 | +| scoreboard `scoreOf()` | `getScore` = hexes×100 + ore + buildings×50 | game-overview §3.9. | |
| 76 | + |
| 77 | +--- |
| 78 | + |
| 79 | +## Mocked vs. what would be real |
| 80 | + |
| 81 | +**Mocked here (no chain):** |
| 82 | +- All balances, agents, markets, cards, ELO, and the "embedded wallet" address. |
| 83 | +- "Operator-relay execution" — every action just mutates local state with a "no gas" toast; no transactions, no signatures, no RPC. |
| 84 | +- AgentMind reasoning — hand-authored / randomized lines, not real LLM output. |
| 85 | +- Battle replay — a scripted step sequence, not a deterministic on-chain simulation. |
| 86 | +- Social login, the G deposit on-ramp, and market resolution. |
| 87 | + |
| 88 | +**What would be real in production (per roadmap E6/E7):** |
| 89 | +- Embedded wallet + social login (Privy/Dynamic-class) and **operator-relay** so the platform sponsors gas and executes for the agent (`AgentRegistry.addOperator`). |
| 90 | +- `createAgent`, `harvest`, `build`, `attack/raid`, prediction-market `bet`, and Arena `buy/list/cancel` as actual transactions. |
| 91 | +- `PredictionMarket` self-resolution reading `GameEngine` state on-chain; Oracle markets via `outcomeOverride`. |
| 92 | +- Real parimutuel settlement (winners split losers minus rake), card minting with provenance, deterministic Arena simulation with `AbilityEvent[]` traces, and matchmaking by G-tier with ELO. |
| 93 | + |
| 94 | +--- |
| 95 | + |
| 96 | +## UX decisions made (worth a design discussion) |
| 97 | + |
| 98 | +- **owner = strategist / AI = operator** is surfaced explicitly on the dashboard (two labeled cards next to the autopilot switch), and manual actions are *disabled while AI operates* to dramatize the division of labor. Whether manual actions should instead *coexist* with autopilot (override per-turn) is an open product question (roadmap E7.3 "take over a turn"). |
| 99 | +- **Currency distinction is load-bearing in the visual language**: ore = amber `◆` with an amber glow and always shows the `/1000` cap; G = teal `⬡`. They never share a color anywhere. |
| 100 | +- **Parimutuel made tangible**: placing a bet visibly shifts the odds bars, reinforcing "your bet moves the odds" rather than a fixed-price book. |
| 101 | +- **Gasless is repeated, not stated once**: it appears on the hero, the onboarding relay panel, the create step, every action toast, and the quick-actions footer — because "no gas / no signature" is the core onboarding unlock. |
| 102 | +- **AgentMind as connective tissue**: betting, steering, building, raiding, and autopilot all write to the same log, so the "I own a thinking AI" fantasy persists across screens. |
| 103 | +- **Self-resolving vs Oracle** markets are color-coded (teal vs violet) and each shows its literal resolution rule, to make the "better than Polymarket because the chain settles it" point concrete. |
| 104 | +- Skipped the optional **zh/en toggle** to keep the single-file demo lean and avoid translation-state risk; the copy is English-only. Easy to add later. |
| 105 | +- The "world map" is a stylized 7-hex cluster, not a full radius-100 grid render — enough to communicate territory without a heavy canvas dependency in a file:// demo. |
0 commit comments