Displays the given value(s) in chat.

Values are separated by a single space.

Non-string values are converted to string prior.

trace(1, 2); // "1 2"
trace(room_speed, "FPS"); // "30 FPS"
var arr = [1,2,3];
trace(arr); // "[1, 2, 3]"
var obj = {a:1,b:2};
trace(obj); // "{ a: 1, b: 2 }"

Advanced users can also enable this function to log to stdout via /stdout chat command - that allows to use it to debug code even if it crashes the game.

Measures time (in nanoseconds) since the last call to this function, and displays it in chat if caption argument was specified.

trace_time();
// do something
trace_time("Time spent on something"); // "Time spent on something: #ns"

Displays a message in chat with a colored line like those sent by players have.

trace_color("Red!", c_red);
trace_color("Green!", c_lime);
trace_color("Fancy!", make_color_rgb(250, 50, 200));

Prepends padstr to str until it reaches specified length.

trace(string_lpad(string(42), "0", 4)); // "0042"

Appends padstr to str until it reaches specified length.

trace(string_rpad(string(42), "0", 4)); // "4200"

Converts a number to a string with automatic precision (unlike string_format, which requires specifying the number of decimal places).

trace(string_auto(0.4)); // "0.4"
trace(string_auto(0.4040)); // "0.404"

Removes leading and trailing spaces from a string.

trace(string_trim(" hi ")); // "hi"

Removes leading spaces from a string.

trace(string_trim(" hi ")); // "hi "

Removes trailing spaces from a string.

trace(string_trim(" hi ")); // " hi"

Splits a string on delimiter into an array of strings.
The general opposite of array_join.

If the string does no contain the delimiter, returns a 1-element array with the entire string.

trace(string_split("1|2|3", "|")); // [1, 2, 3]

Returns a SHA-1 hash of a string, assuming Unicode encoding.

Returns a SHA-1 hash of a string, assuming UTF-8 encoding.

Returns a MD5 hash of a string, assuming Unicode encoding.

Returns a MD5 hash of a string, assuming UTF-8 encoding.

Creates an array of given size. Size of 0 is allowed.

The resulting array is filled with zeroes.

var arr = array_create(3);
trace(arr); // [0, 0, 0]

Returns the length of the provided array.

Returns 0 for non-array values.

You can also use the standard array_length_1d alias for this function.

var arr = [1, 2, 3];
trace(array_length(arr)); // 3

Inserts a value to the end of the array, expanding it.

Creates a 1-element array if the value isn't an array yet.

Returns the array (either the same if the value was an array or a newly made one).

var arr = [1];
trace(arr); // [1]
array_push(arr, 2);
trace(arr); // [1, 2]

Returns the index of first occurrence of a value in the array.

var arr = ["a", "b", "c"];
trace(array_find_index(arr, "b")); // 1
trace(array_find_index(arr, "c")); // 2
trace(array_find_index(arr, "d")); // -1

Replaces the contents of an array with given value.

var arr = [1, 2, 3];
array_clear(arr, 4);
trace(arr); // [4, 4, 4]

Returns a shallow copy of the given array.

var a = [1, 2, 3];
var b = array_clone(a);
a[1] = 4;
trace(a); // [1, 4, 3]
trace(b); // [1, 2, 3]

Copies values between arrays.

Destination-array is expanded to fit new size if needed.

var a = [1, 2, 3, 4];
var b = [4, 5];
array_copy(a, 3, b, 0, 2);
trace(a); // [1, 2, 3, 4, 5]

Returns a new array with values representing a section of an array.

This is more or less a shortcut for array_create + array_copy.

var arr = [1, 2, 3, 4, 5];
trace(array_slice(arr, 1, 3)); // [1, 2, 3]

Joins the contents of an array into a string, separating them as specified.

var arr = [1, 2, 3];
trace(array_join(arr, "|")); // "1|2|3"

string_split can be considered a counterpart of this function.

Retrieves a field' value from a lightweight object by name.

Returns undefined if the field is amiss or the value is not a lightweight object.

var obj = { str: "hi" };
trace(lq_get(obj, "str")); // "hi"

Retrieves a field' value from a lightweight object by name.

Returns defvalue if the field is amiss or the value is not a lightweight object.

var obj = { str: "hi" };
trace(lq_defget(obj, "some", "oh no")); // "oh no"

Modifies a field' value in a lightweight object by name.

var obj = { num: 1 };
lq_set(obj, "num", 2);
trace(obj.num); // 2

Returns whether a field is present in the given object.

var obj = { a: 4 };
trace(lq_exists(obj, "a")); // 1
trace(lq_exists(obj, "b")); // 0

Returns the number of fields on the given object.

var obj = { a: 4, b: "?" };
trace(lq_size(obj)); // 2

Retrieves a field' name by index.

Fields are numbered by order of their definiion.

