Docs Quick code

Function reference

Every game function, object command and field, and the language's own functions. Generated from the code.

Generated by editor/tools/build_code_docs.gd from the language itself — don't edit by hand. The same list is in reference/api.json for tools and the website.

#Game functions

#Messages & screen

Function	What it does
`popup(text)`	a short message on screen
`banner(text)`	a big announcement in the middle of the screen ("Boss fight!"); {names} show values
`hud_text(name, text, corner = "top_right")`	text on screen that updates itself: "Score: {score}" ({name} = a variable, counter, item or timer)
`hud_clear(name)`	removes an on-screen text
`hud_bar(name, value, max, corner = "top_left", color = "hp")`	a bar on screen (health, boss, progress); hud_clear(name) hides it
`show_hud(name)`	shows one of your HUDs (HUDs panel), e.g. show_hud("Boss bar")
`hide_hud(name)`	hides a HUD
`toggle_hud(name)`	shows a hidden HUD, hides a shown one
`hud_shown(name)`	true while that HUD is showing
`choice(question, options)`	shows the choices and waits; gives the one picked (its text)
`screen_effect("flash", seconds = 0.5, strength = 1, color = "white")`	flash / blur / split / black_white / wobble for a moment
`shake(strength = 0.15, seconds = 0.4)`	shakes the screen
`camera_look(object, seconds = 2)`	the camera looks at an object (or player) for a while
`print(text)`	prints to the editor's Output (Play mode)

#Waiting & timing

Function	What it does
`wait(seconds)`	pause this code (the game keeps going)
`dt()`	seconds since the last frame: x += speed * dt() moves at the same speed on every computer
`time()`	seconds since the level started (game time; it stops while the game is paused)
`frame()`	how many frames since the level started
`hour()`	the time of day, 0 to 24 (with a day & night cycle)
`set_hour(h)`	jump to that time of day (e.g. 20.5 = half past eight in the evening)
`is_night()`	true after dusk and before dawn
`day()`	which day it is (1 at the start; +1 each midnight)
`start_timer(name, seconds, when_done = "nothing", show = true)`	a countdown (show = false keeps it off screen, for your own HUD); when_done: "lose", "win"
`stop_timer(name)`	—
`time_left(timer)`	seconds left on a timer (0 = not running)

#Running code at the same time

Function	What it does
`run_async(fn, …)`	runs a function alongside this code (both carry on); gives a task
`every(seconds, fn)`	calls fn every few seconds until cancelled; gives a task
`after(seconds, fn)`	calls fn once, later; gives a task
`cancel(task)`	stops a task from run_async, every or after
`task_running(task)`	true while that task hasn't finished or been cancelled

#Messages & events

Function	What it does
`send(message, data = nil)`	every on_message(message, …) handler and "Message received" event runs (data goes along)
`on_message(message, fn)`	calls fn(data) whenever send(message, data) happens
`on(event, fn)`	calls fn when this object's event happens: "touched", "bumped", "used", "destroyed", "hurt"
`event_data()`	what came with the event or run_script(id, data) that started this script
`run_script(id, data = nil)`	runs that script's "Called" events; their code reads data with event_data()
`player_event(name)`	runs your own player event (Player controls: an Event set to "My own player event")

#Items & money

Function	What it does
`has(item)`	how many the player has ("* key" = any key)
`give(item, count = 1)`	—
`take(item, count = 1)`	—
`use_item(item)`	uses an item (potion…) like the inventory does
`equipped(slot)`	the item equipped as "weapon" or "armor" ("" if none)
`money_count()`	how much money the player has
`held()`	the item in the player's hand (the selected skillbar slot; "" if empty)
`select_slot(n)`	picks skillbar slot n (1–8), like pressing that key
`put_on_bar(item, n)`	puts an item the player has in skillbar slot n

#Switches, counters & quests

Function	What it does
`switch_on(name)`	true / false
`set_switch(name, on = true)`	—
`counter(name)`	number
`add(counter, amount = 1)`	—
`start_quest(id, goal text)`	—
`complete_quest(id)`	—
`quest_active(id)`	true / false
`quest_done(id)`	true / false
`objective()`	the current objective's text (this level's Goal, or the game's list)
`objective_done(text = "")`	finishes the current objective (only if its text matches, when given)

