RimWorld Wiki - User contributions [en]

Modding Tutorials/Asset Bundles

2026-06-25T23:08:19Z

CryptikLemur: Adding information on texture load priority

{{DISPLAYTITLE:Asset Bundles}}

{{BackToTutorials}}

{{:Modding_Tutorials/Under_Review}}

This tutorial explains what asset bundles are, why you might want them, and how they compare to the two other ways RimWorld can load custom art: loose textures and DDS files. It starts from zero, so you do not need to know anything about Unity going in. The later sections branch into the actual build process and then into the deeper stuff: shaders, sounds, fonts, and the things that go wrong.

== What is an asset bundle? ==

An asset bundle is a single file that holds a bunch of Unity assets already packed in the format the engine wants. RimWorld runs on Unity, and Unity has its own internal way of storing textures, meshes, shaders, audio, and so on. A loose PNG sitting in your mod's <code>Textures/</code> folder is not in that format yet, so the game has to convert it before it can use it.

A bundle is that conversion done ahead of time, saved to disk, and handed to the engine in one piece. The rest of this page is mostly consequences of that.

== Why would I care? ==

Two reasons, mostly:

'''Load time.''' When you ship loose PNGs, RimWorld converts every single one while the game boots (more on this in the next section). For a small mod you will never notice. For a mod with hundreds or thousands of textures, that conversion adds up, and it is part of why a heavily-modded load screen sits there for a while. A bundle skips the conversion because the work is already done.

'''Everything that is not a texture.''' Loose files only really work for textures and sounds. If you want to ship a custom shader, a custom font, a custom mesh, or anything else Unity-shaped, a bundle is the normal way to get it into the game. There is no <code>Shaders/</code> folder you can just drop a file into.

If your mod is XML and a handful of textures, you probably do not need bundles at all. If your mod is large, or it needs a custom shader or font, you do.

As of 1.6, bundles are the encouraged path for anything beyond a small loose-texture mod. The engine grew real first-class support for them: it loads them for you, swaps the right one per operating system, and serves their contents through the same content lookup you already use. Earlier versions made you wire all of that up by hand, which is why older tutorials look more involved than this one. On 1.6+ most of the friction is gone.

== Loose textures vs DDS vs asset bundles ==

All three of these get a texture onto the screen. They differ in '''when''' the work happens and '''what''' they can carry. Mix those two questions up and the whole topic gets confusing fast.

=== Loose textures (PNG) ===

You put a <code>.png</code> in your mod's <code>Textures/</code> folder and reference it by path. Simplest possible setup, and what almost every tutorial starts with. (The [[Modding_Tutorials/Textures|Textures]] page covers the path rules and texture conventions in full; this page assumes you have that down.)

RimWorld does not render your PNG directly. On load it converts the PNG into a compressed GPU texture (the same family of formats DDS uses) and caches the result. So the PNG is a source file, not the thing the GPU actually draws. That conversion is cheap for one texture and not cheap for a thousand.

* '''Pro:''' dead simple, easy to edit, easy to diff, no tooling.
* '''Con:''' the game pays a conversion cost on load, and you cannot ship anything other than textures and sounds this way.

=== DDS textures ===

A <code>.dds</code> file is a texture that is ''already'' in a GPU-ready compressed format. If you drop a DDS next to where the PNG would go, RimWorld uses it directly and skips the conversion step entirely.

So the loose-vs-DDS question is mostly about that conversion cost, not about how the final image looks. A correctly-made DDS and the game's own PNG conversion land in roughly the same place visually. What DDS buys you is a faster load and no first-load hitch, because the expensive part already happened on your machine when you made the file.

The catch is you have to ''make'' the DDS, and if you make it wrong (wrong compression, no mipmaps, wrong color space) it can look worse than just letting the game convert the PNG. It is a real win for large texture sets, and a footgun for people who do not know what BC7 or mipmaps are.

* '''Pro:''' no runtime conversion, faster load, no first-load stutter for that texture.
* '''Con:''' you have to generate it correctly, harder to edit after the fact, much larger on disk than the source PNGs, and still textures-only.

=== Asset bundles ===

A bundle is the next step up. It is one file that can hold many textures (already in GPU format, like DDS, so same load-time win) ''plus'' meshes, shaders, fonts, and audio. Instead of hundreds of loose files converted one by one, the engine loads one bundle and everything inside is ready to go.

The trade is that a bundle is opaque. You cannot open it in an image editor and tweak a pixel. You rebuild it from your source assets, which means you keep your editable PNGs and Unity sources somewhere and treat the bundle as a build output, the same way you treat a compiled DLL.

* '''Pro:''' fastest load for large asset sets, one file instead of thousands, and it is the only option for shaders, fonts, and custom meshes.
* '''Con:''' you need a build step and the Unity tooling to produce it, and the output is not hand-editable.

=== Quick comparison ===

{| class="wikitable"
! Approach !! Load cost !! Disk size !! Can carry !! Editable after build? !! Good for
|-
| Loose PNG || Converted every load || Small || Textures, sounds || Yes || Small mods, prototyping
|-
| DDS || None (pre-converted) || Large || Textures || Painful || Large texture sets
|-
| Asset bundle || None (pre-converted) || Smallest || Textures, meshes, shaders, fonts, audio || No (rebuild from source) || Large mods, anything non-texture
|}

That disk-size column is worth some real numbers. Take one texture set of around 960 files and store it all three ways:

* As loose PNGs: about 40 MB.
* Converted to DDS: about 230 MB. The conversion skips the runtime work but blows up the size on disk.
* Packed into a single asset bundle: about 28 MB.

