Stage Scripting

Advanced stages can be given access to custom scripts and articles by setting the scripting parameter in its config.ini to “1”.

Stages with scripting enabled get two new tabs in addition to terrain and player spawns: Markers and Article spawners.

Markers

Markers are simply a set of immovable coordinates. They can be used in a variety of ways, such as creating a path for a moving platform to follow or arbitrary boundaries for things like goalposts or spawn areas.

To find a specific marker’s coordinates in a match, use the functionsget_marker_x()→  and get_marker_y()→

Selecting or placing one opens a small menu that lets you change the marker’s color and symbol for better organization.

Article Spawners

For more details on how stage articles themselves work, check the Articles and Stage Articles pages.

At the start of a match, article spawners will create an article that uses the script set corresponding to the spawner’s number, shown on the upper-right of its icon in the top bar. Selecting or placing one opens a menu with the following properties:

Obj Type – Whether the article is normal, a platform or a solid block.

Layout – Whether the article will spawn in both stage layouts, or is exclusive to either Aether or Basic. When articles are spawned manually (outside the stage builder) the function is_aether_stage()→ can be used instead.

Depth – The depth of the article, which determines whether it shows in front of (negative value) or behind (positive value) other layers. An extensive list of which depth value corresponds to each layer can be found on the Stage Sprites page.

Parallax X – The article’s horizontal parallax (only applies to normal articles)

Parallax Y – The article’s vertical parallax (only applies to normal articles)

ARG0 – ARG7 – These values will be transferred to the article’s spawn_variables array when created.

Folders

Scripted stages will detect the following additional folders: /scripts/, /scripts/attacks/, /sounds/sfx/, and /sprites/articles/.

The scripts and attacks folder behave similarly to character scripts. To see what scripts stages normally use and when they use them, check the Stage Scripts page.

The sfx folder loads sounds to be used with the sound_get()→ function, much like the sounds folder in players. Likewise, the articles folder loads sprites for use with sprite_get()→

Rule Overrides

Custom stages can also override the normal rules, accessible via the stage’s config.ini file, under the section labelled [scripting_overrides]. A value of -1 means the rule will not be overridden.

Variable	Description
stocks	Overrides the amount of stocks a player starts with. Setting this to "0" will disable stocks.
time	Overrides the time limit for the match. Setting this to "0" will disable the timer.
teams	Overrides teams. Setting this to "0" disables set teams, and setting it to "1" will auto-sort every other player into opposite teams if teams were not enabled in the lobby beforehand.
team_attack	Overrides team attack, either enabling or disabling friendly fire.
hide_hud	Disables the HUD. Setting this to "2" will hide the standard hud while still running the stage's draw_hud.gml

Stage Scripts

• load.gml– Called right after the item is loaded into the game. This is where you would normally set sprites’ origins and bounding boxes.
• unload.gml - Called when the item is unloaded. This is where you want to clear out anything that wouldn't be unloaded automatically.
• init.gml – Called once the main stage object is created.
• other_init.gml – Called by all other players on the stage. This is where you want to initialize variables that you can change on other players.
• draw_hud.gml – Used to draw HUD for custom game modes. Draws over every other player’s HUD.
• match_end.gml – Called the moment the match ends.
• article[index]_init.gml – Called once the specified custom article object is created.
• article[index]_update.gml – Called every frame for the specified custom article object.
• article[index]_draw.gml – Used to draw things on an article. Everything will be drawn in front of the article.
• npc_hit_player.gml – Called when you hit another player with any hitbox. Use hit_player_obj to reference the player object that was hit. Use hit_player to reference which player you hit (player 1, player 2, etc). Use my_hitboxID to reference the hitbox you hit them with. To change the knockback given, edit hit_player_obj.orig_knock. You can disable the purple kill effect by setting hit_player_obj.should_make_shockwave to false.
• npc_got_parried.gml – Called when your hitbox is parried. Use hit_player_obj to reference the player object who parried your hitbox. Use hit_player to reference which player parried your hitbox (player 1, player 2, etc). Use my_hitboxID to reference the hitbox that was parried.
• player_death.gml – Called whenever a player dies. Use hit_player_obj to reference the player object that just died.
• Anything under the /scripts/attacks folder

Stage Player Objects

oPlayer instances spawned via stages will search for all normal script and sprite names, but with "npc_" prefixed to it (npc_idle.png, npc_update.gml, etc.) These sprites should be placed in /sprites/articles.

The hitbox-relevant scripts npc_hit_player.gml and npc_got_parried.gml will also play for any hitbox that the stage spawns.