Hotload Performance

<cat>Code.Editor</cat>
<title>Hotload Performance</title>

Here's some tips in case hotloading code changes to your addon is getting too slow.

Our hotloading system needs to go through every object in memory, replacing any from the old DLL with one from the new DLL. This can get slow if you've got huge data structures with millions of objects.

Some things to keep in mind:
* Arrays of primitive types (`byte`, `int`, etc) survive the hotload without getting processed, which is very quick
* Arrays of custom struct types that only contain value types can be copied across very quickly too
* Arrays of any other custom types will have each item processed one-by-one, which can be much slower

# Find out what's slow

You can find out which objects are the slowest to replace by setting this console variable:

```
hotload_log 2
```

This will log a bunch of timing info to the console after each hotload, for both server and client DLLs.

The output will look like this:

```
Server Hotload processed 3,272,107 instances in 3.65s
----------------------------------------------------------------------------------------
| MinimalExample.MinimalPlayer.Example                            | 1000000 | 1321.7ms |
|   [StaticField] Sandbox.InteropSystem::Address                  | 1000000 | 1321.7ms |
----------------------------------------------------------------------------------------
| MinimalExample.MinimalPlayer.Example[]                          | 2048000 |  859.6ms |
|   [StaticField] Sandbox.InteropSystem::Address                  | 1024000 |  793.7ms |
|   [StaticField] MinimalExample.MinimalPlayer::_task             | 1024000 |   66.0ms |
----------------------------------------------------------------------------------------
| Sandbox.Prop                                                    |     644 |  120.2ms |
|   [StaticField] Sandbox.InteropSystem::Address                  |     644 |  120.2ms |
----------------------------------------------------------------------------------------
...
```

There will be a table for each type encountered, with the second column counting how many instances were seen, and the last column the time taken to process all the instances. The types are listed in descending order of time taken. You can ignore the rows starting with `[StaticField]` for now, they describe how the instances were found.

From the example above, we can see processing `MinimalExample.MinimalPlayer.Example` instances is taking the bulk of the hotload time.

# Using SkipHotload

When you've found what types are slow to process, you can tell the hotloading system to just skip over fields and properties containing instances of those types.

When a field or property is skipped, it will be left uninitialized after the hotload. That means `null` for reference types, or `default(T)` for value types.

Continuing with the example above, we've worked out a property `BigList` is holding all the instances that hotload is taking ages to process. We can skip that property with the `[SkipHotload]` attribute:

```
[SkipHotload]
public List<List<Example>> BigList { get; set; }
```

Now hotloading takes much less time:

```
Server Hotload processed 231,741 instances in 1.12s
---------------------------------------------------------------------------------------------
| Sandbox.Prop                                                            |   644 | 108.0ms |
|   [StaticField] Sandbox.InteropSystem::Address                          |   644 | 108.0ms |
---------------------------------------------------------------------------------------------
...
```

However that property is now `null` after hotload, so skipping is only useful for data structures that you can generate again (and more quickly than it would take hotload to process). For example, your type might contain some raw data in a `byte` array that doesn't need to be skipped, and also some larger uncompressed representation of the same data for live use that you can regenerate after hotload is done.

# Hotload callback interfaces

For cases where you want to repopulate skipped fields, the containing type can implement `IHotloadManaged`. This has two methods that will be called by the hotloading system: `IHotloadManaged.Destroyed` is called on the old instance, and `IHotloadManaged.Created` is called on the new one that replaces it.

In `Destroyed` you can populate a `state` dictionary with values to bring over to the new instance, which get passed to `Created`:

```
void IHotloadManaged.Destroyed(Dictionary<string, object> state)
{
	state["Example"] = BigList.Select(x => x.Count).ToArray();
}

void IHotloadManaged.Created(IReadOnlyDictionary<string, object> state)
{
    var example = (int[])state["Example"];

    // ... repopulate big list ...
}
```

You'll want to only store stuff in the dictionary that is quick for hotload to process, like arrays of primitive types. 

# Fast-path hotloads

As of 13/04/2023, if you only change method bodies the game will attempt a much faster hotload. This should be most useful when tweaking code handling visuals or UI. Not all changes are supported to start with, so it might still have to fall back to the old slower hotload in some cases.

If you start encountering errors that could be related to this feature, you can disable it with this console variable:

```
hotload_fast 0
```

Please also tell us about what went wrong in an issue here: https://github.com/sboxgame/issues/issues
It'll be super helpful to know what change you made when the problem occurred.

Also please make sure to check if anyone else has already made an issue!

Hotload Performance

Account Management

Special Pages

Wiki List

S&box Wiki