# OWNTOWN — Complete Game Audit (code-grounded)

> This page describes OWNTOWN **exactly as it is implemented in the codebase** — no planned
> features, no marketing. Where the code does not prove something, it is marked
> *"not confirmed from code."* Last reviewed: 2026-06-18 (**Economy V2 — dual currency $OTWN + Candy 🍬**).

**TL;DR for a new player:** Connect Phantom (you need ≥ 5,000 $OTWN to play, or watch as a
spectator), make your character, talk to Mira at the plaza, **mine at Deepworks and fish at
Stillwater** to fill your bag with ore/fish (and XP), **sell that loot to a vendor for $OTWN**.
Now there are **two currencies**: **$OTWN** is the hard money you earn and carry home to your
wallet; **🍬 Candy** is what the city *spends* — every shop, repair, forge, home and tower is priced
in Candy. You get Candy **only one way**: **stake $OTWN at the Candy Factory** (next to the casino)
and it slowly mints Candy from a fixed, shrinking daily pool; trade spare Candy for $OTWN on the
**Candy Market** (live candlestick chart, DexScreener USD prices). **World Boss** and **PvP arena**
are the high-end $OTWN sources; the **bank** cashes $OTWN back to your wallet. You level up to
survive tougher zones, ride vehicles (L10), mine better and forge stronger gear — there is no quest
system beyond the beginner guide.

---

## 1. Overview

OWNTOWN is a **real-time, multiplayer, 3D browser game** (Three.js client + Node/Socket.IO server
+ SQLite) set in a coastal city, Pacifica Bay. It is **gated by a Solana token ($OTWN)**: to play
(not just watch) your wallet must hold a minimum balance. Players walk a shared city, **gather
resources (mining, fishing), fight monsters, trade with other players, craft/buy gear, own
property, and move $OTWN in and out of their real wallet.** All rewards are server-authoritative.

## 1b. Economy V2 — Two Currencies ($OTWN + Candy 🍬)

OWNTOWN runs on **two currencies**, with one hard rule: **SELL → $OTWN, BUY → Candy.**

- **$OTWN** — the on-chain hard money. Earned by **selling loot to vendors** (fish, ore, monster
  loot), plus World Boss / PvP rewards. Withdrawable to your real wallet. Used for: **staking**,
  **Candy Market settlement**, and the bank.
- **🍬 Candy** — an **internal, off-chain** currency. **Whole/0.1-granular** (never finer in the
  game; sub-0.1 is burned). **Zero fees everywhere except one** (the claim fee, below). Candy is
  the **only** thing shops/forge/repairs/homes/towers accept. Its logo is a **lollipop**.

**Candy is minted ONLY by staking** — never from mining, fishing, loot, quests, or gameplay.

### The Candy Factory (staking) — beside the casino
- Stake $OTWN → it’s locked into an internal pool and you earn Candy by **weight share** of a
  global daily pool: `your share = pool × (your stake / total staked)`.
- **Emission:** **300 Candy/day** at genesis, **−1%/day** (`300 × 0.99^dayN`, server-time only).
- **Claim:** 0.1-granular, **minimum 0.1**, **60-second cooldown**; a **5% claim fee** goes to the
  city Treasury (floored to 0.1, so claims under 2.0 are effectively fee-free); the sub-0.1
  remainder is **burned** and accounted. Supply invariant: `minted = credited + treasury + burned`.
- **Unstake:** each stake is **locked 12h**; unstaking charges a **2% $OTWN fee** to the Treasury
  (98% returned). All server-enforced; a clean adapter layer lets real on-chain staking slot in
  later without a rewrite.

### The Candy Market (CANDY / $OTWN order book)
- A real **limit-order book**: place bids (lock $OTWN) / asks (lock Candy), price-time matching,
  partial fills, **zero fee both sides**, cancel refunds the escrow. **Self-trading blocked.**
- **Live candlestick chart** — fixed **1-hour OHLC candles**, auto-rolls each hour, times shown in
  the viewer’s local zone (buckets are UTC). Built from real trades only; empty state otherwise.
- **USD pricing** via **DexScreener** (hourly): shows `1 $OTWN ≈ $x` and derives `1 Candy ≈
  lastTradePrice($OTWN) × otwnUsd`. Surfaced on the Hub’s “Candy Market Pulse” too.
