Kartmaker
Kartmaker | |
---|---|
Author | fickleheart, Kart Krew Dev |
Latest version | 1 (Dr. Robotnik's Ring Racers 2.2) |
Release date | January 26, 2019 |
Operating system | Cross-platform |
Kartmaker is a group of applications for automatically packaging character addons for Sonic Robo Blast 2 Kart and Dr. Robotnik's Ring Racers. These applications take a folder with a sprites.png
file, a properties.txt
including template and character information, and .ogg
sound files to generate a playable racer.
Kartmaker interprets character data according to a JSON-formatted text file, though the expected data is slightly different for different versions of Kartmaker.
Character Formatting
Excepting the addition of rivals and a different set of skincolors, both games share a very similar set of properties for character generation:
"name": "example", "realname": "Example_Skin", "prefix": "EXMP", "stats": [5, 5], "startcolor": 96, "prefcolor": "red", "rivals": ["example2", "example3", "example4"],
The properties are as follows:
name
: The internal name for your character. Characters will never share name values; loading two characters with the same name will cause the latter one to have a number appended to their name. Names can't have spaces in them (use underscores instead), can't be longer than 16 characters, and are automatically converted to lowercase.realname
: The display name for your character on character select and elsewhere. Characters may share the same realname. Realnames can't have spaces in them (use underscores instead), and can't be longer than 16 characters.prefix
: A prefix used to name several assets related to your character (sounds and icons in SRB2Kart, sounds only in Ring Racers.) Prefixes should always be four characters exactly, and if two characters use the same prefix, they will replace each others' assets. If you aren't sure what prefix to use, either shorten the driver's name to four characters (e.g. "Mario" → MRIO), or create a unique prefix to serve as your signature (e.g. Togen's first character can use the prefix "TGN1".)stats
: The character's engine stats. The order is[speed, weight]
. Stats will be forcibly clamped to be no less than 1, and no greater than 9, and characters can only have stats outside this range by using Lua.startcolor
: The first color that is used to determine your character's recolor range. In SRB2Kart, the default startcolor is 160 (includes 160 through 175), and in Ring Racers the default is 96 (includes 96 through 111). In general, this is only changed to allow characters to use specific shades of green as non-recolorable design elements.prefcolor
: Your character's default color. Pressing Backspace while choosing colors will return the user to this default color, and bots in Ring Racers will always use the prefcolor.rivals
: A list ofname
values for your character's rivals in Ring Racers' Grand Prix mode. Rivals past the third will be ignored. If a rival is not available on the current setup, they will be replaced with a random character. This property is not used in SRB2Kart.
Transparent Colors
The following property is listed below the character properties:
"transparent_colors": [ 115, 115, 255, 82, 82, 255 ],
These are the two colors that will be treated as transparent by Kartmaker when processing sprites, listed as RGB values. By default, these are two specific shades of blue (indexes 228 and 229 in SRB2Kart, 148 and 149 in Ring Racers). If you need to use those two colors for your character, please change the RGB values in this property to different colors that your character won't be using and recolor the blank areas in the template as necessary.
SRB2Kart Template Formatting
SRB2Kart Kartmaker uses pixel-based coordinates to fetch sprites, and then a layer system to automate tire animations.
In SRB2Kart Kartmaker, the "sprites"
table is a list of frames in the following format:
"A1": { "offset": [40, 71], "layers": [[0, 0], [0, 320]] },
"A1"
: The frame's letter and angle. Sprites will be animated by advancing one letter every tic, and the angle is chosen by checking the player object's angle against the current viewpoint's position. See Sprite for further details."offset"
: The frame's visual offset. This gets used to determine where the "center" of the character is. In most cases, this should be slightly above the bottom center of the frame. When a character is drifting, they shake slightly by using different offsets like[39, 71]
and[41, 71]
."layers"
: A list of pixel coordinates.[0, 0]
fetches the sprite starting in the top left corner, then[0, 320]
looks 320 pixels lower to fetch the sprite in the fourth row underneath it. Kartmaker uses these layers to automate things like tire animations.
SRB2Kart lacks the flexible sprite animation system that Ring Racers uses, but suppose a creator wants to add a second signpost to their asymmetrical template. They would create a "T0" frame definition so that Kartmaker correctly imports the new graphic, then use another utility like Simple AnimaL to manage the custom animation.
"T0": { "offset": [40, 71], "layers": [[560, 0]] }
"T0"
signals that we are defining coordinates for the nineteenth frame, but also making it omnidirectional so that it looks the same at all angles."offset"
is simply the same value already used forS0
.- Since
S0
uses"layers": [[480, 0]]
andT0
uses"layers": [[560, 0]]
, this places the second signpost one spot to the right, in the ninth column and first row.
Ring Racers Template Formatting
Ring Racers Kartmaker forgoes SRB2Kart Kartmaker's pixel-based cell sizing to instead measure coordinates in tiles.
In Ring Racers Kartmaker, the "sprites"
table is a list of sprite2 names like "STIN"
, and each sprite2 contains a list of frames in the following format:
"A1": { "offset": [48, 84], "layers": [[0, 0], [0, 5]] },
"A1"
: The frame's letter and angle. Sprites will be animated by advancing one letter every tic, and the angle is chosen by checking the player object's angle against the current viewpoint's position. See Sprite for further details."offset"
: The frame's visual offset. This gets used to determine where the "center" of the character is. In most cases, this should be slightly above the bottom center of the frame. When a character is drifting inwards, they shake violently by using different offsets like[42, 84]
and[54, 84]
."layers"
: A list of sprite-scaled coordinates.[0, 0]
fetches the sprite in the zeroth row and zeroth column, then[0, 5]
puts the sprite in the fifth row underneath it. Kartmaker uses these layers to automate things like tire animations.
Supposing that a creator wants to add a silly signpost ("SSIG") to their asymmetrical template, they would achieve this by adding a new entry to their "sprites"
list. If the silly signpost is placed directly right of the normal signpost, then it would look like this.
"SSIG": { "A0": { "offset": [48, 79], "layers": [[9, 1]] } },
"SSIG"
is the new sprite2 name."A0"
signals that we are defining coordinates for the first frame of the SSIG, but also making it omnidirectional so that it looks the same at all angles."offset"
is simply the same value already used for the normal"SIGN"
sprite.- Since
SIGN
uses"layers": [[8, 1]]
andSSIG
uses"layers": [[9, 1]]
, this places the alternate signpost one spot to the right, in the ninth column and first row.
Post-Processing
SLADE can be used after generation to edit your character's properties and frames. While this allows you to add/remove frames without directly editing your Kartmaker template, post-processing also allows one to add Lua, flags, and hi-res scaling information to their skin.
SF_BADNIK
In Ring Racers, characters with Badnik = True
display extra explosion effects when they die, and have their death sprite doubled in scale with squash and stretch animation effects removed.
SF_MACHINE
In Ring Racers, characters with Machine = True
make a different sound when they gasp for air.
SF_IRONMAN
In Ring Racers, characters with flags = SF_IRONMAN
will periodically shapeshift, taking on the properties of a different racer including their speed, weight, and certain Lua effects.
- The character will transform into a random non-ironman character when making significant progress such as starting a new lap in Race modes, or taking damage in Battle modes.
- In both cases, ironman characters will briefly reveal their true form on hit, then resume transformation when they recover.
- Ironman transformations will display a ranking portrait rotated 180 degrees, will retain the player's original skincolor, and will retain the ironman character's voice lines.
- Lua scripts will return different results depending on whether they check the ironman player controller's skin, or the ironman map object's skin.
- If a Heavy Magician ironman player transforms into
riders_sonic
, their mobj skin will beriders_sonic
but their player skin's name will still beheavymagician
. Custom animations and gameplay mechanics should almost always check the former value to ensure that ironman shapeshifts behave as expected.
- If a Heavy Magician ironman player transforms into
highresscale
If a character has a highresscale
value in their S_SKIN, their sprites will be drawn at a higher resolution for values below 1, and a lower resolution for values above 1; a character with a scale of 0.5 will be drawn at 50% their normal size. SRB2Kart requires the SF_HIRES
skin flag for highresscale
to take effect, but Ring Racers does not.
Common Errors/FAQ
Why doesn't Kartmaker do anything when I open it?
Kartmaker does not include a GUI. The intended mode of operation is to run kartmaker.exe while providing a folder full of your materials.
You can save the following code as "Select Folder.bat" to open a window that prompts you to type a template name. In the event that an error occurs, the window will remain open and allow you to read through the console.
@echo off set /p skin="Enter the template or character name (e.g. KC_example): " kartmaker.exe "%cd%\%skin%" pause
What are the bottom two rows on each template for?
Kartmaker uses these additional rows to automate tire animations for your normal sprites. These sprites should not be edited except to reflect changes you've made to the normal kart, such as recoloring, replacing, or removing the normal art.
What is each row in the template used for?
SRB2Kart
- normal driving/still, turning left
- drifting left
- in pain/spinout
Asymmetrical templates for SRB2Kart will also add:
- additional asymmetrical frames for normal driving and spinouts
- turning right
- drifting right
Ring Racers
- normal driving/still, turning left
- looking slightly left (drifting, glaring)
- looking hard left (honking, leering)
- in pain/spinout, dying/exploding
Asymmetrical templates for Ring Racers will also add:
- additional asymmetrical frames for normal driving and spinouts
- looking slightly right
- looking hard right
Other templates (such as for on-foot racers) may follow different rules. If the layout for your template isn't immediately obvious, either study the template data in properties.txt or ask for help.
Why are there 2/3 death poses in Ring Racers templates?
Ring Racers templates animate character deaths by alternating between frames. In the case of symmetrical templates, the pattern is 0→1→0→1→0, while in asymmetrical templates the pattern is 0→1→0→2→0. This can be customized, or edited after generation, if you want a different pattern.
Why am I hearing "whoosh"/thok sounds?
Your prefix is too long or short; Kartmaker expects these to be four characters exactly.
Why are my sounds/icons replacing somebody else's sounds/icons?
Your skin prefix should be a unique four-character string. If two different characters use "EXMP", then the newer character will always overwrite the older character's assets.
Why is Kartmaker force-quitting?
Your sprites.png is too small for your template, and Kartmaker is trying to fetch pixels that are out-of-bounds.
Why is there a syntax error in my S_SKIN?
Names and realnames should have underscores, not spaces.
Gallery/Extra Templates
-
Game palette used for SRB2Kart and early versions of SRB2.
-
Symmetrical Sonic silhouette template for SRB2Kart Kartmaker.
-
Asymmetrical Sonic silhouette template for SRB2Kart Kartmaker.
-
Game palette used for Dr. Robotnik's Ring Racers and current versions of SRB2.
-
Symmetrical Tails silhouette template for Ring Racers Kartmaker.
-
Symmetrical Tails silhouette template for Ring Racers Kartmaker, with asymmetrical spinout frames.
-
Asymmetrical Tails silhouette template for Ring Racers Kartmaker.