---
title: "Hot reload C# in a running game"
url: https://recursiveai.org/onegame/cookbook/hot-reload/
description: "Hot reload C# in a running game: save an edit to a view or the simulation and see it in the next frame with the world kept, what happens on a compile error or a rude edit, and what it means for determinism. With onegame."
version: "1.15.2"
---

# Hot reload C# in a running game

Run the game with `onegame run` and save an edit to any C# file: in a Debug build it is applied to the running program in place, with the same tick, the same entities and the same state. There is nothing to set up. The scaffold below is a complete small game, a ship you fly with WASD or a gamepad.

```shell
dotnet tool install -g RecursiveAI.OneGame.Cli --version 1.15.2
onegame new kiln && cd kiln
onegame run
```

You need the .NET 10 SDK. The terminal says:

```text
hot reload on: edit code and save to see it in the running game (--no-hot turns it off; see docs/hot-reload.md).
```

Fly the ship a little, then change its label in `Game.cs` and save the file. The label in the window changes at once:

```csharp
    [View]
    public string Label() => $"ship at {X.ToInt()}, {Y.ToInt()}";   // was $"x {X.ToInt()}  y {Y.ToInt()}"
```

```text
hot reload: edit applied; the world is unchanged.
```

An edit to the simulation applies the same way and runs from the next tick. Make the cruising speed 2 instead of 1.5 in `OnTick`, and the ship speeds up where it is:

```csharp
        var speed = Boost ? Fixed.FromInt(3) : Fixed.FromInt(2);   // was Fixed.FromRatio(3, 2)
```

Views, sim code, commands and screens all reload, and so do pictures and other files in `art/`. A script or an AI agent driving the game over [live control](https://recursiveai.org/onegame/cookbook/live-control-mcp/) can wait for each edit with the `hot_reload` tool, which reports how many edits were `applied`.

## A compile error

Delete a semicolon and save. The game keeps running the last good code:

```text
hot reload: the edit does not compile; the game keeps running the last good code.
hot reload: ; expected [CS1002, Game.cs(26)]
```

Fix it and save again, and the edit applies.

## A rude edit restarts with the world kept

Some edits can’t be applied to a running program: changing the type of a synced member, renaming or removing one, or changing a method’s signature on a loaded type. Rename the synced `Boost` property to `Boosting` everywhere in `Game.cs` and save:

```text
hot reload: this edit cannot be applied to the running game: Renaming field '__p_Boost' requires restarting the application [ENC0020, generated code of Kiln_Ship, from a change to its synced members, commands or views].
hot reload: world saved; restarting and loading it.
```

The new process loads the world the old one saved: the same tick, the same hash, the ship where it was. Ctrl+R in the terminal restarts the game by hand.

## Determinism

Hot reload is for iterating, not for recording facts. A run that spans an edit was made by two versions of the code and can’t be reproduced, so live control reports it as `replaySafe: false`, and a session recording is cut into a new segment at the edit. For a recording or a hash you keep, run from a clean start: `onegame run --no-hot`, or a test. This one holds right for three seconds with the final code. Save it as `scenarios/cruise.yaml`:

```yaml
name: cruise
description: Hold right for 180 ticks from a clean start.
steps:
  - action: { name: move, state: down, x: 1, y: 0 }
  - step: 180
  - action: { name: move, state: up }
expect:
  - state: { entity: Ship, property: X, equals: 360 }
```

```shell
onegame test --scenario scenarios/cruise.yaml
```

```text
PASS cruise (39 ms, tick 180, hash f2118bbfde6c48e2)
1 passed, 0 failed
```

## Limits

- **Debug builds and `onegame run` only.** Batch runs (`--frames`, `--capture`, `--scenario`, `--replay`, `--json`), `onegame test`, `--release` builds and exports don’t hot reload, nor do Android, iOS and web runs or cluster nodes started with `onegame cluster`.
- **Start-up code takes effect on the next start.** Edits to `Setup`, `DefineActions`, `Style`, `DefineFonts` and `RegisterEntities` are accepted but used after a restart.
- **A restart drops live-control state.** Actions held over live control are released and connections end; reconnect to the same socket.
- **Peers see drift.** A client or server you run with `onegame run` is hot; edit its sim code and peers on the old code report drift, as expected.
- **`replaySafe` is coarse.** Even a view-only edit sets it to false, and after a rude-edit restart it reads true again although the world came from edited code.

More in [Hot reload](https://recursiveai.org/onegame/docs/hot-reload/).