- Every functional action (Place Bid / Place Ask / Cancel, and stake/unstake/claim) goes through an
  in-game **confirmation modal** — no native browser popups.

### What changed from V1
- **All buying** (gear, forge, craft, food, clinic heal, repair, boutique, vehicles, property) is
  now **Candy**. The **player marketplace** is **Candy, zero-fee** (old 2%/7% fees removed).
- **Property = a tradable Deed item.** Buying a **home (Palm Grove)** *or* a **Skyvault tower**
  with Candy grants a `Deed` key in your inventory; sell the Deed on the marketplace to transfer
  ownership. Skyvault tower owners also collect **90% of billboard ad revenue**.
- **Billboard ads** are paid in **Candy** now (USDC dropped); split **90% tower owner / 10%
  treasury**.
- **CHIP (casino currency) retired** — balances auto-refunded to $OTWN; the **casino is closed**
  for an upgrade (will return Candy-based).

## 2. New Player First Steps

1. **Login** — landing page shows **"Connect Phantom Wallet"**, **"Tour the City as Spectator"**
   (guest, no wallet), and on localhost a **dev wallet** button.
2. **Authenticate** — Connect Phantom → server challenge → you sign it in Phantom → the server
   verifies the signature **and** your on-chain $OTWN balance. Pass = "player"; insufficient =
   "guest" (spectator).
3. **Create your citizen** — onboarding modal **"CREATE YOUR CITIZEN"**: display name (3–20
   chars), skin tone, hair, face, optional "OTWN Cap," fixed starter outfit.
4. **Spawn + meet the guide** — you spawn at **Sunrise Plaza**. **Mira** (guide NPC) is right
   there calling *"New in town? Press E — I'll show you around!"* A beginner guide auto-opens
   ~2.5s after first join.
5. **First activity** — walk east to **Deepworks Cliff and mine** with your starter Pulse Pick,
   then sell the ore.

## 3. Starting Mission / Early Objective

