Scriptor Broker File Format - coldrockgames/doc-scriptor GitHub Wiki

For professional game projects with numerous scripts and events, managing configurations directly in the game source code can become tedious and error-prone. The ScriptorBroker simplifies this process by allowing you to bulk-load definitions through a single JSON configuration file.

Example Configuration File

Here’s an example of how the configuration for the object model in The Scriptor Broker could look like as a json file:

{
    "Monster": {
        "on_combat_start": [
            { "filter_field": null, "filter_value": null, "is_override": false, "script_file"  : "monster_combat_start" },
        ],
        "on_combat_end": [
            { "filter_field": null, "filter_value": null, "is_override": false, "script_file"  : "monster_combat_end"   },
        ],
        "on_attack": [
            { "filter_field": null, "filter_value": null, "is_override": false, "script_file"  : "monster_attack"       },
        ],
        "on_hit": [
            { "filter_field": null,   "filter_value": null,     "is_override": false, "script_file"  : "monster_hit"          },
            { "filter_field": "race", "filter_value": "human*", "is_override": false, "script_file"  : "monster_sound_scream" },
            { "filter_field": "race", "filter_value": "orc*"  , "is_override": false, "script_file"  : "monster_sound_grunt"  },
            { "filter_field": "race", "filter_value": "beast*", "is_override": false, "script_file"  : "monster_sound_squeek" },
        ],
        "on_die": [
            { "filter_field": null,   "filter_value": null,     "is_override": false, "script_file"  : "monster_die"          },
            { "filter_field": "race", "filter_value": "human*", "is_override": false, "script_file"  : "monster_red_blood"    },
            { "filter_field": "race", "filter_value": "orc*"  , "is_override": false, "script_file"  : "monster_green_blood"  },
            { "filter_field": "race", "filter_value": "beast*", "is_override": false, "script_file"  : "monster_red_blood"    },
        ],
    },
    "Lich": {
        "on_life_leech": [
            { "filter_field": null, "filter_value": null, "is_override": false, "script_file"  : "lich_life_leech" },
        ],
        "on_hit": [
            { "filter_field": null, "filter_value": null, "is_override": true , "script_file"  : "lich_hit"        },
        ],
    },
    "Boss": {
        "on_combat_start": [
            { "filter_field": null, "filter_value": null, "is_override": false, "script_file"  : "boss_combat_start" },
        ],
        "on_combat_end": [
            { "filter_field": null, "filter_value": null, "is_override": false, "script_file"  : "boss_combat_end"   },
        ],
        "on_hit": [
            { "filter_field": null, "filter_value": null, "is_override": true , "script_file"  : "boss_hit"          },
        ],
    },
    "UndeadLord": {
        "on_combat_start": [
            { "filter_field": null, "filter_value": null, "is_override": true , "script_file"  : "undead_lord_combat_start" },
        ],
        "on_hit": [
            { "filter_field": null, "filter_value": null, "is_override": true , "script_file"  : "undead_lord_hit"          },
        ],
    },
}

File Structure Explained

1. Root-Level Objects: The root keys (Monster, Lich, Boss, UndeadLord) correspond to the type names of your in-game objects. The ScriptorBroker compares these names with the broadcast sender's type.
2. Events: Each object contains a list of events (e.g., on_combat_start, on_hit) that match the broadcast titles. The broker triggers scripts based on these event names.
3. Event Definitions: Each event includes the components of a Broker Event:

• filter_field: The field name to filter. Optional, may also be omitted or set to null.
• filter_value: A (wildcard-)string of the value, the filter_field must match.
• is_override: A boolean value that determines if the event overrides inherited events.
• script_file: The name of the script file to execute.

In the example above you can see, how such filters can even be used to create sound- and blood-effects based on the type of monster in combat (look at "Monster" -> "on_hit"/"on_die"). This way, you can freely adapt and patch your combat animations without entering game source code.

Where to Place Script Files?

Similar to other raptor modules, the scriptor language has its' own configuration file, which can be found in the __GAME_SETUP__ section of the raptor project template.

The Scriptor_Configuration File

Scriptor only needs a few configuration keys to work.

The default configuration file looks like this:

/*
    Configuration values for the Scriptor language
*/

// The file extension for scriptor scripts
#macro         SCRIPTOR_EXTENSION		".scriptor"
#macro release:SCRIPTOR_EXTENSION		".scx"

// A sub folder in your working_directory (included files)
// where all scriptor files are stored.
// Set it to "" if you store your scriptor files in included 
// files root.
#macro	SCRIPTOR_ROOT_FOLDER			"scripts/"

In most cases, you won’t need to adjust these settings as they are straightforward and self-explanatory.

The default folder for your script files is scripts, located at the root level of your included files in GameMaker. You may change this value to anything you want, but make sure, the string ends with a / to maintain compatibility.

If you prefer to store your scripts directly in the root folder of your included files (something that I do NOT recommend!), you can set the value to an empty string "".

Additionally, note that the file extension changes in the release configuration. With raptor-pro, you also acquired a license to the raptor-json-compiler, which encrypts your script files’ source code in the release build. This ensures your scripts are secure and cannot be tampered with once your game is published.