init

     _             _                                                       
    |  `.       .'  |                   _                             _    
    |    \_..._/    |                  | |                           | |   
   /    _       _    \     |\_/|  __ _ | |_  ___  _ __    ___   __ _ | | __
`-|    / \     / \    |-'  / __| / _` || __|/ __|| '_ \  / _ \ / _` || |/ /
--|    | |     | |    |-- | (__ | (_| || |_ \__ \| |_) ||  __/| (_| ||   < 
 .'\   \_/ _._ \_/   /`.   \___| \__,_| \__||___/| .__/  \___| \__,_||_|\_\
    `~..______    .~'                       _____| |   by: katsaii         
              `.  |                        / ._____/ logo: mashmerlow      
                `.|                        \_)

Catspeak is the spiritual successor to the long dead execute_string function from GameMaker 8.1, but on overdrive.

Use the built-in Catspeak scripting language to expose safe and sandboxed modding APIs within GameMaker projects, or bootstrap your own domain-specific languages and development tools using the back-end code generation tools offered by Catspeak.

Example

Compile performant scripts from plain-text...

// parse Catspeak code
var ir = Catspeak.parseString(@'
  let catspeak = "Catspeak"

  return "hello! from within " + catspeak
');

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

// call the Catspeak code just like you would any other GML function!
show_message(getMessage());

...without giving modders unrestricted access to your sensitive game code:

var ir = Catspeak.parseString(@'
  game_end(); -- heheheh, my mod will make your game close >:3
');

// calling `badMod` will throw an error instead
// of calling the `game_end` function
try {
  var badMod = Catspeak.compileGML(ir);
  badMod();
} catch (e) {
  show_message("a mod did something bad!");
}

§ CATSPEAK_DEBUG_MODE

#macro CATSPEAK_DEBUG_MODE true

Determines whether sanity checks and unsafe developer features are enabled at runtime.

Debug mode is enabled by default, but you can disable these checks by defining a configuration macro, and setting it to false:

#macro Release:CATSPEAK_DEBUG_MODE false

⚠️ Warning
Although disabling this macro may give a noticable performance boost, it will also result in undefined behaviour and cryptic error messages if an error occurs.
If you are getting errors in your game, and you suspect Catspeak may be the cause, make sure to re-enable debug mode if you have it disabled.

Returns Bool

§ catspeak_force_init

function catspeak_force_init()
  -> Bool

Usually the Catspeak environment tries to self-initialise at the start of the game, but at what time this happens relative to other scripts is not guaranteed by GameMaker.

Call this function to force the core Catspeak environment to be initialised immediately. If Catspeak was already initialised before calling this function, then nothing will happen.

📝 Note
You shouldn't need to call this function unless you are trying to use Catspeak from within a global script asset, or through gml_pragma("global", ...).
If neither of these situations apply to you, feel free to forget this function even exists.

Returns Bool

Returns true the first time this function is called, and false every other time.

§ CATSPEAK_VERSION

#macro CATSPEAK_VERSION "3.0.0"

The Catspeak runtime version, as a string, in the MAJOR.MINOR.PATCH format.

Updated before every new release.

Returns String