Built-in Functions

All of the GDLisp global functions are documented here. These functions are available (in the function namespace) at the top-level of every GDLisp file.

Note that most of the GDScript built-in functions are available unmodified in GDLisp as well. All names in GDScript which contain an underscore have their underscores replaced with dashes in GDLisp, so get_stack translates to get-stack in GDLisp for instance. The exceptions to this are:

• assert, preload, and yield are not functions and are instead special forms in GDLisp. See assert Forms, preload Forms, and yield Forms, respectively.

• typeof in GDLisp behaves differently. It is documented at typeof.

• convert has been wrapped to support GDLisp synthetic types. See convert.

• len has been wrapped in GDLisp to support GDLisp lists in addition to strings, arrays, and dictionaries. See len.

• bool has been extended to support all types. See bool.

*

(defn * (&rest args)
  ...)

Multiplies all of the arguments (which must be numerical or vectors) together. If given no arguments, returns the integer 1.

+

(defn + (&rest args)
  ...)

Adds all of the arguments (which must be numerical or vectors) together. If given no arguments, returns the integer 0.

To concatenate strings in GDLisp, use the built-in Godot function str, which accepts multiple strings and concatenates them together.

-

(defn - (x &rest args)
  ...)

Subtracts all of the arguments from the first in order. If given only one argument, returns its negation. That is, (- x) is equivalent to (- 0 x).

/

(defn / (x &rest args)
  ...)

Divides all of the arguments out of the first in order. If given only one argument, returns its reciprocal. That is, (/ x) is equivalent to (/ 0 x).

/=

(defn /= (x &rest args)
  ...)

Returns true if none of the arguments are equal to each other. Note that since /= is non-transitive, this is different than just checking whether adjacent arguments are equal. That is, (/= 1 2 1) is false even though no adjacent elements are equal.

<

(defn < (x &rest args)
  ...)

Returns true if each argument (in order) is less than the following element, according to their natural ordering.

<=

(defn <= (x &rest args)
  ...)

Returns true if each argument (in order) is less than or equal to the following element, according to their natural ordering.

=

(defn = (x &rest args)
  ...)

Checks whether each argument is equal to the argument following it.

>

(defn > (x &rest args)
  ...)

Returns true if each argument (in order) is greater than the following element, according to their natural ordering.

>=

(defn >= (x &rest args)
  ...)

Returns true if each argument (in order) is greater than or equal to the following element, according to their natural ordering.

append

(defn append (&rest args)
  ...)

Appends all of the lists together, returning a list which contains all of the elements of each argument, in the same order they appeared.

The resulting list will share structure with the final argument to append. That is, the cons cells leading up to the final argument to append will not be rebuilt. Additionally, the final argument to append can be an improper list, while all of the other arguments must be proper lists.

apply

(defn apply (f &rest args)
  ...)

Calls the function object f with the given arguments, returning the result of the function call. At least one argument must be supplied, and the final argument is treated as a list of arguments, not an individual one.

For a version of apply without the “variable argument” behavior, see funcall.

The difference between this function and funcall is that the former treats its final argument as a list and prepends the others onto it. Concretely, all of the following will sum the numbers from one to four, returning ten:

