Skip to content

05. Skills & Traits tool: Talents

Jump to bottom
Ketei edited this page Jul 1, 2026 · 4 revisions

I. Introduction and Core Principles

1.1 Purpose and Role

The Talents tool is the central metadata catalog for all Stats, Skills and Traits defined in your project.

  • Role: In the external GDScript files (stat_block.gd, skill_set.gd and trait_block.gd) stats, skills and traits are defined as simple variables. The Talents tool bridges the gap by providing the human-readable data and Custom Data associated with those variables.
    • Access: The system is managed by three separate singletons and resource classes:
    • Stats: NexusForge.Stats (Class: NFStatManager)
    • Skills: NexusForge.Skills (Class: NFSkillManager)
    • Traits: NexusForge.Traits (Class: NFTraitManager)
  • Storage:
    • All metadata for stats is stored in a separate StatCatalog resource file.
    • All metadata for skills is stored in a single SkillCatalog resource file.
    • All metadata for traits is stored in a separate TraitCatalog resource file.

Warning

The resource files that these tools use gets cleaned on project export to remove old and redundant information. It is not recommended to manually edit the storage of any of the files as the data could be removed from the exported copy.

1.2 Data Synchronisation and Dual Nature

The catalogues manage two distinct types of entries.

  1. Exported attributes: These are attributes defined statically in the GDScript files. (Exported variables)
  2. Custom Talents: These are talents created dynamically at runtime via the API (create_*).

Important

  • Creating a custom stat/skill/talent during runtime will make all current and future instances of SkillSet and TraitBlock also register it with an initial value of 0.
  • Erasing a custom stat/skill/talent WON'T remove it from existing instances of StatBlock, SkillSet and TraitBlock but will prevent new instances of them from having it.

II. The Editor Interface

Note

  • Only the valid variables declared on each script will appear on the drop-down.
  • The items in the drop-downs are always sorted alphabetically.
  • These drop-downs automatically update when the external GDScript files[1] are saved.

The Talents editor features a simple, three-column layout for focused data entry, managing the catalogue resources from one window.

  • Layout: The window is divided into an identical Stat Column (Left), Skills Column (Center) and Traits Column (Right).
  • Drop-downs: A drop-down at the top of each column lists all available stats/skills/traits.
  • Metadata Fields: Selecting an ID from the drop-down loads the fields for that attribute:
    • Name: The human-readable display name.
    • Description: The text description.
    • Custom Data: A tree view for storing custom data.

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

III. Usage in GDScript:

The catalogues (accessed via NexusForge.Stats, NexusForge.Skills, NexusForge.Traits) manages all metadata for skills.

Tip

All attributes (exported & custom) can be accessed and updated directly with their ID. e.g. NexusForge.Stats.health, NexusForge.Skills.shield & NexusForge.Traits.cold_resist

Caution

Unlike other modules, accessing a non-existing attribute directly WILL return an object. To verify if the attribute is valid call is_valid(). e.g. NexusForge.Stats.invalid_stat.is_valid(): Will return false.

3.1 Signals and Constants

Signal Arguments Emitted
[stat/skill/trait]_created id: StringName Emitted when a new custom attribute is created.
[stat/skill/trait]_erased id: StringName Emitted when a custom attribute is erased.
stat_clamping_toggled stat_id: StringName Emmited when the clamping of a stat was enabled or disabled.
stat_clamping_changed stat_id: StringName Emitted when a value of a clamped stat changed.

3.2 Methods

A. Retrieval

Function Signature Purpose Return Type
stats()/skills()/traits() Returns a list containing all registered attributes. Array[StringName]
get_*_name(id) Returns the display name for the attribute. String
get_*_description(id) Returns the description for the attribute. String
get_*_data(id, data_id) Returns the value of a specific custom data key. Variant or null if key doesn't exist.

NFStatManager only.

Function Signature Purpose Return Type
allows_greater(id) Returns true if the stat allows for greater values. Bool
allows_lesser(id) Returns true if the stat allows for lesser values. Bool
get_range_max(id) Returns the maximum allowed value for the stat. Float
get_range_min(id) Returns the minimum allowed value for the stat. Float

B. Assignment

Function Signature Purpose Notes
set_*_name(id, new_name) Sets the display name for the attribute.
set_*_description(id, new_description) Sets the description for the attribute.
set_*_data(id, data_key, data) Sets a custom data key-value pair. If data is null, the key is erased.

C. Validation

Function Signature Purpose Return Type
has_*(id) Checks if the attribute is registered Bool
has_*_data(id, data_id) Checks if the skill/trait has the specified custom data key. Bool

D. Removal

Function Signature Purpose Notes
erase_*(id) Removes an entry. Entries for exported attributes can't be removed.
clear_*_data(id) Clears the entire custom data dictionary for the attribute.

IV. Usage in GDScript: StatBlock, SkillSet and TraitBlock Class.

Tip

All attributes (exported & custom) can be accessed and updated directly with their ID. e.g. character.stats.health, character.skills.shield & character.traits.cold_resist

The StatBlock, SkillSet and TraitBlock class are the data objects used on the CharacterSheet. It holds the actual numerical values for a specific attribute.

4.1 Retrieval

Function Signature Purpose Return Type Notes
stats(), skills()/traits() Returns a list with all Exported attributes. Array[StringName] Static methods.
custom_*() Returns a list with the custom attributes registered in this specific instance. Array[StringName]
custom_[skill/trait]_value(id) Gets the value of an instance-specific custom skill/trait. Integer Returns -1 if the skill/trait doesn't exist.

4.2 Validation

Function Signature Purpose Return Type
has_custom(id: StringName) Checks if the instance has a custom attribute. Bool

4.3 Creation & Assignment

Function Signature Purpose Notes
create_custom(id, value/type) Creates a custom trait for this instance only. The second argument is for value on skills and traits.
For stats it takes either enum TYPE_INT or TYPE_FLOAT

To update a custom attribute access it directly after creation. e.g. NexusForge.Stats.my_custom_stat = 6

Caution

When updating a custom attribute always ensure the stat exists by using has_custom. If the attribute doesn't exist it'll trigger a null-access error.

V. Footnotes

  1. Default paths:
  • StatBlock: res://addons/nexus_forge/resources/stat_block.gd.
  • SkillSet: res://addons/nexus_forge/resources/skill_set.gd.
  • TraitBlock: res://addons/nexus_forge/resources/trait_block.gd.

Clone this wiki locally