Cookbook
Each recipe starts from something you want to do ("run code when an instance is destroyed"), names the API that does it and why, quotes a snippet from a mod that ships in this repository with a link to the exact lines, and lists the mistakes that cost time. Where both the typed form (from the generated interop) and the untyped form work, both are shown. The recipes assume you have read the concepts: the game thread, value lifetime, ownership and fault isolation explain why many of the gotchas exist. If you have not built a mod yet, start with the first mod.
Hooks
Run your code before or after a game script or object event. See Hooks.
| I want to... | Recipe |
|---|---|
| change a script's argument before it runs | Change a script's argument |
| run the original script again (more loot, repeated effect) | Run the original script again |
| cancel a script and return my own value | Cancel a script and return your own value |
| change what a script returned | Change what a script returned |
| run code when an instance is destroyed | Instance destroyed |
| run code when an instance is created | Instance created |
| run code every step of an object | Every step |
| hook a user event | Hook a user event |
look up the name of an event (Create_0, Step_1, Draw_64, Other_10) | Event names |
| hook a function I only know the name of at runtime, and unhook it | Hook by name |
| run something once inside the next matching call, with a timeout | Run once in the next call |
| choose between the attribute, the typed ref and a string | Attribute, typed or string |
Game state
Read and change what the game keeps. See Game state.
| I want to... | Recipe |
|---|---|
| read or write a global variable | Globals |
| find a singleton instance and edit its variables | Singleton instance |
| loop over every instance of an object, children included | Iterate instances |
| create or destroy an instance | Spawn and destroy |
| read a ds_map | Read a ds_map |
| edit a ds_list that lives inside a ds_map | Edit a ds_list |
| read arrays and structs | Arrays and structs |
| walk the object table and its parent and child objects | Object table |
| scale a value without compounding it | Scale without compounding |
Calling the game
Make the game do something. See Calling the game.
| I want to... | Recipe |
|---|---|
| call a script, typed or by name | Call a script |
| call a builtin | Call a builtin |
| run an object event directly | Run an object event |
| look up an asset by name and play a sound | Assets and sounds |
| run code inside the game's own event | Inside the game's event |
Drawing and UI
Put pixels on screen, in the game or in the overlay. See Drawing and UI.
| I want to... | Recipe |
|---|---|
| add a sprite and a sound and draw in the game's GUI layer | Sprite and sound |
| reskin one of the game's sprites | Reskin a sprite |
draw text and shapes with draw_* | Draw builtins |
| draw a game sprite at a position | draw_sprite_ext |
| draw with the game's own UI scripts | Game UI scripts |
| build an overlay tab with ImGui | Overlay tab |
| keep a tab alive when it reads live data | UI.Guarded |
| give widgets stable ids | Stable ids |
| open and close UI scopes correctly | Scopes |
Input
Keys, the mouse and clicks. See Input.
| I want to... | Recipe |
|---|---|
| detect a key press | Key press |
| read the mouse in GUI coordinates | Mouse |
| take a click the game never sees | Take a click |
| keep keys from reaching the game while my window is open | Swallow the keyboard |
| understand what the overlay does to my input | The overlay and your input |
Settings and persistence
Keep things between runs. See Settings and persistence.
| I want to... | Recipe |
|---|---|
| save a setting | Config |
| offer settings in the game's own menu | ModSettings |
| read a file from my mod's folder | Mod folder |
| keep per-character data inside the save | Data in the save |
| survive a hot reload | Hot reload |
| clean up when the mod unloads | OnShutdown |
Robustness and testing
Fail soft, stay fast, and test without a mouse. See Robustness and testing.
| I want to... | Recipe |
|---|---|
| handle a game that is not ready (the title screen) | Catch GmlException |
| keep one bad callback from disabling my mod | Guard |
| keep per-frame work cheap | Throttle OnUpdate |
| do slow work in the background and come back to the game | Background work |
| see what a compiled script calls, and who calls it | Inspect compiled code |
| expose commands to the test host | Test host |
| write a regression mod for a risky area | Regression mods |
Looking for the whole API instead? See the API reference. Looking for which script to hook in a game you do not know? See Finding hooks.