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 functions  and

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:

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

– Whether the article will spawn in both stage layouts, or is exclusive to either Aether or Basic.

– The depth of the article, which determines whether it shows in front of (negative value) or behind (positive value) other layers. A depth of 0 is the ground layer. A depth of -30 is behind the ground layer.

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

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

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

Folders
Scripted stages will detect the following additional folders:,  ,   and.

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 function, much like the sounds folder in players. Likewise, the articles folder loads sprites for use with

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

Stage Scripts

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

Stage Player Objects
instances spawned via stages will search for all normal script and sprite names, but with "npc_" prefixed to it (, , etc.)

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