Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Player, Game State & Infrastructure

28. Player System

Player Traits

TraitPurpose
PlayerResourcesCash, resources, income tracking
PlayerStatisticsKill/death/build statistics
PlayerExperiencePlayer-wide experience points
PlayerRadarTerrainPer-player radar terrain state
PlaceBuildingBuilding placement handler
PlaceBeaconMap beacon placement
DamageNotifierUnder attack notifications
HarvesterAttackNotifierHarvester attack notifications
EnemyWatcherEnemy unit detection
GameSaveViewportManagerSave game viewport state
ResourceStorageWarningStorage full warning
AllyRepairAllied repair permission

Victory Conditions

TraitPurpose
ConquestVictoryConditionsDestroy all to win
StrategicVictoryConditionsStrategic point control
MissionObjectivesScripted mission objectives
TimeLimitManagerGame time limit

Developer Mode

TraitPurpose
DeveloperModeCheat commands (instant build, unlimited power, etc.)

Faction System

TraitPurpose
FactionFaction definition (name, internal name, side)

29. Selection System

TraitPurpose
SelectionWorld-level selection management (5.4KB)
SelectableActor can be selected (bounds, priority, voice)
IsometricSelectableIsometric selection variant
SelectionDecorationsSelection box rendering
IsometricSelectionDecorationsIsometric selection boxes
ControlGroupsCtrl+number group management
ControlGroupsWidgetControl group UI
SelectionUtilsSelection utility helpers

30. Hotkey System

Mod-level Hotkey Configuration (RA mod)

  • hotkeys/common.yaml — Shared hotkeys
  • hotkeys/mapcreation.yaml — Map creation hotkeys
  • hotkeys/observer-replay.yaml — Observer & replay hotkeys
  • hotkeys/player.yaml — Player hotkeys
  • hotkeys/control-groups.yaml — Control group bindings
  • hotkeys/production.yaml — Production hotkeys
  • hotkeys/music.yaml — Music control
  • hotkeys/chat.yaml — Chat hotkeys

Hotkey Logic Classes

  • SingleHotkeyBaseLogic — Base hotkey handler
  • MusicHotkeyLogic, MuteHotkeyLogic, ScreenshotHotkeyLogic

31. Cursor System

Configured via Cursors: section in mod.yaml, defining cursor sprites, hotspots, and frame counts. The mod references a cursors YAML file that maps cursor names to sprite definitions.


32. Notification System

Sound Notifications

Configured via Notifications: section referencing YAML files that map event names to audio files.

Text Notifications

WidgetPurpose
TextNotificationsDisplayWidgetOn-screen text notification display

Actor Notifications

TraitPurpose
ActorLostNotification“Unit lost”
AnnounceOnKillKill notification
AnnounceOnSeenEnemy spotted
CaptureNotificationBuilding captured
DamageNotifierUnder attack (player-level)
HarvesterAttackNotifierHarvester under attack
ResourceStorageWarningSilos needed
StartGameNotificationBattle control online

33. Replay System

Replay Infrastructure

  • ReplayBrowserLogic — Full replay browser with filtering, sorting
  • ReplayUtils — Replay file parsing utilities
  • ReplayPlayback (in core engine) — Replay playback as network model

Replay Features

  • Order recording (all player orders per tick)
  • Desync detection via state hashing
  • Observer mode with full visibility
  • Speed control during playback
  • Metadata: players, map, mod version, duration, outcome

IC Enhancements

IC’s replay system extends OpenRA’s infrastructure with two features informed by SC2’s replay architecture (see research/blizzard-github-analysis.md § Part 5):

Analysis event stream: A separate data stream alongside the order stream, recording structured gameplay events (unit births, deaths, position samples, resource collection, production events). Not required for playback — purely for post-game analysis, community statistics, and tournament casting tools. See formats/save-replay-formats.md § “Analysis Event Stream” for the event taxonomy.

Per-player score tracking: GameScore structs (see 02-ARCHITECTURE.md § “Game Score / Performance Metrics”) are snapshotted periodically into the replay file. This enables post-game economy graphs, APM timelines, and comparative player performance overlays — the same kind of post-game analysis screen that SC2 popularized. OpenRA’s replay stores only raw orders; extracting statistics requires re-simulating the entire game. IC’s approach stores the computed metrics at regular intervals for instant post-game display.

Replay versioning: Replay files include a base_build number and a data_version hash in the replay metadata JSON (following SC2’s dual-version scheme — see formats/save-replay-formats.md § “Metadata”). The base_build identifies the protocol format; data_version identifies the game rules state. A replay is playable if the engine supports its base_build protocol, even if minor game data changes occurred between versions.

Foreign replay import (D056): IC can directly play back OpenRA .orarep files and Remastered Collection replay recordings via ForeignReplayPlayback — a NetworkModel implementation that decodes foreign replay formats through ic-cnc-content, translates orders via ForeignReplayCodec, and feeds them to IC’s sim. Playback will diverge from the original sim (D011), but a DivergenceTracker monitors and surfaces drift in the UI. Foreign replays can also be converted to .icrep via ic replay import for archival and analysis tooling. The foreign replay corpus doubles as an automated behavioral regression test suite — detecting gross bugs like units walking through walls or harvesters ignoring ore. See formats/save-replay-formats.md § “Foreign Replay Decoders” and decisions/09f/D056-replay-import.md.


