Skip to content

CLAUDE.md

Latest commit

 

History

History
147 lines (112 loc) · 5.43 KB

CLAUDE.md

File metadata and controls

147 lines (112 loc) · 5.43 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Cossacks: Back to War - Community Edition is a WebAssembly port of the classic 2002 RTS game for browser play. The codebase uses SDL3 (via Emscripten ports) for graphics, audio, and input.

Build System

This project builds exclusively for WebAssembly using Emscripten:

cd build-emscripten
emcmake cmake ..
emmake make -j4
python tools/dev-server.py  # Serve with CORS headers
# Open http://localhost:8080/dmcr.html

For clean rebuilds:

cd build-emscripten
rm -rf CMakeCache.txt CMakeFiles/
emcmake cmake ..
emmake make -j4

Architecture

Directory Structure

src/
├── Main executable/     # Core game engine (~94 source files)
├── CommCore library/    # UDP multiplayer networking (replaced by WebRTC)
├── IntExplorer library/ # Menu/UI framework
├── IChat library/       # Chat system
├── ai/Algeria/          # CPU player AI (static library)
├── Main/               # CMake build target
├── CommCore/           # CMake build target
├── IntExplorer/        # CMake build target
└── IChat/              # CMake build target

Core Components

Main Executable (src/Main executable/)

  • Ddex1.cpp - SDL application callbacks (SDL_AppInit, SDL_AppIterate, SDL_AppEvent)
  • EmscriptenMain.cpp - WebAssembly entry point and main loop
  • IR_Main.cpp - Game initialization and player login
  • mapa.cpp - Main game loop, mouse input, selection handling
  • MapDiscr.h - Central game object definitions
  • GP_Draw.cpp - GP sprite rendering (8000+ lines, has assembly reference code)
  • 3DGraph.cpp - Isometric terrain rendering
  • Masks.cpp - Terrain texture transition masks
  • Lines.cpp - Line/rectangle drawing primitives
  • Mouse_X.cpp - Mouse cursor handling
  • NewMon.cpp - Unit/monster management and selection
  • Multi.cpp - Multiplayer and selection commands
  • GameSound.cpp - SDL audio system
  • WinCompat.h - Windows API compatibility layer for Emscripten

CommCore Library - Legacy UDP multiplayer (replaced by WebRTC in WebRTCTransport.cpp)

IntExplorer Library - Dynamic window system with tables, scrollbars, buttons

IChat Library - Chat system (GameSpy-era protocol)

AI (src/ai/Algeria/) - CPU player AI as static library

Key Data Structures (MapDiscr.h)

  • OneObject - Individual unit/building instance (position, state, order queue, 80+ boolean flags)
  • GeneralObject - Unit/building type definitions (stats, animations, weapons, costs)
  • Nation - Player state (8 resources: gold, wood, stone, iron, coal, oil, sulfur, tin)
  • Order1 - Command queue as linked list (move, attack, build, etc.)
  • Weapon - Projectile/attack definitions with child weapon support
  • NewMonster - Extended unit data (sprites, animations, selection rect)

GP Sprite Format

The game uses a custom "GP" sprite format with RLE-compressed masks:

GP_Header (23 bytes):

  • dx, dy - Sprite offset
  • Lx, Ly - Sprite dimensions
  • NLines - Number of scanlines
  • Options - Rendering mode (0=standard, 1=palette-encoded for faction colors, etc.)
  • NextPict - Offset to linked sprite frame (-1 if none)

Mask Format (after header):

  • Each line has a header byte
  • If bit 7 set: Complex format (bits 5-6 = extra bits for space/pixel counts)
  • Otherwise: Simple format (header = segment count, 2 bytes per segment)
  • Segments contain: space (transparent pixels) + pixel count

Faction Colors: Sprites with Options=1 use 2-bit encoded pixels (0-3) indexed into NatPal[Nation*4] for faction-specific colors.

Current State

Working

  • Game compiles to WebAssembly and runs in browser
  • Terrain rendering (including angled terrain and shore transitions)
  • Unit/building rendering with faction colors
  • Mouse input and drag-to-select units
  • Selection rectangle drawing
  • Basic UI and menus
  • Audio (sounds slightly "crunchy")
  • WebRTC multiplayer networking (via WebRTCTransport.cpp and web/webrtc.js)

Known Issues

  • Water rendering has white line glitches
  • Minimap screen outline not visible
  • Some font rendering issues in menus

Assembly Reference Code

The codebase contains #ifdef _MSC_VER blocks with x86 assembly that serve as reference. The portable C++ implementations in the #else branches are used for the Emscripten build. Key files with assembly blocks:

  • GP_Draw.cpp - GP sprite rendering functions
  • Masks.cpp - Terrain texture transitions
  • Lines.cpp - Line drawing primitives
  • Fastdraw.cpp - Sprite blitting functions
  • path.cpp - Pathfinding optimizations
  • Mouse_X.cpp - Cursor buffer operations
  • fog.cpp - Fog of war

Development Notes

  • No automated test suite; testing is manual in browser
  • TRACE/DOTRACE macros available in Testing builds
  • Max 65535 game objects, 8 players/nations
  • Frame rate capped at 30 FPS
  • Game assets bundled via Emscripten file packager (~480MB)

Common Patterns for Porting Assembly

When porting assembly blocks, look for:

  1. Simple memory fills (rep stosb/stosd) → memset() or loop
  2. Memory copies (rep movsb/movsd) → memcpy() or loop
  3. RLE mask parsing → Parse header byte, iterate segments
  4. Linked list iteration → Update pointer: ptr = (Type*)((byte*)base + offset)
  5. Bresenham algorithms → Standard C++ implementation

Always wrap portable code in #else after #ifdef _MSC_VER and before #endif.