Skip to content

03. Characters tool: Persona

Jump to bottom
Ketei edited this page Dec 3, 2025 · 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 centralize and configure all static data specific to a single character.

  • Access: Characters are loaded directly as resources (no singleton required).
  • 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 Methods:
    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 constant DEFAULT_DATA on the CharacterSheet[1] resource.

Important

This tool doesn't enforce an unique ID system. It's up to the developer that each character's ID is unique.

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 and initial custom data is properly assigned.

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.
To prevent data loss do the following:

  1. Load ALL your characters
  2. Change the variable type
  3. Save the script (Ctrl + S).
  4. Save all the characters (Ctrl + S again).

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 have the parent's value unless the subspecies has it enabled itself. This goes from the subspecies all the way to the top species.

Clone this wiki locally