Scripting

This article details an upcoming feature in V0.3 that is only available in pre-releases.

Scripting is programmed level-specific behaviour that is currently defined by inputting command lines in the level files' "script" section. It has three main components: Variables, triggers and events. Variables are used to keep track of what's happening in the level. Triggers check for when something specific occurs in the level. Events are executed to alter the level or player in some way.

To assist you, the Level Editor can show the Row, Column and Tile ID you are currently hovering by clicking the Script Interface button. There is also a handy log that tells you exactly what has occured and if any errors happen.

Scripting structure

The scripting works by calling events from triggers. The syntax is the following:

OCCURENCE(TRIGGER)[EVENT]

Where you replace each word with a proper scripting sentence.

• OCCURENCE defines how many times the event can happen.
  • when - Fires every time the trigger happens. Triggers such as "walk" and "drive" execute once every time the tile is entered, not while someone is there.

• • if - Fires once, and then the trigger is removed forever
  • for - not implemented.
  • while - not implemented.
• TRIGGER defines when the event should be called.
• EVENT defines what should happen.

Variables

First you might want to declare some variables. Variables keep track of user-defined values and can read values from the level as well, such as the current crystal count or the amount of miners in the level. Always declare variables at the start of the script.

There are three variable types: Strings, integers, and floats. These can be used to keep track of what happens in a level, such as how many times the player has reinforced walls or how many caverns they have opened. This is how to declare them:

string MessStr="This is a message!"

int MyInteger=5

float MyFloatNumber=2.6

This saves the string "This is a message!" to MessStr. When you later write MessStr anywhere, such as show a message of that string, it will be replaced by the message "This is a message!". Citations around strings are not required at the moment.

There are also variable names that are reserved as macros and cannot be overwritten. When used in scripting, these will return information about the game status. These are:

Reserved variables

crystals	Returns the crystal count
ore	Returns the ore count
studs	Returns the studs count
air	Returns the air status in miner-seconds
miners	Returns the amount of miners
vehicles	Returns the amount of vehicles
buildings	Returns the amount of buildings

You can use these to e.g. show a message when the player has collected 3 crystals or trigger a monster invasion if the player constructs too many buildings (with a fair warning first).

Triggers

A trigger activates in response to things that happen in the world, such as a wall being drilled or a miner walking over a tile.

Here is a list of the currently available triggers:

• (drill:ROW,COLUMN) - Call the corresponding event when a wall at ROW,COLUMN is drilled, or the wall there collapses.
• (laser:ROW,COLUMN) - Call the corresponding event when a wall at ROW,COLUMN is destroyed by a laser.
• (laserhit:ROW,COLUMN) - Call the corresponding event when a wall at ROW,COLUMN is hit by a laser, but not destroyed.
• (change:ROW,COLUMN) - Call the corresponding event when a wall at ROW,COLUMN is changed in any way. This includes reinforcing, shoveling once, drilling, finding a cave etc
• (change:ROW,COLUMN,ID) - Call the corresponding event when a wall at ROW,COLUMN is changed in any way to a tile of type ID.
• (reinforce:ROW,COLUMN) - Call the corresponding event when a wall at ROW,COLUMN is reinforced by any unit.

• (time:SECONDS) - Call the corresponding event when SECONDS seconds have been reached. Supports decimal floats.

• (hover:ROW,COLUMN) - Activates when the player hovers that tile. The tile has to be visible.

• (click:ROW,COLUMN) - Activates when the player clicks that tile. The tile has to be visible.

• (walk:ROW,COLUMN) - Activates when a miner walks on a tile.

• (drive:ROW,COLUMN) - Activates when a vehicle drives on a tile.

• (VARIABLE>=OTHERNUMBER) - Activates when VARIABLE is larger than, or equal to, OTHERNUMBER. The operands can be replaced by any valid float or integer variable, and also regular numeric values. All variables used here are converted to integers, which cuts off any decimals, so if you compare 2.2 and 2.9 they will be equal.

Comparisation operators

>=	Larger than or equal to
>	Larger than
<=	Less than
<	Less than or equal to
==	Equal to
!=	Not equal to

Events

• [drill:ROW,COLUMN]: Drill tile ROW,COLUMN. It will play the appropriate effect and place rubble, ignoring what tile it is. This'll get fixed later to check that the tile can actually be drilled.

• [msg:MsgStr]: Display the message string MsgStr, as defined above

• [place:ROW,COLUMN,ID]: Place tile with ID at ROW,COLUMN. To find the IDs of the tiles, check the Wiki: https://manicminers.fandom.com/wiki/Level_data_file. Note that if you place a wall on top of a miner or vehicle, they will just phase through the ground. This behaviour will be updated in the future to simply bury them until they are dug out.

• [wait:SECONDS]: Wait for SECONDS seconds before executing the next command. Only supported inside of event chain.

• [win:MsgStr]: Player wins the level with the message defined by string MsgStr

• [lose:MsgStr]: Player loses the level with the message defined by string MsgStr

• [sound:MySoundName]: Plays the .ogg file of that name from /ManicMiners/Levels/ASSETS/Sounds

• [pan:ROW,COLUMN]: The player's camera pans to the tile at ROW,COLUMN

• [shake:1.0]: The player's camera shakes with magnitude 1.0. The magnitude can be increased above 1.0.

Math events

Variables like int, float and string have specific events that makes it possible to alter them while the game is running.

Mathematical operators

Addition	+=	Addition by
-	Subtraction	-=	Subtraction by
*	Multiplication	*=	Multiplication by
//	Division (note the double lines)	/=	Division by

Event chains

You can also declare events as chains (functions) that can be called all at once. The syntax is like this:

EVENT;

where EVENT_CHAIN is replaced by whatever name you want and EVENT are the events you want to execute, in order. When you then write EVENT_CHAIN instead of a regular event anywhere, it will call the EVENT_CHAIN instead and execute the EVENT lines one by one. This can occur multiple times. You can put delays in event chains using the "wait" event, at which point the rest of the event will execute at a later time. Note that after each event chain there must be an empty line to signal the end of the event.

Objectives

You can bind objectives to scripting using the register keyword as such:

register:NumDrilledWalls>=10/Drill these 10 walls!

This will create an objective called "Drill these 10 walls!" that will be fulfilled when the variable NumDrilledWalls becomes 10 or larger.

Examples

Show a message when a wall is drilled

string HappyBirthday="Happy birthday, cadet!"
when(drill:2,2)[msg:HappyBirthday]

When any unit drill the wall in row 2, column 2, call the message event which in this case will display the text saved in the string variable HappyBirthday. As that string was defined above, drilling this wall wishes the player a happy birthday!

Time based event

when(time:10)[place:6,7,11]

When time reaches 10 seconds, place a tile of water (ID 11) at row 6, column 7.

Increasing counter with a chain event

int counter=0
string myStr="Counter: "
string myMsg

when(click:6,6)[myChain]
myChain::counter+=1;
myMsg=myStr+counter;
msg:myMsg;

Every time you click on the tile at row 6, column 6 the value of counter increases and a message is displayed with the new value.