Iron Curtain — Design Documentation

Project: Rust-Native RTS Engine

Status: Pre-development (design phase)
Date: 2026-02-19
Codename: Iron Curtain
Author: David Krasnitsky

What This Is

A Rust-native RTS engine that supports OpenRA resource formats (.mix, .shp, .pal, YAML rules) and reimagines internals with modern architecture. Not a clone or port — a complementary project offering different tradeoffs (performance, modding, portability) with full OpenRA mod compatibility as the zero-cost migration path. OpenRA is an excellent project; IC explores what a clean-sheet Rust design can offer the same community.

Document Index

LLM feature overview (optional / experimental): See Experimental LLM Modes & Plans for a consolidated overview of planned LLM gameplay modes, creator tooling, and external-tool integrations. The project is fully designed to work without any LLM configured.

Key Architectural Invariants

These are non-negotiable across the entire project:

1. Simulation is pure and deterministic. No I/O, no floats, no network awareness. Takes orders, produces state. Period.
2. Network model is pluggable via trait. GameLoop<N: NetworkModel, I: InputSource> is generic over both network model and input source. The sim has zero imports from ic-net. They share only ic-protocol. Within the lockstep family (all shipping implementations), swapping network backends touches zero sim code. Non-lockstep architectures (rollback, FogAuth) would also leave ic-sim untouched but may require game loop extension in ic-game.
3. Modding is tiered. YAML (data) → Lua (scripting) → WASM (power). Each tier is optional and sandboxed.
4. Bevy as framework. ECS scheduling, rendering, asset pipeline, audio — Bevy handles infrastructure so we focus on game logic. Custom render passes and SIMD only where profiling justifies it.
5. Efficiency-first performance. Better algorithms, cache-friendly ECS, zero-allocation hot paths, simulation LOD, amortized work — THEN multi-core as a bonus layer. A 2-core laptop must run 500 units smoothly.
6. Real YAML, not MiniYAML. Standard serde_yaml with inheritance resolved at load time.
7. OpenRA compatibility is at the data/community layer, not the simulation layer. Same mods, same maps, shared server browser — but not bit-identical simulation.
8. Full resource compatibility with Red Alert and OpenRA. Every .mix, .shp, .pal, .aud, .oramap, and YAML rule file from the original game and OpenRA must load correctly. This is non-negotiable — the community’s existing work is sacred.
9. Engine core is game-agnostic. No game-specific enums, resource types, or unit categories in engine core. Positions are 3D (WorldPos { x, y, z }). System pipeline is registered per game module, not hardcoded.
10. Platform-agnostic by design. Input is abstracted behind InputSource trait. UI layout is responsive (adapts to screen size via ScreenClass). No raw std::fs — all assets go through Bevy’s asset system. Render quality is runtime-configurable.

Crate Structure Overview

iron-curtain/
├── ic-cnc-content     # Wraps cnc-formats + EA-derived code; Bevy asset integration; MiniYAML auto-conversion pipeline (C&C-specific, keeps ra- prefix)
├── ic-protocol    # PlayerOrder, TimestampedOrder, OrderCodec trait (SHARED boundary)
├── ic-sim         # Deterministic simulation (Bevy FixedUpdate systems)
├── ic-net         # NetworkModel trait + implementations; RelayCore library (no ic-sim dependency)
├── ic-render      # Isometric rendering, shaders, post-FX (Bevy plugin)
├── ic-ui          # Game chrome: sidebar, minimap, build queue (Bevy UI)
├── ic-editor      # SDK: scenario editor, asset studio, campaign editor, Game Master mode (D038+D040, Bevy app)
├── ic-audio       # .aud playback, EVA, music (Bevy audio plugin)
├── ic-script      # Lua + WASM mod runtimes
├── ic-ai          # Skirmish AI, mission scripting, LLM-enhanced AI strategies (depends on ic-llm)
├── ic-llm         # LlmProvider trait, prompt infra, skill library, Tier 1 CPU inference (traits + infra only — no ic-sim)
├── ic-paths       # Platform path resolution: data dirs, portable mode, credential store
├── ic-game        # Top-level Bevy App, ties all game plugins together (NO editor code)
└── ic-server      # Unified server binary (D074): depends on ic-net (RelayCore) + optionally ic-sim (for FogAuth/relay-headless deployments)

License

All files in src/ and research/ are licensed under CC BY-SA 4.0. Engine source code is licensed under GPL v3 with an explicit modding exception (D051).

Trademarks

Red Alert, Tiberian Dawn, Command & Conquer, and C&C are trademarks of Electronic Arts Inc. Iron Curtain is not affiliated with, endorsed by, or sponsored by Electronic Arts.

Foreword — Why I’m Building This

I’ve been a Red Alert fan since the first game came out. I was a kid, playing at a friend’s house over what we’d now call a “LAN” — two ancient computers connected with a cable. I was hooked. The cutscenes, the music, building a base and watching your stuff fight. I would literally go to any friend’s house that could run this game just to play it.

That game is the reason I wanted to learn how computers work. Someone, somewhere, built that. I wanted to know how.

Growing Up

I started programming at 12 — Pascal. Wrote little programs, thought it was amazing, and then looked at what it would actually take to make a game that looks and feels and plays real good. Yeah, that was going to take a while.

I went through a lot of jobs and technologies over the years. Network engineering, backend development, automations, cyber defense. I wrote Java for a while, then Python for many years. Each job taught me things I didn’t know I’d need later. I wasn’t chasing a goal — I was just building a career and getting better at making software.

Along the way I discovered Rust. It clicked. Most programming languages make you choose: either you get full control over your computer’s resources (but risk hard-to-find bugs and crashes), or you get safety (but give up performance). Rust gives you both. The language is designed so that entire categories of bugs — the kind that cause crashes, security holes, and impossible-to-reproduce errors — simply can’t happen. The compiler catches them before the program ever runs. You can write high-performance code and actually sleep at night.

I also found OpenRA around this time, and I was glad an open-source community had kept Red Alert alive for so long. I browsed through the C# codebase (I know C# well enough), enjoyed poking around the internals, but eventually real life pulled me away.

I did buy a Rust game dev book though. Took some Udemy courses. Played with prototypes. The idea of writing a game in Rust never quite left.

The Other Games That Mattered

I was a gamer my whole life, and a few games shaped how I think about making games, not just playing them.

Half-Life — I spent hours customizing levels and poking at its mechanics. Same for Deus Ex — pulling apart systems, seeing how things connected.

But the one that really got me was Operation Flashpoint: Cold War Crisis (now ArmA: Cold War Assault). OFP had a mission editor that was actually approachable. You could create scenarios in simple ways, dig through its resources and files, and build something that felt real. I spent more time editing missions, campaigns, and multiplayer scenarios for OFP than playing any other game. Recreating movie scenes, building tactical situations, making co-op missions for friends — that was my thing.

What OFP taught me is that the best games are the ones that give you tools and get out of your way. Games as platforms, not just products. That idea stuck with me for twenty years, and it’s a big part of why Iron Curtain works the way it does.

How This Actually Started

Over five years, Rust became my main language. I built backend systems, contributed to open-source projects, and got to the point where I could think in Rust the way I used to think in Python. The idea kept nagging: what if I tried writing a Red Alert engine in Rust?

Then, separately, I got into LLMs and AI agents. I was between jobs and decided to learn the tooling by building real projects with it. Honestly, I hated it at first. The LLM would generate a bunch of code, and I’d spend all my time reviewing and correcting it. It got credit for the fun part.

But the tools got better, and so did I. What changed is that they made it realistic to take on big, complex solo projects with proper architecture. Break everything down, make each piece testable, follow best practices throughout. The tooling caught up with what I already knew how to do.

This project didn’t start as an attempt to replace OpenRA. I just wanted to test new technology — see if Rust, Bevy, and LLM-assisted development could come together into something real. A proof of concept. A learning exercise. But the more I thought about the design, the more I realized it could actually serve the community. That’s when I decided to take it seriously.

This project is also a research opportunity. I want to take LLM-assisted coding to the next level — not just throw prompts at a model and ship whatever comes back. I’m a developer who needs to understand what code does. When code is generated, I do my best to read through it, understand every part, and verify it. I use the best models available to cross-check, document, and maintain a consistent code style so the codebase stays reviewable by humans.

There’s a compounding effect here: as the framework and architecture become more solid, the rules for how the LLM creates and modifies code become more focused and restricted. The design docs, the invariants, the crate boundaries — they all constrain what the LLM can do, which reduces the chance of serious errors. On top of that, I’m a firm believer in verifying code with tests and benchmarks. If it’s not tested, it doesn’t count.

If you’re curious about the actual methodology — how research is conducted, how decisions are made, how the human-agent relationship works in practice, and exactly how much work is behind these documents — see Chapter 14: Development Methodology, particularly the sections on the Research-Design-Refine cycle and Research Rigor. The short version: 76 design decisions, 63 standalone research documents, 20+ open-source codebases studied at the source code level, ~95,000 lines of design and research documentation, 160+ commits of iterative refinement. None of it generated in a few prompts. All of it human-directed, human-reviewed, and human-committed.

What Bugged Me About the Alternatives

OpenRA is great for what it is. But I’ve felt the lag — not just in big battles, it’s random. Something feels off sometimes. The Remastered Collection has the same problem, which made me wonder if they went the C# route too — and it turns out they did. The original C++ engine runs as a DLL, but the networking and rendering layers are handled by a proprietary C# client. For me it comes down to raw performance: the original Red Alert was written in C, and it ran close to the hardware. C# doesn’t.

The Remastered Collection has the same performance issues. Modding is limited. Windows and Xbox only.

I kept thinking about what Rust brings to the table:

• Fast like C — runs close to the hardware, no garbage collector, predictable performance
• Safe — the compiler prevents the kinds of bugs that cause crashes and security vulnerabilities in other languages
• Built for multi-core — modern CPUs have many cores, and Rust makes it safe to use all of them without the concurrency bugs that plague other languages
• Here to stay — it’s in the Linux kernel, backed by every major tech company, and growing fast

What I Wanted to Build

Once I committed, the ideas came fast.

Bevy was the obvious engine choice. It’s the most popular community-driven Rust game engine, it uses a modern architecture that’s a natural fit for RTS games (where you need to efficiently manage thousands of units at once), and there’s a whole community of people working on it constantly. Building on top of Bevy means inheriting their progress instead of reinventing rendering, audio, and asset pipelines from scratch. And it means modders get access to a real modern rendering stack — imagine toggling between classic sprites and something with dynamic water, weather effects, proper lighting. Or just keeping it classic, but smooth.

Cross-engine compatibility — I wanted OpenRA players and Iron Curtain players to coexist. My background includes a lot of work translating between different systems, and the same principles apply here.

Switchable netcode — inspired by how CS2 does sub-tick processing and relay servers. If we pick the wrong networking model, or something better comes along, we should be able to swap it without touching the simulation code.

Community independence — the game should never die because someone turns off a server. Self-hosted everything. Federated workshop. No single point of failure.

Security done through architecture — not a kernel-level anti-cheat, but real defenses: order validation inside the simulation, signed replays, relay servers that own the clock. Stuff that comes from building backend systems and knowing how people cheat.

LLM-generated missions — this is the part that excites me most. What if you could describe a scenario in plain English and get a playable mission? Like OFP’s mission editor, but you just tell it what you want. The output is standard YAML and Lua, fully editable. You bring your own LLM — local or cloud, your choice. The game works perfectly without one, but for those who opt in: infinite content.

Where This Is Now

I put all of these ideas together and did a serious research phase to figure out what’s actually feasible. These design documents are the result. They cover architecture, networking, modding, security, performance, file format compatibility, cross-engine play, and a 36-month roadmap.

Every decision has a rationale. Every system has been thought through against the others. It’s designed to be built piece by piece, tested in isolation, and contributed to by anyone who cares to.

What started as “can I get this to work?” turned into “how do I make sure everything I build can serve the community?” That’s where I am now.

My goal is simple: make us fall in love again.

— David Krasnitsky, February 2026

What Iron Curtain Offers

Iron Curtain is a new open-source RTS engine built for the Command & Conquer community. It loads your existing Red Alert and OpenRA assets — maps, mods, sprites, music — and plays them on a modern engine designed for performance, modding, and competitive play. Ships with Red Alert and Tiberian Dawn, with more C&C titles and community-created games to follow.

This project is in design phase — no playable build exists yet. Everything below describes design targets, not shipped features.

For Players

• Smooth performance, even in large battles. No random stutters or micro-freezes. Rust has no garbage collector; Bevy’s ECS gives cache-friendly memory layout; zero allocation during gameplay. Target: 500 units smooth on a 2012 laptop, 2000+ on modern hardware.
• Multiplayer that doesn’t randomly break. No more matches silently falling out of sync with no explanation. Fixed-point integer math guarantees every player’s game stays in sync, and when something does go wrong, the engine pinpoints exactly what diverged.
• Play on any device. Windows, macOS, Linux, Steam Deck, browser (WASM), and mobile — all planned from day one via platform-agnostic architecture.
• Complete campaigns that flow. All original campaigns fully playable. Continuous mission flow (briefing → mission → debrief → next) — no exit-to-menu between levels.
• Two campaign modes. Play the original 14 missions per side in their classic form — linear, faithful, complete. Or play the Enhanced Edition, where those same missions become milestones in a strategic campaign with a War Table, side operations, enemy initiatives, and a dynamic arms race that shapes every battle ahead. The classic path is always available; the Enhanced Edition is for players who want to command a war.
• The War Table. Between milestone missions, the War Table presents available operations (authored and procedurally generated), enemy initiatives to counter or absorb, and a live arms-race readout. Every operation is a real RTS mission with concrete rewards — capture a prototype, deny an enemy weapon program, recruit resistance fighters, rescue a captured hero. You choose which operations to run, but you can’t do them all. That opportunity cost is the strategic game.
• A dynamic arms race. Expansion-pack units are campaign rewards, not linear unlocks. Capture a Chrono Tank through an Italy operation. Prevent the enemy’s super-soldier program through intelligence raids. The commando path yields full-quality tech; the commander path trades precision for broader denial. Three-state outcomes (acquired / partial / denied) mean every technology has a story. The final mission is different every playthrough — different units, different threats, different approach routes, different briefing text — because it reflects every choice you made across the campaign.
• Branching and persistent. Your choices create different paths. Surviving units, veterancy, and equipment carry over between missions. Defeat is another branch, not a game over.
• Choose your own balance. Classic Westwood, OpenRA, or Remastered tuning — a lobby setting, not a mod. Tanya and Tesla coils feel as powerful as you remember, or as balanced as competitive play demands.
• Choose your country or institution (proposed). Allies pick a nation (England, France, Germany, Greece) with a thematic bonus reflecting their alternate-timeline identity. Soviets pick a competing power structure (Red Army, NKVD, GRU, Science Bureau) — each with a distinct playstyle. Same mechanic, different narrative framing. Adds variety to mirror matches with reasonable balance overhead. Community can add more via YAML modding. (Under research — see research/subfaction-country-system-study.md. Requires D019 integration and community feedback before formal adoption.)
• Switchable pathfinding. Three movement models: Remastered (original feel), OpenRA (improved flow), IC Default (flowfield + ORCA-lite). Select per lobby or per scenario. Modders can ship custom pathfinding via WASM.
• Switchable render modes. Toggle Classic/HD/3D mid-game (F1 key, like the Remastered Collection). Different players can use different render modes in the same multiplayer game.
• Switchable AI opponents. Classic Westwood, OpenRA, or IC Default AI — selectable per AI slot. Two-axis difficulty (engine scaling + behavioral tuning). Mix different AI personalities and difficulties in the same match.
• Five ways to find a game. Direct IP, Among Us-style room codes, QR codes (LAN/streaming), server browser, ranked matchmaking queue — plus Discord/Steam deep links.
• Built-in voice and text chat. Push-to-talk voice (Opus codec, relay-forwarded), text chat with team/all/whisper/observer channels. Contextual ping system (8 types + ping wheel), chat wheel with auto-translated phrases, minimap drawing, tactical markers. Voice optionally recorded in replays (opt-in). Speaking indicators in lobby and in-game.
• Command console. Unified / command system — every GUI action has a console equivalent. Developer overlay, cvar system, tab completion with fuzzy matching. Hidden cheat codes (Cold War phrases) for single-player fun.
• Your data is yours. All player data stored locally in open SQLite files — queryable by any tool that speaks SQL. 24-word recovery phrase restores your identity on any machine, no account server needed. Full backup/restore via ic backup CLI. Optional Steam Cloud / GOG Galaxy sync for critical data.

For Competitive Players

• Ranked matchmaking. Glicko-2 ratings, seasonal rankings with Cold War military rank themes, 10 placement matches, optional per-faction ratings. Map veto system with anonymous opponent during selection.
• Player profiles. Avatar, title, achievement showcase, verified statistics, match history, friends list, community memberships. Reputation data is cryptographically signed — no fake stats.
• Architectural anti-cheat. Relay server owns the clock (blocks lag switches and speed hacks). Deterministic order validation (all clients agree on legality). No kernel drivers, no invasive monitoring — works on Linux and in browsers.
• Tamper-proof replays. Ed25519-signed replays and relay-certified match results. No disputes.
• Tournament mode. Caster view (no fog), player-perspective spectating, configurable broadcast delay (1–5 min), bracket integration, server-side replay archive.
• Sub-tick fairness. Orders processed in the order they happened, not the order packets arrived. Adapted from Counter-Strike 2’s sub-tick architecture.
• Train against yourself. AI mimics a specific player’s style from their replays. “Challenge My Weakness” mode targets your weakest skills for focused practice.
• Foreign replay import. Load and play back OpenRA and Remastered Collection replays directly. Convert to IC format for analysis. Automated behavioral regression testing against replay corpus.
• Fair-play match controls. Ready-check before match start. In-match voting — kick griefers, remake broken games, mutual draw — with anti-abuse protections (premade consolidation, army-value checks). Pause and surrender with ranked penalty framework.
• Disconnect handling. Grace period for brief disconnects, abandon penalties with escalating cooldowns, match voiding for early exits. Remaining teammates choose to play on (with AI substitute) or surrender.
• Spectator anti-coaching. In ranked team games, live spectators are locked to one team’s perspective — the relay won’t send opposing orders until the broadcast delay expires.

For Modders

• Your existing work carries over. Loads OpenRA YAML rules, maps, sprites, audio, and palettes directly. MiniYAML auto-converts at runtime. Migration tool included.
• Mod without programming. 80% of mods are YAML data files — change a number, save, done. Standard YAML means IDE autocompletion and validation work out of the box.
• Three tiers, no recompilation. YAML for data. Lua for scripting (missions, AI, abilities). WASM for engine-level mods (new mechanics, total conversions) in any language — sandboxed, near-native speed.
• Scenario editor. Full SDK with 30+ drag-and-drop modules across 8 categories: terrain painting, unit placement, visual trigger editor, reusable compositions (publishable to Workshop), layers with runtime show/hide, media & cinematics (video playback, cinematic sequences, dynamic mood-based music, ambient sound zones, EVA notifications with priority queuing). Campaign editor with visual graph and weighted random paths. Game Master mode for live scenario control. Simple and Advanced modes with onboarding profiles for veterans of other editors.
• Asset studio. Visual asset browser (XCC Mixer replacement), sprite/palette/terrain editors, bidirectional format conversion (SHP↔PNG, AUD↔WAV, VQA↔WebM), UI theme designer. Hot-reload bridge between editor and running game.
• Workshop for everything, not just mods. Publish individual music tracks, sprite sheets, voice packs, balance presets, UI themes, script libraries, maps, campaign chapters, or full mods — each independently versioned, licensed, and dependable. A mission pack can depend on a music pack and an HD sprite pack without bundling either.
• Auto-download on lobby join. Join a game → missing content downloads automatically via P2P (BitTorrent/WebTorrent). Lobby peers seed directly — fast and free. Auto-downloaded content cleans itself up after 30 days of non-use; frequently used content auto-promotes to permanent.
• Dependency resolution. Cargo-style semver ranges, lockfile with SHA-256 checksums, transitive resolution, conflict detection. ic mod tree shows your full dependency graph. ic mod audit checks license compatibility.
• Reusable script libraries. Publish shared Lua modules (AI behaviors, trigger templates, UI helpers) as Workshop resources. Other mods require() them as dependencies — composable ecosystem instead of copy-paste.
• CI/CD publishing. Headless CLI with scoped API tokens. Tag a release in git → CI validates, tests, and publishes to the Workshop automatically. Beta/release promotion channels.
• Federated and self-hostable. Official server, community mirrors, local directories, and Steam Workshop — all appear in one merged view. Offline bundles for LAN parties. No single point of failure.
• Creator tools. Reputation scores, badges (Verified, Prolific, Foundation), download analytics, collections, ratings & reviews, DMCA process with due process. LLM agents can discover and pull resources with author consent (ai_usage permission per resource).
• Hot-reload. Change YAML or Lua, see it in-game immediately. No restart.
• Console command extensibility. Register custom / commands via Lua or WASM — with typed arguments, tab completion, and permission levels. Publish reusable .iccmd command scripts to the Workshop.
• Mod profiles. Save a named set of mods + experience settings as a shareable TOML file (D067). One SHA-256 fingerprint replaces per-mod version checking in lobbies. ic profile save/activate/inspect/diff CLI. Publish profiles to the Workshop as modpacks.

For Content Creators & Tournament Organizers

• Observer and casting tools. No-fog caster view, player-perspective spectating, configurable broadcast delay, signed replays.
• Creator recognition. Reputation scores, featured badges, optional tipping links — credit and visibility for modders and creators.
• Player analytics. Post-game stats, career pages, campaign dashboards. Every ranked match links to its replay.

For Community Leaders & Server Operators

• Self-hostable everything. A single ic-server binary (D074) with toggleable capability flags handles relay, matchmaking, ranking, Workshop P2P seeding, and moderation. Federated architecture — communities mirror each other’s content. Ed25519-signed credential records (not JWT) with transparency logs for server accountability. No single point of failure.
• Community governance. RFC process, community-elected representatives, self-hosting independence. The project can’t be killed by one organization.
• Observability. OTEL-based telemetry (metrics, traces, logs), pre-built Grafana dashboards for self-hosters. Zero-cost when disabled.

For Developers & Contributors

• Modern Rust on Bevy. No GC, memory safety, fearless concurrency. ECS scheduling, parallel queries, asset hot-reloading, large plugin ecosystem. 14 focused crates with clear boundaries.
• Clean sim/net separation. ic-sim and ic-net never import each other — only ic-protocol. Swap the network model without touching simulation code.
• Multi-game engine. Game-agnostic core. RA and TD are game modules via a GameModule trait. Pathfinding, spatial queries, rendering, fog — all pluggable per game.
• Standalone crates. ic-cnc-content parses C&C formats independently. ic-sim runs headless for AI training or testing.

Nice-to-Haves

Interested specifically in the LLM-related gameplay/content/tooling plans? See Experimental LLM Modes & Plans for a consolidated overview (all experimental / optional). IC ships built-in CPU models (Tier 1) for zero-config operation; external LLM providers (BYOLLM Tiers 2–4) are optional for higher quality.

• AI-generated missions and campaigns. Describe a scenario, get a playable mission — or generate an entire branching campaign with recurring characters who evolve, betray, and die based on your choices. Choose a story style (C&C Classic, Realistic Military, Political Thriller, and more). World Domination mode: conquer a strategic map region by region with garrison management and faction dynamics. Each mission reacts to how you actually played — the LLM reads your battle report and adapts the next mission’s narrative, difficulty, and objectives. Mid-mission radar comms, RPG-style dialogue choices, and cinematic moments are all generated. Every output is standard YAML + Lua, fully playable without the LLM after creation. Built-in mission templates provide a fallback without any LLM at all. IC ships built-in CPU models for zero-config operation; external LLM providers unlock higher quality. Phase 7.
• AI-generated custom factions. Describe a faction concept in plain English — “a guerrilla faction that relies on stealth, traps, and hit-and-run” — and the LLM generates a complete tech tree, unit roster, building roster, and unique mechanics as standard YAML. References Workshop sprite packs, sound packs, and weapon definitions (with author consent) to assemble factions with real assets from day one. Balance-validated against existing factions. Fully editable by hand, publishable to Workshop, playable in skirmish and custom games. Phase 7.
• LLM-enhanced AI. Two modes: LlmOrchestratorAi wraps conventional AI with LLM strategic guidance, LlmPlayerAi lets the LLM play the game directly — designed for community entertainment streams (“GPT vs. Claude playing Red Alert”). Observable reasoning overlay for spectators. Neither mode allowed in ranked. Phase 7.
• LLM coaching. Post-match analysis, personalized improvement suggestions, and adaptive briefings based on your play history. Phase 7.
• LLM Skill Library. Persistent, semantically-indexed store of verified LLM outputs — AI strategies and generation patterns that improve over time. Verification-to-promotion pipeline ensures quality. Shareable via Workshop. Voyager-inspired lifelong learning. Phase 7.
• Dynamic weather. Real-time transitions (sunny → rain → storm), terrain effects (frozen water, mud), snow accumulation. Deterministic weather state machine.
• Advanced visuals for modders. Bevy’s wgpu stack gives modders access to bloom, dynamic lighting, GPU particles, shader effects, day/night, smooth zoom, and even full 3D rendering — while the base game stays classic isometric. Render modes are switchable mid-game (see above).
• Switchable UI themes. Classic, Remastered, or Modern look — YAML-driven, community themes via Workshop.
• Achievements. Per-game-module, mod-defined via YAML + Lua, Steam sync.
• Toggleable QoL. Every convenience (attack-move, health bars, range circles) individually toggleable. Experience profiles bundle 6 axes — balance + AI preset + pathfinding preset + QoL + UI theme + render mode: “Vanilla RA,” “OpenRA,” “Remastered,” or “Iron Curtain.”

How This Was Designed

The networking design alone studied 20+ open-source codebases, 4 EA GPL source releases, and multiple academic papers — all at the source code level. Every major subsystem went through the same process. 76 design decisions with rationale. 63 research documents. ~95,000 lines of design and research documentation across 160+ commits.

📖 Read the full design documentation →

Iron Curtain — Platform Capabilities

Everything you get when you choose Iron Curtain as your RTS platform — whether you’re a player, a modder, a map maker, or building a total conversion.

For Players

Gameplay Modes

The Red Alert Experience — Faithful and Enhanced

IC recreates the Red Alert feel using values verified against EA source code, then adds quality-of-life features that don’t break the classic identity:

Faithfully Recreated:

• Palette-indexed sprite rendering with all original SHP draw modes (shadow, ghost, predator)
• Isometric 14-layer Z-order (terrain → shadows → buildings → units → aircraft → projectiles → effects → UI)
• Credit counter with ticking animation, power bar with green/yellow/red states
• EVA voice system with priority queuing (rare notifications don’t get lost)
• Unit voice pools with no-immediate-repeat selection
• Dynamic music (combat/build/victory transitions honoring Frank Klepacki’s intent)

IC Enhancements (New Features With No Classic RA Equivalent):

• Attack-move (default on), rally points, parallel factories, unit stances (Aggressive/Defensive/Hold/Return Fire)
• Smart box-select (harvesters deprioritized), camera bookmarks (F5-F8)
• Dynamic weather system affecting movement and terrain passability (D022)
• Veterancy promotions with visible rank indicators and stat bonuses
• Render mode toggle (F1): Classic / HD / 3D — switchable mid-game (D048)

Customization — Play Your Way

IC doesn’t force one way to play. Every axis is independently composable:

Balance Presets (D019):

• Classic (original EA values — frozen, never changes)
• OpenRA (tracks upstream OpenRA balance patches)
• Remastered Collection
• IC Default (patched once per ranked season based on telemetry)
• Custom (player-editable YAML)

Subfaction Selection (proposed — under research):

• Allies pick a nation — England, France, Germany, Greece — each with a thematic passive and one tech tree modification reflecting their alternate-timeline military tradition
• Soviets pick an institution — Red Army, NKVD, GRU, Soviet Science Bureau — competing power structures within the totalitarian state, each with a distinct playstyle identity
• Narrative asymmetry (countries vs. institutions) with mechanical symmetry (both sides get 1 passive + 1 tech tree mod) — reasonable balance overhead
• Classic preset uses original RA1 country bonuses (5 countries, 10% passives); IC Default uses the expanded 4×4 system; Custom/modded subfactions via YAML inheritance
• Community can add new countries or institutions via Tier 1 YAML modding (no code required)
• See research/subfaction-country-system-study.md for full design rationale and industry research. Requires D019 integration and community feedback before formal adoption

Experience Profiles (D033):

• Vanilla RA, OpenRA, Remastered, or Iron Curtain — each bundles balance + theme + QoL + AI + pathfinding + render mode
• Override any individual axis in the lobby
• Create and share custom profiles via Workshop

Quality of Life Toggles (D033):

• Production: attack-move, waypoint queue, multi-queue, rally points, parallel factories
• Commands: force-fire, force-move, guard, scatter, unit stances
• UI: health bars, range circles, build radius, target lines, selection outline
• Selection: box shape (diamond/rectangle), smart type cycling
• All individually toggleable, not locked to presets

Pathfinding Variants (D045):

• Remastered (original feel), OpenRA (improved A*), IC Default (flowfield + ORCA-lite hybrid)
• Per-lobby selection, mod-extensible via WASM

AI Personality & Difficulty (D043):

• Named AI Commanders with portraits, specializations, visible agendas, and contextual taunts (Generals ZH / Civ 5 pattern)
• 6 built-in RA1 commanders (Col. Volkov — Armor, Cmdr. Nadia — Intel, Gen. Kukov — Brute Force, Cdr. Stavros — Air, Col. von Esling — Defense, Lt. Tanya — Spec Ops)
• Two-axis tuning: commander persona (aggression, expansion, tech preference) × engine difficulty scaling (resource bonuses)
• Mix different commanders in the same match — each AI slot picks independently
• Puppet Master strategic guidance: optional external advisor (LLM, human coach, or future types) that directs AI objectives without replacing tick-level control; Masterless by default
• Community commanders via Workshop (YAML — no code required); LLM-generated commanders (Phase 7)
• Replay-based behavioral mimicry: AI learns from your replays (D042)

Multiplayer Infrastructure

• Relay servers eliminate lag-switching and host advantage — relay owns the clock (D007)
• Sub-tick fairness — orders from faster and slower players processed fairly (D008)
• Adaptive run-ahead — client predicts during lag, corrects without rubber-banding
• Encrypted transport — X25519 key exchange, AES-256-GCM authenticated encryption, Ed25519 identity binding (TransportCrypto)
• Community servers — single ic-server binary with toggleable capability flags (relay, matchmaking, ranking, Workshop P2P seeding, moderation) and federated trust (D074)
• Cross-engine browser — see OpenRA and CnCNet games from the IC client (D011)
• Portable identity — 24-word recovery phrase; restore on any machine (D061)

Replays & Analysis

• Auto-recording of all matches with Match ID system
• Arbitrary seeking (forward and backward) via keyframe re-simulation
• 5 camera modes: free, player perspective, follow unit, directed (AI auto-follows action), drone cinematic
• Observer overlays: army composition, production queues, economy, powers, score, APM
• Heatmaps: unit death, combat, camera attention, economy
• Graphs: army value, income, unspent resources, APM — all clickable (jump to that moment)
• Video export (WebM) with cinematic camera path editor, lens controls, letterbox
• Foreign replay import — play OpenRA .orarep and Remastered replays with divergence tracking (D056)
• Anonymization for sharing (strip names, voice, chat)

Workshop & Content

• Browse and install maps, mods, campaigns, themes, AI presets, music, sprites, voice packs, and more
• One-click mod profiles — save different mod combinations, switch instantly
• Auto-download on lobby join — missing content installs automatically (P2P preferred, HTTP fallback)
• Mod fingerprint — SHA-256 hash ensures all players have identical rules
• Federated mirrors — official server, community mirrors, local directories; works offline with bundles

Tutorial & Onboarding (D065)

• Commander School — 6-mission dopamine-first tutorial campaign (blow things up first, learn economy later)
• IC-aware hints — veterans see “IC adds rally points,” newcomers see “Right-click to set a rally point”
• Feature Smart Tips — non-intrusive contextual tips on Workshop, Settings, Profile, and Main Menu screens
• Adaptive pacing — hint frequency scales with demonstrated skill
• Post-game learning — “You had 15 idle harvester seconds” with replay moment links

Platform Support

For Modders & Content Creators

Three-Tier Modding System

Each tier is optional and sandboxed. No C# runtime. No engine recompilation. No forking.

OpenRA Compatibility — Bring Your Existing Work

Scenario Editor (SDK — D038)

A full visual mission editor inspired by OFP’s mission editor and Arma 3’s Eden Editor:

12 editing modes: Terrain (paint tiles/resources/cliffs/water), Entities (place units/buildings/props), Groups (squad organization), Triggers (area-based conditional logic), Waypoints (OFP F4-style visual route authoring), Connections (visual trigger/waypoint linking), Modules (30+ drag-and-drop logic blocks), Regions (named spatial zones), Layers (dynamic mission expansion), Portals (sub-map transitions), Scripts (Lua file browser/editor), Campaign (mission graph wiring)

Key capabilities:

• Simple/Advanced mode — same data model, different UI complexity; beginners place units in minutes, advanced users add triggers and scripting
• Entity placement with double-click, naming (variable names for scripts), faction assignment, probability of presence, condition of presence, veterancy, health, inline Lua init scripts
• Trigger system — area-based with conditions (unit present/destroyed/captured/built), min/mid/max randomized timers, repeatable/one-shot, Lua escape hatch for custom conditions
• Module system — 30+ pre-built logic nodes: Wave Spawner, Patrol Route, Guard Position, Reinforcements, Destroy Target, Capture Building, Defend Position, Escort Convoy, Weather Change, Camera Pan, Cinematic Sequence, Map Segment Unlock, Sub-Scenario Portal, Tutorial Step, Spectator Bookmark, and more
• Waypoints — visual route authoring with types (Move, Attack, Guard, Patrol, Harvest, Script, Wait), synchronization lines for multi-group coordination, route naming for script reference
• Mission outcomes — named outcome triggers (Mission.Complete("victory_bridge_intact")) wired to campaign branch graph
• Compositions — reusable prefabs (base layouts, defensive formations, scripted encounters) saved and shared via Workshop
• Preview / Test / Validate / Publish toolbar — Test launches real game runtime; Validate checks rules asynchronously; Publish Readiness aggregates all warnings
• Git-first collaboration — stable content IDs, canonical serialization, semantic diff/merge helpers
• Undo/redo + autosave with crash recovery
• Interactive guided tours — 10 built-in step-by-step walkthroughs with spotlight overlay and validation (D038)
• F1 context help — opens authoring manual page for any selected element

