Skip to content

CLAUDE.md

Latest commit

 

History

History
136 lines (92 loc) · 4.09 KB

CLAUDE.md

File metadata and controls

136 lines (92 loc) · 4.09 KB

CLAUDE.md

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

Common Development Commands

Building and Running

# Build all binaries and frontend
make install

# Run the game controller
go run cmd/ssl-game-controller/main.go

# Run with hot-reload development mode  
make dev

# Build frontend only
cd frontend && npm run build

# Run frontend development server
cd frontend && npm run dev

Testing and Quality

# Run all Go tests
make test

# Run frontend linting
cd frontend && npm run lint

# Run frontend type checking
cd frontend && npm run type-check

Protocol Buffer Generation

# Regenerate protobuf code after modifying .proto files
make proto

Docker

# Build Docker images for game controller and ref client
make docker

# Run complete test environment with autoRefs
docker compose up

Architecture Overview

This is the SSL Game Controller for RoboCup Small Size League - a Go backend with Vue.js frontend that manages robot soccer matches.

Core Components

Game Engine (internal/app/engine/): Central state machine that processes all game state changes through a queue-based system. Maintains current match state and coordinates with various processors for rule enforcement.

State Machine (internal/app/statemachine/): Translates change requests into new game states. Handles all game transitions including commands, stages, cards, and game events.

State Store (internal/app/store/): Append-only persistent storage for all state changes, enabling replay and revert functionality.

Communication Layers:

  • Frontend communicates via WebSocket API (/api/control) using protobuf messages
  • External clients connect via TCP with protobuf protocols for teams, autorefs, remote control, and CI integration
  • UDP multicast publishes referee messages to all match participants

Key Protocols

Client Types (all in proto/rcon/):

  • ssl_gc_rcon_team.proto: Team communication (timeouts, substitutions, advantage choice)
  • ssl_gc_rcon_autoref.proto: Automated referee game event proposals
  • ssl_gc_rcon_remotecontrol.proto: Manual referee control
  • ssl_gc_ci.proto: CI integration for testing

Core Data (in proto/state/):

  • ssl_gc_state.proto: Complete game state representation
  • ssl_gc_game_event.proto: 80+ types of game events and violations
  • ssl_gc_referee_message.proto: Standard SSL referee message format

Frontend Structure

Technology: Vue.js 3 + TypeScript + Quasar UI framework State Management: Pinia stores in frontend/src/store/ Components: Organized by feature in frontend/src/components/

  • control/: Manual game control buttons
  • match/: Live match display and event management
  • team/: Team-specific settings and information
  • game-events/: Game event input forms and displays

Keyboard Shortcuts: Centralized in frontend/src/providers/shortcuts/ with global event listeners registered in the control plugin. All shortcuts (numpad commands, Ctrl+Space for auto-continue, Ctrl+1-9 for continue actions) are handled in one place with automatic disabling during text input.

Adding New Teams

For new teams, add the team name to defaultTeams in internal/app/engine/config.go and submit a pull request.

Development Modes

System Mode (default): Uses system time Vision Mode: Uses ssl-vision timestamps for simulation integration
CI Mode: Full control via TCP for automated testing - recommended for simulator integration

CI mode enables:

  • No multicast network traffic (set network.publish-address to empty)
  • Controlled data flow and timing
  • Direct ssl-vision tracking data input
  • Integration with test frameworks

External Dependencies

  • ssl-vision: Provides field geometry (required)
  • Tracker source: Ball/robot positions for advanced rule checking (TIGERs AutoRef or ER-Force AutoRef)

Without tracker source, the following features are disabled:

  • Ball placement progress checking
  • Robot count validation
  • Game continuation readiness
  • No progress detection
  • Goalkeeper change validation