Physics Thread

This page describes classes which are only accessible from the physics thread: GameHandle and GraphicEntityHandle.


The class GameHandle is a handle through which a script running on the physics thread interacts with the state of the simulation. The global variable game is an instance of this type. Note that positions given to this class refer to the game's full state, which includes an impenetrable border 2 units thick; as a result, only coordinates between 2 and the game's width or height minus 3 refer to usable positions. The portion of the level visible to the player is usually an even smaller rectangle within this - it is typical to use the parts of the grid that are usable but not visible to spawn inputs and delete outputs.

Member Functions

VisibleBlock? at(Vector position)
VisibleBlock? at(Int x, Int y)
Inspects the current content of position and, if there is a block there, returns a VisibleBlock representing it. Returns nil otherwise.
void interact(Interaction interaction)
void interact(vector<Interaction> interactions)
Applies the listed interaction or interactions to the game.
void place(Vector position, VisibleBlock block)
void place(Vector position, View view, BlockSpecification block)
void place(Vector position, BlockSpecification block)
If possible, places the block specified by block at the given position. The first overload ignores everything about block except its members block.view and block.what. The last overload uses the identity view.
Note that placements can also be done via game:interact
void join(CellFace face)
void join(CellFace face, Int tensile_strength, Int lateral_strength)
If possible, creates a joint at the indicated face. If three arguments are specified, places a joint with the specified strengths, otherwise uses the default strengths.
Note that joins can also be done via game:interact

vector<Interaction> grab_interactions_from_region(Rectangle region)
Returns a list of interactions necessary to recreate the object in the specified region. The interactions returned have their coordinates shifted so that they would recreate the object with its lower corner moved to (0, 0). This can be used in conjunction with transform_interaction to recreate the object somewhere else, possibly after rotations or flips.
void destroy(Vector position)
Destroys all blocks at position.
CellView neighbor(CellView base, Direction dir)
Returns the position that an object starting at base and moving by dir would end up after one step (following any portals that this might pass through).
CellFace meeting(CellFace base)
Computes the face that matches up with the given one (after following all portals that might affect this in the true geometry of the world).

void each_step(Callback callback)
Immediately calls callback() and does so at the start of every subsequent step of the simulation.
GraphicEntityHandle create_graphic(GraphicEntity graphic)
Adds a graphic entity to the rendered state. Note that this entity will become visible at the time point currently being computed on the physics thread and stay visible until the handle is destroyed. These entities are not preserved in save files.
void send_script(String source)
void send_script(String source, Message arg)
Attaches a script to the current physical state, which will run as soon as the state is transferred to the renderer. 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 set_success()
Indicates that the level is complete.
void send_event(GameEvent event)
Attaches the specified event to the current state.
PinReference? pin(Vector position, Movement? direction)
Creates an invisible pin on the block at the specified position. This prevents movement in the specified direction. If NEUTRAL or nil is given for direction, the pin prevents movement in all directions. This can be used, for example, to prevent an incorrect output from moving to the right.
If successful, returns a handle that can be used to later remove this pin.
DestroyHookReference? on_destroy(Vector position, Callback callback)
If there is a block at the given position, this function will ensure that callback is called when that block is destroyed.
If successful, returns a handle that can be used to unhook this callback.
QuotaReference add_quota(Int amount, String text)
Adds a quota to the quota list, with the given amount and text.
Returns a reference to this quota that can be used to later update the amount or change its status.
GameBuilder? get_initiator()
If a solution is currently being simulated, returns an object describing the state of the solution when the player started the simulation. Returns nil if the player is working on the factory. This can be used to award achievements based on the player's solution rather than the current state of the simulation.
Int get_step_count()
Returns the number of steps since the simulation of the level began. Starts at 0.
void achieve(String achievement_name)
Marks the named achievement as completed.
void disable_cross_welding(Boolean? flag)
If flag is true or not provided, disables welds between objects that are only connected to the weld sites by a path that passes through the front end of inactive portals.

Otherwise enables this behavior (enabled by default).

void on_cross_weld(Callback callback)
Calls callback(face, is_weld) whenever either the face at face is welded due to cross-welding (with is_weld being true in this case) or whenever the face at face is considered already connected (hence performs a shallow weld) due to cross-welding (with is_weld being false in this case).
TrackerReference? track(Vector2 position)
TrackerReference? track(Int x, Int y)
If there is an object at the specified position, returns a reference that can be used to track its position in the future.


A variant referring to a value of type either AcceptEvent or RejectEvent.


Constructors region)
An event indicating that an output has been accepted at the given region. Rendered with a green rectangle effect when received by the user and triggers a sound effect.


Rectangle where
The region of the event.


Constructors region)
An event indicating that an output has been rejected at the given region. Triggers a sound effect.


Rectangle where
The region of the event.


A handle to a pin that was created by game:pin(...).

Member Functions

void destroy()
Destroys the pin.


A handle to track objects. Return from game:track(...).

Member Functions

Boolean exists()
Returns whether the tracked object still exists.
CellView get_position()
Returns the tracked object's current position.


A handle to a pin that was created by game:add_quota(...).

Member Functions

void set_okay(Bool)
Sets whether the quota is okay (by default true). A quota which is not okay will be displayed in red on the quota menu and should be used to indicate that an incorrect output has been received.
Bool get_okay()
Gets whether the quota is okay.
void set_remaining(Int)
Sets the remaining count of the quota.
Int get_remaining()
Gets the remaining count of the quota.
Bool decrement()
Decreases the remaining count of the quota by 1, if the remaining count was positive. Returns true if the count is now zero and false otherwise.



vector<Interaction> reconstruction_actions
The interactions required to rebuild the state.
Table keys
A table of keys saved with the state.