Skip to content

03. Characters tool: Persona

Jump to bottom
Ketei edited this page Jun 30, 2026 · 11 revisions

I. Introduction and Core Structure

1.1 Purpose and Access

The Characters tool is designed for the creation and management of individual entity data using the custom CharacterSheet resource class. This tool allows developers to centralise and configure all static data specific to a single character.

Access

Characters are individual resources and can be used directly. But registering them to the singleton allows register mods to tweak the character sheet before returning it.

Method Return Advantages Downsides
load("res://my_character.tres") CharacterSheet Conflicting IDs are irrelevant. -
NexusForge.Characters.get_character("character_id") CharacterSheet - Apply modifications/overrides to the sheet.
- The sheet is shared by pointer.		 Requires character registration and an unique ID[4]

Storage

Every character is saved as a separate .tres file, featuring a custom icon. Double-clicking the file opens it directly in the editor.

Creation

  1. Using Godot's built-in Resource Creator and then double-clicking the resulting file.
  2. Going to the Nexus Forge editor, selecting the Characters tab, clicking the "three dots" menu, and choosing "Create character".

1.2 Character Sheet Structure

Field Type Notes
Character ID StringName Unique identifier.
Name String Display name.
Gender enum Defined by members of the Gender enum[1].
Species StringName ID of the species defined on the Species tool.
Custom Data Dictionary Contains data unique to that character
Stats StatBlock Defines the character stat values
Skills SkillSet Defines the character skills values
Traits TraitBlock Defines the character trait values

Tip

You can set up so that all new characters created have default custom data entries by modifying the variable custom_data on the CharacterSheet[1] resource.

Important

The characters don't enforce an unique ID. However if using the Character's object in the singleton one is required.

1.3 Defining Attributes (External Script Dependency)

The structure of the stat, skill and trait block is dictated by external GDScript files. The editor updates automatically upon script save.

Block Script File Type Requirement
Stats stat_block.gd Must be an @export[2] variable of class RangeInt or RangeFloat.
Skills skill_set.gd Must be an @export[2] variable of type int.
Traits trait_block.gd Must be an @export[2] variable of type int.

For more information and examples on defining attributes see Defining Character Attributes.

II. Species Integration and Value Limits

2.1 Interacting with Species (Data Enrichment)

Note

Linking a character to a Species ID is not mandatory for runtime functionality but is vital for editor convenience and data enrichment.

  • Defining a species allows easy access to shared custom data (e.g., species-wide resistances) and enables the import function.
  • Subspecies are visually indicated in the dropdown by parentheses (e.g., Blue Slime (Slime)).
  • A button next to the species dropdown allows the user to import the Stats, Skills, and Traits from the selected Species/Subspecies. If a Subspecies is selected, the tool resolves values via recursive inheritance[3].

2.2 Stat Value Limits (Editor Interface)

This feature is available only for Stats.

  • A button located to the left of the stat's name expands Min/Max limit controls.
  • Expanding the section reveals two Spinboxes ("Min" and "Max") and their corresponding Checkboxes.
  • Enabling a checkbox enforces the boundary.
  • Visual Cue: The icon on the button changes to show which limits are active:
    • Min Enabled: The left part of the icon turns green.
    • Max Enabled: The right part of the icon turns green.

Important

Enabling limits automatically enforces it on the stat value. If it falls outside the enabled limit, it is automatically clamped to the limit.

III. Usage in GDScript (Data Objects and API)

The CharacterSheet functions as a data container. Runtime interaction involves accessing the nested attribute objects.

Important

This class has a custom constructor CharacterSheet.new_character(). This method ensures all objects are initialized correctly.

3.1 The RangeInt and RangeFloat Classes (Stats)

These objects manage the value and constraints of a Stat.

Variable Type Purpose Notes
value int / float The current active value of the stat.
min_value / max_value int / float The defined boundary limits.
allow_lesser bool If true, the value is allowed to fall below min_value. When set to true, it immeditaly clamps value to enforce the limit.
allow_greater bool If true, the value is allowed to exceed max_value. When set to true, it immeditaly clamps value to enforce the limit.

Runtime Access Example:

# Load the character sheet resource
var my_character_sheet: CharacterSheet = load("res://path/to/my_character.tres")

# Accessing a value
var current_health: float = my_character_sheet.stats.health.value

# Setting a new min value
my_character_sheet.stats.health.min_value = 10.0

Caution

RangeInt and RangeFloat are distinct classes, changing the type of an existing stat variable (@export var health: RangeInt to RangeFloat) will result in the loss of all saved values for that stat in the resource file upon loading it.

IV. Footnotes

  1. The default path for the CharacterSheet script is res://addons/nexus_forge/resources/character_sheet.gd
  2. The variable must have the export flag. For example @export or @export_storage.
  3. Species stat/skill/trait inheritance means that the subspecies will inherit stats from the parent species. To learn more check the species inheritance system (Link Pending)
  4. If the Register Character IDs setting is on, all characters will be register by default, waning you of any potential duplicate ID too.

Clone this wiki locally