Built-in functions

this() -> NodeId

The node this script is on.

node(id: i32) -> NodeId

The node a #[node_path] field picked. Zero is nobody.

spawn(name: String, at: Vec2)

Makes a copy of the artifact this node's Spawner names, at a point in the world, at the end of the step.

destroy(node: NodeId)

Remove node from the scene.

destroy_self()

Remove the node this script is on.

hide()

Make this node invisible. An invisible area overlaps nothing.

show()

Make this node visible again.

set_visible(node: NodeId, visible: bool)

Show or hide another node.

position() -> Vec2

Where this node is in the world, as the step began.

move_to(position: Vec2)

Put this node at position, in world units.

move_node(node: NodeId, position: Vec2)

Put another node at position.

translate(by: Vec2)

Move this node by by, from wherever it is now.

set_scale(scale: Vec2)

Set this node's scale outright, with nothing to anneal from.

jump()

Asks this node's Character Body to jump, honouring its coyote time, jump buffer and air jumps.

cut_jump()

Cuts this node's rising jump short, keeping the share its Jump Cut sets.

drop_down()

Asks this node's Character Body to drop through the one-way ledge it stands on. Nothing happens on solid ground or in the air.

grounded() -> bool

Whether this node's Character Body stood on something as the step began.

velocity() -> Vec2

Which way and how fast this node's Character Body was moving as the step began, in world units a second; down is positive. It includes the body's Drift, the share of its motion the world gave it, such as a wind, a belt or a shove.

walk_to(point: Vec2) can be awaited

Sends this node's Nav Agent to point by the cheapest way round walls and across links; with await in front, waits until the walk ends.

stop_walking()

Stops this node's Nav Agent where it stands, or at the end of a link it is crossing.

arrived() -> bool

Whether this node's Nav Agent reached where it was last sent, as the step began.

can_reach(point: Vec2) -> bool

Whether this node could walk to point from where it stood as the step began, round walls and across links unless its Nav Agent does not use them.

road_distance(point: Vec2) -> f32

How far this node would walk to reach point by the cheapest way, in world units; -1 when it cannot reach it.

position_of(node: NodeId) -> Vec2

Where that node stood in the world as the step began; (0, 0) for a node that is gone.

nearest(group: String) -> NodeId

The nearest other shown node in the group as the step began, by straight distance; nobody, node(0), when there is none.

nearest_seen(group: String, mask: i32) -> NodeId

The nearest other shown node in the group that this node could see past walls on mask; nobody, node(0), when there is none.

can_see(point: Vec2, mask: i32) -> bool

Whether no wall on the collision layers in mask stood between this node and point as the step began; -1 is every layer.

tile_at(map: NodeId, layer: String, cell: Vec2) -> i32

The tile painted at cell on the layer named layer of the map on map, as the step began: its number in the Tilemap panel, or 0 for an empty cell, a layer the map has not got, or a node with no TileMap.

set_tile(map: NodeId, layer: String, cell: Vec2, tile: i32)

Paints tile number tile, upright, into cell on the layer named layer of the map on map, from the next step; 0 empties it. A scene tile places its node, and the node placed for a cell emptied or painted over goes. The change is the run's: the map's file, and the scene the next time it is entered, are as painted. A map, a layer or a number that does not exist changes nothing, and the Console says so once.

clear_tile(map: NodeId, layer: String, cell: Vec2)

Empties cell on the layer named layer of the map on map, from the next step, as set_tile with 0 does.

cell_at(map: NodeId, point: Vec2) -> Vec2

The cell of the map on map that the world point point falls in, in whole numbers; (0, 0) for a node with no TileMap.

cell_centre(map: NodeId, cell: Vec2) -> Vec2

Where the centre of cell of the map on map is in the world; (0, 0) for a node with no TileMap.

tile_number(map: NodeId, layer: String, cell: Vec2, key: String) -> f32

The Data row key of the tile at cell on the layer named layer of the map on map, as a number: a whole or decimal number as it is, a flag as 1 or 0, text as 0; 0 when the tile or the row is missing.

