User Side

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.

StateHandle

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.

Member Functions

void send_script(String source) void send_script(String source, Message arg)
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 send_script(String source)
void send_script(String source, Message arg)

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)

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.

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)

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.

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.

(Int,Int) get_extent()
Returns the width and height of the game state.

void set_visible_region(Rectangle? region)
Sets the part of the level that will be visible to the player. If no region is specified, defaults to making the entire level visible.

void set_interaction_region(Rectangle? region)
Sets the part of the level that the player can interaction with. If no region is specified, defaults to making the entire level possible to interact with.

void add_hint(HintKind, String message)
Adds a message to the lower right side of the user's screen with the given message. The message will automatically disappear after some time.

HintHandle add_continuous_hint(HintKind, String message)
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.

bool is_at_start()
Return `true` if the game is not currently simulation.

PartialInteraction get_partial_interaction()
Returns the interaction that the user is currently attempting. For tutorial use.

bool is_info_tab_open()
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.`

void suppress_transport_menu(Bool?)
Hides the transport menu (or unhides if `false</code? is passed). For tutorial use.`

void suppress_interface_hints(Bool?)
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.

float get_simulation_speed()
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`.

void request_level_refresh(updates)
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.

Members

GridHandle grid
A handle to the currently visible game state.

SavingHandle

A handle passed to callbacks registered with state:on_save(...).

Member Functions

void set(String key, Message value)
Stores a given key-value pair in the save file. These keys are accessible as global variables in the user side state when the save is reloaded.

Viewport

A representation of the user's view into the world.

Members

Vectord center
The center of the view in world coordinates.

Float zoom
The zoom level, equal to the screen-coordinates length of the edges of a block in the world.

Member Functions

Vectord world_to_view(Vectord) Vectord world_to_view(Vector) Rectangled world_to_view(Rectangle) Rectangled world_to_view(Rectangled)
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.

Vectord view_to_world(Vectord) Rectangled view_to_world(Rectangled)
Converts a given point or region from screen coordinates into world coordinates.

CollectorHandle

A type passed to callbacks registered with state:on_interface_render_lower(...) or state:on_interface_render_upper(...).

Member Functions

void draw_rectangle(Rectangled region, (Float,Float,Float,Float) color)
Draws a rectangle at the given region on the screen in the given RGBA color.

void draw_menu_item(String name, Rectangled region, (Float,Float,Float,Float) color)
Draws an element of the menu atlas at the given position.

void draw_text(Text text, (Float,Float,Float,Float) color, Alignment horizontal, Alignment vertical, Vectord reference_pt)
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.

Members

Viewport viewport
The user's current viewport.

Float time
The time of the frame.

Float aspect
The aspect ratio of the game's window.

Float step_time
The progress towards the next step (between 0 and 1).

Int step_count
The number of steps fully simulated, starting from 0.

Text

A representation of text to be rendered.

Constructors

Text.new(String what, Float height) Text.new(String what, Float height, Float max_width) Text.new(String what, Float height, Float max_width, Float first_indentation, Float later_indentation)
Creates a new text request with the given parameters.

Members

String text
The text to display.

Float height
The height of the text in screen coordinates.

Float max_width
The maximum width of the text before a line break in screen coordinates.

Float first_indentation
The indentation on the first line after a line break or the start of the text. (Default: 0)

Float later_indentation
The indentation on any line other than the first after a line break or start of the text. (Default: 0)

HintKind

An enumeration of the following values, which affect the order and style in which hints are displayed:

HintKind Hint.unmarked
A plain hint.

HintKind Hint.error
An error message.

HintKind Hint.info
An informational hint.

HintKind Hint.tutorial
An error message.

HintKind Hint.rejection
A hint about an output being rejected.

MouseInfo

A class representing the state of the mouse, passed to callbacks registered with state:on_interface_update(...).

Members

Vectord where
The position of the mouse in screen coordinates.

MouseButtonState lmb
The status of the left mouse button.

MouseButtonState mmb
The status of the middle mouse button.

MouseButtonState rmb
The status of the right mouse button.

Boolean captured
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.

Float aspect
The aspect ratio of the window.

Boolean shift
Whether the user is holding Shift.

Boolean ctrl
Whether the user is holding Ctrl.

MouseButtonState

The class MouseButtonState represents four possible states for a mouse button:

MOUSE_NONE
MOUSE_CLICKED
MOUSE_HELD
MOUSE_RELEASED

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.