CS2 Reviewer

A comprehensive tool for analyzing Counter-Strike 2 demo files with interactive visualization and detailed statistics.

Overview

CS2 Reviewer parses CS2 demo files (.dem) and provides an interactive web interface to analyze matches, visualize kill positions on maps, and review detailed statistics including player positions, economic data, and round-by-round breakdowns.

Key Features

• Comprehensive Demo Parsing: Extract all match data including teams, players, rounds, kills, and economics
• Interactive Map Visualization: Click kill events to see victim/attacker/assister positions overlaid on actual CS2 maps
• 3D Position Tracking: Every kill includes X/Y/Z coordinates for spatial analysis
• Economic Analysis: Track equipment values, money spent, and economic decisions
• Split-Level Map Support: Proper handling for Nuke and Vertigo (upper/lower floors)
• Type-Safe Architecture: Full TypeScript support with runtime validation
• Modern & Legacy UIs: Choose between modern Svelte SPA or server-rendered Haml templates

Supported Maps

de_ancient, de_anubis, de_dust2, de_inferno, de_mirage, de_nuke, de_overpass, de_vertigo

Architecture

The project consists of three interconnected components:

┌─────────────────────────────────────────────────────────────┐
│                     CS2 Reviewer System                      │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐      ┌──────────────┐      ┌───────────┐ │
│  │ demo_parser  │─────▶│ web_server   │◀─────│web_client │ │
│  │   (Go CLI)   │      │ (Ruby/Sinatra)│      │(Svelte SPA)│ │
│  └──────────────┘      └──────────────┘      └───────────┘ │
│                                                               │
│  • Parses .dem      • HTTP API             • Modern UI       │
│  • Event-driven     • File uploads         • TypeScript      │
│  • JSON output      • Subprocess calls     • Interactive     │
│                     • Serves both UIs      • Type-safe       │
└─────────────────────────────────────────────────────────────┘

Data Flow

User uploads .dem file
        ↓
  web_server receives upload
        ↓
  Calls demo_parser (Go binary)
        ↓
  Parses demo → JSON output
        ↓
  Ruby processes JSON
        ↓
  ┌──────────────────┬──────────────────┐
  │                  │                  │
  Haml templates  Svelte SPA         JSON API
  (legacy UI)     (modern UI)        (for clients)

Technology Stack

Component	Language	Framework/Tools	Purpose
demo_parser	Go 1.21.7	demoinfocs-golang	Binary parsing of CS2 demos
web_server	Ruby 3.3.4	Sinatra, Puma, Haml	API + legacy UI
web_client	TypeScript 5.6	Svelte 5, Vite 6, Zod	Modern SPA with type safety

Prerequisites

Required Software

• Go 1.21.7 or higher
• Ruby 3.3.4 or higher
• Node.js 18+ (for web_client)
• Bundler (Ruby gem manager)
• npm (Node package manager)

Installation

macOS (using Homebrew)

# Install Go
brew install go

# Install Ruby (using rbenv recommended)
brew install rbenv
rbenv install 3.3.4

# Install Node.js
brew install node

Ubuntu/Debian

# Install Go
wget https://go.dev/dl/go1.21.7.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.7.linux-amd64.tar.gz

# Install Ruby (using rbenv recommended)
sudo apt install rbenv
rbenv install 3.3.4

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Quick Start

1. Clone the Repository

git clone <repository-url>
cd cs2-reviewer

2. Build the Demo Parser

cd demo_parser
make build
cd ..

3. Setup Web Server

cd web_server
bundle install
cd ..

4. Setup Web Client (Optional - for modern UI)

cd web_client
npm install
cd ..

5. Start the Application

Option A: Quick Start (Legacy UI)

cd web_server
bundle exec rackup
# Access at http://localhost:4567

Option B: Full Stack Development (Modern UI)

# Terminal 1 - Start web server
cd web_server
bundle exec rerun -- rackup

# Terminal 2 - Start web client dev server
cd web_client
npm run dev
# Access at http://localhost:5173

Option C: Production-like Setup

# Build web client
cd web_client
npm run build
cd ..

# Start web server
cd web_server
bundle exec puma
# Access Haml UI at http://localhost:4567
# Access Svelte SPA at http://localhost:4567/app

Project Structure

cs2-reviewer/
├── demo_parser/              # Go binary for parsing CS2 demos
│   ├── cmd/                  # CLI entry point
│   │   └── cs2-reviewer/     # Main application
│   ├── internal/             # Parser implementation
│   │   └── counter_strike/   # CS2-specific logic
│   ├── out/bin/              # Build output
│   ├── Makefile              # Build automation
│   └── README.md             # Parser documentation
│
├── web_server/               # Ruby Sinatra backend + legacy UI
│   ├── main.rb               # Sinatra application
│   ├── views/                # Haml templates
│   │   ├── layout.haml       # HTML wrapper
│   │   ├── index.haml        # Upload form
│   │   └── upload.haml       # Results display
│   ├── public/               # Static assets
│   │   ├── css/              # Bootstrap
│   │   ├── js/               # JavaScript
│   │   ├── maps/             # CS2 map images
│   │   └── app/              # Built web_client (generated)
│   ├── lib/                  # Ruby modules
│   ├── spec/                 # Tests
│   └── README.md             # Server documentation
│
├── web_client/               # TypeScript/Svelte SPA
│   ├── src/
│   │   ├── main.ts           # Entry point
│   │   ├── App.svelte        # Root component
│   │   ├── lib/              # Svelte components
│   │   └── models/           # Type-safe data models
│   ├── vite.config.ts        # Build to ../web_server/public/app/
│   └── README.md             # Client documentation
│
└── README.md                 # This file

Development Workflows

Workflow 1: CLI Only (Demo Parsing)