var obj = { a: 4, b: "?" };
trace(lq_get_key(obj, 0)); // "a"
trace(lq_get_key(obj, 1)); // "b"

Retrieves a field' value by index.

Fields are numbered by order of their definiion.

var obj = { a: 4, b: "?" };
trace(lq_get_value(obj, 0)); // 4
trace(lq_get_value(obj, 1)); // "?"

Produces a shallow copy of an object.

var obj = { a: 4, b: "?" };
var copy = lq_clone(obj);
copy.a += 4;
trace(obj); // { a: 4, b: "?" }
trace(copy); // { a: 8, b: "?" }

Things aren't quite as they seem with file functions in modding.

The general concept is that files on disk have to be explicitly loaded by the mod before you can do anything with them. In local modes, it's just a 1 frame delay.

In online multiplayer, the file(s) also have to be transmitted to the co-player(s) so that the performed actions are the same, which means more delay before loading. Modified files are kept on the machine of player that loaded the mod.

Modified files are saved into a special "data" directory created per-mod.
When loading, the priority of picking files is as following (from first tried to last tried):

• Mod's data directory (previously createdmodified files)
• Directory in which mod's .gml file is located.
• Game's appdata directory.
• Game's installation directory.

Files created at runtime (i.e. saved by mod) are considered to be loaded instantly, obviously.

Start loading the given path(s).

Paths can be either actual paths (strings) or arrays of paths.

Returns the number of frames until files will be ready.

If the file doesn't exist, it is still to be "loaded", which in online multiplayer simply informs the other player(s) that the file is amiss.

The following would preload a text file test.txt and display it's contents once done:

wait file_load("test.txt"); // pause the script's execution until file's loaded.
trace("test.txt:", string_load("test.txt")); // display the contents

Unloads the given files from memory.

This is instantaneous and returns nothing.

Returns whether the file by given path is loaded (regardless of whether it exists).

var t = file_load("test.txt");
trace(file_loaded("test.txt")); // 0 - not yet
wait t;
trace(file_loaded("test.txt")); // 1 - now it is

Returns whether the file by given path is loaded and exists.

trace(file_exists("test.txt")); // 0 
string_save("hi", "test.txt");
trace(file_exists("test.txt")); // 1

Unloads a file from memory and removes it from disk (on machine of player that loaded the mod).

Returns the size (in bytes) of file at given path, or -1 if it isn't loaded / does not exist.

Returns a SHA-1 hash of the file at given path, or undefined if it does not exist / is not loaded.

Returns a MD5 hash of the file at given path, or undefined if it does not exist / is not loaded.

Initiates downloading of a file from the internet to the given location.

The function returns nothing and makes no promises as to when and whether operation will complete - use file_loaded to find when it loads.

The file is downloaded from original URL by the player that loaded the mod - in online multiplayer, the other player will be sent the mod-loading-player's copy of it once it loads.

The following would download a file and display it's contents:

file_download("http://yal.cc/ping", "ping.txt");
while (!file_loaded("ping.txt")) wait 1;
trace("Unix time at Yellow's website:", string_load("ping.txt"));

Finds all files in the given directory and populates the provided array.

The function looks relative to mod's data directory first and then directory where the mod itself is located, first of two taking priority for "overlapping" files.

If array already contains items, any extras are replaced with undefined (to avoid clashing between multiple searches).

If depth is above 0, recursively searches in subdirectories as well, up to specified depth.

Returns the number of frames until data will be ready.

The array is filled with lightweight objects with the following fields:

• name: name and extension of the item (e.g. "some.png")
• path: full path to the item (e.g. "sprites/some.png")
• ext: the extension of the file, including dot (e.g. ".png")
  This is a blank string "" for directories and files without extension.
• is_dir: whether it is a directory (true or false).
• is_data: whether the entry resides inside the mod's data directory.

For example, the following would display paths to all files inside the "sprites" directory next to the mod.

var arr = [];
wait file_find_all("sprites", arr);
var n = array_length(arr);
for (var i = 0; i < n; i++) {
	trace(arr[i].path);
}

If you want to look in mod's directory specifically, you can use "." as path, but note that you should usually only do this if your mod comes with it's own directory (as otherwise you would be picking up files form other mods in search).

Loads and returns the contents of given file as a string.

Returns undefined if the file does not exist or is not loaded.

trace(string_load("test.txt")); // "hi" or undefined
string_save("test.txt", "hi");
trace(string_load("test.txt")); // "hi"

Saves the contents of a string to the given file.

The following example would add one "hi" to "test.txt" upon each execution:

wait file_load("test.txt");
var s = string_load("test.txt");
if (s == undefined) s = "hi"; else s += "hi";
trace("text: " + s);
string_save(s, "test.txt");

• Same as with built-in GameMaker functions, for ones that allow to load files with multiples frames (subimages), they should be arranged in a horizontal strip:
  