(+ 1 2 3 4)
(funcall #'+ 1 2 3 4)
(apply #'+ 1 2 3 4 ())
(apply #'+ '(1 2 3 4))
(apply #'+ 1 2 '(3 4))

array

(defn array (&rest xs)
  ...)

Constructs a array of the arguments given. The [ ... ] syntax desugars to a call to this function.

array->list

(defn array->list (arr)
  ...)

Converts a Godot array or pooled array into a proper list.

array/concat

(defn array/concat (&rest arrays)
  ...)

Concatenates all of the arrays in order, producing a new array. The existing arrays are not modified. If given an empty argument list, returns an empty array.

array/filter

(defn array/filter (p xs)
  ...)

Applies the unary predicate p to each element of the array xs and returns a filter of all elements for which the predicate returned truthy. Does not modify xs.

array/find

(defn array/find (p arr &opt default)
  ...)

Applies the unary predicate p to each element of the array arr. Returns the first element of the array for which the predicate returned true. If no element returns true, then default is returned. This function will short-circuit and stop calling p as soon as a match is found.

array/fold

(defn array/fold (f xs &opt x)
  ...)

A left-fold over an array. f shall be a function of two arguments, xs shall be a Godot array, and x (if supplied) shall be a non-null starting value.

The array is traversed from the beginning to the end. At each element, the call (funcall f acc element) is made, where acc is the value we’ve accumulated so far and element is the current element. The return value of that function call is used as the new value of acc. At the end, acc is returned.

The initial value of acc is x if supplied. If x is not supplied, then the initial value is the first element of the array, and iteration begins at the second. If x is not supplied and the array is empty, then an error is produced.

array/map

(defn array/map (f xs)
  ...)

Applies the unary function f to each element of the array xs and returns a new array of the returned values. Does not modify xs.

array/reverse

(defn array/reverse (arg)
  ...)

Returns a new array containing all of the same elements as the input array arg but in reverse order. Does not mutate arg.

bool

(defn bool (x)
  ...)

Normalizes the argument to Boolean. Returns #t if x is truthy, or #f otherwise.

cons

(defn cons (a b)
  ...)

Constructs a fresh cons cell, with the first argument as car and the second as cdr.

connect>>

(defn connect>> (obj signal-name function)
  ...)

Connects the signal on obj whose name is the string signal-name to the given function. This function is similar to the built-in method connect on Godot objects, but the former is designed to work on GDLisp first-class functions, such as those constructed with lambda Forms or function Forms.

This function returns a unique identifier which can be passed to disconnect>> to disconnect the signal.

Warning

Due to current limitations in the implementation, signals connected in this way can only accept up to six arguments. If you need more than six arguments, use the built-in Godot method Object.connect instead.

connect1>>

(defn connect1>> (obj signal-name function)
   ...)

Connects the signal on obj whose name is the string signal-name to the given function. The connection will be dropped as soon as it’s been called once.

Returns an identifier that can be passed to disconnect>> to disconnect the signal.

Warning

Like connect>>, functions connected with this function can only accept up to six arguments.

convert

(defn convert (what type)
  ...)

Converts the value what into the type type, according to the Godot rules for the GDScript function of the same name. type can be a primitive type object (such as Int) or a type enumeration constant (such as Type:INT).

dict

(defn dict (&rest xs)
  ...)

Constructs a dictionary, where each even-indexed argument is a key paired with the value immediately after it. of the arguments given. The { ... } syntax desugars to a call to this function. The behavior is undefined if this function is called with an odd number of arguments.

dict/elt

(defn dict/elt (dict k)
  ...)

Gets the value corresponding to key k of the dictionary dict.

dict/find

(defn dict/find (p dict &opt default)
  ...)

Iterates over the dictionary dict in element insertion order. For each key-value pair of the dictionary, the predicate p is called with two arguments: the key and the value. Returns the first key for which the predicate returned true, or default if no match is found. This function will short-circuit and stop calling p as soon as a match is found.

disconnect>>

(defn disconnect>> (obj signal-name index)
  ...)

Disconnects a signal that was connected using connect>> or connect1>>. The index shall be the return value of the function that was used to make the connection.

Note that signals connected with Godot’s built-in connect method should be disconnected, correspondingly, with the Object.disconnect method. This function is only designed to disconnect signals made using the GDLisp functions connect>> and connect1>>.

equal?

(defn equal? (x &rest args)

Returns whether each value is equal to the one after it, following data structures recursively. This function is similar to the built-in Godot function deep_equal, but equal? works on more data types. Specifically, equal? will recursively follow arrays (of any type), dictionaries, and GDLisp lists.

elt

(defn elt (x y)
  ...)

Gets the element from the data structure. (elt x y) is guaranteed to compile to the Godot x[y], hence can be used on arrays, dictionaries, and any other data structure that the subscript operator is compatible with.

funcall

(defn funcall (f &rest args)
  ...)

Calls the function object f with the given arguments, returning the result of the function call. Note that, since function objects do not know their own function signature at compile-time, the number of arguments cannot be validated at compile time when using funcall. An error will be issued at runtime, if the argument count does not match up.

Example:

(let ((my-function (lambda (x y) (+ x y))))
  (funcall my-function 10 15)) ; Returns 25

For a version of funcall that takes a list of arguments rather than individual arguments, see apply.

gcd

(defn gcd (&rest args)
  ...)

Returns the greatest common divisor of the arguments, or 0 if no arguments are given.

gensym

(defn gensym (&opt prefix)
  ...)

Returns a new symbol object whose name has not appeared in the GDLisp source code that the compiler has encountered up to this point and that has not been interned dynamically with intern.

If prefix is provided, then it must be a string and the returned symbol will have a name that begins with prefix. If not, then a default prefix will be chosen for you.

init

(defn init (a)
  ...)

Returns a new list which consists of all of the elements of the original list a except the final one. a can be a proper or improper list, and in either case the terminator is ignored (it is not considered the final element, even if it is nontrivial), and the resulting list shall be proper.

a must be nonempty.

instance?

(defn instance? (value type)
  ...)

Given a value and a type object, returns whether or not that value is an instance of that type. The type object can be any of the following.

• A GDScript or GDLisp class.

• The name of a built-in Godot object type, such as Node or Spatial.

• A Godot primitive type, such as Int.

• A GDLisp abstract type, such as BaseArray or AnyVal.

intern

(defn intern (s)
  ...)

Returns a symbol object whose name is s. If the given symbol already exists in the global symbol table, then the same object (up to = comparison) is returned. Otherwise, a new symbol object is created and returned.

last

(defn last (a)
  ...)

Returns the final element of a, which must be a nonempty list (proper or improper). The terminator of an improper list is ignored (it is not considered the final element, even if it is nontrivial).

lcm

(defn lcm (&rest args)
  ...)

Returns the least common multiple of the arguments, or 1 if no arguments are given.

len

(defn len (x)
  ...)

Returns the length of the list, array, dictionary, or string object.

list

(defn list (&rest args)
  ...)

Returns a proper list containing all of the arguments, in the same order.

list->array

(defn list->array (list)
  ...)

Converts a proper list into a Godot array.

list/elt

(defn list/elt (list n)
  ...)

Given a list and an index, returns the element of the list at that 0-indexed position. Produces an error if the index is out of bounds.

list/copy

(defn list/copy (list)
  ...)

Returns a new list containing the same elements as list in the same order. The two lists will not share any structure.

list/filter

(defn list/filter (p xs)
  ...)

Applies the unary predicate p to each element of xs and returns a list of all elements for which the predicate returned truthy. The returned list shares no structure with the argument list.

list/find

(defn list/find (p xs &opt default)
  ...)

Applies the unary predicate p to each element of the proper list xs. Returns the first element of the list for which the predicate returned true. If no element returns true, then default is returned. This function will short-circuit and stop calling p as soon as a match is found.

list/fold

(defn list/fold (f xs &opt x)
  ...)

A left-fold over a list. f shall be a function of two arguments, xs shall be a proper list, and x (if supplied) shall be a non-null starting value.

The list is traversed from the beginning to the end. At each list element, the call (funcall f acc element) is made, where acc is the value we’ve accumulated so far and element is the current element. The return value of that function call is used as the new value of acc. At the end, acc is returned.

The initial value of acc is x if supplied. If x is not supplied, then the initial value is the first element of the list, and iteration begins at the second. If x is not supplied and the list is empty, then an error is produced.

list/map

(defn list/map (f xs)
  ...)

Applies the unary function f to each element of the list xs and returns a new list of the result values.

list/reverse

(defn list/reverse (arg)
  ...)

Returns a list containing all of the same elements as arg but in reverse order. Does not mutate arg.

list/tail

(defn list/tail (list k)
  ...)

Returns the kth cdr of list. That is, returns a tail of the list with the first k elements removed. The resulting list shares structure with list.

max

(defn max (&rest args)
  ...)

Returns the maximum of all of the arguments given, or - INF if given no arguments.

member

(defn member? (value structure)
  ...)

Returns whether or not the value is a member of the structure. This is guaranteed to compile to the Godot in infix operator and has the same semantics.

min

(defn min (&rest args)
  ...)

Returns the minimum of all of the arguments given, or INF if given no arguments.

mod

(defn mod (x y)
  ...)

Returns the (integer) modulo of x by y. As in Godot, to take a floating-point modulo, use the built-in GDScript function fmod.

NodePath

(defn NodePath (string)
  ...)

Constructs a NodePath object containing the given string.

not

(defn not (x)
  ...)

Returns a proper Boolean (i.e. either #t or #f) of the opposite truthiness to x. So if x is truthy then this function returns #f, and if x is falsy then this function returns #t.

set-dict/elt

(defn set-dict/elt (x dict k)
  ...)

Sets the value corresponding to key k of the dictionary dict to x. If the key does not exist in the dictionary, then it is inserted.

set-elt

(defn set-elt (x y z)
  ...)

Sets the element from the data structure. (set-elt x y z) is guaranteed to compile to the Godot y[z] = x, hence can be used on arrays, dictionaries, and any other data structure that the subscript operator is compatible with.

snoc

(defn snoc (a b)
  ...)

Appends an element b to the end of a proper list a. The list a is not modified, and the returned list is a newly-constructed one.

typeof

(defn typeof (value)
  ...)

Given a value, return a type object representing its type. Note that this is not the same as the GDScript typeof function, which returns an integer constant. The object returned by the GDLisp typeof function is an object representing the value’s most specific type, which can be passed to instance? for instance checks.

• In the case of a primitive value (i.e. an instance of a subtype of AnyVal), a special type object is returned. This type object can only be passed to instance? and does not have any public fields or methods.

• In the case of an object whose type is defined in GDLisp or GDScript, the script resource or inner class resource is returned.

• In the case of a direct instance of a Godot native type like Node, the relevant native type object is returned.

vector

(defn vector (x y &opt z)
  ...)

Constructs a vector of two or three dimensions with the given arguments. The V{ ... } syntax desugars to calls to this function.

vector/map

(defn vector/map (f arg &rest args)
  ...)

Applies a function to each component of the 2D or 3D vectors. In its simplest form (with two arguments), vector/map produces a new vector of the same dimension as the input, where f has been applied to the X and Y (and Z, if 3D) coordinates of the input vector.

If given more than two arguments, the arguments must all be of the dimension. f will be applied to the X components of all input vectors at once, then to the Y components, then to the Z components (if needed), producing a single new vector.

Example:

(vector/map #'+ V{1 2} V{100 200}) ; Returns V{101 202}