- Joined
- Jun 30, 2017
- Messages
- 50
Introduction
Patchwork - MapConverter is a Node.js console application used to convert between warcraft III's map binaries and their textual representation. This allows for easier way of distributing map's source code through git and potentially being able to resolve merge conflicts for stuff that is typically edited through the World Editor, like terrain or Object data.
Additionally, patchwork can extract trigger files into multiple files replicating the category tree from trigger editor into your filesystem and also compile this same directory tree into a valid triggers/custom scripts files.
Requirements
To install and use this tool, you will require the following:
- Node.js v21 or higher
- npm package manager installed (bundled with Node.js installation)
- node added to system PATH variable (also an option in Node.js installation)
npm i -g patchwork-mapconverterWarning
In case you're updating from 0.0.7 version you must convert your GUI triggers back into war3map format before updating!!!How to use
Running
npx patchwork-mapconverter will display the options and commands this tool has to offer:To use this tool, you must provide it a triggerdata.txt file, which you can obtain by opening wc3 archive in CascView. It can be found on
_retail_/UI path.To provide this file you've extracted to the tool, you must active the following option
npx patchwork-mapconverter -td <filePathToTriggerData.txt>Note: This tool works for maps saved in latest World Editor, I can't guarantee they will work for map files created/saved using older World Editor versions.
I believe most of these descriptions offer good enough explanation of what specific options do. However, I will point out a few particularly useful features:
Smart imports option works differently depending on command:
war2json
When this command is chosen along with this option, smart imports will copy all files that are defined inside war3map.imp (world editor's imports registry file) and paste them into the<output>/<importsFolderName> path, effectively separating the import files from the other map files.json2war
When this command is chosen along with this option, smart imports will copy all the files from<input>/<importsFolderName> into <output> but retaining the relative path that was inside the <importsFolderName>, furthermore the option also generates its own war3map.imp file into the output path, populating it with all those copied files within <importsFolderName>, eliminating the need of doing imports by using the imports manager in World Editor.Compose triggers options also works differently depending on command:
Furthermore, for every category the tool will generate a .ini file which specifies a few category options and most importantly, the order of variables/custom scripts/triggers inside said category, because one cannot rely on alphabetical ordering of files (which is done for folders) when it comes to custom scripts due to map loading process.
war2json
In this mode, the tool will take war3map.wtg and war3map.wct files (GUI triggers, and custom scripts) and export them into<output>/<sourceFolder> while retaining the relative path that was found in the trigger editor. Trigger Library and Category elements are converted into folders, while everything else turns into files. The kind of file depends on the configured extension. (Note: changing the file extension for those sub-options will not cause the tool to change the format these triggers are exported as, they will always be JSON)Furthermore, for every category the tool will generate a .ini file which specifies a few category options and most importantly, the order of variables/custom scripts/triggers inside said category, because one cannot rely on alphabetical ordering of files (which is done for folders) when it comes to custom scripts due to map loading process.
json2war
In this mode, the tool will take all files and folders found inside<input>/<sourceFolder> and convert them into categories, triggers, variables, scripts, etc.. retaining the relative paths and trigger editor element ordering stored in .ini files, if they're provided. If the ordering is not provided, the order of these elements is at the discretion of whatever the Node.js runtime decides (safe to assume that it will be random)With this option, you can specify a file with Regex rules of which files should the tool ignore, this file works for both war2json and json2war, if you want the ignore file to work for only 1 of the commands, consider giving the tool a filepath that doesn't exist, or having 2 separate files for each command. (Note: this doesn't ignore tool-exported files, such as the imports file or triggers file, in case of smart imports or compose triggers options enabled.)
Using this option you will have to supply a triggerdata.txt file which can be acquired from CascView opening the game, or a modified triggerdata.txt like GrapesOfWath's Enhanced GUI triggers. The tool and the World editor uses this file in order to read the triggers file.
Possible options are .json, .yaml, .toml, more are coming later.
A nice suggestion
In case of using VSCode, my suggestion is to have a.vscode/launch.json with following content:
JSON:
{
"version": "0.2.0",
"configurations": [
{
"name": "map2json",
"program": "patchwork-mapconverter",
"request": "launch",
"runtimeExecutable": "npx",
"skipFiles": [
"<node_internals>/**"
],
"type": "node",
"args": [
"-d",
"-ct",
"-si",
"-td",
"./.vscode/triggerdata.txt",
"war2json",
"./build.w3m",
"./map"
]
},
{
"type": "node",
"request": "launch",
"runtimeExecutable": "npx",
"name": "json2map",
"skipFiles": [
"<node_internals>/**"
],
"program": "patchwork-mapconverter",
"args": [
"-d",
"-ct",
"-si",
"-td",
"./.vscode/triggerdata.txt",
"json2war",
"./map",
"./build.w3m"
]
}
]
}Doing so, allows you to have a quick way of executing this tool's commands whenever you have something that needs to be tested, or simply for making a map for general public.
map2json task should executed after every World Editor change, like modifying the terrain or defining new units in object editor, so that their JSON counterparts can get these updates.
json2map task should be executed after every code or import change, before testing a map or saving the map to a file for public release.
json2map task, with the forementioned configuration in tasks.json file will generate a build.w3m folder, which can be opened in World editor to test/edit the map.
Another advice is to have this folder added to your .gitignore file, since the idea of this tool is to have only textual representation of these files in your repository.
Furthermore, in
patchwork.ignore file, you could add these files:
Code:
war3map.wtg
war3map.wct
war3map.j
war3map.luaSo that when executing map2json task, it doesn't touch your source code. And there's no need to have the compiled .j/.lua files in your repo.
If you have any issues you can comment on this thread, or if you find any bugs you can raise an issue on GitHub.
Happy coding/map making!
- All illegal foldername characters that can be typed as trigger elements in trigger editor are now being replaced by another character:
TypeScript:
function safeReplaceTriggerName(name: string): string {
return name
.replaceAll('/', '-')
.replaceAll('\\', '-')
.replaceAll(':', ';')
.replaceAll('*', '+')
.replaceAll('?', '!')
.replaceAll('"', '\'')
.replaceAll('<', '(')
.replaceAll('>', ')')
.replaceAll('|', '_')
}- Doodad flags have been fixed (fixed my mistake regarding bitwise operators)
- Triggers can now be converted from/to YAML and TOML options (-ge option)
- Doodad flags have been fixed (begone outdated definitions!) (fixes doodad's Z height problem)
- Empty patchwork.ignore file no longer causes problems.
- Fixed trigger composer and import composers not checking with file blacklist
- Added support to convert map data to/from YAML and TOML (-mde option)
- Added prettify option that works only for JSON format (-p option)
- OE data which contains a \u0000 char (Curse ability's 'Crs' field) are now properly transferred between binary and json format
- Scripted triggers will no longer sometimes be enabled when they're supposed to be disabled after converting JSON to war3map format
- runOnMapInit now properly processed for scripted triggers
- can now handle converted triggers
- added previously unsupported things from .doo (and .doo.units) and .w3i:
- random drop tables
- game data set
- game data version
- use TFT
- water tinting
- terrain fog
- map properties opened at least once
- map was reduced from original terrain size
- upgrades & tech blacklist
- player all/enemy low/high priority bitmaps
- waygate data
- special doodads (doodads embedded into terrain)
- imports will no longer have auto-prepended war3mapimported in the path
- triggerdata.txt is now only required when converting GUI triggers
- trigger comments which are using illegal slash and backslash will have those converted into '-' symbols
- duplicate trigger comments will get numbers appended to their names
- .wts will no longer lose non-ascii chars (using utf-8)
- fixed converting disabled custom scripts from war3map file to FileSystem + those same custom scripts are now copied back into war3map file
- GUI triggers JSON format has been changed in order to fix specific cases caused by WEU converter
Last edited:
