This project is a proof of concept. Although the approach proved to work quite well not enough interest was shown by the community during its prototyping and feedback phase. Adoption by the community is essential for this program to be useful as generating a useful set of conversion files can only be done by a community. For this reason no further development will be done.
This is a prototype of a program that allows you to change the style of DungeonDraft maps with the help of conversion files.
The underlying principle is that of a simple search and replace. You can replace materials with other materials, objects with other objects and so on. The program can be used for all kinds of things. For example:
- Convert between asset styles like 2-Minute-Tabletop, Crosshead and Forgotten Adventures
- Convert between summer, winter, spring and fall
A conversion file is a sort of look-up map which tells the program how the conversion should be done. For more information about creating conversion maps see "How to create conversion maps"
Download one of the pre-built ddstyleconverter.exe files from Releases
Go to Step 2: Install program
Install python3 (version >= 3.8) and add it to your PATH system environment variable.
You can check the version via CMD or powershell with:
python --version
Download or clone the repo.
Open a CMD instance inside the project root folder and create a virtual environment.
python -m venv .\venv
Activate the venv:
.\venv\Scripts\activate
Install pyInstaller package:
pip install pyInstaller
Run the build file:
.\scripts\build_for_windows.cmd
You should now have a ddstyleconverter.exe file under dist. After the build succeeded you can delete the venv you previously created.
Go to Step 2: Install program
Create an empty folder where you want to install the program for example C:\ddstyleconverter
Copy ddstyleconverter.exe into that folder.
Optional: Add the installation path to your PATH system environment variable. This enables you to execute the program from anywhere which makes it much easier to use.
Delete ddstyleconverter.exe file from the installation directory.
Optional: Remove the path to the installation directory from the PATH system environment variable.
An up-to-date Ubuntu 20.04 should have python >= 3.8. Check it with:
python3 --version
From here on pythonX will be used as placeholder for the python you should use. Depending on your system you need to
replace X with 3, 3.8, 3.9 or 3.10 .
Install python version>=3.8 if not yet installed.
sudo apt install pythonX
Download one of the pre-built ddstyleconverter files from Releases
Go to Step 2: Install the files
Install python if haven't already.
Download or clone repo.
Create a venv inside the repo:
sudo apt install pythonX-venv
pythonX -m venv ./venv
Activate venv:
source venv/bin/activate
Install pyInstaller:
pythonX -m pip install pyInstaller
Now run the build script:
./scrips/build_for_ubuntu.sh
Copy the ddstyleconverter file either from dist from where you downloaded it to usr/bin/
Make the file executable:
sudo chmod ugo=rx usr/bin/ddstyleconverter
Delete the file /usr/bin/ddstyleconverter
IMPORTANT:
Add all the asset packs you need to the map before you do the conversion.
If you try to open a map that has references to assets of an un-imported asset pack it will just load forever.
ddstyleconverter [--verbose-info, --verbose-debug, --version, --help, --out output_path,--cmap conversion_map_path, --create-cmap] target_path
target_path: Path to the file which should be processed.
--out output_path: Specify output_path as file path to where the result should be written. The file itself must not exist but the parent directory must.
--cmap conversion_map_path: Specify conversion_map_path as path to the conversion map file.
--verbose-info: Enables verbose output to console
--verbose-debug: Enables very verbose output to console
--version: Print version and exits
--help: Display help and exit
--create-cmap: If this option is used the target file is not converted. Instead the target file is used to automatically
generate a conversion map. For more information about that see "How To create conversion maps". This option does
does not require a --cmap argument but can be combined with a --out argument.
Converting a map:
Ubuntu:
ddstyleconverter path/to/file.dungeondraft_map --out path/to/output_file.dungeondraft_map --cmap path/to/conversion_map.json
Windows:
ddstyleconverter.exe path\to\file.dungeondraft_map --out path\to\output_file.dungeondraft_map --cmap path\to\conversion_map.json
When one of the paths has \' at the end, the arguments will get mixed up. This is a problem with how python handles
arguments and probably can't be fixed. For example on Windows ddstyleconverter.exe '\folder name with spaces\'
will fail but ddstyleconverter.exe '\folder name with spaces' will succeed.
Conversion maps can be created from DungeonDraft maps. Currently, only object conversions are supported.
The DungeonDraft map has to have at least two levels. Objects on the first level will get mapped to the closest
object on the second level. Relative rotation, translation and scale will automatically be calculated. For an example of
such a DungeonDraft map have a look at example_maps/vanilla_to_dungeondraft.dungeondraft_map.
To create a conversion map from a DungeonDraft map use:
ddstyleconverter --create-cmap path/to/dd_map.dungeondraft_map on Ubuntu
ddstyleconverter.exe --create-cmap path\to\dd_map.dungeondraft_map on Windows
Conversion maps are simple json files. Don't give up if you're not familiar with the json format. The json syntax is really easy to understand and requires zero programming knowledge. I recommend downloading and installing a text editor that supports the json format, for example Notepad++.
Before we can create a conversion map we need to understand the format of dungeondraft_map files.
Don't worry, it's really simple.
Open up a dungeondraft_map file with your chosen text editor.
If you are using Notepad++ tell the program that it should interpret the text as json via Language > J > JSON.
What you will see is text in json format. Take a while to understand the basic format.
The important parts are under world/levels (reading: Under world and there under levels),
here you see the contents of each level.
The contents are conveniently split into: patterns, walls, portals, terrain, materials, paths, objects and roofs
Have a look at each of those entries. Most of them are lists (surrounded by []) of simple sub-entries.
For example an objects entry has the format:
{
"position": "Vector2(1036, 1537.44)",
"rotation": -0,
"scale": "Vector2( 0.892452, 0.892356 )",
"mirror": false,
"texture": "res://packs/xjCzavyl/textures/objects/anvil_01.png",
"layer": 100,
"shadow": false,
"block_light": false,
"node_id": "26"
}
The important parts here is the texture entry. That is what we want to replace.
To create a conversion file create a new file and give it the file extension json. The basic format of a conversion map is:
{
"style_maps": {
"materials": [],
"objects": [],
"paths": [],
"patterns": [],
"portals": [],
"roofs": [],
"terrain": [],
"walls": []
}
}
All entry types extend the same base entry, which has the format:
{
"from_texture": "",
"to_texture": ""
}
The from_texture and to_texture entries have to contain values from the respective
texture entries from the dungeondraft_map file.
For example an entry under materials would look like this:
{
"from_texture": "res://textures/materials/lava_tile.png",
"to_texture": "res://packs/xjCzavyl/textures/materials/lava_tile.png"
}
Which reads as: Replace all texture values within materials entries that have the value
res://textures/materials/lava_tile.png with res://packs/xjCzavyl/textures/materials/lava_tile.png
The easiest way to find those texture values is to have a dungeondraft_map file which contains exactly two things:
- The object/path/wall/etc you want to be replaced
- The respective object/path/wall/etc with what you want to replace the first thing. You can only replace a path with path and an object with an object and so on.
I recommend putting them on different levels to make it easier to compare them. Such a dungeondraft_map file would look something like this:
{
"header": {
"creation_build": "1.0.3.2 tricky vampire",
"creation_date": {
"year": 2022,
"month": 4,
"day": 21,
"weekday": 4,
"dst": false,
"hour": 11,
"minute": 24,
"second": 25
},
"uses_default_assets": true,
"asset_manifest": [
{
"name": "Crosshead",
"id": "xjCzavyl",
"version": "1",
"author": "Crosshead",
"custom_color_overrides": {
"enabled": false,
"min_redness": 0.1,
"min_saturation": 0,
"red_tolerance": 0.04
}
}
],
...
},
"world": {
...
"levels": {
"0": {
"label": "Crosshead",
...
"objects": [
{
"position": "Vector2( 1280, 2048 )",
"rotation": -0.698132,
"scale": "Vector2( 0.552237, 0.552487 )",
"mirror": false,
"texture": "res://packs/xjCzavyl/textures/objects/book_01.png",
"layer": 100,
"shadow": false,
"block_light": false,
"node_id": "2a"
}
]
...
},
"1": {
"label": "Ground",
...
"objects": [
{
"position": "Vector2( 1280, 2048 )",
"rotation": 0,
"scale": "Vector2( 1, 1 )",
"mirror": false,
"texture": "res://textures/objects/activities/administration/book_04.png",
"layer": 100,
"shadow": false,
"block_light": false,
"node_id": "3d"
}
],
...
}
}
}
}
As you may notice both objects have completely different scales and rotations.
Because of that the objects entries of the conversion maps supports rotation, translation and scale
The objects entry to replace "res://textures/objects/activities/administration/book_04.png" with "res://packs/xjCzavyl/textures/objects/book_01.png" would look like this:
{
"from_texture": "res://textures/objects/activities/administration/book_04.png",
"to_texture": "res://packs/xjCzavyl/textures/objects/book_01.png",
"translation": "Vector2(-11.58, -1.95)",
"rotation": -0.698132,
"scale": "Vector2( 0.552237, 0.552237 )"
}