Back to the town ↗

Reborn script modding

Add settings panels, recipes, and other features with GDScript.

Reborn 0.3.0 early alphaModAPI 2.0.0Updated 18 November 2026

Before you begin

Use GDScript to add features such as crafting recipes, camera controls, and settings panels. Reborn's scripting API is called API2. For item data, textures, or model replacements, start with FATE DAT modding.

Script mods can access your files and operating system. Only install scripts from authors you trust.

Choose the right kind of mod#

A DAT/asset mod changes game data and artwork. A script mod adds behavior through the functions Reborn exposes. You can include both in one package.

Work through the API rather than editing the game's internal objects. The API provides readable snapshots, notifications, and specific actions such as crafting transactions. A snapshot is a copy of data: editing it won't change the game.

Which version goes where?#

FieldValueWhat it controls
game>=0.3.0 <0.4.0Compatible Reborn versions in these examples
schema1The mod.json file format
api>=2.0.0 <3.0.0Compatible ModAPI versions
script.api2The script entry format
versionYour mod's versionYour own releases, such as 1.0.0

Settings and saved mod data also have their own schema versions. Keep them separate from the game and package versions. Don't change native save-version stamps.

Make a working API2 panel#

This example adds a Mod status panel under Extensions on the main menu. Its Enable mod setting is under Mods > Configure. Applying that setting updates the panel without restarting. It doesn't change gameplay or need a loaded character.

Use a plain-text editor and save the files as UTF-8. You don't need the Godot editor. Make sure the filenames end in .json or .gd, rather than .txt. Create this folder structure, including the empty Data folder:

text
HelloReborn/
  mod.json
  main.gd
  settings.json
  Data/

Save this as mod.json:

json
{
  "schema": 1,
  "id": "example.hello_reborn",
  "name": "Hello Reborn",
  "author": "Your name",
  "version": "1.0.0",
  "kind": "reborn",
  "api": ">=2.0.0 <3.0.0",
  "game": ">=0.3.0 <0.4.0",
  "content": "Data",
  "script": {"api": 2, "entry": "main.gd"},
  "settings": "settings.json",
  "description": "A small API2 settings and status panel."
}

Save this as settings.json:

json
{
  "schema": 2,
  "fields": [
    {"id":"enabled", "label":"Enable mod",
     "type":"toggle", "scope":"personal",
     "apply":"live", "default":true}
  ]
}

Save this as main.gd:

gdscript
extends RefCounted

var api
var settings: Dictionary = {}

func initialize(value) -> bool:
    api = value
    for operation in ["configuration.read", "configuration.observe",
                      "ui.panel", "ui.publish"]:
        if operation not in api.capabilities().operations:
            return false
    settings = api.configuration()
    var panel = {
        "title": "Mod status",
        "rows": [
            {"id":"status", "kind":"text", "value":_status()},
            {"id":"refresh", "kind":"button",
             "label":"Refresh", "value":null}
        ]
    }
    if not api.register_ui_panel("status", panel, _action):
        return false
    return api.on_configuration_changed(_configuration_changed)

func _status() -> String:
    return "Enabled" if settings.get("enabled", true) else "Disabled"

func _configuration_changed(event: Dictionary) -> void:
    settings = event.values.duplicate(true)
    api.publish_ui("status", {"status":_status()})

func _action(_request: Dictionary) -> void:
    api.publish_ui("status", {"status":_status()})

func dispose() -> void:
    settings.clear()
    api = null
  1. Install HelloReborn using the installation steps below. Enable it, choose Apply changes, then Restart now.
  2. Back in Mods, select Hello Reborn and choose Configure.
  3. Turn Enable mod off, then click Apply. Wait for Settings applied, then return to the main menu.
  4. Open Extensions and choose Mod status. The panel should say Disabled. Its Refresh button reads the current setting again.
  5. Return to Mods > Configure, turn Enable mod on, and Apply. Reopen the panel to check that it says Enabled.

This switch changes the displayed status; it doesn't unload the script. The example was checked in the released 0.3.0 build without a loaded character.

Lifecycle rules#

Your entry script extends RefCounted and implements initialize(api). Register your policies, providers, panels, and observers there. Return true once all required registrations succeed; registrations made later are rejected.

Check that the API supports the functions you need, and check their return values. Keep callbacks short and don't yield from them. Use notifications to update cached data rather than copying catalogs or inventories every frame.

Use dispose() to release your own stored values. API access is already revoked at that point, so cleanup can't depend on API calls.

A lease identifies the current data context, such as the loaded character. It isn't a permanent character or save ID. Clear cached views when their context closes or becomes unavailable, then request fresh data when it's ready again. Use current leases, revisions, and transaction quotes when submitting changes.

Script scope is separate from asset targeting#

Scripts run across eligible cores by default. To restrict a script to Undiscovered Realms, use:

json
"script": {
  "api": 2,
  "entry": "main.gd",
  "scope": {"cores": ["undiscovered_realms"]}
}

Add scope.locations to restrict it to supported location IDs. If both cores and locations are listed, both must match. Use targets for DAT files and assets, and script.scope for script behavior. UR must still be installed and enabled. Scope doesn't give a script control over multiplayer sessions.

Declare identity dependencies and settings#

Keep id stable across updates and increase version for each release. Use a distinctive author prefix in your ID. IDs accept lowercase letters, digits, dots, underscores, and hyphens; versions use X.Y.Z.

Set game and api to the versions you've tested. For dependencies and load order, see the manifest fields in the DAT guide.