34. Lobby System

Lobby Widget Logic

  • Lobby/ directory contains all lobby UI logic
  • Player slot management, faction selection, team assignment
  • Color picker integration
  • Map selection integration
  • Game options (tech level, starting cash, short game, etc.)
  • Chat functionality
  • Ready state management

Lobby-Configurable Options

TraitLobby Control
MapOptionsGame speed, tech, cash, fog, shroud
LobbyPrerequisiteCheckboxToggle prerequisites
ScriptLobbyDropdownScript-defined dropdown options
MapCreepsAmbient creeps toggle

35. Mod Manifest System (mod.yaml)

The mod manifest defines all mod content via YAML sections:

SectionPurpose
MetadataMod title, version, website
PackageFormatsArchive format handlers (Mix, etc.)
PackagesFile system mount points
MapFoldersMap directory locations
RulesActor rules YAML files (15 files for RA)
SequencesSprite sequence definitions (7 files)
TileSetsTerrain tile sets
CursorsCursor definitions
ChromeUI chrome YAML
Assemblies.NET assembly references
ChromeLayoutUI layout files (~50 files)
FluentMessagesLocalization strings
WeaponsWeapon definition files (6 files: ballistics, explosions, missiles, smallcaliber, superweapons, other)
VoicesVoice line definitions
NotificationsAudio notification mapping
MusicMusic track definitions
HotkeysHotkey binding files (8 files)
LoadScreenLoading screen class
ServerTraitsServer-side trait list
FontsFont definitions (8 sizes)
MapGridMap grid type (Rectangular/Isometric)
DefaultOrderGeneratorDefault order handler class
SpriteFormatsSupported sprite formats
SoundFormatsSupported audio formats
VideoFormatsSupported video formats
TerrainFormatTerrain format handler
SpriteSequenceFormatSprite sequence handler
GameSpeedsSpeed presets (slowest→fastest, 80ms→20ms)
AssetBrowserAsset browser extensions

36. World Traits (Global Game State)

TraitPurpose
ActorMapSpatial index of all actors (19KB)
ActorMapOverlayActorMap debug visualization
ScreenMapScreen-space actor lookup
ScreenShakerScreen shake effects
DebugVisualizationsDebug rendering toggles
ColorPickerManagerPlayer color management
ValidationOrderOrder validation pipeline
OrderEffectsOrder visual/audio feedback
AutoSaveAutomatic save game
LoadWidgetAtGameStartInitial widget loading

37. Game Speed Configuration

SpeedTick Interval
Slowest80ms
Slower50ms
Default40ms
Fast35ms
Faster30ms
Fastest20ms

38. Damage Model

Damage Flow

  1. Armament fires Projectile at target
  2. Projectile travels/hits using projectile-specific behavior
  3. Warhead(s) applied at impact point
  4. Warhead checks target validity (target types, stances)
  5. DamageWarhead / SpreadDamageWarhead calculates raw damage
  6. Armor type lookup against weapon’s Versus table
  7. DamageMultiplier traits modify final damage
  8. Health reduced

Key Damage Types

  • Spread damage — Falloff over radius
  • Target damage — Direct damage to specific target
  • Health percentage — Percentage-based damage
  • Terrain damageDamagedByTerrain for standing in hazards

Damage Modifiers

  • DamageMultiplier — Generic incoming damage modifier
  • HandicapDamageMultiplier — Player handicap
  • FirepowerMultiplier — Outgoing damage modifier
  • HandicapFirepowerMultiplier — Player handicap firepower
  • TerrainModifiesDamage — Infantry terrain modifier (prone, etc.)

39. Developer / Debug Tools

In-Game Debug

TraitPurpose
DeveloperModeInstant build, give cash, unlimited power, build anywhere, fast charge, etc.
CombatDebugOverlayCombat range and target debug
ExitsDebugOverlayBuilding exit debug
ExitsDebugOverlayManagerManages exit overlays
WarheadDebugOverlayWarhead impact debug
DebugVisualizationsMaster debug toggle
RenderDebugStateActor state text debug
DebugPauseStatePause state debugging

Debug Overlays

OverlayPurpose
ActorMapOverlayActor spatial grid
TerrainGeometryOverlayTerrain cell borders
CustomTerrainDebugOverlayCustom terrain types
BuildableTerrainOverlayBuildable cells
CellTriggerOverlayScript cell triggers
HierarchicalPathFinderOverlayPathfinder hierarchy
PathFinderOverlayPath search debug
MarkerLayerOverlayMap markers

Performance Debug

Widget/LogicPurpose
PerfGraphWidgetRender/tick performance graph
PerfDebugLogicPerformance statistics display

Asset Browser

LogicPurpose
AssetBrowserLogicBrowse all mod sprites, audio, video assets

Summary Statistics

CategoryCount
Actor Traits (root)~130
Render Traits~80
Condition Traits~34
Multiplier Traits~20
Building Traits~35
Player Traits~27
World Traits~55
Attack Traits7
Air Traits4
Infantry Traits3
Sound Traits9
Palette Traits17
Palette Effects5
Power Traits5
Radar Traits3
Support Power Traits10
Crate Traits13
Bot Modules12
Projectile Types8
Warhead Types15
Widget Types~60
Widget Logic Classes~40+
Lua Global APIs16
Lua Actor Properties34
Order Generators/Targeters11
Total Cataloged Features~700+