FastAssetBundleLoader

Game loads faster with large size mods by caching asset bundles.

It speeds up repeated mod startup by caching slow asset bundles into reusable files in a shared folder under Valheim's Unity persistent data path. The implementation is based on the same general approach as DiFFoZ's BepInExFasterLoadAssetBundles, but is adapted and trimmed for this Valheim-focused project. https://thunderstore.io/c/lethal-company/p/DiFFoZ/BepInEx_Faster_Load_AssetBundles_Patcher/

What it does

• It checks loaded UnityFS bundles with format version 6 or newer for caching and recompresses eligible bundles into reusable LZ4 files. Eligibility is broader than LZ4HC: the header's compression flags describe the blocks-info table, not necessarily the bundle's data blocks. Recompression that produces identical bytes is recorded so it does not repeat on later loads.
• Install FastAssetBundleLoader.dll in BepInEx/patchers. Both release archives contain the DLL under patchers/ and can be extracted into the BepInEx directory.

Cache behavior

• Cache files are stored under <Application.persistentDataPath>/FastAssetBundleLoader/cache/v1 by default. On Windows this is normally %USERPROFILE%/AppData/LocalLow/IronGate/Valheim/FastAssetBundleLoader/cache/v1.
• Profiles using the same storage root reuse cache entries for identical bundle contents. Changed bundles get separate entries. v1 is the cache format version, not the mod release version.
• In BepInEx/config/sighsorry.fast_asset_bundle_loader.cfg, leave [General] CacheRootDirectory empty for the default location, or set an absolute storage root on another drive. FastAssetBundleLoader/cache/v1 is always appended. Relative paths are not accepted.
• Old CacheDirectory settings and caches under BepInEx/cache are not used or migrated. Existing files are left untouched; the shared cache is populated as eligible bundles load.
• Only one game process can use a given cache directory at a time. If the cache is busy or inaccessible, the other instance uses original bundle loading without caching for that run. An existing .cache.lock file is normal; the open file handle, not the file's presence, determines ownership.
• To reset the shared cache, close all game instances and delete only the dedicated FastAssetBundleLoader/cache/v1 directory. Do not delete the Valheim save-data directory. Resetting the cache affects every profile sharing that location.
• Cache files are created only when eligible asset bundles are actually loaded.
• A single run may not warm every cache entry if the game is closed before the background queue finishes or if some bundles are loaded only in specific scenes. Later runs may therefore become faster.
• For a broader warm-up, enter a world instead of stopping at the lobby and keep the game running until cache activity settles. Different gameplay paths may create additional entries, so caching every installed asset bundle is not guaranteed.
• Cache could take up to few GB of your disk space according to the mods you are using. (More than 3GB in my case)
• The main measured benefit is repeated loading to the lobby. Improvements from lobby to world depend on which eligible bundles are loaded and may not be noticeable in every setup.

Configuration

Settings are stored in BepInEx/config/sighsorry.fast_asset_bundle_loader.cfg. Restart the game after editing the file; the patcher reads its configuration during startup.

The Valheim launch argument --ignore-space-check bypasses the free-disk-space threshold for that process. The argument is case-insensitive and does not change the saved configuration.

Building and packaging

FastAssetBundleLoader.sln builds FastAssetBundleLoader.csproj, producing bin/Release/netstandard2.1/FastAssetBundleLoader.dll. Use a .NET SDK and a Valheim installation containing BepInEx and the game's managed assemblies. Run these PowerShell commands from the repository root:

# Build without installing the DLL or creating release packages.
dotnet build .\FastAssetBundleLoader.sln -c Release

# Specify a nonstandard game installation.
dotnet build .\FastAssetBundleLoader.sln -c Release "-p:GamePath=D:\SteamLibrary\steamapps\common\Valheim"

The project derives its BepInEx and managed-assembly reference paths from the selected game installation. -p:BepInExPath=... and -p:CorlibPath=... can override those paths explicitly.

Game deployment and package creation are separate opt-in operations. Close the game before replacing an installed DLL.

# Copy the DLL and its PDB, when present, into BepInEx/patchers.
dotnet build .\FastAssetBundleLoader.sln -c Release -p:DeployToGame=true

# On Windows, update the manifest version and create both release ZIPs.
dotnet build .\FastAssetBundleLoader.sln -c Release -p:CreatePackages=true

DeployToGame and CreatePackages default to false. Package creation runs only for Windows Release builds and does not deploy to the game unless DeployToGame=true is also supplied. It updates Thunderstore/manifest.json to the assembly version and overwrites the matching ZIPs under Thunderstore and Nexus. Both archives contain patchers/FastAssetBundleLoader.dll; Thunderstore also contains the README, changelog, manifest, and icon at the archive root.