Asset Studio (SDK — D040)

XCC Mixer replacement with visual editing — no command-line tools needed:

• Browse .mix/.big/.oramap archives with extraction
• View sprites (.shp/.png with palette), palettes (.pal), terrain tiles (.tmp), audio (.aud/.wav/.ogg), video (.vqa/.mp4/.webm), 3D models (.gltf/.vxl)
• Edit palettes (remap, faction colors, hue shifts), sprite sheets (reorder frames, adjust timing, composite layers), terrain tiles (connectivity rules, transitions), chrome/themes (9-slice panels, live menu preview)
• Convert bidirectionally: SHP ↔ PNG, AUD ↔ WAV, VQA ↔ WebM
• Import PNG → palette-quantized SHP; GLTF → game models with LODs; fonts → bitmap sheets
• Batch operations — bulk palette remap, resize, re-export across assets
• Diff/compare — side-by-side version comparison with pixel-diff highlights
• Hot-reload bridge — edit assets, see changes in running game immediately
• Provenance metadata — track source, author, license, modification history per asset
• Optional LLM-assisted generation (Phase 7) — describe a unit → LLM generates sprite sheet → iterate

Campaign System (D021)

• Branching graph backbone — missions linked by named outcomes, not linear lists
• Optional strategic layer / War Table — phase-based campaign wrapper that presents operations, enemy initiatives, and urgency between milestone missions
• Operations as a distinct campaign tier — main missions, SpecOps, theater branches, generated operations, and follow-up reveals all use the same campaign graph foundation
• Expiring opportunities — optional mission nodes with expires_in_phases timers and on_expire consequences let the world move without you
• Arms race / tech ledger — campaign-visible acquisition / denial state that changes later missions and endgame composition
• Command Authority and phase pressure — players cannot run every operation before the main mission becomes urgent
• Multiple outcomes per mission — win/loss/partial each branch differently
• No mandatory game-over — designer controls what happens on defeat (retry, fallback, consequences)
• Unit roster persistence — surviving units carry forward with veterancy, kills, equipment
• Campaign variables — Lua-accessible flags, counters, and state that persist across missions; strategic-layer campaigns also get first-class phase / initiative / ledger state
• Hero progression (optional) — XP, levels, skill trees, loadouts per named character
• Intermission / War Table screens — Hero Sheets, Skill Choice, Armory/Loadout, operation cards, and strategic readouts between missions
• Campaign Graph Editor in SDK — visual node-and-edge editing, drag missions, label outcomes, author phase metadata, validate branches

Export to Other Engines (D066)

IC scenarios can be exported to other Red Alert implementations:

• Export-safe authoring mode — live fidelity indicators (green/yellow/red) per entity/trigger
• Pattern-based trigger downcompilation — Trigger.AfterDelay() → RA1 timed trigger, Trigger.OnKilled() → destroyed trigger, etc.
• Extensible export targets — community can add Tiberian Sun, RA2, Remastered via WASM plugins
• CLI export — ic export --target openra|ra1 mission.yaml -o ./output/

The vision: IC becomes the tool the C&C community uses to create content for any C&C engine, not just IC itself.

Workshop Distribution (D030)

• Publish maps, mods, campaigns, themes, AI presets, music, sprites, voice packs, script libraries, observer layouts, camera paths, LLM configs
• Versioning — semver with dependency ranges (Cargo-style); lockfile for reproducible installs
• Licensing — SPDX identifiers with ic mod audit for compatibility checking
• Channels — dev / beta / release with promotion between channels
• P2P distribution — BitTorrent/WebTorrent for large packages; HTTP fallback
• Community mirrors — run your own Workshop server; federation with official
• Offline bundles — export resources as portable archives for LAN parties
• CI/CD integration — headless publishing via scoped API tokens; tag-based automation
• CLI: ic mod install, ic mod update, ic mod tree, ic mod audit, ic mod publish

LLM-Powered Creator Tools (Optional — D016)

Built-in CPU models (Tier 1) run locally after a one-time download; no account or external service needed. External LLM providers (BYOLLM Tiers 2–4) unlock higher quality.

• Single mission generation — text prompt → terrain, objectives, AI behavior, triggers, briefing
• Campaign generation — text description → full branching multi-mission campaign
• Natural language intent — “Soviet campaign, disgraced colonel, Eastern Front” → pre-filled campaign parameters
• Replay-to-scenario extraction — convert replay into playable mission with optional LLM-generated narrative
• Player-aware generation — LLM reads your match history for personalized missions
• LLM Orchestrator AI — strategic wrapper around conventional AI; AI handles micro
• Skill Library (D057) — persistent store of verified LLM outputs; promotes quality over time

For Engine Developers & Researchers

Deterministic Simulation Core

• Fixed-point math only (i32/i64, scale 1024) — no floats in sim; identical results on all platforms
• No I/O in sim — pure state evolution; no file, network, or clock access
• No HashMap/HashSet — BTreeMap/BTreeSet/IndexMap only; deterministic iteration
• Snapshottable state — full game state serializable for replays, save/load, crash recovery, delta encoding (D010)
• External Sim API — ic-sim is a public library crate: new(), step(), inject_orders(), query_state(), snapshot(), restore()
• Use cases: AI bot tournaments, academic research, automated testing, replay analysis tools

Pluggable Architecture (14+ Trait Seams — D041)

Every major subsystem is abstracted behind a trait — swap algorithms without forking:

Multi-Game Engine

IC is not hardcoded for Red Alert. The GameModule trait defines everything game-specific:

• Components, systems, and scheduling
• Fog model, damage model, pathfinding
• AI defaults, order validation
• Each module (RA1, TD, RA2, D2K, custom) registers its own rules
• Same engine binary runs different games via module selection

Performance

• Render-sim split — simulation at 15 Hz, rendering at 60+ FPS with interpolation
• Zero-allocation hot paths — string interning, object pooling, pre-allocated buffers
• Delta encoding — property-level change tracking; baselines (Quake 3 pattern) reduce snapshot payloads ~90%
• Amortized staggered updates — fog, AI, and pathfinding spread across multiple ticks
• Multi-layer pathfinding — hierarchical sectors + JPS + flowfield + ORCA-lite avoidance
• GPU compatibility tiers — auto-detection; playable on 12-year-old hardware

Security & Anti-Cheat

• Relay time authority — server owns the clock; lag-switch impossible (D007)
• Deterministic order validation — all clients agree on accept/reject; cheated orders rejected identically (D012)
• Capability-based WASM sandbox — mods cannot access filesystem, network, or raw memory (D005)
• Signed replay hash chain — Ed25519 signing; tampering detected (D010)
• Mandatory transport encryption — AEAD on all network traffic
• Bounded reconciler corrections — state corrections validated before application

Observability

• Unified OTEL telemetry — client, relay, tracking, AI all emit structured events (D031)
• Desync diagnostics — Merkle tree pinpoints divergence to exact system/entity
• Background replay writer — crash-safe, zero frame-time impact
• Diagnostic overlay — FPS, latency, order rate, path cache stats in-game

Community Infrastructure

• Unified ic-server binary with independently toggleable capability flags: relay, matchmaking, ranking, Workshop P2P seeding, moderation (D074)
• Ed25519 signed credential records — portable reputation across communities
• Transparency logs — server publishes signed operation log for accountability
• Federated architecture — communities interoperate with official infrastructure
• Server configuration via server_config.toml with deployment guide (Chapter 15)

Quick Comparison

LLM / RAG Retrieval Index

This page is a retrieval-oriented map of the design docs for agentic LLM use (RAG, assistants, copilots, review bots).

For a human-facing overview of the project’s experimental LLM gameplay/content/tooling plans, see Experimental LLM Modes & Plans.

It is not a replacement for the main docs. It exists to improve:

• retrieval precision
• token efficiency
• canonical-source selection
• conflict resolution across overlapping chapters

Purpose

The mdBook is written for humans first, but many questions (especially design reviews) are now answered by agents that retrieve chunks of documentation. This index defines:

• which documents are canonical for which topics
• which documents are supporting / illustrative
• how to chunk and rank content for lower token cost
• how to avoid mixing roadmap ideas with accepted decisions

Canonical Source Priority (Use This Order)

When multiple docs mention the same topic, agents should prefer sources in this order unless the user specifically asks for roadmap or UX examples:

1. Decision docs (src/decisions/09*/D0XX-*.md) — normative design choices, tradeoffs, accepted defaults. Each decision is now a standalone file (e.g., src/decisions/09b/D052-community-servers.md). The parent 09b-networking.md etc. are lightweight index pages.
2. Core architecture / netcode / modding / security / performance chapters (02–06, 10) — system-level design details and implementation constraints
3. Player Flow (17-PLAYER-FLOW.md) — UX flows, screen layouts, examples, mock UI
4. Roadmap (08-ROADMAP.md) — phase timing and sequencing (not normative runtime behavior)
5. Research docs (research/*.md) — prior art, evidence, input to decisions (not final policy by themselves)

If conflict exists between a decision doc and a non-decision doc, prefer the decision doc and call out the inconsistency.

Doc Roles (RAG Routing)

Topic-to-Canonical Source Map

Retrieval Rules (Token-Efficient Defaults)

Chunking Strategy

• Decision files are now one-per-decision — chunk at ###/#### level within each file
• Architecture and player-flow files are now one-per-subsystem/screen — chunk at ###/#### level within each file
• Include heading path metadata, e.g.:
  • decisions/09g/D065-tutorial.md > Layer 3 > Controls Walkthrough
• Include decision IDs detected in the chunk (e.g., D065, D068)
• Tag each chunk with doc class: decision, architecture, ux-flow, roadmap, research

Chunk Size

• Preferred: 300–900 tokens
• Allow larger chunks for code blocks/tables that lose meaning when split
• Overlap: 50–120 tokens

Ranking Heuristics

• Prefer decision docs for normative questions (“should”, “must”, “decided”)
• Prefer src/18-PROJECT-TRACKER.md + src/tracking/milestone-dependency-map.md for “what next?”, dependency-order, and implementation sequencing questions
• Prefer src/tracking/implementation-ticket-template.md when the user asks for implementer task breakdowns or ticket-ready work packages tied to G* steps
• Prefer src/tracking/external-code-project-bootstrap.md, src/tracking/external-project-agents-template.md, and src/tracking/source-code-index-template.md when the user asks how to start a separate code repo that should follow these design docs
• Prefer src/tracking/future-language-audit.md + src/tracking/deferral-wording-patterns.md for reviews of vague future wording, deferral placement, and North Star claim formatting
• Prefer src/tracking/testing-strategy.md for CI/CD pipeline definitions, test tier assignments, fuzz targets, performance benchmarks, and release criteria
• Prefer src/architecture/type-safety.md + src/16-CODING-STANDARDS.md § Type-Safety Coding Standards for newtype policy, deterministic collection bans, typestate patterns, and clippy configuration
• Prefer src/tracking/feature-scenario-spec-template.md when implementing a UI screen or feature — the three-layer spec (Feature/Screen/Scenario) provides exact widget IDs, guard conditions, behavioral branches, non-goals, and Given/When/Then acceptance criteria that eliminate ambiguity
• Prefer src/player-flow/*.md (individual screen files) for UI layout / screen wording questions — use the index in 17-PLAYER-FLOW.md to route to the right file. If the page includes Feature/Screen/Scenario spec blocks, those are canonical for implementation
• Prefer 08-ROADMAP.md only for “when / phase” questions
• Prefer research docs only when the question is “why this prior art?” or “what did we learn from X?”

Conflict Handling

If retrieved chunks disagree:

1. Prefer the newer revision-noted decision text
2. Prefer decision docs over non-decision docs
3. Prefer security/netcode docs for trust/authority behavior
4. State the conflict explicitly and cite both locations

High-Cost Docs — Resolved

All previously identified high-cost files (>40KB) have been split into individually addressable sub-files. Each hub page retains overview content and a routing table to its sub-files.

Chapter-Level Splits

Decision Category Splits

Individual Decision Sub-Splits

Large individual decisions have been further split into sub-files:

Tracking & Planning Splits

Sub-File Splits Within Existing Directories

Retrieval pattern: Read the hub/index page (~500–2,000 tokens) to identify which sub-file to load, then load only that sub-file (~2k–12k tokens). Never load the full original content unless doing a cross-cutting audit.

Decision Capsule Standard (Pointer)

For better RAG summaries and lower retrieval cost, add a short Decision Capsule near the top of each decision (or decision file).

Template:

• src/decisions/DECISION-CAPSULE-TEMPLATE.md

Capsules should summarize:

• decision
• status
• canonical scope
• defaults / non-goals
• affected docs
• revision note summary

This gives agents a cheap “first-pass answer” before pulling the full decision body.

Practical Query Tips (for Agents and Humans)

• Include decision IDs when known (D068 selective install, D065 tutorial)
• Include doc role keywords (decision, player flow, roadmap) to improve ranking
• For behavior + UI questions, retrieve both:
  • decision doc chunk (normative)
  • 17-PLAYER-FLOW.md chunk (surface/example)

Examples:

• D068 cutscene variant packs AI Enhanced presentation fingerprint
• D065 controls walkthrough touch phone tablet semantic prompts
• D008 sub-tick timestamp normalization relay canonical order

01 — Vision & Competitive Landscape

Project Vision

Build a Rust-native RTS engine that:

• Supports OpenRA resource formats (.mix, .shp, .pal, YAML rules)
• Reimagines internals with modern architecture (not a port)
• Explores different tradeoffs: performance, modding depth, portability, and multiplayer architecture
• Provides OpenRA mod compatibility as the zero-cost migration path
• Is game-agnostic at the engine layer — built for the C&C community but designed to power any classic RTS (D039). Ships with Red Alert (default) and Tiberian Dawn as built-in game modules; RA2, Tiberian Sun, and community-created games are future modules on the same engine (RA2 is a future community goal, not a scheduled deliverable)

Project Philosophy: Classical Foundation, Experimental Ambition

Iron Curtain delivers two things that are non-negotiable:

1. The classical Red Alert experience. The game plays like Red Alert. The units, the feel, the pace — faithful to the original.
2. The OpenRA experience. Existing mods work. Competitive play works. The 18 years of community investment carries forward.

That is the foundation, and it ships complete.

On top of that foundation, IC explores ideas and features that push the genre forward — not as replacements for the classical experience, but as additions alongside it:

• Deterministic desync diagnosis that pinpoints the exact tick and entity that diverged
• A Workshop with P2P content delivery, federated community servers, and cross-community trust signals
• Three-tier modding (YAML → Lua → WASM) where total conversions are hot-loadable modules
• A unified community server binary where a $5 VPS hosts an entire community
• Fog-authoritative server mode for maphack-proof competitive play
• Ranked matchmaking with relay-signed match results and Ed25519 replay chains
• Branching campaigns with persistent unit rosters and veterancy carry-over

These features are designed, built, and shipped — but they are also tested against reality. Community feedback and real-world usage decide what stays as-is, what evolves, and what gets rethought. IC treats its own designs as hypotheses: strong enough to commit to, honest enough to revise.

IC does not defer hard problems or bend around limitations. If the best available library doesn’t fit, IC builds its own. If a standard protocol doesn’t cover the use case, IC extends it. If a security model requires architectural commitment, that commitment is made upfront. The default stance is to define the standard, not to adopt someone else’s compromise. But “no compromise on engineering” does not mean “no listening to the community” — the two reinforce each other.

Community Pain Points We Address

These are the most frequently reported frustrations from the C&C community — sourced from OpenRA’s issue tracker (135+ desync issues alone), competitive player feedback (15+ RAGL seasons), modder forums, and the Remastered Collection’s reception. Every architectural decision in this document traces back to at least one of these. This section exists so that anyone reading this document for the first time understands why the engine is designed the way it is.

Critical — For Players

1. Desyncs ruin multiplayer games. OpenRA has 135+ desync issues in its tracker. The sync report buffer is only 7 frames deep — when a desync occurs mid-game, diagnosis is often impossible. Players lose their game with no explanation. This is the single most-complained-about multiplayer issue. → IC answer: Per-tick state hashing follows the Spring Engine’s SyncDebugger approach — binary search identifies the exact tick and entity that diverged. Fixed-point math (no floats in sim — invariant #1) eliminates the most common source of cross-platform non-determinism. See 03-NETCODE.md for the full desync diagnosis design.

2. Random performance drops. Even at low unit counts, something “feels off” — micro-stutters from garbage collection pauses, unpredictable frame timing. In competitive play, a stutter during a crucial micro moment loses games. C#/.NET’s garbage collector is non-deterministic in timing. → IC answer: Rust has no garbage collector. Zero per-tick allocation is an invariant (not a goal — a rule). The efficiency pyramid (see 10-PERFORMANCE.md) prioritizes better algorithms and cache layout before reaching for threads. Target: 500-unit battles smooth on a 2-core 2012 laptop.

3. Campaigns are systematically incomplete. OpenRA’s multiplayer-first culture has left single-player campaigns unfinished across multiple supported games: Dune 2000 has only 1 of 3 campaigns playable, TD campaigns are also incomplete, and there’s no automatic mission progression — players exit to menu between missions. → IC answer: Campaign completeness is a first-class exit criterion for every shipped game module. The Enhanced Edition goes beyond completion: a strategic layer (War Table) between milestone missions, side operations that earn tech and deny enemy capabilities, a dynamic arms race where expansion-pack units are campaign rewards, and a final mission shaped by every choice the player made. Persistent unit rosters, veterancy, and equipment carry-over (D021). Continuous flow: briefing → mission → debrief → next mission, no menu breaks. The classic linear path is always available for purists.

4. No competitive infrastructure. No ranked matchmaking, no automated anti-cheat, no signed replays. The competitive scene relies entirely on community-run CnCNet ladders and trust-based result reporting. → IC answer: Glicko-2 ranked matchmaking, relay-certified match results (signed by the relay server — fraud-proof), Ed25519-signed tamper-proof replays, tournament mode with configurable broadcast delay. See 01-VISION.md § Competitive Play and 06-SECURITY.md.

5. Balance debates fractured the community. OpenRA’s competitive rebalancing made iconic units feel less powerful — Tanya, MiGs, V2 rockets, Tesla coils all nerfed for tournament fairness. This was a valid competitive choice, but it became the only option. Players who preferred the original feel had no path forward. The community split over whether the game should feel like Red Alert or like a balanced esport. → IC answer: Switchable balance presets (D019) — classic EA values (default), OpenRA balance, Remastered balance, custom — are a lobby setting, not a total conversion. Choose your experience. No one’s preference invalidates anyone else’s.

6. Platform reach is limited. The Remastered Collection is Windows/Xbox only. OpenRA covers Windows, macOS, and Linux but not browser or mobile. There’s no way to play on a phone, in a browser, or on a Steam Deck without workarounds. → IC answer: Designed for Windows, macOS, Linux, Steam Deck, browser (WASM), and mobile from day one. Platform-agnostic architecture (invariant #10) — input abstracted behind traits, responsive UI, no raw filesystem access.

Critical — For Modders

7. Deep modding requires C#. OpenRA’s YAML system covers ~80% of modding, but anything beyond value tweaks — new mechanics, total conversions, custom AI — requires writing C# against a large codebase with a .NET build toolchain. This limits the modder pool to people comfortable with enterprise software development. → IC answer: Three tiers — YAML (data, 80% of mods), Lua (scripting, missions and abilities), WASM (engine-level, total conversions) — no recompilation ever (invariant #3). WASM accepts any language. The modding barrier drops from “learn C# and .NET” to “edit a YAML file.”

8. MiniYAML has no tooling. OpenRA’s custom data format has no IDE support, no schema validation, no linting, no standard parsing libraries. Every editor is a plain text editor. Typos and structural errors are discovered at runtime. → IC answer: Standard YAML with serde_yaml (D003). JSON Schema for validation. IDE autocompletion and error highlighting work out of the box with any YAML-aware editor.

9. No mod distribution system. Mods are shared via forum posts and manual file copying. There’s no in-game browser, no dependency management, no integrity verification, no one-click install. → IC answer: Workshop registry (D030) with in-game browser, auto-download on lobby join (CS:GO-style), semver dependencies, SHA-256 integrity, federated mirrors, Steam Workshop as optional source.

10. No hot-reload. Changing a YAML value requires restarting the game. Changing C# code requires recompiling the engine. Iteration speed for mod development is slow. → IC answer: YAML + Lua hot-reload during development. Change a value, see it in-game immediately. WASM mods reload without game restart.

Important — Structural

11. Single-threaded performance ceiling. OpenRA’s game loop is single-threaded (verified from source). There’s a hard ceiling on how many units can be simulated per tick, regardless of how many CPU cores are available. → IC answer: Bevy’s ECS scheduling enables parallel systems where profiling justifies it. But per the efficiency pyramid (D015), algorithmic improvements and cache layout come first — threading is the last optimization, not the first.

12. Scenario editor is terrain-only. OpenRA’s map editor handles terrain and actor placement but not mission logic — triggers, objectives, AI behavior, and scripting must be done in separate files by hand. → IC answer: The IC SDK (D038+D040) ships a full creative toolchain: visual trigger editor, drag-and-drop logic modules, campaign graph editor, Game Master mode, asset studio. Inspired by OFP/Arma 3 Eden — not just a map painter, a mission design environment.

These pain points are not criticisms of OpenRA — they’re structural consequences of technology choices made 18 years ago. OpenRA is a remarkable achievement. Iron Curtain exists because we believe the community deserves the next step.

Why This Deserves to Exist

Capabilities Beyond OpenRA and the Remastered Collection

New Capabilities Not Found Elsewhere

Enhanced Edition Campaigns — Strategic Layer + Dynamic Arms Race (D021)

The original Red Alert campaigns ship complete and playable in their classic linear form — 14 missions per side (Allied and Soviet), in order, faithful to the original. The Enhanced Edition transforms them into something the originals never were — but something Westwood were already moving toward. Tiberian Sun introduced a world map where the player chose which territory to attack next. Red Alert 2 let you pick which country to invade. These were deliberate experiments in strategic agency, constrained by scope and timeline rather than intent. Games like XCOM, Total War, and Into the Breach have since proven this model works. The Enhanced Edition completes what Westwood started.

The 14 original missions become narrative milestones in a phase-based strategic campaign. Between milestones, the War Table presents available operations — authored expansion-pack missions, IC originals, and procedurally generated SpecOps — alongside enemy initiatives that advance the Soviet war machine. The player picks which operations to run, but Command Authority limits how many per phase. Unchosen operations resolve with consequences. The war moves without you.

Every expansion-pack unit and enemy capability is tied to the operational layer through a dynamic arms race. Capture a Chrono Tank through Italy operations. Deny the enemy’s super-soldier program through intelligence raids. Commander-vs-commando path choices determine tech quality: commando yields full prototypes; commander yields damaged captures or denial without acquisition. Three-state outcomes (acquired / partial / denied) mean every playthrough builds a unique arsenal — and faces a unique enemy.

The final mission reflects every choice: different units, different enemy composition, different approach routes, different briefing text. Two playthroughs produce genuinely different endgames — not just harder or easier, but different in kind.

The classic campaign ships separately as a faithful reproduction — same 14 missions per side, same difficulty, no strategic layer. For players who want the original 1996 experience untouched. Within the Enhanced Edition, players who skip optional operations face a harder road (no bonus assets, full enemy strength) but the campaign remains completable. Campaigns use directed graphs with multiple outcomes per mission, failure-forward branching, persistent unit rosters with veterancy and equipment carry-over, and continuous flow (no exit-to-menu). Inspired by XCOM, Total War, Jagged Alliance, and Operation Flashpoint.

Optional LLM-Generated Missions (BYOLLM — power-user feature)

For players who want more content: an optional in-game interface where players describe a scenario in natural language and receive a fully playable mission — map layout, objectives, enemy AI, triggers, briefing text. Generated content is standard YAML + Lua, fully editable and shareable. Requires the player to configure their own LLM provider (local or cloud) — the engine never ships or requires a specific model. Every feature works fully without an LLM configured.

The “One More Prompt” effect. Civilization is famous for “one more turn” — the compulsion loop where every turn ends with a reason to play the next one. IC’s LLM features are designed to create the same pull, but for content creation: “one more prompt.”

The generative campaign system (D016) is the primary driver. After each mission, the LLM inspects the battle report — what happened, who survived, what was lost — and generates the next mission as a direct reaction to the player’s choices. The debrief ends with a narrative hook: Sonya’s loyalty is cracking, Morrison is moving armor south, the bridge you lost three missions ago is now the enemy’s supply line. The player doesn’t just want to play the next mission — they want to see what the LLM does with what just happened. That curiosity is the loop.

But the effect extends beyond campaigns:

• “What if I describe THIS scenario?” — Single mission generation turns a text prompt into a playable map. The gap between idea and play is seconds. Players who would never build a mission in an editor will generate dozens.
• “What if I pit GPT against Claude?” — LLM exhibition matches (D073) let players set up AI-vs-AI battles with different models, strategies, and personalities. Each match plays out differently. The spectacle is endlessly variable.
• “What if I coach it differently this time?” — Prompt-coached matches (D073) let players give real-time strategic guidance to an LLM-controlled army. Same starting conditions, different prompt, different outcome.
• “What if I try a Soviet pulp sci-fi campaign with high moral complexity?” — The parameter space for generative campaigns is vast. Different faction, different tone, different story style, different difficulty curve — each combination produces a fundamentally different experience.

The compulsion comes from the same place as Civilization’s: the system is responsive enough that every output creates a reason to try another input. The difference is that in Civ, the loop is “I wonder what happens next turn.” In IC, the loop is “I wonder what happens if I say this.”

Rendering: Classic First, Modding Possibilities Beyond

The core rendering goal is to faithfully reproduce the classic Red Alert isometric aesthetic — the same sprites, the same feel. HD sprite support is planned so modders can provide higher-resolution assets alongside the originals.

Because the engine builds on Bevy’s rendering stack (which includes a full 2D and 3D pipeline via wgpu), modders gain access to capabilities far beyond the classic look — if they choose to use them:

• Post-processing: bloom, color grading, screen-space reflections on water
• Dynamic lighting: explosions illuminate surroundings, day/night cycles
• GPU particle systems: smoke, fire, debris, weather (rain, snow, sandstorm, fog, blizzard)
• Dynamic weather: real-time transitions (sunny → overcast → rain → storm), snow accumulation on terrain, puddle formation, seasonal effects — terrain textures respond to weather via palette tinting, overlay sprites, or shader blending (D022)
• Shader effects: chrono-shift shimmer, iron curtain glow, tesla arcs, nuclear flash
• Smooth camera: sub-pixel rendering, cinematic replay camera, smooth zoom
• 3D rendering: a Tier 3 (WASM) mod can replace the sprite renderer entirely with 3D models while the simulation stays unchanged

These are modding possibilities enabled by the engine’s architecture, not development goals for the base game. The base game ships with the classic isometric aesthetic. Visual enhancements are content that modders and the community build on top.

Scenario Editor & Asset Studio (D038 + D040)

OpenRA’s map editor is a standalone terrain/actor tool. The IC SDK ships a full creative toolchain as a separate application from the game — not just terrain/unit placement, but full mission logic: visual triggers with countdown/timeout timers, waypoints, drag-and-drop modules (wave spawner, patrol route, guard position, reinforcements, objectives), compositions (reusable prefabs), Probability of Presence per entity for replayability, layers, and a Game Master mode for live scenario manipulation. The SDK also includes an asset studio (D040) for browsing, editing, and generating game resources — sprites, palettes, terrain, chrome/UI themes — with optional LLM-assisted generation for non-artists. Inspired by Operation Flashpoint’s mission editor, Arma 3’s Eden Editor, and Bethesda’s Creation Kit.

Architectural Differences from OpenRA

OpenRA is a mature, actively maintained project with 18 years of community investment. These are genuine architectural differences, not criticisms:

What Makes People Actually Switch

1. Better performance — visible: bigger maps, more units, no stutters
2. Campaigns you never want to leave — the Enhanced Edition turns the original 14 missions per side into a strategic campaign with a War Table, side operations, enemy initiatives, and an arms race that makes every playthrough unique. Classic path always available. Going back to the originals feels empty
3. Better modding — WASM scripting, SDK with scenario editor & asset studio, hot reload
4. Competitive infrastructure — ranked matchmaking, anti-cheat, tournaments, signed replays — OpenRA has none of this
5. Player analytics — post-game stats, career page, campaign dashboard with roster graphs — your match history is queryable data, not a forgotten replay folder
6. Better multiplayer — desync debugging, smoother netcode, relay server
7. Runs everywhere — browser via WASM, mobile, Steam Deck natively
8. OpenRA mod compatibility — existing community migrates without losing work
9. Workshop with auto-download — join a game, missing mods download automatically (CS:GO-style); no manual file hunting
10. Creator recognition — reputation scores, featured badges, optional tipping — modders get credit and visibility
11. Achievement system — per-game-module achievements stored locally, mod-defined achievements via YAML + Lua, Steam sync for Steam builds
12. Optional LLM enhancements — IC ships built-in CPU models for zero-config operation; external LLM providers (BYOLLM) unlock higher quality for generated missions, adaptive briefings, coaching suggestions — a quiet power-user feature, not a headline

Item 8 is the linchpin. If existing mods just work, migration cost drops to near zero.

Competitive Play

Red Alert has a dedicated competitive community (primarily through OpenRA and CnCNet). CnCNet provides community ladders and tournament infrastructure, but there’s no integrated ranked system, no automated anti-cheat, and desyncs remain a persistent issue (135+ tracked in OpenRA’s issue tracker). This is a significant opportunity. IC’s CommunityBridge will integrate with both OpenRA’s and CnCNet’s game browsers (shared discovery, separate gameplay) so the C&C community stays unified.

Ranked Matchmaking

• Rating system: Glicko-2 (improvement over Elo — accounts for rating volatility and inactivity, used by Lichess, FIDE, many modern games)
• Seasons: 3-month ranked seasons with placement matches (10 games), YAML-configurable tier system (D055 — Cold War military ranks for RA: Conscript → Supreme Commander, 7+2 tiers × 3 divisions), end-of-season rewards
• Queues: 1v1 (primary), 2v2 (team), FFA (experimental). Separate ratings per queue
• Map pool: Curated competitive map pool per season, community-nominated and committee-voted. Ranked games use pool maps only
• Balance preset locked: Ranked play uses a fixed balance preset per season (prevents mid-season rule changes from invalidating results)
• Matchmaking server: Lightweight Rust service, same infra pattern as tracking/relay servers (containerized, self-hostable for community leagues)

Leaderboards

• Global, per-faction, per-map, per-game-module (RA1, TD, etc.)
• Public player profiles: rating history, win rate, faction preference, match history
• Replay links on every match entry — any ranked game is reviewable

Tournament Support

• Observer mode: Spectators connect to relay server and receive tick orders with configurable delay
  • No fog — for casters (sees everything)
  • Player fog — fair spectating (sees what one player sees)
  • Broadcast delay — 1-5 minute configurable delay to prevent stream sniping
• Bracket integration: Tournament organizers can set up brackets via API; match results auto-report
• Relay-certified results: Every ranked and tournament match produces a CertifiedMatchResult signed by the relay server (see 06-SECURITY.md). No result disputes.
• Replay archive: All ranked/tournament replays stored server-side for post-match analysis and community review

Anti-Cheat (Architectural, Not Intrusive)

Our anti-cheat emerges from the architecture — not from kernel drivers or invasive monitoring:

Philosophy: No kernel-level anti-cheat (no Vanguard/EAC). We’re open-source and cross-platform — intrusive anti-cheat contradicts our values and doesn’t work on Linux/WASM. We accept that lockstep has inherent maphack risk (every client runs the full sim). The fog-authoritative server is the real answer for high-stakes play.

Performance as Competitive Advantage

Competitive play demands rock-solid performance — stutters during a crucial micro moment lose games:

Competitive Landscape

Active Projects

OpenRA (C#) — The community standard

• 14.8k GitHub stars, actively maintained, 18 years of community investment
• Latest release: 20250330 (March 2025) — new map editor, HD asset support, post-processing
• Mature community, mod ecosystem, server infrastructure — the project that proved open-source C&C is viable
• Multiplayer-first focus — single-player campaigns often incomplete (Dune 2000: only 1 of 3 campaigns fully playable; TD campaign also incomplete)
• SDK supports non-Westwood games (KKND, Swarm Assault, Hard Vacuum, Dune II remake) — validates our multi-game extensibility approach (D018)

Vanilla Conquer (C++)

• Cross-platform builds of actual EA source code
• Not reimagination — just making original compile on modern systems
• Useful reference for original engine behavior

Chrono Divide (TypeScript)

• Red Alert 2 running in browser, working multiplayer
• Proof that browser-based RTS is viable
• Study their architecture for WASM target

Dead/Archived Projects (lessons learned)

Chronoshift (C++) — Archived July 2020

• Binary-level reimplementation attempt, only English 3.03 beta patch
• Never reached playable state
• Lesson: 1:1 binary compatibility is a dead end

OpenRedAlert (C++)

• Based on ancient FreeCNC/FreeRA, barely maintained
• Lesson: Building on old foundations doesn’t work long-term

Key Finding

No Rust-based Red Alert or OpenRA ports exist. The field is completely open.

EA Source Release (February 2025)

EA released original Red Alert source code under GPL v3. Benefits:

• Understand exactly how original game logic works (damage, pathfinding, AI)
• Verify Rust implementation against original behavior
• Combined with OpenRA’s 17 years of refinements: “how it originally worked” + “how it should work”

Repository: https://github.com/electronicarts/CnC_Red_Alert

Reference Projects

These are the projects we actively study. Each serves a different purpose — do not treat them as interchangeable.

OpenRA — https://github.com/OpenRA/OpenRA

What to study:

• Source code: Trait/component architecture, how they solved the same problems we’ll face (fog of war, build queues, harvester AI, naval combat). Our ECS component model maps directly from their traits.
• Issue tracker: Community pain points surface here. Recurring complaints = design opportunities for us. Pay attention to issues tagged with performance, pathfinding, modding, and multiplayer.
• UX/UI patterns: OpenRA has 17 years of UI iteration. Their command interface (attack-move, force-fire, waypoints, control groups, rally points) is excellent. Adopt their UX patterns for player interaction.
• Mod ecosystem: Understand what modders actually build so our modding tiers serve real needs.

What NOT to copy:

• Unit balance. OpenRA deliberately rebalances units away from the original game toward competitive multiplayer fairness. This makes iconic units feel underwhelming (see Gameplay Philosophy below). We default to classic RA balance. This pattern repeats across every game they support — Dune 2000 units are also rebalanced away from originals.
• Simulation internals bug-for-bug. We’re not bit-identical — we’re better-algorithms-identical.
• Campaign neglect. OpenRA’s multiplayer-first culture has left single-player campaigns systematically incomplete across all supported games. Dune 2000 has only 1 of 3 campaigns playable; TD campaigns are also incomplete; there’s no automatic mission progression (players exit to menu between missions). Campaign completeness is a first-class goal for us — every shipped game module must have all original campaigns fully playable with continuous flow (D021). Beyond completeness, IC’s Enhanced Edition wraps the original missions in a strategic layer: a War Table between milestones, side operations that earn tech and deny enemy capabilities, enemy initiatives that advance without the player, and a dynamic arms race where every expansion-pack unit is a campaign reward with commando/commander trade-offs. The final mission reflects every choice. The classic linear path is always available. Inspired by XCOM, Total War, Jagged Alliance, and Operation Flashpoint.

EA Red Alert Source — https://github.com/electronicarts/CnC_Red_Alert

What to study:

• Exact gameplay values. Damage tables, weapon ranges, unit speeds, fire rates, armor multipliers. This is the canonical source for “how Red Alert actually plays.” When OpenRA and EA source disagree on a value, EA source wins for our classic preset.
• Order processing. The OutList/DoList pattern maps directly to our PlayerOrder → TickOrders → apply_tick() architecture.
• Integer math patterns. Original RA uses integer math throughout for determinism — validates our fixed-point approach.
• AI behavior. How the original skirmish AI makes decisions, builds bases, attacks. Reference for ic-ai.

Caution: The codebase is 1990s C++ — tangled, global state everywhere, no tests. Extract knowledge, don’t port patterns.

EA Remastered Collection — https://github.com/electronicarts/CnC_Remastered_Collection

What to study:

• UI/UX design. The Remastered Collection has the best UI/UX of any C&C game. Clean, uncluttered, scales well to modern resolutions. This is our gold standard for UI layout and information density. Where OpenRA sometimes overwhelms with GUI elements, Remastered gets the density right.
• HD asset pipeline. How they upscaled and re-rendered classic assets while preserving the feel. Relevant for our rendering pipeline.
• Sidebar design. Classic sidebar with modern polish — study how they balanced information vs screen real estate.

EA Tiberian Dawn Source — https://github.com/electronicarts/CnC_Tiberian_Dawn

What to study:

• Shared C&C engine lineage. TD and RA share engine code. Cross-referencing both clarifies ambiguous behavior in either.
• Game module reference. When we build the Tiberian Dawn game module (D018), this is the authoritative source for TD-specific logic.
• Format compatibility. TD .mix files, terrain, and sprites share formats with RA — validation data for ic-cnc-content.

Chrono Divide — (TypeScript, browser-based RA2)

What to study:

• Architecture reference for our WASM/browser target
• Proof that browser-based RTS with real multiplayer is viable

Gameplay Philosophy

Classic Feel, Modern UX

Iron Curtain’s default gameplay targets the original Red Alert experience, not OpenRA’s rebalanced version. This is a deliberate choice:

• Units should feel powerful and distinct. Tanya kills soldiers from range, fast, and doesn’t die easily — she’s a special operative, not a fragile glass cannon. MiG attacks should be devastating. V2 rockets should be terrifying. Tesla coils should fry anything that comes close. If a unit was iconic in the original game, it should feel iconic here.
• OpenRA’s competitive rebalancing makes units more “fair” for tournament play but can dilute the personality of iconic units. That’s a valid design choice for competitive players, but it’s not our default.
• OpenRA’s UX/UI innovations are genuinely excellent and we adopt them: attack-move, waypoint queuing, production queues, control group management, minimap interactions, build radius visualization. The Remastered Collection’s UI density and layout is our gold standard for visual design.

Switchable Balance Presets (D019)

Because reasonable people disagree on balance, the engine supports balance presets — switchable sets of unit values loaded from YAML at game start:

Presets are just YAML files in rules/presets/. Switching preset = loading a different set of unit/weapon/structure YAML. No code changes, no mod required. The lobby UI exposes preset selection.

This is not a modding feature — it’s a first-class game option. “Classic” vs “OpenRA” balance is a settings toggle, not a total conversion.

Toggleable QoL Features (D033)

Beyond balance, every quality-of-life improvement added by OpenRA or the Remastered Collection is individually toggleable: attack-move, waypoint queuing, multi-queue production, health bar visibility, range circles, guard command, and dozens more. Built-in presets group these into coherent experience profiles:

Select a profile, then override any individual setting. Want classic balance with OpenRA’s attack-move but without build radius circles? Done. Good defaults, full customization.

See src/decisions/09d/D019-balance-presets.md and src/decisions/09d/D033-qol-presets.md, and D032 in src/decisions/09c-modding.md.

Timing Assessment

• EA source just released (fresh community interest)
• Rust gamedev ecosystem mature (wgpu stable, ECS crates proven)
• No competition in Rust RTS space
• OpenRA showing architectural age despite active development
• WASM/browser gaming increasingly viable
• Multiple EA source releases provide unprecedented reference material

Verdict: Window of opportunity is open now.

02 — Core Architecture

Keywords: architecture, crate boundaries, ic-sim, ic-net, ic-protocol, GameLoop<N, I>, NetworkModel, InputSource, deterministic simulation, Bevy, platform-agnostic design, game modules, async runtime, tokio, bevy_tasks, IoBridge, WASM portability, GUI-first binary design

Architectural positioning — federated, not centralized. IC uses federated servers for trust and coordination (relay, ranking, matchmaking) with P2P for content distribution (Workshop delivery, replay sharing). There is no mandatory central server — anyone can run an ic-server instance — but servers exist and are the authority path for ranked play. Casual games can use a host-embedded listen server with zero external infrastructure. “Federated” means multiple independent operators, each sovereign; “P2P” refers to BitTorrent-style content transfer between players, not peer-to-peer game networking.

Decision: Bevy

Rationale (revised — see D002 in decisions/09a-foundation.md):

• ECS is our architecture — Bevy gives it to us with scheduling, queries, and parallel system execution out of the box
• Saves 2–4 months of engine plumbing (windowing, asset pipeline, audio, rendering scaffolding)
• Plugin system maps naturally to pluggable networking (NetworkModel as a Bevy plugin)
• Bevy’s 2D rendering pipeline handles classic isometric sprites; the 3D pipeline is available passively for modders (see “3D Rendering as a Mod”)
• wgpu is Bevy’s backend — we still get low-level control via custom render passes where profiling justifies it
• Breaking API changes are manageable: pin Bevy version per development phase, upgrade between phases

Bevy provides:

Simulation / Render Split (Critical Architecture)

The simulation and renderer are completely decoupled from day one.

┌───────────────────────────────────────────────┐
│               GameLoop<N, I>                  │
│                                               │
│  Input(I) → Network(N) → Sim (tick) → Render  │
│                                               │
│  Tick rate set by game speed preset (D060)    │
│  Default: Slower ≈15 tps, Normal ≈20 tps      │
│  Renderer interpolates between sim states     │
│  Renderer can run at any FPS independently    │
└───────────────────────────────────────────────┘

Simulation Properties

• Deterministic: Same inputs → identical outputs on every platform
• Pure: No I/O, no floats in game logic, no network awareness
• Fixed-point math: i32/i64 with known scale (never f32/f64 in sim)
• Snapshottable: Full state serializable for replays, save games, desync debugging, rollback, campaign state persistence (D021)
• Headless-capable: ic-sim can run without a renderer (dedicated servers, AI training, automated testing). External consumers drive Simulation directly — GameLoop is the client-side frame loop and always renders (see architecture/game-loop.md).
• Library-first: ic-sim is a Rust library crate usable by external projects — not just an internal dependency of ic-game

External Sim API (Bot Development & Research)

ic-sim is explicitly designed as a public library for external consumers: bot developers, AI researchers, tournament automation, and testing infrastructure. The sim’s purity (no I/O, no rendering, no network awareness) makes it naturally embeddable.

#![allow(unused)]
fn main() {
// External bot developer's Cargo.toml:
// [dependencies]
// ic-sim = "0.x"
// ic-protocol = "0.x"

use ic_sim::{Simulation, SimConfig};
use ic_protocol::{PlayerOrder, TimestampedOrder};

// Create a headless game
let config = SimConfig::from_yaml_bytes(&yaml_bytes)?;
let mut sim = Simulation::new(config, map, players, seed);

// Game loop: inject orders, step, read state
loop {
    let state = sim.query_state();  // read visible game state
    let orders = my_bot.decide(&state);  // bot logic
    sim.inject_orders(&orders);  // submit orders for this tick
    sim.step();  // advance one tick
    if sim.is_finished() { break; }
}
}

Use cases:

• AI bot tournaments: Run headless matches between community-submitted bots. Same pattern as BWAPI’s SSCAIT (StarCraft) and Chrono Divide’s @chronodivide/game-api. The Workshop hosts bot leaderboards; ic mod test provides headless match execution (see 04-MODDING.md).
• Academic research: Reinforcement learning, multi-agent systems, game balance analysis. Researchers embed ic-sim in their training harness without pulling in rendering or networking.
• Automated testing: CI pipelines create deterministic game scenarios, inject specific order sequences, and assert on outcomes. Already used internally for regression testing.
• Replay analysis tools: Third-party tools load replay files and step through the sim to extract statistics, generate heatmaps, or compute player metrics.

API stability: The external sim API surface (Simulation::new, step, inject_orders, query_state, snapshot, restore) follows the same versioning guarantees as the mod API (see 04-MODDING.md § “Mod API Versioning & Stability”). Breaking changes require a major version bump with migration guide.

Distinction from AiStrategy trait: The AiStrategy trait (D041) is for in-engine AI that runs inside the sim’s tick loop as a WASM sandbox. The external sim API is for out-of-process consumers that drive the sim from the outside. Both are valid — AiStrategy has lower latency (no serialization boundary), the external API has more flexibility (any language, any tooling, full process isolation).

Phase: The external API surface crystallizes in Phase 2 when the sim is functional. Bot tournament infrastructure ships in Phase 4-5. Formal API stability guarantees begin when ic-sim reaches 1.0.

Simulation Core Types

#![allow(unused)]
fn main() {
/// All sim-layer coordinates use fixed-point
pub type SimCoord = i32;  // 1 unit = 1/SCALE of a cell (see P002)

/// Position is 3D-aware from day one.
/// RA1 game module sets z = 0 everywhere (flat isometric).
/// RA2/TS game module uses z for terrain elevation, bridges, aircraft altitude.
pub struct WorldPos {
    pub x: SimCoord,
    pub y: SimCoord,
    pub z: SimCoord,  // 0 for flat games (RA1), meaningful for elevated terrain (RA2/TS)
}

/// Cell position on a discrete grid — convenience type for grid-based game modules.
/// NOT an engine-core requirement. Grid-based games (RA1, RA2, TS, TD, D2K) use CellPos
/// as their spatial primitive. Continuous-space game modules work with WorldPos directly.
/// The engine core operates on WorldPos; CellPos is a game-module-level concept.
pub struct CellPos {
    pub x: i32,
    pub y: i32,
    pub z: i32,  // layer / elevation level (0 for RA1)
}

/// The sim is a pure function: state + orders → new state
pub struct Simulation {
    world: World,          // ECS world (all entities + components)
    tick: SimTick,         // Current tick number (newtype over u64 — see type-safety.md)
    rng: DeterministicRng, // Seeded, reproducible RNG
}

impl Simulation {
    /// THE critical function. Pure, deterministic, no I/O.
    /// Panics in debug if `orders.tick != self.tick` (caller bug — the relay
    /// guarantees tick alignment). In release, a tick mismatch is a hard error
    /// that cannot be silently ignored (returns `Err`). All other order-level
    /// failures are handled inside validation (D012) and never surface here.
    pub fn apply_tick(&mut self, orders: &TickOrders) -> Result<(), SimError> {
        debug_assert_eq!(orders.tick, self.tick, "tick mismatch: caller bug");
        if orders.tick != self.tick {
            return Err(SimError::TickMismatch { expected: self.tick, got: orders.tick });
        }
        // 0. Swap double buffers (fog, influence maps — see Double Buffering below)
        self.swap_double_buffers();
        // 1. Validate all orders via OrderValidator (D041/D012 — anti-cheat)
        let validated = self.validate_orders(orders);
        // 2. Run the game module's system pipeline (step 1 = apply_orders,
        //    step 2+ = movement, combat, harvesting, etc.)
        //    Orders are sorted by sub-tick timestamp within apply_orders().
        self.run_systems(&validated);
        // 3. Advance tick
        self.tick += 1;
        Ok(())
    }

    /// Snapshot for rollback / desync debugging / save games.
    /// Returns a SimCoreSnapshot — the sim-internal portion only (ECS entities,
    /// player states, map, RNG, intern table). Pure — no I/O.
    /// The full SimSnapshot (including script_state and campaign_state)
    /// is composed by `ic-game`, which collects script state from
    /// `ic-script` and wraps it: `SimSnapshot { core, campaign_state, script_state }`.
    /// This preserves the crate boundary: `ic-sim` never imports `ic-script`.
    /// Callers (in ic-game) persist snapshots using crash-safe I/O:
    /// payload written first, header updated atomically after fsync
    /// (Fossilize pattern — see D010 and state-recording.md).
    pub fn snapshot(&self) -> SimCoreSnapshot { /* serialize sim-internal state */ }

    /// Restore from a sim-core snapshot. Returns `Err(SimError::ConfigMismatch)`
    /// if the snapshot's `game_seed` or `map_hash` don't match the current
    /// `Simulation` config — prevents cross-game snapshot injection (S3).
    pub fn restore(&mut self, snap: &SimCoreSnapshot) -> Result<(), SimError> {
        /* verify config, then deserialize */
    }

    /// Delta snapshot — encodes only sim-internal components that changed
    /// since `baseline`. ~10x smaller than full snapshot for typical gameplay.
    /// Returns a SimCoreDelta; `ic-game` wraps it into DeltaSnapshot by
    /// attaching campaign/script state if changed.
    /// Used for replay keyframes and autosave.
    /// Autosave: the game thread produces a SimCoreDelta (cheap) plus any
    /// changed CampaignState/ScriptState (see D010 and state-recording.md
    /// for the baseline pattern), then the I/O thread applies the sim delta
    /// to its cached baseline to reconstruct a full SimSnapshot for .icsave.
    /// See D010 and `10-PERFORMANCE.md` § Delta Encoding.
    pub fn delta_snapshot(&self, baseline: &SimCoreSnapshot) -> SimCoreDelta {
        /* property-level diff — only changed components serialized */
    }
    /// Apply a sim-core delta. Returns `Err(SimError::BaselineMismatch)` if
    /// `delta.baseline_tick` / `delta.baseline_hash` don't match current state
    /// — prevents applying a delta from a divergent branch (S10).
    pub fn apply_delta(&mut self, delta: &SimCoreDelta) -> Result<(), SimError> {
        /* verify baseline, then merge delta into current state */
    }

    /// Fast hash for per-tick desync detection (SyncHash newtype — see type-safety.md)
    pub fn state_hash(&self) -> SyncHash { /* hash critical state */ }

    /// Full SHA-256 state hash for replay signing and snapshot verification
    /// (StateHash newtype — see type-safety.md). Cold path — called at signing
    /// cadence (every N ticks), not every tick. Returns the full Merkle root
    /// before u64 truncation.
    pub fn full_state_hash(&self) -> StateHash { /* SHA-256 Merkle root */ }

    /// Surgical correction for cross-engine reconciliation.
    /// Requires `&ReconcilerToken` — an unforgeable capability token (S5).
    /// Only the `SimReconciler` system can construct one (`_private: ()`).
    pub fn apply_correction(
        &mut self,
        correction: &EntityCorrection,
        _token: &ReconcilerToken,
    ) {
        // Directly set an entity's field — only used by reconciler
    }
}
}

