Market Mayhem

A multiplayer market simulation where information is imperfect, trust is risky, and every decision has consequences.

Players trade five fictional assets with virtual credits, react to public headlines, and weigh a private clue that nobody else has. When the bell rings, a hidden event resolves, and the strongest portfolio wins. The results screen then explains what really happened.

Fictional educational simulation. Virtual credits only. Not financial advice.

Live demo: add your Vercel URL here

How to play

1. Open a room. Enter a name, create a room, and share the 5-letter code (or the invite link). Everyone starts with 100,000 virtual credits. The host picks one of four scenarios.
2. Read the news, guard your clue. Headlines reach everyone at once. You also get a private clue that nobody else sees, and it might be wrong: check its confidence level.
3. Trade before the bell. Buy and sell five fictional companies. When the timer ends, the hidden event resolves, final prices are applied, and the highest portfolio value wins. The results screen reveals every player's clue and explains what really happened.

Landing	Lobby
Trading	Results

On a phone, the private clue is pinned to the top of the trading screen:

Scenarios

Scenario	The question	What it teaches
The Energy Shock	Shipping lanes are jammed. Is the shortage real?	A temporary shock and a lasting change look the same on day one.
The Rate Shock	A big rate hike is rumored. Who wins if money gets expensive?	One event can push different sectors in opposite directions.
The Cloud Breach	CloudForge reports a security incident. How bad is it?	Scary headlines move prices before the facts arrive.
The Battery Hype	A "battery breakthrough" is teased. Future, or headline?	Hype against fundamentals: buy the rumor, sell the news.

Rules in full: docs/game-rules.md.

Quick start

pnpm install
pnpm dev          # Next.js on :3000 + game server on :4000

Open http://localhost:3000, create a room, then open the invite link in a second browser window or tab and join. Each tab is its own player, and a refresh keeps your seat.

Script	What it does
pnpm dev	Web app and game server with hot reload
pnpm demo:fast	Same, with a ~70 s trading phase for quick demos
pnpm test	Engine, scenario-contract, balance, persistence and AI-summary tests, plus full multiplayer rounds over real sockets
pnpm balance	Plays every scenario with three fixed strategies and prints the balance table
pnpm typecheck / pnpm lint	TypeScript and ESLint
pnpm build and pnpm start	Production web build
pnpm start:server	Production game server

To play from a phone on the same Wi-Fi, open http://<your-LAN-IP>:3000. The client connects to port 4000 on the same host automatically.

What's in the demo

Everything in the blueprint's MVP scope:

• Guest identity with a server-issued player ID and a secret session token (stored in sessionStorage)
• Create and join rooms by 5-character code, ready-up, host start, and replay
• Five fictional assets with live prices, sparklines and a price chart. Headlines are marked on the chart.
• Buy and sell with a review/confirm step, fees and price impact, plus holdings and trade history
• Public news feed and a private clue card. Clues go only to the intended player.
• A server-authoritative timer and a state machine: LOBBY → STARTING → ACTIVE → RESOLVING → FINISHED
• Final ranking, every player's clue revealed ("who knew what"), a per-asset debrief and takeaways
• Reconnect: refreshing mid-round restores your room, portfolio and clue
• Seeded, reproducible market path (P1)

Architecture

app/, components/, lib/   Next.js UI (client components), useGame socket hook
shared/                   Types, event names, Zod schemas, assets and rules shared by both sides
server/
  index.ts                Env config (Zod) and boot
  app.ts                  Express HTTP routes and Socket.IO handlers (validation, identity, rate limits)
  game/Room.ts            Room state machine, trading, ticking, scoring, results
  game/RoomManager.ts     Collision-checked room codes, idle-room cleanup
  engine/                 Pure functions: seeded RNG, price model, portfolio math, ranking
  scenarios/              Scenario configs (hidden truth) and balance hints. Server-only.
  balance/                Automated balance play-tests (`pnpm balance`)
  persistence/            Optional PostgreSQL (Prisma) write queue
  ai/                     Optional Gemini round summary (narrates computed results only)
  test/                   node:test suites
docs/game-rules.md        Player-facing rules and the price model
docs/scenario-authoring.md  The scenario contract and how to add one
docs/qa-matrix.md         Manual QA checklist for staging
docs/launch-checklist.md  Production release and demo-day checklist
pitch/                    Speaker notes and the demo script

Server-authoritative. The browser only sends intent (symbol, side, quantity, requestId, roundId). The server validates the payload with Zod, then checks membership, round state, deadline, cash and holdings. It sets the execution price and rejects duplicate request IDs. Cash, holdings, prices and scores never come from the client.

Money is stored as integer cents throughout, never floats.

HTTP

Route	Purpose
GET /health	Health check
GET /api/assets	Asset metadata and opening prices
GET /api/rooms/:code	Public room snapshot
GET /api/rooms/:code/results	Final results (409 until finished)

This is the beginning of the README. Read the rest at the original. Read the full README ↗