Settings schema 1 applies changes after a restart. Schema 2 supports layouts and live settings, as in the panel example. A setting marked restart-only still needs a restart. Live settings don't reload a script or its content.

Use personal settings for preferences such as presentation. Use shared settings for gameplay rules, since they affect compatibility between players. Give numeric settings valid ranges and defaults, and give choice fields matching options. Changing a settings schema or default also changes the package's identity for compatibility checks.

Read settings with configuration() and subscribe with on_configuration_changed(callback). Older get_config, on_config_changed, and register_live_config examples don't apply to API2. Adding a setting alone doesn't implement the action it describes.

Find a supported script operation#

Check api.capabilities().operations for available features, then call the corresponding API method. Operation identifiers aren't commands you can pass to a generic dispatcher.

The methods below are present in 0.3.0. This is an overview, not a complete recipe for each feature. The working panel above is the starting example; test other features separately with your own mod.

AreaMain methodsUse
Configurationconfiguration, on_configuration_changedRead settings and follow changes
Diagnosticslog, diagnosticsReport problems in your mod
Definitionsfind_definitions, definition_snapshotRead loaded game definitions
Player and inventoryplayer_snapshot, inventory_snapshot, on_player_changed, on_inventory_changedRead player progress and inventory changes
Questsquests_snapshot, on_quests_changedRead the journal and observe turn-ins
Mergingregister_merge_policy, merge_providers, register_pickup_merge_policyHandle compatible book/charm charges and pickup merging
Equipment and tooltipsequipment_snapshot, register_equipment_modifier_policy, register_item_tooltip_policyAdd supported bonuses and tooltip information
Combat observationson_combat_result, on_damage_committed, on_defeat_creditedObserve attacks, damage, and credited kills
Animationregister_animation_override, animation_overridesRegister packaged player animations and check their status
Craftingregister_recipe, preview_recipe, commit_recipe, cancel_recipeAdd recipes and let the game handle transactions
Fishing and encountersregister_fishing_reward_policy, register_monster_population_policyAdjust catch rewards and supported dungeon encounters
Cameraregister_camera_provider, trace_cameraSupply camera poses and check scenery clearance
UIregister_ui_panel, publish_uiCreate settings/status panels
Saved mod dataregister_state, state_snapshot, replace_state, on_state_changedStore your mod's character or single-player world data

Each feature has limits. Combat notifications report damage already dealt; they don't set damage. Quest notifications don't grant rewards. Equipment policies allow specific bonuses, and population policies allow specific encounter changes.

API2 doesn't expose general commands to move actors, change arbitrary stats or inventory, replace the whole HUD, register unrestricted audio/fonts, or control multiplayer sessions. Older API1 examples may use functions that no longer exist.

Save only mod owned state#

Register a state schema during initialize() to save your mod's data. Character data and single-player campaign-world data are stored separately. Save plain values, not Nodes, Resources, Callables, or engine references.

  1. Read state_snapshot(scope).
  2. Change your own data.
  3. Call replace_state(scope, data, lease, revision) using the snapshot's current lease and revision.
  4. Subscribe to on_state_changed to follow later updates.

Stale leases or revisions are rejected so they can't overwrite newer data. An accepted change is included in the next normal game save; it isn't written to disk immediately.

When upgrading a state schema, migrate only the mod's data. Don't change gameplay, random-number state, or the original profile as part of migration. Test fresh data, upgrades, unsupported newer data, and missing-mod cases on copied saves.

Keep the package ID stable and never write directly into native saves. Removing a mod's content can make a character incompatible. Recovery/import options may create a separate copy and discard missing content, so keep backups.

Install diagnose and test#

  1. Keep your editable mod folder separate from the installed copy.
  2. Extract any ZIP. In Mods, choose Open Mods folder and copy in the complete HelloReborn folder, with mod.json directly inside it. Keep the empty Data folder too.
  3. Return to Mods and choose Refresh. Enable the mod, check dependencies and load order, then choose Apply changes and Restart now.
  4. Open Mods again and check that the mod is loaded. Select it and use Configure for settings; script panels open from Extensions on the main menu.
  5. Test gameplay changes on a disposable character or copied save.

Enlarge the game window if the top-row controls are hidden. Install folder is another way to copy a mod: select the folder containing mod.json, rather than its parent or the ZIP.

Portable installs store mods in Data/mods beside the launcher. After editing a script or content file, close the game, update the installed copy, and restart. For live settings, use Configure > Apply; restarting isn't needed unless the setting requires it.

Test the mod alone, with its dependencies, and with other mods affecting the same features. Try both load orders where relevant. Check every supported core and location, save/reload, configuration changes, and what happens when data becomes unavailable.

Test the actions your mod uses: for example, commit and cancel a recipe, swap equipment, or turn in a quest. Also check updates, removal, missing assets, menu return, and clean exit.

Use the Mods diagnostics report to investigate failures. Include the Reborn build, mod ID/version, cores, load order, and reproduction steps. Use api.diagnostics() and short api.log messages for your own script. A script can compile and still fail during initialization or gameplay.

Package and maintain your mod#

ZIP one clear package folder with mod.json at its root and every referenced file present. Add a README with tested versions and cores, installation steps, settings, conflicts, save/removal risks, and credits.

Leave out caches, personal settings, test saves, and unrelated game files. Keep editable source and backups separately. Give each release a new versioned archive.

When porting an API1 mod, update its code to use API2 policies, notifications, state, and panels. Replace the old top-level entry/register(api) setup. Changing the manifest's version fields alone won't migrate the script.