Matrix Games Forums

Hey friends! I'm the guy who is making the Distant Worlds 2 Refreshed mod series, available on Steam Workshop. Over on Discord some folks were asking how I add new art assets to DW2. I promised to write up a guide outlining the steps (as of the publishing of this post).

Until things change, most DW2 modding is still a bit--well...difficult. The DW2 team have future plans for modding tools and opening up various parts of the game for more types of modding (code mods), and for letting modders change certain things they can't as-of-now. However, due to the barriers to entry for DW2 modding, most folks stick with just changing the .xml files you can find in your Distant Worlds 2/data folder (since you can just have loose .xml files in a new mod folder and the game will overwrite things (kinda like modding in Distant Worlds 1)).

For anything art-related, though, it takes a bunch of extra steps. So let's get started.

For the purposes of this guide, we will be replacing a vanilla player flag graphic with a new one. Adding/replacing other art assets will follow the same basic steps. Adding new assets will typically also involve editing a game .xml somewhere so DW2 knows where an asset is and when to use it.

I'm NOT a code guy, I'm a 2D art asset guy. So please excuse the clumsy descriptions and brute-force methods of getting through some things.

Background info:
DW2 uses bundles for its art assets, not loose files.

These bundles are listed in your Distant Worlds 2/data/db/bundles folder. There are a lot of bundles in that folder, but the one that holds the most stuff we will probably utilize is the CoreContent.bundle. Ultimately we will need to build our own bundle for our mods, using the folder structure found within the various game bundles.

When working to replace old art assets or place new art assets, you'll need to know where assets live in DW2 bundles (there are directory structures embedded within bundles...the game data files (.xmls) usually reference art assets living within these directories). In DW1, you could just have loose files with the same directory structure, but for now DW2 requires us to dance in and out of these "bundles". So...here we go.

To look inside a bundle, you'll need to use the DW2 Bundle Tool available in a pinned message in the #mod channel on the DW2 discord.

In addition to just browsing inside the bundle, you'll also need to use that tool to "extract" the various files within. You'll ALSO ALSO then need to use that tool to "convert" the various art assets into readable files. Extracting files by themselves brings out extension-less files. The tool is used to convert them. Be aware is a command-line thing, so you'll need to use proper syntax when doing all that.

Install the Bundle Tool via the instructions in the #mods channel on Discord. There's a "help" command you can run via command prompt that describes the ways you can use the tool.

For example, to "list" all files within a bundle, you'd run this command via the command prompt from within the directory you have your Bundle Tool installed:
dw2bt.exe list "<<YOUR DW2 GAME DIRECTORY HERE>>\data\db\bundles\CoreContent.bundle".

Use quotes and put where you have DW2 installed at the front and you should get a huge list of files within that bundle. For art assets we're typically interested in files that have the "texture" descriptor in the list.