Verification

The managed tests link production bundle-header, hashing, file, and metadata code with a logger stub. They require a .NET 8 runtime and can run without Valheim or Unity:

dotnet test .\Tests\FastAssetBundleLoader.Tests.csproj -c Release

The PowerShell 7 boundary checks inspect the built loader and exercise managed paths using the installed game and BepInEx assemblies. Build the loader in the same configuration first:

dotnet build .\FastAssetBundleLoader.sln -c Release
pwsh -NoProfile -File .\Tests\Verify-RuntimeHooks.ps1 -Configuration Release
pwsh -NoProfile -File .\Tests\Verify-CacheReservation.ps1 -Configuration Release

For a nonstandard installation, pass -p:GamePath=... to the build and -GamePath ... to each verification script. These checks do not launch Valheim, install Harmony detours, or execute Unity native asset loading. Actual game verification still requires cold-cache and warm-cache launches, mod combinations, and client, host, and dedicated-server runs.

Other mods to run the game faster

• StartupAccelerator
• LocalizationCache

I have tested with following combination to measure loading time.

• Modpack only = 246s
• FastAssetBundleLoader + Modpack = 170s
• StartupAccelerator + Modpack = 202s
• LocalizationCache + Modpack = 218s
• FastAssetBundleLoader + LocalizationCache + Modpack = 145s
• FastAssetBundleLoader + StartupAccelerator + Modpack = 127s

StartupAccelerator is faster but some mods might not work properly with it.

Changelog

1.0.7

• Verified the asset-bundle loading and recompression contracts against Valheim 1.0.7 on both the Windows client and dedicated server.
• Preserve an earlier HarmonyX patch's decision to skip the original file-based bundle load without inspecting, hashing, queueing, or redirecting that file.
• Updated the required BepInExPack Valheim dependency to 5.4.2350.
• Kept the existing configuration keys, shared-cache path, metadata format, CRC handling, and offset behavior unchanged.

1.0.6

• Maintenance release: rebuilt and repackaged the 1.0.5 implementation as version 1.0.6.
• No runtime behavior, configuration, or cache-format changes from 1.0.5.

1.0.5

• Preserve an earlier HarmonyX patch's result when it has already skipped the original stream or memory bundle load.
• Recheck cache entries after reserving work so a bundle cached or marked to skip by a just-finished job is not queued again.
• Reject malformed UnityFS headers whose compressed blocks-info table cannot fit inside the declared bundle size.
• Simplified cache redirection helpers while preserving separate synchronous and asynchronous fallback behavior.
• Added managed regression tests and runtime-boundary checks, and documented configuration, restart requirements, and build commands.
• Release package creation now requires CreatePackages=true; normal Release builds no longer update the manifest or overwrite release archives. Game deployment remains opt-in.

1.0.4

• Moved the default cache to <Application.persistentDataPath>/FastAssetBundleLoader/cache/v1 so mod-manager profiles can reuse cached bundles with identical contents. On Windows this is normally %USERPROFILE%/AppData/LocalLow/IronGate/Valheim/FastAssetBundleLoader/cache/v1.
• Added CacheRootDirectory to optionally select an absolute storage root. The dedicated FastAssetBundleLoader/cache/v1 directory is appended; v1 tracks the cache format independently of the mod version.
• Added process-level cache locking. If another game instance owns the cache, this instance loads original bundles without caching for that run.
• Removed legacy cache configuration and metadata support. Old caches under BepInEx/cache are left untouched and are not migrated; the shared cache is created as eligible bundles load.
• Updated the README with shared-cache configuration and reset instructions. Close all game instances before deleting the dedicated shared cache directory; this affects every profile using it.

1.0.3

• Moved FastAssetBundleLoader.dll into the patchers/ directory in both Thunderstore and Nexus archives so they can be extracted directly into the BepInEx directory.

1.0.2

• Cache regeneration is recommended after updating: close the game, delete only BepInEx/cache/ValheimFasterLoadAssetBundles, and let eligible bundles rebuild as they are loaded.
• The first run may not warm every cache entry. Enter a world and allow cache activity to settle; later runs or different gameplay paths may create additional entries.

1.0.1

• Refactored the asset bundle cache pipeline and runtime hooks for safer cache reuse.
• Improved cache metadata validation, cleanup, and failure handling.
• Clarified cache warm-up behavior, including when entering a world or additional runs may create more entries.
• Added reproducible standalone Thunderstore and Nexus release packaging.

1.0.0

• Initial release.