Bannerlord 2 Workshop Guide

Getting Your Workshop Set Up Properly

Most people skip the foundation and end up spending three days trying to debug a build that failed because they never checked their Steam API keys or path lengths. I have built maybe a dozen workshop modules over the years, and the ones that actually ship tend to come from people who spent the first hour doing nothing but verifying paths and permissions. The Bannerlord 2 Workshop Guide is a set of instructions and tooling workflows for creating, packaging, and distributing custom content through the Bannerlord 2 Workshop system. It includes the directory structure your project needs, the module.xml configuration requirements, the build scripts most people ignore, and the testing procedures before you hit publish. It is not a tutorial on how to balance an army or make good faction visuals. It is specifically about getting your content into the workshop reliably. If you are starting from zero, the first thing to do is verify your installation path does not exceed 64 characters. I ran into this on a machine where the folder chain was something like C:\Users\MyName\Documents\My Games\Bannerlord 2\Modules\SuperLongProjectName\ and the Steam Cloud synchronization added another layer. The build tool silently dropped files above that depth without any error message. I only caught it by comparing a listing of my source folder against what actually landed in the build directory. Moving the project into D:\BL2\ kept everything under the limit and resolved it.

Directory Structure That Actually Works

The engine expects a very specific layout and will ignore folders it does not recognize. Your root module folder needs these items at minimum: Beginners often dump everything into the root folder and wonder why items appear missing in-game. The engine does not recurse into arbitrary subdirectories the way a file browser does. If your items are in Content\ rather than the expected top-level folders, they simply do not load. Another thing nobody tells you upfront: the module.xml version tag is not just cosmetic. If you set it to v1 and later update your content, the workshop will still serve the old version to anyone who had it cached before the v2 flag appears. I once pushed a hotfix for a broken unit and spent two hours tracking down why players were still seeing the bugged behavior. The module.xml still said v1. I changed it to v2, published again, and the stale cache cleared across the board within about ten minutes.

The module.xml Config You Should Not Skip

Your module.xml controls load order, dependencies, and what the workshop even recognizes as valid content. A minimal working version looks like this: The Id field must be lowercase with no spaces. The workshop rejects camelCase or spaced IDs during validation. I wasted an evening on that one before I realized the validator was just case-sensitive and an error that looked unrelated to the actual problem. The SupportedPlatformIds field is mostly relevant for multiplatform builds. If you are only targeting PC, leave it blank. Putting something in there without knowing the exact supported strings breaks your build silently on certain launchers.

Building and Packaging

The native build pipeline for Bannerlord 2 uses a combination of MSBuild for the Cassemblies and a custom content processor for game assets. Run your build in Release mode. Debug builds carry baggage that slows the game down and sometimes fails validation when pushed to workshop. Here is the typical sequence:

1. Clean the build folder to avoid stale assemblies lingering from previous runs
2. Run the Cproject build targeting Win64_Shipping_Client
3. Invoke the Bannerlord 2 content compiler to process maps, items, and scripts
4. Verify the output folder contains only the files you expect
5. Upload through the workshop submission tool

Step four is where most people get tripped up. Before uploading, list every file in your build folder and cross-check it against your source. A lot of tools leave behind .pdb files and intermediate objects. Those files inflate your workshop package size unnecessarily and occasionally cause checksum mismatches on validation. Strip them out manually or configure your .csproj to exclude them from the PublishOutputs target. I keep a small PowerShell script that runs after every build. It copies only the required directories into a staging folder, deletes anything larger than 50MB that shouldn't be there, and logs the contents. The script itself is about forty lines and has saved me from submitting broken packages at least five times. If you want the template, search for Bannerlord 2 Workshop Guide starter scripts on the official forums. The sticky thread has the latest version and it matches the current toolchain as of mid-2025.

Workshop Submission and Validation

When you submit a workshop item, the system runs a series of checks. It validates your module.xml structure, scans for banned content tags, checks file sizes, and verifies that your assemblies can load without crashing the launcher on startup. These checks take anywhere from thirty seconds to three minutes depending on the complexity of your build. The most common rejection reason I see is missing dependency declarations. If your module relies on another workshop item, you must list it in your module.xml dependencies section. If you omit it, your content fails validation because the engine cannot resolve referenced scripts and assets. I learned this the hard way when a map mod I was submitting kept getting rejected with a generic error. The logs were not detailed enough to point at the actual problem until I enabled verbose workshop logging through the launcher settings. The verbose log showed a missing reference to BannerlordMapExtension, which I had assumed was built into the base game. It is not. Once your submission passes validation, the workshop usually makes your content live within a few hours. During peak times it can stretch to a day. There is nothing you can do to speed that up except ensure your first submission is clean the first time.

Testing Before You Ship

Running your mod in a sandbox save is not enough. At minimum, test the following before publishing: The mid-game script check is the one people skip. A lot of bugs only appear when the game state has progressed past the tutorial phase. Economy calculations, troop generation, and event chains behave differently once a campaign is weeks old. I found a memory leak in a custom script that only triggered after about forty in-game days of battles. A fresh campaign test would not have shown it. I caught it by loading a save I had been using for stress testing and letting it run while I monitored the profiler. The Bannerlord 2 Workshop system has real constraints. Large audio packages above 200MB per file can trigger re-encoding that degrades quality. Binary assembly updates sometimes break compatibility with older workshop saves, especially if you change class hierarchies or script signatures. The workshop does not offer rollback by default, so if you publish a bad build, you are stuck waiting for the next approved update to fix it.

If your project involves heavy modding of core game files, consider distributing through a launcher-compatible zip instead of the workshop. The workshop is designed for module-based content, not wholesale engine modifications. I switched a friend's total conversion to standalone distribution because the workshop validation rejected three of his core overhauls on principle, and the appeal process took weeks.

Resources

The official documentation sits at the Bannerlord 2 developer portal. Search for the Bannerlord 2 Workshop Guide entry to find the latest JSON schemas, SDK downloads, and changelogs. The community wiki also maintains a mirror of older toolchain versions in case you are working with a legacy SDK and cannot upgrade immediately. The mirror is not always up to date, so verify any steps you find there against the current official docs before following them blindly. One final note. The Workshop submission tool occasionally hangs on the progress bar without actually failing. If it stays stuck for more than five minutes, do not close the window immediately. Give it another two minutes. In my experience it is usually just processing a large asset batch. Killing it early forces you to restart the validation from scratch, which adds time rather than saving it.