ic-game Integration: Full Snapshot Restore & Delta Application

ic-sim only exposes restore(&SimCoreSnapshot) and apply_delta(&SimCoreDelta) — sim-internal operations. The full SimSnapshot and DeltaSnapshot types (defined in formats/save-replay-formats.md) include campaign and script state that lives outside ic-sim. The ic-game integration layer provides the end-to-end restore and apply contracts:

#![allow(unused)]
fn main() {
/// ic-game integration — NOT part of ic-sim.
/// This is the canonical contract for full snapshot restore (save-load,
/// reconnection) and full delta application (replay seeking).
/// All callers go through these functions.
impl GameRunner {
    /// Restore from a full SimSnapshot (save-load, reconnection).
    /// Called after verification: save-load verifies payload_hash;
    /// reconnection verifies Verified<SimSnapshot> via StateHash
    /// (see desync-recovery.md § Reconnection).
    ///
    /// Core restore is attempted first — if it fails, campaign and script
    /// state are NOT modified (preserving the pre-call state).
    pub fn restore_full(&mut self, snap: &SimSnapshot) -> Result<(), SimError> {
        // 1. Restore sim-internal state (may fail: config mismatch)
        self.simulation.restore(&snap.core)?;
        // 2. Restore campaign state (D021 branching graph, flags, roster)
        self.campaign = snap.campaign_state.clone();
        // 3. Rehydrate script state: initialize fresh Lua/WASM VMs,
        //    then call each mod's on_deserialize() with saved bytes.
        //    ic-game orchestrates this via ic-script — ic-sim is not involved.
        if let Some(ref script) = snap.script_state {
            self.script_runtime.rehydrate(script);
        }
        Ok(())
    }

    /// Apply a full DeltaSnapshot (replay seeking only).
    /// The caller must apply deltas in order on top of a restored full
    /// snapshot — see replay-keyframes-analysis.md § Seeking algorithm.
    ///
    /// Core delta is applied first — if it fails (baseline mismatch),
    /// campaign and script state are NOT modified.
    pub fn apply_full_delta(&mut self, delta: &DeltaSnapshot) -> Result<(), SimError> {
        // 1. Apply sim-internal delta (may fail: baseline mismatch)
        self.simulation.apply_delta(&delta.core)?;
        // 2. Replace campaign state if the delta includes it
        if let Some(ref campaign) = delta.campaign_state {
            self.campaign = Some(campaign.clone());
        }
        // 3. Replace script state if the delta includes it.
        //    Script deltas are full replacements (not incremental patches)
        //    because Lua/WASM state is opaque to the engine.
        if let Some(ref script) = delta.script_state {
            self.script_runtime.rehydrate(script);
        }
        Ok(())
    }
}
}

Use sites: restore_full() is called by save-load (formats/save-replay-formats.md), reconnection (netcode/desync-recovery.md § Reconnection step 5), and co-op resume (D016-world-assets-multiplayer.md). apply_full_delta() is called during replay seeking (applying intervening deltas between a full keyframe and the target tick). Reconnection does not use apply_full_delta() — the reconnecting client receives a full SimSnapshot via restore_full(), then catches up by re-simulating ticks at accelerated speed via normal apply_tick() (see desync-recovery.md § Reconnection).

Order Validation (inside sim, deterministic)

#![allow(unused)]
fn main() {
impl Simulation {
    fn execute_order(&mut self, player: PlayerId, order: &PlayerOrder) {
        match self.validate_order(player, order) {
            OrderValidity::Valid => self.apply_order(player, order),
            OrderValidity::Rejected(reason) => {
                self.record_suspicious_activity(player, reason);
                // All honest clients also reject → stays in sync
            }
        }
    }

    fn validate_order(&self, player: PlayerId, order: &PlayerOrder) -> OrderValidity {
        // Every order type validated: ownership, affordability, prerequisites, placement
        // This is deterministic — all clients agree on what to reject
    }
}
}

ECS Design

ECS is a natural fit for RTS: hundreds of units with composable behaviors.

External Entity Identity

Bevy’s Entity IDs are internal — they can be recycled, and their numeric value is meaningless across save/load or network boundaries. Any external-facing system (replay files, Lua scripting, observer UI, debug tools) needs a stable entity identifier.

IC uses generational unit tags — a pattern proven by SC2’s unit tag system (see research/blizzard-github-analysis.md § Part 1) and common in ECS engines:

#![allow(unused)]
fn main() {
#[derive(Clone, Copy, Hash, Eq, PartialEq, Serialize, Deserialize)]
pub struct UnitTag {
    pub index: u16,     // slot in a fixed-size pool
    pub generation: u16, // incremented each time the slot is reused
}
}

• Index identifies the pool slot. Pool size is bounded by the game module’s max entity count (RA1: 2048 units + structures).
• Generation disambiguates reuse. If a unit dies and a new unit takes the same slot, the new unit has a higher generation. Stale references (e.g., an attack order targeting a dead unit) are detected by comparing generations.
• Replay and Lua stable: UnitTag values are deterministic — same game produces the same tags. Replay analysis can track a unit across its entire lifetime. Lua scripts reference units by UnitTag, never by Bevy Entity.
• Network-safe: UnitTag is 4 bytes, cheap to include in PlayerOrder. Bevy Entity is never serialized into orders or replays.

A UnitPool resource maps UnitTag ↔ Entity and manages slot allocation/recycling. All public-facing APIs (Simulation::query_unit(), order validation, Lua bindings) use UnitTag; Bevy Entity is an internal implementation detail.

Component Model (mirrors OpenRA Traits)

OpenRA’s “traits” are effectively components. Map them directly. The table below shows the RA1 game module’s default components. Other game modules (RA2, TD) register additional components — the ECS is open for extension without modifying the engine core.

OpenRA vocabulary compatibility (D023): OpenRA trait names are accepted as YAML aliases. Armament and combat both resolve to the same component. This means existing OpenRA YAML definitions load without renaming.

Canonical enum names (D027): Locomotor types (Foot, Wheeled, Tracked, Float, Fly), armor types (None, Light, Medium, Heavy, Wood, Concrete), target types, damage states, and stances match OpenRA’s names exactly. Versus tables and weapon definitions copy-paste without translation.

| OpenRA Trait | ECS Component | Purpose | | Health | Health { current: i32, max: i32 } | Hit points | | Mobile | Mobile { speed: i32, locomotor: LocomotorType } | Can move | | Attackable | Attackable { armor: ArmorType } | Can be damaged | | Armament | Armament { weapon: WeaponId, cooldown: u32 } | Can attack | | Building | Building { footprint: FootprintId } | Occupies cells (footprint shapes stored in a shared FootprintTable resource, indexed by ID — zero per-entity heap allocation) | | Buildable | Buildable { cost: i32, time: u32, prereqs: Vec<StructId> } | Can be built | | Selectable | Selectable { bounds: Rect, priority: u8 } | Player can select | | Harvester | Harvester { capacity: i32, resource: ResourceType } | Gathers ore | | Producible | Producible { queue: QueueType } | Produced from building |

These 9 components are the core set. The full RA1 game module registers ~50 additional components for gameplay systems (power, transport, capture, stealth, veterancy, etc.). See Extended Gameplay Systems below for the complete component catalog. The component table in AGENTS.md lists only the core set as a quick reference.

Component group toggling (validated by Minecraft Bedrock): Bedrock’s entity system uses “component groups” — named bundles of components that can be added or removed by game events (e.g., minecraft:angry adds AttackNearest + SpeedBoost when a wolf is provoked). This is directly analogous to IC’s condition system (D028): a condition like “prone” or “low_power” grants/revokes a set of component modifiers. Bedrock’s JSON event system ("add": { "component_groups": [...] }) validates that event-driven component toggling scales to thousands of entity types and is intuitive for data-driven modding. See research/mojang-wube-modding-analysis.md § Bedrock.

System Execution Order (deterministic, configurable per game module)

The RA1 game module registers this system execution order:

Per tick:
  1.  apply_orders()          — Process all player commands (move, attack, build, sell, deploy, guard, etc.)
  2.  power_system()          — Recalculate player power balance, apply/remove outage penalties
  3.  production_system()     — Advance build queues, deduct costs, spawn completed units
  4.  harvester_system()      — Gather ore, navigate to refinery, deliver resources
  5.  docking_system()        — Manage dock queues (refinery, helipad, repair pad)
  6.  support_power_system()  — Advance superweapon charge timers
  7.  movement_system()       — Move all mobile entities (includes sub-cell for infantry)
  8.  crush_system()          — Check vehicle-over-infantry crush collisions
  9.  mine_system()           — Check mine trigger contacts
  10. combat_system()         — Target acquisition, fire weapons, create projectile entities
  11. projectile_system()     — Advance projectiles, check hits, apply warheads (Versus table + modifiers)
  12. capture_system()        — Advance engineer capture progress
  13. cloak_system()          — Update cloak/detection states, reveal-on-fire cooldowns
  14. condition_system()      — Evaluate condition grants/revocations (D028)
  15. veterancy_system()      — Award XP from kills, check level-up thresholds
  16. death_system()          — Remove destroyed entities, spawn husks, apply on-death warheads
  17. crate_system()          — Check crate pickups, apply random actions, spawn new crates
  18. transform_system()      — Process pending unit transformations (MCV ↔ ConYard, deploy/undeploy)
  19. trigger_system()        — Check mission/map triggers (Lua callbacks)
  20. notification_system()   — Queue audio/visual notifications (EVA, alerts), enforce cooldowns
  21. fog_system()            — Update visibility (staggered — not every tick, see 10-PERFORMANCE.md)

Order is fixed per game module and documented. Changing it changes gameplay and breaks replay compatibility.

A different game module (e.g., RA2) can insert additional systems (garrison, mind control, prism forwarding) at defined points. The engine runs whatever systems the active game module registers, in the order it specifies. The engine itself doesn’t know which game is running — it just executes the registered system pipeline deterministically.

FogProvider Trait (D041)

fog_system() delegates visibility computation to a FogProvider trait — like Pathfinder for pathfinding. Different game modules need different fog algorithms: radius-based (RA1), elevation line-of-sight (RA2/TS), or no fog (sandbox).

#![allow(unused)]
fn main() {
/// Game modules implement this to define how visibility is computed.
pub trait FogProvider: Send + Sync {
    /// Recompute visibility for a player.
    fn update_visibility(
        &mut self,
        player: PlayerId,
        sight_sources: &[(WorldPos, SimCoord)],  // (position, sight_range) pairs
        terrain: &TerrainData,
    );

    /// Is this position currently visible to this player?
    fn is_visible(&self, player: PlayerId, pos: WorldPos) -> bool;

    /// Has this player ever seen this position? (shroud vs fog distinction)
    fn is_explored(&self, player: PlayerId, pos: WorldPos) -> bool;

    /// All entity IDs visible to this player (for AI view filtering, render culling).
    fn visible_entities(&self, player: PlayerId) -> &[EntityId];
}
}

RA1 registers RadiusFogProvider (circle-based, fast, matches original RA). RA2/TS would register ElevationFogProvider (raycasts against terrain heightmap). The fog-authoritative NetworkModel variant (D074 — operator-enabled capability, implementation at M11) reuses the same trait on the server side to determine which entities to send per client. See D041 in decisions/09d-gameplay.md for full rationale.

Entity Visibility Model

The FogProvider output determines how entities appear to each player. Following SC2’s proven model (see research/blizzard-github-analysis.md § 1.4), each entity observed by a player carries a visibility classification that controls which data fields are available:

#![allow(unused)]
fn main() {
/// Per-entity visibility state as seen by a specific player.
/// Determines which component fields the player can observe.
pub enum EntityVisibility {
    /// Currently visible — all public fields available (health, position, orders for own units).
    Visible,
    /// Previously visible, now in fog — "ghost" of last-known state.
    /// Position/type from when last seen; health, orders, and internal state are NOT available.
    Snapshot,
    /// Never seen or fully hidden — no data available to this player.
    Hidden,
}
}

Field filtering per visibility level:

Last-seen snapshot table: When a visible entity enters fog-of-war, the FogProvider stores a snapshot of its last-known position, type, owner, and build progress. The renderer displays this as a dimmed “ghost” unit. The snapshot is explicitly stale — the actual unit may have moved, morphed, or been destroyed. Snapshots are cleared when the position is re-explored and the unit is no longer there.

Double-Buffered Shared State (Tick-Consistent Reads)

Multiple systems per tick need to read shared, expensive-to-compute data structures — fog visibility, influence maps, global condition modifiers (D028). The FogProvider output is the clearest example: targeting_system(), ai_system(), and render all need to answer “is this cell visible?” within the same tick. If fog_system() updates visibility mid-tick, some systems see old fog, others see new — a determinism violation.

IC uses double buffering for any shared state that is written by one system and read by many systems within a tick:

#![allow(unused)]
fn main() {
/// Two copies of T — one for reading (current tick), one for writing (being rebuilt).
/// Swap at tick boundary. All reads within a tick see a consistent snapshot.
pub struct DoubleBuffered<T> {
    /// Current tick — all systems read from this. Immutable during the tick.
    read: T,
    /// Next tick — one system writes to this during the current tick.
    write: T,
}

impl<T> DoubleBuffered<T> {
    /// Called exactly once per tick, at the tick boundary, before any systems run.
    /// After swap, the freshly-computed write buffer becomes the new read buffer.
    pub fn swap(&mut self) {
        std::mem::swap(&mut self.read, &mut self.write);
    }

    /// All systems call this to read — guaranteed consistent for the entire tick.
    pub fn read(&self) -> &T { &self.read }

    /// Only the owning system (e.g., fog_system) calls this to prepare the next tick.
    pub fn write(&mut self) -> &mut T { &mut self.write }
}
}

Where double buffering applies:

Note: influence_map_system() and weather_surface_system() are not in the RA1 21-step pipeline above. Influence maps are computed by AI subsystems (Phase 4, D043). weather_surface_system ships with dynamic weather (Phase 4, D022). When added, they will be inserted at defined points in the game module’s pipeline. The double-buffer pattern applies regardless of where in the pipeline they land.

Why not Bevy’s system ordering alone? Bevy’s scheduler can enforce that fog_system() runs before targeting_system(). But it cannot prevent a system scheduled between two readers from mutating shared state. Double buffering makes the guarantee structural: the read buffer is physically separate from the write buffer. No scheduling mistake can cause a reader to see partial writes.

Cost: One extra copy of each double-buffered data structure. For fog visibility (a bit array over map cells), this is ~32KB for a 512×512 map. For influence maps (a [i32; CELLS] array), it’s ~1MB for a 512×512 map. These are allocated once at game start and never reallocated — consistent with Layer 5’s zero-allocation principle.

Swap timing: DoubleBuffered::swap() is called in Simulation::apply_tick() before the system pipeline runs. This is a fixed point in the tick — step 0, before the engine runs OrderValidator (D041) and then apply_orders() (step 1). The write buffer from the previous tick becomes the read buffer for the current tick. The swap is a pointer swap (std::mem::swap), not a copy — effectively free.

OrderValidator Trait (D041)

The engine enforces that ALL orders pass validation before apply_orders() executes them. This formalizes D012’s anti-cheat guarantee — game modules cannot accidentally skip validation:

#![allow(unused)]
fn main() {
/// Game modules implement this to define legal orders. The engine calls
/// validate() for every order, every tick — before the module's systems run.
pub trait OrderValidator: Send + Sync {
    fn validate(
        &self,
        player: PlayerId,
        order: &PlayerOrder,
        state: &SimReadView,
    ) -> OrderValidity;
}
}

RA1 registers StandardOrderValidator (ownership, affordability, prerequisites, placement, rate limits). See D041 in decisions/09d-gameplay.md for full design and GameModule trait integration.

Extended Gameplay Systems (RA1 Module)

Moved to architecture/gameplay-systems.md for RAG/context efficiency.

The 9 core components above cover the skeleton. A playable Red Alert requires ~50 components and ~20 systems power, construction, production, harvesting, combat, fog of war, shroud, crates, veterancy, carriers, mind control, iron curtain, chronosphere, and more.

Architecture Sub-Pages

Core Architecture Extended Gameplay Systems (RA1 Module)

The 9 core components in the main architecture document cover the skeleton. A playable Red Alert requires ~50 components and ~20 systems. This section designs every gameplay system identified in 11-OPENRA-FEATURES.md gap analysis, organized by functional domain.

Power System

Every building generates or consumes power. Power deficit disables defenses and slows production — core C&C economy.

#![allow(unused)]
fn main() {
/// Per-building power contribution.
pub struct Power {
    pub provides: i32,   // Power plants: positive
    pub consumes: i32,   // Defenses, production buildings: positive
}

/// Marker: this building goes offline during power outage.
pub struct AffectedByPowerOutage;

/// Player-level resource (not a component — stored in PlayerState).
pub struct PowerManager {
    pub total_capacity: i32,
    pub total_drain: i32,
    pub low_power: bool,  // drain > capacity
}
}

power_system() logic: Sum all Power components per player → update PowerManager. When low_power is true, buildings with AffectedByPowerOutage have their production rates halved and defenses fire at reduced rate (via condition system, D028). Power bar UI reads PowerManager from ic-ui.

YAML:

power_plant:
  power: { provides: 100 }
tesla_coil:
  power: { consumes: 75 }
  affected_by_power_outage: true

Full Damage Pipeline (D028)

The complete weapon → projectile → warhead chain:

Armament fires → Projectile entity spawned → projectile_system() advances it
  → hit detection (range, homing, ballistic arc)
  → Warhead(s) applied at impact point
    → target validity (TargetTypes, stances)
    → spread/falloff calculation (distance from impact)
    → Versus table lookup (ArmorType × WarheadType → damage multiplier)
    → DamageMultiplier modifiers (veterancy, terrain, conditions)
    → Health reduced

#![allow(unused)]
fn main() {
/// A fired projectile — exists as its own entity during flight.
pub struct Projectile {
    pub weapon_id: WeaponId,
    pub source: EntityId,
    pub owner: PlayerId,
    pub target: ProjectileTarget,
    pub speed: i32,            // fixed-point
    pub warheads: Vec<WarheadId>,
    pub inaccuracy: i32,       // scatter radius at target
    pub projectile_type: ProjectileType,
}

pub enum ProjectileType {
    Bullet,         // instant-hit (hitscan)
    Missile { tracking: i32, rof_jitter: i32 },  // homing
    Ballistic { gravity: i32 },                    // arcing (artillery)
    Beam { duration: u32 },                        // continuous ray
}

pub enum ProjectileTarget {
    Entity(EntityId),
    Ground(WorldPos),
}

/// Warhead definition — loaded from YAML, shared (not per-entity).
pub struct WarheadDef {
    pub spread: i32,           // area of effect radius
    pub versus: VersusTable,   // ArmorType → damage percentage
    pub damage: i32,           // base damage value
    pub falloff: Vec<i32>,     // damage multiplier at distance steps
    pub valid_targets: Vec<TargetType>,
    pub invalid_targets: Vec<TargetType>,
    pub effects: Vec<WarheadEffect>,  // screen shake, spawn fire, etc.
}

/// ArmorType × WarheadType → percentage (100 = full damage)
/// Loaded from YAML Versus table — identical format to OpenRA.
/// Flat array indexed by ArmorType discriminant for O(1) lookup in the combat
/// hot path — no per-hit HashMap overhead. ArmorType is a small enum (<16 variants)
/// so the array fits in a single cache line.
pub struct VersusTable {
    pub modifiers: [i32; ArmorType::COUNT],  // index = ArmorType as usize
}
}

