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.
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
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.
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).
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.
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.
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.
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.
GameEvent
A variant referring to a value of type either AcceptEvent or RejectEvent.
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.
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.