Perfect for: Batch processing, scripting, data extraction

cd demo_parser
./out/bin/cs2-reviewer /path/to/demo.dem > output.json

Output: Structured JSON with all match data

Workflow 2: Legacy UI Development

Perfect for: Quick demos, simple usage, server-side rendering

cd web_server
bundle exec rerun -- rackup
# Visit http://localhost:4567
# Upload demo → View results

Features:

• File upload interface
• Server-side rendering
• Bootstrap UI
• Auto-reload on changes

Workflow 3: Modern UI Development

Perfect for: Frontend development, type-safe coding, modern tooling

# Terminal 1 - Backend
cd web_server
bundle exec rerun -- rackup

# Terminal 2 - Frontend
cd web_client
npm run dev
# Visit http://localhost:5173

Features:

• Hot Module Replacement (HMR)
• TypeScript type checking
• Zod runtime validation
• Component-based architecture
• ESLint + Prettier

Workflow 4: Production Build

Perfect for: Deployment, testing final build

# Build everything
cd demo_parser && make build && cd ..
cd web_client && npm run build && cd ..

# Start production server
cd web_server
bundle exec puma

Access:

• Legacy UI: http://localhost:4567
• Modern SPA: http://localhost:4567/app

Component Documentation

Each component has detailed documentation:

• demo_parser/README.md - Go binary architecture, data structures, event handlers
• web_server/README.md - Ruby API, routes, Haml templates, integration
• web_client/README.md - Svelte components, TypeScript models, build config

Usage Examples

Parsing a Demo File (CLI)

./demo_parser/out/bin/cs2-reviewer ~/demos/match.dem > match.json

Uploading via Web UI

1. Start web_server: cd web_server && bundle exec rackup
2. Open http://localhost:4567
3. Click "Upload a demo"
4. Select .dem file
5. View interactive results with map visualization

Using the Modern SPA

1. Build web_client: cd web_client && npm run build
2. Start web_server: cd web_server && bundle exec puma
3. Open http://localhost:4567/app
4. Click kill events to visualize positions on map
5. View detailed round-by-round statistics

Common Issues & Troubleshooting

demo_parser binary not found

Error: No such file or directory: '../demo_parser/out/bin/cs2-reviewer'

Solution: Build the Go binary first

cd demo_parser
make build

Port already in use

Error: Address already in use - bind(2) for "127.0.0.1" port 4567

Solution: Kill process using port or change port

# Find process
lsof -i :4567
# Kill it
kill -9 <PID>

web_client shows blank/loading forever

Issue: web_client fetches from /test endpoint which requires cached demo data

Solution: Either:

1. Use the legacy UI to upload a demo first
2. Place test JSON in web_server/tmp/de_nuke.json
3. Modify web_client/src/App.svelte to use a different endpoint

Go version mismatch

Error: go.mod requires go >= 1.21.7

Solution: Update Go

go version  # Check current version
# Install Go 1.21.7+ using your package manager

Ruby version mismatch

Error: Your Ruby version is X.X.X, but your Gemfile specified 3.3.4

Solution: Use rbenv or rvm

rbenv install 3.3.4
rbenv local 3.3.4

TypeScript errors in web_client

Issue: Type mismatches or Zod validation failures

Solution: Run type checking

cd web_client
npm run check  # Runs svelte-check and tsc

Project Status

Current State

✅ Working:

• Go demo parser (fully functional)
• Ruby web server with file upload
• Legacy Haml UI with map visualization
• Modern Svelte SPA with type safety
• Interactive kill position visualization

⚠️ In Progress:

• Migration from Haml templates to Svelte SPA
• Two parallel frontends (transitional state)

❌ Missing:

• File upload in web_client (relies on cached data)
• Environment configuration (hardcoded URLs)
• Test coverage
• CI/CD pipeline
• Deployment documentation

Recent Changes

• ✨ Complete TypeScript rewrite with Zod validation
• ✨ Svelte 5 with new runes API
• 🐛 Fixed API/client integration issues
• 🔧 Restored Makefile for simplified builds

Future Roadmap

Short Term

• Add file upload to web_client
• Environment-based configuration
• Extract map metadata to config files
• Add error handling and user feedback
• Write tests for all components

Medium Term

• Complete migration to Svelte SPA (deprecate Haml)
• Add round timeline scrubber
• Player statistics dashboard
• Heatmaps for common positions
• Export functionality (PDF, images)

Long Term

• Real-time demo analysis (stream processing)
• Machine learning for strategic insights
• Multi-demo comparison
• Team performance tracking over time
• Integration with CS2 Game State Integration (GSI)

Use Cases

For Competitive Teams

• Post-match analysis and review
• Identify strategic mistakes
• Analyze opponent tendencies
• Economic decision analysis

For Players

• Personal performance review
• Positioning improvement
• Aim analysis (headshot %, accuracy)
• Highlight identification

For Analysts

• Statistical analysis
• Machine learning datasets
• Strategic research
• Content creation (highlight reels)

Contributing

This is a personal project, but contributions are welcome!

Development Setup

1. Fork the repository
2. Follow the Quick Start guide
3. Create a feature branch
4. Make your changes
5. Test thoroughly
6. Submit a pull request

Code Style

• Go: Follow gofmt formatting
• Ruby: Follow Ruby Style Guide
• TypeScript: Use ESLint + Prettier (configured in web_client)

License

This project uses map assets derived from Boltobserv (GPL-3 licensed).

Acknowledgments

• demoinfocs-golang - CS2 demo parsing library
• Boltobserv - Map assets and coordinate systems
• SimpleRadar - High-quality radar images

Support

For issues, questions, or feature requests, please open an issue on GitHub.

---

Note: This project was created for educational and analytical purposes. It is not affiliated with Valve Corporation or Counter-Strike 2.