tile_flag(map: NodeId, layer: String, cell: Vec2, key: String) -> bool

The same row as a flag: a flag as it is, a number as not 0, text as false; false when the tile or the row is missing.

tile_text(map: NodeId, layer: String, cell: Vec2, key: String) -> String

The same row as text: text as it is, a flag as true or false, a number written out; empty when the tile or the row is missing.

build_placeholder()

Builds what this node's Placeholder stands for, as its child, at the end of the step: the artifact's nodes, their scripts told on_create on the next step, and the scene tiles of any map in it placed as it arrives. Asked again, or once built, nothing more is built. On a node with no Placeholder, or one naming no artifact, nothing is built, and the Console says so once.

start_timer()

Starts this node's Timer on a fresh countdown of its Wait Time.

stop_timer()

Stops this node's Timer, throwing away what was left of its countdown.

time_left() -> f32

How many seconds were left on this node's Timer as the step began; 0 when it is stopped or there is none.

play_clip(clip: String)

Plays one of this node's Animated Sprite clips from its first frame, even the one already playing.

play_property_clip(clip: String)

Plays one of this node's Property Animation clips from its start, even the one already playing or one that has finished.

set_param(name: String, value: f32)

Sets the number name that this node's State Machine and layers read, from the next step.

set_param_flag(name: String, on: bool)

Sets the switch name that this node's State Machine and layers read, from the next step.

trigger(name: String)

Fires the trigger name for this node's State Machine and layers on the next step, and it is gone after that step whether a connection took it or not.

state() -> String

The state this node's State Machine was in as the step began, a nested one written like air/rise; empty with none.

ragdoll(limp: bool)

Turns every Physical Bone on this node and under it limp, so the rig falls as bodies pinned together; false stands it back up at its rest pose.

play_cutscene() can be awaited

Plays this node's cutscene from its start, or from its end at a negative speed; with await in front, waits until it ends.

complete()

End the level as won; a level of the Levels list opens the next one, or the list's Then open scene after the last.

fail()

End the level as lost; a level of the Levels list opens again from its start.

change_scene(name: String)

Moves the game to a fresh copy of the scene with that name, its file's name without .ron or .scene, at the end of the step; kept and saved values carry over.

pause()

Pauses the game at the end of the step: nodes set to run while paused keep going, and the rest stop where they are.

resume()

Ends the pause at the end of the step.

quit()

Closes the game at the end of the step, once its saves are written; in the editor, stops Play.

set_time_scale(scale: f32)

Runs the whole game at scale of its speed from the next step, between 0.05 and 1, until the scene changes; a sprite on Unscaled ticks keeps real time.

emit(signal: String)

Tell whoever the scene connected to this node. They hear it next step.

heard(signal: String) -> bool

Whether signal reached this node's inbox this step.

heard_value(signal: String) -> f32

The number signal carried into this node's inbox this step, such as a frame trigger's payload; 0 if it carried none or was not heard.

in_group(node: NodeId, group: String) -> bool

Whether that node was in the group as the step began; false for a node that is gone.

emit_to(group: String, signal: String)

Sends a signal to every node in a group; they hear it on the next step.

keep_number(key: String, value: f32)

Keeps a number until the game closes; it lands at the end of the step.

add_number(key: String, amount: f32)

Adds to a kept number at the end of the step; a key never kept, or holding a point, counts as 0.

kept_number(key: String, default: f32) -> f32

Reads a kept number as it was when the step began, or default if it was never kept or holds a point.

keep_point(key: String, value: Vec2)

Keeps a point until the game closes; it lands at the end of the step.

kept_point(key: String, default: Vec2) -> Vec2

Reads a kept point as it was when the step began, or default if it was never kept or holds a number.

save_number(key: String, value: f32)

Saves a number to disk, where it lasts from one launch of the game to the next; it lands at the end of the step.

saved_number(key: String, default: f32) -> f32

Reads a saved number as it was when the step began, or default if it was never saved.

save_text(key: String, text: String)

Saves text to disk, where it lasts from one launch of the game to the next; it lands at the end of the step.

saved_text(key: String, default: String) -> String

