RICO'S WORLD (RicosWorld) — 16-Bit Persistent Colony-Sim MMO

Rico's World (RicosWorld) is a top-down 16-bit SNES-styled persistent 2D colony simulation MMO where players act as Charter Pioneers issuing high-level designations (wall blueprints, stockpile & farming zones, mining orders, workbench bills, and inter-colony trade contracts) while autonomous colonists with physiological needs (hunger, rest), psychological moods & thoughts, traits, and skills carry them out on a persistent 100×100 tile grid (10 Hz simulation) connected to a shared planetary world map (1 Hz simulation).

• Git Forge & Issue Tracker: https://git.johnathonwheeler.com/game-dev/RicosWorld
• Live Server: https://ricosworld.themels.online
• Agent Collaboration & Git Workflow: See AGENTS.md

---

Quick Start (One-Command Run)

Prerequisites

• Node.js v22.5+ / v24 LTS (uses Node's built-in node:sqlite out-of-the-box; optional PostgreSQL via DATABASE_URL).

1. Install & Launch Everything

npm install
npm run dev

This single command starts:

• Authoritative Simulation Server on http://localhost:4000 (10 Hz local colony ticks, 1 Hz world map loop, password/session auth, binary WebSocket transport, SQLite/PostgreSQL persistence).
• 2D PixiJS Web Client on http://localhost:5173.

2. Test Two-Player World Map & Escrowed Trading

Open two browser tabs at http://localhost:5173, register or sign in as two different pioneers (e.g. Commander_Vance and Pioneer_Lyra), and click World Map [M] in the top-right bar to view both settlements on the shared world grid, dispatch an escrowed trade offer (e.g., offer 10 Timber Log for 8 Cut Slate), and accept it from the other player's tab.

---

Git Workflow & Issue Tracking (scripts/forgejo.mjs)

All development on Rico's World is tracked via issues and pull requests on our self-hosted Forgejo instance (https://git.johnathonwheeler.com/game-dev/RicosWorld). Read AGENTS.md before making any changes.

node scripts/forgejo.mjs whoami      # Verify active agent identity (agent-gemini / agent-claude / agent-kimi)
node scripts/forgejo.mjs issues      # List open issues on game-dev/RicosWorld
node scripts/forgejo.mjs prs         # List open pull requests

---

Running Tests & Determinism Verification

Run the full headless test suite (unit tests, binary snapshot/delta sync tests, headless 300-tick command-log replay determinism test, and 2-player server integration tests):

npm test

Or run individual workspace suites:

npm run test:sim      # Headless sim-core unit & command-log replay determinism tests
npm run test:server   # Multi-client server persistence, auth, offline shield & world trade tests
npm run typecheck     # Strict TypeScript verification across all workspaces

---

Repository Structure

.
├── AGENTS.md                 # AI Agent Collaboration Guide & Git/PR workflow rules
├── CLAUDE.md                 # Directive pointer to AGENTS.md for Claude Code
├── GEMINI.md                 # Directive pointer to AGENTS.md for Gemini / Antigravity
├── content/                  # Data-driven JSON definitions (hashed for replay parity)
│   ├── terrains.json         # Terrain walkability, movement cost, fertility, ore yield
│   ├── items.json            # Materials, crops & rations with stack limits and nutrition
│   ├── buildings.json        # Walls, sleeping cots, campfire hearth & masonry workbench
│   ├── needs.json            # Hunger & rest basis-point decay and thresholds
│   ├── jobs.json             # Priority weights for eat, sleep, build, haul, farm, mine, craft
│   ├── traits.json           # Colonist traits (Guild Mason, Fleet-Footed, Iron Metabolism)
│   ├── recipes.json          # Crafting recipe definitions
│   └── events.json           # Colony & world event definitions
├── sim-core/                 # Pure deterministic simulation library (zero I/O or engine deps)
│   ├── src/
│   │   ├── content-registry.ts
│   │   ├── prng.ts           # Seeded 32-bit Mulberry32 PRNG
│   │   ├── types.ts          # Structure-of-Arrays TileMap (100x100) & ECS records
│   │   ├── pathfinding.ts    # Deterministic A* pathfinder & adjacent work positioning
│   │   ├── binary-codec.ts   # Binary snapshot & WebSocket frame serializer (ArrayBuffer)
│   │   └── colony-sim.ts     # Fixed-tick simulation loop, needs, mood, skills & job AI
│   └── tests/                # Unit tests & headless command-log replay determinism check
├── server/                   # Authoritative game server
│   ├── src/
│   │   ├── auth.ts           # Scrypt password hashing & session token verification
│   │   ├── persistence.ts    # Dual SQLite (node:sqlite) & PostgreSQL (pg) adapters
│   │   ├── game-server.ts    # Interest management, Protected Offline Hibernation, World Trade
│   │   └── main.ts           # Server entrypoint
│   └── tests/                # 2-player WebSocket trade, auth & persistence integration tests
├── client/                   # Web / TypeScript + PixiJS v8 2D Client
│   ├── index.html            # 16-bit SNES title screen, HUD & modal layout
│   ├── public/sprites/       # Blender-rendered 3D-to-2D SNES sprite PNGs & manifest.json
│   └── src/
│       ├── snes-pixel-sprites.ts # External sprite sheet loader + procedural pixel fallback
│       ├── colony-renderer.ts    # PixiJS 2D tile, zone, blueprint, item & pawn renderer
│       ├── main.ts               # Binary WebSocket client, auth UI, HUD & world map UI
│       └── styles.css
├── scripts/
│   ├── forgejo.mjs           # CLI wrapper for Forgejo issues, PRs, labels & reviews
│   ├── deploy.mjs            # Production deployment script for ricosworld.themels.online
│   ├── dev.mjs               # Local multi-process development runner
│   └── blender_generate_snes_assets.py # Blender 4.x Python script for 3D-to-2D SNES sprites
└── docs/
    ├── ARCHITECTURE.md       # System design, tick pipeline, binary protocol & offline rules
    ├── GAME_DESIGN.md        # Lore, fixed-point math formulas, mood/skills & balance bible
    ├── ROADMAP.md            # Engineering roadmap mapped to Forgejo Issues (#1–#8)
    ├── BLENDER_SNES_ASSET_PROMPT.md # 3D-to-2D Blender asset generation spec
    └── SETUP.md              # Forgejo git server, agent tokens & VPS infrastructure guide

---

Optional PostgreSQL Mode

By default, the server persists accounts, settlements, binary colony snapshots (BLOB), command logs, and world trades to server/data/frontier.db via Node 24's built-in node:sqlite.

To run against PostgreSQL instead:

docker compose up -d
DATABASE_URL="postgres://frontier:frontier_dev_password@localhost:5432/frontier_mmo" npm run dev