• For functions dealing with loading from files, behaviour depends on file status:
  • If the file is already loaded (see file_load), the function performs it's action (addition/replacement) immediately, also returning the result (e.g. -1 for sprite_add if a sprite cannot be loaded).
  • If the file is not yet loaded, it will be loaded asynchronously.
    Functions that return new sprites will return an initially empty sprite and update it once the image becomes available.
    Functions that replace existing sprites will not carry out the operation until the image is loaded.
    If an error occurs, error text will be shown in chat.

• Many functions allow to specify origin (x, y). Origin defines rotation point for the sprite. General rules are as following:
  • Level tiles have origin at top-left (0, 0).
  • Various entities and projectiles have origin at center of mass.
  • Weapons have origin at "handle" point.
  • When replacing sprites/subimages, origin can be omitted to not change it.

• Sprites loaded by the mod are automatically unloaded when the mod is - no need to do that manually.

Loads a sprite from a file and returns resulting sprite index.

If the file is loaded but image loading fails, returns -1.

So, if you wanted to load and draw the sprite shown in notes section, you could save that as test.png next to a test.mod.gml, with code as following:

global.spr_test = sprite_add("test.png", 4, 12, 12);
#define draw
draw_sprite(global.spr_test, current_frame * 0.4, mouse_x, mouse_y - 32);

Loads a sprite from a base64-encoded string.

This can be convenient for smaller mods, where embedding images into code allows to distribute them as a single .gml file.

You can find both online tools (search for "image to base64") for the purpose and plugins for popular image editors.

The following loads a 18x24 image from a base64-encoded string and draws it spinning at mouse cursor.

global.spr_test = sprite_add("iVBORw0KGgoAAAANSUhEUgAAABIAAAAYCAYAAAD3Va0xAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAADFSURBVDhPnZKLDcMwCES9/z6ZogN0nFbHxx8MBudJKDa+O+EkLeHn1BVksjyfbzmQRDCcmAJd0gALPGwdyNEd8LGdkfaOeSdRdboJ6B5g7VRIF80UpgmRiBxo2eKzfTXsbUHHciIMlIjxfoATZGuDjPY5g54TvCFyxu4VM5kLiQDWETgj9YE+8onTlRSR5kDLloE2qaqIfqFfJ7vSDHxsHyxB1TD4pBaugmYdvBwxoKYXhJ6eB+Ui9tqPd0Ji/LFveDFFa38MVTOUat2nfgAAAABJRU5ErkJggg==", 1, 9, 12);
#define draw
draw_sprite_ext(global.spr_test, 0, mouse_x, mouse_y - 32, 1, 1, current_frame * 15, c_white, 1);

Loads a single-frame weapon sprite from a file and automatically generates "shine" frames required for such:

As outlined above, for weapon sprites the origin should be somewhere at the handle, as it is pivoted to player sprite using that.

Same as sprite_add_weapon, but loads from a base64-encoded string like sprite_add_base64 does.

Replaces an existing sprite with one from the image.

If loading fails, the sprite is left untouched.

If origin is not specified, the existing one is used.

Same as sprite_replace, but loads a base64-encoded string like sprite_add_base64 does.

Restores a "built-in" (non-mod-created) sprite to it's original state.

Deletes a previously created sprite.

Mods can only delete sprites created by them.

Draws a string with a simple "drop shadow" type effect - that is, by drawing it 3 more times in black color at (+1, +0), (+0, +1) and (+1, +1) offsets.

Draws a string with "tags" for multiple colors, images, and more.

Supported tags are as following:

• @w: Changes color to white.
• @s: Changes color to silver.
• @d: Changes color to dark gray.
• @r: Changes color to red.
• @g: Changes color to green.
• @b: Changes color to blue.
• @p: Changes color to purple.
• @y: Changes color to yellow.
• @q: Randomly offsets the subsequent offsets.

  Is used for cursed weapon' tips in base game.
  

  #define draw_gui
  draw_text_nt(10, 50, "@qh @qe @ql @ql @qo");
  

• @(color:<decimal color>)
  Allows to use arbitrary colors. Best used with template strings:
  

  #define draw_gui
  draw_text_nt(10, 50, `@(color:${c_yellow})hi`);
  draw_text_nt(10, 70, `@(color:${make_color_hsv(current_frame, 200, 255)})hi`);
  