Reads saved text as it was when the step began, or default if it was never saved or holds a number.

forget(key: String)

Forgets a saved value, number or text, so it reads as its default from then on; it lands at the end of the step.

set_language(code: String)

Switches the game's text to the language code names, such as fr; it lands at the end of the step.

language() -> String

The code of the language the game's text is in, such as en; empty if the game has no tables.

held(action: String) -> bool

Whether the player is holding action down.

pressed(action: String) -> bool

Whether action went down on this step: a key, a button, a slider moved, a box ticked, a list choice, Enter in a text field, or a drag landing or coming back.

direction(action: String) -> Vec2

Where action's composite points: right minus left, down minus up.

amount(action: String) -> f32

How far a slider for action is set, in its own range; 1 or 0 for a tick box; a list's choice from 0; a number field's number; what a drop delivered; for a key, 1 while it is held and 0 otherwise.

entered(action: String) -> String

The text in the text field for action, as the step began; empty if there is none.

letters() -> f32

How many characters the Text on this node shows in all as the step began, leaving out markup tags; 0 if it has no Text, and 0 in the editor while the game is not playing.

camera_view() -> Vec4

What the camera shows, in world units: (left, top, right, bottom).

camera_fit(point: Vec2, size: Vec2) -> CameraFit

How much of a size box centred on point the camera shows: .Whole, .Partial or .Outside.

cut()

Cuts the game's camera straight to its live framing, with no blend. Needs a Camera Rig on the camera the game is seen through; without one nothing moves, and the Console says so once.

shake(strength: f32, seconds: f32)

Shakes the camera the game is seen through, with a Camera Rig or without, by up to strength world units for seconds; a weaker shake during a stronger one changes nothing. The picture moves, not the camera: the shake is drawn on top of the Camera's Offset and never written into it, so an Offset a script anneals or sets meanwhile is drawn shaken and is exactly what it wrote once the shake ends; where the camera rests, which camera_view() and the room's Confiner read, stays put.

make_current()

Makes the Camera on this node the one the game is seen through, and switches every other camera in the scene off: a cut to it, its room taken at once and a shake carried over. On a node with no Camera nothing changes, and the Console says so once.

random(min: f32, max: f32) -> f32

A number from min up to but not including max, new at every call, on every turn of a loop, and different every Play.

random_per_play(min: f32, max: f32) -> f32

A number from min up to but not including max, rolled once per Play for each place it is written and each turn of a loop around it, on each node.

burst(count: f32)

Adds count particles to this node's particle emitter at the end of the step, as the Particles panel's Burst does; a full pool drops the rest.

restart()

Empties this node's particle emitter at the end of the step and lets a One Shot fire again.

play_sound(clip: String)

Play a clip bound on this node's AudioSourceComponent.

play_music(clip: String)

Start a music track. A track the level's music asset names is changed to by the asset's rule for the pair: a cut, a crossfade, or at the end of the playing track's pass. Any other name is a clip bound on this node's AudioSourceComponent, which replaces whatever was playing. Asking for the track already playing leaves it playing.

stop_sound()

Silence this node's sounds.

stop_music()

Stop the music track.

set_master_volume(level: f32)

Set the master bus, 0.0 to 1.0.

set_music_volume(level: f32)

Set the music bus, 0.0 to 1.0.

set_sfx_volume(level: f32)

Set the effects bus, 0.0 to 1.0.

set_mix(name: String, seconds: f32)

Slide the mix to the Audio Mix snapshot called name over seconds, and hold it there: no zone moves the mix until clear_mix().

clear_mix(seconds: f32)

Let go of the mix set_mix() holds, sliding over seconds to the zone the listener stands in, or else to the room's own mix.

set_music_layer(name: String, volume: f32, seconds: f32)

Fade the music's layer called name to volume, 0.0 to 1.0, over seconds, on every track playing; the level is kept for any track that starts with a layer of that name later.

set_number(component: String, property: String, value: f32)

Write a number onto another component on this node. A path such as velocity.x reaches one part of a point. An optional whole number takes one at least 0, and a negative one empties it.

set_flag(component: String, property: String, value: bool)

