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
main();

// grab the counter function from the script
var counter = main.getGlobals().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_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