# jaasssoooonnnnn/firstlight_cr architecture

> Architecture diagram of the GitHub repository jaasssoooonnnnn/firstlight_cr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jaasssoooonnnnn/firstlight_cr
- Repository: https://github.com/jaasssoooonnnnn/firstlight_cr

## Overview

FirstLight CR is an offline Clash Royale environment and agent-training system. Its main loop reconstructs replay behavior in the native engine, turns observations and actions into training examples, learns recurrent policies through imitation learning and PPO self-play, then evaluates or runs those policies in matches. The graph also preserves the card-semantics and distributed-worker branches. Several links reflect README-level capabilities because their implementation was not sampled; edges cite only the README or source-index references that support them.

Main entry points: [`native_runner/battle_env.py`](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/battle_env.py) (Battle environment), [`native_runner/training/v4/async_cluster_self_play.py`](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/async_cluster_self_play.py) (Self-play collection), [`native_runner/cr_native_env.py`](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/cr_native_env.py) (Native match host), [`native_runner/training/v4/model.py`](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/model.py) (Recurrent actor-critic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Native battle runtime"]
  node_probe["Native engine probe"]
  node_native["Native match host<br/>[cr_native_env.py]"]
  node_battle["Battle environment<br/>[battle_env.py]"]
  node_contracts["Versioned contracts<br/>[contracts.py]"]
  node_match["Match configuration<br/>[match_factory.py]"]
end

subgraph group_data["Replay and game data"]
  node_cards["Card specifications<br/>[card_specs.py]"]
  node_semantics["Static card logic<br/>[card_logic.py]"]
  node_catalog["Card and mechanics catalog<br/>[catalog.py]"]
  node_replay["Replay reconstruction"]
  node_archive[("Replay archive<br/>[replay_archive.py]")]
end

subgraph group_learning["Training and policy"]
  node_cache[("Training cache<br/>[cache_builder.py]")]
  node_imitation["Imitation learning<br/>[imitation.py]"]
  node_tensor["Observation tensorization<br/>[tensorizer.py]"]
  node_model["Recurrent actor-critic<br/>[model.py]"]
  node_ppo["PPO optimization<br/>[ppo.py]"]
  node_selfplay["Self-play collection"]
  node_transport["Remote worker transport"]
end

subgraph group_play["Play and operations"]
  node_session["Policy inference session<br/>[policy_session.py]"]
  node_evaluate["Match evaluation<br/>[evaluate.py]"]
  node_viewer["Replay and match viewer<br/>[replay_viewer.py]"]
  node_service["Policy service<br/>[serve_policy.py]"]
end

node_researcher(("Trainer / researcher"))
node_player(("Offline player"))
node_replays[("Replay dataset")]

node_replays -->|"supplies replays"| node_replay
node_replay -->|"reconstructs matches"| node_native
node_replay -->|"adapts episodes"| node_archive
node_archive -.->|"feeds cache"| node_cache
node_cache -.->|"provides examples"| node_imitation
node_imitation -->|"trains policy"| node_model
node_selfplay -->|"collects matches"| node_battle
node_selfplay -.->|"collects PPO data"| node_ppo
node_ppo -->|"updates policy"| node_model
node_selfplay -->|"uses worker transport"| node_transport
node_battle -->|"binds engine"| node_native
node_native -->|"controls native engine"| node_probe
node_match -->|"configures matches"| node_native
node_battle -->|"uses wire contracts"| node_contracts
node_battle -->|"uses card specs"| node_cards
node_cards -->|"resolves card logic"| node_semantics
node_catalog -->|"compiles logic"| node_semantics
node_battle -.->|"supplies observations"| node_tensor
node_tensor -->|"encodes model input"| node_model
node_model -->|"runs inference"| node_session
node_session -.->|"selects actions"| node_battle
node_researcher -->|"chooses data"| node_replays
node_researcher -->|"starts training"| node_selfplay
node_researcher -->|"compares policies"| node_evaluate
node_evaluate -.->|"runs matches"| node_battle
node_player -->|"opens offline match"| node_viewer
node_viewer -->|"uses policy"| node_session
node_player -->|"requests actions"| node_service
node_service -.->|"serves inference"| node_session

click node_probe "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/probe/cr_replay_probe.cpp"
click node_native "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/cr_native_env.py"
click node_battle "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/battle_env.py"
click node_contracts "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/contracts.py"
click node_match "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/match_factory.py"
click node_cards "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/card_specs.py"
click node_semantics "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/resource_compiler/card_logic.py"
click node_catalog "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/resource_compiler/catalog.py"
click node_replay "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/royaleapi_replay.py"
click node_archive "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/replay_archive.py"
click node_cache "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/cache_builder.py"
click node_imitation "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/imitation.py"
click node_tensor "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/tensorizer.py"
click node_model "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/model.py"
click node_ppo "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/ppo.py"
click node_selfplay "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/async_cluster_self_play.py"
click node_transport "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/remote_worker_transport.py"
click node_session "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/policy_session.py"
click node_evaluate "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/evaluate.py"
click node_viewer "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/replay_viewer.py"
click node_service "https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/serve_policy.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_probe,node_native,node_battle,node_contracts,node_match toneBlue
class node_cards,node_semantics,node_catalog,node_replay,node_archive,node_replays toneAmber
class node_cache,node_imitation,node_tensor,node_model,node_ppo,node_selfplay,node_transport toneMint
class node_session,node_evaluate,node_viewer,node_service toneRose
class node_researcher,node_player toneIndigo
```

## Components

### Native battle runtime

- [Native engine probe](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/probe/cr_replay_probe.cpp): `native_runner/probe/cr_replay_probe.cpp`
- [Native match host](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/cr_native_env.py): `native_runner/cr_native_env.py`
- [Battle environment](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/battle_env.py): `native_runner/battle_env.py`
- [Versioned contracts](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/contracts.py): `native_runner/contracts.py`
- [Match configuration](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/match_factory.py): `native_runner/match_factory.py`

### Replay and game data

- [Card specifications](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/card_specs.py): `native_runner/card_specs.py`
- [Static card logic](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/resource_compiler/card_logic.py): `native_runner/resource_compiler/card_logic.py`
- [Card and mechanics catalog](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/resource_compiler/catalog.py): `native_runner/resource_compiler/catalog.py`
- [Replay reconstruction](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/royaleapi_replay.py): `native_runner/royaleapi_replay.py`
- [Replay archive](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/replay_archive.py): `native_runner/training/replay_archive.py`

### Training and policy

- [Training cache](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/cache_builder.py): `native_runner/training/v4/cache_builder.py`
- [Imitation learning](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/imitation.py): `native_runner/training/v4/imitation.py`
- [Observation tensorization](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/tensorizer.py): `native_runner/training/v4/tensorizer.py`
- [Recurrent actor-critic](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/model.py): `native_runner/training/v4/model.py`
- [PPO optimization](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/ppo.py): `native_runner/training/v4/ppo.py`
- [Self-play collection](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/async_cluster_self_play.py): `native_runner/training/v4/async_cluster_self_play.py`
- [Remote worker transport](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/remote_worker_transport.py): `native_runner/training/v4/remote_worker_transport.py`

### Play and operations

- [Policy inference session](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/policy_session.py): `native_runner/training/v4/policy_session.py`
- [Match evaluation](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/evaluate.py): `native_runner/training/v4/evaluate.py`
- [Replay and match viewer](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/replay_viewer.py): `native_runner/training/replay_viewer.py`
- [Policy service](https://github.com/jaasssoooonnnnn/firstlight_cr/blob/main/native_runner/training/v4/serve_policy.py): `native_runner/training/v4/serve_policy.py`

### Other components

- **Trainer / researcher**
- **Offline player**
- **Replay dataset**

## Connections

- Replay dataset → Replay reconstruction: supplies replays (evidence: `README.md`)
- Replay reconstruction → Native match host: reconstructs matches (evidence: `README.md`)
- Replay reconstruction → Replay archive: adapts episodes (evidence: `native_runner/royaleapi_replay.py`)
- Replay archive → Training cache: feeds cache
- Training cache → Imitation learning: provides examples
- Imitation learning → Recurrent actor-critic: trains policy (evidence: `README.md`)
- Self-play collection → Battle environment: collects matches (evidence: `README.md`)
- Self-play collection → PPO optimization: collects PPO data (evidence: `native_runner/training/v4/async_cluster_self_play.py`)
- PPO optimization → Recurrent actor-critic: updates policy (evidence: `README.md`)
- Self-play collection → Remote worker transport: uses worker transport (evidence: `native_runner/training/v4/async_cluster_self_play.py`)
- Battle environment → Native match host: binds engine (evidence: `native_runner/battle_env.py`)
- Native match host → Native engine probe: controls native engine (evidence: `README.md`)
- Match configuration → Native match host: configures matches (evidence: `native_runner/cr_native_env.py`)
- Battle environment → Versioned contracts: uses wire contracts (evidence: `native_runner/battle_env.py`)
- Battle environment → Card specifications: uses card specs (evidence: `native_runner/battle_env.py`)
- Card specifications → Static card logic: resolves card logic
- Card and mechanics catalog → Static card logic: compiles logic (evidence: `native_runner/resource_compiler/catalog.py`)
- Battle environment → Observation tensorization: supplies observations
- Observation tensorization → Recurrent actor-critic: encodes model input (evidence: `native_runner/training/v4/policy_session.py`)
- Recurrent actor-critic → Policy inference session: runs inference (evidence: `native_runner/training/v4/policy_session.py`)
- Policy inference session → Battle environment: selects actions (evidence: `native_runner/training/v4/policy_session.py`)
- Trainer / researcher → Replay dataset: chooses data (evidence: `README.md`)
- Trainer / researcher → Self-play collection: starts training (evidence: `README.md`)
- Trainer / researcher → Match evaluation: compares policies (evidence: `README.md`)
- Match evaluation → Battle environment: runs matches
- Offline player → Replay and match viewer: opens offline match (evidence: `README.md`)
- Replay and match viewer → Policy inference session: uses policy (evidence: `native_runner/training/replay_viewer.py`)
- Offline player → Policy service: requests actions (evidence: `README.md`)
- Policy service → Policy inference session: serves inference