Write a true/false onto another component on this node.

set_point(component: String, property: String, value: Vec2)

Write a point onto another component on this node.

set_colour(component: String, property: String, value: Vec4)

Write a colour onto another component on this node.

set_text(component: String, property: String, text: String)

Write text onto another component on this node; any text field works, and a choice field takes one of its choices by name, such as "Deny".

vec2(x: f32, y: f32) -> Vec2

Build a Vec2.

vec4(x: f32, y: f32, z: f32, w: f32) -> Vec4

Build a Vec4. A colour is red, green, blue, alpha.

tau() -> f32

One full turn in radians.

abs(x: f32) -> f32

The absolute value of x.

floor(x: f32) -> f32

x rounded down to the whole number at or below it, so 2.7 gives 2 and -0.5 gives -1.

min(a: f32, b: f32) -> f32

The smaller of a and b.

max(a: f32, b: f32) -> f32

The larger of a and b.

clamp(x: f32, lo: f32, hi: f32) -> f32

x, kept between lo and hi.

sqrt(x: f32) -> f32

The square root of x; 0 for a negative number.

angle_of(direction: Vec2) -> f32

The angle direction points at in radians, as a rotation: 0 to the right, a quarter turn straight down; 0 for no direction.

angle_between(a: Vec2, b: Vec2) -> f32

The angle between two directions in radians, from 0 when they point the same way to half a turn when they are opposite.

ease(curve: Easing, t: f32) -> f32

Run t (0 to 1) through curve and return where it lands.

text(value: f32) -> String

A number as text: a whole number with no decimal point, anything else with up to two decimals.

anneal_by(by: Vec2, seconds: f32, curve: Easing) can be awaited

Move this node by by over seconds, following curve.

anneal_to(position: Vec2, seconds: f32, curve: Easing) can be awaited

Move this node to position over seconds, following curve.

anneal_turn(by: f32, seconds: f32, curve: Easing) can be awaited

Turn this node by by radians over seconds, following curve.

anneal_rotation(angle: f32, seconds: f32, curve: Easing) can be awaited

Turn this node to face angle radians, the short way, over seconds.

anneal_scale(scale: Vec2, seconds: f32, curve: Easing) can be awaited

Scale this node to scale over seconds, following curve.

anneal_number(component: String, property: String, to: f32, seconds: f32, curve: Easing) can be awaited

Anneal a number field on another component on this node to to.

anneal_point(component: String, property: String, to: Vec2, seconds: f32, curve: Easing) can be awaited

Anneal a point field on another component on this node to to.

anneal_colour(component: String, property: String, to: Vec4, seconds: f32, curve: Easing) can be awaited

Anneal a colour field on another component on this node to to.

pulse_by(by: Vec2, seconds: f32, curve: Easing) runs until stopped

Move this node by by and back, forever, seconds each way.

pulse_turn(by: f32, seconds: f32, curve: Easing) runs until stopped

Turn this node by by radians and back, forever, seconds each way.

pulse_scale(scale: Vec2, seconds: f32, curve: Easing) runs until stopped

Scale this node to scale and back, forever, seconds each way.

pulse_number(component: String, property: String, to: f32, seconds: f32, curve: Easing) runs until stopped

Anneal a number field on another component to to and back, forever.

pulse_point(component: String, property: String, to: Vec2, seconds: f32, curve: Easing) runs until stopped

Anneal a point field on another component to to and back, forever.

pulse_colour(component: String, property: String, to: Vec4, seconds: f32, curve: Easing) runs until stopped

Anneal a colour field on another component to to and back, forever.

quench()

Stop every anneal and pulse running on this node, wherever each stands.

quench_path(path: String)

Stop the anneal or pulse running on one property of this node.

break_here(reason: String)

Pause the editor on this frame, saying why.

await wait(seconds: f32)

Suspend for seconds, then carry on from here.

await wait_frames(steps: i32)

Suspend for steps simulation steps.

await wait_until(condition: bool)

Suspend until condition is true. Tested once per step.

await signal(name: String)

Suspend until name arrives in this node's inbox.