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?#
| Field | Value | What it controls |
|---|---|---|
| game | >=0.3.0 <0.4.0 | Compatible Reborn versions in these examples |
| schema | 1 | The mod.json file format |
| api | >=2.0.0 <3.0.0 | Compatible ModAPI versions |
| script.api | 2 | The script entry format |
| version | Your mod's version | Your 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:
HelloReborn/
mod.json
main.gd
settings.json
Data/Save this as mod.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:
{
"schema": 2,
"fields": [
{"id":"enabled", "label":"Enable mod",
"type":"toggle", "scope":"personal",
"apply":"live", "default":true}
]
}Save this as main.gd:
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- Install HelloReborn using the installation steps below. Enable it, choose Apply changes, then Restart now.
- Back in Mods, select Hello Reborn and choose Configure.
- Turn Enable mod off, then click Apply. Wait for Settings applied, then return to the main menu.
- Open Extensions and choose Mod status. The panel should say Disabled. Its Refresh button reads the current setting again.
- 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:
"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.
| Area | Main methods | Use |
|---|---|---|
| Configuration | configuration, on_configuration_changed | Read settings and follow changes |
| Diagnostics | log, diagnostics | Report problems in your mod |
| Definitions | find_definitions, definition_snapshot | Read loaded game definitions |
| Player and inventory | player_snapshot, inventory_snapshot, on_player_changed, on_inventory_changed | Read player progress and inventory changes |
| Quests | quests_snapshot, on_quests_changed | Read the journal and observe turn-ins |
| Merging | register_merge_policy, merge_providers, register_pickup_merge_policy | Handle compatible book/charm charges and pickup merging |
| Equipment and tooltips | equipment_snapshot, register_equipment_modifier_policy, register_item_tooltip_policy | Add supported bonuses and tooltip information |
| Combat observations | on_combat_result, on_damage_committed, on_defeat_credited | Observe attacks, damage, and credited kills |
| Animation | register_animation_override, animation_overrides | Register packaged player animations and check their status |
| Crafting | register_recipe, preview_recipe, commit_recipe, cancel_recipe | Add recipes and let the game handle transactions |
| Fishing and encounters | register_fishing_reward_policy, register_monster_population_policy | Adjust catch rewards and supported dungeon encounters |
| Camera | register_camera_provider, trace_camera | Supply camera poses and check scenery clearance |
| UI | register_ui_panel, publish_ui | Create settings/status panels |
| Saved mod data | register_state, state_snapshot, replace_state, on_state_changed | Store 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.
- Read state_snapshot(scope).
- Change your own data.
- Call replace_state(scope, data, lease, revision) using the snapshot's current lease and revision.
- 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#
- Keep your editable mod folder separate from the installed copy.
- 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.
- Return to Mods and choose Refresh. Enable the mod, check dependencies and load order, then choose Apply changes and Restart now.
- 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.
- 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.
No chapters match that search. Try a different word or clear the search.
Back to the town ↗