Skip to content

Basic hot reload support for mod development #160

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jakobhellermann wants to merge 13 commits into
base: master
Choose a base branch
from
Open

Basic hot reload support for mod development #160

Show file tree
Hide file tree
Changes from 12 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
41c9f54
build: copy files to <CopyDir> if set
jakobhellermann Jun 25, 2025
a8d1c21
hot reload: load mods from `ModsHotReload` folder
jakobhellermann Jul 7, 2025
3d45283
hot reload: just reload mods from regular mods folder
jakobhellermann Jul 7, 2025
7f96f2c
hot reload: add mod directories to hot reload search path
jakobhellermann Jul 7, 2025
82f5fb1
hot reload: fix out of order event processing and idempotence
jakobhellermann Jul 7, 2025
723c58e
hot reload: read debug symbols
jakobhellermann Jul 7, 2025
9e4a3e4
hot reload: silence warning and hot reload only after startup
jakobhellermann Jul 7, 2025
9ef2793
hot reload: handle events in unity update thread
jakobhellermann Jul 7, 2025
0325ec9
hot reload: make configurable via `EnableHotReload` setting
jakobhellermann Jul 7, 2025
325e81c
Fix review comment (string.IsNullOrEmpty)
jakobhellermann Aug 30, 2025
48666fd
fix formatting
jakobhellermann Aug 30, 2025
0656490
add `#region` section around hot reloading code
jakobhellermann Aug 30, 2025
8443231
Merge branch 'master' into HEAD
jakobhellermann Aug 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions Assembly-CSharp/Assembly-CSharp.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,11 @@

<PropertyGroup>
<OutputDir>$(SolutionDir)/OutputFinal</OutputDir>
<!-- todo macOS -->
<GamePath Condition="'$(OS)' == 'Windows_NT'">C:/Program Files (x86)/Steam/steamapps/common/Hollow Knight</GamePath>

@fifty-six fifty-six Aug 28, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd ideally give an env variable for this because these paths aren't universal (external drive steam library, flatpak, etc). Or Directory.Build.props. Can still default if it's unset but then people with less standard paths don't have to mess with the checked in csproj

@jakobhellermann jakobhellermann Aug 30, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I understand correctly, Directory.Build.Props automatically overrides the solution properties, so putting

<Project>
    <PropertyGroup>
        <GamePath>D:/Games/Hollow Knight</GamePath>
    </PropertyGroup>
</Project>

next to the solution will just work.

Of course you have to know that this exists. I guess you could leave a comment mentioning it here? Or have a Directory.Build.Props.example checked into git.

<GamePath Condition="'$(OS)' != 'Windows_NT'">$(HOME)/.local/share/Steam/steamapps/common/Hollow Knight</GamePath>
<CopyDir>$(GamePath)/hollow_knight_Data/Managed</CopyDir>

<Mono Condition="$(OS) == WINDOWS_NT" />
<Mono Condition="$(OS) != WINDOWS_NT">mono</Mono>
</PropertyGroup>
Expand Down Expand Up @@ -78,6 +83,13 @@
<Copy SourceFiles="@(Dependencies)" DestinationFolder="$(OutputDir)" />
</Target>

<Target Name="CopyOutputAfterFinal" AfterTargets="OutputFinal" Condition="'$(CopyDir)' != ''">
<ItemGroup>
<OutputFiles Include="$(OutputDir)\**\*" />
</ItemGroup>
<Copy SourceFiles="@(OutputFiles)" DestinationFolder="$(CopyDir)" />
</Target>

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
<DebugType>full</DebugType>
<DocumentationFile>bin\$(Configuration)\Assembly-CSharp.mm.xml</DocumentationFile>
Expand Down
15 changes: 9 additions & 6 deletions Assembly-CSharp/Mod.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,13 +110,16 @@ private string GetGlobalSettingsPath()
string globalSettingsFileName = $"{GetType().Name}.GlobalSettings.json";

string location = GetType().Assembly.Location;
string directory = Path.GetDirectoryName(location);
string globalSettingsOverride = Path.Combine(directory, globalSettingsFileName);
if (string.IsNullOrEmpty(location))
{ // TODO: not set while hot reloading

@jakobhellermann jakobhellermann Aug 30, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is kind of annoying. If I'm understanding this feature, if you have a DebugMod.GlobalSettings.json in GameDir/Managed/Mods/DebugMod/, then it will be loaded with priority over SavesDir/DebugMod.GlobalSettings.json.

Of course, while reloading, we can't look up the path of the assembly. I think lumafly puts each mod into a directory of the same name, but if you manually copy MyCoolFolder/DebugMod.dll into your Managed, then hot reloading has no idea about this settings override file.

Maybe this is fine for a niche use case in a development feature.

@BadMagic100 BadMagic100 Aug 30, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Settings overrides are generally intended for mod pack distribution, personally I don't mind if we just say this isn't supported with hot reloading but I have no decision power

string directory = Path.GetDirectoryName(location);
string globalSettingsOverride = Path.Combine(directory, globalSettingsFileName);

if (File.Exists(globalSettingsOverride))
{
Log("Overriding Global Settings path with Mod directory");
return globalSettingsOverride;
if (File.Exists(globalSettingsOverride))
{
Log("Overriding Global Settings path with Mod directory");
return globalSettingsOverride;
}
}

return Path.Combine(Application.persistentDataPath, globalSettingsFileName);
Expand Down
18 changes: 18 additions & 0 deletions Assembly-CSharp/ModHooksGlobalSettings.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,24 @@ public class ModHooksGlobalSettings
/// </summary>
public int PreloadBatchSize = 5;

/// <summary>
/// When enabled, listens for filesystem changes to mod DLLs.
/// On modification, mods will be unloaded, and the new copy of the assembly gets loaded as well.
/// <para><b>Limitations:</b></para>
/// <list type="bullet">
/// <item><description>
/// The old assembly does not get unloaded. If you have created any unity game objects or components,

@BadMagic100 BadMagic100 Jul 7, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems rough, not because of needing to destroy stuff in unload but because it makes a reload costly.

@jakobhellermann jakobhellermann Jul 8, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Costly compared to what?

The regular use case should be unchanged, even with EnableHotReload enabled, and only subsequent changes will incur the extra assembly overhead.
And I think even that overhead is not too bad, when developing with scriptengine in nine sols I rarely had to restart the game because it became laggy after too many hot reload cycles.

/// make sure to Destroy them in the mod's Unload function.
/// </description></item>k
/// <item><description>
/// Dependencies of mods cannot be hot reloaded. When you modify a dependency DLL, no change will be made to the mod depending on it.
/// </description></item>
/// <item><description>
/// <c>Assembly.location</c> will return an empty string for hot-reloaded mods
/// </description></item>
/// </list>
/// </summary>
public bool EnableHotReload = false;

/// <summary>
/// Maximum number of days to preserve modlogs for.
Expand Down
Loading