• @(<sprite>)
  Inserts a sprite into text. Can be either name of built-in sprite or a decimal sprite index for custom sprites.
  The sprite will be shown animated at 12fps (game's standard).
  

  #define draw_gui
  draw_text_nt(10, 50, "@(sprMutant1Idle) can roll");
  

• @(<sprite>:<frame>)
  Shows a specific frame of the given sprite.
  

  #define draw_gui
  draw_text_nt(10, 50, "@(sprRevolver:0) s that make breakfast");
  

• @(<sprite>:<-speed>)
  Shows the given sprite animated at given speed, measured in multiplier relative to 30fps.
  

  #define draw_gui
  draw_text_nt(10, 50, "@(sprGammaGuts:-0.5) blast");
  

• @(sprButSmall:<button>), @(sprButBig:<button>)
  Displays a controller button as per player's settings (controls + gamepad type).

  Button can be one of following:

  • fire
  • spec
  • pick
  • swap
  • move: Movement stick
  • aim: Aiming stick

  #define draw_gui
  draw_text_nt(10, 50, "Move with @1(sprButSmall:move)");
  

• (sprButBug:<button>)
  Same as sprButSmall, but, well, larger sprites. Used for menus.
• (sprKeySmall:<button>)
  Displays a keyboard button as per player's settings (controls).

  Button can be one of following:

  • fire
  • spec
  • pick
  • swap
  • nort
  • sout
  • east
  • west
  • (custom): as per MSDN

  Key images are 3 characters wide at most.
  

  #define draw_gui
  draw_text_nt(10, 50, "Fire with @1(keysmall:0) or @1(keysmall:fire)");
  

• @1(...) ... @9(...)
  Same as @(...) tags, but aligns the image to be in the middle of X symbols.
  

  #define draw_gui
  draw_text_nt(10, 50, "@2(sprMapIcon:10)x3");
  

Executed once when the mod finishes loading.

This is where you would usually load sprites, set global variables, and so on.

You do not have to declare an init script explicitly - if the mod file contains code before the start of the first script, it'll be automatically considered to be the init code.

#define init
global.map = ds_map_create();

Executed just before a mod is unloaded.

This is where you clean up after your mod if you intend it to be loaded-unloaded freely.

Assets and data structures created by the mod will be destroyed automatically, but instances won't, so consider taking care of those, particularly if they behave unusually when left unsupervised.

#define cleanup
trace("See you later!");

Executed whenever a run is [re-]started.

Executed every frame.

An important distinction is that this is executed before anything else, making it perfect for quickly responding to game' events before anything else might.

Executed from draw event - after most other things are drawn, but before any HUD elements are drawn.

Draws relative to level by default.

Can be used to draw non-standard shadows beneath select objects.

Anything drawn here will be displayed in black semi-transparent color like shadows are.

For simpler cases, you can change spr_shadow, spr_shadow_x, and spr_shadow_y on entities.

Can be used to draw custom bloom, such as on projectiles.

The game's lighting system (for dark levels) is an interesting one - it clears a surface with white color, then "punches out" black and gray holes in the surface, then draws it with subtractive blending mode over the game, having it that white areas of surface become black on screen, gray areas darken the image, and black areas leave the image unaffected.

draw_dark_begin executes after the surface is cleared. You can use it to re-clear it with a different color to have completely dark areas still visible.

draw_dark executes after the game finishes drawing it's gray circles, and is where you draw your own gray circles.

draw_dark_end executes after the game finishes drawing it's black circles, and is where you draw your own black circles. You can also use this to hide something by drawing white circles.

#define step
with (TopCont) darkness = 1; // force all levels to be dark

#define draw_dark_begin
draw_clear(dddddd);

#define draw_dark
draw_set_color(808080);
draw_circle(mouse_x, mouse_y, 30 + random(4), false);

#define draw_dark_end
draw_set_color(000000);
draw_circle(mouse_x, mouse_y, 20 + random(4), false);

Allows to draw things on top of HUD - for custom UI and such.

Draws relative to screen by default.

Allows to draw things on top of literally everything - you can even draw on top of sideart by specifying X coordinate below 0 or above game_width.

Draws relative to screen by default.

Executes while the game is paused (can be used for custom UI).

Executed on run [re-]start if any player(s) use the character.

This is where you would reset any run-related global variables.

Should return the custom character' name.

#define race_name
return "SOME";

Should return the character' description for character select.

#define race_text
return "PASSIVE TEXT#@rACTIVE@w TEXT";

May return the starting weapon for the character. Defaults to revolver.

#define race_swep
return wep_pop_rifle;

May return a sprite for use as map (shown in pause / on gameover) icon.

player_index is a 0-based index.

skin is the skin as per Player.skin.

May return a sprite for use as portrait art (on character select and in pause menu).

player_index is a 0-based index.

skin is the skin as per Player.skin.

Can return one or more tips for display on loading screens.

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

Executed for character' button on character selection screen. This is where you would set it's sprite_index and anything else that you require.

May return the race ID for use as default sounds for the character.

Can be overriden in create script.

#define race_soundbank
return char_fish;

May return the sound to be played when when selecting (but not yet starting with) the character on the character select menu.

#define race_menu_confirm
return sndMutant1Slct;

May return the sound to be played when when starting a run with the character.

#define race_menu_confirm
return sndMutant1Cnfm;

Executes when:

• The character is spawned (on game start).
• The character is revived.
• Character' race/skin is changed via assigning Player.race/skin.

You should use this to:

• Set character' sprites and sounds.
• Change character-specific stats.
• Initialize any variables for later use in step/draw.

#define create
spr_idle = sprMolesargeIdle;
spr_walk = sprMolesargeWalk;
spr_hurt = sprMolesargeHurt;
spr_dead = sprMolesargeDead;

Executes from character's step event after all standard-issue logic and before the final check for death. This is where you usually handle passive/active abilities.

#define step
if (button_pressed(index, "spec")) {
	trace("<active ability>");
}

Executes from character's draw event before most things are drawn.

Can be used to draw anything (e.g. additional weapon(s)) behind the character, as well as temporarily overriding any variables.

Executes from character's draw event just after the character sprite is drawn.

If the situation requires you to draw something in front of the character but behind the front-facing weapon, this is where you do that.

Executes from character's draw event after most things are drawn.

Can be used to draw anything (e.g. additional weapon(s)) in front of the character and front-facing weapon.

May return whether the character is unlocked. Defaults to true.

May return the unlock hint text when the character is locked. Defaults to "???".

May return the number of skins available for the character. Defaults to 1.

You would then set sprites/sounds/etc. based on skin variable in create.
Default skins would have incremental indexes (0, 1, 2, ..) while custom skins have string indexes and execute after race-mod's create script.

May return whether the specified character' skin is unlocked. Defaults to true.

May return the custom label for character' skin. Defaults to "Skin <A, B, ..>".

Executed for character' skin' button. This is where you would set it's sprite_index and anything else that you require.

#define race_skin_button(skin)
switch (skin) {
	case 0: sprite_index = sprMolesargeIdle; break;
	case 1: sprite_index = sprMolefishIdle; break;
}

Should return character-specific Throne Butt (mutation) text.

This shouldn't be too long, since in coop multiple of these can be appended together to form the combined description.

Called when Throne Butt is taken or lost.

You are not required to make TB "cancelable" since it can only be removed via skill_set call.

Should return the ultra mutation' name per it's number (1-based).

Number of available ultra mutations is deducted based on number of valid strings returned from this function.

#define race_ultra_name(i)
switch (i) {
	case 1: return "Ultra A";
	case 2: return "Ultra B";
}

Should return the ultra mutation' description per it's number (1-based).

Called for ultra mutation' button to set it's sprite_index (and anything else).

Should return the ultra mutation' sprite for use in HUD per it's number (1-based).

Called when an ultra mutation is picked.

If race_ultra_lose is defined, it is called only when ultra mutation is taken and with one argument. Otherwise it's called both when it is taken or lost with additional value argument (for consistency with race_tb_take).

Legacy script. If defined, race_ultra_take will receive only one argument (index) and will not be called when ultra mutation is removed.

It is not required to make ultras "cancelable" since they can only be lost via ultra_set call.

Must return the race ID to apply to - can be either decimal for adding skins to default characters, or a string for adding skins to custom characters.

Much like game_start in custom character mods, executes on run [re-]start if the skin is in use by any player(s).

May return whether the skin is unlocked. Defaults to true.

May return text to display on skin button' mouseover.

Argument contains result from skin_avail for easier reuse.

Much like race_skin_button, applies to skin select button in loadout UI.

May return a sprite for use as portrait art (on character select and in pause menu).

May return a sprite for use as map (shown in pause / on gameover) icon.

If defined, overrides race_name.

If defined, overrides race_text.

If defined, overrides race_tb_text.

Much like create in custom character mods, executes in Player' create event.

Much like step in custom character mods, executes in Player' step event.

Much like draw_begin in custom character mods, executes in Player' draw event before most things are drawn.

Much like draw in custom character mods, executes in Player' draw event just after the actual player sprite is drawn

Much like draw_end in custom character mods, executes in Player' draw event after most things are drawn.

Executed every step while the player is carrying the weapon.

First passed argument indicates whether the weapon is in primary (1) or secondary (0) slot.

Executed whenever the weapon is reloaded.

This is where you play custom sounds, create shells, etc.

If this is not defined, behaviour is as following:

• For melee weapons, sndMeleeFlip is played.
• For shell-type weapons, sndShotReload is played and the number of shells equal to weapon_cost is created.
• For bolt-type weapons, sndCrossReload is played.
• For weapons with name starting with "PLASMA", either sndPlasmaReload or sndPlasmaReloadUpg are played, depending on whether player has Laser Brain.
• For weapons with name starting with "LIGHTNING", either sndLightningReload or sndLightningReloadUpg are played, depending on whether player has Laser Brain.
• For other modded weapons no action occurs by default.

Should return weapon' name.

Defaults to file name.

#define weapon_name(q)
return "SMG";

May return weapon' loading screen tip, if any.

Defaults to "" (no weapon-specific tip).

#define weapon_text(q)
return "quickly"

Should return weapon' ammo type. Possible values:

• 0: Melee
• 1: Bullet
• 2: Shell
• 3: Bolt
• 4: Explosive
• 5: Energy

#define weapon_type(q)
return 1;

Should return whether the weapon is automatic. Possible values are:

• 1/true: Automatic
• 0/false: Non-automatic, except for Steroids
• -1: Non-automatic even for Steroids

#define weapon_auto(q)
return true;

Should return the cooldown between weapon' shots, in frames.

Defaults to 1.

#define weapon_load(q)
return 3; // 1/10 sec.

Should return the weapon' ammo cost per shot.

Defaults to 0 for melee-type weapons and to 1 for the rest.

#define weapon_cost(q)
return 1;

Should return the number of rads spent per shot, for "ultra" weapons.

Defaults to 0.

#define weapon_rads(q)
return 0;

Should return the sound played when swapping to the weapon.

Defaults to sndSwapPistol.

#define weapon_swap(q)
return sndSwapPistol

May return whether the weapon is melee (held and swung accordingly).

Defaults to 1 for melee-type weapons and to 0 for the rest.

Should return the weapon' "difficulty tier", which determines when it'll drop.

You can check built-in weapon' tiering via weapon_get_area for reference.

#define weapon_area(q)
return 1;

Should return the weapon' sprite. Also see sprite_add_weapon.

#define init
global.spr_smg = sprite_add_weapon_base64("iVBORw0KGgoAAAANSUhEUgAAABIAAAANCAYAAACkTj4ZAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAB5SURBVDhPYwACRhBBTfAfigkBvOrAkrraZjBFODGSGqwArACG/bxjMTCyPEg9GoYDFIWEsJS4GpwN0gsxAgHACkAYm4tgciAMUouGMQCKBlwYpA6iHD9A14CCcXkHG8BmM5ymxCBkTRS7CAZgYkQZBAIka6ASYGAAANr1jVDoeE7cAAAAAElFTkSuQmCCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", 3, 4);

#define weapon_sprt
return global.spr_smg;

May return a different sprite from weapon's normal sprite for use in HUD.

This is useful for cases where the weapon is too big to have a meaningful outline in HUD when cropped automatically.

Defaults to what is returned from weapon_sprt.

May return a weapon sprite for display in Loadout.

If not defined, a tilted 2x version of weapon_sprt will be shown.

You would usually only care about this for custom golden weapons and those used as start weapons for custom races.

May return whether and which laser sight sprite the weapon should use.

Allowed values are as following:

• 1/true: show laser sight
• 0/false: hide laser sight
• (sprite index): use custom laser sight sprite

Defaults to true for bolt-type weapons and to false for the rest.

May return whether the weapon is golden and can occur in Mansion.

Possible values are as following:

• 1: Golden; can drop from Mansion' chest.
• 0: Not golden
• -1: Golden, but does not drop in Mansion (like loop-specific golden weapons).

Custom golden weapons can be locked on characters, but will only function when the according weapon mod is loaded, obviously.

Called when the weapon should be fired.

You are only obliged to create the actual projectile(s), play sound(s), and spawn any additional effects (if needed) - cooldown and ammo are deducted automatically.

#define weapon_fire(wep)
sound_play(sndPistol);
// create a shell (cosmetic):
with (instance_create(x, y, Shell)) motion_add(
	other.gunangle + other.right * 100 + random(60) - 30,
	2 + random(2)
);
// create the bullet:
with (instance_create(x, y, Bullet1)) {
	motion_add(other.gunangle + (random(32) - 16) * other.accuracy, 16);
	image_angle = direction;
	team = other.team;
	creator = other;
}
weapon_post(2, -6, 3); // weapon shift, camera shift, camera shake

Sometimes you may want to store some additional information with the weapon - say, have the weapon be far more powerful that it's tier counterparts, but only last for a limited number of shots.

For such occasions you can have the weapon-value presented as a lightweight object - if you set the weapon-value (wep / bwep on Player, wep on WepPickup, etc.) to a lightweight object with the field wep equal to your mod' ID (see mod_current), the game will call your mod on all occasions, passing the weapon-value to weapon_ scripts as first argument.

A simple limited-ammo super-heavy revolver mod would be as following:

#macro defammo 50
#define weapon_name(q)
return `LIMTIED REVOLVER (${is_object(q) ? q.ammo : defammo})`;
#define weapon_type(q) return 1;
#define weapon_cost(q) return 1;
#define weapon_sprt(q) return sprHeavyRevolver;
#define weapon_fire(q)
// pack the weapon into an object if it isn't yet:
if (!is_object(wep)) wep = { wep: mod_current, ammo: defammo };
// check ammo:
if (wep.ammo <= 0) {
	if (infammo == 0) ammo[weapon_get_type(wep)] += weapon_get_cost(wep);
	sound_play(sndEmpty);
	with (instance_create(x, y, PopupText)) {
		target = other.index;
		mytext = "EMPTY";
	}
	exit;
} else wep.ammo -= 1;
// actual firing:
sound_play_gun(sndHeavyRevoler, 0.2, -0.5);
with (instance_create(x, y, Shell)) {
	sprite_index = sprHeavyShell;
	motion_add(other.gunangle + other.right * 100 + random(50) - 25, 2 + random(2));
}
with (instance_create(x, y, HeavyBullet)) {
	motion_add(other.gunangle + random_range(-1, 1) * other.accuracy, 16);
	image_angle = direction;
	team = other.team;
	creator = other;
	damage *= 2;
}
weapon_post(6, -7, 5);

If saving it as limited-revolver.wep.gml, you could then do /loadwep limited-revolver to load the mod and /gml Player.bwep = "limited-revolver" to assign it to player's secondary weapon slot for testing.

Should return area code for display on map/loading screens (e.g. "6-?").
" L#"/" H#" are appended automatically.

#define area_name
return "ZZZ";

May return "true" if the area is in fact a secret area.

Is called with a number of area #1 sprites and should return the new sprite for them.
Used to determine sprites for floors, walls, and debris.

#define area_sprite(q)
switch (q) {
	case sprFloor1: return sprFloor0;
	case sprFloor1B: return sprFloor0;
	case sprFloor1Explo: return sprFloor0Explo;
	case sprWall1Trans: return sprWall0Trans;
	case sprWall1Bot: return sprWall0Bot;
	case sprWall1Out: return sprWall0Out;
	case sprWall1Top: return sprWall0Top;
	case sprDebris1: return sprDebris0;
}

Can return [x, y] or [x, y, showdot] or [x, y, showdot, showline] for use on map.

For secret areas you'll usually want to just return [argument0, 9].

Is executed prior to anything being generated. A good time to set seed/etc.

Is called by FloorMaker instances as they advance around. Should create floor(s) relative to current position (x, y) as well as adjusting the instance' direction. For example,

#define area_make_floor
instance_create(x, y, Floor);
var turn = choose(0, 0, 0, 0, 0, 0, 0, 0, 0, 90, -90, 90, -90, 180);
direction += turn;
if (turn == 180 && point_distance(x, y, 10016, 10016) > 48) {
	// turnarounds - weapon chests spawn in such
	instance_create(x, y, Floor);
	instance_create(x + 16, y + 16, WeaponChest);
}
if (random(19 + instance_number(FloorMaker)) > 22) {
	// dead ends - ammo chests spawn in such
	if (point_distance(x, y, 10016, 10016) > 48) {
		instance_create(x + 16, y + 16, AmmoChest);
		instance_create(x, y, Floor);
	}
	instance_destroy();
} else if (random(4) < 1) {
	// branching
	instance_create(x, y, FloorMaker);
}

Is called for floors when they may spawn an enemy. Usually are to be spawned at (x + 16, y + 16).

Is called for floor tiles when it's time to spawn props. Example:

#define area_pop_props
if (random(5) < 1
	&& point_distance(10016, 10016, x, y) > 100
	&& !place_meeting(x, y, NOWALLSHEREPLEASE)
) {
	// quarter-walls (optional)
	var myx = x + choose_w(0, 16);
	var myy = y + choose_w(0, 16);
	if (!place_meeting(myx, myy, hitme)) {
		instance_create(myx, myy, Wall);
		instance_create(x, y, NOWALLSHEREPLEASE);
	}
} else if (random_w(12) < 1) {
	instance_create(x, y, Cactus);
}

Called after numerous chests have been plucked onto the level and before the extras are cleaned up. Can modify a number of variables:

• gol: Base quantity of any chest.
• wgol: Extra weapon chests
• agol: Extra ammo chests
• rgol: Extra radiation canisters / Rogue canisters

Used for spawning extra things such as wall decals or doing area-specific postfixes, e.g.

#define area_pop_extras
with (Floor)
if (!place_free(x - 32, y) && !place_free(x + 32, y) && place_free(x, y)) {
	for (var i = -1; i <= 1; i += 2)
	for (var k = 0; k <= 1; k += 1) {
		with (instance_create(x + (1 - i) * 16, y + k * 16, Bones)) {
			image_xscale = i;
			sprite_index = sprBones;
		}
	}
}

Executed when everything finishes generating in the custom area.

Is called by GameCont on room end of the area. Should change area/subarea accordingly. For example, if you wanted to have the game go to 2-1 after your area, you could do

#define area_finish
area = 2;
subarea = 1;

Called by GameCont just after calculating the next area in a normal way. Can be used to insert areas by deciding whether to change area to yours based on lastarea, lastsubarea, area, subarea. For example, if you wanted to insert your area before 2-1, you could do

#define area_transit
if (lastarea != "test" && area == 2) {
	area = "test";
}

#define area_name
return "ZZZ";

#define area_sprite(q)
switch (q) {
	case sprFloor1: return sprFloor0;
	case sprFloor1B: return sprFloor0;
	case sprFloor1Explo: return sprFloor0Explo;
	case sprWall1Trans: return sprWall0Trans;
	case sprWall1Bot: return sprWall0Bot;
	case sprWall1Out: return sprWall0Out;
	case sprWall1Top: return sprWall0Top;
	case sprDebris1: return sprDebris0;
}

#define area_transit
if (lastarea != "test" && area == 2) {
	area = "test";
}

#define area_finish
area = 2;
subarea = 1;

#define area_setup
goal = 40;
background_color = make_color_rgb(106, 122, 175);
BackCont.shadcol = c_black;
TopCont.fog = sprFog2;

#define area_make_floor
instance_create(x, y, Floor);
var turn = choose(0, 0, 0, 0, 0, 0, 0, 0, 0, 90, -90, 90, -90, 180);
direction += turn;
if (turn == 180 && point_distance(x, y, 10016, 10016) > 48) {
	// turnarounds - weapon chests spawn in such
	instance_create(x, y, Floor);
	instance_create(x + 16, y + 16, WeaponChest);
}
if (random(19 + instance_number(FloorMaker)) > 22) {
	// dead ends - ammo chests spawn in such
	if (point_distance(x, y, 10016, 10016) > 48) {
		instance_create(x + 16, y + 16, AmmoChest);
		instance_create(x, y, Floor);
	}
	instance_destroy();
} else if (random(4) < 1) {
	// branching
	instance_create(x, y, FloorMaker);
}

#define area_pop_enemies
if (random(4) < 1) instance_create(x + 16, y + 16, Bandit);

#define area_pop_props
if (random(4) < 1) instance_create(x + 16, y + 16, NightCactus);

#define area_mapdata(lx, ly, lp, ls, ws, ll)
return [lx, 9];

Returns whether the mutation is currently acquired.

skill can be either a numeric value (see constants) or a mod name.

Acquires or unacquires the given mutation.

skill can be either a numeric value (see constants) or a mod name.

Removes all currently acquired mutations with their effects.

Used for Melting<->Skeleton transformations, for example.

Returns the mutation identifier (constants for built-in mutations, strings for mods) for the mutation at given position (0-based).

Returns undefined if out of range.

For example, if you wanted to show names of all currently acquired mutations, you could do

var i = 0;
while (true) {
	var mut = skill_get_at(i++);
	if (mut == undefined) break;
	trace(skill_get_name(mut));
}

Returns whether the given mutation is currently enabled and can appear in mutation pool.

skill can be either a numeric value (see constants) or a mod name.

Changes whether the given mutation is enabled and can appear in mutation pool.

skill can be either a numeric value (see constants) or a mod name.

mut_none = 0
mut_rhino_skin = 1
mut_extra_feet = 2
mut_plutonium_hunger = 3
mut_rabbit_paw = 4
mut_throne_butt = 5
mut_lucky_shot = 6
mut_bloodlust = 7
mut_gamma_guts = 8
mut_second_stomach = 9
mut_back_muscle = 10
mut_scarier_face = 11
mut_euphoria = 12
mut_long_arms = 13
mut_boiling_veins = 14
mut_shotgun_shoulders = 15
mut_recycle_gland = 16
mut_laser_brain = 17
mut_last_wish = 18
mut_eagle_eyes = 19
mut_impact_wrists = 20
mut_bolt_marrow = 21
mut_stress = 22
mut_trigger_fingers = 23
mut_sharp_teeth = 24
mut_patience = 25
mut_hammerhead = 26
mut_strong_spirit = 27
mut_open_mind = 28
mut_heavy_heart = 29

Returns whether the mod is allowed to sideload other mods.

This shows a prompt to the player that loaded the mod on first call and the player needs to accept via /allowmod.

Once the player had confirmed permission, the mod can use the additional functions shown below.

If sideloading (mod_sideload) is on for the mod, attempts to load the given mod much like /loadmod command would. You'll usually need to specify the path or at least the mod-type extension in this.

Returns 1 if sideloading is enabled and 0 if sideloading is disabled.

#define init
while (!mod_sideload()) wait 1;
mod_load("test.mod");

would load test.mod.gml from the same directory that the executing mod is in.

Same as mod_load, but as with /loadlive command.

Same as mod_load, but as with /loadtext command.

If sideloading (mod_sideload) is on for the mod, attempts to unload the given mod much like /unloadmod command would. You'll usually need to specify the path or at least the mod-type extension in this.

Returns 1 if sideloading is enabled and 0 if sideloading is disabled.