environment

The primary user-facing API for compiling Catspeak programs and configuring the Catspeak runtime environment.

Example

A high-level overview of Catspeak usage. The example walks through how to compile, execute, and introspect the global variables of a Catspeak script:

// parse Catspeak code
var ir = Catspeak.parseString(@'
  count = 0
  counter = fun {
    count += 1
    return count
  }
');

// compile Catspeak code into a callable GML function
var main = Catspeak.compileGML(ir);

// initialise the Catspeak script by calling its main entry point
catspeak_execute(main);

// grab the counter function from the script
var counter = catspeak_globals(main).counter;

// call the Catspeak `counter` function from GML!
show_message(counter()); // prints 1
show_message(counter()); // prints 2
show_message(counter()); // prints 3
show_message(counter()); // prints 4

§ Catspeak

#macro Catspeak global.__catspeak__

The default global Catspeak environment. Mostly exists for UX reasons.

Unless you need to have multiple instances of Catspeak with different configurations, you should use this. Otherwise, you should create a new sandboxed Catspeak environment using new CatspeakEnvironment().

Returns Struct.CatspeakEnvironment

§ catspeak_execute

function catspeak_execute(
  callee : Any,
  ... : Any,
) -> Any

Simple wrapper over catspeak_execute_ext which infers the self and other context from the current callsite.

📝 Note
Gets around a limitation in GML where the self and other of the callsite cannot be accessed from within bound methods. Use this function if you want the self of a called Catspeak function to be the same as the self of the callsite in GML land.

Arguments

callee
The function to call. Can be a GML function, Catspeak function, or a function bound using catspeak_method.
...
The arguments to pass to this function.

Returns Any

The result of evaluating the callee function.

§ catspeak_execute_ext

function catspeak_execute_ext(
  callee : Any,
  self_ : Struct,
  args? : Array<Any>,
  offset? : Real,
  argc? : Real,
) -> Any

Executes a Catspeak-compatible function in the supplied self scope.

📝 Note
Gets around a limitation in GML where the self and other of the callsite cannot be accessed from within bound methods. Use this function if you want the self of a called Catspeak function to be the same as the self of the callsite in GML land.

Arguments

callee
The function to call. Can be a GML function, Catspeak function, or a function bound using catspeak_method.
self_
The self context to use when calling this Catspeak function.
args (optional)
The argument list to call this function with. Defaults to no arguments.
offset (optional)
The offset in the args array to begin reading arguments from. Defaults to 0.
argc (optional)
The number of arguments to pass to the function call. Defaults to array_length(args) - offset.

Returns Any

The result of evaluating the callee function.

§ catspeak_globals

function catspeak_globals(
  callee : Any,
) -> Struct

Returns a struct containing the global variable context of a Catspeak function, or undefined if no globals exist.

Arguments

callee
The function to get the global context of. Can be a GML function, Catspeak function, or a function bound using catspeak_method.

Returns Struct

§ catspeak_method

function catspeak_method(
  self_ : Any,
  callee : Any,
) -> Any

Binds a function to a self. Similar to the built-in method function, except this supports Catspeak functions as well as GML functions.

📝 Note
Prefered over using method otherwise you risk breaking your compiled Catspeak functions.

Arguments

self_
The scope to bind this function to. Can be a struct or undefined.
callee
The function to get the global context of. Can be a GML function, Catspeak function, or a function bound using catspeak_method.

Returns Any

§ catspeak_special_to_struct

function catspeak_special_to_struct(
  gmlSpecial : Any,
) -> Struct

Because Catspeak is sandboxed, care must be taken to not expose any unintentional exploits to modders with GML-specific knowledge. One exampe of an exploit is using the number -5 to access all the internal global variables of a game:

var globalBypass = -5;
show_message(globalBypass.secret);

Catspeak avoids these exploits by requiring that all special values be converted to their struct counterpart; that is, Catspeak does not coerce numbers to these special types implicitly.

Use this function to convert special GML constants, such as self, global, or instances into their struct counterparts. Will return undefined if there does not exist a valid conversion.

Arguments

gmlSpecial
Any special GML value to convert into a Catspeak-compatible struct. E.g. global or an instance ID.

Returns Struct