Clod - Territorial Strategy Game

A grid-based multiplayer territorial strategy game built with TypeScript and Node.js. Players compete to control zones, collect resources, and defend against AI enemies in turn-based tactical gameplay.

🎮 Game Features

• Territorial Control: Claim zones by occupying them for 5 turns with progressive moon phases 🌑🌒🌓🌔🌕
• Shop System: 9x9 interactive shop area with walk-to-buy mechanics and emoji pricing
• Zone-Specific Rewards: Corner zones generate 💎 diamonds (3pts), side zones generate ⚡ energy/💰 gold (2pts)
• Powerup System: ⚡ Sprint, 🧲 Pull, 🛡️ Shield with energy costs and charge mechanics
• Relic System: Passive upgrades available after turn 10 for advanced strategy
• Event System: Real-time feedback on territory control, resource generation, and combat
• AI Enemies: 👻 Scouts and 🤖 destroyers that move toward controlled zones
• Multiplayer: Real-time WebSocket-based multiplayer support
• Offline Mode: Single-player vs AI gameplay

📋 Quick Start

Prerequisites

• Node.js 20+
• npm 10+

Installation & Setup

# Clone and install
git clone <repository>
cd clod
npm install

# Build all packages
npm run build

# Quick commands (recommended)
npm run play           # Play offline (human vs AI)
npm run server         # Start multiplayer server
npm run create         # Create multiplayer game (will prompt for name)

# Advanced commands  
npm run dev:cli -- -- --offline                    # Play offline
npm run dev:cli -- -- --create --name "YourName"   # Create game with name
npm run dev:cli -- -- --join GAMEID --name "Name"  # Join existing game

🏗️ Architecture

This is a monorepo with separate packages:

clod/
├── packages/
│   ├── game-engine/     # Core game logic & rules
│   ├── game-server/     # WebSocket multiplayer server
│   └── cli-client/      # Terminal game client
├── shared/              # Common types & protocols
└── package.json         # Workspace configuration

Package Details

packages/game-engine

• Purpose: Core game mechanics, state management, and rule validation
• Key Files:
  • TerritorialGameEngine.ts - Main game logic
  • ConsoleUI.ts - Terminal rendering
  • types/game.ts - Game state interfaces
• Features: Turn-based movement, zone control, resource spawning, enemy AI

packages/game-server

• Purpose: Multiplayer game coordination via WebSocket
• Key Files:
  • index.ts - HTTP + WebSocket server setup
  • GameServer.ts - Game session management
• API:
  • POST /api/games - Create new game
  • GET /api/games - List active games
  • GET /health - Server health check

packages/cli-client

• Purpose: Terminal-based game interface
• Key Files:
  • index.ts - CLI argument parsing
  • GameClient.ts - Game state & server communication
• Features: Single-char input, offline/online modes, WebSocket client

shared/

• Purpose: Common types and constants
• Contents: WebSocket protocols, game constants, shared interfaces

🎯 Gameplay Guide

Objective

Control zones to generate resources and accumulate points while defending against AI enemies.

Game Elements

Symbol	Meaning
🔵 🔴	Player 1 & 2
🟫🟪🟨🟩🟧🔲	Unclaimed zones A-F (color-coded)
🟦 🟥	Controlled zones (blue/red for each player)
💎 💰	Diamonds (3pts) & Gold (2pts) resources
👻 🤖	Scout/Destroyer enemies
⬛	Empty space

Controls

• WASD: Move player
• Q: Quit game

Rules

1. Turn Structure: Each player gets 1 move, then time-step processes
2. Zone Control: Stay in a zone for 5 turns to claim it with progressive moon phases 🌑🌒🌓🌔🌕
3. Guaranteed Resources: Controlled zones generate resources every turn (100% guaranteed!)
4. Zone Rewards: 🟫🟩 corners=💎(3pts), 🟪🟧 sides=⚡energy/💰gold(2pts), 🟨🔲 strategic=💰(2pts)
5. Shop System: Walk over items or prices in central 9x9 area to buy with gold
6. Powerups: Use 1/2/3 keys to activate ⚡Sprint, 🧲Pull, 🛡️Shield abilities
7. Enemy Movement: AI enemies move toward controlled zones and steal resources
8. Events: ⚡ RECENT EVENTS panel shows all turn actions and results
9. Winning: 15 points OR control 4 zones simultaneously

🔧 Development

Building

npm run build              # Build all packages
npm run build -w <package> # Build specific package

Running

npm run dev:server         # Start game server (port 3001)
npm run dev:engine         # Watch game engine changes
npm run dev:cli            # Run CLI in development mode

Testing

# Test offline mode
npm run play

# Test multiplayer (requires server running)
npm run server        # Terminal 1: Start server
npm run create         # Terminal 2: Create game  
npm run dev:cli -- -- --join GAMEID --name "Player2"  # Terminal 3: Join game

🌐 Multiplayer Protocol

HTTP API

# Create game
POST /api/games
Body: { "playerName": "string" }
Response: { "gameId": "string", "message": "string" }

# List games  
GET /api/games
Response: [{ "id": "string", "playerCount": number, "spectatorCount": number, "createdAt": "string" }]

WebSocket Messages

Client → Server

{
  type: 'join' | 'move' | 'spectate',
  gameId?: string,
  playerName?: string, 
  direction?: 'w' | 'a' | 's' | 'd'
}

Server → Client

{
  type: 'game-state' | 'error' | 'player-joined' | 'player-left',
  data?: GameState,
  message?: string
}

📁 Project History

This project evolved through several iterations:

1. Initial Concept: Card-based roguelike inspired by Balatro
2. Pivot 1: Prisoner's dilemma puzzle mechanics
3. Pivot 2: Resource collection with sharing bonuses
4. Final Form: Territorial control with strategic zone management

Key design decisions:

• Immutable State: Clean game state management for multiplayer
• Separation of Concerns: Game logic isolated from UI/networking
• Client/Server Architecture: Enables real-time multiplayer
• Monorepo Structure: Shared dependencies while maintaining modularity

🚀 Roadmap (from IDEAS.md)

Phase 1: Core Systems ✅ COMPLETE

• Powerup System: ⚡Sprint, 🧲Pull, 🛡️Shield with energy costs and charges
• Shop System: 9x9 interactive area with walk-to-buy mechanics and auto-refresh
• Win Conditions: Hybrid victory system (15 points OR 4 zones control)
• Relic System: Passive modifiers available after turn 10 (implemented but needs expansion)

Phase 2: Enhanced Mechanics

• Cooperative Collection: +50% bonus when near teammate
• Enhanced Enemy System: 👻🤖🕷🛡 with specific counters
• Capture Rewards: Powerup/relic shards on zone capture

Phase 3: Advanced Features

• Preview Panel: Show projected zone progress and income
• Stage Modifiers: Fog, tremors, tax, resource scaling
• Overcharge System: Bank energy for instant powerup use
• ASCII Rendering: Mono-width mode for alignment reliability

📝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes in appropriate packages
4. Build and test locally
5. Submit a pull request

📄 License

ISC License - See package.json for details