[Bug] Overlay installs cannot enter a world on 0.3.19: Optimum.GameContent.dll is missing from the overlay

[Pixnop]

Reported by a player (plorant) on the RiftLauncher ModDB page on 2026-10-01. Their logs are in a document they shared publicly: https://docs.google.com/document/d/1pi-qv_1OIG3AyuGQLzdbC1Y82A4YbOMToiwW73drkVc/edit

Environment

• Windows (win32), Vintage Story 1.22.7, Optimum 0.3.19
• Installed by RiftLauncher 1.7.0-beta.12 from the win-x64 overlay: the four assemblies patched in place, the game started through the vanilla executable
• No third-party mods: the server log lists game, creative, survival only

What happens

Creating a new world or entering an existing one fails every time. The same install runs fine once Optimum is removed.

The integrated server starts normally. Its log opens with Game Version: v1.22.7 (Stable) + Optimum v0.3.19, world generation runs (the Optimum worldgen pass timing lines are there), and then:

[Event] Begin game ticking...
[Notification] Entering runphase RunGame
[Notification] Server stop requested, begin shutdown sequence. Stop reason: Exception thrown by server during startup or process

That stop is the consequence, not the cause. The client is what dies. RiftLauncher's verbose log captured the game's output:

Unhandled exception. System.Exception: Coding error: Mods must not get assets before AssetsLoaded stage - do not load assets in a Start() method!
   at Vintagestory.Client.NoObf.TextureAtlasManager.LoadBitmap(ClientMain game, AssetLocationAndSource textureLoc)
   at Vintagestory.Client.NoObf.TextureAtlasManager.LoadCompositeBitmap(ClientMain game, AssetLocationAndSource compositeTextureLocation, Dictionary`2 cache)
   at Vintagestory.Client.NoObf.TextureAtlasManager.LoadBitmaps(BakedBitmap[] bitmaps)
   at Vintagestory.Client.NoObf.TextureAtlasManager.<>c__DisplayClass66_0.<PopulateTextureAtlassesFromTextures>b__0()
   at Vintagestory.API.Util.AsyncHelper.Multithreaded.OnWorkerThread(Action task)
   at Vintagestory.API.Util.AsyncHelper.Multithreaded.<>c__DisplayClass3_0.<StartWorkerThread>b__0()
   at Vintagestory.API.Common.TyronThreadPool.<>c__DisplayClass11_0.<QueueTask>b__0(Object _)
   at System.Threading.ThreadPoolWorkQueue.Dispatch()
   at System.Threading.PortableThreadPool.WorkerThread.WorkerThreadStart()
   at System.Threading.Thread.StartCallback()

What I could and could not check

• The trace is on a worker thread inside PopulateTextureAtlassesFromTextures, so it reads like texture loading running before the asset manager has flagged its assets as loaded. With no mod in the picture, the message's own advice (a mod loading assets in Start()) does not apply.
• I have not reproduced it. A Windows test on our side applied and removed Optimum 0.3.19 through the same launcher without an error, but that run did not enter a world, so it says nothing about this path.
• The same player could not build Optimum with its own installer either (their two earlier comments on the Optimum page, MSB4025 on 0.3.18 and CS0246 on 0.3.19), so there is no run of the packaged build on that machine to compare with.

Questions

1. Can the atlas population race the asset stage, on some machines only (core count, disk speed)?
2. Does an overlay-patched folder started through the vanilla executable miss anything Optimum's own launcher sets up before the game starts?

If the second is true, every RiftLauncher install of Optimum is exposed, and the fix or a guard belongs on the launcher side as well.

[Pixnop]

The trace in the report is the second failure of that session, not the first. The first one is on the integrated server, it does not depend on the machine, and it comes from the overlay: Optimum.GameContent.dll is never shipped or deployed, while the patched Mods/VSEssentials.dll needs it the moment the server reaches RunGame.

I worked from the 0.3.19 sources and from a 1.22.7 folder patched with the 0.3.19 linux-x64 overlay, with ILSpy on the vanilla and patched assemblies side by side. The win-x64 side rests on the published manifest and on the player's log. The analysis is static. The first failure is then confirmed by starting the dedicated server of that patched folder, see Reproduced below.

The overlay leaves out an assembly the patched VSEssentials references

The patched Mods/VSEssentials.dll carries an assembly reference the vanilla one does not have: Optimum.GameContent, Version=1.0.0.0, with six type references into it (OptimumMapPageCache, OptimumTerrainSampler, OptimumMapTextureArray, OptimumMapPageRenderer, OptimumMapPagePriorityQueue, PageReadResult). No assembly in the patched folder defines those types.

It comes from patches/runtime/VSEssentials/Vintagestory/GameContent/ChunkMapLayer.cs.patch, line 18: private OptimumMapPagePriorityQueue loadQueue = new OptimumMapPagePriorityQueue();. That is a field initializer, so it runs in every ChunkMapLayer constructor, client and server. Optimum.Patcher/mod-patcher.cs transplants those fields (lines 111 to 121) and the constructor (line 154). The classes are excluded from VSEssentials (sources/VSEssentials/VSEssentialsMod.csproj, lines 48 to 53) and built into Optimum.GameContent.dll by optimum-game-content/optimum-game-content.csproj. The donor gets its reference in scripts/prepare-runtime-donors.sh:277 and scripts/prepare-runtime-donors.ps1:340.

The overlay path never puts that file in the game folder. scripts/package-overlay.sh stages Optimum.Api.Contracts.dll at the root (line 102) and no other assembly of ours. The published optimum-manifest-win-x64.json and optimum-manifest-linux-x64.json for v0.3.19 have no Optimum.GameContent.dll in files[]. And GamePatcher.DeployOverlayAssets (Optimum.Bootstrap.Core/Patch/GamePatcher.cs, lines 401 to 408) copies the contracts assembly only. The standalone Windows package does ship the file (scripts/package.ps1, lines 276 and 277), and so do scripts/install-macos.sh:215 and scripts/tests/run-server-smoke.sh:92.

At runtime the chain is short. WorldMapManager.StartServerSide registers OnLvlFinalize for EnumServerRunPhase.RunGame, and OnLvlFinalize calls Activator.CreateInstance(typeof(ChunkMapLayer), api, this). The patched constructor has newobj [Optimum.GameContent]Vintagestory.GameContent.OptimumMapPagePriorityQueue::.ctor() at IL_0046, on its unconditional path, so it cannot be compiled without the assembly, and the game's AssemblyResolver.AssemblyResolve only searches the game root, Lib, Mods and the data path's Mods. ServerEventAPI.OnServerStage has no try/catch. The FileNotFoundException therefore goes up through ServerSystemModHandler.OnBeginRunGame, ServerMain.EnterRunPhase and ServerMain.Launch into the catch of ClientProgram.ServerThreadStart, the only place in the game that produces "Exception thrown by server during startup or process".

The player's server log is that failure line for line: Entering runphase RunGame at 14:51:39.974, the stop request in the same second, no Starting server threads, and a suspend warning naming worker threads that ServerMain.Launch only starts after that missing line. The stop reason is the server's own exception and not Exit request by client, so in that run the server went first. The log also shows the mods were patched: Instantiated 150 mod systems from 3 enabled mods, where vanilla 1.22.7 has 148 and the patch adds OptimumStatusModSystem and OptimumOutfitTexturePrewarmerModSystem. The exception text is missing from what was shared because that catch logs through the client logger. It will be in client-main.log.

So this is not that player's machine. Any 1.22.7 folder patched from the 0.3.19 overlay should lose its integrated server at RunGame, on Windows and on Linux. Joining a multiplayer server should fail later, on the client, since WorldMapManager.StartClientSide hooks the same OnLvlFinalize to LevelFinalize. I did not follow that path further. 0.3.18 was packaged by the same script; I did not check whether its donor already carried the reference.

Reproduced

VintagestoryServer started from a 1.22.7 folder patched with the 0.3.19 linux-x64 overlay, on a fresh data path:

[Server Notification] Entering runphase RunGame
Critical error occurred
System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation.
 ---> System.IO.FileNotFoundException: Could not load file or assembly 'Optimum.GameContent, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null'. The system cannot find the file specified.
   at Vintagestory.GameContent.ChunkMapLayer..ctor(ICoreAPI api, IWorldMapManager mapSink)
   ...
   at Vintagestory.GameContent.WorldMapManager.OnLvlFinalize()
   at Vintagestory.Server.ServerEventAPI.OnServerStage(EnumServerRunPhase runPhase)

That folder holds Optimum.Api.Contracts.dll and no Optimum.GameContent.dll, and the published 0.3.19 manifests list no such file.

The AssetsLoaded exception is the teardown racing the texture workers

AssetManager.TryGet(AssetLocation, bool) throws that message when allAssetsLoaded is false. AddExternalAssets sets the flag. Only InitAndLoadBaseAssets and UnloadExternalAssets clear it, and after startup the one client call that does is near the end of ClientMain.Dispose(). The atlas threads cannot start before AddExternalAssets has returned, because ClientSystemStartup.StartLoadingBlockShapesWhenReady and its item sibling wait for AfterAssetsLoaded. The flag was true when decoding began, and a session teardown cleared it while workers were still inside LoadBitmaps. The advice in the message about mods and Start() does not apply here.

The frames are ours. <>c__DisplayClass66_0 is the transplanted closure (vanilla 1.22.7 names its own <>c__DisplayClass65_0), from patches/VintagestoryLib/Vintagestory.Client.NoObf/TextureAtlasManager.cs.patch lines 64 to 75 and Optimum.Patcher/Program.cs:560: Environment.ProcessorCount - 1 workers per atlas where vanilla starts one. The player has 8 logical processors (server-debug.log says Starting parsing ItemTypes in 2 threads, which is Clamp(ProcessorCount / 2 - 2, 1, 8)), so seven pool workers for the block atlas and seven for the item atlas.

Those workers have no protection. AsyncHelper.Multithreaded.StartWorkerThread queues them through TyronThreadPool.QueueTask(Action, string), which has no catch, and LoadBitmaps never looks at game.disposed. The collection thread stops waiting for them as soon as game.disposed is set, and Dispose() reaches UnloadExternalAssets about three seconds later (ClientSystemStartup.Dispose waits up to 2.5 s first). Any worker still decoding then throws on a pool thread and the process dies. The collection threads are wrapped (loadBlockAtlasManagerAsync, prepareAsync), the workers are not. Vanilla has the same hole with a single worker. The patch widens it.

What tore the session down at 14:43 I cannot prove. On the loading screen the ways into ClientMain.Dispose() are GuiScreenConnectingToServer.onCancel and the disconnect and mod-error paths, and nothing reacts on its own when the integrated server dies: the screen shows "Something went awry...please check the program logs..." and then waits. A Cancel on that screen during a slow first texture load is my best guess.

The launcher log could not show more. RiftLauncher keeps the first 2,048 characters of each stderr chunk and does not record stdout, and the excerpt is exactly 2,048 characters with CRLF line ends, cut inside the second trace. More may have followed. And 14:43 and 14:50 are two attempts: the server log in the document belongs to the later one.

The two questions

Can atlas population race the asset stage? Not during startup, the ordering holds. It races teardown, and core count only changes how many workers are exposed.

Does the vanilla executable miss something Optimum.exe sets up? No environment variable and no argument. The patched assemblies read OPTIMUM_* variables for diagnostics only, and OptimumConfig creates its own ModConfig/optimum.json. What the overlay path lacks is in the package and in the checks. The file above, first. Then Optimum.exe --validate-only, which JIT-prepares every patched method (PreparePatchedMethods in Optimum.Launcher/Program.cs) and would have stopped on ChunkMapLayer::.ctor, while the overlay's RuntimeValidator reads metadata from VintagestoryLib.dll, VintagestoryAPI.dll and Vintagestory.dll only and says so in its own comment. Last, the shader compatibility scan: with no .optimum/shader-compatibility.json, OptimumConfig.LoadShaderCompatibilityReport returns with nothing disabled. Harmless on this install, wrong for a folder with mods that override shaders.

What I would change, and how to confirm

• Stage Optimum.GameContent.dll in scripts/package-overlay.sh next to the contracts assembly, copy it in GamePatcher.DeployOverlayAssets, and remove it on rollback and uninstall.
• Make RuntimeValidator resolve the non-framework references of all four patched assemblies against the game root, Lib and Mods, and fail the patch when one is missing. That check would have caught this before a player did.
• In TextureAtlasManager, let the workers survive a teardown: leave the LoadBitmaps loop once game.disposed is set, and catch in the worker lambda.
• Look at scripts/package-linux.sh (lines 258 to 265) and the Makefile deploy target (lines 96 to 104). Both copy Optimum.Api.Contracts.dll without Optimum.GameContent.dll. I did not build that package, so it may be covered somewhere I did not see.

On the player's side, client-main.log from a failed attempt should hold a [Fatal] entry naming Optimum.GameContent, with ChunkMapLayer..ctor and WorldMapManager.OnLvlFinalize in the stack. For the 14:43 run it should also show Destroying game session, waiting up to 200ms for client threads to exit and The quest as to why Fulgen crashes here. just before the end. On our side it should reproduce on any machine: patch a clean 1.22.7 with the 0.3.19 overlay, start the vanilla executable, create a world. Dropping a locally built Optimum.GameContent.dll next to Optimum.Api.Contracts.dll should be enough to get in.

A launcher cannot repair a 0.3.19 overlay install, the file is not in the archive. What it can do is refuse an overlay whose manifest does not list every assembly the patched output references.

[Zaldaryon]

PR #131 has been merged into main as 480be24. The overlay now packages and deploys Optimum.GameContent.dll, fixing the reproduced FileNotFoundException at RunGame. This fix will be included in the next Optimum release. The separate client texture atlas teardown race mentioned in the discussion was not changed or verified by this fix.