So DDS is the ''largest'' on disk, not the smallest. It trades space for skipping the load-time conversion. The bundle gets that same load-time win and still ends up the smallest of the three, because it is compressed into one file. (Numbers from a comparison shared in the [https://discord.com/channels/214523379766525963/632790371256238120/1405733585268375643 RimWorld modding Discord]; your exact figures will vary with the texture set and compression settings.)

== The workflow, in plain terms ==

Before any code or folder layout, here is what building a bundle actually looks like from a height:

# You keep your real, editable source assets (PNGs, Unity materials, shader files, font files) in a Unity project.
# In that Unity project you tag each asset with a bundle name, then tell Unity to build the bundles.
# Unity spits out the bundle files.
# You ship those bundle files inside your RimWorld mod.
# At game load, RimWorld finds the bundle on its own and serves its contents through the normal content lookup (1.6 does the loading for you; textures and sounds resolve by their existing path, while shaders and fonts you still fetch by name in code).

That is the loop. You edit in Unity, build, copy the output into your mod, and the game picks it up. The first time through it feels like a lot of ceremony for a texture. Once it is set up, adding a new asset is just "drop it in the Unity project, rebuild, copy."

You do not have to do every step by hand. The next section covers that before the build details, so you can go find a tool first if you would rather not set this up yourself.

== Before we get started: Do I actually have to do everything below? ==

No. Setting up the Unity project, writing the build script, and juggling per-platform bundles is fiddly enough that several modders have written tools to do it for you. They wrap the whole thing, handle the multi-platform build, and spit out ready-to-ship bundles without you babysitting the Unity editor. If that sounds like what you want, you can stop here and go find one; the rest of this page is for when you want to understand what those tools are doing or build it yourself.

This tutorial does not point at any specific one on purpose, since they come and go and get superseded. A search on Google or GitHub for RimWorld asset bundle tooling turns them up, and the modding Discord communities are usually the fastest place to find out which one people are actually using right now and which one is abandoned. Ask there before sinking an afternoon into a tool that got replaced six months ago.

== Branch: the real build steps ==

If you want the actual mechanics, here they are. First, install the right Unity editor. This matters more than anything else on this page: a bundle built on the wrong Unity version may silently fail to load. RimWorld 1.6 runs on '''Unity 2022.3.35f1''', so install exactly that version through the Unity Hub (under "Add" you can pick a specific archived version, or grab it from the Unity download archive). Build your bundles in 2022.3.35f1 and they line up with what the game expects. If RimWorld updates to a new Unity version down the line, you rebuild against the new one.

=== Folder layout ===

Inside your mod, bundles usually live somewhere like:

MyMod/
About/
Defs/
Textures/
AssetBundles/
mymod_assets_win
mymod_assets_mac
mymod_assets_linux

The bundle file itself has no extension. You name it whatever you tagged it in Unity, with the OS suffix on the end (see the deep dive for why the three files). There is no <code>.dll</code> required to use a bundle: a pure XML-and-textures mod can ship a bundle and never write a line of C#, because the game loads it and serves its contents automatically.

=== Tagging and building in Unity ===

In the Unity project, select an asset, and at the bottom of the Inspector there is an AssetBundle dropdown. Assign a bundle name there. Everything sharing that name builds into the same bundle.

Then you need a small editor script to actually trigger the build, because Unity does not expose bundle building in the default menus.

The bare version is just one <code>BuildPipeline.BuildAssetBundles</code> call. It works, but it ships your textures with whatever import settings they happened to have, which is usually uncompressed and wasteful. Controlling how each texture imports before it gets packed is what actually shrinks the disk and memory footprint, so the script below does two things: it walks your textures and sets sane import settings on each, then builds.

<syntaxhighlight lang="csharp">
using UnityEditor;
using UnityEngine;
using System.IO;

public static class BundleBuilder
{
[MenuItem("Assets/Build AssetBundles")]
static void Build()
{
// First pass: set good import settings on every texture in the project.
foreach (string guid in AssetDatabase.FindAssets("t:Texture2D"))
{
string assetPath = AssetDatabase.GUIDToAssetPath(guid);
if (AssetImporter.GetAtPath(assetPath) is not TextureImporter tex) continue;

string lower = assetPath.ToLower();
bool isTerrain = lower.Contains("/terrain/");
bool isMask = lower.Contains("_mask");
bool isNormal = lower.Contains("_normal");

// GUI type suits RimWorld's flat 2D art and avoids Unity generating sprite sub-assets.
tex.textureType = isNormal ? TextureImporterType.NormalMap : TextureImporterType.GUI;
tex.alphaIsTransparency = true;

// Mask and normal maps hold raw data, not color, so they must stay linear (sRGB off).
tex.sRGBTexture = !isMask && !isNormal;

// Terrain tiles repeat across the ground; everything else should clamp at its edges.
tex.wrapMode = isTerrain ? TextureWrapMode.Repeat : TextureWrapMode.Clamp;
tex.anisoLevel = isTerrain ? 8 : 1;

tex.filterMode = FilterMode.Trilinear;
tex.mipmapEnabled = true;

// BC7 high-quality compression: small on disk and in VRAM, good for hand-painted art.
tex.SetPlatformTextureSettings(new TextureImporterPlatformSettings
{
name = "Standalone",
overridden = true,
format = TextureImporterFormat.BC7,
maxTextureSize = 4096,
textureCompression = TextureImporterCompression.CompressedHQ
});

tex.SaveAndReimport();
}

// Second pass: build the bundles.
string output = "Assets/BuiltBundles";
Directory.CreateDirectory(output);
BuildPipeline.BuildAssetBundles(
output,
BuildAssetBundleOptions.ChunkBasedCompression, // LZ4
BuildTarget.StandaloneWindows64
);
}
}
</syntaxhighlight>

A few notes on what that import pass is doing:

* '''BC7 + CompressedHQ''' is the compression that gets you the small disk and VRAM footprint. Without it the texture sits in memory uncompressed.
* '''sRGB off for masks and normal maps.''' A stuff-color mask or a normal map stores data, not a picture, so it must be read as linear. Leaving sRGB on silently corrupts it. The script keys off <code>_mask</code> and <code>_normal</code> in the filename, so name your files accordingly.
* '''Terrain repeats, everything else clamps.''' Terrain tiles need <code>Repeat</code> wrap so they tile seamlessly across the ground; a regular sprite wants <code>Clamp</code> so its edges do not bleed. The script keys off a <code>/Terrain/</code> folder in the path.
* '''Mipmaps on''' so the texture does not shimmer when the camera zooms out.

This is a trimmed-down version of what dedicated bundle-building tools do; they also handle audio compression, font atlas generation, and per-bundle include/exclude rules. The texture settings above are the ones worth knowing by hand. Run the menu item, Unity reimports the textures and writes the bundles to the output folder, and you copy the ones you care about into your mod's <code>AssetBundles/</code> folder.

=== Loading the bundle in your mod ===

In 1.6 you do not load the bundle yourself at all, which catches people off guard since the older docs make it look involved. RimWorld scans every active mod's <code>AssetBundles/</code> folder on startup, loads what it finds, and keeps the loaded bundles on the mod. You do not write <code>AssetBundle.LoadFromFile</code>, you do not call <code>LoadAsset</code>, you do not run anything in a static constructor.

The game's normal content lookup also checks bundles for you. When you ask for a texture the usual way, with <code>ContentFinder<Texture2D>.Get("Things/Item/MyThing")</code>, RimWorld walks three places in order: first it looks for a loose file at that path in any active mod, then it falls back to the base game's built-in resources, and only if both miss does it look inside your loaded bundles at the matching path. Same call, same path string, whether the texture is loose or bundled. The asset just has to live at the same path inside the bundle that the loose file would have used (so an asset packed at <code>Textures/Things/Item/MyThing</code> resolves for the path above).

The practical upshot: for textures and sounds you do not change a single line of your mod's code to switch from loose to bundled. You reference them by path like you always did. You only build a bundle, drop it in the folder, and the game finds the contents.

'''A bundle cannot overwrite or retexture a base game texture.''' Because bundles are checked last, after the base game's own resources, the vanilla texture is always found first and your bundled version at the same path is never reached. Bundles are for adding new content, not replacing what ships with the game. If you want to retexture vanilla art, you still do it the old way: a loose file at the matching path (which is checked before the base resources), or a def or <code>texPath</code> redirect that points the vanilla thing at your own texture. The same goes for sounds.

The exception is shaders. The content lookup skips the loose-file step for shaders entirely (there is no loose-shader path), so a shader is only ever found inside a bundle. <code>ContentFinder<Shader>.Get("MyShaderName")</code> works, but only because the shader is in a bundle for it to find.

== Branch: the deep dive ==

Most of this only comes up once you are shipping a shader or a font. A small texture-only mod can skip the whole section.

=== Shaders and the cross-platform problem ===

A compiled shader is platform-specific, which is why a lot of mods end up shipping multiple bundles. A shader built for DirectX (Windows) is not the same bytes as one built for Metal (Mac) or Vulkan/OpenGL (Linux). If you build one bundle on Windows and ship it, your shader works on Windows and quietly fails on Mac and Linux, usually showing up as bright magenta where the texture should be.

The fix is to build a bundle per platform, and 1.6 makes this almost free because the game does the picking for you. Name your bundle files with the suffix the game looks for:

* <code>mymod_assets_win</code> loads on Windows
* <code>mymod_assets_mac</code> loads on Mac
* <code>mymod_assets_linux</code> loads on Linux

The game checks the running platform and loads only the matching one. A bundle with no suffix at all loads on every platform, which is fine for textures and meshes that do not care, but not safe for shaders. So you build the same assets three times in Unity with different <code>BuildTarget</code> values (<code>StandaloneWindows64</code>, <code>StandaloneOSX</code>, <code>StandaloneLinux64</code>), give each the right suffix, and ship all three. You write no platform-detection code yourself.

If you have ever installed a mod that worked fine for everyone except the Mac and Linux players who saw pink everywhere, this is almost always why.

=== Sounds ===

Audio can go in a bundle as an <code>AudioClip</code>, and for a lot of sounds it is fine and saves you the loose-file management. RimWorld can also load loose audio through its normal sound def system, so for ordinary sound effects you often do not need a bundle at all. Where bundles help is when you want the audio packed with everything else, or when you are loading clips directly from code rather than through a SoundDef.

=== Fonts ===

If you want a custom font in your UI, a bundle is the way. You import the font into Unity, build it into a bundle, load it as a <code>Font</code>, and assign it where you draw text. There is no loose-font path in RimWorld at all, so here the bundle is not a speed-up, it is the only way in.

=== Meshes ===

Same story as fonts. Custom 3D meshes (not the usual flat sprites, actual geometry) come in through a bundle as a <code>Mesh</code>. Most RimWorld mods never touch this, but if you are doing something with real geometry it is here.

=== Compression and a couple of gotchas ===

A few things worth knowing before you spend an afternoon confused:

* '''Unity version mismatch.''' A bundle built on a different Unity version than the game uses may refuse to load, often with no clear error, the asset just comes back null. Build on Unity 2022.3.35f1 for RimWorld 1.6. This is the single most common reason a bundle that worked in the editor does nothing in-game.
* '''Bundle file compression.''' This is how the bundle file is packed on disk, separate from texture compression below. Bundles can be built uncompressed, LZ4, or LZMA. LZ4 is the usual sweet spot: small enough, and it does not stall on load the way LZMA can. <code>BuildAssetBundleOptions.ChunkBasedCompression</code> gives you LZ4.
* '''In-memory texture compression and the white-outline bug.''' Loose textures are compressed in memory once loaded, and that compression is what produces the faint white halo people sometimes see around a sprite (the art program threw away color data in fully transparent pixels). A bundle lets you turn that in-memory compression off for its textures, which sidesteps the halo without the usual workaround of padding the outline. The [[Modding_Tutorials/Textures|Textures]] page documents the bug and the loose-texture fix.
* '''Shader stripping.''' Unity sometimes strips shader variants it thinks are unused during the build, and then your shader looks wrong at runtime because the variant you needed got cut. If a shader misbehaves only in the built bundle but works in the editor, this is a likely suspect.
* '''Color space.''' If your textures look washed out or too dark coming out of a bundle, check that the import settings and color space match what the game expects. This is the same class of problem that makes a hand-rolled DDS look wrong.

== Summary ==

* Loose PNG: simplest, but converted on every load and limited to textures and sounds.
* DDS: a texture pre-converted to GPU format, so it skips the load-time conversion. Same final look, faster load, but you have to make it right, and it lands much larger on disk than the source PNGs.
* Asset bundle: one pre-packed file that carries textures, meshes, shaders, fonts, and audio. The fastest option for big mods and the only option for shaders, fonts, and custom meshes.

If your mod is small, stay loose. If it is large or needs anything Unity-shaped beyond a texture, learn bundles, and on 1.6+ that is the encouraged path anyway since the engine does the loading and per-OS swapping for you. And if you are shipping a shader, build one bundle per platform with the right suffix, or your Mac and Linux players get magenta.

[[Category:Modding]]
[[Category:Modding tutorials]]

Modding Tutorials/Asset Bundles

2026-06-25T22:55:13Z

CryptikLemur: Adding summary info about DDS size

{{DISPLAYTITLE:Asset Bundles}}

{{BackToTutorials}}

This tutorial explains what asset bundles are, why you might want them, and how they compare to the two other ways RimWorld can load custom art: loose textures and DDS files. It starts from zero, so you do not need to know anything about Unity going in. The later sections branch into the actual build process and then into the deeper stuff: shaders, sounds, fonts, and the things that go wrong.

== What is an asset bundle? ==

An asset bundle is a single file that holds a bunch of Unity assets already packed in the format the engine wants. RimWorld runs on Unity, and Unity has its own internal way of storing textures, meshes, shaders, audio, and so on. A loose PNG sitting in your mod's <code>Textures/</code> folder is not in that format yet, so the game has to convert it before it can use it.

A bundle is that conversion done ahead of time, saved to disk, and handed to the engine in one piece. The rest of this page is mostly consequences of that.

== Why would I care? ==

Two reasons, mostly:

'''Load time.''' When you ship loose PNGs, RimWorld converts every single one while the game boots (more on this in the next section). For a small mod you will never notice. For a mod with hundreds or thousands of textures, that conversion adds up, and it is part of why a heavily-modded load screen sits there for a while. A bundle skips the conversion because the work is already done.

'''Everything that is not a texture.''' Loose files only really work for textures and sounds. If you want to ship a custom shader, a custom font, a custom mesh, or anything else Unity-shaped, a bundle is the normal way to get it into the game. There is no <code>Shaders/</code> folder you can just drop a file into.

If your mod is XML and a handful of textures, you probably do not need bundles at all. If your mod is large, or it needs a custom shader or font, you do.

As of 1.6, bundles are the encouraged path for anything beyond a small loose-texture mod. The engine grew real first-class support for them: it loads them for you, swaps the right one per operating system, and serves their contents through the same content lookup you already use. Earlier versions made you wire all of that up by hand, which is why older tutorials look more involved than this one. On 1.6+ most of the friction is gone.

== Loose textures vs DDS vs asset bundles ==

All three of these get a texture onto the screen. They differ in '''when''' the work happens and '''what''' they can carry. Mix those two questions up and the whole topic gets confusing fast.

=== Loose textures (PNG) ===

You put a <code>.png</code> in your mod's <code>Textures/</code> folder and reference it by path. Simplest possible setup, and what almost every tutorial starts with. (The [[Modding_Tutorials/Textures|Textures]] page covers the path rules and texture conventions in full; this page assumes you have that down.)

RimWorld does not render your PNG directly. On load it converts the PNG into a compressed GPU texture (the same family of formats DDS uses) and caches the result. So the PNG is a source file, not the thing the GPU actually draws. That conversion is cheap for one texture and not cheap for a thousand.

* '''Pro:''' dead simple, easy to edit, easy to diff, no tooling.
* '''Con:''' the game pays a conversion cost on load, and you cannot ship anything other than textures and sounds this way.

=== DDS textures ===

A <code>.dds</code> file is a texture that is ''already'' in a GPU-ready compressed format. If you drop a DDS next to where the PNG would go, RimWorld uses it directly and skips the conversion step entirely.

So the loose-vs-DDS question is mostly about that conversion cost, not about how the final image looks. A correctly-made DDS and the game's own PNG conversion land in roughly the same place visually. What DDS buys you is a faster load and no first-load hitch, because the expensive part already happened on your machine when you made the file.

The catch is you have to ''make'' the DDS, and if you make it wrong (wrong compression, no mipmaps, wrong color space) it can look worse than just letting the game convert the PNG. It is a real win for large texture sets, and a footgun for people who do not know what BC7 or mipmaps are.

* '''Pro:''' no runtime conversion, faster load, no first-load stutter for that texture.
* '''Con:''' you have to generate it correctly, harder to edit after the fact, much larger on disk than the source PNGs, and still textures-only.

=== Asset bundles ===

A bundle is the next step up. It is one file that can hold many textures (already in GPU format, like DDS, so same load-time win) ''plus'' meshes, shaders, fonts, and audio. Instead of hundreds of loose files converted one by one, the engine loads one bundle and everything inside is ready to go.

The trade is that a bundle is opaque. You cannot open it in an image editor and tweak a pixel. You rebuild it from your source assets, which means you keep your editable PNGs and Unity sources somewhere and treat the bundle as a build output, the same way you treat a compiled DLL.

* '''Pro:''' fastest load for large asset sets, one file instead of thousands, and it is the only option for shaders, fonts, and custom meshes.
* '''Con:''' you need a build step and the Unity tooling to produce it, and the output is not hand-editable.

=== Quick comparison ===

{| class="wikitable"
! Approach !! Load cost !! Disk size !! Can carry !! Editable after build? !! Good for
|-
| Loose PNG || Converted every load || Small || Textures, sounds || Yes || Small mods, prototyping
|-
| DDS || None (pre-converted) || Large || Textures || Painful || Large texture sets
|-
| Asset bundle || None (pre-converted) || Smallest || Textures, meshes, shaders, fonts, audio || No (rebuild from source) || Large mods, anything non-texture
|}

That disk-size column is worth some real numbers. Take one texture set of around 960 files and store it all three ways:

* As loose PNGs: about 40 MB.
* Converted to DDS: about 230 MB. The conversion skips the runtime work but blows up the size on disk.
* Packed into a single asset bundle: about 28 MB.

So DDS is the ''largest'' on disk, not the smallest. It trades space for skipping the load-time conversion. The bundle gets that same load-time win and still ends up the smallest of the three, because it is compressed into one file. (Numbers from a comparison shared in the [https://discord.com/channels/214523379766525963/632790371256238120/1405733585268375643 RimWorld modding Discord]; your exact figures will vary with the texture set and compression settings.)

== The workflow, in plain terms ==

Before any code or folder layout, here is what building a bundle actually looks like from a height:

# You keep your real, editable source assets (PNGs, Unity materials, shader files, font files) in a Unity project.
# In that Unity project you tag each asset with a bundle name, then tell Unity to build the bundles.
# Unity spits out the bundle files.
# You ship those bundle files inside your RimWorld mod.
# At game load, RimWorld finds the bundle on its own and serves its contents through the normal content lookup (1.6 does the loading for you; textures and sounds resolve by their existing path, while shaders and fonts you still fetch by name in code).

That is the loop. You edit in Unity, build, copy the output into your mod, and the game picks it up. The first time through it feels like a lot of ceremony for a texture. Once it is set up, adding a new asset is just "drop it in the Unity project, rebuild, copy."

You do not have to do every step by hand. The next section covers that before the build details, so you can go find a tool first if you would rather not set this up yourself.

== Before we get started: Do I actually have to do everything below? ==

No. Setting up the Unity project, writing the build script, and juggling per-platform bundles is fiddly enough that several modders have written tools to do it for you. They wrap the whole thing, handle the multi-platform build, and spit out ready-to-ship bundles without you babysitting the Unity editor. If that sounds like what you want, you can stop here and go find one; the rest of this page is for when you want to understand what those tools are doing or build it yourself.

This tutorial does not point at any specific one on purpose, since they come and go and get superseded. A search on Google or GitHub for RimWorld asset bundle tooling turns them up, and the modding Discord communities are usually the fastest place to find out which one people are actually using right now and which one is abandoned. Ask there before sinking an afternoon into a tool that got replaced six months ago.

== Branch: the real build steps ==

If you want the actual mechanics, here they are. First, install the right Unity editor. This matters more than anything else on this page: a bundle built on the wrong Unity version may silently fail to load. RimWorld 1.6 runs on '''Unity 2022.3.35f1''', so install exactly that version through the Unity Hub (under "Add" you can pick a specific archived version, or grab it from the Unity download archive). Build your bundles in 2022.3.35f1 and they line up with what the game expects. If RimWorld updates to a new Unity version down the line, you rebuild against the new one.

=== Folder layout ===

Inside your mod, bundles usually live somewhere like:

MyMod/
About/
Defs/
Textures/
AssetBundles/
mymod_assets_win
mymod_assets_mac
mymod_assets_linux

The bundle file itself has no extension. You name it whatever you tagged it in Unity, with the OS suffix on the end (see the deep dive for why the three files). There is no <code>.dll</code> required to use a bundle: a pure XML-and-textures mod can ship a bundle and never write a line of C#, because the game loads it and serves its contents automatically.

=== Tagging and building in Unity ===

In the Unity project, select an asset, and at the bottom of the Inspector there is an AssetBundle dropdown. Assign a bundle name there. Everything sharing that name builds into the same bundle.

Then you need a small editor script to actually trigger the build, because Unity does not expose bundle building in the default menus.

The bare version is just one <code>BuildPipeline.BuildAssetBundles</code> call. It works, but it ships your textures with whatever import settings they happened to have, which is usually uncompressed and wasteful. Controlling how each texture imports before it gets packed is what actually shrinks the disk and memory footprint, so the script below does two things: it walks your textures and sets sane import settings on each, then builds.

<pre>
using UnityEditor;
using UnityEngine;
using System.IO;

public static class BundleBuilder
{
[MenuItem("Assets/Build AssetBundles")]
static void Build()
{
// First pass: set good import settings on every texture in the project.
foreach (string guid in AssetDatabase.FindAssets("t:Texture2D"))
{
string assetPath = AssetDatabase.GUIDToAssetPath(guid);
if (AssetImporter.GetAtPath(assetPath) is not TextureImporter tex) continue;

string lower = assetPath.ToLower();
bool isTerrain = lower.Contains("/terrain/");
bool isMask = lower.Contains("_mask");
bool isNormal = lower.Contains("_normal");

// GUI type suits RimWorld's flat 2D art and avoids Unity generating sprite sub-assets.
tex.textureType = isNormal ? TextureImporterType.NormalMap : TextureImporterType.GUI;
tex.alphaIsTransparency = true;

// Mask and normal maps hold raw data, not color, so they must stay linear (sRGB off).
tex.sRGBTexture = !isMask && !isNormal;

// Terrain tiles repeat across the ground; everything else should clamp at its edges.
tex.wrapMode = isTerrain ? TextureWrapMode.Repeat : TextureWrapMode.Clamp;
tex.anisoLevel = isTerrain ? 8 : 1;

tex.filterMode = FilterMode.Trilinear;
tex.mipmapEnabled = true;

// BC7 high-quality compression: small on disk and in VRAM, good for hand-painted art.
tex.SetPlatformTextureSettings(new TextureImporterPlatformSettings
{
name = "Standalone",
overridden = true,
format = TextureImporterFormat.BC7,
maxTextureSize = 4096,
textureCompression = TextureImporterCompression.CompressedHQ
});

tex.SaveAndReimport();
}

// Second pass: build the bundles.
string output = "Assets/BuiltBundles";
Directory.CreateDirectory(output);
BuildPipeline.BuildAssetBundles(
output,
BuildAssetBundleOptions.ChunkBasedCompression, // LZ4
BuildTarget.StandaloneWindows64
);
}
}
</pre>

A few notes on what that import pass is doing:

* '''BC7 + CompressedHQ''' is the compression that gets you the small disk and VRAM footprint. Without it the texture sits in memory uncompressed.
* '''sRGB off for masks and normal maps.''' A stuff-color mask or a normal map stores data, not a picture, so it must be read as linear. Leaving sRGB on silently corrupts it. The script keys off <code>_mask</code> and <code>_normal</code> in the filename, so name your files accordingly.
* '''Terrain repeats, everything else clamps.''' Terrain tiles need <code>Repeat</code> wrap so they tile seamlessly across the ground; a regular sprite wants <code>Clamp</code> so its edges do not bleed. The script keys off a <code>/Terrain/</code> folder in the path.
* '''Mipmaps on''' so the texture does not shimmer when the camera zooms out.

This is a trimmed-down version of what dedicated bundle-building tools do; they also handle audio compression, font atlas generation, and per-bundle include/exclude rules. The texture settings above are the ones worth knowing by hand. Run the menu item, Unity reimports the textures and writes the bundles to the output folder, and you copy the ones you care about into your mod's <code>AssetBundles/</code> folder.

=== Loading the bundle in your mod ===

In 1.6 you do not load the bundle yourself at all, which catches people off guard since the older docs make it look involved. RimWorld scans every active mod's <code>AssetBundles/</code> folder on startup, loads what it finds, and keeps the loaded bundles on the mod. You do not write <code>AssetBundle.LoadFromFile</code>, you do not call <code>LoadAsset</code>, you do not run anything in a static constructor.

The game's normal content lookup also checks bundles for you. When you ask for a texture the usual way, with <code>ContentFinder<Texture2D>.Get("Things/Item/MyThing")</code>, RimWorld first looks for a loose file at that path, and if it does not find one it looks inside your loaded bundles at the matching path. Same call, same path string, whether the texture is loose or bundled. The asset just has to live at the same path inside the bundle that the loose file would have used (so an asset packed at <code>Textures/Things/Item/MyThing</code> resolves for the path above).

The practical upshot: for textures and sounds you do not change a single line of your mod's code to switch from loose to bundled. You reference them by path like you always did. You only build a bundle, drop it in the folder, and the game finds the contents.

The exception is shaders. The content lookup skips the loose-file step for shaders entirely (there is no loose-shader path), so a shader is only ever found inside a bundle. <code>ContentFinder<Shader>.Get("MyShaderName")</code> works, but only because the shader is in a bundle for it to find.

== Branch: the deep dive ==

Most of this only comes up once you are shipping a shader or a font. A small texture-only mod can skip the whole section.

=== Shaders and the cross-platform problem ===

A compiled shader is platform-specific, which is why a lot of mods end up shipping multiple bundles. A shader built for DirectX (Windows) is not the same bytes as one built for Metal (Mac) or Vulkan/OpenGL (Linux). If you build one bundle on Windows and ship it, your shader works on Windows and quietly fails on Mac and Linux, usually showing up as bright magenta where the texture should be.

The fix is to build a bundle per platform, and 1.6 makes this almost free because the game does the picking for you. Name your bundle files with the suffix the game looks for:

* <code>mymod_assets_win</code> loads on Windows
* <code>mymod_assets_mac</code> loads on Mac
* <code>mymod_assets_linux</code> loads on Linux

The game checks the running platform and loads only the matching one. A bundle with no suffix at all loads on every platform, which is fine for textures and meshes that do not care, but not safe for shaders. So you build the same assets three times in Unity with different <code>BuildTarget</code> values (<code>StandaloneWindows64</code>, <code>StandaloneOSX</code>, <code>StandaloneLinux64</code>), give each the right suffix, and ship all three. You write no platform-detection code yourself.

If you have ever installed a mod that worked fine for everyone except the Mac and Linux players who saw pink everywhere, this is almost always why.

=== Sounds ===

Audio can go in a bundle as an <code>AudioClip</code>, and for a lot of sounds it is fine and saves you the loose-file management. RimWorld can also load loose audio through its normal sound def system, so for ordinary sound effects you often do not need a bundle at all. Where bundles help is when you want the audio packed with everything else, or when you are loading clips directly from code rather than through a SoundDef.

=== Fonts ===

If you want a custom font in your UI, a bundle is the way. You import the font into Unity, build it into a bundle, load it as a <code>Font</code>, and assign it where you draw text. There is no loose-font path in RimWorld at all, so here the bundle is not a speed-up, it is the only way in.

=== Meshes ===

Same story as fonts. Custom 3D meshes (not the usual flat sprites, actual geometry) come in through a bundle as a <code>Mesh</code>. Most RimWorld mods never touch this, but if you are doing something with real geometry it is here.

=== Compression and a couple of gotchas ===

A few things worth knowing before you spend an afternoon confused:

* '''Unity version mismatch.''' A bundle built on a different Unity version than the game uses may refuse to load, often with no clear error, the asset just comes back null. Build on Unity 2022.3.35f1 for RimWorld 1.6. This is the single most common reason a bundle that worked in the editor does nothing in-game.
* '''Bundle file compression.''' This is how the bundle file is packed on disk, separate from texture compression below. Bundles can be built uncompressed, LZ4, or LZMA. LZ4 is the usual sweet spot: small enough, and it does not stall on load the way LZMA can. <code>BuildAssetBundleOptions.ChunkBasedCompression</code> gives you LZ4.
* '''In-memory texture compression and the white-outline bug.''' Loose textures are compressed in memory once loaded, and that compression is what produces the faint white halo people sometimes see around a sprite (the art program threw away color data in fully transparent pixels). A bundle lets you turn that in-memory compression off for its textures, which sidesteps the halo without the usual workaround of padding the outline. The [[Modding_Tutorials/Textures|Textures]] page documents the bug and the loose-texture fix.
* '''Shader stripping.''' Unity sometimes strips shader variants it thinks are unused during the build, and then your shader looks wrong at runtime because the variant you needed got cut. If a shader misbehaves only in the built bundle but works in the editor, this is a likely suspect.
* '''Color space.''' If your textures look washed out or too dark coming out of a bundle, check that the import settings and color space match what the game expects. This is the same class of problem that makes a hand-rolled DDS look wrong.

== Summary ==

* Loose PNG: simplest, but converted on every load and limited to textures and sounds.
* DDS: a texture pre-converted to GPU format, so it skips the load-time conversion. Same final look, faster load, but you have to make it right, and it lands much larger on disk than the source PNGs.
* Asset bundle: one pre-packed file that carries textures, meshes, shaders, fonts, and audio. The fastest option for big mods and the only option for shaders, fonts, and custom meshes.

If your mod is small, stay loose. If it is large or needs anything Unity-shaped beyond a texture, learn bundles, and on 1.6+ that is the encouraged path anyway since the engine does the loading and per-OS swapping for you. And if you are shipping a shader, build one bundle per platform with the right suffix, or your Mac and Linux players get magenta.

[[Category:Modding]]
[[Category:Modding tutorials]]

Modding Tutorials/Asset Bundles

2026-06-24T19:30:14Z

CryptikLemur: Adding new page on Asset Bundles

{{DISPLAYTITLE:Asset Bundles}}

{{BackToTutorials}}

This tutorial explains what asset bundles are, why you might want them, and how they compare to the two other ways RimWorld can load custom art: loose textures and DDS files. It starts from zero, so you do not need to know anything about Unity going in. The later sections branch into the actual build process and then into the deeper stuff: shaders, sounds, fonts, and the things that go wrong.

== What is an asset bundle? ==

An asset bundle is a single file that holds a bunch of Unity assets already packed in the format the engine wants. RimWorld runs on Unity, and Unity has its own internal way of storing textures, meshes, shaders, audio, and so on. A loose PNG sitting in your mod's <code>Textures/</code> folder is not in that format yet, so the game has to convert it before it can use it.

A bundle is that conversion done ahead of time, saved to disk, and handed to the engine in one piece. The rest of this page is mostly consequences of that.

== Why would I care? ==

Two reasons, mostly:

'''Load time.''' When you ship loose PNGs, RimWorld converts every single one while the game boots (more on this in the next section). For a small mod you will never notice. For a mod with hundreds or thousands of textures, that conversion adds up, and it is part of why a heavily-modded load screen sits there for a while. A bundle skips the conversion because the work is already done.

'''Everything that is not a texture.''' Loose files only really work for textures and sounds. If you want to ship a custom shader, a custom font, a custom mesh, or anything else Unity-shaped, a bundle is the normal way to get it into the game. There is no <code>Shaders/</code> folder you can just drop a file into.

If your mod is XML and a handful of textures, you probably do not need bundles at all. If your mod is large, or it needs a custom shader or font, you do.

As of 1.6, bundles are the encouraged path for anything beyond a small loose-texture mod. The engine grew real first-class support for them: it loads them for you, swaps the right one per operating system, and serves their contents through the same content lookup you already use. Earlier versions made you wire all of that up by hand, which is why older tutorials look more involved than this one. On 1.6+ most of the friction is gone.

== Loose textures vs DDS vs asset bundles ==

All three of these get a texture onto the screen. They differ in '''when''' the work happens and '''what''' they can carry. Mix those two questions up and the whole topic gets confusing fast.

=== Loose textures (PNG) ===

You put a <code>.png</code> in your mod's <code>Textures/</code> folder and reference it by path. Simplest possible setup, and what almost every tutorial starts with. (The [[Modding_Tutorials/Textures|Textures]] page covers the path rules and texture conventions in full; this page assumes you have that down.)

RimWorld does not render your PNG directly. On load it converts the PNG into a compressed GPU texture (the same family of formats DDS uses) and caches the result. So the PNG is a source file, not the thing the GPU actually draws. That conversion is cheap for one texture and not cheap for a thousand.

* '''Pro:''' dead simple, easy to edit, easy to diff, no tooling.
* '''Con:''' the game pays a conversion cost on load, and you cannot ship anything other than textures and sounds this way.

=== DDS textures ===

A <code>.dds</code> file is a texture that is ''already'' in a GPU-ready compressed format. If you drop a DDS next to where the PNG would go, RimWorld uses it directly and skips the conversion step entirely.

So the loose-vs-DDS question is mostly about that conversion cost, not about how the final image looks. A correctly-made DDS and the game's own PNG conversion land in roughly the same place visually. What DDS buys you is a faster load and no first-load hitch, because the expensive part already happened on your machine when you made the file.

The catch is you have to ''make'' the DDS, and if you make it wrong (wrong compression, no mipmaps, wrong color space) it can look worse than just letting the game convert the PNG. It is a real win for large texture sets, and a footgun for people who do not know what BC7 or mipmaps are.

* '''Pro:''' no runtime conversion, faster load, no first-load stutter for that texture.
* '''Con:''' you have to generate it correctly, harder to edit after the fact, much larger on disk than the source PNGs, and still textures-only.

=== Asset bundles ===

A bundle is the next step up. It is one file that can hold many textures (already in GPU format, like DDS, so same load-time win) ''plus'' meshes, shaders, fonts, and audio. Instead of hundreds of loose files converted one by one, the engine loads one bundle and everything inside is ready to go.

The trade is that a bundle is opaque. You cannot open it in an image editor and tweak a pixel. You rebuild it from your source assets, which means you keep your editable PNGs and Unity sources somewhere and treat the bundle as a build output, the same way you treat a compiled DLL.

* '''Pro:''' fastest load for large asset sets, one file instead of thousands, and it is the only option for shaders, fonts, and custom meshes.
* '''Con:''' you need a build step and the Unity tooling to produce it, and the output is not hand-editable.

=== Quick comparison ===

{| class="wikitable"
! Approach !! Load cost !! Disk size !! Can carry !! Editable after build? !! Good for
|-
| Loose PNG || Converted every load || Small || Textures, sounds || Yes || Small mods, prototyping
|-
| DDS || None (pre-converted) || Large || Textures || Painful || Large texture sets
|-
| Asset bundle || None (pre-converted) || Smallest || Textures, meshes, shaders, fonts, audio || No (rebuild from source) || Large mods, anything non-texture
|}

That disk-size column is worth some real numbers. Take one texture set of around 960 files and store it all three ways:

* As loose PNGs: about 40 MB.
* Converted to DDS: about 230 MB. The conversion skips the runtime work but blows up the size on disk.
* Packed into a single asset bundle: about 28 MB.

So DDS is the ''largest'' on disk, not the smallest. It trades space for skipping the load-time conversion. The bundle gets that same load-time win and still ends up the smallest of the three, because it is compressed into one file. (Numbers from a comparison shared in the [https://discord.com/channels/214523379766525963/632790371256238120/1405733585268375643 RimWorld modding Discord]; your exact figures will vary with the texture set and compression settings.)

== The workflow, in plain terms ==

Before any code or folder layout, here is what building a bundle actually looks like from a height:

# You keep your real, editable source assets (PNGs, Unity materials, shader files, font files) in a Unity project.
# In that Unity project you tag each asset with a bundle name, then tell Unity to build the bundles.
# Unity spits out the bundle files.
# You ship those bundle files inside your RimWorld mod.
# At game load, RimWorld finds the bundle on its own and serves its contents through the normal content lookup (1.6 does the loading for you; textures and sounds resolve by their existing path, while shaders and fonts you still fetch by name in code).

That is the loop. You edit in Unity, build, copy the output into your mod, and the game picks it up. The first time through it feels like a lot of ceremony for a texture. Once it is set up, adding a new asset is just "drop it in the Unity project, rebuild, copy."

You do not have to do every step by hand. The next section covers that before the build details, so you can go find a tool first if you would rather not set this up yourself.

== Before we get started: Do I actually have to do everything below? ==

No. Setting up the Unity project, writing the build script, and juggling per-platform bundles is fiddly enough that several modders have written tools to do it for you. They wrap the whole thing, handle the multi-platform build, and spit out ready-to-ship bundles without you babysitting the Unity editor. If that sounds like what you want, you can stop here and go find one; the rest of this page is for when you want to understand what those tools are doing or build it yourself.

This tutorial does not point at any specific one on purpose, since they come and go and get superseded. A search on Google or GitHub for RimWorld asset bundle tooling turns them up, and the modding Discord communities are usually the fastest place to find out which one people are actually using right now and which one is abandoned. Ask there before sinking an afternoon into a tool that got replaced six months ago.

== Branch: the real build steps ==

If you want the actual mechanics, here they are. First, install the right Unity editor. This matters more than anything else on this page: a bundle built on the wrong Unity version may silently fail to load. RimWorld 1.6 runs on '''Unity 2022.3.35f1''', so install exactly that version through the Unity Hub (under "Add" you can pick a specific archived version, or grab it from the Unity download archive). Build your bundles in 2022.3.35f1 and they line up with what the game expects. If RimWorld updates to a new Unity version down the line, you rebuild against the new one.

=== Folder layout ===

Inside your mod, bundles usually live somewhere like:

MyMod/
About/
Defs/
Textures/
AssetBundles/
mymod_assets_win
mymod_assets_mac
mymod_assets_linux

The bundle file itself has no extension. You name it whatever you tagged it in Unity, with the OS suffix on the end (see the deep dive for why the three files). There is no <code>.dll</code> required to use a bundle: a pure XML-and-textures mod can ship a bundle and never write a line of C#, because the game loads it and serves its contents automatically.

=== Tagging and building in Unity ===

In the Unity project, select an asset, and at the bottom of the Inspector there is an AssetBundle dropdown. Assign a bundle name there. Everything sharing that name builds into the same bundle.

Then you need a small editor script to actually trigger the build, because Unity does not expose bundle building in the default menus.

The bare version is just one <code>BuildPipeline.BuildAssetBundles</code> call. It works, but it ships your textures with whatever import settings they happened to have, which is usually uncompressed and wasteful. Controlling how each texture imports before it gets packed is what actually shrinks the disk and memory footprint, so the script below does two things: it walks your textures and sets sane import settings on each, then builds.

<pre>
using UnityEditor;
using UnityEngine;
using System.IO;

public static class BundleBuilder
{
[MenuItem("Assets/Build AssetBundles")]
static void Build()
{
// First pass: set good import settings on every texture in the project.
foreach (string guid in AssetDatabase.FindAssets("t:Texture2D"))
{
string assetPath = AssetDatabase.GUIDToAssetPath(guid);
if (AssetImporter.GetAtPath(assetPath) is not TextureImporter tex) continue;

string lower = assetPath.ToLower();
bool isTerrain = lower.Contains("/terrain/");
bool isMask = lower.Contains("_mask");
bool isNormal = lower.Contains("_normal");

// GUI type suits RimWorld's flat 2D art and avoids Unity generating sprite sub-assets.
tex.textureType = isNormal ? TextureImporterType.NormalMap : TextureImporterType.GUI;
tex.alphaIsTransparency = true;

// Mask and normal maps hold raw data, not color, so they must stay linear (sRGB off).
tex.sRGBTexture = !isMask && !isNormal;

// Terrain tiles repeat across the ground; everything else should clamp at its edges.
tex.wrapMode = isTerrain ? TextureWrapMode.Repeat : TextureWrapMode.Clamp;
tex.anisoLevel = isTerrain ? 8 : 1;

tex.filterMode = FilterMode.Trilinear;
tex.mipmapEnabled = true;

// BC7 high-quality compression: small on disk and in VRAM, good for hand-painted art.
tex.SetPlatformTextureSettings(new TextureImporterPlatformSettings
{
name = "Standalone",
overridden = true,
format = TextureImporterFormat.BC7,
maxTextureSize = 4096,
textureCompression = TextureImporterCompression.CompressedHQ
});

tex.SaveAndReimport();
}

// Second pass: build the bundles.
string output = "Assets/BuiltBundles";
Directory.CreateDirectory(output);
BuildPipeline.BuildAssetBundles(
output,
BuildAssetBundleOptions.ChunkBasedCompression, // LZ4
BuildTarget.StandaloneWindows64
);
}
}
</pre>

A few notes on what that import pass is doing:

* '''BC7 + CompressedHQ''' is the compression that gets you the small disk and VRAM footprint. Without it the texture sits in memory uncompressed.
* '''sRGB off for masks and normal maps.''' A stuff-color mask or a normal map stores data, not a picture, so it must be read as linear. Leaving sRGB on silently corrupts it. The script keys off <code>_mask</code> and <code>_normal</code> in the filename, so name your files accordingly.
* '''Terrain repeats, everything else clamps.''' Terrain tiles need <code>Repeat</code> wrap so they tile seamlessly across the ground; a regular sprite wants <code>Clamp</code> so its edges do not bleed. The script keys off a <code>/Terrain/</code> folder in the path.
* '''Mipmaps on''' so the texture does not shimmer when the camera zooms out.

This is a trimmed-down version of what dedicated bundle-building tools do; they also handle audio compression, font atlas generation, and per-bundle include/exclude rules. The texture settings above are the ones worth knowing by hand. Run the menu item, Unity reimports the textures and writes the bundles to the output folder, and you copy the ones you care about into your mod's <code>AssetBundles/</code> folder.

=== Loading the bundle in your mod ===

In 1.6 you do not load the bundle yourself at all, which catches people off guard since the older docs make it look involved. RimWorld scans every active mod's <code>AssetBundles/</code> folder on startup, loads what it finds, and keeps the loaded bundles on the mod. You do not write <code>AssetBundle.LoadFromFile</code>, you do not call <code>LoadAsset</code>, you do not run anything in a static constructor.

The game's normal content lookup also checks bundles for you. When you ask for a texture the usual way, with <code>ContentFinder<Texture2D>.Get("Things/Item/MyThing")</code>, RimWorld first looks for a loose file at that path, and if it does not find one it looks inside your loaded bundles at the matching path. Same call, same path string, whether the texture is loose or bundled. The asset just has to live at the same path inside the bundle that the loose file would have used (so an asset packed at <code>Textures/Things/Item/MyThing</code> resolves for the path above).

The practical upshot: for textures and sounds you do not change a single line of your mod's code to switch from loose to bundled. You reference them by path like you always did. You only build a bundle, drop it in the folder, and the game finds the contents.

The exception is shaders. The content lookup skips the loose-file step for shaders entirely (there is no loose-shader path), so a shader is only ever found inside a bundle. <code>ContentFinder<Shader>.Get("MyShaderName")</code> works, but only because the shader is in a bundle for it to find.

== Branch: the deep dive ==

Most of this only comes up once you are shipping a shader or a font. A small texture-only mod can skip the whole section.

=== Shaders and the cross-platform problem ===

A compiled shader is platform-specific, which is why a lot of mods end up shipping multiple bundles. A shader built for DirectX (Windows) is not the same bytes as one built for Metal (Mac) or Vulkan/OpenGL (Linux). If you build one bundle on Windows and ship it, your shader works on Windows and quietly fails on Mac and Linux, usually showing up as bright magenta where the texture should be.

The fix is to build a bundle per platform, and 1.6 makes this almost free because the game does the picking for you. Name your bundle files with the suffix the game looks for:

* <code>mymod_assets_win</code> loads on Windows
* <code>mymod_assets_mac</code> loads on Mac
* <code>mymod_assets_linux</code> loads on Linux

The game checks the running platform and loads only the matching one. A bundle with no suffix at all loads on every platform, which is fine for textures and meshes that do not care, but not safe for shaders. So you build the same assets three times in Unity with different <code>BuildTarget</code> values (<code>StandaloneWindows64</code>, <code>StandaloneOSX</code>, <code>StandaloneLinux64</code>), give each the right suffix, and ship all three. You write no platform-detection code yourself.

If you have ever installed a mod that worked fine for everyone except the Mac and Linux players who saw pink everywhere, this is almost always why.

=== Sounds ===

Audio can go in a bundle as an <code>AudioClip</code>, and for a lot of sounds it is fine and saves you the loose-file management. RimWorld can also load loose audio through its normal sound def system, so for ordinary sound effects you often do not need a bundle at all. Where bundles help is when you want the audio packed with everything else, or when you are loading clips directly from code rather than through a SoundDef.

=== Fonts ===

If you want a custom font in your UI, a bundle is the way. You import the font into Unity, build it into a bundle, load it as a <code>Font</code>, and assign it where you draw text. There is no loose-font path in RimWorld at all, so here the bundle is not a speed-up, it is the only way in.

=== Meshes ===

Same story as fonts. Custom 3D meshes (not the usual flat sprites, actual geometry) come in through a bundle as a <code>Mesh</code>. Most RimWorld mods never touch this, but if you are doing something with real geometry it is here.

=== Compression and a couple of gotchas ===

A few things worth knowing before you spend an afternoon confused:

* '''Unity version mismatch.''' A bundle built on a different Unity version than the game uses may refuse to load, often with no clear error, the asset just comes back null. Build on Unity 2022.3.35f1 for RimWorld 1.6. This is the single most common reason a bundle that worked in the editor does nothing in-game.
* '''Bundle file compression.''' This is how the bundle file is packed on disk, separate from texture compression below. Bundles can be built uncompressed, LZ4, or LZMA. LZ4 is the usual sweet spot: small enough, and it does not stall on load the way LZMA can. <code>BuildAssetBundleOptions.ChunkBasedCompression</code> gives you LZ4.
* '''In-memory texture compression and the white-outline bug.''' Loose textures are compressed in memory once loaded, and that compression is what produces the faint white halo people sometimes see around a sprite (the art program threw away color data in fully transparent pixels). A bundle lets you turn that in-memory compression off for its textures, which sidesteps the halo without the usual workaround of padding the outline. The [[Modding_Tutorials/Textures|Textures]] page documents the bug and the loose-texture fix.
* '''Shader stripping.''' Unity sometimes strips shader variants it thinks are unused during the build, and then your shader looks wrong at runtime because the variant you needed got cut. If a shader misbehaves only in the built bundle but works in the editor, this is a likely suspect.
* '''Color space.''' If your textures look washed out or too dark coming out of a bundle, check that the import settings and color space match what the game expects. This is the same class of problem that makes a hand-rolled DDS look wrong.

== Summary ==

* Loose PNG: simplest, but converted on every load and limited to textures and sounds.
* DDS: a texture pre-converted to GPU format, so it skips the load-time conversion. Same final look, faster load, but you have to make it right.
* Asset bundle: one pre-packed file that carries textures, meshes, shaders, fonts, and audio. The fastest option for big mods and the only option for shaders, fonts, and custom meshes.

If your mod is small, stay loose. If it is large or needs anything Unity-shaped beyond a texture, learn bundles, and on 1.6+ that is the encouraged path anyway since the engine does the loading and per-OS swapping for you. And if you are shipping a shader, build one bundle per platform with the right suffix, or your Mac and Linux players get magenta.

[[Category:Modding]]
[[Category:Modding tutorials]]