# LifeTown Online 🏙️

An **original browser-based multiplayer life simulation** — create a character, move into
Maple Court, get a job, furnish your home, befriend the townsfolk and other players, and
live an ongoing simulated life. No installation, no plugins: it runs in a modern desktop
or mobile browser.

> All characters, world design, UI, code, audio and visuals are original to this project.
> No copyrighted assets, names, logos or UI from any existing game are used.

---

## Quick start

```bash
npm install       # three, ws, vite
npm run build     # bundles the client into client/dist
npm start         # serves game + WebSocket on http://127.0.0.1:7788
```

Open **http://127.0.0.1:7788** in two browser windows to play multiplayer.

Environment overrides: `GAME_PORT` (default `7788`). Player saves are JSON files in `saves/`.

## Controls

| Action | Desktop | Mobile |
|---|---|---|
| Move | WASD / arrows | virtual joystick (bottom-left) |
| Run | hold Shift | joystick edge / 🏃 button |
| Interact | E or 👋 Act | ✋ button |
| Dance emote | F or 💃 | — |
| Orbit camera | left-drag | drag on scene |
| Zoom | wheel | pinch area |
| Chat focus | Enter | tap chat box |

Walk up to glowing POI rings (café, gym, pond, stage…) or furniture at home and press **E**.

## What's in the MVP

- **Character creator** — live 3D preview; body type, height, skin tones, hair styles &
  colours, eyes, brows, nose, mouth, outfits, shoes, accessories, voice, age and up to 3
  personality traits.
- **One living district — Maple Court** — main street with café, City Hall, gym, home-goods
  store and arcade. **Every venue is enterable**: walk to a street-facing door and press E to
  step into a shared furnished interior with activity spots (order coffee, hit the gym mats,
  browse the shop catalogue, play the arcade); apartment doors lead straight into your home.
  store, apartments, arcade façade, central plaza with fountain & stage, park with pond,
  food truck, bus stop, benches, lamps and trees.
- **Needs & mood** — hunger, energy, hygiene, fun, social, comfort decay over time;
  weighted mood engine with 13 moods + transient moodlets drive facial expressions and HUD.
- **NPCs with routines** — 10 original townsfolk walk POI-to-POI on daily schedules,
  chatter ambiently and react to your interactions.
- **Jobs & economy** — 12 careers × 5 ranks with pay, XP and promotions; shifts worked at
  real workplaces; TownCoins earned/spent across shops, homes, food and gifts.
- **Housing & build mode** — studio apartment instanced per player (5 more tiers purchasable),
  drag-to-place furniture on a snap grid with rotate/duplicate/sell tools, 58-item catalogue
  whose items boost needs recovery, cooking speed and productivity.
- **Friendship & romance** — contextual interaction wheels (Friendly/Romantic/Funny/Negative)
  gated by two independent relationship meters with tier labels and partner status.
- **Multiplayer** — server-authoritative sessions/rosters/economy/relationships over one
  WebSocket; 12 Hz snapshots with client-side interpolation; zone instances for town and
  every home; invitations to visit; global + local chat with speech bubbles.
- **Day/night & weather** — full day cycle (24 min/day) with dawn/dusk skies, sun/moon
  lighting, window glow and street lamps; sunny/cloudy/rain/storm/fog with rain particles,
  puddles that soak in, fog banks and lightning flashes.
- **Mini-games** — fishing (timing bar) and cooking (memory) feeding back into needs & fun.
- **Phone** — Messages, Contacts (relationship bars), Map, Careers, Bank (transaction log),
  LifeFeed social posts with in-game screenshots, Calendar of recurring town events, Home
  (teleport, property market, invites).
- **Progression** — player levels gate catalog/homes; 8 achievements incl. First Home,
  Social Butterfly, Millionaire, Interior Designer.
- **Save/load** — profiles autosave server-side (money, job, house, layout, inventory,
  relationships, achievements, needs); clients resume via token.
- **Audio** — fully procedural WebAudio: location-based music (home/town/night), rain beds,
  footsteps, door/cash/UI blips, achievement jingles.

## Architecture

```
lifetown/
├─ shared/data.mjs        # single source of truth: jobs, catalog, NPCs, interactions…
├─ server/
│  ├─ index.mjs           # Node http static server + ws upgrade (/ws)
│  ├─ game.mjs            # GameServer: sessions, zones, snapshots, NPCs, clock/weather,
│  │                      #   economy, relationships, achievements, persistence
│  └─ persist.mjs         # atomic JSON profile storage
├─ client/
│  ├─ index.html          # shell: title, creator, HUD, phone, build bar, modals
│  └─ src/
│     ├─ gfx/engine.ts    # renderer, ACES tone-mapping, day/night lighting rig
│     ├─ gfx/avatar.ts    # modular stylized characters + procedural animation set
│     ├─ gfx/town.ts      # procedural district geometry
│     ├─ gfx/interior.ts  # instanced home shells + grid scaffolding
│     ├─ gfx/furniture.ts # 58 procedural furniture builders
│     ├─ gfx/weatherfx.ts # rain particles, puddles, lightning hooks
│     ├─ controller.ts    # input, collision, camera rig, network transform sync
│     ├─ world.ts         # actor manager, interpolation, bubbles/name-tags
│     ├─ systems.ts       # needs simulation + mood derivation
│     ├─ audio.ts         # WebAudio sequencer & SFX synth
│     └─ ui/*             # HUD, chat, phone apps, dialogs/minigames, build UI, creator
└─ scripts/
   ├─ e2e.mjs             # 20-check two-client protocol test
   └─ shot.mjs            # headless-browser walkthrough of every screen
```

**Performance notes:** static geometry is modest-draw-call by construction, shadows come
from a single tight sun cascade, remote players interpolate between 12 Hz snapshots, and
interiors are separate zone scenes so only one district is ever loaded.

## Verification

```bash
node scripts/e2e.mjs    # exercises auth, movement sync, chat, social gates, jobs,
                        # cooldowns, shopping, housing, zones, invites, persistence
node scripts/shot.mjs   # drives the real client headless through all major screens
```

## Roadmap beyond MVP

Beach zone & swimming, nightclub with DJ events, vehicles (bicycle → sports car),
weddings & festivals, group activities, Postgres/Redis backing stores, WebRTC voice,
seasonal events, pets, and expanded careers with skill mini-courses at the university.