soroban-abacus-flashcards/apps/web/src/arcade-games/know-your-world

Know Your World

A geography quiz game where players identify countries, states, and territories on unlabeled maps.

Documentation

Document	Description
Architecture	System overview, data flow, component responsibilities
Features	Complete feature inventory with file references
Patterns	Code conventions, component limits, testing patterns
Magnifier Architecture	Deep dive on zoom system
Precision Controls	Cursor dampening and pointer lock

Implementation Details

Document	Description
Background Music	Music system architecture (Strudel)
Celebration System	Victory animations and types
Give Up Flow	Give up mechanics and re-asking
Map Cropping	Viewport fitting algorithm
Strudel Layering	Music layering implementation

---

Quick Start

Game Modes

• Cooperative: Work together to find all regions
• Race: Compete - first click wins the point
• Turn-Based: Take turns finding locations

Maps

• World Map: 256 countries and territories (filterable by continent)
• USA States: 51 states (50 + DC)

Difficulty

Filter by region size: Huge → Large → Medium → Small → Tiny

Assistance Levels

Level	Hot/Cold	Hints	Learning Mode
Learning	✓	✓ Auto	✓ Type name
Guided	✓	✓
Helpful	✓	On request
Standard		On request
None

---

Key Features

Precision Controls

Tiny regions (like Gibraltar at 0.08px) are clickable thanks to:

• Adaptive magnifier: 8-60x zoom based on region density
• Cursor dampening: Slows cursor over tiny regions
• Pointer lock: Pixel-precise control mode

Multiplayer

• Real-time cursor sharing
• Cooperative give-up voting
• Turn order enforcement

Audio

• Speech synthesis for region names (with optional regional accents)
• Hot/cold audio feedback
• Dynamic background music (regional styles)

---

Project Structure

know-your-world/
├── docs/                    # Documentation (START HERE)
│   ├── ARCHITECTURE.md      # System overview
│   ├── FEATURES.md          # Feature inventory
│   ├── PATTERNS.md          # Code conventions
│   └── implementation/      # Implementation details
│
├── components/              # React components
│   ├── GameComponent.tsx    # Root (phase router)
│   ├── MapRenderer.tsx      # Main game (6285 lines - needs refactoring)
│   └── GameInfoPanel.tsx    # Control panel (2090 lines - needs refactoring)
│
├── hooks/                   # Custom hooks
├── utils/                   # Utility functions
├── music/                   # Music system
│
├── Provider.tsx             # React Context
├── Validator.ts             # Server-side logic
├── types.ts                 # TypeScript interfaces
└── maps.ts                  # Map data

---

Development

Running Locally

npm run dev
# Navigate to /arcade/room/{roomId}

Storybook

npm run storybook
# Navigate to "Arcade Games / Know Your World"

Debug Mode

Add ?debug=1 to any URL to enable debug overlays:

• Bounding boxes
• Zoom info
• Hot/cold enable conditions

---

Maintenance Notes

Large Files Needing Refactoring

File	Lines	Notes
MapRenderer.tsx	6,285	Extract to feature modules
GameInfoPanel.tsx	2,090	Extract UI sections

See PATTERNS.md for refactoring guidelines.

Test Coverage

Area	Status
Validator	✓ Good
Utils	✓ Good
Components	Partial
Hooks	Needs coverage

---

Related Documentation

• Game SDK - Arcade game framework
• Arcade System - Room/session architecture

Credits

• Map data: @svg-maps/world, @svg-maps/usa
• Label positioning: D3 Force
• Animations: React Spring
• Music: Strudel