There is **no quest/objective system** (no tracked goals, rewards, or completion). The only
"mission" is the **tutorial guide** (Mira's modal). Its exact "FIRST STEPS — DO THESE TODAY":

1. *Mine at Deepworks Cliff — your Pulse Pick is already in your inventory.*
2. *Fish at Stillwater Pond — relaxing $OTWN, and the only place legendary pets drop.*
3. *Sell your ore & fish: quick-sell from the inventory, or list them on the Market Pier.*
4. *Reach level 5+, gear up, then hunt monsters in the Redline Zone for bigger drops.*

## 4. Core Gameplay Loop

```
gather (mine / fish / fight)  →  items + XP
        ↓
sell loot to a vendor  →  $OTWN   (the hard money)
        ↓
stake $OTWN at the Candy Factory  →  🍬 Candy   (the only way Candy is minted)
        ↓
spend Candy: gear, forge, food, clinic, repairs, crafting, cosmetics, vehicles, property
   …or trade Candy ⇄ $OTWN on the Candy Market (live chart)
        ↓
level up + better gear  →  fight monsters for rare drops & gear
        ↓
endgame: World Boss (timed) + PvP arena (weekly $OTWN pool)
        ↓
cash out $OTWN to your wallet (bank withdraw)
```

## 5. XP and Leveling

- **Earn XP from:** mining, fishing (~half of mining), killing monsters. **World Boss and PvP do
  not grant XP** (not confirmed from code).
- **Curve:** `xpRequired(L) = floor(100·L^1.65 + 50·L)`, cumulative; **max level 100**.
- **Leveling changes stats:** maxHealth +4/level, maxStamina +2/level, strength +0.8, defense
  +0.5, miningEfficiency +1 per 10 levels, craftingSkill +1 per 8, luck (capped 25), carry
  capacity +2/level. Level-up refills health/stamina.
- **Unlocks:** **vehicles require level 10**; the guide gates monster-hunting at "level 5+"; some
  monsters have level requirements. Most zones are `minLevel 1`, so leveling matters more for
  **combat survivability, vehicle access, mining efficiency and forge odds** than for unlocking
  areas.

## 6. Map / World Areas (16 zones, two maps)

- **Sunrise Plaza** — spawn, meet Mira.
- **Market Pier** — player marketplace + boutique (cosmetics).
- **Skyvault Coastal Towers** — billboard ad towers.
- **MedBay Clinic** — heal HP for $OTWN.
- **Volta Food Row** — buy food.
- **Marina Garage** — buy vehicles (L10+).
- **Palm Grove Residences** — buy/sell homes (6 properties).
- **Stillwater Pond** — fishing (5 spots); only place pets drop.
- **Candy Factory** — beside the casino (west of the bay); stake $OTWN → mint Candy + open the Candy Market.
- **Lucky Reef Casino** — currently closed for an upgrade.
- **Beach Cafe / Civic Green / Boulevard / Sunrise Beach** — ambient areas (5 decorative NPCs at
  the cafe).
- **Deepworks Cliff Mine** — mining (8 nodes).
- **Redline Zone A-7** — danger PvE; monsters.
- **Verdant Hollow** — danger PvE "leveling forest," reached via a portal.
- **Tidebreak Arena** — PvP.
- **Worldboss (Rift)** — separate instance for the World Boss.

## 7. Resources and Activities

| Activity | Where | You receive | XP? | $OTWN direct? |
|---|---|---|---|---|
| **Mining** | Deepworks Cliff | Ore (resonite, iron, circuit scrap, rare cores) | ✅ | ❌ (sell it) |
| **Fishing** | Stillwater Pond | Fish + ultra-rare **legendary pets** | ✅ | ❌ (sell it) |
| **Combat (PvE)** | Redline / Verdant Hollow | Item drops + **tiered gear (T4–T6)**; pet XP | ✅ | ❌ |

**Important:** mining/fishing/PvE write item ledger rows (`amount:0, currency:'ITEM'`). They give
**items + XP, not coins** — you earn $OTWN by **selling** those items. Mining has a daily soft-cap
fatigue multiplier that lowers XP and rare-drop odds for grinders.

## 8. Inventory and Items

- Stored per-player as item instances (durability, pet XP, owned/locked status).
- **13 categories:** material, weapon, tool, food, medical, cosmetic, armor, vehicle, pet, mount,
  vehicle_part, permit, repair_kit. ~78 base items + 32 gear + vehicles.
- In the **Inventory panel (I)** you can equip, use/consume, repair, quick-sell, sell-all loot,
  list on market, or craft.
- **Starter inventory:** Pulse Pick, driftwood baton, volt noodles, coastal tee, palm sneakers,
  level 1. **Starter $OTWN grant = 0** in production (new players earn by selling loot); a staging
  env can fund test players.

## 9. Gear / Equipment

- **Slots:** outfit, shoes, accessory, weapon, tool, head, chest, legs, feet, pet, mount.
- **Tiers T1–T6** (Common → Mythic). T1–T3 buyable; **T4–T6 from drops, the forge, or event
  shops**.
- **Only head/chest/legs/feet/weapon/accessory grant stats.** Cosmetics and tools/mounts give no
  stats. Bonuses: hp, stamina, attack, defense, mining, crafting, luck, speed. **Speed capped at
  +30%, luck at +20.**
- **Forge:** craft T4+ gear with a success chance scaling from tier + crafting skill + level +
  equipped pet level; failure burns half materials + the fee.

## 10. Pets

- **Exactly 3 pets:** Golden Whale, Sea Dragon, Demon Salamander — all legendary, **tradable**,
  dropped **ultra-rarely from fishing**.
- **Functional, not cosmetic:** an equipped pet **levels from your kills** (max L30) and gives a
  **forge-success bonus of +1.5 percentage points per level** (up to +43.5pp).

## 11. Marketplace / Trading / Selling

- **Player marketplace (Candy, ZERO fee):** list (item escrowed, no listing fee), buy (buyer pays
  the full Candy price, seller receives 100% — no tx fee), cancel. Prices are 0.1-granular Candy.
  An in-game **List modal** (qty + price + live total) and a **buy/confirm modal** replace the old
  native prompts.
- **NPC quick-sell / sell-all:** instant sell of loot to the system **for $OTWN** at base value;
  **subject to the daily earn cap** (items over the cap are kept, not lost). This is the SELL→$OTWN
  side of the economy.
- **Property = tradable Deed:** buying a home or tower grants a `Deed` item; **resell by listing the
  Deed on the marketplace** (Candy, zero fee) — buying it transfers ownership server-side. (Old
  list/unlist/resale-fee flow removed.)
- Trade currency is **Candy**; loot→vendor is **$OTWN**. Vehicles are owner-bound / non-tradable;
  the **Abyssal Dragon mount is tradable**; property **Deeds are tradable**.

## 12. Wallet / Access / Player Mode

- **Auth:** Solana ed25519 challenge → sign → verify, then a **JWT session (12h)**.
- **Token gate:** wallet must hold **≥ 5,000 $OTWN** (default), checked at login, **re-checked on
  every connect**, and **swept every 10 min in production**.
- **Spectator/guest:** no wallet needed — can **watch the world, read chat, view the
  marketplace, follow a player** — but **cannot mine, fight, fish, trade, or chat.** Block
  message: *"Spectators cannot do that — hold 5,000 $OTWN to play."*
- **Banking (non-custodial):** deposit by sending $OTWN on-chain and pasting the tx signature
  (RPC-verified). Withdraw with a minimum + per-day cap + fee; fresh deposits and marketplace
  proceeds have a cooldown; **the starter grant can never be withdrawn**. Payouts are admin-
  approved or auto-paid from a hot wallet with an hourly cap and kill-switch.

## 13. Combat / Enemies / Risk

- **Monsters** spawn with HP and respawn timers. Attacking costs stamina; weapon durability drops
  per hit. Damage = `(strength·1.5 + weapon + gearAttack + rng·4) × buffMult`.
- **Monster types:** forest_minor/major/boss, stray, brute, warden — each with tiered drop
  tables.
- Monsters fight back; at 0 HP you **respawn at the plaza at 50% health**. No item/$OTWN loss on
  death is confirmed in code.
- **World Boss** — "Abyssal Tidewyrm," spawns on a ~12h schedule in its own arena, with
  telegraphed abilities (Abyss Slam, Dark Wave, Defensive Shell, enrage < 30% HP) and a Witch
  revive. **Rewards are damage-ranked:** rank 1 gets mats + tokens + **500 $OTWN** + the unique
  **Abyssal Dragon mount** (first daily claim); lower ranks get chests/mats/tokens/$OTWN.
- **PvP** — queue-based 1v1 in Tidebreak Arena; loser returns to plaza at half HP; **weekly points
  → top 50 split a weekly $OTWN pool**, claimable once per completed week. No item drops.

## 14. Chat / Social / Multiplayer

- Live multiplayer: you see other players' positions, equipment and movement.
- **Chat panel:** World (global, rate-limited, @mentions, staff ✦), Whispers (DMs, `/w name
  msg`), Friends (add/accept/decline/remove, online status, `/friend name`).
- **Emotes:** Dance / Laugh / Sleep. **Notifications:** mentions, market sales, friend requests.

## 15. Mobile and Desktop Controls

- **Desktop:** WASD/arrows move, Shift sprint, Space jump, E interact, F attack; left-drag orbit,
  scroll zoom, click map to auto-walk. Panels: I inventory, C character, M minimap, Enter chat,
  Esc close.
- **Mobile:** left-side virtual joystick; right-side buttons ACT / JUMP / RUN (RUN becomes
  MOUNT/DISMOUNT when a mount is equipped); right-half drag orbits; pinch zoom; tap map to walk;
  floating chat launcher.
- **HUD:** level + name, HP/stamina/XP bars, **$OTWN balance (click → bank)** + **🍬 Candy badge
  (click → Candy Factory)**, zone, minimap, 5 action buttons (Character, Inventory, Gear, PvP,
  Market), toasts, buff bar, consumable quick-buttons.

## 16. Security / Bot Protection / Moderation

- **Connection gates:** banned-wallet reject, datacenter/Tor/VPS IP block, per-IP + global +
  per-wallet reconnect limits.
- **Signup anti-sybil:** ~3 accounts/IP/hour + **Cloudflare Turnstile CAPTCHA** on character
  creation.
- **Anti-cheat:** server-authoritative movement/teleport validation (mount-aware), scripted-route
  loop detection, mining-rhythm flagging, auto-ban on flag threshold, idle-sweep of parked bots,
  and a trusted-wallet allowlist.
- **Admin panel** (`/admin`, key-gated): ban/freeze/kick, balance adjust, ledger + marketplace
  sales view, withdrawals approve/reject, config tuning, events, treasury, daily metrics, bot
  sweep.
- **Token-gate sweep** every 10 min removes wallets that dropped below the minimum.

## 17. All Confirmed Features

- Solana wallet login + 5,000 $OTWN token gate + spectator mode
- Character creation onboarding + guide NPC (Mira)
- 3D multiplayer city, ~16 zones, portal to Verdant Hollow
- Mining + Fishing (XP, items, fatigue/luck)
- XP/leveling to 100 with stat scaling
- Inventory, 11 equipment slots, gear T1–T6
- **Economy V2: dual currency $OTWN + Candy 🍬** (SELL→$OTWN, BUY→Candy)
- **Candy Factory** — stake $OTWN to mint Candy (300/day, −1%/day, 12h lock, 2% unstake fee,
  5% claim fee → treasury, 0.1-granular, whole-supply accounting)
- **Candy Market** — CANDY/$OTWN order book, hourly candlestick chart, DexScreener USD pricing
- Gear shop, gear forge (RNG), boutique cosmetics, food vendor, clinic heal, repair, crafting — **all priced in Candy**
- Player marketplace (**Candy, zero-fee**) + NPC quick-sell/sell-all (**$OTWN**)
- PvE combat, drops, gear drops, respawn
- World Boss (scheduled, ranked rewards, unique mount)
- PvP arena (weekly $OTWN pool)
- 3 functional legendary pets
- Vehicles/mounts (L10+, owner-bound) + tradable dragon mount
- **Property (homes + Skyvault towers) as tradable Deed items** (Candy) + interior decoration + vehicle parking
- On-chain bank deposit/withdraw (non-custodial)
- Chat (world/whisper/friends), emotes, notifications
- Billboard ads (**Candy**, 90% owner / 10% treasury)
- In-game confirmation modals for all economy actions; lollipop Candy logo
- Buffs (Tide Blessing from moon koi)
- Full admin/moderation + anti-bot stack
- Desktop + mobile controls

## 18. Partial / Unclear Features

- **Faction reputation** — table exists, *not yet used*. No gameplay.
- **Billboard ads** — now paid in **Candy** (USDC removed); 90% credited to the tower owner in
  Candy, 10% to the Candy treasury. (Owner ad income is real Candy, credited on placement.)
- **Casino (Lucky Reef)** — **closed for an upgrade** (CHIP retired + auto-refunded to $OTWN).
  Slot engine + ledger code retained for a future Candy-based relaunch.
- **Tower interiors** — Skyvault towers are ownable (Deed + ad revenue) but have **no walk-in
  interior yet** (Phase 2); homes do.
- **Mining-rhythm bot flag** — severity 1, *manual-review only, not auto-punished*.
- **Starter weapon mismatch** — starter grants the driftwood baton but default equips the tide
  sidearm; cosmetic inconsistency.
- **`dev:setLevel`** socket event — dev/mock-mode only.

## 19. Not Confirmed / Do Not Claim

- *"Candy can be mined / looted / earned from gameplay"* — false; Candy is minted **only** by
  staking $OTWN at the Candy Factory.
- *"Mining/fishing earn $OTWN directly"* — false; they give **items + XP**. $OTWN comes from
  selling loot to vendors.
- Mining/fishing/PvE granting currency — not confirmed (only World Boss and PvP credit $OTWN from
  combat; selling credits the rest).
- Quests, story missions, objectives, daily tasks — not implemented.
- Any items/pets/mounts/zones beyond those listed — there are exactly 3 pets, the listed
  vehicles + 1 dragon mount, and the listed zones.
- XP from World Boss or PvP — not confirmed.
- Exact fee %, earn cap, autoban threshold — these are runtime/env-configured, not fixed
  constants.
- Hot-wallet funding mechanism and ad settlement batch — not confirmed.

---

*Generated from a direct source audit of `/opt/owntown` (server, shared, and client). Economy V2
(Candy) reflected as of 2026-06-18.*