projectile_system() logic: For each Projectile entity: advance position by speed, check if arrived at target. On arrival, iterate warheads, apply each to entities in spread radius using SpatialIndex::query_range(). For each target: check valid_targets, look up VersusTable, apply DamageMultiplier conditions, reduce Health. If Health.current <= 0, mark for death_system().

YAML (weapon + warhead, OpenRA-compatible):

weapons:
  105mm:
    range: 5120          # in world units (fixed-point)
    rate_of_fire: 80     # ticks between shots
    projectile:
      type: bullet
      speed: 682
    warheads:
      - type: spread_damage
        damage: 60
        spread: 426
        versus:
          none: 100
          light: 80
          medium: 60
          heavy: 40
          wood: 120
          concrete: 30
        falloff: [100, 50, 25, 0]

DamageResolver Trait (D041)

The damage pipeline above describes the RA1 resolution algorithm. The data (warheads, versus tables, modifiers) is YAML-configurable, but the resolution order — what happens between warhead impact and health reduction — varies between game modules. RA2 needs shield-first resolution; Generals-class games need sub-object targeting. The DamageResolver trait abstracts this step:

#![allow(unused)]
fn main() {
/// Game modules implement this to define damage resolution order.
/// Called by projectile_system() after hit detection and before health reduction.
pub trait DamageResolver: Send + Sync {
    fn resolve_damage(
        &self,
        warhead: &WarheadDef,
        target: &DamageTarget,
        modifiers: &StatModifiers,
        distance_from_impact: SimCoord,
    ) -> DamageResult;
}

pub struct DamageTarget {
    pub entity: EntityId,
    pub armor_type: ArmorType,
    pub current_health: i32,
    pub shield: Option<ShieldState>,
    pub conditions: Conditions,
}

pub struct DamageResult {
    pub health_damage: i32,
    pub shield_damage: i32,
    pub conditions_applied: Vec<(ConditionId, u32)>,
    pub overkill: i32,
}
}

RA1 registers StandardDamageResolver (Versus table → falloff → multiplier stack → health). RA2 would register ShieldFirstDamageResolver. See D041 in ../decisions/09d-gameplay.md for full rationale and alternative implementations.

Support Powers / Superweapons

#![allow(unused)]
fn main() {
/// Attached to the building that provides the power (e.g., Chronosphere, Iron Curtain device).
pub struct SupportPower {
    pub power_type: SupportPowerType,
    pub charge_time: u32,          // ticks to fully charge
    pub current_charge: u32,       // ticks accumulated
    pub ready: bool,
    pub one_shot: bool,            // nukes: consumed on use; Chronosphere: recharges
    pub targeting: TargetingMode,
}

pub enum TargetingMode {
    Point,                   // click a cell (nuke)
    Area { radius: i32 },   // area selection (Iron Curtain effect)
    Directional,             // select origin + target cell (Chronoshift)
}

pub enum SupportPowerType {
    /// Defined by YAML — these are RA1 defaults, but the enum is data-driven.
    Named(String),
}

/// Player-level tracking.
pub struct SupportPowerManager {
    pub powers: Vec<SupportPowerStatus>, // one per owned support building
}
}

support_power_system() logic: For each entity with SupportPower: increment current_charge each tick. When current_charge >= charge_time, set ready = true. UI shows charge bar. Activation comes via player order (sim validates ownership + readiness), then applies warheads/effects at target location.

Building Mechanics

#![allow(unused)]
fn main() {
/// Build radius — buildings can only be placed near existing structures.
pub struct BuildArea {
    pub range: i32,   // cells from building edge
}

/// Primary building marker — determines which building produces (e.g., primary war factory).
pub struct PrimaryBuilding;

/// Rally point — newly produced units move here.
pub struct RallyPoint {
    pub target: WorldPos,
}

/// Building exit points — where produced units spawn.
pub struct Exit {
    pub offsets: Vec<CellPos>,   // spawn positions relative to building origin
}

/// Building can be sold.
pub struct Sellable {
    pub refund_percent: i32,  // typically 50
    pub sell_time: u32,       // ticks for sell animation
}

/// Building can be repaired (by player spending credits).
pub struct Repairable {
    pub repair_rate: i32,     // HP per tick while repairing
    pub repair_cost_per_hp: i32,
}

/// Gate — wall segment that opens for friendly units.
pub struct Gate {
    pub open_delay: u32,
    pub close_delay: u32,
    pub state: GateState,
}

pub enum GateState { Open, Closed, Opening, Closing }

/// Wall-specific: enables line-build placement.
pub struct LineBuild;
}

Building placement validation (in apply_orders() → order validation):

1. Check footprint fits terrain (no water, no cliffs, no existing buildings)
2. Check within build radius of at least one friendly BuildArea provider
3. Check prerequisites met (from Buildable.prereqs)
4. Deduct cost → start build animation → spawn building entity

Production Queue

#![allow(unused)]
fn main() {
/// A production queue (each building type has its own queue).
pub struct ProductionQueue {
    pub queue_type: QueueType,
    pub items: Vec<ProductionItem>,
    pub parallel: bool,           // RA2: parallel production per factory
    pub paused: bool,
}

pub struct ProductionItem {
    pub actor_type: ActorId,
    pub remaining_cost: i32,
    pub remaining_time: u32,
    pub paid: i32,               // credits paid so far (for pause/resume)
    pub infinite: bool,          // repeat production (hold queue)
}
}

production_system() logic: For each ProductionQueue: if not paused and not empty, advance front item. Deduct credits incrementally (one tick’s worth per tick — production slows when credits run out). When remaining_time == 0, spawn unit at building’s Exit position, send to RallyPoint if set.

Production Model Diversity

The ProductionQueue above describes the classic C&C sidebar model, but production is one of the most varied mechanics across RTS games — even within the OpenRA mod ecosystem. Analysis of six major OpenRA mods (see research/openra-mod-architecture-analysis.md) reveals at least five distinct production models:

The engine must not hardcode any of these. The production_system() described above is the RA1 game module’s implementation. Other game modules register their own production system via GameModule::system_pipeline(). The ProductionQueue component is defined by the game module, not the engine core. A KKnD-style module might define a PerBuildingProductionQueue component with different constraints; a Dune II module might omit queue mechanics entirely and use a SingleItemProduction component.

This is a key validation of invariant #9 (engine core is game-agnostic): if a non-C&C total conversion on our engine needs a fundamentally different production model, the engine should not resist it.

Resource / Ore Model

#![allow(unused)]
fn main() {
/// Ore/gem cell data — stored per map cell (in a resource layer, not as entities).
pub struct ResourceCell {
    pub resource_type: ResourceType,
    pub amount: i32,     // depletes as harvested
    pub max_amount: i32,
    pub growth_rate: i32, // ore regrows; gems don't (YAML-configured)
}

/// Storage capacity — silos and refineries.
pub struct ResourceStorage {
    pub capacity: i32,
}
}

harvester_system() logic:

1. Harvester navigates to nearest ResourceCell with amount > 0
2. Harvester mines: transfers resource from cell to Harvester.capacity
3. When full (or cell depleted): navigate to nearest DockHost with DockType::Refinery
4. Dock, transfer resources → credits (via resource value table)
5. If no refinery, wait. If no ore, scout for new fields.

Player receives “silos needed” notification when total stored exceeds total ResourceStorage.capacity.

Transport / Cargo

#![allow(unused)]
fn main() {
pub struct Cargo {
    pub max_weight: u32,
    pub current_weight: u32,
    pub passengers: Vec<EntityId>,
    pub unload_delay: u32,
}

pub struct Passenger {
    pub weight: u32,
    pub custom_pip: Option<PipType>,  // minimap/selection pip color
}

/// For carryall-style air transport.
pub struct Carryall {
    pub carry_target: Option<EntityId>,
}

/// Eject passengers on death (not all transports — YAML-configured).
pub struct EjectOnDeath;

/// ParaDrop capability — drop passengers from air.
pub struct ParaDrop {
    pub drop_interval: u32,  // ticks between each passenger exiting
}
}

Load order: Player issues load order → movement_system() moves passenger to transport → when adjacent, remove passenger from world, add to Cargo.passengers. Unload order: Deploy order → eject passengers one by one at Exit positions, delay between each.

Capture / Ownership

#![allow(unused)]
fn main() {
pub struct Capturable {
    pub capture_types: Vec<CaptureType>,  // engineer, proximity
    pub capture_threshold: i32,           // required capture points
    pub current_progress: i32,
    pub capturing_entity: Option<EntityId>,
}

pub struct Captures {
    pub speed: i32,              // capture points per tick
    pub capture_type: CaptureType,
    pub consumed: bool,          // engineer is consumed on capture (RA1 behavior)
}

pub enum CaptureType { Infantry, Proximity }
}

capture_system() logic: For each entity with Capturable being captured: increment current_progress by capturer’s speed. When current_progress >= capture_threshold, transfer ownership to capturer’s player. If consumed, destroy capturer. Reset progress on interruption (capturer killed or moved away).

Stealth / Cloak

#![allow(unused)]
fn main() {
pub struct Cloak {
    pub cloak_delay: u32,         // ticks after last action before cloaking
    pub cloak_types: Vec<CloakType>,
    pub ticks_since_action: u32,
    pub is_cloaked: bool,
    pub reveal_on_fire: bool,
    pub reveal_on_move: bool,
}

pub struct DetectCloaked {
    pub range: i32,
    pub detect_types: Vec<CloakType>,
}

pub enum CloakType { Stealth, Underwater, Disguise, GapGenerator }
}

cloak_system() logic: For each Cloak entity: if reveal_on_fire and fired this tick, reset ticks_since_action. If reveal_on_move and moved this tick, reset. Otherwise increment ticks_since_action. When above cloak_delay, set is_cloaked = true. Rendering: cloaked and no enemy DetectCloaked in range → invisible. Cloaked but detected → shimmer effect. Fog system integration: cloaked entities hidden from enemy even in explored area unless detector present.

Infantry Mechanics

#![allow(unused)]
fn main() {
/// Infantry sub-cell positioning — up to 5 infantry per cell.
pub struct InfantryBody {
    pub sub_cell: SubCell,  // Center, TopLeft, TopRight, BottomLeft, BottomRight
}

pub enum SubCell { Center, TopLeft, TopRight, BottomLeft, BottomRight }

/// Panic flee behavior (e.g., civilians, dogs).
pub struct ScaredyCat {
    pub flee_range: i32,
    pub panic_ticks: u32,
}

/// Take cover / prone — reduces damage, reduces speed.
pub struct TakeCover {
    pub damage_modifier: i32,   // e.g., 50 (half damage)
    pub speed_modifier: i32,    // e.g., 50 (half speed)
    pub prone_delay: u32,       // ticks to transition to prone
}
}

movement_system() integration for infantry: When infantry moves into a cell, assigns SubCell based on available slots. Up to 5 infantry share one cell in different visual positions. When attacked, infantry with TakeCover auto-goes prone (grants condition “prone” → DamageMultiplier of 50%).

Death Mechanics

#![allow(unused)]
fn main() {
/// Spawn an actor when this entity dies (husks, ejected pilots).
pub struct SpawnOnDeath {
    pub actor_type: ActorId,
    pub probability: i32,   // 0-100, default 100
}

/// Explode on death — apply warheads at position.
pub struct ExplodeOnDeath {
    pub warheads: Vec<WarheadId>,
}

/// Timed self-destruct (demo truck, C4 charge).
pub struct SelfDestruct {
    pub timer: u32,        // ticks remaining
    pub warheads: Vec<WarheadId>,
}

/// Damage visual states.
pub struct DamageStates {
    pub thresholds: Vec<DamageThreshold>,
}

pub struct DamageThreshold {
    pub hp_percent: i32,   // below this → enter this state
    pub state: DamageState,
}

pub enum DamageState { Undamaged, Light, Medium, Heavy, Critical }

/// Victory condition marker — this entity must be destroyed to win.
pub struct MustBeDestroyed;
}

death_system() logic: For entities with Health.current <= 0: check SpawnOnDeath → spawn husk/pilot. Check ExplodeOnDeath → apply warheads at position. Remove entity from world and spatial index. For SelfDestruct: decrement timer each tick in a pre-death pass; when 0, kill the entity (triggers normal death path).

Transform / Deploy

#![allow(unused)]
fn main() {
/// Actor can transform into another type (MCV ↔ ConYard, siege deploy/undeploy).
pub struct Transforms {
    pub into: ActorId,
    pub delay: u32,              // ticks for transformation
    pub facing: Option<i32>,     // required facing to transform
    pub condition: Option<ConditionId>,  // condition granted during transform
}
}

Processing: Player issues deploy order → transform_system() starts countdown. During delay, entity is immobile (grants condition “deploying”). After delay, replace entity with into actor type, preserving health percentage, owner, and veterancy.

Docking System

#![allow(unused)]
fn main() {
/// Building or unit that accepts docking (refinery, helipad, repair pad).
pub struct DockHost {
    pub dock_type: DockType,
    pub dock_position: CellPos,  // where the client unit sits
    pub queue: Vec<EntityId>,    // waiting to dock
    pub occupied: bool,
}

/// Unit that needs to dock (harvester, aircraft, damaged vehicle for repair pad).
pub struct DockClient {
    pub dock_type: DockType,
}

pub enum DockType { Refinery, Helipad, RepairPad }
}

docking_system() logic: For each DockHost: if not occupied and queue non-empty, pull front of queue, guide to dock_position. When docked: execute dock-type-specific logic (refinery → transfer resources; helipad → reload ammo; repair pad → heal). When done, release and advance queue.

Veterancy / Experience

#![allow(unused)]
fn main() {
/// This unit gains XP from kills.
pub struct GainsExperience {
    pub current_xp: i32,
    pub level: VeterancyLevel,
    pub thresholds: Vec<i32>,      // XP required for each level transition
    pub level_conditions: Vec<ConditionId>,  // conditions granted at each level
}

/// This unit awards XP when killed (based on its cost/value).
pub struct GivesExperience {
    pub value: i32,   // XP awarded to killer
}

pub enum VeterancyLevel { Rookie, Veteran, Elite, Heroic }
}

veterancy_system() logic: When death_system() removes an entity with GivesExperience, the killer (if it has GainsExperience) receives value XP. Check thresholds: if XP crosses a boundary, advance level and grant the corresponding condition. Conditions trigger multipliers: veteran = +25% firepower/+25% armor; elite = +50%/+50% + self-heal; heroic = +75%/+75% + faster fire rate (all values from YAML, not hardcoded).

Campaign carry-over (D021): GainsExperience.current_xp and level are part of the roster snapshot saved between campaign missions.

Campaign Strategic Layer (D021)

Campaign progression is not part of ic-sim. Tactical missions emit MissionOutcome data, and the campaign runtime in ic-script / ic-game advances the save-authoritative CampaignState between missions.

D021 now supports two campaign shapes on the same foundation:

• Graph-only campaigns — branching mission graph, persistent roster/state, no extra command layer
• Strategic-layer campaigns — the same graph wrapped in a phase-based War Table that exposes optional operations, enemy initiatives, Command Authority, and an arms-race ledger between milestone missions

The important architecture rule is that the graph remains authoritative. The War Table is an organizer and presenter over graph nodes; it does not replace mission outcomes with a separate progression system.

#![allow(unused)]
fn main() {
#[derive(Serialize, Deserialize, Clone)]
pub struct StrategicLayerState {
    pub current_phase: Option<CampaignPhaseState>,
    pub completed_phases: Vec<String>,
    pub war_momentum: i32,
    pub operations: Vec<CampaignOperationState>,
    pub active_enemy_initiatives: Vec<EnemyInitiativeState>,
    pub asset_ledger: CampaignAssetLedgerState,
}

pub enum CampaignFocusState {
    StrategicLayer,
    Intermission,
    Briefing,
    Mission,
    Debrief,
}

pub struct CampaignPhaseState {
    pub phase_id: String,
    pub operational_budget_total: u32,
    pub operational_budget_remaining: u32,
    pub main_mission_urgent: bool,
}

pub struct CampaignOperationState {
    pub mission_id: MissionId,
    pub source: OperationSource,
    pub status: OperationStatus,
    pub expires_after_phase: Option<String>,
    pub generated_instance: Option<GeneratedOperationState>,
    pub generation_fallback: Option<GenerationFallbackMode>,
}

pub enum OperationSource { Authored, Generated }

pub enum OperationStatus {
    Revealed,
    Available,
    Completed,
    Failed,
    Skipped,
    Expired,
}

pub struct GeneratedOperationState {
    pub profile_id: String,
    pub seed: u64,
    pub site_kit: String,
    pub security_tier: u8,
    pub resolved_modules: Vec<ResolvedModulePick>,
}

pub struct ResolvedModulePick {
    pub slot: String,
    pub module_id: String,
}

pub enum GenerationFallbackMode {
    AuthoredBackup { mission_id: MissionId },
    ResolveAsSkipped,
}

pub struct EnemyInitiativeState {
    pub initiative_id: String,
    pub status: EnemyInitiativeStatus,
    pub ticks_remaining: u32,
    pub counter_operation: Option<MissionId>,
}

pub enum EnemyInitiativeStatus {
    Revealed,
    Countered,
    Activated,
    Expired,
}

pub struct CampaignAssetLedgerState {
    pub entries: Vec<CampaignAssetLedgerEntry>,
}

pub struct CampaignAssetLedgerEntry {
    pub asset_id: String,
    pub owner: AssetOwner,
    pub state: AssetState,
    pub quantity: u32,
    pub quality: Option<String>,
    pub consumed_by: Vec<MissionId>,
}

pub enum AssetOwner { Player, Enemy }

pub enum AssetState {
    Acquired,
    Partial,
    Denied,
}
}

CampaignState.flags remains the extension surface for authored story state, but first-party strategic-layer data should not be buried in generic flags. Focus state, generated-operation payloads, phase/budget state, initiative state, and asset-ledger state need first-class fields so save/load, UI, replay metadata, and campaign validation can reason about them directly.

Guard Command

#![allow(unused)]
fn main() {
pub struct Guard {
    pub target: EntityId,
    pub leash_range: i32,   // max distance from target before returning
}

pub struct Guardable;  // marker: can be guarded
}

Processing in apply_orders(): Guard order assigns Guard component. combat_system() integration: if a guarding unit’s target is attacked and attacker is within leash range, engage attacker. If target moves beyond leash range, follow.

Crush Mechanics

#![allow(unused)]
fn main() {
pub struct Crushable {
    pub crush_class: CrushClass,
}

pub enum CrushClass { Infantry, Wall, Hedgehog }

/// Vehicles that auto-crush when moving over crushable entities.
pub struct Crusher {
    pub crush_classes: Vec<CrushClass>,
}
}

crush_system() logic: After movement_system(), for each entity with Crusher that moved this tick: query SpatialIndex at new position for entities with matching Crushable.crush_class. Apply instant kill to crushed entities.

Crate System

#![allow(unused)]
fn main() {
pub struct Crate {
    pub action_pool: Vec<CrateAction>,  // weighted random selection
}

pub enum CrateAction {
    Cash { amount: i32 },
    Unit { actor_type: ActorId },
    Heal { percent: i32 },
    LevelUp,
    MapReveal,
    Explode { warhead: WarheadId },
    Cloak { duration: u32 },
    Speed { multiplier: i32, duration: u32 },
}

/// World-level system resource.
pub struct CrateSpawner {
    pub max_crates: u32,
    pub spawn_interval: u32,   // ticks between spawn attempts
    pub spawn_area: SpawnArea,
}
}

crate_system() logic: Periodically spawn crates (up to max_crates). When a unit moves onto a crate: pick random CrateAction, apply effect to collecting unit/player. Remove crate entity.

Mine System

#![allow(unused)]
fn main() {
pub struct Mine {
    pub trigger_types: Vec<TargetType>,
    pub warhead: WarheadId,
    pub visible_to_owner: bool,
}

pub struct Minelayer {
    pub mine_type: ActorId,
    pub lay_delay: u32,
}
}

mine_system() logic: After movement_system(), for each Mine: query spatial index for entities at mine position matching trigger_types. On contact: apply warhead, destroy mine. Mines are invisible to enemy unless detected by mine-sweeper unit (uses DetectCloaked with CloakType::Stealth).

Notification System

#![allow(unused)]
fn main() {
pub struct NotificationEvent {
    pub event_type: NotificationType,
    pub position: Option<WorldPos>,  // for spatial notifications
    pub player: PlayerId,
}

pub enum NotificationType {
    UnitLost,
    BaseUnderAttack,
    HarvesterUnderAttack,
    BuildingCaptured,
    LowPower,
    SilosNeeded,
    InsufficientFunds,
    BuildingComplete,
    UnitReady,
    NuclearLaunchDetected,
    EnemySpotted,
    ReinforcementsArrived,
}

/// Per-notification-type cooldown (avoid spam).
/// Flat array indexed by NotificationType discriminant — small fixed enum,
/// avoids HashMap overhead on a per-event check.
pub struct NotificationCooldowns {
    pub cooldowns: [u32; NotificationType::COUNT],  // ticks remaining, index = variant as usize
    pub default_cooldown: u32,                       // typically 150 ticks (~10 sec)
}
}

notification_system() logic: Collects events from other systems (combat → “base under attack”, production → “building complete”, power → “low power”). Checks cooldown for each type. If not on cooldown, queues notification for ic-audio (EVA voice line) and ic-ui (text overlay). Audio mapping is YAML-driven:

notifications:
  base_under_attack: { audio: "BATL1.AUD", priority: high, cooldown: 300 }
  building_complete: { audio: "CONSTRU2.AUD", priority: normal, cooldown: 0 }
  low_power: { audio: "LOPOWER1.AUD", priority: high, cooldown: 600 }

Cursor System

#![allow(unused)]
fn main() {
/// Determines which cursor shows when hovering over a target.
pub struct CursorProvider {
    pub cursor_map: HashMap<CursorContext, CursorDef>,
}

pub enum CursorContext {
    Default,
    Move,
    Attack,
    AttackForce,     // force-fire on ground
    Capture,
    Enter,           // enter transport/building
    Deploy,
    Sell,
    Repair,
    Guard,
    SupportPower(SupportPowerType),
    Chronoshift,
    Nuke,
    Harvest,
    Impassable,
}

pub struct CursorDef {
    pub sprite: SpriteId,
    pub hotspot: (i32, i32),
    pub sequence: Option<AnimSequence>,  // animated cursors
}
}

Logic: Each frame (render-side, not sim), determine cursor context from: selected units, hovered entity/terrain, active command mode (sell, repair, support power), force modifiers (Ctrl = force-fire, Alt = force-move). Look up CursorDef from CursorProvider. Display.

Hotkey System

#![allow(unused)]
fn main() {
pub struct HotkeyConfig {
    pub bindings: HashMap<ActionId, Vec<KeyCombo>>,
    pub profiles: HashMap<String, HotkeyProfile>,
}

pub struct KeyCombo {
    pub key: KeyCode,
    pub modifiers: Modifiers,  // Ctrl, Shift, Alt
}
}

Built-in profiles:

• classic — original RA1 keybindings
• openra — OpenRA defaults
• modern — WASD camera, common RTS conventions

Fully rebindable in settings UI. Categories: unit commands, production, control groups, camera, chat, debug. Hotkeys produce PlayerOrders through InputSource — the sim never sees key codes.

Camera System

