Introduction[]
Mods are supported for MacOS, Windows and Linux! You cannot install them on the mobile version.
You can download mods from the Official WorldBox Discord server or GameBanana.
To install mods you first need a mod loader. For NML (NeoModLoader) and BepInEx Installation guides scroll down. If you are using NCMS (outdated mod loader) it is recommend you swap it out with NML.
Big Thanks to Keymasterer ._. for this guide (this page directly quotes steps from this guide)
NML (NeoModLoader) Installation[]
NML is a very new mod-loader for the game that acts as the official replacement for NCMS. To use NML, remove NCMS first if you still have it installed (NML has full support for loading NCMS mods, so you won't miss out on any mods by doing this). This section takes info from keymaster's guide.
Windows[]
Note: Make sure hidden files are shown, you can google how to do this if they're not shown.
1. Enable "Experimental Mode" at the bottom of the game's setting menu
2. Download NeoModLoader.dll
3. Go to StreamingAssets/mods file of the game. You can do this by opening Steam -> Library -> Worldbox -> Gear Icon (far right) -> Manage -> Browse Local Files -> worldboxData -> StreamingAssets -> mods
4. Move the NeoModLoader.dll file into the "mods" folder you just opened. If there are any files/folders with "NCMS" in their name (e.g. NCMS_memload.dll, NCMS, ...), delete them.
5. Once you load your game a new folder called "Mods" should appear directly in your "worldbox" folder. This is where you would put actual mods. Additionally, you'll also find a new button with the NML logo in the main tab in-game.
You're Done!
MacOS[]
1. Enable "Experimental Mode" at the bottom of the game's setting menu
2. Download NeoModLoader.dll
3. Go to StreamingAssets/mods file of the game. You can do this by opening Steam -> Library -> Worldbox -> Gear Icon (far right) -> Manage -> Browse Local Files. Then, right-click the worldbox icon in the worldbox folder, select "Show Package Contents", then go to Contents, then Resources, then Data, then StreamingAssets, then mods.
4. Move the NeoModLoader.dll file into the "mods" folder you just opened. If there are any files/folders with "NCMS" in their name (e.g. NCMS_memload.dll, NCMS, ...), delete them.
5. Once you load your game a new folder called "Mods" should appear directly in your "worldbox" folder. This is where you would put actual mods. Additionally, you'll also find a new button with the NML logo in the main tab in-game.
You're Done!
If you have problems seek help on the worldbox discord server.
Linux (guide might be outdated): https://steamcommunity.com/app/1206560/discussions/0/3418808280406220269/
BepInEx Installation[]
Since the installation of BepInEx is completely different between Windows and MacOS, this part of the guide will be split into two parts, one for Windows, and one for MacOS. This section takes info from keymaster's guide.
WINDOWS GUIDE (For linux/mac: here)
Windows[]
Note: Make sure hidden files are shown, you can google how to do this if they're not shown.
1. First download BepInEx_x64_5.4.21.0.zip from the BepInEx GitHub repository. The _x86 or _unix versions of it won't work on Windows.
2. Open your worldbox folder. You can do this by opening Steam -> Library -> Worldbox -> Gear Icon (far right) -> Manage -> Browse Local Files.
3. Drag the contents of the BepInEx_x64_5.4.21.0.zip into your worldbox file
4. Your worldbox folder should contain a folder called BepInEx, a file called winhttp.dll, a file called doorstop_config.ini, a file called changelog.txt, and one called worldbox.exe. Some of the file extensions might not show up for you if you never disabled the "Hide hidden extensions" option in your file explorer. If the folders/files are there, right-click worldbox.exe and select "Run as administrator" to allow it to finish its installation!
5. After granting the permissions and letting the game run, a new folder should appear in your BepInEx folder called "plugins". Said folder is where you put BepInEx mods.
You're Done!
An Image to help
MacOS[]
1. First, download BepInEx_unix_5.4.21.0.zip from the BepInEx GitHub repository. The _x86 or _x64 version of it don't work on MacOS.
2. Open your worldbox folder. You can do this by opening Steam -> Library -> Worldbox -> Gear Icon (far right) -> Manage -> Browse Local Files.
3. Drag the contents of the BepInEx_unix_5.4.21.0.zip into your worldbox file
4. Your worldbox folder should contain a folder called BepInEx, a folder called doorstop_libs, a file called run_bepinex.sh, a file called changelog.txt, and one called worldbox which has the icon of WorldBox.
5. The next step is to open run_bepinex.sh with a text/code editor of your choice and to search for 'executable_name=" '.
6. There should only be one result in the file. Go to said search result, and have the line say 'executable_name="worldbox.app" ' 7. Once you did that, save the file and completely close it. After you're done with these steps, you're ready to run worldbox with BepInEx on MacOS. But to do this, you can't just open the game like you'd usually do, you instead have to go into a terminal and use sh to run the run_bepinex.sh file.
You're Done... almost (read below to do what is mentioned in step 7)
1. Right-click worldbox.app in your worldbox folder, right-click it, and select "Get Info". In the menu that appears, right-click the path next to the "where" attribute and select "Copy as Pathname".
2. Once you have the path copied, go into a terminal of your choice (the default terminal that MacOS provides in called 'terminal', you can search it using spotlight search).
3. Once you're in the terminal, type 'cd ""', use your arrow keys to go between the two " characters, and paste in the path that you copied earlier with cmd+v (⌘+v).
4. If it does, press the return key (⮐) (the one that is used to make a new line when writing text in applications like word/sending messages in discord).
5. After doing so, try to type 'ls' (written with a lower case L, NOT an upper case i), and run said command with the return key (⮐). The text that the terminal displays in response to the command should list worldbox.app and the files from BepInEx which you put into the worldbox folder earlier. The Mods folder will only be there if you also have NCMS/NML installed.
6. If you did do everything correctly and see the correct files/folders, type 'sudo sh ./run_bepinex.sh', and press the return key (⮐). You'll be asked for the password of the user that you're currently logged into by MacOS, because the sudo command requires administrator permissions. Just type it in (you can't see it at all while typing it in), and press the return key (⮐) again. If you did everything correctly, your terminal will start displaying a lot of text that seemingly doesn't make any sense, and after a few seconds, worldbox will open itself. There's a very low chance that you might get an error message. Don't worry if this happens, it kinda just does sometimes, and you can try to run the command again. Once you ran the command successfully, your BepInEx folder should get a new folder inside it called "plugins". Said folder is where you put BepInEx mods.
You're Really Done!
Videos (might be outdated)[]
You only need to watch one of the videos as each teach you full installation in their video.
https://youtu.be/KfEOEFTfboQ - Andreiavich, Mod Installation & Simple GUI guide
https://youtu.be/kep3Tp-5a_U - DogsAreBetterThanCats, Mod Installation
Installing Mods[]
This section's info is entirely taken from keymaster's guide.
NML (NeoModLoader)[]
NML supports loading both mods made for NML and mods made for NCMS.
Download the mod and extract it into another folder. Next, check if the folder which you extracted the mod into only contains one other folder or several other folders/files like mod.json/Code/icon.png directly inside it. After you checked this, go to your worldbox folder (in the Steam library menu for WorldBox, select the settings wheel on the right, choose "Manage", and then "Browse local files" to find your worldbox folder), then go to the Mods folder directly within said worldbox folder. If the folder that you checked earlier contained several files/folders directly inside it, move the whole folder into your Mods folder. If there was only one other folder and nothing else directly within the folder that you extracted the mod into, only move said folder into your Mods folder.
BepInEx[]
The first step for installing a BepInEx mod once you have BepInEx installed correctly is to download the mods’ zip archive. After that, head over to your worldbox folder (in the Steam library menu for WorldBox, select the settings wheel on the right, choose "Manage", and then "Browse local files" to find your worldbox folder). From there, go to the BepInEx folder, then the plugins folder inside your BepInEx folder. If there's no plugins folder, that means you messed up some step of the BepInEx installation. Otherwise, move the contents in the zip archive of the mod directly into your plugins folder.
Native Mod Loader[]
In addition to mod-loader like BepInEx or NML, a small number of mods also use the games’ native mod-loader that NML itself uses to launch. Based purely on mod files, there's no easy way to differentiate between mods for BepInEx and ones for the native mod-loader. Because of this, it's vital to check the description/installation instructions of the specific mod to figure out what type of mod it is. To actually install the mod, move its DLL files to the same StreamingAssets/mods folder that the NML mod-loader goes into (reference the section on how to install NML if you don't know where that is).
FAQ[]
Taken directly from keymaster's guide. Please view it for more context if needed.
Is BepInEx compatible with NML?[]
Yes, they are fully compatible. The only things that might be incompatible are two individual mods, please refer to the section here about compatibility for more information.
Should I use NML or NCMS?[]
NCMS has officially been discontinued by its own creator because NML is better than NCMS. There's no good reason to use NCMS for anything.
NML isn't loading any mods for me, why?[]
Make sure that you deleted NCMS, as NML doesn't load mods from the Mods folder if it detects that NCMS is installed.
NCMS is broken, how do I fix it?[]
NCMS is an outdated/obsolete mod-loader, and there's no reason to still use it. Delete any files associated with NCMS, and download NML instead. Instructions for downloading NML, if you need them, can be found further up in this guide!
NML is broken, how do I fix it?[]
It's most likely only broken for you because you messed up a step of the installation. Please check the section of this tutorial about installing NML to find out what step you messed up. Common mistakes are not enabling experimental mode/incorrectly inserting NeoModLoader.dll.
No BepInEx/plugins folder is appearing, how do I fix this?[]
This probably happened due to an incorrect BepInEx installation. Please check the section of this tutorial about installing BepInEx for your OS to find out what step you messed up.
I don't understand how to use X mod; can you please explain it?[]
If a mod has to be installed in specific ways or has specific key binds or anything along those lines, this will usually be mentioned in the mods’ description. Please make sure to always read said descriptions before using the mods!
I don't really understand this guide, how do I do X thing?[]
The instruction here should be easy to understand, but if you feel a need to have someone help you, feel free to ask for help in the modding-talk channel on the official WorldBox Discord server!
Creating Mods[]
WorldBox Modding will consist of either code changes or texture changes. These changes affect how the game looks and works.
For coding, you will need basic C# knowledge and a decompiler of choice.
Texturing requires a tool that can extract and import textures. You can find tutorials for both types of editing, this guide will assume you have some prior experience.
Modding: Coding[]
Coding changes in this game are made through a file called Assembly-CSharp.dll. This file once opened by a decompiler such as DnSpy, or DotPeek will show a list of all the classes and code. There are notable library classes such as ActorStatsLibrary, ActorTraitLibrary, and PowerLibrary which let you edit Stats, Traits, and Powers with ease. Though these libraries do not contain all the code for their actions. Using DnSpy your analyzer can find your code references throughout to find the code you need. Generally, you'll find what you need by searching its name in your search bar. The other larger notable classes are Actor, ActorBase, and Mapbox containing all sorts of random information, and maybe the best place to look if you cannot find what you need.
Check this page for Code Examples.
Modding: Textures[]
Texture editing is possible through editing a variety of files ending in ".assets". You'll use tools such as UTinyRipper, Asset Studio, and Unity Asset Bundle Extractor to extract images and audio. To import/change these images to make a texture change you'll use Unity Asset Bundle Extractor Also known as (UABE). Using UABE you can edit imagery, add resources (audio, image, sprite, etc), and edit audio. The game uses sprite sheets and will consist of all zoomed-in sprites under "sactx-1024x1024-Uncompressed-WorldAtlas-5e0836b1". The UI is in a similar file with "SpriteAtlas" instead of WorldAtlas. These two atlases contain a large number of sprites and any changes you wish to make on sprites contained within them can only be made through them. Any Icons or other images can be found and edited individually.
Note: Texture changing through processes such as UABE is tedious and will out-date every update, a better idea is to only use these processes for texture extraction and make an assembly or bepinex mod to actually import the sprites or images.
Modding: BepInEx[]
Useful links:
Modding: How to use NCMS to create mods[]
[Outdated Section, might still have some useful Info]
NCMS provides easy modding for Worldbox. In order to create one, you need a config.json file with the mod name, description, icon path, etc of the mod. Also a code file to hold all the code (in C#). To add textures, you can create a GameResources file and put the texture inside.
Modding with NCMS requires .dll decompiler mentioned on Moding:Coding (Jetbrains Dotpeek is recommended). With the decompiler, use it on the Assembly-CSharp and search “library” . After that, you can just look at the librarys to see examples of the modding content your gonna make. (Like BuildingLibrary for building mods)
YouTube video that further explains the usage of NCMS on Worldbox: