Nuclear Throne Together allows you to define additional custom races.

This is done by creating a yourracename.race.gml file in game's main or appdata directory and loading it via /loadrace yourracename.

The file can #define the following scripts to be called by the game:

init

Executed when the mod is loaded. This is where you create sprites and initialize general global variables.

create

Executed from each player instance of the matching race upon creation. This is where you you set sprites, sounds, and character-specific properties. For example,

#!cpp
#define create
spr_idle = sprSpookyBanditIdle;
spr_walk = sprSpookyBanditWalk;
spr_hurt = sprSpookyBanditHurt;
spr_dead = sprSpookyBanditDead;

See Player' variables for a complete list of built-in variables that you can mess with.

game_start

Executed from each player instance of the matching race after everyone picked characters and the game is starting. This is where you initialize player-specific global variables.

step

Executed from each player instance of the matching race after all other actions in the step event. This is where you handle active and most passive abilities.

draw

Executed from each player instance of the matching race after all other actions in the draw event. This is where you draw any visual effects/overlays.

race_name

Should return the race' name, for character selection and other menus. For example,

#!cpp
#define race_name
return "Bandit";

race_text

Should return the race's passive & active description for display on character select screen.

race_portrait

If defined, should return a sprite for character' portrait art (used in character select and pause menu).

race_mapicon

If defined, should return a sprite for use on map/progress graph.

race_swep

If defined, should return a starting weapon ID for the race. This can be a mod weapon too.

race_avail

If defined, should return whether the race is currently unlocked.

race_menu_button

If defined, will be called by the character select menu' button for the race upon it's creation. For example,

#!cpp
#define init
global.sprMenu = sprite_add_base64("(icon' base64 here)", 1, 0, 0);
#define race_menu_button
sprite_index = global.sprMenu;

race_skins

Can return the number of skins that the race will have (default 1)

race_skin_avail

Can return whether the given skin for the custom race is unlocked. Is called with skin index.

race_skin_button

If defined, will be called by the skin switch button. Can be used to set skin button' sprites.

race_soundbank

Can return built-in race' ID/name to source default snd_ variable' values from.

race_tb_text

Should return the description for Throne Butt mutation for this race.

race_tb_take

Executed when TB is taken by any of the players.

Keep in mind that the player of the chosen race might not be alive at the time.

race_ultra_name

Receives an ultra mutation' index (1, 2, ..) and should return a name for it.

This will determine the number of ultra mutation buttons shown. For example,

#!cpp
#define race_ultra_name
switch (argument0) {
case 1: return "Ultra 1";
case 2: return "Ultra 2";
default: return "";
}

race_ultra_text

Receives an ultra mutation' index and should return it's description.

race_ultra_button

Called by an ultra mutation' button upon it's creation. Receives an ultra mutation' index. Should set up the sprite for it. Similar logic as with race_menu_button.

race_ultra_take

Called with an ultra mutation' index when an ultra mutation of this race is picked. Same as with TB, keep in mind that the player of the given race may not be around when this is triggered.

race_ultra_icon

race_ttip

Called by the game when it intends to display a character-specific tooltip during loading.

Can return either a single tooltip,

#!cpp
#define race_ttip
return choose("Tip 1", "Tip 2");

or an array of tooltips for game to pick from,

#!cpp
#define race_ttip
return ["Tip 1", "Tip 2"];