#Levels & worlds

Function	What it does
`level_complete(name = "")`	true once that level's Goal is done ("" = this level): level_complete("Cave")
`world_complete(name = "")`	true once that world (a group of levels) is complete ("" = this world): world_complete("Grass Land")
`completed_level()`	the name of the level whose goal was done last ("" = none yet); for the event "A level's goal is complete"
`completed_world()`	the name of the world completed last ("" = none yet); for the event "A world is complete"
`in_zone(name)`	true while the player is in that zone (Level view ▸ Zone tool): in_zone("Forest")
`win()`	the player wins
`lose()`	the player loses (the lose screen)
`lives_left()`	lives left (-1 = unlimited)
`best_score()`	the best score so far (Game Settings ▸ Lives & score)
`save_game()`	saves the game (the autosave slot; Continue loads it)
`checkpoint()`	the player comes back here after falling or being defeated

#Objects & finding things

Function	What it does
`object(name)`	the object with that Script name in this level
`objects(tag)`	every object whose model has that tag (a list)
`spawn(what, x, level, z, count = 1)`	a new copy of a prefab or model (by name); no position = next to this object. Gives the new object
`remove_self()`	removes the object this script is on
`nearest(tag, from = self)`	the closest object with that tag ("any" = any object), or nil
`objects_near(where, radius, tag = "any")`	the objects within radius tiles of a position or object, nearest first
`line_of_sight(a, b)`	true if nothing solid is between two objects or positions
`raycast(from, direction, distance = 20)`	what a line hits first: {object =, position =, tile =}, or nil
`tile_at(x, level, z)`	the model name of the ground tile there ("" if empty)
`set_tile(x, level, z, model)`	puts a ground tile there (by model name)
`clear_tile(x, level, z)`	removes the ground tile there
`path_to(from, to)`	a walkable path as a list of tile vectors (empty if there's no way)

#The player

Function	What it does
`hp()`	the player's health
`heal(hp)`	—
`hurt(hp)`	—
`launch(direction = "forward", speed = 12)`	pushes the player: "forward" (a dash), "up", "up_forward", "back", "left", "right"
`player_move(what, value, how = "set")`	walk_speed, run_speed, jump_height or gravity; how: "set", "add", "times", "reset"
`allow(move, on = true)`	lets the player jump, run, attack, climb or swim (false stops it)
`freeze(on = true)`	stops the player's controls (a cutscene); freeze(false) gives them back
`player_model(name)`	the player wears another model ("" = the usual one)
`player_state()`	what the player is doing: idle, walk, run, jump, fall, climb, swim

#Input

Function	What it does
`key_down(key)`	true while that key (or mouse button) is held: key_down("Q"), key_down("Space"), key_down("Mouse Right") (key_pressed: once per press)
`key_pressed(key)`	true once when that key goes down, then false until it's let go and pressed again: in a loop, if key_pressed("E") then … end runs once per press
`key_released(key)`	true once when that key is let go
`mouse_x()`	the mouse's x on the screen (pixels from the left)
`mouse_y()`	the mouse's y on the screen (pixels from the top)
`mouse_tile()`	the tile under the mouse as a vector (x, level, z), or nil over the sky
`pad_down(button)`	true while a gamepad button is held: "A", "B", "X", "Y", "LB", "RB", "Start", "Up"…
`pad_pressed(button)`	true once when a gamepad button goes down
`pad_axis(stick)`	-1…1: "left_x", "left_y", "right_x", "right_y", "lt", "rt"
`action_down(action)`	true while a control is held, whatever key the player set for it: "jump", "interact", "attack", "run", "forward", "back", "left", "right"
`action_pressed(action)`	true once when that control is pressed

#Sound & effects

Function	What it does
`play(sound, volume = 1)`	a sound (built-in name like "door", or your sound's name or id)
`play_at(sound, where, volume = 1)`	a sound at an object or position (quieter far away)
`stop_sound(sound = "")`	stops that sound, or every sound playing
`volume(kind, level)`	"music", "sound" or "all" at 0…1
`music(id)`	change the music ("" = the level's)
`music_fade(id, seconds = 2)`	fades into other music ("" = the level's)
`particles(effect, size = 1)`	plays a particle effect once here (built-in name like "explosion", or your effect's name)

#Chance

Function	What it does
`chance(percent)`	true that often
`rand(low, high)`	a whole number between them

#Data & debugging

Function	What it does
`data(name)`	a Data table (Data tab) as a table of rows: data("Enemies")["Goblin"].hp
`watch(name, value)`	shows a value live in the debug overlay (F3) and the editor's Watch list while playing

#Objects

#Object commands

Function	What it does
`obj.move(dx, dy, dz, seconds = 1, wait = true, ease = "smooth")`	glide by tiles (x, levels, z); ease: smooth, linear, in, out, bounce, elastic, back
`obj.move_to(x, y, z, seconds = 1, wait = true)`	glide to a tile (x, level, z)
`obj.go_home(seconds = 1, wait = true)`	glide back to where it was placed
`obj.turn(degrees, seconds = 0.5, wait = true)`	turn around (+ = left)
`obj.particles(effect, size = 1)`	plays a particle effect once on it
`obj.play(animation, keep = false)`	plays a part animation (attack, wave…) once, or keeps playing it
`obj.hide()`	invisible and walk-through
`obj.show()`	back again
`obj.show_hud()`	shows its Attached HUD (nameplate, health bar…)
`obj.hide_hud()`	hides its Attached HUD
`obj.remove()`	gone for the rest of the game
`obj.distance(other)`	tiles between them (other: an object or player)
`obj.touching(what)`	true if touching it: an object, player, or a tag like "enemy"
`obj.can_move(dx, dy, dz)`	true if that move wouldn't run into anything solid
`obj.attach(model, point = "Right hand")`	shows a model (by name) on an attachment point: player.attach("Sword"), self.attach("Party hat", "Head")
`obj.detach(point = "Right hand")`	takes off what's on that attachment point
`obj.teleport(x, y, z)`	jumps there at once (a vector works too): player.teleport(4, 0, 9)
`obj.look_at(target, seconds = 0.3, wait = true)`	turns to face an object, the player or a position
`obj.face(degrees, seconds = 0.3, wait = true)`	turns to a direction (0 = -Z, 90 = -X…)
`obj.tween(what, to, seconds = 1, ease = "smooth", wait = true)`	glides x, y, z, turn or scale to a value with easing: "linear", "smooth", "in", "out", "bounce", "elastic", "back"
`obj.set_scale(size, seconds = 0)`	grows or shrinks it (1 = normal)
`obj.tint(color, seconds = 0)`	colours it ("red", "#ff8800"; "" = its own colours)
`obj.follow(target, speed = 3, keep = 1.5)`	keeps walking after an object or the player (stop() ends it)
`obj.flee(target, speed = 3)`	keeps walking away from it
`obj.stop()`	stops follow / flee / a glide
`obj.hurt(amount)`	takes health from it (objects with Health; the player too)
`obj.heal(amount)`	gives health back
`obj.has_tag(tag)`	true if its model has that tag
`obj.say(text, seconds = 2.5)`	a speech bubble over it

#Object fields

Function	What it does
`obj.x`	tile X (fractions while moving)
`obj.y`	height level
`obj.z`	tile Z
`obj.name`	its Script name ("" if none)
`obj.exists`	false if it was removed or not found
`obj.position`	where it is, as a vector
`obj.hp`	its health (objects with Health, or the player); nil if it has none
`obj.max_hp`	its full health
`obj.model`	the name of its model
`obj.tags`	its model's tags (a list)
`obj.hidden`	true while hidden
`obj.turn`	which way it faces, in degrees

#Language functions

#Maths

Function	What it does
`abs(x)`	x without its sign
`min(a, b, …)`	the smallest
`max(a, b, …)`	the biggest
`round(x, step = 1)`	nearest whole number (or nearest step: round(x, 0.5))
`floor(x)`	down to a whole number
`ceil(x)`	up to a whole number
`clamp(x, low, high)`	x kept between low and high
`wrap(x, low, high)`	x wrapped around inside low…high (wrap(370, 0, 360) = 10)
`sign(x)`	-1, 0 or 1
`sqrt(x)`	square root
`pow(x, y)`	x to the power y (same as x ^ y)
`exp(x)`	—
`log(x)`	natural log
`lerp(a, b, t)`	part way from a to b (t = 0…1); works on vectors too
`smoothstep(low, high, x)`	0…1, easing in and out
`sin(degrees)`	—
`cos(degrees)`	—
`tan(degrees)`	—
`asin(x)`	degrees
`acos(x)`	degrees
`atan(x)`	degrees
`atan2(y, x)`	the angle in degrees to the point (x, y)
`int(x)`	whole number (drops the fraction); int("42") reads text
`float(x)`	a number with a fraction; float("2.5") reads text
`num(text)`	the number in a text (nil if there isn't one)

#Random

Function	What it does
`random(low = 0, high = 1)`	a random number between them (with a fraction)
`randf()`	a random number 0…1
`randi_range(low, high)`	a random whole number
`random_pick(list)`	one item at random (nil for an empty list)
`shuffle(list)`	mixes the list up (in place)
`seed(n)`	makes random numbers repeat the same way each run
`noise(x, y = 0, z = 0)`	smooth random -1…1 that changes gently with x, y, z (terrain, wobble)

#Vectors

Function	What it does
`vec(x, y, z)`	a vector (a position or a direction): v.x, v + w, v * 2
`pos(obj)`	an object's position as a vector
`length(v)`	how long a vector is
`normalize(v)`	the same direction, length 1
`distance(a, b)`	between two vectors, or two objects (tiles)
`dot(a, b)`	how much two directions agree
`cross(a, b)`	the direction at right angles to both
`angle_to(from, to)`	the turn in degrees from one position to face another (on the ground)

#Text

Function	What it does
`str(x)`	x as text
`len(x)`	length of a text, list or table (same as #x)
`upper(text)`	—
`lower(text)`	—
`sub(text, start, count = to the end)`	part of a text (start at 0)
`find(text, part)`	where part starts in text (-1 if it isn't there)
`contains(text or list, part)`	true if it's in there
`split(text, separator = " ")`	a list of the pieces
`replace(text, old, new)`	every old changed to new
`trim(text)`	without spaces at the ends
`starts_with(text, part)`	—
`ends_with(text, part)`	—
`format("{0} has {1} hp", name, hp)`	fills in the {n} slots
`join(list, separator = ", ")`	the items as one text
`rep(text, n)`	the text n times
`char(code)`	the letter with that code
`type(x)`	"number", "text", "bool", "nil", "list", "table", "vector", "function" or "object"

#Lists & tables

Function	What it does
`list(a, b, …)`	a list of the values
`push(list, value)`	adds to the end (also list:push(value))
`pop(list)`	takes the last item off and gives it
`insert(list, index, value)`	puts a value in at index
`remove(list, value)`	takes the first matching value out; remove(table, key)
`remove_at(list, index)`	takes the item at index out and gives it
`index_of(list, value)`	where it is (-1 if not there)
`sort(list, compare = nil)`	sorts the list in place (compare(a, b) → true if a goes first)
`reverse(list)`	turns the list around (in place)
`slice(list, from, to = end)`	a new list of items from … up to (not including) to
`copy(list or table)`	a separate copy (deep)
`keys(table)`	its keys as a list
`values(table)`	its values as a list
`has_key(table, key)`	true if the table has that key
`range(from, to, step = 1)`	a list of numbers from … up to and including to
`map(list, fn)`	a new list of fn(item) for each item
`filter(list, fn)`	a new list of the items where fn(item) is true
`sum(list)`	all the numbers added up

#Waiting

Function	What it does
`wait_until(fn, timeout = 0)`	waits until fn() is true (checks every frame); gives false if timeout seconds pass first

#Checks & debugging

Function	What it does
`assert(condition, message = "assert failed")`	stops the code with the message when condition is false
`error(message)`	stops the code with that message
`pcall(fn, …)`	runs fn and catches its error: gives [true, result] or [false, message]
`warn(message)`	a warning in the Output panel (the code goes on)
`breakpoint()`	pauses the game here and shows this code's values (F5 continue, F10 next line)

#Libraries

Function	What it does
`require("Utils")`	the functions of the script named Utils (a library), as a table