init
Copy _ _
| `. .' | _ _
| \_..._/ | | | | |
/ _ _ \ |\_/| __ _ | |_ ___ _ __ ___ __ _ | | __
`-| / \ / \ |-' / __| / _` || __|/ __|| '_ \ / _ \ / _` || |/ /
--| | | | | |-- | (__ | (_| || |_ \__ \| |_) || __/| (_| || <
.'\ \_/ _._ \_/ /`. \___| \__,_| \__||___/| .__/ \___| \__,_||_|\_\
`~..______ .~' _____| | 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.
This top-level module contains common metadata and utility functions used throughout the Catspeak codebase.
Example
Compile performant scripts from plain-text...
GameMaker Language (.gml)Copy// 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.compile(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:
GameMaker Language (.gml)Copyvar 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.compile(ir);
badMod();
} catch (e) {
show_message("a mod did something bad!");
}
§ catspeak_collecttop ^
GameMaker Language (.gml)Copyfunction catspeak_collect()At times, Catspeak creates a lot of garbage which tends to have a longer lifetime than is typically expected.
Calling this function forces Catspeak to collect that garbage.
§ CATSPEAK_DEBUG_MODEtop ^
GameMaker Language (.gml)Copy#macro CATSPEAK_DEBUG_MODE trueDetermines 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:
GameMaker Language (.gml)Copy#macro Release:CATSPEAK_DEBUG_MODE false
⚠️ WarningAlthough 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_inittop ^
GameMaker Language (.gml)Copyfunction catspeak_force_init()
-> BoolUsually 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.
📝 NoteYou 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_location_createtop ^
GameMaker Language (.gml)Copyfunction catspeak_location_create(
row : Real,
column : Real,
) -> RealWhen compiling programs, diagnostic information can be added into the generated IR. This information (such as the line and column numbers of an expression or statement) can be used by failing Catspeak programs to offer clearer error messages.
Encodes the line and column numbers of a source location into a 32-bit integer. The first 20 least-significant bits are reserved for the row number, with the remaining 12 bits used for the (less important) column number.
Because a lot of diagnostic information may be created for any given Catspeak program, it is important that this information has zero memory impact; hence, the line and column numbers are encoded into a 32-bit integer--which can be created and discarded without allocating memory--instead of as a struct.
Mask layout
Copy| 00000000000011111111111111111111 |
| <--column--><-------line-------> |
📝 NoteBecause of this, the maximum line number is 1,048,576 and the maximum column number is 4,096. Any line/column counts beyond this will raise an exception in debug mode, and just be garbage data in release mode.
Arguments
rowThe row number of the source location.
columnThe column number of the source location. This is the number of Unicode codepoints since the previous new-line character. As a result, tabs are considered a single column, not 2, 4, 8, etc. columns.
Returns Real
§ catspeak_location_get_columntop ^
GameMaker Language (.gml)Copyfunction catspeak_location_get_column(
location : Real,
) -> RealGets the column component of a Catspeak source location. This is stored as a 12-bit unsigned integer within the most significant bits of the supplied Catspeak location handle.
Arguments
locationA 32-bit integer representing the diagnostic information of a Catspeak program.
Returns Real
§ catspeak_location_get_rowtop ^
GameMaker Language (.gml)Copyfunction catspeak_location_get_row(
location : Real,
) -> RealGets the line component of a Catspeak source location. This is stored as a 20-bit unsigned integer within the least-significant bits of the supplied Catspeak location handle.
Arguments
locationA 32-bit integer representing the diagnostic information of a Catspeak program.
Returns Real
§ CATSPEAK_VERSIONtop ^
GameMaker Language (.gml)Copy#macro CATSPEAK_VERSION "3.2.0"The Catspeak runtime version, as a string, in the MAJOR.MINOR.PATCH format.
Updated before every new release.
Returns String