Kartmaker - SRB2 Wiki (2024)

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 of name 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 for S0.
• Since S0 uses "layers": [[480, 0]] and T0 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]] and SSIG 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.

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 be riders_sonic but their player skin's name will still be heavymagician. Custom animations and gameplay mechanics should almost always check the former value to ensure that ironman shapeshifts behave as expected.

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 offset /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.