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. Make sure you have 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 set up the routes and points, edit some settings to advise the KMP compiler, and run the compiler.
Wiimm already implemented the auto connection of enemy routes 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
When a tool of Wiimms SZS Tools reads a file, the process is always the same: The file is read into memory and analyzed to find out the file 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 hold 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, the file course.kmp is searched for and scanned. Native files are scanned by a binary scanner and text files are translated by the 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 the use of name before it is defined (forward references). 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 in 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 binary (commands ENCODE, PATCH), as text (commands DECODE, PATCH, CAT), or dropped (command CHECK).
Standard routes only
All 32 original racing tracks, and all custom tracks too, use 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 these 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 both direction. For Wiimms tools, 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 with »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 4 parts:
- Creating a KMP text file by an binary KMP or by SZS.
- Editing the text file.
- Verifying the edits.
- Creating the updated KMP or SZS.
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 to 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 all the cases above, the filename is course.kmp.txt. Then 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 controlled 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 points are analyzed. If the NEXT list is empty, then all standard routes pointing to the dispatch point are searched. 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.
Route Classes
The problem: You want to create a battle arena with 2 levels. The auto-connect calculation must be independent for each level with exception of the passages. Block Plaza is a Nintendo example for this kind of arenas.
The solution is to use classes. Every route is part of a class. Or more specific: Every end of the route is in 2 classes: one for incoming connections and one for outgoing connections. So we have 4 classes for each route:
- Class for incoming connections by PREV links.
- Class for outgoing connections by PREV links.
- Class for incoming connections by NEXT links.
- Class for outgoing connections by NEXT links.
The auto-connect for a PREV link will only search destinations where the incoming PREV class matches (not: is identical) the outgoing PREV class. And same for the NEXT links.
Theses concept seems to be difficult, but usually you don't need the full functionality. In deed, the later implemented one-way support is much easier to manage.
Predefined classes
Classes are automatically defined by the first usage of a class name. Up to 250 classes can be defined, much more than needed. There are 3 pre-defined classes with special meanings:
- $OFF
- Class $off matches none and disables auto-connect.
- $ANY
- Class $any matches all classes other than class $off.
- $DEFAULT
- Class $default is the default class at the beginning. There is nothing special with it.
All standard classes (= all except $off and $any, but including $default) matches the same class and class $any.
Commands, Syntax and Defaults
There ar 4 commands to support the class model:
Syntax: "$DEF-CLASS" [":"] class_name "$CLASS" [":"] class_name_prev [class_name_next] "$AC-PREV" [":"] class_name "$AC-NEXT" [":"] class_name
- $DEF-CLASS
- ???
- $CLASS
- ???
- $AC-PREV
- ???
- $AC-NEXT
- $AC-NEXT works identical like $AC-PREV, but for the NEXT links.
Examples
???
Fine Tuning
Beside classes, there exist more commands that allow fine tuning of the auto connect algorithm. Your can define, if a route is standard or a dispatch point. There is a way to declare one-way connections. Last not least, you can setup some routes manually and disable the auto connection.
Dispatch mode
Usually, the split into standard routes and dispatch points is done by the tools:
- Each route with exact one route point and without any PREV link is a dispatch point.
- All other routes are standard routes.
But the user can override this auto detection with the command $SETTINGS.
- Syntax: "$SETTINGS" [":"] setting1 setting2 [ "AUTO" | "ROUTE" | "DISPATCH" ]
- Default: $SETTINGS: 0 0 AUTO
The command starts with the keyword $SETTINGS (case insensitive). The following colon is optional. Then 2 numerical expressions for the 2 settings are expected. The last optional parameter is a keyword (or its unique abbreviation). AUTO (the default, if the parameter missed) enables the auto detection and the other 2 keywords override it.
Example: Set the mode of a route with only one route point to standard route:
$SETTING 0 0 ROUTE
One-way links
Usually, the auto-connect algorithm creates a ling form a standard route to the nearest dispatch point, and a second link in the other direction. But sometimes, you want only a one-way connection for example to jump down from a upper level to the base level. For this case, command $ONEWAY exists:
- Syntax: "$ONEWAY" [":"] "NONE" | "PREV" | "NEXT" | "BOTH"
- Default: $ONEWAY: NONE
The command starts with the keyword $ONEWAY (case insensitive). The following colon is optional. Then a keyword (or its unique abbreviation) is expected. It declares, which end of the route is a one-way connection. The command has only impact for auto connected standard routes.
Example: Set the PREV link to one-way:
$ONEWAY: PREV
One-way links are possible for manual links to. Prefix the destination group name by an »>«:
$PREV: G1 >G2 G3
Here, the link to G2 is one-way.
Manual Links
For each single route, standard or dispatch point, it is possible to disable the auto-connect and to setup the links manually.
If at least 1 NEXT link is defined, auto-connect is disabled for the NEXT links. Same for PREV links. If at least 1 PREV link is defined, auto.connect is disabled for the NEXT links.
Examples:
$GROUP R5, next: DP1 >DP3 $PREV: DP2 >DP4
It is also possible, to disable auto-connect if the link list is empty. This is done by using the pre-defined class $OFF:
$AC-PREV $off $AC-NEXT $off
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