Creating enemy routes of battle arenas with Wiimm's tools
This tutorial explains the creation of enemy routes in battle arenas using Wiimms SZS Tools. Be sure to understood the concept of Standard Routes and Dispatch Points!
Introduction
As of v1.60a, Wiimms SZS Tools support an automatic connection of Standard Routes and Dispatch Points. All you need is to setup up the routes and points, edit some settings to advise the KMP compiler, and run the compiler.
Wiimm implemented the auto connection of enemy routes already and started a final test phase. See the change log for progress.
There is a second page with full code examples, which are used as reference from this page.
KMP Compiler
If a tool of Wiimms SZS Tools reads a file, is does always the same: The file is read into memory and analyzed to find out the data format. If the file has an acceptable file format, a scan function is selected and the file data is scanned and translated into the internal data structures, which can held more data than the files.
In case of KMP (see image on the right), native KMP files and text KMP files are accepted for input. For SZS archives, file course.kmp is searched and scanned. Native are scanned by a binary scanner and text files by a KMP compiler.
Wiimms SZS Tools use a 2-pass compiler to translate KMP text files into the internal data structure. On each pass the complete text file is scanned. In the first pass the file is scanned for name definitions. This allows to use a name before it is defined. Error messages are suppressed. The second pass is used to setup the internal data structure. Error messages about syntax errors or missing names are printed.
The concept of the 2-pass compiler is important for this article, because route links are created by names that are defined later!
The internal data structure allows manipulations of the data on different ways independent of the external file format. Manipulations are for example transformations, but also automatic route connections.
At the end, the data is is stored as as binary (commands ENCODE, PATCH), as text (commands DECODE, PATCH, CAT), or dropped (command CHECK). aof
Standard routes only
All 32 original racing tracks, and all custom tracks too, uses standard routes. In this case, each end of the routes is linked to 1 to 6 beginnings of other routes. The NEXT links are used for this connections. To get bidirectional links, the PREV links of the destinations are set to the previous routes. The PREV links can be set automatically by analyzing all NEXT links. Wiimm's tools does it, if parameter @AUTO-CONNECT is set to AC$PREV.
Let's look the group headers of Luigi Circuit. You can find the full de-compiled enemy route definition here.
@AUTO-CONNECT = AC$PREV # == automatic calculation of PREV links # zero based index: 0, prev: 1, next: 4 5 $GROUP G1, next: G2A G2B .... # zero based index: 4, prev: 0, next: 2 3 $GROUP G2A, next: G3A G3B .... # zero based index: 5, prev: 0, next: 2 3 $GROUP G2B, next: G3A G3B
Lines beginning with »#« are comments. Here they show the numerical route index and the links in botth direction. For Wiimm's tool's, the »$GROUP« tells the compiler to start a new group. The group names are generic and the numbering of group names following the links. In this example, group G1 has 2 successors named G2A and G2B. The PREV links are not defined, because they are calculated automatically.
This concept works for battle arenas too. Nintendo used it for SNES Battle Course 4 (A21). Anyway, using dispatch points is the better concept for battle arenas.
Standard routes and dispatch points
9 of 10 battle arenas by Nintendo use Dispatch Points. Here we use GCN Cookie Land as example. You can find the full de-compiled enemy route definition here.
The text creator of Wiimm's tools print the standard routes like this:
# zero based index: 0, prev: 10, next: 12 $GROUP G1, next: DP4 $PREV: DP2 .... some points
Each group name begins with »G« like usual. The group name is followed by the NEXT list. This is the same as for racing tracks. In a second line the PREV links are listed. It is needed because the links are individual and not based on the NEXT links.
A Dispatch Point looks similar, but the names begin »DP«. This makes differentiation between both route types easier:
# zero based index: 10, prev:, next: 0 3 7 $GROUP DP2, next: G1 G4 G8 $PREV: $SETTINGS: 0 0x80 AUTO .... exact one point
The PREV list is empty. Because there are route setting with values other than zero, an additional $SETTINGS line is printed.
How to create a good ENPT setup
All above is an large introduction. And here begins the real tutorial with the basics. A later chapter »Fine Tuning« will show, how to handle special cases like route to route links, routes on 2 or more levels levels, one-way links (e.g. for jumping down).
The base tutorial consists of 3 parts:
- How to create a KMP text file in text.
- Editing and verifying the text file.
- Creating the final KMP.
Creating a KMP text file
Wiimms SZS Tools are not good to insert routes. Here are graphical tools definitely better. This is not really a problem. Insert your routes and your dispatch points too. There is no need ti link them, the KMP compiler will do it for you and more.
If you have a binary KMP, just do one of:
wkmpt decode course.kmp --battle -od course.kmp.txt wkmpt cat course.kmp --battle >course.kmp.txt
Both commands do the same: Load the binary KMP and write a text KMP.
If you KMP is part of a SZS file, you can use the same commands:
wkmpt decode ARENA.szs --battle -od course.kmp.txt wkmpt cat ARENA.szs --battle >course.kmp.txt
It is also possible to extract the whole KMP and re-create the SZS later with the updates KMP:
wszst extract ARENA.szs --battle
In this case, a directory named ARENA.d is created.
Some notes about options:
- Option --battle disable the auto detection of battles and tells the tools, that the track file is definitely a battle arena.
- The tools usually don't overwrite existing files. Option --overwrite or short -o disables this security mode.
- Option --dest FILE or -d FILE selects another destination (output) file.
- -od FILE is s short form of -o -d FILE is a short form of --overwrite --dest FILE.
- >FILE redirect the output to FILE.
If you are unsure about using the command line, then read this. Windows users can also create batch files like:
@echo off wszst extract ARENA.szs --battle @pause
Edit the ENPT section
The next part is a loop of editing the text file and verifying the results.
To edit the text KMP you need a text editor, but not a document editor like Microsoft Word. A recommendation for Windows users is notepad++.
Open the KMP text file with the editor. In al cases of above, the filename is course.kmp.txt. The scroll to the {ENPT] section. Don't remove or edit other part, if you don't know, what you do. They are needed to re-create the complete KMP file.
Make the following setting (edit the line):
@AUTO-CONNECT = AC$DISPATCH
Below the marker #ENPT# (a comment) you find the decode routes. In case of GCN Cookie Land it looks like here listed.
First, we edit the standard routes. Change this ...
# zero based index: 0, prev: 10, next: 12 $GROUP G1, next: DP4 $PREV: DP2
... to this ...
$GROUP G1
... for all standard routes to remove the manual links.
Dispatch points looks different. Change this ...
# zero based index: 9, prev:, next: 1 3 4 $GROUP DP1, next: G2 G4 G5 $PREV: $SETTINGS: 1 0x40 AUTO
... to this ...
$GROUP DP1 $SETTINGS: 1 0x40
and remove the PREV and NEXT links. Keep the $SETTINGS line, if you want to keep the settings.
If you heave remove all links, you can run the KMP compiler to verify your settings (see next section). The auto-connect works like this:
- First all routes are divided into 2 sets: Standard routes and dispatch points. This is done automatically, but can be cobtrolled by special settings.
- Then the PREV and NEXT list of all standard routes are analyzed. If an empty list is found, the nearest dispatch point of same class is searched and linked. The class concept is explained in the Fine Tuning part of this tutorial ⇒ ignore it for the moment.
- Now, all dispatch point are analyzed. If the NEXT list is empty, then all standard routes are searched, that point to the dispatch point. For the up to 6 routes, a NEXT link is inserted.
Verify your edits
There are 2 good ways to verify your edits:
- Create a new text KMP from the edited edited KMP and verify it with an editor. or at the console.
- Create an OBJ file and load it with your favorite 3D Tool.
After verification, you can edit the text KMP again for a next loop.
Create a new text KMP
You can use the same commands as above to a create a new text KMP with the edited text as source:
wkmpt decode course.kmp.txt -od verify.txt wkmpt cat course.kmp.txt >verify.txt
If working with an console window, it is possible to pipe the output to a pager and scroll through it. The following command works for Windows and Linux:
wkmpt cat -N course.kmp.txt | more
Linux users (Cygwin users too) can use the more powerful tool less instead of the classic more:
wkmpt cat course.kmp.txt |& less +/'^!|#ENP'
The option +/'^!|#ENP' enables searching for errors and data of sections ENPH and ENPT. Type »n« to jump to the next matching line.
Section ENPH gives an overview about all routes and it links. Section ENPT shows the the routes with the new calculated connections.
Create an OBJ file
A second method for verification is to export the data to an Wavefront OBJ file and to open it with any 3D Tool.
wkmpt draw course.kmp.txt --draw enpt,white -od path/to/a.obj
With this options, only the enemy routes are drawn. Q white ground is added for an optimal view from the top. The example image from above is made by this.
Alternatively, you can visualize the KCL:
wkmpt draw course.kmp.txt --draw enpt,kcl -od path/to/a.obj
Create a new course.kmp or TRACK.szs
To create a binary KMP, use the command:
wkmpt encode course.kmp.txt -od new-course.kmp
If you have extracted a complete SZS file, use the following command to create a new one:
wszst create ARENA.d -od new.szs
If you have touched file course.kmp.txt, a new course.kmp is automatically created.
Fine Tuning
???
Dispatch mode
???
Route Classes
???
One-way links
???
Manual Links
???
Links
Main Tutorials
Introduction –
Textures –
Scale –
Modeling ⇒ Using Blender –
BRRES: CTools
BRRES: BrawlBox –
BRRES: RiiStudio –
Minimap –
Solidity –
KCL: Wiimms Tools –
KMP Editing
Object Editing –
Cameras –
Cannons –
Post-effects –
Videos
Battle Arenas
Battle Arenas –
Enemy routes in battle arenas ⇒ Using Wiimm's Tools –
Coins
Misc. Tutorials
Getting Files –
BrawlBox Tricks –
Animations –
Shadows –
Mipmaps
Custom Effects –
Moving Terrain –
Music –
Ports –
Paint Remakes –
Tutorial Archive
Extended presence flags: Track Tutorial –
LE-CODE Track FAQ
Testing and Reviewing
Testing a Track –
Visual Review –
Track Transformation –
Fixing Errors
Software
3D Tools –
BrawlBox –
CTools Pack –
KMP3D –
KMP Cloud –
KMP Modifier
Lorenzi's KMP Editor –
MagicY –
Material Tool –
Post-Effect Editor –
Wiimms SZS Tools –
Wiimm's Tool Manager
Other
KMP Objects –
Custom Objects –
Model Database –
Tutorial Archive