This tutorial will go through the process of creating our first mod and uploading it to the Steam Workshop for community members to subscribe to and play with friends!

To enable workshop uploading and download in-game, a Beta is available on Steam labelled "workshop-beta". If all goes smoothly we'll roll this out to all users in the coming days.

Our goal for this mod is to get some familiarity playing with a couple of editor tools, learn about the file structures used in Barony and get to know how our implementation of the Workshop operates. The vision is as follows:

• Modify the starting Barony map to include a Ring of Slow Digestion for 1 player.
  
• Create a mod folder containing our modified map file.
  
• Upload to the Steam Workshop and setting the required tags, images and descriptions to advertise our creation.

Very simple, but once you've got the Workshop-upload part down you can spend more time in the editor to create more complex adventures. This guide is VERY extensive and full of pretty pictures to check your progress. Personally I can speedrun through every step of the guide in less than 5 minutes so don't be dismayed by the length.

At the time of writing, only map files are compatible with Barony's mod-loading capability. I plan to extend this further in a direction that isn't 100% confirmed yet, I'll wait to hear feedback from the community for requested content mod feature types.

• Remodels of .vox files for weapons/items/monsters
  
• Retextures of our in-game tilesets
  
• Music remixes
  
• Alternate sound effects
  
• Item gold value/weight/sprite image variations
  
• Rebalances to what items can appear in which levels on the ground/in chests/in shops
  
• Replacing our existing books with new texts
  
• Translations for the game

• Random generation variables like monster spawn lists/minibosses/traps/furniture types (these are tied to the level set e.g mines)
  
• Modifying/Editing Player classes
  
• New spells or items
  
• Probably some more things...

A reminder our open source Barony code is available for perusal at: https://github.com/TurningWheel/Barony/

If you get our project running and compiling, you can upload your compiled Barony.exe files up on the workshop for others to download in our current system. (Though obviously not hot-swappable like map files are!)

I plan to make a small guide in the future for getting that set up and running for those with the know-how to code, but are unfamiliar with setting up a project from GitHub in Visual Studio on Windows.

In (Blessed) addition (heh), I'd also like to release a more in-depth guide for the editor to fully explore the possibilities for aspiring mapmakers.

Steam Forum discussion thread here

We'll be editing a copy of the first map in the game, "start.lmp". All map files used in Barony have the .lmp filename extension.

Open up the Barony Editor through Steam (select "launch editor"). Navigate to the top-left menu and select Open...



Either manually type start.lmp or use the scrollbar (left click drag or scroll wheel) to get to where the "start.lmp" map lives in the alphabetical order.