For flags, you could then "extract" all flags by using this command:
dw2bt.exe extract "<<YOUR DW2 GAME DIRECTORY HERE>>\data\db\bundles\CoreContent.bundle" UserInterface/Flags/*.*

In the above extract example, it would place all the extracted files in a directory UserInterface/Flags within the location you've installed the Bundle Tool.

You would then need to convert each one to a .png. You'd do that this way:
dw2bt convert "UserInterface\Flags\Human_1" "UserInterface\Flags\Human_1.dds"

Adding a new file

It can be daunting to get things listed, extracted and converted, but I've done that for you, so for this guide I'll just help you skip all of that.

Remember, DW2 Player Flags live in the CoreContent bundle in the following directory:
UserInterface/Flags

They are .png textures. They are 400px by 250px.

There, done! NOW we can get started.

/========== ADDING A SINGLE PLAYER FLAG (a modding guide to DW2) ==========\

/// Step 1 -- Create your player flag

Here's one. Poof! That was easy.
/// Step 2 -- Install Stride Game Engine and .Net 6.0 SDK

(yes, really). You'll need .Net to let Stride load things properly. And you'll need Stride to create bundles. DW2 was built in Stride. That's the process for now.

https://www.stride3d.net/download/

You can install the most current version of Stride. Old DW2 modding instructions mention a very old Stride version called Xenko, but Xenko became Stride...so it's just the newest version of that.
/// Step 3 -- Create a new project in Stride

Start Stride.

Pick "New project" and "New game". Then name your project.
Then just accept the defaults for the next screen. Click OK.
### CONTINUED IN NEXT POST ###

### PART 2 ###

/// Step 4 -- Clear out most of the default stuff.

While in the "Assets" folder of your project (see the Solution Explorer window in the lower left pane), select and delete everything except "Skybox texture" in the Asset viewer in the bottom center pane.
Without a bunch of visual assets, your windows will re-arrange themselves. In the Solution explorer (left pane) go from Assets to the Code folder.

Erase the Basic Camera Controller thing there.
Now let's save the project.
You'll be asked to reload some stuff. Yes, do that.
### Continued in next part ###

### PART 3 ###

/// Step 5 -- Create your folder structure

Remember I helped you cheat in the introduction of this guide where I told you where the Player Flags live? Well this is why. We have to build our folder structure in our game project to match the folder structure within the DW2 game bundles. Since we're replacing an existing player flag (remember, DW2 doesn't let us add new flags yet), we have to know where to place our custom flag.

Player Flags live in:
UserInterface/Flags

So, in our game project under the Solution Explorer, under Assets...create a folder called UserInterface. Then create a folder within UserInterface called Flags.
/// Step 6 -- Drag in your custom flag

Go find where you saved your 400px by 250px .png image you want for your player flag. Drag it into the Asset viewer window in Stride.

Stride will sense you are brining in a texture and will give you some options as to what type of texture this will be. Choose the COLOR option.

Stride will then ask if you want to copy the asset into your project. Pick yes.
Stride will then ask if you want to put it in the default location. Pick yes.
### CONTINUED IN NEXT POST ###

### PART 4 ###

/// Step 7 -- Rename and "root" your flag

Since we can't add new flags, we have to replace one. For this example, we're going to swap out the first Human flag in the game (called Human_1). You can swap out another one if you like. Here are the flag names in the game:
Alright. So in this guide we're going to add a new Human_1 flag. In Stride, rename the flag you dragged in as Human_1. Also, right click on your flag in Stride Assets and select the option "include as root asset". A little blue dot should light up in the upper left of the asset thumbnail in Stride.
Double check the flag is in the Assets/UserInterface/Flags folder in your Stride project.

Save the project and exit Stride. Yes, exit Stride.

/// Step 8 -- Editing some Stride stuff

So..again...DW2 modding is strange. We'll need to do some deleting and editing of Stride files before we can continue.

Go to where you have your Stride projects. Default location is under Documents/Stride Projects. Find your project name.

Delete the Bin folder. Yes, just yank it.
Now, go into your (project name).windows folder and use a text editor to edit the .sdpkg file (I recommend Sublime Text (https://www.sublimetext.com/) but you do you.
### CONTINUED IN NEXT POST ###

### PART 5 ###

(continuing with Step 8)

Change your .sdpkg file to include the following parameters under the Bundles: portion. Replace the [].
If you don't do this, the project won't create a bundle you can use for your mod.

Under the Name: portion of the Bundles: section, you can call it whatever you want. I'm just going with MY_MOD_NAME for the guide.

Notice you are outlining the PathSelector to highlight just the first folder in your created folders (UserInterface). Stride will grab anything else within UserInterface. With this, you're pretty much telling Stride to make a bundle called MY_MOD_NAME.bundle and include all the stuff you have in Stride under the UserInterface folder. We just so happen to just have the Flags folder.

You can also see that the RootAssets are listed at the bottom of the file already. Good job.

Save the file.

/// Step 9 -- Build the project

Re-open Stride. Re-open your project.

Near the bottom of the screen, click the "output" tab so you can watch for any errors. Your screen will probably be blank (no green text...I took this pic out of order)
Click the Build Project button to the left of the green "play" button icon.
If the gods are kind, you'll just have a bunch of green text (maybe one line of yellow...that is fine). If you have a bunch of red text, I'm afraid I'm not sure what happened. This is where my "not a coder" idiocy stops me from being helpful. Sorry, friend.

But let's assume you have that green DONE near the bottom of the Output pane. That means your bundles have been created. Let's keep going.

### CONTINUED IN NEXT POST ###

### PART 6 ###

/// Step 10 -- Grab your bundles and make your mod

Alright! Bundles should be made. Let's go get them.

Exit Stride.

Go back to where your Stride Project is.

Remember that Bin folder we deleted back in Step 8? It should be back now!

Go into the Bin folder, then follow the path outlined in the screenshot until you get to your bundles.
Copy the two bundles outlined in the above screenshot. One should have a long, obnoxious name.

Now...head over to your Distant Worlds 2 folder. Go to your Mods folder.

If you haven't already, create a folder for your mod. Call it whatever (in this example it's called MY MOD TITLE).

Paste the two bundle files in your mod folder.

ALSO, create a new text file called mod.json.
Open this blank new text file in a text editor.

Fill it out like this.
Start things off with a {

Then add the shown stuff.

Then close things with a }

This .json file is what tells DW2 about your mod and what .bundle file to include.

Save the .json file.

/// Step 11 -- Start DW2 and start your mod

Open DW2.

Go to Modifications.

Your mod should (hopefully) be listed. By enabling the mod, you will have successfully replaced the original player flag with your custom one.
BE SURE YOU EXIT DW2 AND RESTART DW2 AFTER ENABLING YOUR MOD.

Yes, you have to exit and restart DW2. It's a quirk.

Congrats!

/========== NOTE ON REBUILDING YOUR BUNDLES ==========\

If you forgot something or wanted to further change something, it's important that you go back into your Stride Project files and re-delete your BIN folder again BEFORE rebuilding the project in Stride.

If you leave your old BIN folder in place, Stride will create additional incremental bundles and I'm not sure how that affects stuff.

By deleting the BIN folder before rebuilding the project, Stride will just make a fresh BIN folder with your bundles that you can copy/paste as described in the guide.

### END OF GUIDE ###

Awesome! Thanks so much for writing / drawing this up!

Thank you so much!
This is very very helpful!

But as always I have the biggest problem in starting stride.
but.. I am on it..
what worked for me (windows 10):
- downloaded and installed visual studio 2022 without anything clicked
-installed .net 6.0 sdk: https://dotnet.microsoft.com/en-us/down ... -installer

-restarted stride and installed the stride plugin for 2022
then it started up, yes!!

before we can start a new project, I had to start visual studio 22 after installing the stride tool for vs2022.
THEN, finally, i could start a project with stride 4.1

WHOOO

edit:
Ok, NOW, afer i found the bundle extractor exactly where you mentioned it (discord DW2 channel) pinned and explained there..
I extracted all the bundles that were mentioned for the flag-example.

what I have done:
etxract the content into a txt file like this:

DW2BT.exe list "Q:\GOGspiele\Distant Worlds 2\data\db\bundles\CoreContent.bundle" > "Q:\GOGspiele\Distant Worlds 2\data\db\bundles\CoreContent.txt"

result: see attachment.
now there are other files like:
CoreContent.fdbc1eb6873d9b08f66950156f7f9267.txt

content:
"No files match."

so, i guess usually we have to etxract all bundles without that serial number, and search for content we want to mod from there.
Thank you, it works.
There is enough work to do - because the data format is still unknown for many things.
I will try to help the translation team with that new knowledge.

Hey @rxnnxs! Sorry for just getting to this. I haven't been on the forums much these last couple of weeks!

Glad you're figuring things out.

Yes we extract specific files out of the bundles without the serial number in the name. Both bundles have to exist...but we really only interface with the bundles with the short names. My lack of coding knowledge shows up here in that I don't know why that is

When you "list" files in the bundles, you'll see several types of files. I've mainly been interfacing with the files listed as "textures". Those files can be converted with the bundling tool into .pngs or .jpgs (I haven't tested out other image formats). The bundling tool seems to know how to convert bundled files into several extensions. There are 3D models and fancy things I haven't messed with yet. I'll try my hand at shipsets down the road...I'm focusing on 2D stuff first.

In the original post, edited the content a bit to provide instructions on using the Bundle Tool.

salemonz wrote: Sun Jan 07, 2024 2:06 am
(continuing with Step 8)
..snip
Change your .sdpkg file to include the following parameters under the Bundles: portion. Replace the [].

mod14.PNG

If you don't do this, the project won't create a bundle you can use for your mod.

Under the Name: portion of the Bundles: section, you can call it whatever you want. I'm just going with MY_MOD_NAME for the guide.

..snip

Hey guys.. if anybody is reading this and knows how to prevent stride to stall when changing bundes[] to the text described above.. please explain how to do it.

In this Video you can see what happens if I try to rename the Bundles[] line

Elliot told me what was the Problem:
I used Tabulator instead of white spaces..

Link

And NOT ONLY THAT!

You have to place exactly the number of spaces into it: If that works, and stride loads you project, you can be happy..