The camera is a purely render-side concern — the sim has no camera concept (Invariant #1). Camera state lives as a Bevy Resource in ic-render, read by the rendering pipeline and ic-ui (minimap, spatial audio listener position). The ScreenToWorld trait (see § “Portability Design Rules”) converts screen coordinates to world positions; the camera system controls what region of the world is visible.

Core Types

#![allow(unused)]
fn main() {
/// Central camera state — a Bevy Resource in ic-render.
/// NOT part of the sim. Save/restore for save games is serialized separately
/// (alongside other client-side state like UI layout and audio volume).
#[derive(Resource)]
pub struct GameCamera {
    /// World position the camera is centered on (render-side f32, not sim fixed-point).
    pub position: Vec2,
    /// Current zoom level. 1.0 = default view. <1.0 = zoomed out, >1.0 = zoomed in.
    pub zoom: f32,
    /// Zoom limits — enforced every frame. Ranked/tournament modes clamp these further.
    pub zoom_min: f32,  // default: 0.5 (see twice as much map)
    pub zoom_max: f32,  // default: 4.0 (pixel-level inspection)
    /// Map bounds in world coordinates — camera cannot scroll past these.
    pub bounds: Rect,
    /// Smooth interpolation factor for zoom (0.0–1.0 per frame, lerp toward target).
    pub zoom_smoothing: f32,  // default: 0.15
    /// Smooth interpolation factor for pan.
    pub pan_smoothing: f32,   // default: 0.2
    /// Internal: zoom target for smooth interpolation.
    pub zoom_target: f32,
    /// Internal: position target for smooth pan (e.g., centering on selection).
    pub position_target: Vec2,
    /// Edge scroll speed in world-units per second (scaled by current zoom).
    pub edge_scroll_speed: f32,
    /// Keyboard pan speed in world-units per second (scaled by current zoom).
    pub keyboard_pan_speed: f32,
    /// Follow mode: lock camera to a unit or player's view.
    pub follow_target: Option<FollowTarget>,
    /// Screen shake state (driven by explosions, nukes, superweapons).
    pub shake: ScreenShake,
}

pub enum FollowTarget {
    Unit(UnitTag),               // follow a specific unit (observer, cinematic)
    Player(PlayerId),            // lock to a player's viewport (observer mode)
}

pub struct ScreenShake {
    pub amplitude: f32,          // current intensity (decays over time)
    pub decay_rate: f32,         // amplitude reduction per second
    pub frequency: f32,          // oscillation speed
    pub offset: Vec2,            // current frame's shake offset (applied to final transform)
}
}

Zoom Behavior

Zoom modifies the OrthographicProjection.scale on the Bevy camera entity. A zoom of 1.0 maps to the default viewport size for the active render mode (D048). Zooming out (zoom < 1.0) shows more of the map; zooming in (zoom > 1.0) magnifies the view.

Input methods:

Zoom-toward-cursor is the expected UX for isometric games (SC2, AoE2, OpenRA all do this). When the player scrolls the mouse wheel, the world point under the cursor stays fixed on screen — the camera position shifts to compensate for the scale change. This requires adjusting position alongside zoom:

#![allow(unused)]
fn main() {
fn zoom_toward_cursor(camera: &mut GameCamera, cursor_world: Vec2, scroll_delta: f32) {
    let old_zoom = camera.zoom_target;
    camera.zoom_target = (old_zoom + scroll_delta * ZOOM_STEP)
        .clamp(camera.zoom_min, camera.zoom_max);
    // Shift position so the cursor's world point stays at the same screen location.
    let zoom_ratio = camera.zoom_target / old_zoom;
    camera.position_target = cursor_world + (camera.position_target - cursor_world) * zoom_ratio;
}
}

Smooth interpolation: The actual zoom and position values lerp toward their targets each frame:

#![allow(unused)]
fn main() {
fn camera_interpolation(camera: &mut GameCamera, dt: f32) {
    let t_zoom = 1.0 - (1.0 - camera.zoom_smoothing).powf(dt * 60.0);
    camera.zoom = camera.zoom.lerp(camera.zoom_target, t_zoom);
    let t_pan = 1.0 - (1.0 - camera.pan_smoothing).powf(dt * 60.0);
    camera.position = camera.position.lerp(camera.position_target, t_pan);
}
}

This frame-rate-independent smoothing (exponential lerp) feels identical at 30 fps and 240 fps. The powf() call is once per frame, not per entity — negligible cost.

Discrete vs. continuous: Keyboard zoom (+/-) uses discrete steps (e.g., 0.25 increments). Mouse scroll uses finer steps (0.1). Both feed zoom_target and smooth toward it. There is NO “snap to integer zoom” constraint — smooth zoom is the default behavior. Classic render mode (D048) with integer scaling uses the same smooth zoom for camera movement but snaps the OrthographicProjection.scale to the nearest integer multiple when rendering, preventing sub-pixel shimmer on pixel art.

Zoom Interaction with Render Modes (D048)

Different render modes have different zoom characteristics:

When a render mode switch occurs (F1 / D048), the camera system adjusts:

• zoom_min / zoom_max to the new mode’s range
• zoom_target is clamped to the new range (if current zoom exceeds new limits)
• Camera position is preserved — only the zoom behavior changes

For 3D render modes, zoom maps to camera distance from the ground plane (dolly) rather than orthographic scale. The ScreenToWorld trait abstracts this — the camera system sets a zoom value, and the active ScreenToWorld implementation interprets it appropriately (orthographic scale for 2D, distance for 3D).

Pan (Scrolling)

Four input methods, all producing the same result — a position_target update:

Speed scales with zoom: When zoomed out, pan speed increases proportionally so map traversal time feels consistent. When zoomed in, pan speed decreases for precision. The scaling is linear: effective_speed = base_speed / zoom.

Bounds clamping: Every frame, position_target is clamped so the viewport stays within bounds (map rectangle plus a configurable padding). The player cannot scroll to see void beyond the map edge. Bounds are set when the map loads and do not change during gameplay.

Screen Shake

Triggered by game events (explosions, superweapons, building destruction) via Bevy events:

#![allow(unused)]
fn main() {
pub struct CameraShakeEvent {
    pub epicenter: WorldPos,   // world position of the explosion
    pub intensity: f32,        // 0.0–1.0 (nuke = 1.0, tank shell = 0.05)
    pub duration_secs: f32,    // how long the shake lasts
}
}

The shake system calculates amplitude from intensity, attenuated by distance from the camera. Multiple concurrent shakes are additive (capped at a maximum amplitude). The shake.offset is applied to the final camera transform each frame — it never modifies position or position_target, so the shake doesn’t drift the view.

Players can disable screen shake entirely via settings (/camera_shake off — D058) or reduce intensity with a slider. Accessibility concern: excessive screen shake can cause motion sickness.

Camera in Replays and Save Games

• Save games: GameCamera state (position, zoom, follow target) is serialized alongside other client-side state. On load, the camera restores to where the player was looking.
• Replays: CameraPositionSample events (see formats/save-replay-formats.md § “Analysis Event Stream”) record each player’s viewport center and zoom level at 2 Hz. Replay viewers can follow any player’s camera or use free camera. The replay camera is independent of the recorded camera data — the viewer controls their own viewport.
• Observer mode: Observers have independent camera control with no zoom restrictions (they can zoom out further than players for overview). The follow_player option (see ObserverState) syncs the observer’s camera to a player’s recorded CameraPositionSample stream.

Camera Configuration (YAML)

Per-game-module camera defaults:

camera:
  zoom:
    default: 1.0
    min: 0.5
    max: 4.0
    step_scroll: 0.1       # mouse wheel increment
    step_keyboard: 0.25    # +/- key increment
    smoothing: 0.15        # lerp factor (0 = instant, 1 = no movement)
    # Ranked override — competitive committee (D037) sets these per season
    ranked_min: 0.75
    ranked_max: 2.0
  pan:
    edge_scroll_speed: 1200.0   # world-units/sec at zoom 1.0
    keyboard_speed: 1000.0
    smoothing: 0.2
    edge_scroll_zone: 8        # pixels from screen edge to trigger
  shake:
    max_amplitude: 12.0         # max pixel displacement
    decay_rate: 8.0             # amplitude reduction per second
    enabled: true               # default; player can override in settings
  bounds_padding: 64            # extra world-units beyond map edges

This makes camera behavior fully data-driven (Principle 4 from 13-PHILOSOPHY.md). A Tiberian Sun module can set different zoom ranges (its taller buildings need more zoom-out headroom). A total conversion can disable edge scrolling entirely if it uses a different camera paradigm.

Game Speed

#![allow(unused)]
fn main() {
/// Lobby-configurable game speed.
pub struct GameSpeed {
    pub preset: SpeedPreset,
    pub tick_interval_ms: u32,   // sim tick period
}

pub enum SpeedPreset {
    Slowest,   // 80ms per tick
    Slower,    // 67ms per tick (default)
    Normal,    // 50ms per tick
    Faster,    // 35ms per tick
    Fastest,   // 20ms per tick
}
}

Speed affects only the interval between sim ticks — system behavior is tick-count-based, so all game logic works identically at any speed. Single-player can change speed mid-game; multiplayer sets it in lobby (synced).

Faction System

#![allow(unused)]
fn main() {
/// Faction identity — loaded from YAML.
pub struct Faction {
    pub internal_name: String,   // "allies", "soviet"
    pub display_name: String,    // "Allied Forces"
    pub side: String,            // "allies", "soviet" (for grouping subfactions)
    pub color: PlayerColor,
    pub tech_tree: TechTreeId,
    pub starting_units: Vec<StartingUnit>,
}
}

Factions determine: available tech tree (which units/buildings can be built), default player color, starting unit composition in skirmish, lobby selection, and Buildable.prereqs resolution. RA2 subfactions (e.g., Korea, Libya) share a side but differ in tech_tree (one unique unit each).

Auto-Target / Turret

#![allow(unused)]
fn main() {
/// Unit auto-acquires targets within range.
pub struct AutoTarget {
    pub scan_range: i32,
    pub stance: Stance,
    pub prefer_priority: bool,   // prefer high-priority targets
}

pub enum Stance {
    HoldFire,      // never auto-attack
    ReturnFire,    // attack only if attacked
    Defend,        // attack enemies in range
    AttackAnything, // attack anything visible
}

/// Turreted weapon — rotates independently of body.
pub struct Turreted {
    pub turn_speed: i32,
    pub offset: WorldPos,      // turret mount point relative to body
    pub current_facing: i32,   // turret facing (0-255)
}

/// Weapon requires ammo — must reload at dock (helipad).
pub struct AmmoPool {
    pub max_ammo: u32,
    pub current_ammo: u32,
    pub reload_delay: u32,    // ticks per ammo at dock
}
}

combat_system() integration: For units with AutoTarget and no current attack order: scan SpatialIndex within scan_range. Filter by Stance rules. Pick highest-priority valid target. For Turreted units: rotate turret toward target at turn_speed per tick before firing. For AmmoPool units: decrement ammo on fire; when depleted, return to nearest DockHost with DockType::Helipad for reload.

Selection Details

#![allow(unused)]
fn main() {
pub struct SelectionPriority {
    pub priority: i32,         // higher = selected preferentially
    pub click_priority: i32,   // higher = wins click-through
}
}

Selection features:

• Priority: When box-selecting 200 units, combat units are selected over harvesters (higher priority)
• Double-click: Select all units of the same type on screen
• Tab cycling: Cycle through unit types within a selection group
• Control groups: 0-9 control groups, Ctrl+# to assign, # to select, double-# to center camera
• Isometric selection box: Diamond-shaped box selection for proper isometric hit-testing

Observer / Spectator UI

Observer mode (separate from player mode) displays overlays not available to players:

#![allow(unused)]
fn main() {
pub struct ObserverState {
    pub show_army: bool,       // unit composition per player
    pub show_production: bool, // what each player is building
    pub show_economy: bool,    // income rate, credits per player
    pub show_powers: bool,     // superweapon charge timers
    pub show_score: bool,      // strategic score tracker
    pub follow_player: Option<PlayerId>,  // lock camera to player's view (writes GameCamera.follow_target)
}
}

Army overlay: Bar chart of unit counts per player, grouped by type. Production overlay: List of active queues per player. Economy overlay: Income rate graph. These are render-only — no sim interaction. Observer UI is an ic-ui concern.

Game Score / Performance Metrics

The sim tracks a comprehensive GameScore per player, updated every tick. This powers the observer economy overlay, post-game stats screen, and the replay analysis event stream (see formats/save-replay-formats.md § “Analysis Event Stream”). Design informed by SC2’s ScoreDetails protobuf (see research/blizzard-github-analysis.md § Part 2).

#![allow(unused)]
fn main() {
#[derive(Clone, Serialize, Deserialize)]
pub struct GameScore {
    // Economy
    pub total_collected: ResourceSet,      // lifetime resources harvested
    pub total_spent: ResourceSet,          // lifetime resources committed
    pub collection_rate: ResourceSet,      // current income per minute (fixed-point)
    pub idle_harvester_ticks: u64,         // cumulative ticks harvesters spent idle

    // Production
    pub units_produced: u32,
    pub structures_built: u32,
    pub idle_production_ticks: u64,        // cumulative ticks factories spent idle

    // Combat
    pub units_killed: u32,
    pub units_lost: u32,
    pub structures_destroyed: u32,
    pub structures_lost: u32,
    pub killed_value: ResourceSet,         // total value of enemy assets destroyed
    pub lost_value: ResourceSet,           // total value of own assets lost
    pub damage_dealt: i64,                 // fixed-point cumulative
    pub damage_received: i64,

    // Activity
    pub actions_per_minute: u32,           // APM (all orders)
    pub effective_actions_per_minute: u32, // EPM (non-redundant orders only)
}
}

APM vs EPM: Following SC2’s distinction — APM counts every order, EPM filters duplicate/redundant commands (e.g., repeatedly right-clicking the same destination). EPM is a better measure of meaningful player activity.

Sim-side only: GameScore lives in ic-sim (it’s deterministic state, not rendering). Observer overlays in ic-ui read it through the standard Simulation query interface.

Debug / Developer Tools

See also ../decisions/09g/D058-command-console.md for the unified chat/command console, cvar system, and Brigadier-style command tree that provides the text-based interface to these developer tools.

Developer mode (toggled in settings, not available in ranked):

#![allow(unused)]
fn main() {
pub struct DeveloperMode {
    pub instant_build: bool,
    pub free_units: bool,
    pub reveal_map: bool,
    pub unlimited_power: bool,
    pub invincible: bool,
    pub give_cash_amount: i32,
}
}

Debug overlays (via bevy_egui):

• Combat: weapon ranges as circles, target lines, damage numbers floating
• Pathfinding: flowfield visualization, path cost heat map, blocker highlight
• Performance: per-system tick time bar chart, entity count, memory usage
• Network: RTT graph, order latency, jitter, desync hash comparison
• Asset browser: preview sprites, sounds, palettes inline

Developer cheats issue special orders validated only when DeveloperMode is active. In multiplayer, all players must agree to enable dev mode (prevents cheating).

Security (V44): The consensus mechanism for multiplayer dev mode must be specified: dev mode is sim state (not client-side), toggled exclusively via PlayerOrder::SetDevMode with unanimous lobby consent before game start. Dev mode orders use a distinct PlayerOrder::DevCommand variant rejected by the sim when dev mode is inactive. Disabled for ranked matchmaking. See 06-SECURITY.md § Vulnerability 44.

Debug Drawing API

A programmatic drawing API for rendering debug geometry. Inspired by SC2’s DebugDraw interface (see research/blizzard-github-analysis.md § Part 7) — text, lines, boxes, and spheres rendered as overlays:

#![allow(unused)]
fn main() {
pub trait DebugDraw {
    fn draw_text(&mut self, pos: WorldPos, text: &str, color: Color);
    fn draw_line(&mut self, start: WorldPos, end: WorldPos, color: Color);
    fn draw_circle(&mut self, center: WorldPos, radius: i32, color: Color);
    fn draw_rect(&mut self, min: WorldPos, max: WorldPos, color: Color);
}
}

Used by AI visualization, pathfinding debug, weapon range display, and Lua/WASM debug scripts. All debug geometry is cleared each frame — callers re-submit every tick. Lives in ic-render (render concern, not sim).

Debug Unit Manipulation

Developer mode supports direct entity manipulation for testing:

• Spawn unit: Create any unit type at a position, owned by any player
• Kill unit: Instantly destroy selected entities
• Set resources: Override player credit balance
• Modify health: Set HP to any value

These operations are implemented as special PlayerOrder variants validated only when DeveloperMode is active. They flow through the normal order pipeline — deterministic across all clients.

Fault Injection (Testing Only)

For automated stability testing — not exposed in release builds:

• Hang simulation: Simulate tick timeout (verifies watchdog recovery)
• Crash process: Controlled exit (verifies crash reporting pipeline)
• Desync injection: Flip a bit in sim state (verifies desync detection and diagnosis)

These follow SC2’s DebugTestProcess pattern for CI/CD reliability testing.

Localization Framework

#![allow(unused)]
fn main() {
pub struct Localization {
    pub current_locale: String,         // "en", "de", "zh-CN"
    pub bundles: HashMap<String, FluentBundle>,  // locale → string bundle
}
}

Uses Project Fluent (same as OpenRA) for parameterized, pluralization-aware message formatting:

# en.ftl
unit-lost = Unit lost
base-under-attack = Our base is under attack!
building-complete = { $building } construction complete.
units-selected = { $count ->
    [one] {$count} unit selected
   *[other] {$count} units selected
}

Mods provide their own .ftl files. Engine strings are localizable from Phase 3. Community translations publishable to Workshop.

Encyclopedia

In-game unit/building/weapon reference browser:

#![allow(unused)]
fn main() {
pub struct EncyclopediaEntry {
    pub actor_type: ActorId,
    pub display_name: String,
    pub description: String,
    pub stats: HashMap<String, String>,  // "Speed: 8", "Armor: Medium"
    pub preview_sprite: SpriteId,
    pub category: EncyclopediaCategory,
}

pub enum EncyclopediaCategory { Infantry, Vehicle, Aircraft, Naval, Structure, Defense, Support }
}

Auto-generated from YAML rule definitions + optional encyclopedia: block in YAML. Accessible from main menu and in-game sidebar. Mod-defined units automatically appear in the encyclopedia.

Palette Effects (Runtime)

Beyond static .pal file loading (ic-cnc-content), runtime palette manipulation for classic RA visual style:

#![allow(unused)]
fn main() {
pub enum PaletteEffect {
    PlayerColorRemap { remap_range: (u8, u8), target_color: PlayerColor },
    Rotation { start_index: u8, end_index: u8, speed: u32 },  // water animation
    CloakShimmer { entity: EntityId },
    ScreenFlash { color: PaletteColor, duration: u32 },       // nuke, chronoshift
    DamageTint { entity: EntityId, state: DamageState },
}
}

Modern implementation: These are shader effects in Bevy’s render pipeline, not literal palette index swaps. But the modder-facing YAML configuration matches the original palette effect names for familiarity. Shader implementations achieve the same visual result with modern GPU techniques (color lookup textures, screen-space post-processing).

Demolition / C4

#![allow(unused)]
fn main() {
pub struct Demolition {
    pub delay: u32,               // ticks to detonation
    pub warhead: WarheadId,
    pub required_target: TargetType,  // buildings only
}
}

Engineer-type unit with Demolition places C4 on a building. After delay ticks, warhead detonates. Target building takes massive damage (usually fatal). Engineer is consumed.

Plug System

#![allow(unused)]
fn main() {
pub struct Pluggable {
    pub plug_type: PlugType,
    pub max_plugs: u32,
    pub current_plugs: u32,
    pub effect_per_plug: ConditionId,
}

pub struct Plug {
    pub plug_type: PlugType,
}
}

Primarily RA2 (bio-reactor accepting infantry for extra power). Included for mod compatibility. When a Plug entity enters a Pluggable building, increment current_plugs, grant condition per plug (e.g., “+50 power per infantry in reactor”).

Game Loop

Game Loop

GameLoop is the client-side frame loop — it always has a renderer and always draws. Headless consumers (dedicated servers, bot harnesses, automated tests) drive Simulation directly via its public API (see 02-ARCHITECTURE.md § External Sim API) and never instantiate GameLoop.

#![allow(unused)]
fn main() {
pub struct GameLoop<N: NetworkModel, I: InputSource> {
    sim: Simulation,
    renderer: Renderer,
    network: N,
    input: I,
    local_player: PlayerId,
    order_buf: Vec<TimestampedOrder>,  // reused across frames — zero allocation on hot path
}

impl<N: NetworkModel, I: InputSource> GameLoop<N, I> {
    fn frame(&mut self) {
        // 1. Gather local input with sub-tick timestamps
        self.input.drain_orders(&mut self.order_buf);
        for order in self.order_buf.drain(..) {
            self.network.submit_order(order);
        }

        // 2. Advance sim — bounded to avoid starving the renderer.
        //    At default Slower speed (~15 tps) / 60 fps, most frames process 0-1 ticks.
        //    The cap handles edge cases (e.g., multiplayer reconnect backlog,
        //    system sleep resume) where many ticks are ready at once.
        const MAX_TICKS_PER_FRAME: u32 = 4;
        let mut ticks_this_frame = 0;
        while let Some(tick_orders) = self.network.poll_tick() {
            self.sim.apply_tick(&tick_orders);
            self.network.report_sync_hash(
                self.sim.tick(),
                self.sim.state_hash(),
            );
            // Full SHA-256 hash at signing cadence for replay signatures
            if self.sim.tick().0 % SIGNING_CADENCE == 0 {
                self.network.report_state_hash(
                    self.sim.tick(),
                    self.sim.full_state_hash(),
                );
            }
            // If the sim transitioned to GameEnded this tick, report
            // the outcome to the network layer for relay consensus.
            // Also emit a final state hash for the terminal tick
            // regardless of signing cadence (see match-end signing below).
            if let Some(outcome) = self.sim.match_outcome() {
                self.network.report_state_hash(
                    self.sim.tick(),
                    self.sim.full_state_hash(),
                );
                self.network.report_game_ended(self.sim.tick(), outcome);
                break; // No more ticks — match is over
            }
            ticks_this_frame += 1;
            if ticks_this_frame >= MAX_TICKS_PER_FRAME {
                break; // Remaining ticks processed next frame
            }
        }

        // 3. Render always runs, interpolates between sim states
        self.renderer.draw(&self.sim, self.interpolation_factor());
    }
}
}

Match-end signing and outcome reporting: When a match ends (surrender vote, elimination, disconnect — see netcode/match-lifecycle.md), the game loop detects the sim’s GameEnded state via sim.match_outcome(), emits a final report_state_hash() for the terminal tick regardless of signing cadence, and calls report_game_ended() to send the outcome to the relay for consensus verification. This ensures the relay’s TickSignature chain covers the complete match with no unsigned tail (see formats/save-replay-formats.md § Signature Chain), and enables the relay to produce a CertifiedMatchResult from client consensus on sim-determined outcomes (see netcode/wire-format.md § Frame::GameEndedReport).

Key property: GameLoop is generic over N: NetworkModel and I: InputSource. It has zero knowledge of whether it’s running single-player or multiplayer, or whether input comes from a mouse, touchscreen, or gamepad. This is the central architectural guarantee.

Lockstep-family only. The GameLoop shown above is the lockstep client loop — it owns a full Simulation and calls sim.apply_tick() with confirmed orders from poll_tick(). This covers all shipping implementations: LocalNetwork, ReplayPlayback, EmbeddedRelayNetwork, and RelayLockstepNetwork. Deferred non-lockstep architectures (FogAuth, rollback) require a different client-side loop variant — FogAuth clients do not run the full sim but instead maintain a partial world via a reconciler (see research/fog-authoritative-server-design.md § 7), and rollback clients need speculative execution with snapshot/restore. The NetworkModel trait and ic-server capability infrastructure are designed to support these variants from day one, but the GameLoop struct itself would need a parallel implementation (e.g., FogAuthGameLoop) or an enum-based client driver. This is an M11 design concern (pending decision P007) — the current GameLoop is complete and correct for all pre-M11 milestones.

Not for headless use. GameLoop always renders — it is the client-side frame driver. ic-server runs the relay protocol without any GameLoop or Simulation instance. External bot/test harnesses use the external sim API (inject_orders() + step()) in their own loop — see 02-ARCHITECTURE.md § External Sim API for a concrete headless loop example. The sim’s headless capability is a property of ic-sim, not of GameLoop.

Game Lifecycle State Machine

The game application transitions through a fixed set of states. Design informed by SC2’s protocol state machine (see research/blizzard-github-analysis.md § Part 1), adapted for IC’s architecture:

┌──────────┐     ┌───────────┐     ┌─────────┐     ┌───────────┐
│ Launched │────▸│ InMenus   │────▸│ Loading │────▸│ InGame    │
└──────────┘     └───────────┘     └─────────┘     └───────────┘
                   ▲     │                            │       │
                   │     │                            │       │
                   │     ▼                            ▼       │
                   │   ┌───────────┐          ┌───────────┐   │
                   │   │ InReplay  │◂─────────│ GameEnded │   │
                   │   └───────────┘          └───────────┘   │
                   │         │                    │           │
                   └─────────┴────────────────────┘           │
                                                              ▼
                                                        ┌──────────┐
                                                        │ Shutdown │
                                                        └──────────┘

• Launched → InMenus: Engine initialization, asset loading, mod registration, and (when required) entry into the first-run setup wizard / setup assistant flow (D069). This remains menu/UI-only — no sim world exists yet.
• InMenus → Loading: Player starts a game or joins a lobby; map and rules are loaded
• Loading → InGame: All assets loaded, NetworkModel connected, sim initialized. See 03-NETCODE.md § “Match Lifecycle” for the ready-check and countdown protocol that governs this transition in multiplayer.
• InGame → GameEnded: Victory/defeat condition met, player surrenders (via the In-Match Vote Framework — PlayerOrder::Vote(VoteOrder::Propose { vote_type: Surrender })), vote-driven resolution (kick, remake, draw), or match void. See 03-NETCODE.md § “Match Lifecycle” for the surrender mechanic, team vote thresholds, and the generic callvote system.
• GameEnded → InMenus: Return to main menu. GameEnded IS the post-game screen: the 5-minute post-game lobby with stats display, chat, rating update, re-queue option, and replay save runs during this state (see 03-NETCODE.md § “Post-Game Flow”). Maps to NetworkStatus::PostGame(CertifiedMatchResult). The transition to InMenus occurs on user action (leave/re-queue) or lobby timeout.
• GameEnded → InReplay: Watch the just-finished game (.icrep is incrementally valid during recording — the viewer opens it immediately; the finalized archival header is written when the background writer flushes)
• InMenus → InReplay: Load a saved replay file
• InReplay → InMenus: Exit replay viewer
• InGame → Shutdown: Application exit (snapshot saved for resume on platforms that require it)

State transitions are events in Bevy’s event system — plugins react to transitions without polling. The sim exists only during InGame and InReplay; all other states are menu/UI-only.

D069 integration: The installation/setup wizard is modeled as an InMenus subflow (UI-only) rather than a separate app state that changes sim/network invariants. Platform/store installers may precede launch, but IC-controlled setup runs after Launched → InMenus using platform capability metadata (see PlatformInstallerCapabilities in platform-portability.md).

Match Cleanup & World Reset

When transitioning out of InGame or InReplay back to InMenus, the client must guarantee zero state leakage between matches. State leakage (lingering entities, stale resources, un-cleared caches) is a known class of “desync on match 2 but not match 1” bugs in RTS engines.

Strategy: drop and recreate. The Simulation (which owns the Bevy World containing all ECS entities, components, and sim resources) is dropped on match exit, not incrementally cleaned. A fresh Simulation is constructed on the next Loading → InGame transition. This is the simplest correct approach — it is impossible for state to leak across a drop boundary.

What is dropped:

• The entire Bevy World (all entities, components, resources) inside Simulation
• The UnitPool (tag allocator resets — new match starts at generation 0)
• All WASM mod instances (sandbox VMs are terminated and re-instantiated for the next match)
• Lua script state (VMs are dropped; fresh VMs created on next match load)
• Campaign runner state in GameRunner (replaced by new CampaignState or None)

What survives across matches:

• Bevy AssetServer and loaded asset handles (textures, audio, meshes) — these live in the outer Bevy App, not inside Simulation. Assets are shared across matches; the asset server’s reference counting handles unloading when no match references them.
• Player settings, keybindings, UI theme state (menu-layer resources)
• Network connection to the relay (for re-queue / rematch without reconnection)
• Mod registry and GameModule registration (module switching requires returning to InMenus and re-entering Loading with the new module)

Module switching (e.g., RA1 → TD): Requires a full return to InMenus. The GameModule registration is re-run during Loading for the new module. Because Simulation is dropped between matches, module-specific ECS components from the previous game are already gone. Asset handles for the previous module are released when their reference counts reach zero (Bevy’s standard asset lifecycle).

State Recording & Replay Infrastructure

State Recording & Replay Infrastructure

The sim’s snapshottable design (D010) enables a StateRecorder/Replayer pattern for asynchronous background recording — inspired by Valve’s Source Engine StateRecorder/StateReplayer pattern (see research/valve-github-analysis.md § 2.2). The game loop records orders and periodic state snapshots to a background writer; the replay system replays them through the same Simulation::apply_tick() path.

StateRecorder (Recording Side)

#![allow(unused)]
fn main() {
/// Orchestrates background recording of game state to `.icrep` files.
/// Tick-order frames and keyframe snapshot blobs are sent as separate
/// messages to a `BackgroundReplayWriter` (see `network-model-trait.md`
/// § Background Replay Writer). The game thread produces per-tick
/// `ReplayTickFrame`s (cheap — just orders + hash) and periodic
/// keyframe blobs (more expensive — see cost model below).
///
/// Lives in ic-game (I/O concern, not sim concern — Invariant #1).
pub struct StateRecorder {
    /// Background writer that drains tick frames and keyframe blobs,
    /// performs LZ4 compression, and appends to the `.icrep` file.
    /// Crash-safe: Fossilize append-safe pattern (see D010).
    writer: BackgroundReplayWriter,
    /// Keyframe cadence: a keyframe blob is produced every this many ticks
    /// (default: 300 — ~20 seconds at the Slower default of ~15 tps).
    keyframe_interval: u64,
    /// Full snapshot cadence: every Nth keyframe is a full `SimSnapshot`
    /// instead of a `DeltaSnapshot` (default: N=10, i.e., every 3000 ticks).
    full_keyframe_every_n: u64,
    /// Baseline for delta keyframes — the last full SimCoreSnapshot.
    last_full_snapshot: SimCoreSnapshot,
    /// Last-known campaign state for delta comparison (None if no campaign active).
    last_campaign_state: Option<CampaignState>,
    /// Last-known script state for delta comparison (None before first keyframe).
    last_script_state: Option<ScriptState>,
}
}

Per-tick recording (every tick): ic-game constructs a ReplayTickFrame { tick, state_hash, orders } and calls writer.record_tick(frame). Cost: negligible (the frame is a small struct; the background writer handles serialization and I/O).

Keyframe recording (every keyframe_interval ticks): ic-game produces the keyframe on the game thread in two steps — (1) Simulation::delta_snapshot(&self.last_full_snapshot) extracts a SimCoreDelta, (2) ic-game compares current campaign/script state against the recorder’s last_campaign_state / last_script_state baselines and composes the full DeltaSnapshot (or SimSnapshot at full-keyframe cadence), including campaign/script state only if changed since the respective baselines. The composed snapshot is serialized to Vec<u8> and passed to writer.record_keyframe(tick, is_full, blob). LZ4 compression and file I/O happen asynchronously on the background writer thread. After recording, the recorder updates its baselines: on full keyframes, all three baselines reset; on delta keyframes, only last_campaign_state and last_script_state are updated if they were included.

Game-thread cost model: Keyframe production costs ~1–1.5 ms per delta keyframe (every 300 ticks / ~20 seconds at Slower default) and ~2–3 ms per full keyframe (every 3000 ticks / ~200 seconds at Slower default) for a 500-unit game. This is well within the 67 ms tick budget (Slower default). The per-tick record_tick() call adds < 0.1 ms. LZ4 compression and disk I/O are fully async. See formats/save-replay-formats.md § Keyframe serialization threading for the full three-phase breakdown.

Per-Field Change Tracking (from Source Engine CNetworkVar)

To support delta snapshots efficiently, the sim uses per-field change tracking — inspired by Source Engine’s CNetworkVar system (see research/valve-github-analysis.md § 2.2). Each ECS component that participates in snapshotting is annotated with a #[track_changes] derive macro. The macro generates a companion bitfield that records which fields changed since the last snapshot. Delta serialization then skips unchanged fields entirely.

#![allow(unused)]
fn main() {
/// Derive macro that generates per-field change tracking for a component.
/// Each field gets a corresponding bit in a compact `ChangeMask` bitfield.
/// When a field is modified through its setter, the bit is set.
/// Delta serialization reads the mask to skip unchanged fields.
///
/// Components with SPROP_CHANGES_OFTEN (position, health, facing) are
/// checked first during delta computation — improves cache locality
/// by touching hot data before cold data. See `10-PERFORMANCE.md`.
#[derive(Component, Serialize, Deserialize, TrackChanges)]
pub struct Mobile {
    pub position: WorldPos,        // changes every tick during movement
    pub facing: FixedAngle,        // changes every tick during turning
    pub speed: FixedPoint,         // changes occasionally
    pub locomotor_type: Locomotor, // rarely changes
}

// Generated by #[derive(TrackChanges)]:
// impl Mobile {
//     pub fn set_position(&mut self, val: WorldPos) {
//         self.position = val;
//         self.change_mask |= 0b0001;
//     }
//     pub fn change_mask(&self) -> u8 { self.change_mask }
//     pub fn clear_changes(&mut self) { self.change_mask = 0; }
// }
}

SPROP_CHANGES_OFTEN priority (from Source Engine): Components that change frequently (position, health, ammunition) are tagged and processed first during delta encoding. This isn’t a correctness concern — it’s a cache locality optimization. By processing high-churn components first, the delta encoder touches frequently-modified memory regions while they’re still in L1/L2 cache. See 10-PERFORMANCE.md for performance impact analysis.

Crash-Time State Capture

When a desync is detected (hash mismatch via report_sync_hash()), the system automatically captures a full state snapshot before any error handling or recovery:

#![allow(unused)]
fn main() {
/// Called by ic-game when a sync hash mismatch is detected.
/// Captures full composite state immediately — before the sim advances
/// further — so the exact divergence point is preserved for offline
/// analysis, including script-managed state that might be the root cause.
fn on_desync_detected(
    sim: &Simulation,
    script_engine: &ScriptEngine,   // ic-script handle (owned by ic-game)
    campaign: &CampaignState,
    tick: u64,
    local_hash: u64,
    remote_hash: u64,
) {
    // 1. Immediate sim core snapshot (SimCoreSnapshot — sim-internal state)
    let core = sim.snapshot();
    // 2. Collect external state so the dump includes script/campaign data.
    //    This mirrors the full SimSnapshot composition path used by saves
    //    and replay keyframes — if divergence is rooted in script state,
    //    the dump captures it.
    let script_state = script_engine.snapshot_all();
    let full = SimSnapshot {
        core,
        campaign_state: Some(campaign.clone()),
        script_state: Some(script_state),
    };
    // 3. Write to crash dump file (same Fossilize append-safe pattern)
    write_crash_dump(tick, local_hash, remote_hash, &full);
    // 4. If Merkle tree is available, capture the tree for
    //    logarithmic desync localization (see 03-NETCODE.md)
    if let Some(tree) = sim.merkle_tree() {
        write_merkle_dump(tick, &tree);
    }
    // 5. Continue with normal desync handling (reconnect, notify user, etc.)
}
}

This ensures desync debugging always has a snapshot at the exact point of divergence — not N ticks later when the developer gets around to analyzing it. The pattern comes from Valve’s Fossilize (crash-safe state capture, see research/valve-github-analysis.md § 3.1) and OpenTTD’s periodic desync snapshot naming convention (desync_{seed}_{tick}.snap).

ML Training Data Extraction

The same keyframe snapshots and order streams that power replay playback also serve as the foundation for AI training data extraction. The StateRecorder’s output (.icrep files with tick-order frames + periodic keyframe snapshots) can be processed offline into structured training datasets:

• Keyframe snapshots → game state observations. Each SimCoreSnapshot or DeltaSnapshot provides the full game state at a point in time. The extraction pipeline applies fog-of-war filtering (same FogFilteredView as live gameplay) to produce per-player observations.
• Tick-order frames → action labels. The ReplayTickFrame { tick, state_hash, orders } recorded every tick provides the ground truth for “what the player did at tick T.”
• Analysis events → temporal context. The optional analysis event stream (HAS_EVENTS flag) provides unit lifecycle, economy snapshots, and camera tracking between keyframes — enriching training samples with recent event history.
• Keyframe seeking → arbitrary tick reconstruction. The keyframe index enables binary-search seeking to any point in the match, then forward simulation to the exact target tick. This means training data can be extracted at any stride without re-simulating from tick 0.

Training extraction operates read-only on .icrep files — no sim modification, no recording changes. The extraction pipeline is a consumer of the same replay format that powers spectator replay, desync debugging, and save games.

See research/ml-training-pipeline-design.md for the complete training pair schema, Parquet export format, headless self-play generation, and the ic training generate / ic training export CLI specification.

Pathfinding & Spatial Queries

Pathfinding & Spatial Queries

Decision: Pathfinding and spatial queries are abstracted behind traits — like NetworkModel. A multi-layer hybrid pathfinder is the first implementation (RA1 game module). The engine core has no hardcoded assumption about grids vs. continuous space.

OpenRA uses hierarchical A* which struggles with large unit groups and lacks local avoidance. A multi-layer approach (hierarchical sectors + JPS/flowfield tiles + ORCA-lite avoidance) handles both small-group and mass unit movement. But pathfinding is a game-module concern, not an engine-core assumption.

Pathfinder Trait

#![allow(unused)]
fn main() {
/// Game modules implement this to provide pathfinding.
/// Grid-based games use multi-layer hybrid (JPS + flowfield tiles + avoidance).
/// Continuous-space games would use navmesh.
/// The engine core calls this trait — never a specific algorithm.
pub trait Pathfinder: Send + Sync {
    /// Request a path from origin to destination.
    /// Returns a local handle (`PathId`) used only inside the running sim instance.
    /// `PathId` is not part of network protocol or replay/save serialization.
    fn request_path(&mut self, origin: WorldPos, dest: WorldPos, locomotor: LocomotorType) -> PathId;

    /// Poll for completed path. Returns waypoints in WorldPos.
    fn get_path(&self, id: PathId) -> Option<&[WorldPos]>;

    /// Can a unit with this locomotor pass through this position?
    fn is_passable(&self, pos: WorldPos, locomotor: LocomotorType) -> bool;

    /// Invalidate cached paths (e.g., building placed, bridge destroyed).
    fn invalidate_area(&mut self, center: WorldPos, radius: SimCoord);

    /// Query the path distance between two points without computing full waypoints.
    /// Returns `None` if no path exists. Used by AI for target selection, threat assessment,
    /// and build placement scoring.
    fn path_distance(&self, from: WorldPos, to: WorldPos, locomotor: LocomotorType) -> Option<SimCoord>;

    /// Batch distance queries — amortizes overhead when AI needs distances to many targets.
    /// Writes results into caller-provided scratch (`out`) in the same order as `targets`.
    /// `None` entries mean no path. Implementations must clear/reuse `out` (no hidden heap scratch
    /// returned to the caller), preserving the zero-allocation hot-path discipline.
    /// Design informed by SC2's batch `RequestQueryPathing` (see `research/blizzard-github-analysis.md` § Part 4).
    fn batch_distances_into(
        &self,
        from: WorldPos,
        targets: &[WorldPos],
        locomotor: LocomotorType,
        out: &mut Vec<Option<SimCoord>>,
    );

    /// Convenience wrapper for non-hot paths (tools/debug/tests).
    /// Hot gameplay loops should prefer `batch_distances_into`.
    fn batch_distances(
        &self,
        from: WorldPos,
        targets: &[WorldPos],
        locomotor: LocomotorType,
    ) -> Vec<Option<SimCoord>> {
        let mut out = Vec::with_capacity(targets.len());
        self.batch_distances_into(from, targets, locomotor, &mut out);
        out
    }
}
}

SpatialIndex Trait

#![allow(unused)]
fn main() {
/// Game modules implement this for spatial queries (range checks, collision, targeting).
/// Grid-based games use a spatial hash grid. Continuous-space games could use BVH or R-tree.
/// The engine core queries this trait — never a specific data structure.
pub trait SpatialIndex: Send + Sync {
    /// Find all entities within range of a position.
    /// Writes results into caller-provided scratch (`out`) with deterministic ordering.
    /// Contract: for identical sim state + filter, the output order must be identical on all clients.
    /// Default recommendation is ascending `EntityId`, unless a stricter subsystem-specific contract exists.
    fn query_range_into(
        &self,
        center: WorldPos,
        range: SimCoord,
        filter: EntityFilter,
        out: &mut Vec<EntityId>,
    );

    /// Update entity position in the index.
    fn update_position(&mut self, entity: EntityId, old: WorldPos, new: WorldPos);

    /// Remove entity from the index.
    fn remove(&mut self, entity: EntityId);
}
}

Determinism, Snapshot, and Cache Rules (Pathfinding/Spatial)

The Pathfinder and SpatialIndex traits are algorithm seams, but they still operate under the simulation’s deterministic/snapshottable rules:

• Authoritative state lives in ECS/components, not only inside opaque pathfinder internals.
• Path IDs are local handles, not stable serialized identifiers.
• Derived caches (flowfield caches, sector caches, spatial buckets, temporary query results) may be omitted from snapshots and rebuilt on load/restore/reconnect.
• Pending path requests must be either:
  • represented in authoritative sim state, or
  • safely reconstructible deterministically on restore.
• Internal parallelism is allowed only if the visible outputs (paths, distances, query results) are deterministic and independent of worker scheduling/order.
• Validation/debug tooling may recompute caches from authoritative state (see 03-NETCODE.md cache validation) to detect missed invalidation bugs.

Why This Matters

This is the same philosophy as WorldPos.z — costs near-zero now, prevents rewrites later:

The RA1 game module registers three Pathfinder implementations — RemastersPathfinder, OpenRaPathfinder, and IcPathfinder (D045) — plus GridSpatialHash. The active pathfinder is selected via experience profiles (D045). A deferred/optional continuous-space game module would register NavmeshPathfinder and BvhSpatialIndex. The sim core calls the trait — it never knows which one is running. The same principle applies to fog, damage, AI, ranking, and validation — see D041 in decisions/09d-gameplay.md for the full trait definitions and rationale.

Platform Portability

Platform Portability

The engine must not create obstacles for any platform. Desktop is the primary dev target, but every architectural choice must be portable to browser (WASM), mobile (Android/iOS), and consoles without rework.

Player Data Directory (D061)

All player data lives under a single, self-contained directory. The structure is stable and documented — a manual copy of this directory is a valid (if crude) backup. The ic backup CLI provides a safer alternative using SQLite VACUUM INTO for consistent database copies. See decisions/09e/D061-data-backup.md for full rationale, backup categories, and cloud sync design.

<data_dir>/
├── config.toml              # Settings (D033 toggles, keybinds, render quality)
├── profile.db               # Identity, friends, blocks, privacy (D053)
├── achievements.db          # Achievement collection (D036)
├── gameplay.db              # Event log, replay catalog, save index, map catalog (D034)
├── telemetry.db             # Unified telemetry events (D031) — pruned at 100 MB
├── keys/
│   └── identity.key         # Ed25519 private key (D052) — recoverable via mnemonic seed phrase (D061)
├── communities/             # Per-community credential stores (D052)
│   ├── official-ic.db
│   └── clan-wolfpack.db
├── saves/                   # Save game files (.icsave)
├── replays/                 # Replay files (.icrep)
├── screenshots/             # PNG with IC metadata in tEXt chunks
├── workshop/                # Downloaded Workshop content (D030)
├── mods/                    # Locally installed mods
├── maps/                    # Locally installed maps
├── logs/                    # Engine log files (rotated)
└── backups/                 # Created by `ic backup create`

Platform-specific <data_dir> resolution:

Override with IC_DATA_DIR environment variable or --data-dir CLI flag. All path resolution is centralized in ic-paths (see § Crate Design Notes). All asset loading goes through Bevy’s asset system (rule 5 below) — the data directory is for player-generated content, not game assets.

Data & Backup UI (D061)

The in-game Settings → Data & Backup panel exposes backup, restore, cloud sync, and profile export — the GUI equivalent of the ic backup CLI. A Data Health summary shows identity key status, sync recency, backup age, and data folder size. Critical data is automatically protected by rotating daily snapshots (auto-critical-N.zip, 3-day retention) and optional platform cloud sync (Steam Cloud / GOG Galaxy).

First-launch flow integrates with D032’s experience profile selection:

1. New player: identity created automatically → 24-word recovery phrase displayed → cloud sync offer → backup reminder prompt
2. Returning player on new machine: cloud data detected → restore offer showing identity, rating, match count; or mnemonic seed recovery (enter 24 words); or manual restore from backup ZIP / data folder copy

Post-milestone toasts (same system as D030’s Workshop cleanup prompts) nudge players without cloud sync to back up after ranked matches, campaign completion, or tier promotions. See decisions/09e/D061-data-backup.md “Player Experience” for full UX mockups and scenario walkthroughs.

Portability Design Rules

1. Input is abstracted behind a trait. InputSource produces PlayerOrders — it knows nothing about mice, keyboards, touchscreens, or gamepads. The game loop consumes orders, not raw input events. Each platform provides its own InputSource implementation.

2. UI layout is responsive. No hardcoded pixel positions. The sidebar, minimap, and build queue use constraint-based layout that adapts to screen size and aspect ratio. Mobile/tablet may use a completely different layout (bottom bar instead of sidebar). ic-ui provides layout profiles, not a single fixed layout.

3. Click-to-world is abstracted behind a trait. Isometric screen→world (desktop), touch→world (mobile), and raycast→world (3D mod) all implement the same ScreenToWorld trait, producing a WorldPos. Grid-based game modules convert to CellPos as needed. No isometric math or grid assumption hardcoded in the game loop.

4. Render quality is configurable per device. FPS cap, particle density, post-FX toggles, resolution scaling, shadow quality — all runtime-configurable. Mobile caps at 30fps; desktop targets 60-240fps. The renderer reads a RenderSettings resource, not compile-time constants. Four render quality tiers (Baseline → Standard → Enhanced → Ultra) are auto-detected from wgpu::Adapter capabilities at startup. Tier 0 (Baseline) targets GL 3.3 / WebGL2 hardware — no compute shaders, no post-FX, CPU particle fallback, palette tinting for weather. Advanced Bevy rendering features (3D render modes, heavy post-FX, dynamic lighting) are optional layers, not baseline requirements; the classic 2D game must remain fully playable on no-dedicated-GPU systems that meet the downlevel hardware floor. See 10-PERFORMANCE.md § “GPU & Hardware Compatibility” for tier definitions and hardware floor analysis.

5. No raw filesystem I/O. All asset loading goes through Bevy’s asset system, never std::fs directly. Mobile and browser have sandboxed filesystems; WASM targets use browser storage APIs (OPFS primary, IndexedDB fallback, localStorage for settings only — see 05-FORMATS.md § Browser Asset Storage). Save games use platform-appropriate storage (OPFS/IndexedDB on web, app sandbox on mobile).

6. App lifecycle is handled. Mobile and consoles require suspend/resume/save-on-background. The snapshottable sim makes this trivial for single-player and local scenarios — snapshot() on suspend, restore() on resume. For live multiplayer, the local snapshot preserves state for crash recovery, but full recovery follows the reconnection protocol (relay-coordinated donor snapshot, verification, catch-up — see desync-recovery.md § Reconnection). The NetworkModel handles reconnection; the engine’s lifecycle hook handles the local snapshot. These are complementary, not interchangeable.

7. Audio backend is abstracted. Bevy handles this, but no code should assume a specific audio API. Platform-specific audio routing (e.g., phone speaker vs headphones, console audio mixing policies) is Bevy’s concern.

Platform Target Matrix

Input Abstraction

#![allow(unused)]
fn main() {
/// Platform-agnostic input source. Each platform implements this.
/// Covers simulation orders (hot path, every tick) and UI-level input
/// (chat, navigation — used in lobby and post-game loops).
pub trait InputSource {
    /// Drain pending player orders from whatever input device is active.
    fn drain_orders(&mut self, buf: &mut Vec<TimestampedOrder>);
    // Caller provides the buffer (reused across ticks — zero allocation on hot path)

    /// Optional: hint about input capabilities for UI adaptation.
    fn capabilities(&self) -> InputCapabilities;

    /// Drain a pending chat message typed by the user (lobby/post-game).
    /// Returns None if no chat input is pending. Platform implementations
    /// source this from text fields, on-screen keyboards, etc.
    /// Default: no-op (platforms without chat input).
    fn drain_chat_input(&mut self) -> Option<ChatMessage> { None }

    /// Whether the user has signaled intent to leave the current screen
    /// (e.g., pressed Escape, tapped Back, clicked Leave button).
    /// Used by post-game and lobby loops. Default: false.
    fn wants_leave(&self) -> bool { false }
}

pub struct InputCapabilities {
    pub has_mouse: bool,
    pub has_keyboard: bool,
    pub has_touch: bool,
    pub has_gamepad: bool,
    pub screen_size: ScreenClass,  // Phone, Tablet, Desktop, TV
}

pub enum ScreenClass {
    Phone,    // < 7" — bottom bar UI, large touch targets
    Tablet,   // 7-13" — sidebar OK, touch targets
    Desktop,  // 13"+ — full sidebar, mouse precision
    TV,       // 40"+ — large text, gamepad radial menus
}
}

ic-ui reads InputCapabilities to choose the appropriate layout profile. The sim never sees any of this.

Platform Installer / Setup Capability Split (D069)

The first-run setup wizard (D069) needs a platform capability view that is separate from raw input capabilities. This captures what the distribution channel / platform shell already handles (binary install/update/verify, cloud availability, file browsing constraints) so IC can avoid duplicating responsibilities.

#![allow(unused)]
fn main() {
pub enum PlatformInstallChannel {
    StoreSteam,
    StoreGog,
    StoreEpic,
    StandaloneDesktop,
    Browser,
    Mobile,
    Console,
}

pub struct PlatformInstallerCapabilities {
    pub channel: PlatformInstallChannel,
    pub platform_handles_binary_install: bool,
    pub platform_handles_binary_updates: bool,
    pub platform_exposes_verify_action: bool, // Steam/GOG-style "verify files"
    pub supports_cloud_sync_offer: bool,      // via PlatformServices or platform API
    pub supports_manual_folder_browse: bool,  // browser/mobile often restricted
    pub supports_background_downloads: bool,  // policy/OS dependent
}
}

ic-game (platform integration layer) populates PlatformInstallerCapabilities and injects it into ic-ui. The D069 setup wizard and maintenance flows use it to decide:

• whether to show platform verify guidance vs IC-side content repair only
• whether to offer manual folder browsing as a primary or fallback path
• whether to present a browser/mobile “setup assistant” variant instead of a desktop-style installer narrative

This preserves the platform-agnostic engine core while making setup UX platform-aware in a principled way.

UI Theme System (D032)

UI Theme System (D032)

The UI is split into two orthogonal concerns:

• Layout profiles — where things go. Driven by ScreenClass (Phone, Tablet, Desktop, TV). Handles sidebar vs bottom bar, touch target sizes, minimap placement, mobile minimap clusters (alerts + camera bookmark dock), and semantic UI anchor resolution (e.g., primary_build_ui maps to sidebar on desktop/tablet and build drawer on phone). One per screen class.
• Themes — how things look. Driven by player preference. Handles colors, chrome sprites, fonts, animations, menu backgrounds. Switchable at any time.

This split is also what enables cross-device tutorial prompts without duplicating tutorial content: D065 references semantic actions and UI aliases, and ic-ui resolves them through the active layout profile chosen from InputCapabilities.

Localization Directionality & RTL/BiDi Layout Contract

Localization support is not just “font coverage.” IC must correctly support bidirectional (BiDi) text, RTL scripts (Arabic/Hebrew), and locale-aware UI layout behavior anywhere translatable text appears (menus, HUD labels, subtitles, dialogue, campaign UI, editor docs/help, and communication labels).

#![allow(unused)]
fn main() {
pub enum UiLayoutDirection {
    Ltr,
    Rtl,
}

pub enum DirectionalUiAssetPolicy {
    MirrorInRtl,
    FixedOrientation,
}
}

Architectural rules (normative):

• Text rendering supports shaping + BiDi. The shared UI text renderer must correctly handle Arabic shaping, Hebrew/Arabic punctuation behavior, and mixed-script strings (RTL + LTR + numbers) for UI, subtitles/closed captions, and communication labels.
• Font support is script-aware, not just “Unicode-capable.” ThemeFonts captures the preferred visual style per role (menu/body/HUD/mono), while the renderer resolves locale/script-aware fallback chains so missing glyphs do not silently break localized or RTL UI.
• Layout direction is locale-driven by default. UI layout profiles resolve anchors/alignments from the active locale (LTR/RTL) and may expose a QA/testing override (Auto, LTR, RTL) without changing the locale itself.
• Mirroring is selective, not global. Menu/settings/profile/chat panels and many list/detail layouts usually mirror in RTL, but battlefield/world-space semantics (map orientation, minimap world mapping, world coordinates, faction symbols where direction carries meaning) are not blindly mirrored.
• Directional assets declare policy. Icons/arrows/ornaments that can flip for readability must declare MirrorInRtl; assets with gameplay or symbolic orientation must declare FixedOrientation.
• Avoid baked text in images. UI chrome/images should not contain baked translatable text where possible. If unavoidable, localized variants are required and must be selected through the same asset/theme pipeline.
• Communication display reuses the same renderer, with D059 safety filtering. Legitimate RTL/LTR message/label display is preserved; anti-spoof filtering (dangerous BiDi controls, abusive invisible chars) is handled at the D059 input/sanitization layer before order injection.
• Shaping, BiDi resolution, and fallback are separate responsibilities under one shared contract. The implementation may use separate components for shaping, BiDi resolution, and font fallback, but ic-ui owns the canonical behavior and tests so runtime/editor/chat surfaces remain consistent.
• Localization QA validates layout with fallback fonts. Mixed-script strings, subtitles, and marker labels must be tested for wrap, truncation, clipping, and baseline alignment across fallback fonts (not just glyph existence), with D038 localization tooling surfacing these checks before publish.

This contract keeps ic-ui platform-agnostic and ensures localization correctness is implemented once in shared rendering/layout code rather than patched per screen or per platform.

Smart Font Fallback & Text Shaping Strategy (Localization)

RTL and broad localization support require a font-system strategy, not a single “full Unicode” font choice.

Requirements (normative):

• Theme fonts define style intent; runtime resolves fallback chains. Themes choose the preferred look (Inter, JetBrains Mono, etc.) while ic-ui resolves locale/script-aware fallback fonts for glyph coverage and shaping compatibility.
• Fallback chains are role-aware. Menu/body/HUD/monospace roles may use different fallback stacks; monospaced surfaces must not silently fall back to proportional fonts unless explicitly allowed by the UI surface policy.
• Fallback behavior is deterministic at layout time. The same normalized text + locale/layout-direction inputs should produce the same line breaks/glyph runs across supported platforms, except for explicitly documented platform-stack differences that are regression-tested in M11.PLAT.BROWSER_MOBILE_POLISH.
• Directionality testing includes font fallback. QA/testing direction overrides (Auto, LTR, RTL) must exercise the active fallback stack so clipping, punctuation placement, and spacing regressions are caught before release.
• Open-source text-stack lessons are implementation guidance, not architecture lock-in. IC may learn from HarfBuzz/FriBidi/Pango/Godot/Qt patterns, but the canonical behavior remains defined by this contract and D038 localization preview tooling.

Theme Architecture

Themes are YAML + sprite sheets — Tier 1 mods, no code required.

#![allow(unused)]
fn main() {
pub struct UiTheme {
    pub name: String,
    pub chrome: ChromeAssets,    // 9-slice panels, button states, scrollbar sprites
    pub colors: ThemeColors,     // primary, secondary, text, highlights
    pub fonts: ThemeFonts,       // menu, body, HUD
    pub main_menu: MainMenuConfig,  // background image or shellmap, music, button layout
    pub ingame: IngameConfig,    // sidebar style, minimap border, build queue chrome
    pub lobby: LobbyConfig,     // panel styling, slot layout
}
}

Built-in Themes

All art assets are original creations — no assets copied from EA or OpenRA. These themes capture aesthetic philosophy, not specific artwork.

Shellmap System

Main menu backgrounds can be live battles — a real game map with scripted AI running behind the menu UI:

• Per-theme configuration: Classic uses a static image (faithful to 1996), Remastered/Modern use shellmaps
• Maps tagged visibility: shellmap are eligible — random selection on each launch
• Shellmaps define camera paths (pan, orbit, or fixed)
• Mods automatically get their own shellmaps

Per-Game-Module Defaults

Each GameModule provides a default_theme() — RA1 defaults to Classic, future modules default to whatever fits their aesthetic. Players override in settings. This pairs naturally with D019 (switchable balance presets): Classic balance + Classic theme = feels like 1996.

Community Themes

• Publishable to workshop (D030) as standalone resources
• Stack with gameplay mods — a WWII total conversion ships its own olive-drab theme
• An “OpenRA-inspired” community theme is a natural contribution

See decisions/09c-modding.md § D032 for full rationale, YAML schema, and legal notes on asset sourcing.

QoL & Gameplay Behavior Toggles (D033)

QoL & Gameplay Behavior Toggles (D033)

Every quality-of-life improvement from OpenRA and the Remastered Collection is individually toggleable — attack-move, multi-queue production, health bars, range circles, guard command, waypoint queuing, and dozens more. Built-in presets group toggles into coherent profiles:

Toggles are categorized as sim-affecting (production rules, unit commands — synced in lobby) or client-only (health bars, range circles — per-player preference). This split preserves determinism (invariant #1) while giving each player visual/UX freedom.

Experience Profiles

D019 (balance), D032 (theme), D033 (behavior), D043 (AI behavior), D045 (pathfinding feel), and D048 (render mode) are six independent axes that compose into experience profiles. Selecting “Vanilla RA” sets all six to classic in one click. Selecting “Iron Curtain” sets classic balance + modern theme + best QoL + enhanced AI + modern movement + HD graphics. After selecting a profile, any individual setting can still be overridden.

Mod profiles (D062) are a superset of experience profiles: they bundle the six experience axes WITH the active mod set and conflict resolutions into a single named, hashable object. A mod profile answers “what mods am I running AND how is the game configured?” in one saved TOML file (D067). The profile’s fingerprint (SHA-256 of the resolved virtual asset namespace) enables single-hash compatibility checking in multiplayer lobbies. Switching profiles reconfigures both the mod set and experience settings in one action. Publishing a local mod profile via ic mod publish-profile creates a Workshop modpack (D030). See decisions/09c-modding.md § D062.

See decisions/09d/D033-qol-presets.md for the full toggle catalog, YAML schema, and sim/client split details. See D043 for AI behavior presets, D045 for pathfinding behavior presets, and D048 for switchable render modes.

Red Alert Experience Recreation Strategy

Red Alert Experience Recreation Strategy

Making IC feel like Red Alert requires more than loading the right files. The graphics, sounds, menu flow, unit selection, cursor behavior, and click feedback must recreate the experience that players remember — verified against the actual source code. We have access to four authoritative reference codebases. Each serves a different purpose.

Reference Source Strategy

The principle: Original RA tells us what the values ARE. Remastered tells us what a modern version SHOULD feel like. OpenRA tells us what the community EXPECTS. Bevy tells us how to BUILD it.

Visual Fidelity Checklist

These are the specific visual elements that make Red Alert look like Red Alert. Each must be verified against original source code constants, not guessed from screenshots.

Sprite Rendering Pipeline

Z-Order (Draw Order)

The draw order determines what renders on top of what. Getting this wrong makes the game look subtly broken — units clipping through buildings, shadows on top of vehicles, overlays behind walls. The canonical order (verified from original source and OpenRA):

Layer 0: Terrain tiles (ground)
Layer 1: Smudges (craters, scorch marks, oil stains)
Layer 2: Building bibs (paved foundations)
Layer 3: Building shadows + unit shadows
Layer 4: Buildings (sorted by Y position — southern buildings render on top)
Layer 5: Infantry (sub-cell positioned)
Layer 6: Vehicles / Ships (sorted by Y position)
Layer 7: Aircraft shadows (on ground)
Layer 8: Low-flying aircraft (sorted by Y position)
Layer 9: High-flying aircraft
Layer 10: Projectiles
Layer 11: Explosions / visual effects
Layer 12: Shroud / fog-of-war overlay
Layer 13: UI overlays (health bars, selection boxes, waypoint lines)

Within each layer, entities sort by Y-coordinate (south = higher draw order = renders on top). This is the standard isometric sort that prevents visual overlapping artifacts. Bevy’s sprite z-ordering maps to this layer system via Transform.translation.z.

Audio Fidelity Checklist

Red Alert’s audio is iconic — the EVA voice, unit responses, Hell March, the tesla coil zap. Audio fidelity requires matching the original game’s mixing behavior, not just playing the right files.

Sound Categories and Mixing

Original RA music system: The original game’s music was a straightforward sequential playlist. THEME.CPP manages a track list with per-theme attributes — each theme has a scenario owner (some tracks only play in certain missions) and a duration. In skirmish, the full soundtrack is available. In campaign, the scenario INI can specify a starting theme, but once playing, tracks advance sequentially and the player can pick from the jukebox in the options menu. There is no combat-detection system, no crossfades, and no dynamic intensity shifting. The Remastered Collection and OpenRA both preserve this simple jukebox model.

IC enhancement — dynamic situational music: While the original RA’s engine didn’t support dynamic music, IC’s engine and SDK treat dynamic situational music as a first-class capability. Frank Klepacki designed the RA soundtrack with gameplay tempo in mind — high-energy industrial during combat, ambient tension during build-up (see 13-PHILOSOPHY.md § Principle #11) — but the original engine didn’t act on this intent. IC closes that gap at the engine level.

ic-audio provides three music playback modes, selectable per game module, per mission, or per mod:

# audio/music_config.yaml
music_mode: dynamic               # "jukebox" | "sequential" | "dynamic"

# Jukebox mode (classic RA behavior):
jukebox:
  tracks: [BIGF226M, GRNDWIRE, HELLMARCH, MUDRA, JBURN_RG, TRENCHES, CC_THANG, WORKX_RG]
  order: sequential               # or "shuffle"
  loop: true

# Dynamic mode (IC engine feature — mood-tagged tracks with state-driven selection):
dynamic_playlist:
  ambient:
    tracks: [BIGF226M, MUDRA, JBURN_RG]
  build:
    tracks: [GRNDWIRE, WORKX_RG]
  combat:
    tracks: [HELLMARCH, TRENCHES, CC_THANG]
  tension:
    tracks: [RADIO2, FACE_THE_ENEMY]
  victory:
    tracks: [RREPORT]
  defeat:
    tracks: [SMSH_RG]
  crossfade_ms: 2000              # default crossfade between mood transitions
  combat_linger_s: 5              # stay in combat music 5s after last engagement

In dynamic mode, the engine monitors game state — active combat, base threat level, unit losses, objective progress — and crossfades between mood categories automatically. Designers tag tracks by mood; the engine handles transitions. No scripting required for basic dynamic music.

Three layers of control for mission/mod creators:

The scenario editor’s Music Playlist module (see decisions/09f/D038-scenario-editor.md “Dynamic Music”) exposes the full dynamic system visually — a designer drags tracks into mood buckets and previews transitions without writing code. The Music Trigger module handles scripted one-shot moments (“play Hell March when the tanks breach the wall”). Both emit standard Lua that modders can extend.

The music_mode setting defaults to dynamic under the iron_curtain experience profile and jukebox under the vanilla profile for RA1’s built-in soundtrack. Game modules and total conversions define their own default mode and mood-tagged playlists. This is Tier 1 YAML configuration — no recompilation, no Lua required for basic use.

Unit Voice System

Unit voice responses follow a specific pattern from the original game:

Implementation: Unit voice definitions live in mods/ra/rules/units/*.yaml alongside other unit data:

# In rules/units/vehicles.yaml
medium_tank:
  voices:
    select: [VEHIC1, REPORT1, YESSIR1]
    move: [ACKNO, AFFIRM1, MOVOUT1]
    attack: [AFFIRM1, YESSIR1]
    deny: [NEGAT1, CANTDO1]
  voice_interval: 200     # minimum ticks between voice responses (prevents spam)

UX Fidelity Checklist

These are the interaction patterns that make RA play like RA. Each is a combination of input handling, visual feedback, and audio feedback.

Core Interaction Loop

Sidebar System

The sidebar is the player’s primary interface and the most recognizable visual element of Red Alert’s UI. Three reference implementations exist:

IC’s sidebar is YAML-driven (D032 themes), supporting all three styles as switchable presets. The Classic theme recreates the 1996 layout. The Remastered theme matches the modernized layout. The default IC theme takes the best elements of both.

Credit counter animation: The original RA doesn’t jump to the new credit value — it counts up or down smoothly ($5000 → $4200 ticks down digit by digit). This is a small detail that contributes significantly to the game feel. IC replicates this with an interpolated counter in ic-ui.

Build queue clock-wipe: The clock-wipe animation (circular reveal showing build progress on the unit icon) is one of RA’s most distinctive UI elements. ic-render implements this as a shader that masks the icon with a circular wipe driven by build progress percentage.

Verification Method

How we know the recreation is accurate — not “it looks about right” but “we verified against source”:

Community verification: Phase 3 exit criteria include “feels like Red Alert to someone who’s played it before.” This is subjective but critical — IC will release builds to the community for feel testing well before feature-completeness. The community IS the verification instrument for subjective fidelity.

What Each Phase Delivers

First Runnable — Bevy Loading RA Resources

First Runnable — Bevy Loading Red Alert Resources

This section defines the concrete implementation path from “no code” to “a Bevy window rendering a Red Alert map with sprites on it.” It spans Phase 0 (format literacy) through Phase 1 (rendering slice) and produces the project’s first visible output — the milestone that proves the architecture works.

Why This Matters

The first runnable is the “Hello World” of the engine. Until a Bevy window opens and renders actual Red Alert assets, everything is theory. This milestone:

• Validates ic-cnc-content. Can we actually parse .mix, .shp, .pal, .tmp into usable data?
• Validates the Bevy integration. Can we get RA sprites into Bevy’s rendering pipeline?
• Validates the isometric math. Can we convert grid coordinates to screen coordinates correctly?
• Generates community interest. “Red Alert map rendered faithfully in Rust at 4K 144fps” is the first public proof that IC is real.

What We CAN Reference From Existing Projects

We cannot copy code from OpenRA (C#) or the Remastered Collection (proprietary C# layer), but we can study their design decisions:

Implementation Steps

Step 1: cnc-formats + ic-cnc-content — Parse Everything (Weeks 1–2)

Build the cnc-formats crate (MIT/Apache-2.0, standalone) to read all Red Alert binary formats — pure Rust, zero Bevy dependency. Then build ic-cnc-content (GPL, IC monorepo) as a thin wrapper adding EA-derived constants and Bevy asset integration.

Deliverables:

Key implementation detail: MIX archives use a CRC32 hash of the filename (uppercased) as the lookup key — there’s no filename stored in the archive. cnc-formats must include the hash function and a known-filename dictionary (from OpenRA’s global.mix filenames list) to resolve entries by name.

Test strategy: Parse every .mix from a stock Red Alert installation. Extract every .shp and verify frame counts match OpenRA’s sequences/*.yaml. Render every .pal as a 16×16 color grid PNG.

Step 2: Bevy Window + One Sprite (Week 3)

The “Hello RA” moment — a Bevy window opens and displays a single Red Alert sprite with the correct palette applied.

What this proves: cnc-formats → ic-cnc-content output can flow into Bevy’s Image / TextureAtlas pipeline. Palette-indexed sprites render correctly on a GPU.

Implementation:

1. Load conquer.mix → extract e1.shp (rifle infantry) and temperat.pal
2. Convert SHP frames to RGBA pixels by looking up each palette index in the .pal → produce a Bevy Image
3. Build a TextureAtlas from the frame images (Bevy’s sprite sheet system)
4. Spawn a Bevy SpriteSheetBundle entity and animate through the idle frames
5. Display in a Bevy window with a simple orthographic camera

Palette handling: At this stage, palette application happens on the CPU during asset loading (index → RGBA lookup). The GPU palette shader (for runtime player color remapping, palette cycling) comes in Phase 1 proper. CPU conversion is correct and simple — good enough for validation.

Player color remapping: Not needed yet. Just render with the default palette. Player colors (palette indices 80–95) are a Phase 1 concern.

Step 3: Load and Render an OpenRA Map (Weeks 4–5)

Parse .oramap files and render the terrain grid in correct isometric projection.

What this proves: The coordinate system works. Isometric math is correct. Theater palettes load. Terrain tiles tile without visible seams.

Implementation:

1. Parse .oramap (ZIP archive containing map.yaml + map.bin)
2. map.yaml defines: map size, tileset/theater, player definitions, actor placements
3. map.bin is the tile grid: each cell has a tile index + subtile index
4. Load the theater tileset (e.g., temperat.mix for Temperate) and its palette
5. For each cell in the grid, look up the terrain tile image and blit it at the correct isometric screen position

Isometric coordinate transform:

screen_x = (cell_x - cell_y) * tile_half_width
screen_y = (cell_x + cell_y) * tile_half_height

Where tile_half_width = 30 and tile_half_height = 15 for classic RA’s 60×30 diamond tiles (these values come from the original source and OpenRA). This is the CoordTransform defined in Phase 0’s architecture work.

Tile rendering order: Tiles render left-to-right, top-to-bottom in map coordinates. This is the standard isometric painter’s algorithm. In Bevy, this translates to setting Transform.translation.z based on the cell’s Y coordinate (higher Y = lower z = renders behind).

Map bounds and camera: The map defines a playable bounds rectangle within the total tile grid. Set the Bevy camera to center on the map and allow panning with arrow keys / edge scrolling. Zoom with scroll wheel.

Step 4: Sprites on Map + Idle Animations + Camera (Weeks 6–8)

Place unit and building sprites on the terrain grid. Animate idle loops. Implement camera controls.

What this proves: Sprites render at correct positions on the terrain. Z-ordering works (buildings behind units, shadows under vehicles). Animation timing matches the original game.

Implementation:

1. Read actor placements from map.yaml — each actor has a type name, cell position, and owner
2. Look up the actor’s sprite sequence from sequences/*.yaml (or the unit rules) — this gives the .shp filename, frame ranges for each animation, and facing count
3. For each placed actor, create a Bevy entity with:
   • SpriteSheetBundle using the actor’s sprite frames
   • Transform positioned at the isometric screen location of the actor’s cell
   • Z-order based on render layer (see § “Z-Order” above) and Y-position within layer
4. Animate idle sequences: advance frames at the timing specified in the sequence definition
5. Buildings: render the “make” animation’s final frame (fully built state)

Camera system:

At this stage, the minimap is a simple downscaled render of the full map — no player colors, no fog. Game-quality minimap rendering comes in Phase 3.

Z-order validation: Place overlapping buildings and units in a test map. Verify visually against a screenshot from OpenRA rendering the same map. The 13-layer z-order system (§ “Z-Order” above) must be correct at this step.

Step 5: Shroud, Fog-of-War, and Selection (Weeks 9–10)

Add the visual layers that make it feel like an actual game viewport rather than a debug renderer.

Shroud rendering: Unexplored areas are black. Explored-but-not-visible areas show terrain but dimmed (fog). The shroud layer renders on top of everything (z-layer 12). Shroud edges use smooth blending tiles (from the tileset) for clean boundaries. At this stage, shroud state is hardcoded (reveal a circle around the map center) — real fog computation comes in Phase 2 with FogProvider.

Selection box: Left-click-drag draws a selection rectangle. In isometric view, this is traditionally a diamond-shaped selection (rotated 45°) to match the grid orientation, though OpenRA uses a screen-aligned rectangle. IC supports both via QoL toggle (D033). Selected units show a health bar and selection bracket below them.

Cursor system: The cursor changes based on what it’s hovering over — move cursor on ground, select cursor on own units, attack cursor on enemies. This is the CursorContext system. At this stage, implement the visual cursor switching; the actual order dispatch (right-click → move command) is Phase 2 sim work.

Step 6: Sidebar Chrome — First Game-Like Frame (Weeks 11–12)

Assemble the classic RA sidebar layout to complete the visual frame. No functionality yet — build queues don’t work, credits don’t tick, radar doesn’t update. But the layout is in place.

What this proves: Bevy UI can reproduce the RA sidebar layout. Theme YAML (D032) drives the arrangement. The viewport resizes correctly when the sidebar is present.

Sidebar layout (Classic theme):

┌───────────────────────────────────────────┬────────────┐
│                                           │  RADAR     │
│                                           │  MINIMAP   │
│                                           ├────────────┤
│          GAME VIEWPORT                    │  CREDITS   │
│          (isometric map)                  │  $ 10000   │
│                                           ├────────────┤
│                                           │  POWER BAR │
│                                           │  ████░░░░  │
│                                           ├────────────┤
│                                           │  BUILD     │
│                                           │  QUEUE     │
│                                           │  [icons]   │
│                                           │  [icons]   │
│                                           │            │
├───────────────────────────────────────────┴────────────┤
│  STATUS BAR: selected unit info / tooltip              │
└────────────────────────────────────────────────────────┘

Implementation: Use Bevy UI (bevy_ui) for the sidebar layout. The sidebar is a fixed-width panel on the right. The game viewport fills the remaining space. Each sidebar section is a placeholder panel with correct sizing and positioning. The radar minimap shows the downscaled terrain render from Step 4. Build queue icons show static sprite images from the unit/building sequences.

Theme loading: Read a theme.yaml (D032) that defines: sidebar width, section heights, font, color palette, chrome sprite sheet references. At this stage, only the Classic theme exists — but the loading system is in place so future themes just swap the YAML.

Content Detection — Finding RA Assets

Before any of the above steps can run, the engine must locate the player’s Red Alert game files. IC never distributes copyrighted assets — it loads them from games the player already owns.

Detection sources (probed at first launch):

If no content source is found, the first-launch flow guides the player to either install the game from a platform they own it on, or point to existing files. IC does not download game files from the internet (legal boundary).

See 05-FORMATS.md § “Content Source Detection and Installed Asset Locations” for detailed source probing logic and the ContentSource enum.

Timeline Summary

Phase 0 exit: Steps 1–2 complete (parsers + one sprite in Bevy). Phase 1 exit: All six steps complete — any OpenRA RA map loads and renders with sprites, animations, camera, shroud, and sidebar layout at 144fps on mid-range hardware.

After Step 6, the rendering slice is done. The next work is Phase 2: making the units actually do things (move, shoot, die) in a deterministic simulation. See 08-ROADMAP.md § Phase 2.

Crate Dependency Graph

Crate Dependency Graph

External Standalone Crates (D076 Tier 1 — separate repos, MIT OR Apache-2.0)

cnc-formats         (clean-room C&C format parsing: .mix, .shp, .pal, .aud, .tmp, .vqa, .wsa, .fnt, .ini; MiniYAML behind `miniyaml` feature; .meg/.pgm behind `meg` feature (Phase 2); CLI: validate/inspect/convert (Phase 0), extract/list (Phase 1, +.meg Phase 2), check/diff/fingerprint (Phase 2), pack (Phase 6a))
fixed-game-math     (deterministic fixed-point arithmetic: Fixed<N>, trig, CORDIC, Newton sqrt)
deterministic-rng   (seedable platform-identical PRNG: range sampling, weighted selection, shuffle)

These exist from Phase 0, day one, in separate repositories (D076). They have zero IC-specific dependencies.

IC Monorepo Crates (GPL v3 with modding exception)

ic-protocol  (shared types: PlayerOrder, TimestampedOrder)
    ↑         (depends on: fixed-game-math)
    ├── ic-sim      (depends on: ic-protocol, ic-cnc-content, fixed-game-math, deterministic-rng, bevy_ecs [public])
    ├── ic-net      (depends on: ic-protocol; contains RelayCore library — no ic-sim dependency)
    ├── ic-cnc-content  (wraps cnc-formats + EA-derived constants — .mix, .shp, .pal, YAML)
    ├── ic-render   (depends on: ic-sim for reading state)
    ├── ic-ui       (depends on: ic-sim, ic-render; reads SQLite for player analytics — D034)
    ├── ic-audio    (depends on: ic-cnc-content)
    ├── ic-script   (depends on: ic-sim, ic-protocol)
    ├── ic-ai       (depends on: ic-sim, ic-protocol, ic-llm; reads SQLite for adaptive difficulty — D034; contains LlmOrchestratorAi/LlmPlayerAi — D044)
    ├── ic-llm      (standalone — LlmProvider trait, prompt infra, skill library; embeds candle-core/candle-transformers/tokenizers for Tier 1 CPU inference — D047; no ic-sim, no ic-ai imports)
    ├── ic-paths    (standalone — platform path resolution, portable mode, credential store; wraps `app-path` + `strict-path` + `keyring` + `aes-gcm` + `argon2` + `zeroize` crates)
    ├── ic-editor   (depends on: ic-render, ic-sim, ic-ui, ic-protocol, ic-cnc-content, ic-paths; SDK binary — D038+D040)
    └── ic-game     (depends on: everything above EXCEPT ic-editor)

ic-server (top-level binary; depends on: ic-net for RelayCore, ic-protocol, ic-paths;
           optionally ic-sim for FogAuth/relay-headless deployments — D074)

Critical boundary: ic-sim never imports from ic-net. The ic-net library crate (RelayCore, NetworkModel trait) never imports from ic-sim. They only share ic-protocol. ic-server is a top-level binary (like ic-game) that may depend on both ic-net and ic-sim — this does not violate the library-level boundary. ic-game never imports from ic-editor — the game and SDK are separate binaries that share library crates.

Bevy ECS dependency: ic-sim depends on bevy_ecs as a public dependency — Simulation wraps a Bevy World, and the GameModule trait exposes &mut World in register_components() and returns Box<dyn System> from system_pipeline(). Callers (ic-game, ic-editor, ic-render) already depend on Bevy directly, so the leaked types create no additional coupling. ic-net and ic-protocol have zero Bevy dependency.

Storage boundary: ic-sim never reads or writes SQLite (invariant #1). Three crates are read-only consumers of the client-side SQLite database: ic-ui (post-game stats, career page, campaign dashboard), ic-ai (difficulty scaling, counter-strategy selection, personalized missions via ic-llm providers, coaching), ic-llm (model pack state, provider config, skill library). Gameplay events are written by a Bevy observer system in ic-game, outside the deterministic sim. See D034 in decisions/09e-community.md.

Binary Architecture: GUI-First Design

The crate graph produces four ship binaries. Each targets a distinct audience with an interface appropriate to that audience’s workflow:

GUI-first principle: The game client (iron-curtain) is a GUI application — not a CLI tool with a GUI bolted on. Players interact through menus, buttons, and mouse clicks. CLI flags on the game binary (--windowed, --mod mymod, --portable) are launch parameters (the same kind every game accepts), not a “CLI mode.” The game never requires a terminal to play.

The ic CLI is a developer tool. It serves the same role as cargo, npm, or dotnet — a command-line interface for automation, scripting, and CI/CD pipelines. It is aimed at modders, server operators, and contributors. Player-facing documentation never directs users to a terminal. The ic CLI is not installed to the system PATH by default — players who install via Steam, GOG, or a platform package manager get the game client and (optionally) the server binary, not the developer CLI.

In-game command console ≠ CLI tool. D058’s unified chat/command system (/help, /speed 2x) is an in-game overlay — part of the GUI, not a separate terminal. It uses the same CommandDispatcher as the CLI for consistency, but the user experience is a text field inside the game window, not a shell prompt. Players who never type / commands lose nothing — every command has a GUI equivalent (D058 CI-1).

Where CLI is the right answer:

• Server operators: ic-server --map Fjord --players 8 on a headless Linux box. No monitor attached. systemd unit files, Docker Compose, Ansible playbooks — CLI is the native interface for infrastructure.
• CI/CD pipelines: ic mod lint && ic mod test && ic mod package in a GitHub Actions workflow. Automation needs non-interactive, scriptable commands.
• Batch modding operations: ic mod migrate --from openra to convert an entire mod directory. Power users who prefer the terminal can use it — the GUI mod manager (SDK) provides the same functionality visually.
• Diagnostics and debugging: ic replay validate *.icrep to batch-check replay integrity. Developer workflow, not player workflow.

Where GUI is the only answer:

• Playing the game (menus, lobbies, matches, replays, settings)
• First-launch wizard and content detection
• Browsing and installing Workshop content
• Configuring LLM providers (D047)
• Campaign setup and mission generation
• Replay viewer with transport controls, camera modes, overlays
• Achievement browsing, career stats, player profile

Async Architecture: Dual-Runtime with Channel Bridge

IC uses two async runtimes that never overlap within a single thread. The split is driven by Bevy’s architecture and WASM portability.

Why Two Runtimes

Bevy does not use tokio. Bevy’s bevy_tasks crate is built on async-executor / futures-lite (the smol family) — a lightweight, custom thread-pool executor with three pools:

But key IC dependencies — librqbit (BitTorrent P2P), reqwest (HTTP), tokio-tungstenite (WebSocket), quinn (QUIC) — require tokio. Calling tokio::Runtime::block_on() from inside Bevy’s executor panics. The solution is a dedicated tokio runtime on a background OS thread, communicating via channels.

Per-Binary Runtime Strategy

The Channel Bridge (Bevy Binaries)

For ic-game and ic-editor, a single background OS thread hosts a tokio runtime. All tokio-dependent I/O runs there. The Bevy ECS communicates via typed channels:

┌──────────────────────────┐   crossbeam-channel   ┌──────────────────────────┐
│  Bevy Game Loop (main)    │ ◄──────────────────► │  Tokio Thread (background)│
│                           │  IoCommand / IoResult │                           │
│  ic-sim (pure, no I/O)    │                       │  reqwest — HTTP/LLM calls │
│  ic-ui (render, ECS)      │                       │  librqbit — P2P downloads │
│  ic-audio (playback)      │                       │  tokio-tungstenite — WS   │
│  bevy_tasks (compute,     │                       │  quinn — QUIC             │
│    async compute, I/O)    │                       │  str0m I/O driver — VoIP  │
└──────────────────────────┘                        └──────────────────────────┘

How it works:

1. A Bevy system needs to make an LLM call or start a download → sends an IoCommand through cmd_tx.
2. The tokio thread receives it, spawns a tokio task (tokio::spawn), and performs the async I/O.
3. When complete, the result is sent back through result_tx.
4. A Bevy system polls result_rx.try_recv() each frame and injects results into the ECS world as events or resource mutations.
5. The sim never touches any of this — it remains pure.

Channel choice: crossbeam-channel for the sync↔async boundary (already used by IC’s replay writer and voice pipeline — see netcode/network-model-trait.md § BackgroundReplayWriter and D059 § Voice Pipeline). Within the tokio runtime, tokio::sync::mpsc for intra-task communication.

#![allow(unused)]
fn main() {
/// Commands sent from Bevy systems to the tokio I/O thread.
pub enum IoCommand {
    HttpRequest { id: RequestId, url: String, method: HttpMethod, body: Option<Vec<u8>> },
    LlmPrompt { id: RequestId, task: LlmTask },
    StartDownload { package_id: PackageId },
    CancelDownload { package_id: PackageId },
    WorkshopPublish { package: PackageManifest },
    ReplayDownload { match_id: MatchId },
}

/// Results returned from the tokio I/O thread to Bevy systems.
pub enum IoResult {
    HttpResponse { id: RequestId, status: u16, body: Vec<u8> },
    LlmResponse { id: RequestId, result: Result<String, LlmError> },
    DownloadProgress { package_id: PackageId, bytes: u64, total: Option<u64> },
    DownloadComplete { package_id: PackageId, path: PathBuf },
    DownloadFailed { package_id: PackageId, error: String },
    PublishResult { result: Result<PackageVersion, WorkshopError> },
}
}

Relay Server: Pure Tokio

ic-server has no Bevy, no ECS, no game loop. It is a standard async Rust server:

• #[tokio::main] with multi-threaded work-stealing scheduler
• One tokio task per game session drives RelayCore + socket I/O
• axum or raw hyper for lobby/tracking HTTP endpoints
• tokio::net::UdpSocket feeding str0m (sans-I/O WebRTC) for game relay and voice forwarding
• Hundreds of concurrent sessions is well within tokio’s comfort zone

This is already established in 03-NETCODE.md § Backend Language: “ic-server binary — standalone headless process that hosts multiple concurrent games. Not Bevy, no ECS. Uses RelayCore + async I/O (tokio).”

Embedded Relay: Bevy’s I/O Pool

When a player clicks “Host Game,” EmbeddedRelayNetwork wraps RelayCore inside the game process. The relay’s socket I/O runs on Bevy’s IoTaskPool — not the tokio thread. This is the pattern established in 03-NETCODE.md: the embedded relay uses Bevy’s async task system, not a separate tokio runtime.

The embedded relay does not need tokio because RelayCore is a library with no runtime dependency — it processes orders and manages sessions. The socket I/O layer is thin and fits naturally into Bevy’s I/O pool. Only external service calls (Workshop API, LLM, BitTorrent) route through the tokio thread.

str0m: Sans-I/O Advantage

str0m (WebRTC/VoIP — D059) has no internal threads, no async runtime, no I/O. All I/O is externalized — you own the sockets and feed str0m packets. This eliminates async runtime conflicts entirely:

• Relay server: A tokio task owns the UDP socket and drives str0m. Natural fit.
• Game client (native): A tokio task on the I/O thread owns the UDP socket. Voice packets are bridged to ic-audio via crossbeam-channel (already the design in D059 § Voice Pipeline).
• Game client (WASM): The browser’s WebRTC API handles transport. str0m is not used — the browser provides equivalent functionality natively.

WASM: Platform-Specific I/O Bridge

Tokio does not work in browser WASM. There is no std::thread in the browser, and tokio’s scheduler depends on it. Bevy on WASM is single-threaded — all three task pools collapse to a single-threaded executor backed by wasm-bindgen-futures::spawn_local.

The I/O bridge abstracts this behind a platform trait:

#![allow(unused)]
fn main() {
/// Platform-agnostic I/O bridge. Bevy systems interact with this
/// trait as a resource — they don't know what runtime backs it.
pub trait IoBridge: Send + Sync {
    fn send_command(&self, cmd: IoCommand);
    fn poll_results(&self) -> Vec<IoResult>;
}

/// Native: backed by crossbeam channels + dedicated tokio thread.
#[cfg(not(target_arch = "wasm32"))]
pub struct NativeIoBridge { /* cmd_tx, result_rx */ }

/// WASM: backed by wasm-bindgen-futures + browser Fetch API.
#[cfg(target_arch = "wasm32")]
pub struct WasmIoBridge { /* internal state */ }
}

Platform-specific behavior:

librqbit is native-only — WASM browser builds fall back to HTTP downloads served by Workshop CDN or relay mirrors. This constraint should be accepted early and the Workshop download system designed with HTTP fallback from the start (D049).

What Is Never Async

• ic-sim — Pure, deterministic, no I/O. Zero async. Invariant #1.
• ECS system logic — Bevy systems run synchronously on the main thread (or parallel via Bevy’s scheduler). They poll channels, they don’t await.
• Order validation — Deterministic, runs inside the sim. No network, no async.
• Audio playback — ic-audio receives events synchronously from ECS and plays sounds. The audio backend (Kira) manages its own threads internally.

Design Principles

1. One tokio runtime per process, on a dedicated thread (for Bevy binaries). Never nest runtimes or call block_on from within Bevy’s executor.
2. Channels are the universal bridge. crossbeam-channel for sync↔async boundaries. tokio::sync::mpsc within tokio tasks. Already the established pattern for replay writing and voice pipeline.
3. Platform divergence lives behind IoBridge. Bevy systems send commands and poll results through the trait. They never import tokio or wasm-bindgen-futures directly.
4. Sans-I/O libraries are preferred where available (str0m for WebRTC). They eliminate async runtime coupling and work on every platform.
5. The sim is the sync anchor. Everything radiates outward from the deterministic sim: the Bevy scheduler drives systems synchronously, systems communicate with async I/O through channels, and results flow back as ECS events. The sim never waits for I/O.

Crate Design Notes

Most crates are self-explanatory from the dependency graph, but three that appear in the graph without dedicated design doc sections are detailed here.

ic-audio — Sound, Music, and EVA

ic-audio is a Bevy audio plugin that handles all game sound: effects, EVA voice lines, music playback, and ambient audio.

Responsibilities:

• Sound effects: Weapon fire, explosions, unit acknowledgments, UI clicks. Triggered by sim events (combat, production, movement) via Bevy observer systems.
• EVA voice system: Plays notification audio triggered by notification_system() events. Manages a priority queue — high-priority notifications (nuke launch, base under attack) interrupt low-priority ones. Respects per-notification cooldowns.
• Music playback: Three modes — jukebox (classic sequential/shuffle), sequential (ordered playlist), and dynamic (mood-tagged tracks with game-state-driven transitions and crossfade). Supports .aud (original RA format via ic-cnc-content) and modern formats (OGG, WAV via Bevy). Theme-specific intro tracks (D032 — Hell March for Classic theme). Dynamic mode monitors combat, base threat, and objective state to select appropriate mood category. See § “Red Alert Experience Recreation Strategy” for full music system design and D038 in decisions/09f-tools.md for scenario editor integration.
• Spatial audio: 3D positional audio for effects — explosions louder when camera is near. Uses Bevy’s spatial audio with listener at GameCamera.position (see § “Camera System”).
• VoIP playback: Decodes incoming Opus voice frames from MessageLane::Voice and mixes them into the audio output. Handles per-player volume, muting, and optional spatial panning (D059 § Spatial Audio). Voice replay playback syncs Opus frames to game ticks.
• Ambient soundscapes: Per-biome ambient loops (waves for coastal maps, wind for snow maps). Weather system (D022) can modify ambient tracks.

Key types:

#![allow(unused)]
fn main() {
pub struct AudioEvent {
    pub sound: SoundId,
    pub position: Option<WorldPos>,  // None = non-positional (UI, EVA, music)
    pub volume: f32,
    pub priority: AudioPriority,
}

pub enum AudioPriority { Ambient, Effect, Voice, EVA, Music }

pub struct Jukebox {
    pub playlist: Vec<TrackId>,
    pub current: usize,
    pub shuffle: bool,
    pub repeat: bool,
    pub crossfade_ms: u32,
}
}

Format support: .aud (IMA ADPCM, via ic-cnc-content decoder), .ogg, .wav, .mp3 (via Kira/bevy_kira_audio). Audio backend is Kira (chosen over rodio/Oddio for sub-frame scheduling, clock-synced crossfade, and per-track DSP). No platform-specific code in ic-audio.

Complete audio design: Library evaluation, bus architecture, dynamic music FSM, EVA priority system, sound pooling, WASM constraints, and performance budget are specified in research/audio-library-music-integration-design.md.

Phase: Core audio (effects, EVA, music) in Phase 3. Spatial audio and ambient soundscapes in Phase 3-4.

Sim → Audio Event Bridge

The sim is pure (invariant #1) and emits no I/O. Audio events are therefore produced by Bevy observer systems in ic-game that detect sim state changes and emit typed Bevy events consumed by ic-audio. This section defines the formal event taxonomy that bridges the two.

Event taxonomy:

Rust type definitions:

#![allow(unused)]
fn main() {
/// Combat sounds — one event per projectile hit, not per salvo.
/// Spatial: always positional.
#[derive(Event, Clone)]
pub struct CombatAudioEvent {
    pub kind: CombatSoundKind,
    pub sound_id: SoundId,
    pub position: WorldPos,
    pub intensity: f32,         // 0.0-1.0, scales volume (explosion size, weapon caliber)
}

#[derive(Clone, Copy)]
pub enum CombatSoundKind {
    WeaponFire,
    ProjectileImpact,
    Explosion,
    UnitDeath,
}

/// Production sounds — non-positional (played as UI feedback).
#[derive(Event, Clone)]
pub struct ProductionAudioEvent {
    pub kind: ProductionSoundKind,
    pub actor_id: ActorId,      // what was built — used for sound lookup in YAML
    pub player: PlayerId,
}

#[derive(Clone, Copy)]
pub enum ProductionSoundKind {
    BuildStarted,
    BuildComplete,
    UnitReady,
}

/// Movement and acknowledgment sounds.
/// Spatial for move-start engine sounds; non-positional for voice acknowledgments.
#[derive(Event, Clone)]
pub struct MovementAudioEvent {
    pub kind: MovementSoundKind,
    pub unit_type: ActorId,
    pub position: WorldPos,
    pub player: PlayerId,
}

#[derive(Clone, Copy)]
pub enum MovementSoundKind {
    Acknowledge,    // "Yes sir", "Affirmative" — voice response to player command
    MoveStart,      // Engine/footstep sound when unit begins moving
}

/// EVA voice line trigger. Routed to the EvaSystem priority queue.
/// See research/audio-library-music-integration-design.md § EVA Priority Queue
/// for queue depth, cooldown, and interruption rules.
#[derive(Event, Clone)]
pub struct EvaNotification {
    pub sound_id: SoundId,
    pub priority: EvaPriority,
    pub notification_type: NotificationType,  // cooldown key — reuses sim's enum
}

/// Dynamic music mood transition request.
/// Emitted when combat score thresholds are crossed or mission ends.
/// See research/audio-library-music-integration-design.md § Dynamic Music FSM
/// for threshold values and transition rules.
#[derive(Event, Clone)]
pub struct MusicStateChange {
    pub target_mood: MusicMood,   // Ambient, Buildup, Combat, Victory, Defeat
    pub crossfade_ms: u32,        // override default crossfade duration (0 = use default)
}

/// Ambient soundscape changes — biome or weather transitions.
#[derive(Event, Clone)]
pub struct AmbientAudioEvent {
    pub kind: AmbientSoundKind,
    pub sound_id: SoundId,
    pub crossfade_ms: u32,        // smooth transition between ambient loops
}

#[derive(Clone, Copy)]
pub enum AmbientSoundKind {
    BiomeChange,     // map load or camera moved to different biome region
    WeatherChange,   // rain start/stop, storm intensity change (D022)
}

/// UI interaction sounds — non-positional, immediate playback.
#[derive(Event, Clone)]
pub struct UiAudioEvent {
    pub sound_id: SoundId,
}
}

Event flow:

┌─────────────────────────────────────────────────────────────────┐
│ ic-sim (deterministic)                                          │
│   Weapon fires → UnitState changes → Production completes → …  │
│   (pure state transitions, no events emitted)                   │
└──────────────────────────┬──────────────────────────────────────┘
                           │ state diffs visible via ECS queries
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│ ic-game  (Bevy observer systems, non-deterministic)             │
│                                                                 │
│   on_weapon_fire()      → emit CombatAudioEvent                 │
│   on_unit_death()       → emit CombatAudioEvent + EvaNotification│
│   on_production_done()  → emit ProductionAudioEvent + EvaNotification│
│   on_move_order()       → emit MovementAudioEvent               │
│   on_notification()     → emit EvaNotification                  │
│   on_mission_end()      → emit MusicStateChange                 │
│   on_weather_change()   → emit AmbientAudioEvent                │
│   on_ui_interaction()   → emit UiAudioEvent                     │
└──────────────────────────┬──────────────────────────────────────┘
                           │ Bevy events
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│ ic-audio  (Bevy observer systems)                               │
│                                                                 │
│   on_combat_event()     → SfxBus (WeaponSub / ExplosionSub)    │
│   on_production_event() → SfxBus (UiSub)                        │
│   on_movement_event()   → VoiceBus (UnitSub)                    │
│   on_eva_notification() → EvaSystem priority queue → VoiceBus   │
│   on_music_change()     → DynamicMusicState FSM → MusicBus      │
│   on_ambient_event()    → AmbientBus (BiomeSub / WeatherSub)    │
│   on_ui_audio()         → SfxBus (UiSub)                        │
└─────────────────────────────────────────────────────────────────┘

Granularity rules:

• Combat: One CombatAudioEvent per projectile hit, not per salvo. This preserves spatial accuracy — each impact plays at its own WorldPos. The sound pool and instance limits in ic-audio handle the case where 50 shells land in one frame (see research/audio-library-music-integration-design.md § Sound Pooling and Instance Limits).
• Acknowledgments: One MovementAudioEvent::Acknowledge per unit per command, with deduplication — if the same unit_type emits an acknowledgment within 100ms, only the first plays. This matches RA1 behavior (select 10 tanks, right-click = one “Acknowledged”, not ten).
• EVA: EvaNotification feeds into the existing priority queue (EvaSystem). Mapping from sim NotificationType to EvaPriority is YAML-driven (see gameplay-systems.md § Notification System). The queue handles cooldowns, max depth, and interruption logic — this bridge layer only emits the event; ic-audio owns all queuing and playback policy.
• Music: MusicStateChange is emitted sparingly — only when the update_combat_score() system in ic-audio crosses a threshold (combat score > 0.3 → Combat mood) or when a mission ends. The DynamicMusicState FSM in ic-audio owns all transition logic, linger timers, and crossfade scheduling.
• Production and UI: Non-positional, immediate playback. No deduplication needed — these events are infrequent by nature.

Key constraint: These event types live in ic-audio (or a shared types module) and are emitted by observer systems in ic-game. They are not emitted by ic-sim — the sim produces pure state changes, and the observer layer in ic-game translates those into audio events. This preserves invariant #1 (simulation is pure, no I/O).

Cross-references: Bus architecture and mixer topology: research/audio-library-music-integration-design.md § 2. EVA priority queue and interruption rules: same document § 4. Dynamic music FSM and combat score thresholds: same document § 3. Notification types and YAML mapping: src/architecture/gameplay-systems.md § Notification System.

ic-ai — Skirmish AI and Adaptive Difficulty

ic-ai provides computer opponents for skirmish and campaign, plus adaptive difficulty scaling.

Architecture: AI players run as Bevy systems that read visible game state and emit PlayerOrders through ic-protocol. The sim processes AI orders identically to human orders — no special privileges. AI has no maphack by default (reads only fog-of-war-revealed state), though campaign scripts can grant omniscience for specific AI players via conditions.

Internal structure — priority-based manager hierarchy: The default PersonalityDrivenAi (D043) uses the dominant pattern found across all surveyed open-source RTS AI implementations (see research/rts-ai-implementation-survey.md):

PersonalityDrivenAi
├── EconomyManager       — harvester assignment, power monitoring, expansion timing
├── ProductionManager    — share-based unit composition, priority-queue build orders, influence-map building placement
├── MilitaryManager      — attack planning, event-driven defense, squad management
└── AiState (shared)     — threat map, resource map, scouting memory

Key techniques: priority-based resource allocation (from 0 A.D. Petra), share-based unit composition (from OpenRA), influence maps for building placement (from 0 A.D.), tick-gated evaluation (from Generals/Petra), fuzzy engagement logic (from OpenRA), Lanchester-inspired threat scoring (from MicroRTS research). Each manager runs on its own tick schedule — cheap decisions (defense) every tick, expensive decisions (strategic reassessment) every 60 ticks. Total amortized AI budget: <0.5ms per tick for 500 units. All AI working memory is pre-allocated in AiScratch (zero per-tick allocation). Full implementation detail in D043 (decisions/09d-gameplay.md).

AI tiers (YAML-configured):

Key types:

#![allow(unused)]
fn main() {
/// AI personality — loaded from YAML, defines behavior parameters.
pub struct AiPersonality {
    pub name: String,
    pub build_order_priority: Vec<ActorId>,  // what to build first
    pub attack_threshold: i32,               // army value before attacking
    pub aggression: i32,                     // 0-100 scale
    pub expansion_tendency: i32,             // how eagerly AI expands
    pub micro_level: MicroLevel,             // None, Basic, Advanced
    pub tech_preference: TechPreference,     // Rush, Balanced, Tech
}

pub enum MicroLevel { None, Basic, Advanced }
pub enum TechPreference { Rush, Balanced, Tech }
}

Adaptive difficulty (D034 integration): ic-ai reads the client-side SQLite database (match history, player performance metrics) to calibrate AI difficulty. If the player has lost 5 consecutive games against “Normal” AI, the AI subtly reduces its efficiency. If the player is winning easily, the AI tightens its build order. This is per-player, invisible, and optional (can be disabled in settings).

Shellmap AI: A stripped-down AI profile specifically for menu background battles (D032 shellmaps). Prioritizes visually dramatic behavior over efficiency — large army clashes, diverse unit compositions, no early rushes. Runs with reduced tick budget since it shares CPU with the menu UI.

# ai/shellmap.yaml
shellmap_ai:
  personality:
    name: "Shellmap Director"
    aggression: 40
    attack_threshold: 5000     # build up large armies before engaging
    micro_level: basic
    tech_preference: balanced
    build_order_priority: [power_plant, barracks, war_factory, ore_refinery]
    dramatic_mode: true        # prefer diverse unit mixes, avoid cheese strategies
    max_tick_budget_us: 2000   # 2ms max per AI tick (shellmap is background)

Lua/WASM AI mods: Community can implement custom AI via Lua (Tier 2) or WASM (Tier 3). Custom AI implements the AiStrategy trait (D041) and is selectable in the lobby. The engine provides ic-ai’s built-in PersonalityDrivenAi as the default; mods can replace or extend it.

AiStrategy Trait (D041):

AiPersonality tunes parameters within a fixed decision algorithm. For modders who want to replace the algorithm entirely (neural net, GOAP planner, MCTS, scripted state machine), the AiStrategy trait abstracts the decision-making:

#![allow(unused)]
fn main() {
/// Game modules and mods implement this for AI opponents.
/// Default: PersonalityDrivenAi (behavior trees driven by AiPersonality YAML).
pub trait AiStrategy: Send + Sync {
    /// Called once per AI player per tick. Reads fog-filtered state, emits orders.
    fn decide(
        &mut self,
        player: PlayerId,
        view: &FogFilteredView,
        tick: u64,
    ) -> Vec<PlayerOrder>;

    /// Human-readable name for lobby display.
    fn name(&self) -> &str;

    /// Difficulty tier for UI categorization.
    fn difficulty(&self) -> AiDifficulty;

    /// Per-tick compute budget hint (microseconds). None = no limit.
    fn tick_budget_hint(&self) -> Option<u64>;
}
}

FogFilteredView ensures AI honesty — the AI sees only what its units see, just like a human player. Campaign scripts can grant omniscience via conditions. AI strategies are selectable in the lobby: “IC Default (Normal)”, “Workshop: Neural Net v2.1”, etc. See D041 in decisions/09d-gameplay.md for full rationale.

Phase: Basic skirmish AI (Easy/Normal) in Phase 4. Hard/Brutal + adaptive difficulty in Phase 5-6a.

ic-script — Lua and WASM Mod Runtimes

ic-script hosts the Lua and WASM mod execution environments. It bridges the stable mod API surface to engine internals via a compatibility adapter layer.

Architecture:

  Mod code (Lua / WASM)
        │
        ▼
  ┌─────────────────────────┐
  │  Mod API Surface        │  ← versioned, stable (D024 globals, WASM host fns)
  ├─────────────────────────┤
  │  ic-script              │  ← this crate: runtime management, sandboxing, adaptation
  ├─────────────────────────┤
  │  ic-sim + ic-protocol   │  ← engine internals (can change between versions)
  └─────────────────────────┘

Responsibilities:

• Lua runtime management: Initializes mlua with deterministic seed, registers all API globals (D024), enforces LuaExecutionLimits, manages per-mod Lua states.
• WASM runtime management: Initializes wasmtime with fuel metering, registers WASM host functions, enforces WasmExecutionLimits, manages per-mod WASM instances.
• Mod lifecycle: Load → initialize → per-tick callbacks → unload. Mods are loaded at game start (not hot-reloaded mid-game in multiplayer — determinism).
• Compatibility adapter: Translates stable mod API calls to current engine internals. When engine internals change, this adapter is updated — mods don’t notice. See 04-MODDING.md § “Compatibility Adapter Layer”.
• Sandbox enforcement: No filesystem, no network, no raw memory access. All mod I/O goes through the host API. Capability-based security per mod.
• Campaign state: Manages Campaign.* and Var.* state for branching campaigns (D021). Campaign variables are stored in save games.

Key types:

#![allow(unused)]
fn main() {
pub struct ScriptRuntime {
    pub lua_states: HashMap<ModId, LuaState>,
    pub wasm_instances: HashMap<ModId, WasmInstance>,
    pub api_version: ModApiVersion,
}

pub struct LuaState {
    pub vm: mlua::Lua,
    pub limits: LuaExecutionLimits,
    pub mod_id: ModId,
}

pub struct WasmInstance {
    pub instance: wasmtime::Instance,
    pub limits: WasmExecutionLimits,
    pub capabilities: ModCapabilities,
    pub mod_id: ModId,
}
}

Determinism guarantee: Both Lua and WASM execute at a fixed point in the system pipeline (trigger_system() step). All clients run the same mod code with the same game state at the same tick. Lua’s string hash seed is fixed. math.random() is redirected to the sim’s deterministic PRNG (not removed — OpenRA compat requires it).

WASM determinism nuance: WASM execution is deterministic for integer and fixed-point operations, but the WASM spec permits non-determinism in floating-point NaN bit patterns. If a WASM mod uses f32/f64 internally (which is legal — the sim’s fixed-point invariant applies to ic-sim Rust code, not to mod-internal computation), different CPU architectures may produce different NaN payloads, causing deterministic divergence (desync). Mitigations:

• Runtime mandate: IC uses wasmtime exclusively. All clients use the same wasmtime version (engine-pinned). wasmtime canonicalizes NaN outputs for WASM arithmetic operations, which eliminates NaN bit-pattern divergence across platforms.
• Defensive recommendation for mod authors: Mod development docs recommend using integer/fixed-point arithmetic for any computation whose results feed back into PlayerOrders or are returned to host functions. Floats are safe for mod-internal scratch computation that is consumed and discarded within the same call (e.g., heuristic scoring, weight calculations that produce an integer output).
• Hash verification: All clients verify the WASM binary hash (SHA-256) before game start. Combined with wasmtime’s NaN canonicalization and identical inputs, this provides a strong determinism guarantee — but it is not formally proven the way ic-sim’s integer-only invariant is. WASM mod desync is tracked as a distinct diagnosis path in the desync debugger.

Browser builds: Tier 3 WASM mods are desktop/server-only. The browser build (WASM target) cannot embed wasmtime — see 04-MODDING.md § “Browser Build Limitation (WASM-on-WASM)” for the full analysis and the documented mitigation path (wasmi interpreter fallback), which is an optional browser-platform expansion item unless promoted by platform milestone requirements.

Phase: Lua runtime in Phase 4. WASM runtime in Phase 4-5. Mod API versioning in Phase 6a.

ic-paths — Platform Path Resolution and Portable Mode

ic-paths is the single crate responsible for resolving all filesystem paths the engine uses at runtime: the player data directory (D061), log directory, mod search paths, and install-relative asset paths. Every other crate that needs a filesystem location imports from ic-paths — no crate resolves platform paths on its own.

ic-paths also owns the CredentialStore — the three-tier credential protection system that encrypts sensitive SQLite columns (OAuth tokens, API keys) with AES-256-GCM. The DEK (Data Encryption Key) is protected by OS keyring (Tier 1, via keyring crate), user vault passphrase with Argon2id KDF (Tier 2), or held session-only in memory (Tier 3, WASM). All crates that handle secrets (ic-llm, ic-net, ic-game) import CredentialStore from ic-paths. See research/credential-protection-design.md for the full design and V61 in 06-SECURITY.md for the threat model.

Two modes:

Mode is selected by (highest priority first):

1. IC_PORTABLE=1 environment variable
2. --portable CLI flag
3. Presence of a portable.marker file next to the executable
4. Otherwise: platform mode

Portable mode uses the app-path crate (zero-dependency, cross-platform exe-relative path resolution with static caching) to resolve all paths relative to the executable. In portable mode the data directory becomes <exe_dir>/data/ instead of the platform-specific location, and the entire installation is self-contained — copy the folder to move it.

Key types:

#![allow(unused)]
fn main() {
/// Resolved set of root paths for the current session.
/// Computed once at startup, immutable thereafter.
pub struct AppDirs {
    pub data_dir: PathBuf,      // Player data (D061): config, saves, replays, keys, ...
    pub install_dir: PathBuf,   // Shipped content: mods/common/, mods/ra/, binaries
    pub log_dir: PathBuf,       // Log files (rotated)
    pub cache_dir: PathBuf,     // Temporary/derived data (shader cache, download staging)
    pub mode: PathMode,         // Platform or Portable — for diagnostics / UI display
}

pub enum PathMode { Platform, Portable }
}

Path boundary integration: AppDirs resolves where directories live; strict-path PathBoundary enforces that untrusted paths stay within them. Callers that handle untrusted input (archive extraction, mod file references, save loading) must create a PathBoundary from the relevant AppDirs field before performing I/O. Convenience methods provide pre-built boundaries for common cases:

#![allow(unused)]
fn main() {
impl AppDirs {
    /// PathBoundary for save directory — save game loading is sandboxed here.
    pub fn save_boundary(&self) -> Result<PathBoundary, strict_path::Error> {
        PathBoundary::new(self.data_dir.join("saves"))
    }
    /// PathBoundary for mod directory — mod file references are sandboxed here.
    pub fn mod_boundary(&self, mod_id: &ModId) -> Result<PathBoundary, strict_path::Error> {
        PathBoundary::new(self.data_dir.join("mods").join(mod_id.as_ref()))
    }
    /// PathBoundary for replay cache — embedded resource extraction is sandboxed here.
    pub fn replay_cache_boundary(&self) -> Result<PathBoundary, strict_path::Error> {
        PathBoundary::new(self.cache_dir.join("replay-resources"))
    }
}
}

See 06-SECURITY.md § Path Security Infrastructure for the full integration table.

Additional override: --data-dir <path> CLI flag overrides the data directory location regardless of mode. This is useful for developers running multiple profiles or testing with different data sets. If --data-dir is set, PathMode is still reported as Platform or Portable based on the detection above — the override only changes data_dir, not the mode label.

Visibility: The current path mode is shown in:

• Settings → Data tab: "Data location: C:\Games\IC\data\ (portable mode)" or "Data location: %APPDATA%\IronCurtain\ (standard)"
• Console: ic_paths command prints all resolved paths and the active mode
• First-launch wizard: if portable mode is detected, a brief note: "Running in portable mode — all data is stored next to the game executable."
• Main menu footer (optional, subtle): a small [P] badge or "Portable" label if the player wants to see it (toggleable via Settings → Video → Show Mode Indicator)

Creating a portable installation: To convert a standard install into a portable one, a user just:

1. Copies the game folder to a USB drive (or any location)
2. Creates an empty portable.marker file next to the executable
3. Launches the game — done

No explicit init step needed. On first launch in portable mode, the engine auto-creates the data/ directory and runs the first-launch wizard normally. If the user already has a platform install on the same machine, the wizard detects it and offers: "Found existing IC data on this machine. [Import my settings & identity] [Start fresh]". This replaces any need for a separate init command — the wizard handles everything, and the user doesn’t need to learn a CLI command to set up portable mode.

WASM: Browser builds return OPFS-backed virtual paths. Portable mode is not applicable — PathMode::Platform is always used. Mobile builds use the platform app sandbox unconditionally.

Phase: Phase 1 (required before any file I/O — asset loading, config, logs).

Install & Source Layout

Install & Source Layout (Community-Friendly Project Structure)

The directory structure — both the shipped product and the source repository — is designed to feel immediately navigable to anyone who has worked with OpenRA. OpenRA’s modding community thrived because the project was approachable: open a mod folder, find YAML rules organized by category, edit values, see results. IC preserves that muscle memory while fitting the structure to a Rust/Bevy codebase.

Design Principles

1. Game modules are mods. Built-in game modules (mods/ra/, mods/td/) use the exact same directory layout, mod.toml manifest, and YAML rule schema as community-created mods. No internal-only APIs, no special paths. If a modder can edit mods/ra/rules/units/vehicles.yaml, anyone can see how the game’s own data is structured. Directly inspired by Factorio’s “game is a mod” principle (validated in D018).

2. Same vocabulary, same directories. OpenRA uses rules/, sequences/, chrome/, maps/, audio/, scripts/. IC uses the same directory names for the same purposes. An OpenRA modder opening IC’s mods/ra/ directory knows where everything is.

3. Separate binaries for separate roles, GUI-first for players. Game client and SDK editor are GUI applications — players and modders interact through windowed interfaces, never through a terminal. The dedicated server is a CLI daemon for headless operation. The ic utility is a developer CLI for automation and CI/CD. Like OpenRA ships OpenRA.exe, OpenRA.Server.exe, and OpenRA.Utility.exe — each role gets the interface natural to its audience. See crate-graph.md § “Binary Architecture: GUI-First Design” for the full breakdown.

4. Flat and scannable. No deep nesting for its own sake. A modder looking at mods/ra/ should see the high-level structure in a single ls. Subdirectories within rules/ organize by category (units, structures, weapons) — the same pattern OpenRA uses.

5. Data next to data, code next to code. Game content (YAML, Lua, assets) lives in mods/. Engine code (Rust) lives in crate directories. They don’t intermingle. A gameplay modder never touches Rust. A engine contributor goes straight to the crate they need.

Install Directory (Shipped Product)

What an end user sees after installing Iron Curtain:

iron-curtain/
├── iron-curtain[.exe]              # Game client — GUI application (ic-game binary)
├── ic-server[.exe]                 # Relay / dedicated server — CLI daemon (ic-server binary)
├── ic[.exe]                        # Developer/modder utility — CLI tool (mod, CI/CD, diagnostics)
├── ic-editor[.exe]                 # SDK — GUI application: scenario editor, asset studio (D038+D040)
├── mods/                           # Game modules + content — the heart of the project
│   ├── common/                     # Shared resources used by all C&C-family modules
│   │   ├── mod.toml                #   manifest (declares shared chrome, cursors, etc.)
│   │   ├── chrome/                 #   shared UI layout definitions
│   │   ├── cursors/                #   shared cursor definitions
│   │   └── translations/           #   shared localization strings
│   ├── ra/                         # Red Alert game module (ships Phase 2)
│   │   ├── mod.toml                #   manifest — same schema as any community mod
│   │   ├── rules/                  #   unit, structure, weapon, terrain definitions
│   │   │   ├── units/              #     infantry.yaml, vehicles.yaml, naval.yaml, aircraft.yaml
│   │   │   ├── structures/         #     allied-structures.yaml, soviet-structures.yaml
│   │   │   ├── weapons/            #     ballistics.yaml, missiles.yaml, energy.yaml
│   │   │   ├── terrain/            #     temperate.yaml, snow.yaml, interior.yaml
│   │   │   └── presets/            #     balance presets: classic.yaml, openra.yaml, remastered.yaml (D019)
│   │   ├── maps/                   #   built-in maps
│   │   ├── missions/               #   campaign missions (YAML scenario + Lua triggers)
│   │   ├── sequences/              #   sprite sequence definitions (animation frames)
│   │   ├── chrome/                 #   RA-specific UI layout (sidebar, build queue)
│   │   ├── audio/                  #   music playlists, EVA definitions, voice mappings
│   │   ├── ai/                     #   AI personality profiles (D043)
│   │   ├── scripts/                #   Lua scripts (shared triggers, ability definitions)
│   │   └── themes/                 #   UI theme overrides: classic.yaml, modern.yaml (D032)
│   └── td/                         # Tiberian Dawn game module (ships Phase 3–4)
│       ├── mod.toml
│       ├── rules/
│       ├── maps/
│       ├── missions/
│       └── ...                     #   same layout as ra/
├── LICENSE
└── THIRD-PARTY-LICENSES

Key features of the install layout:

• mods/common/ is directly analogous to OpenRA’s mods/common/. Shared assets, chrome, and cursor definitions used across all C&C-family game modules. Community game modules (Dune 2000, RA2) can depend on it or provide their own.
• mods/ra/ is a mod. It uses the same mod.toml schema, the same rules/ structure, and the same sequences/ format as a community mod. There is no “privileged” version of this directory — the engine treats it identically to <data_dir>/mods/my-total-conversion/. This means every modder can read the game’s own data as a working example.
• Every YAML file in mods/ra/rules/ is editable. Want to change tank cost? Open rules/units/vehicles.yaml, find medium_tank, change cost: 800 to cost: 750. The same workflow as OpenRA — except the YAML is standard-compliant and serde-typed.
• The CLI (ic) is the modder/operator Swiss Army knife. ic mod init, ic mod check, ic mod test, ic mod publish, ic backup create, ic export, ic server validate-config. One binary, consistent subcommands — aimed at modders, server operators, and CI/CD pipelines. Players never need it — every player-facing action has a GUI equivalent in the game client or SDK editor.

Source Repository (Contributor Layout)

What a contributor sees after cloning the repository:

iron-curtain/                       # Cargo workspace root
├── Cargo.toml                      # Workspace manifest — lists all crates
├── Cargo.lock
├── deny.toml                       # cargo-deny license policy (GPL-compatible deps only)
├── AGENTS.md                       # Agent instructions (this file)
├── README.md
├── LICENSE                         # GPL v3 with modding exception (D051)
├── mods/                           # Game data — YAML, Lua, assets (NOT Rust code)
│   ├── common/
│   ├── ra/
│   └── td/
├── crates/                         # All Rust crates live here
│   ├── ic-cnc-content/                 # Wraps cnc-formats + EA-derived code; Bevy asset integration
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── mix.rs              #   MIX archive reader (wraps cnc-formats)
│   │       ├── shp.rs              #   SHP sprite reader (wraps cnc-formats)
│   │       ├── pal.rs              #   PAL palette reader (wraps cnc-formats)
│   │       ├── aud.rs              #   AUD audio decoder (wraps cnc-formats)
│   │       ├── vqa.rs              #   VQA video decoder (wraps cnc-formats)
│   │       ├── miniyaml.rs         #   MiniYAML auto-conversion pipeline (parser from cnc-formats, D025)
│   │       ├── oramap.rs           #   .oramap map loader
│   │       └── mod_manifest.rs     #   OpenRA mod.yaml parser (D026)
│   ├── ic-protocol/                # Shared boundary: orders, codecs
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── orders.rs           #   PlayerOrder, TimestampedOrder
│   │       └── codec.rs            #   OrderCodec trait
│   ├── ic-sim/                     # Deterministic simulation (the core)
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs              #   pub API: Simulation, step(), snapshot()
│   │       ├── components/         #   ECS components — one file per domain
│   │       │   ├── mod.rs
│   │       │   ├── health.rs       #     Health, Armor, DamageState
│   │       │   ├── mobile.rs       #     Mobile, Locomotor, Facing
│   │       │   ├── combat.rs       #     Armament, AutoTarget, Turreted, AmmoPool
│   │       │   ├── production.rs   #     Buildable, ProductionQueue, Prerequisites
│   │       │   ├── economy.rs      #     Harvester, ResourceStorage, OreField
│   │       │   ├── transport.rs    #     Cargo, Passenger, Carryall
│   │       │   ├── power.rs        #     PowerProvider, PowerConsumer
│   │       │   ├── stealth.rs      #     Cloakable, Detector
│   │       │   ├── capture.rs      #     Capturable, Captures
│   │       │   ├── veterancy.rs    #     Veterancy, Experience
│   │       │   ├── building.rs     #     Placement, Foundation, Sellable, Repairable
│   │       │   └── support.rs      #     Superweapon, Chronoshift, IronCurtain
│   │       ├── systems/            #   ECS systems — one file per simulation step
│   │       │   ├── mod.rs
│   │       │   ├── orders.rs       #     validate_orders(), apply_orders()
│   │       │   ├── movement.rs     #     movement_system() — pathfinding integration
│   │       │   ├── combat.rs       #     combat_system() — targeting, firing, damage
│   │       │   ├── production.rs   #     production_system() — build queues, prerequisites
│   │       │   ├── harvesting.rs   #     harvesting_system() — ore collection, delivery
│   │       │   ├── power.rs        #     power_system() — grid calculation
│   │       │   ├── fog.rs          #     fog_system() — delegates to FogProvider trait
│   │       │   ├── triggers.rs     #     trigger_system() — Lua/WASM script callbacks
│   │       │   ├── conditions.rs   #     condition_system() — D028 condition evaluation
│   │       │   ├── cleanup.rs      #     cleanup_system() — entity removal, state transitions
│   │       │   └── weather.rs      #     weather_system() — D022 weather state machine
│   │       ├── traits/             #   Pluggable abstractions (D041) — NOT OpenRA "traits"
│   │       │   ├── mod.rs
│   │       │   ├── pathfinder.rs   #     Pathfinder trait (D013)
│   │       │   ├── spatial.rs      #     SpatialIndex trait
│   │       │   ├── fog.rs          #     FogProvider trait
│   │       │   ├── damage.rs       #     DamageResolver trait
│   │       │   ├── validator.rs    #     OrderValidator trait (D041)
│   │       │   └── ai.rs           #     AiStrategy trait (D041)
│   │       ├── math/               #   Fixed-point arithmetic, coordinates
│   │       │   ├── mod.rs
│   │       │   ├── fixed.rs        #     Fixed-point types (i32/i64 scale — P002)
│   │       │   └── pos.rs          #     WorldPos, CellPos
│   │       ├── rules/              #   YAML rule deserialization (serde structs)
│   │       │   ├── mod.rs
│   │       │   ├── unit.rs         #     UnitDef, Buildable, DisplayInfo
│   │       │   ├── weapon.rs       #     WeaponDef, Warhead, Projectile
│   │       │   ├── alias.rs        #     OpenRA trait name alias registry (D023)
│   │       │   └── inheritance.rs  #     YAML inheritance resolver
│   │       └── snapshot.rs         #   State serialization for saves/replays/rollback
│   ├── ic-net/                     # Networking library (never imports ic-sim)
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── network_model.rs    #   NetworkModel trait (D006)
│   │       ├── relay_lockstep.rs    #   EmbeddedRelayNetwork + RelayLockstepNetwork
│   │       ├── local.rs            #   LocalNetwork (testing, single-player)
│   │       └── relay_core.rs       #   RelayCore library (D007)
│   ├── ic-server/                  # Unified server binary (D074) — top-level, depends on ic-net + optionally ic-sim
│   │   ├── Cargo.toml
│   │   └── src/
│   │       └── main.rs             #   ic-server binary entry point
│   ├── ic-render/                  # Isometric rendering (Bevy plugin)
│   ├── ic-ui/                      # Game chrome, sidebar, minimap
│   ├── ic-audio/                   # Sound, music, EVA, VoIP
│   ├── ic-script/                  # Lua + WASM mod runtimes
│   ├── ic-ai/                      # Skirmish AI, adaptive difficulty, LLM strategies (depends on ic-llm)
│   ├── ic-llm/                     # LLM provider traits + infra, Tier 1 CPU inference (no ic-sim)
│   ├── ic-paths/                   # Platform path resolution, portable mode, credential store (wraps `app-path` + `strict-path` + `keyring` + `aes-gcm` + `argon2` + `zeroize`)
│   ├── ic-editor/                  # SDK binary: scenario editor, asset studio (D038+D040)
│   └── ic-game/                    # Game binary: ties all plugins together
│       ├── Cargo.toml
│       └── src/
│           └── main.rs             #   Bevy App setup, plugin registration
├── tools/                          # Developer tools (not shipped)
│   └── replay-corpus/              #   Foreign replay regression test harness (D056)
└── tests/                          # Integration tests
    ├── sim/                        #   Deterministic sim regression tests
    └── format/                     #   File format round-trip tests

Where OpenRA Contributors Find Things

An OpenRA contributor’s first question is “where does this live in IC?” This table maps OpenRA’s C# project structure to IC’s Rust workspace:

ECS Translation: OpenRA Traits → IC Components + Systems

OpenRA merges data and behavior into “traits” (C# classes). In IC’s ECS architecture, these split into components (data) and systems (behavior):

The naming convention follows Rust idioms (snake_case files, PascalCase types) but the organization mirrors OpenRA’s categorical grouping — combat things together, economy things together, movement things together.

Why This Layout Works for the Community

For data modders (80% of mods): Never leave mods/. Edit YAML, run ic mod check, see results. The built-in game modules serve as always-available, documented examples of every YAML feature. No need to read Rust code to understand what fields a unit definition supports — look at mods/ra/rules/units/infantry.yaml.

For Lua scripters (missions, game modes): Write scripts/*.lua in your mod directory. The API is a superset of OpenRA’s (D024) — same 16 globals, same function signatures. Existing OpenRA missions run unmodified. Test with ic mod test.

For engine contributors: Clone the repo. crates/ holds all Rust code. Each crate has a single responsibility and clear boundaries. The naming (ic-sim, ic-net, ic-render) tells you what it does. Within ic-sim, components/ holds data, systems/ holds logic, traits/ holds the pluggable abstractions — the ECS split is consistent and predictable.

For total-conversion modders: The ic-sim/src/traits/ directory defines every pluggable seam — custom pathfinder, custom AI, custom fog of war, custom damage resolution. Implement a trait as a WASM module (Tier 3), register it in your mod.toml, and the engine uses your implementation. No forking, no C# DLL stacking.

Development Asset Strategy

A clean-sheet engine needs art for editor chrome, UI menus, CI testing, and developer workflows — but it cannot ship or commit copyrighted game content. This subsection documents how reference projects host their game resources, what IC can freely use, and what belongs (or doesn’t belong) in the repository.

How Reference Projects Host Game Resources

Original Red Alert (1996): Assets ship as .mix archives — flat binary containers with CRC-hashed filenames. Originally distributed on CD-ROM, later as a freeware download installer (2008). All sprites (.shp), terrain (.tmp), palettes (.pal), audio (.aud), and cutscenes (.vqa) are packed inside these archives. No separate asset repository — everything distributes as compiled binaries through retail channels. The freeware release means free to download and play, not free to redistribute or embed in another project.

EA Remastered Collection (2020): Assets distribute through Steam (and previously Origin). The HD sprite sheets, remastered music, and cutscenes are proprietary EA content — not covered by the GPL v3 license that applies only to the C++ engine DLLs. Resources use updated archive formats (MegV3 for TD HD, standard .mix for classic mode) at known Steam AppId paths. See § Content Detection for how IC locates these.

OpenRA: The engine never distributes copyrighted game assets. On first launch, a content installer detects existing game installations (Steam, Origin, GOG, disc copies) or downloads specific .mix files from EA’s publicly accessible mirrors (the freeware releases). Assets are extracted and stored to ~/.openra/Content/ra/ (Linux) or the OS-appropriate equivalent. The OpenRA source repository contains only engine code (C#, GPL v3), original UI chrome art, mod rules (MiniYAML), maps, Lua scripts, and editor art — all OpenRA-created content. The few original assets (icons, cursors, fonts, panel backgrounds) are small enough for plain git. No Git LFS, no external asset hosting.

Key pattern: Every successful engine reimplementation project (OpenRA, CorsixTH, OpenMW, Wargus) uses the same model — engine code in the repo, game content loaded at runtime from the player’s own installation. IC follows this pattern exactly.

Legal Boundaries — What IC Can Freely Use

OpenRA’s original chrome art is technically GPL v3 and could be used — but IC’s design explicitly creates all theme art as original work (D032). Copying OpenRA’s chrome would create visual confusion between the two projects and contradict the design direction. Study the patterns (layout structure, what elements exist), create original art.

The EA GPL source repositories contain no art assets whatsoever — only C/C++ source code. The .mix archives containing actual game content (sprites, audio, palettes, terrain, cutscenes) are copyrighted EA property distributed through retail channels, even in the freeware release.

What Belongs in the Repository

Git LFS is not needed. The design docs already rejected Git LFS for Workshop distribution (“1GB free then paid; designed for source code, not binary asset distribution; no P2P” — see D049). The same reasoning applies to development: IC’s repository is code + YAML + design docs + small original icons. Total committed binary assets will stay well under 10MB.

CI testing strategy: Parser and format tests use synthetic fixtures — small, hand-crafted binary files (a 2-frame .shp, a trivial .mix with 3 files, a minimal .pal) committed to tests/fixtures/. These are original creations that exercise ic-cnc-content code without containing EA content. Integration tests requiring real RA assets are gated behind an optional feature flag (#[cfg(feature = "integration")]) and run on CI runners where RA is installed, configured via IC_CONTENT_DIR environment variable.

Repository Asset Layout

Extending the source repository layout (see § Source Repository above):

iron-curtain/
├── assets/                         # IC-original assets ONLY (committed)
│   ├── editor/                     #   SDK toolbar icons, editor cursors, panel art
│   ├── ui/                         #   Menu chrome sprites, HUD elements
│   ├── fonts/                      #   Bundled open-licensed fonts
│   └── placeholder/                #   Debug sprites, test palettes, grid overlays
├── tests/
│   └── fixtures/                   #   Synthetic .mix/.shp/.pal for parser tests
├── content/                        #   *** GIT-IGNORED *** — local dev game files
│   └── ra/                         #   Developer's RA installation (pointed to or symlinked)
├── .gitignore                      #   Ignores content/, target/, *.db
└── ...

The content/ directory is git-ignored. Each developer either symlinks it to their RA installation or sets IC_CONTENT_DIR to point elsewhere. This keeps copyrighted assets completely out of version control while giving developers a consistent local path for testing.

Freely-Usable Resources for Graphics, Menus & CI

IC needs original art for editor chrome, UI menus, and visual tooling. These are the recommended open-licensed sources:

Icon libraries (for editor toolbar, SDK panels, menu items):

Fonts (for UI text, editor panels, console):

Smart font support note (localization/RTL):

• Primary UI fonts (theme-driven) and fallback fonts (coverage-driven) are distinct concerns.
• A broad-coverage family such as Noto should be available as the fallback backbone for scripts not covered by the theme’s primary font.
• Correct RTL rendering still depends on the shared shaping + BiDi + layout-direction contract above; fallback fonts alone are insufficient.

UI framework:

• egui (MIT) — the editor’s panel/widget framework, and the game client’s developer overlays (D058 console, D031 debug overlay — gated behind dev-tools feature flag, absent from release builds). Ships with Bevy via bevy_egui. Provides buttons, sliders, text inputs, dropdown menus, tree views, docking, color pickers — all rendered procedurally with no external art needed. Handles 95% of SDK chrome requirements.
• Bevy UI — the game client’s player-facing UI framework. Used for in-game chrome (sidebar, minimap, build queue) with IC-original sprite sheets styled per theme (D032). Player-facing game UI uses bevy_ui exclusively.

Game content (sprites, terrain, audio, cutscenes):

• Player’s own RA installation — loaded at runtime via ContentDetector. Every developer needs Red Alert installed locally (Steam, GOG, or freeware). This is the development workflow, not a limitation — you’re building an engine for a game you play.
• No external asset CDN. IC does not host, mirror, or download copyrighted game files. The browser build (Phase 7) uses drag-and-drop import from the player’s local files — see 05-FORMATS.md § Browser Asset Storage.

Placeholder art (for development before real assets load):

During early development, before the full content detection pipeline is complete, use committed placeholder assets in assets/placeholder/:

• Colored rectangles (16×16, 24×24, 48×48) as unit stand-ins
• Numbered grid tiles for terrain testing
• Solid-color palette files (.pal-format, 768 bytes) for render pipeline testing
• Simple geometric shapes for building footprints
• Generated checkerboard patterns for missing texture fallbacks

These are all original creations — trivial to produce, zero legal risk, and immediately useful for testing the render pipeline before content detection is wired up.

IC SDK & Editor Architecture (D038 + D040)

IC SDK & Editor Architecture (D038 + D040)

The IC SDK is the creative toolchain — a separate Bevy application that shares library crates with the game but ships as its own binary. Players never see editor UI. Creators download the SDK to build maps, missions, campaigns, and assets. This section covers the practical architecture: what the GUI looks like, what graphical resources it uses, how the UX flows, and how to start building it. For the full feature catalog (30+ modules, trigger system, campaign editor, dialogue trees, Game Master mode), see decisions/09f/D038-scenario-editor.md and decisions/09f/D040-asset-studio.md.

SDK Application Structure

The SDK is a single Bevy application with tabbed workspaces:

┌───────────────────────────────────────────────────────────────────────┐
│  IC SDK                                              [_][□][X]        │
├──────────────┬────────────────────────────────────────────────────────┤
│              │  [Scenario Editor] [Asset Studio] [Campaign Editor]    │
│  MODE PANEL  ├────────────────────────────────────────┬───────────────┤
│              │                                        │               │
│  ┌─────────┐ │         ISOMETRIC VIEWPORT             │  PROPERTIES   │
│  │Terrain  │ │                                        │  PANEL        │
│  │Entities │ │    (same ic-render as the game —       │               │
│  │Triggers │ │     live preview of actual game        │  [Name: ___]  │
│  │Waypoints│ │     rendering)                         │  [Faction: _] │
│  │Modules  │ │                                        │  [Health: __] │
│  │Regions  │ │                                        │  [Script: _]  │
│  │Scripts  │ │                                        │               │
│  │Layers   │ │                                        │               │
│  └─────────┘ │                                        │               │
│              ├────────────────────────────────────────┤               │
│              │  BOTTOM PANEL (context-sensitive)       │               │
│              │  Triggers list / Script editor / Vars  │               │
│              ├────────────────────────────────────────┴───────────────┤
│              │  STATUS BAR: cursor pos │ cell info │ complexity meter │
└──────────────┴───────────────────────────────────────────────────────┘

Four main areas:

GUI Technology Choice

The SDK faces a UI technology decision that the game does not: the game’s UI is a themed, styled chrome layer (D032) built for immersion, while the SDK needs a dense, professional tool UI with text fields, dropdowns, tree views, scrollable lists, and property inspectors.

Approach: Dual UI — ic-render viewport + egui panels

Why egui for tool panels: Bevy UI (bevy_ui) is designed for game chrome — styled panels, themed buttons, responsive layouts. The SDK needs raw productivity UI: property grids with dozens of fields, type-ahead search in entity palettes, nested tree views for trigger folders, side-by-side diff panels. egui provides all of these out of the box. bevy_egui is a mature integration crate. Player-facing game UI uses themed bevy_ui exclusively; egui appears in two contexts: the SDK (tool panels, inspectors) and the game client’s developer overlays (D058 console, D031 debug overlay — both gated behind a dev-tools feature flag, absent from release builds). The SDK uses both bevy_ui (for the isometric viewport chrome) and egui (for everything else).

Why ic-render for the viewport: The editor viewport must show exactly what the game will show — same sprite draw modes, same z-ordering, same palette application, same shroud rendering. If the editor used a simplified renderer, creators would encounter “looks different in-game” surprises. Reusing ic-render eliminates this class of bugs entirely.

What Graphical Resources the Editor Uses

The SDK does not need its own art assets for the editor chrome — it uses egui’s default styling (suitable for professional tools) plus the game’s own assets for content preview.

Key point: The SDK ships with minimal original art — just icons and cursors for the editor UI itself. All game content (sprites, terrain, palettes, audio) comes from the player’s installed games. This is the same legal model as the game: IC never distributes copyrighted assets.

Entity palette thumbnails: When the SDK loads a game module, it renders a small thumbnail for every placeable entity type — a 48×48 preview showing the unit’s idle frame. These are cached on disk after first generation. The entity palette (left panel in Entities mode) displays these as a searchable grid, with categories, favorites, and recently-placed lists. This is the “Garry’s Mod spawn menu” UX described in D038 — search-as-you-type finds any entity instantly.

UX Flow — How a Creator Uses the Editor

Creating a New Scenario (5-minute orientation)

1. Launch SDK. Opens to a start screen: New Scenario, Open Scenario, Open Campaign, Asset Studio, Recent Files.
2. New Scenario. Dialog: choose map size, theater (Temperate/Snow/Interior), game module (RA1/TD/custom mod). A blank map with terrain generates.
3. Terrain mode (default). Terrain brush active. Paint terrain tiles by clicking and dragging. Brush sizes 1×1 to 7×7. Elevation tools if the game module supports Z. Right-click to eyedrop a tile type.
4. Switch to Entities mode (Tab or click). Entity palette appears in the left panel. Search for “Medium Tank” → click to select → click on map to place. Properties panel on the right shows the entity’s attributes: faction, facing, stance, health, veterancy, Probability of Presence, inline script.
5. Switch to Triggers mode. Draw a trigger area on the map. Set condition: “Any unit of Faction A enters this area.” Set action: “Reinforcements module activates” (select a preconfigured module). Set countdown timer with min/mid/max randomization.
6. Switch to Modules mode. Browse built-in modules (Wave Spawner, Patrol Route, Reinforcements, Objectives). Drag a module onto the map or assign it to a trigger.
7. Press Test. SDK launches ic-game with this scenario via LocalNetwork. Play the mission. Close game → return to editor. Iterate.
8. Press Publish. Exports as .oramap-compatible package → uploads to Workshop (D030).

Simple ↔ Advanced Mode

D038 defines a Simple/Advanced toggle controlling which features are visible:

Simple mode hides 15+ features to present a clean, approachable interface. A new creator sees: terrain tools, entity palette, basic triggers, pre-built modules, waypoints, and a Test button. That’s enough to build a complete mission. Advanced mode reveals the full power. Toggle at any time — no data loss.

Editor Viewport — What Gets Rendered

The viewport is not just a map — it renders multiple overlay layers on top of the game’s normal isometric view:

Layer 0:   Terrain tiles (from ic-render, same as game)
Layer 1:   Grid overlay (faint lines showing cell boundaries, toggle-able)
Layer 2:   Region highlights (named regions shown as colored overlays)
Layer 3:   Trigger areas (pulsing colored boundaries with labels)
Layer 4:   Entities (buildings, units — rendered via ic-render)
Layer 5:   Waypoint markers (numbered circles with directional arrows)
Layer 6:   Connection lines (links between triggers, modules, waypoints)
Layer 7:   Entity selection highlight (selected entity's bounding box)
Layer 8:   Placement ghost (translucent preview of entity being placed)
Layer 9:   Cursor tool overlay (brush circle for terrain, snap indicator)

Layers 1–3 and 5–9 are editor-only overlays drawn on top of the game rendering. They use basic 2D shapes (rectangles, circles, lines, text labels) rendered via Bevy’s Gizmos system or a simple overlay pass. No complex art assets needed — colored geometric primitives with alpha transparency.

Asset Studio GUI

The Asset Studio is a tab within the same SDK application. Its layout differs from the scenario editor:

┌───────────────────────────────────────────────────────────────────────┐
│  IC SDK  — Asset Studio                                               │
├───────────────────────┬───────────────────────────┬───────────────────┤
│                       │                           │                   │
│  ASSET BROWSER        │    PREVIEW VIEWPORT       │  PROPERTIES       │
│                       │                           │                   │
│  📁 conquer.mix       │   (sprite viewer with     │  Frames: 52       │
│    ├── e1.shp         │    palette applied,        │  Width: 50        │
│    ├── 1tnk.shp       │    animation controls,     │  Height: 39       │
│    └── ...            │    zoom, frame scrub)      │  Draw mode:       │
│  📁 temperat.mix      │                           │    [Normal ▾]     │
│    └── ...            │   ◄ ▶ ⏸ ⏮ ⏭  Frame 12/52 │  Palette:         │
│  📁 local assets      │                           │    [temperat ▾]   │
│    └── my_sprite.png  │                           │  Player color:    │
│                       │                           │    [Red ▾]        │
│  🔎 Search...         │                           │                   │
├───────────────────────┴───────────────────────────┼───────────────────┤
│  TOOLS:  [Import] [Export] [Batch] [Compare]      │  In-context:      │
│                                                    │  [Preview as unit]│
└────────────────────────────────────────────────────┴───────────────────┘

Three columns: Asset browser (tree view of loaded archives + local files), preview viewport (sprite/palette/audio/video viewer), and properties panel (metadata + editing controls). The bottom row has action buttons and the “preview as unit / building / chrome” in-context buttons that render the asset on an actual map tile (using ic-render).

How to Start Building the Editor

The editor bootstraps on top of the game’s rendering — so the first-runnable (§ “First Runnable” above) is a prerequisite. Once the engine can load and render RA maps, the editor development follows a clear sequence:

Phase 6a Bootstrapping (Editor MVP)

Total: ~18 weeks for a functional scenario editor MVP. This covers the “core scenario editor” deliverable from Phase 6a — everything a creator needs to build and publish a playable mission.

Asset Studio Bootstrapping

The Asset Studio can be developed in parallel once ic-cnc-content is mature (Phase 0):

Total: ~10 weeks for Asset Studio Layer 1 (browser/viewer) + Layer 2 (basic editing). Layer 3 (LLM generation) is Phase 7.

Do We Have Enough Information?

Yes — the design is detailed enough to build from. The critical path is clear:

1. Rendering engine (§ “First Runnable”) is the prerequisite. Without ic-cnc-content and ic-render, there’s no viewport.
2. GUI framework (egui) is a known, mature Rust crate. No research needed — it has property inspectors, tree views, text editors, and all the widget types the SDK needs.
3. Viewport rendering reuses ic-render — the same code that renders the game renders the editor viewport. This eliminates the hardest rendering problem.
4. Editor overlays (trigger zones, waypoints, grid lines) are simple 2D shapes on top of the game render. Bevy’s Gizmos API handles this.
5. Data model is defined — scenarios are YAML + map.bin (OpenRA-compatible format), triggers are YAML structs, modules are YAML + Lua. No new format to invent.
6. Feature scope is defined in D038 (every module, every trigger type, every panel). The question is NOT “what should the editor do” — that’s answered. The question is “in what order do we build it” — and that’s answered by the phasing table above.

What remains open:

• P003 (audio library choice) affects the Asset Studio’s audio player but not the scenario editor
• Exact egui widget customization for the entity palette (search UX, thumbnail rendering) needs prototyping
• Campaign graph editor’s visual layout algorithm (auto-layout for mission nodes) needs implementation experimentation
• The precise line between bevy_ui and egui usage may shift during development — start with egui for everything, migrate specific widgets to bevy_ui only if styling needs demand it

See decisions/09f/D038-scenario-editor.md for the full scenario editor feature catalog, and decisions/09f/D040-asset-studio.md for the Asset Studio’s three-layer architecture and format support tables.

Multi-Game Extensibility (Game Modules)

Multi-Game Extensibility (Game Modules)

The engine is designed as a game-agnostic RTS framework (D039) that ships with Red Alert (default) and Tiberian Dawn as built-in game modules. The same engine can run RA2, Dune 2000, or an original game as additional game modules — like OpenRA runs TD, RA, and D2K on one engine.

Game Module Concept

A game module is a bundle of:

#![allow(unused)]
fn main() {
/// Each supported game implements this trait.
pub trait GameModule {
    /// Register ECS components (unit types, mechanics) into the world.
    fn register_components(&self, world: &mut World);

    /// Return the ordered system pipeline for this game's simulation tick.
    fn system_pipeline(&self) -> Vec<Box<dyn System>>;

    /// Provide the pathfinding implementation (selected by lobby/experience profile, D045).
    fn pathfinder(&self) -> Box<dyn Pathfinder>;

    /// Provide the spatial index implementation (spatial hash, BVH, etc.).
    fn spatial_index(&self) -> Box<dyn SpatialIndex>;

    /// Provide the fog of war implementation (radius, elevation LOS, etc.).
    fn fog_provider(&self) -> Box<dyn FogProvider>;

    /// Provide the damage resolution algorithm (standard, shield-first, etc.).
    fn damage_resolver(&self) -> Box<dyn DamageResolver>;

    /// Provide order validation logic (D041 — engine enforces this before apply_orders).
    fn order_validator(&self) -> Box<dyn OrderValidator>;

    /// Register format loaders (e.g., .vxl for RA2, .shp for RA1).
    fn register_format_loaders(&self, registry: &mut FormatRegistry);

    /// Register render backends (sprite renderer, voxel renderer, etc.).
    fn register_renderers(&self, registry: &mut RenderRegistry);

    /// List available render modes — Classic, HD, 3D, etc. (D048).
    fn render_modes(&self) -> Vec<RenderMode>;

    /// Register game-module-specific commands into the Brigadier command tree (D058).
    /// RA1 registers `/sell`, `/deploy`, `/stance`, etc. A total conversion registers
    /// its own novel commands. The engine's built-in commands (chat, help, cvars) are
    /// pre-registered before this method is called.
    fn register_commands(&self, dispatcher: &mut CommandDispatcher);

    /// YAML rule schema for this game's unit definitions.
    /// Used by the editor for validation/autocomplete and by `ic mod lint` for checking.
    fn rule_schema(&self) -> RuleSchema;
}

/// Describes the YAML rule structure for a game module.
/// Maps top-level YAML keys to expected field types, marks required vs optional fields,
/// and declares valid enum values. Used by the scenario editor (D038) for autocomplete,
/// `ic mod lint` for validation, and LLM generation (D016) for schema-aware output.
struct RuleSchema {
    /// Top-level actor categories (e.g., "infantry", "vehicle", "building", "aircraft").
    actor_categories: Vec<CategoryDef>,
    /// Weapon definition schema.
    weapon_schema: FieldMap,
    /// Projectile/warhead schemas.
    warhead_schema: FieldMap,
}
}

Bevy App Construction (ic-game)

The GameModule trait provides the pieces; the ic-game binary assembles them into a Bevy App. Each IC crate exposes a Bevy Plugin that accepts game-module-provided configuration:

// ic-game/src/main.rs (simplified)
fn main() {
    let module: Box<dyn GameModule> = select_game_module(); // CLI flag, config, or lobby selection

    let mut app = App::new();
    app.add_plugins(DefaultPlugins);                    // Bevy: windowing, input, asset server
    app.add_plugins(SimPlugin::new(&*module));           // ic-sim: ECS components + system pipeline
    app.add_plugins(NetPlugin);                          // ic-net: NetworkModel, relay client
    app.add_plugins(RenderPlugin::new(&*module));        // ic-render: sprite/voxel backends
    app.add_plugins(AudioPlugin);                        // ic-audio: .aud, EVA, music
    app.add_plugins(UiPlugin);                           // ic-ui: sidebar, minimap, build queue
    app.add_plugins(ScriptPlugin);                       // ic-script: Lua + WASM runtimes
    app.add_plugins(AiPlugin);                           // ic-ai: skirmish AI
    app.run();
}

What SimPlugin::new() does internally:

1. Calls module.register_components(world) — inserts game-specific ECS components
2. Stores the system pipeline from module.system_pipeline() as a resource — Simulation::apply_tick() runs these in order
3. Inserts trait objects as Bevy resources: module.pathfinder() → Res<Box<dyn Pathfinder>>, module.spatial_index() → Res<Box<dyn SpatialIndex>>, etc.
4. Calls module.register_format_loaders(registry) — registers .shp, .mix, etc. with Bevy’s AssetServer
5. Stores module.rule_schema() for validation and editor integration

Plugin registration order matters: SimPlugin must register before RenderPlugin (render reads sim state). NetPlugin provides the NetworkModel resource that GameLoop depends on. ScriptPlugin registers after SimPlugin because Lua/WASM scripts interact with already-registered components.

Module selection: select_game_module() returns a Box<dyn GameModule> based on launch context — defaulting to RA1, switchable via --mod td CLI flag or lobby selection. The module choice is fixed for the lifetime of a match; switching modules between matches uses the drop-and-recreate strategy (see game-loop.md § Match Cleanup).

Validation from OpenRA mod ecosystem: Analysis of six major OpenRA community mods (see research/openra-mod-architecture-analysis.md) confirms that every GameModule trait method addresses a real extension need:

• register_format_loaders() — OpenKrush (KKnD on OpenRA) required 15+ custom binary format decoders (.blit, .mobd, .mapd, .lvl, .son, .vbc) that bear no resemblance to C&C formats. TiberianDawnHD needed RemasterSpriteSequence for 128×128 HD tiles. Format extensibility is not optional for non-C&C games.
• system_pipeline() — OpenKrush replaced 16 complete mechanic modules (construction, production, oil economy, researching, bunkers, saboteurs, veterancy). OpenSA (Swarm Assault) added living-world systems (plant growth, creep spawners, colony capture). The pipeline cannot be fixed.
• render_modes() — TiberianDawnHD is a pure render-only mod (zero gameplay changes) that adds HD sprite rendering with content source detection (Steam AppId, Origin registry, GOG paths). Render mode extensibility enables this cleanly.
• pathfinder() — OpenSA needed WaspLocomotor (flying insect pathfinding); OpenRA/ra2 defines 8 locomotor types (Hover, Mech, Jumpjet, Teleport, etc). RA1’s JPS + flowfield is not universal.
• fog_provider() / damage_resolver() — RA2 needs elevation-based LOS and shield-first damage; OpenHV needs a completely different resource flow model (Collector → Transporter → Receiver pipeline). Game-specific logic belongs in the module.
• register_commands() — RA1 registers /sell, /deploy, /stance, superweapon commands. A Tiberian Dawn module registers different superweapon commands. A total conversion registers entirely novel commands. The engine cannot predefine game-specific commands (D058).

What the engine provides (game-agnostic)