Click on the entry to fill out the text box. (Ignore the start1.lmp in the picture, my directory has a bunch of test map names which your steam install won't have.)



Open the file. Here we see a tile based layout of the first map in Barony. In the bottom left of the editor window is the text "WALLS" which shows which tiles are currently visible on screen. There are 3 total layers, FLOOR, WALLS and CEILING.

• FLOOR tiles are what the players/monsters move on.
  
• WALLS tiles are 1 tile high and blocks movement when placed on floors. These are the diggable parts of the wall, and torches spawn on walls at this height.
  
• CEILING tiles are passable tiles that are 2 tiles high from the FLOOR layer, and are mostly for decoration. Entities do not check for collision with these tiles.

To toggle between tile layers, use SHIFT + scroll wheel up or down to change the height. For users without a scroll wheel, CTRL + U or CTRL + P will also change the layer height.



Some wall tiles that are currently on screen are trees, columns and map borders, and the gates that are behind the spawn point.

There is also 1 other object type in the editor, "sprites". Sprites are objects that inhabit the game world and usually are visible and interactable by the player. Think torches, switches, doors, monsters, items, gold, decoration etc. The 4 arrow symbols seen in this map are hidden in-game sprites that control the 4 possible player spawn points in the map and are required in every map.

You can navigate around the map in the main view using the UP/DOWN/LEFT/RIGHT arrow keys. Pressing the F key toggles the overhead view into first person mode, where you can see the physical layout from the perspective of the player. This will only render tiles into proper 3d space and keep the sprite tiles as 2d representations.



The camera in this mode is also controllable with the arrow keys as well. If you pan the camera left you can see the sprite representation of the table that spawns in with the starting readable book.



Back out of first person mode using the same F key used to get into it. For this tutorial, we're not going to modify the map layout but insert some new sprites into the spawn area. To access the sprite select menu, use the S key.



In this screen you can use the mouse to select (left click) one of the symbols seen to then place it down on our map. To exit this screen either press the ESCAPE key or make a selection.

When hovering over each tile, you can see a little tooltip label that gives a rough indication of what each sprite does, as well as the little editor image that will show up on the main map view. This tutorial will not cover the use cases of each sprite, that will be covered elsewhere. Note that some of the sprites like the explosion series of sprites are not actually in-game objects but are used as resources as animations in Barony like fireball explosions or striking a wall.

Let's select sprite 125: PODIUM. We're going to create an object to sit a new item on top of. Select with left click, and place down the sprite with left click as well.



Once a sprite has been placed, change the current tool to the "POINT" tool with the 2 key or by clicking the button in the right-side panel. This tool is for selecting sprites, whereas the default pencil tool only paints tiles for us and ignores clicking on sprite objects.

Sprites can be ready-to-go when placed, or sometimes have an advanced "properties" menu accessible via F2. To access the properties for a certain sprite, left click on a sprite to select it (blue highlight is drawn when selected) and press the F2 key. Pressing F2 when no sprite is selected will bring up the properties for the last picked up sprite. You'll be notified if the sprite doesn't have properties available through a status message in the bottom right corner of the editor.

The PODIUM sprite for example spawns in a cute little lectern-looking piece of furniture, featured in the new Blessed Addition levels. One of the properties exposed for all the new furniture types (beds/chairs etc) is the facing direction of the model in-game. Here we can set a direction value from 0-7 to rotate through the cardinal directions EAST, SOUTHEAST, SOUTH, SOUTWEST, WEST, NORTHWEST, NORTH, NORTHEAST. 0 is EAST while 7 is NORTHEAST.
Setting a property to –1 will usually leave it up to the game to orient the model (for most furniture it picks a facing random direction to place the sprite).

Most of the time this value will represent the actual facing direction of the in-game model, but you'll find some quirks like the podium model being slightly offset from these values. Let's pick WEST and see what happens. Type in 4 into the property box and click on OK.

Now we want to save the map. BEFORE HITTING SAVE: Let's check out the brand new save/load directory options in our editor. Press CTRL + D to bring up this menu or find it under File->Directory...

Since we're going to export this map in our fancy workshop mod, we should save this somewhere unique that doesn't overwrite the game's base files as this will cause havoc in multiplayer lobbies if one player has different map data from the rest.

The directory menu allows us to specify unique save and load locations in the Barony folder for our maps. We can keep the Load (open) Dir as ./maps as default, but we will want to change the save location. Type the new folder name into the text input field, call it something simple "test" "testmod" or whatever! I've gone with "myfirstmod". Now click "Set as save directory", if the folder name typed in doesn't exist, a new empty mod folder structure will be automatically created for you and
the save path will be set. For reference the location of this folder is in the Barony Steam install folder steamapps/Barony/mods/myfirstmod/maps/

Once set, click the X to close that dialogue.



Let's now save the file, go to File->Save as... and you should see an empty list of maps to save you file in. This is the new directory we just created. Hitting save will save straight to this new mod folder and not overwrite any of your base game stuff.

When doing this for the first time in a mod folder, always use Save as... to bring up the location dialogue to make sure you're writing to the correct area! The editor happily overwrites any map file with the same name it finds, so beware! If you do mess up for whatever reason, you can also do a Steam verify game files to restore the modified data.



Once we're happy with the save location, change the Load Dir in the CTRL + D directory menu into your mod folder and bring up the open dialogue with CTRL + O. Verify our brand new start.lmp has entered the folder as expected. If you're happy with the results, we can just use CTRL + S or the save option in the File dropdown in the future.

Time to open this bad boy up in game! Load Barony from Steam as well. If your Barony window is fullscreen, change it to a smaller windowed box as we'll be alt+tabbing our way through playtests constantly and fullscreen makes this take a while.

Hit that brand new "Custom Content" button and let's see the new window!



You'll be face to face with a new empty menu, with 3 buttons; "local mods" "new mod folder" and "start modded game". The "new mod folder" button will create a dialogue for you to create a new mod subdirectory which we achieved through the editor, so we'll leave that untouched throughout the rest of this tutorial.

Hit "local mods" to load every folder in our Barony/mods/ directory and you should see our recently created folder come up. If it doesn't show up, your Windows or whatever account may not have write privileges to create new directories... So try running the editor/Barony as administrator which could help. This shouldn't happen but it's something that crossed my mind. Here's hoping it shows up anyway!



For each mod folder there's an option on the far right to "Load Item". This internally appends the folder contents to the Barony read directories, and lets us use content that otherwise is not present in the main install directory.

So for our first mod, we edited the start.lmp map. Barony checks the mod folder for this file first, then falls back on it's base Barony/maps folder to check if start.lmp exists if not present anywhere else.

Pressing this button should turn the box green to indicate a load success. You can then unload the mod later if you do not want to use it. Lets keep it loaded then hit "start modded game".



We enter the Character Creation as normal, but you see theres a "(Modded)" text drawn in as well. This means that you are currently loading into a game with modified files.

If you had hit the "Start Game" button like normal on the main menu underneath the logo, we won't use any of our loaded mod files. Additionally in the bottom right of the window you'll see text that indicates the amount of mods loaded alongside the version number and build date.

You won't see the "mods loaded" text if you hit "Start Game" from the main menu. A quick check here is a good way to make sure you're running an unmodified version in case you're playing multiplayer with your buddies.



Another feature of Workshop support is separate savefiles for modded sessions. Once you get to the Gamemode selection screen you'll see a friendly reminder that your single/multiplayer saves won't be overwritten.

Mods use savegame_modded.dat, savegame_modded2.dat, savegame_multiplayer_modded.dat and savegame2_multiplayer_modded.dat files in the Barony directory for reference.

Choose singleplayer and let's enter the game.

In game we can see our new podium! You can smash it to pieces if you like, one fireball spell should do the trick.

One issue - the model is facing the wrong way. I'd like the little ridge on the back to be on the other side of the model, to make the podium look like it's giving you an item. No problem, alt + tab back to the editor!



Make sure the Point tool is selected, left click the podium and hit F2. Since we want to rotate the model 180 degrees, we need to change the facing angle by 4 * 45 degrees. Since 8 is not a valid direction in the editor, we choose 0 to be 180 degrees around from 4.

Click OK and then CTRL + S to save. Alt + tab back to Barony!



A nifty thing about Barony maps is that they are loaded in on-the-fly, so any changes you make to a level will take effect the next time you load the map. Press ESC to open the pause menu and select restart.



Back in the game and our podium has rotated successfully, great job podium - looking good.

Now we need to give it an item for the player. Hit S again to open the sprites window, and select ITEM (sprite 8) from the window.



Once we have the item tile selected on our cursor, press F2 to see some of the options we have.

Items are one of the more versatile sprites in the editor. We can editor a bunch of things, like item type, status, blessing, quantity, identified status, and random category (we won't use this here, but for reference this one applies if the item type was random_item, you can select random magicstaff, random food for numbers 1-16).

For this mod I want to give the player a Ring of Slow Digestion. Status Worn, blessing 0, quantity 1, and unidentified. You can select the item type from the right-side window and left clicking on an entry. The rest you can click on the fields to edit or press TAB to cycle through which typing field is active.

(Quick note for Blessing: a value of "00" means the blessing is random within standard Barony limits, so -2 to +2. To choose +0 specifically just enter in the value of "0" and the little information text will update to show it's not random anymore.)



Here is the filled out item property window we were looking for. Make sure to hit OK and confirm the changes.



Move the item over the podium sprite and left click to drop. Sprites can occupy the same tile and the Barony engine will happily comply, some models may visually conflict and monsters may be trapped inside a door or chest when they spawn in.

If you have 2 overlapping sprites, the bottom-most on the tooltip list will be the sprite that gets selected with the Point tool. Press C to cycle the order of anything below your cursor when nothing is selected.



After pressing C, the podium sprite is now the bottom most. It doesn't matter in-game what the order is, this is just for moving objects around if you have a bunch of things stacked ontop of each other.

I'll note here that if you right click a sprite (selected or not), you'll create a duplicate into your cursor's selection and leave the old sprite where it was. Great for copying out copies of items or quickly placing furniture without going back to the Sprite window with S.

The copied items will have the same properties as the sprite you duplicated as well. So creating a bunch of rings of slow digestion is a matter of right clicking and left click placing them elsewhere.

To delete a sprite (if you ever accidentally right clicked something or otherwise), just press the DELETE key while a sprite is selected and it will disappear.

CTRL + S to save and let's alt + tab back into Barony and hit restart game once again.



Our ring is on the podium! There's special code in the game for tables and podiums to place items that are in the same location ontop of them. Use this for theming of rooms or shops.



Upon picking up the item, you'll see that it's unidentified, and gives us the ring of slow digestion message. Our map content is complete for our tutorial mod!

There's one more thing to show off - the Barony levels.txt file. This determines the order of maps to load in game. We don't need to change anything for our start.lmp map changes since that map name is used by the base game, but if we create new map names you'll need to know where to find them.

Now let's detour to the Steam Barony install folder, right click on Barony in the Steam Library list and click BROWSE LOCAL FILES... under the LOCAL FILES tab.



This will open up the location where Barony is installed, and if you're going to be creating content you'll need to know where these live. It should be something like C:\Program Files (x86)\Steam\SteamApps\common\Barony on Windows.

You'll see the following folders:

• Barony game maps and levels.txt are stored in the maps/ folder
  
• Images for icons are in the images/ folder
  
• Item images and definitions are in items/ folder
  
• In-game text is the lang/ folder
  
• models/ holds the .vox Voxel models for creatures/items/particles
  
• music/ and sounds/ folders keep our sound clips and music files safe
  
• books/ contains plaintext .txt files of classics like The Lusty Goblin Maid

Open up the mods/ folder and you should see our "myfirstmod" we created in the editor earlier. Open that up and you should see the same set of folders (except empty) you can place your custom content in for non-map related things. As of time of writing, only maps folders are supported in the Beta test. Open up the maps/ folder.



You'll see our modified start.lmp file, as well as a levels.txt file that mirrors the same content as the base game maps/levels.txt file. When we load the mod we're actually using this file but since it is identical to the base maps/levels.txt file there's no perceivable difference.



Open up levels.txt in a reasonable text file editor (Windows users can use WordPad, don't use Notepad as it doesn't like to display the information correctly). Right click the file and Open With... And select Wordpad. I personally use Notepad++ for all my text editing on Windows. Linux/Mac users shouldn't have an issue with any text editor so pick your favorite.



We can see a bunch of level names prefixed with "map: " or "gen: " and a title of the .lmp file to load. Each line is a new level, so map: start will load start.lmp first, then gen: mine spawns a Mines level on level 1. At level 5 we get the map: minetoswamp transition level.

A line with "map: XXXX" literally loads just the XXXX.lmp file in game, and is used for static maps like start.lmp, minetown.lmp, mysticlibrary.lmp and so on. None of the map data is randomly placed here.

A line with "gen: XXXX" loads XXXX.lmp as a base empty floor, and dynamically generates a level using our engine and places any subroom map files that exist with the name XXXX00.lmp, XXXX01.lmp, XXXX02.lmp and so on.

"gen: mine" for example loads an empty 40x40 room mine.lmp as the base, and fills it in with room names that follow the mine00.lmp, mine01.lmp, mine02.lmp convention. All the rooms are placed randomly until there's no more room to fit any combination of rooms. An exception is always made for mine00.lmp as the the 00 map defines the start location of the players in a room and will ALWAYS generate.

Important syntax here: the "map: start" or "gen: mine" REQUIRES a space between the colon : and the map file name.

Feel free to play with this as you wish, editing the levels.txt file shows the changes immediately after you select restart game in the pause menu.

mine.lmp in first person editor:


mine00 in first person editor (you can see the player spawn sprites):


For test purposes we'll experiment by removing all the "gen: mine" lines from the level.txt, and instead go from start.lmp to minetoswamp.lmp. Hit save on the text file, alt + tab to Barony and restart the game via the pause menu.



After picking up our new shiny ring, advance to level 1 of the game. You should now see as in the below screenshot, the mines to swamp transition level. We've successfully altered the map sequence!



That was a quick overview of how to edit Barony's map files. Next up I'll demonstrate how to upload your mod to our new Steam Workshop page! Feel free to undo our levels.txt changes if you like from here, and just keep the start.lmp map file as the only changed content.

Back in Barony, end the current game and jump back into the menu. Now click on the "Workshop" menu option to open up the window where we can edit our workshop items. You'll see a blank empty window like the "Custom Content" window showed, with a similar set of buttons.

There's "start modded game" which launches a game loaded with your selected mods, "get subscribed item list" which lists out your subscribed Workshop mods, and "my workshop items" which returns a list of the mods you've personally created. Both of these options will probably return with no results as expected.

In the top right corner there's a "upload workshop content" button which you should click to start the upload process.



At the "Upload to workshop" window, we've got a bunch of buttons to play with. The basic workflow is select a folder to upload, prepare for upload, edit title/description/Workshop tags and upload.

The top section is a mini folder browser to select your mod folder for upload. The "home directory" button takes you back to the steam install directory (loaded by default on upload window open) if you ever get lost. "open" will open up the highlighted folder and "previous folder" takes you up 1 level in the folder list. "new mod folder" is another place to create a blank mod template folder if you haven't done so already.

Click on "mods" from the folder browser to highlight and click "open".



You should now see the contents of Barony/mods/ which should just list your 1 mod folder, "myfirstmod". This is what we want to upload, not the maps/ folder.

Once this is highlighted, click "select folder for upload".



You'll see a preview of the files/folders inside the mod selected in the right-hand pane just to make sure it's not empty. Click "prepare" to begin creating a Workshop item.



A message should appear saying the item and file handle was created successfully. From here, you've actually got a blank Workshop item sitting in your account as hidden, and we now need to choose what content to upload to it.

You have 2 fields to enter text, a title and description. Enter a quick name and description as these can be changed later in the Steam Workshop itself. (Descriptions can support 10,000 characters in the workshop which is more real estate than we have here!)

Next are the Workshop tag fields, which users can use to filter your Workshop submissions. I've provided some default labels that MUST be set in the Barony client, you can't change these in the Workshop. Tags can be changed later on and I'll explain how to do that further below.

Let's select "dungeons" as a tag. After seeing an X showing the tag is selected, hit the "set item fields" button.



This does a quick sanity check on the title/description/folder path to make sure they all exist and are valid data. If everything is green, we're good to hit that "upload!" button!



You'll see some orange text showing the progress of the upload. The status of a Workshop item goes from 0, 1, 2, 3, 4, 5 and then it is completed. If anything fails at this point (could be bad internet connection, some error on Steam or Barony 's behalf etc) you can just close the window and re-enter all the info again and create another workshop item.

Status 2 and 3 is the uploading of file data which will take the most time typically for large files. Since we've only got a couple of kilobytes it should be quick.



On success, a friendly green message appears and will close the "Upload to workshop" window in 5 seconds. Wait for this to time out to return to the main "Workshop" menu window.

Now you can click "my workshop items" and see your mod in the list! I've got a bunch of test data in the screenshots so ignore those. For each entry in the row there's an option to "Update" the tags and content of a workshop item. So you'll be able to make map changes etc through this option. Give it a click.



You'll see a window similar to the previous upload window. Here the Title and Description fields are not editable, but the workshop tags are. Here I've also selected the "gameplay" tag and the message at the bottom says that only tags will be updated and no files. If I wanted to also change some content I can simply "select folder to upload" on the opened mods/ folder again. Pressing "deselect folder" will deselect any content changes for the upload.



Here is an example of pressing select folder with the wrong filepath selected, the "folder to upload: .\" means that I've incorrectly selected my base game directory to upload (100s of megabytes...) shown in the file preview which is not what you want to do. It should display ".\mods/myfirstmod".

The orange message tells me that content is also trying to be updated, not just tags. So deselect folder and hitting "modify tags/content" will only update the "gameplay" tag for my mod.



Here is an example of pressing select folder with the wrong filepath selected, the "folder to upload: .\" means that I've incorrectly selected my base game directory to upload (100s of megabytes...) shown in the file preview which is not what you want to do. It should display ".\mods/myfirstmod".

The orange message tells me that content is also trying to be updated, not just tags. So deselect folder and hitting "modify tags/content" will only update the "gameplay" tag for my mod.

Link to the Steam Workshop:
https://steamhost.cn/steamcommunity_com/app/371970/workshop/

Now we can jump onto the Workshop and see our uploaded content. Head to the above link or go to the Barony community hub and find the Workshop tab to open.

On your Steam avatar in the right section you can browse the files you've posted. Click on your mod in the Workshop item previews.



Here we see an overview of our Workshop item, the correct tags are there with a small 0.010MB file size. The game will automatically insert a version tag for the mod to say which version of Barony it was created in (V3.1.3). To update this, simply open the modify workshop item in Barony and just upload with no changes and the tag should get updated to match your game client when it changes in the future.

Give your creation a subscribe to allow yourself to download it.



Scrolling down we can also see the visibility of the item. By default all Workshop content is hidden so no need to worry about leaving unfinished business on the site. When you're ready you can hit Public to show your creations off!

Speaking of unfinished business, we missed a preview image! This is a file that can't be edited in the Workshop and needs to be present when we upload our content.



Go back to the file explorer and look at the Barony/mods/myfirstmod folder. We need to place an image file to serve as our Workshop preview page item. I simply took a screenshot and pasted/saved it in paint of my shiny ring on the pedestal.

The file name needs to be preview.png, preview.jpg or preview.gif for Workshop to accept it as a valid image file. The filesize also needs to be less than 1MB. Any dimension is fine, try make a square image to match the Workshop item display grid.

You can see my preview.png file in the folder list below. Alt + tab to Barony!



Open up the "Workshop" tab and hit "my workshop items" to see your newly created mod in the list. You can hover over the titles to show a preview of the title, description and list of tags on the item.

I sneakily edited the title and description from the Workshop page between screenshots and you can see the results below.

Hit "Update" again since we need to upload our missing preview image file.



Same story as last time, except we're going to select our mod folder again (Barony/mods/myfirstmod) as our preview image is tucked away in there. Click "select folder to upload" and the file preview list shows our preview.png file. Hit upload and wait for it to go green.



Once it hits green and uploaded, navigate back to the Steam Workshop page for our mod. We'll see our amazing screenshot is now inserted onto our Workshop item! From here if you want to add additional promo images for your mod you can do it in the Steam Workshop page, you just can't edit the first image outside of Barony.



Finally to finish things up for our mod, let's make this bad boy public so the world can bear witness to our creation!

Thanks for reading this tutorial, definitely took a bunch of effort to write! I followed these steps as I was writing them to make my first submitted Workshop Item WOJ's Start With Ring of Slow Digestion Mod

I extended the idea by spawning in 4 separate podiums and rings to support multiplayer. Make sure to consider if your map is viable in singleplayer only or can be opened up to multiplayer audiences. I will also do a quick summary of how to install and play this mod as a demo since the Steam Workshop has some quirks that unfortunately we cannot help.

Please leave any questions/comments/concerns for this tutorial in the comments below, Visit the Steam Forum thread to discuss general Workshop details further.

If any images need to be up-rez'd let me know as well. I ran all my screenshots through a dumb image resize tool that may have cut out some finer detail.