This page describes classes which are only accessible from the user side: StateHandle. Note that commands written in the console are executed on the user side, though they can use send_script to send scripts to the physics side.
The class StateHandle is a handle through which a script running on the user thread interacts with the user and displays any overlays on top of the game world. The global variable state is an instance of this type.
Sends a script to the physical state, which will run as soon as the physical state next accepts interactions - which is the earlier of when the game is paused or when the currently rendered step and the succeeding one have been fully displayed. You may optionally pass a parameter arg which will be sent with the script and may be accessed in the sent script as arg. Any other type passed as arg will be automatically converted to Message if possible.
void begin_interaction(Table specification)
Begins a custom interaction. (TODO)
void filter_interactions(Callback callback)
Calls callback whenever the game tries to determine whether an action is legal - this will occur both when the user actually attempts to interact and when they merely have a tool open and could possibly interact. The expression callback(interaction) should return nil if the interaction is allowable and should otherwise returnn a string. The argument action is the Interaction in question. Note that if the user attempts an interaction which is blocked by the filter, the retured string will be shown to them as an error message in the lower right of their screen.
void filter_user_interactions(Callback callback)
Calls callback whenever the user tries to interact. If callback(action) returns false, where action is the UserAction attempted, the action is not performed. Interactions necessary to exit the level or quit the game cannot be intercepted. This is only used for tutorials in the campaign - and it is strongly recommended to use state:filter_interactions instead of this function in essentially all cases.
The relevant user actions are not yet well documented.
void on_interface_update(Callback callback)
Calls callback(mouse) every frame (unless the console is open), where mouse is a value of type MouseInfo. If the callback returns true, the mouse will be regarded as captured.
void on_interface_render_lower(Callback callback)
Calls callback(collector) every frame, where collector is a value of type CollectorHandle, which can be used to draw on to the user's screen, underneath the rest of the interface.
void on_interface_render_upper(Callback callback)
Calls callback(collector) every frame, where collector is a value of type CollectorHandle, which can be used to draw on to the user's screen, above the rest of the interface.
void on_save(Callback callback)
Calls callback(save) when the game is saved, where save is a value of type SaveHandle, which can be used to associate extra values to the save file - and which should be used to ensure that if the game is saved and then loaded (restoring all the given keys), the user will not notice any discontinuity.
Adds a message to the lower right side of the user's screen with the given message. The function returns a handle that must be used to later dismiss the hint. Hints are automatically dismissed whenever the game reloads.
Return true if the game is not currently simulation.
Returns the interaction that the user is currently attempting. For tutorial use.
Return true the info tab is open. For tutorial use.
void, Bool? suppress_toolbar_menu()
Hides the toolbar menu (or unhides if false</code? is passed). For tutorial use.
Hides the transport menu (or unhides if false</code? is passed). For tutorial use.
Hides the interface hints (or unhides if false</code? is passed). For tutorial use.
Rectangled lookup_interface_parameter(String key)
Returns the position of a specified element of the interface. For tutorial use.
Returns the current speed of the simulation. A speed of 1 equals 4 steps of the simulation per second.
void set_info_menu_key(String key, String value)
Sets the text to display for a given challenge's toggle in the info menu.
void on_info_key_click(Callback callback)
Calls callback(key) whenever the user clicks a toggle in the info menu with the given key.
Requests that the current state be reloaded, with an optional argument updates that is a table with save keys to be updated. The request will take place after all scripts finish running if we are at the start of a level, or will take place whenever the user next returns to the start of the level if the simulation is running.
Converts a given point or region in world coordinates into screen coordinates. Screen coordinates range from -1 to 1 vertically from bottom to top and range -aspect to aspect horizontally, where aspect is the aspect ratio of the screen.
Draws text. The reference point and alignment controls where the text will be displayed on screen - for instance, if the alignment parameters are ALIGN_MIDDLE and ALIGN_LOWER, then the text will be positioned such that reference_pt.x is the horizontal center of the text and reference_pt.y is the vertical position of the bottom edge of the text.
The user's current viewport.
The time of the frame.
The aspect ratio of the game's window.
The progress towards the next step (between 0 and 1).
The number of steps fully simulated, starting from 0.
A boolean representing whether the mouse is captured by some other element on top of the one being updated. If true, you should not treat mouse clicks as being directed at the current interface. If you wish to capture the mouse, you should return true from the update callback; simply setting this member to true will not work.
The aspect ratio of the window.
Whether the user is holding Shift.
Whether the user is holding Ctrl.
The class MouseButtonState represents four possible states for a mouse button:
When a mouse button is clicked, the state will change to MOUSE_CLICKED for one frame, and then MOUSE_HELD until the mouse button is released, giving MOUSE_RELEASED for one frame, then MOUSE_NONE until the mouse button is clicked again.