10. Custom Stats

I. Introduction and Core Principles

1.1 Purpose and Design Philosophy

The StatCatalog (Singleton: NexusForge.Stats, Class: StatCatalog) is the project-wide registry for managing custom stats that are created dynamically at runtime.

• Role: It is designed to register global stats that are not defined as static @export variables in the StatBlock file. This allows for adding new stats via code (e.g., from other plugins or DLC) that all StatBlock instances can recognize and track.
• No Visual Tool: Unlike other catalog tools, the StatCatalog does not have a visual editor. It is a code-only API, as stats are generally considered self-explanatory and are managed entirely by the developer.

Note

• When a new custom stat is registered via the API, it is automatically added to all existing StatBlock instances (that were created using StatBlock.new_stat_block()) and will be included in all newly instantiated blocks.
• When a custom stat is erased from the catalog, it is NOT removed from existing StatBlock instances. It only prevents the stat from being added to new instances created after the erasure.

---

II. Usage in GDScript (API Hooks)

The API is accessed via the NexusForge.Stats singleton and provides full control over the definition and properties of global custom stats.

2.1 System Signals

Signal Name	Arguments	Purpose
stat_created	stat_id: StringName	Emitted when a new stat is successfully registered.
stat_erased	stat_id: StringName	Emitted when a registered stat is erased.
stat_min_range_changed	stat_id: StringName, new_min: float	Emitted when set_custom_min_value is called only if the stat's definition does not allow lesser values.
stat_max_range_changed	stat_id: StringName, new_max: float	Emitted when set_custom_max_value is called only if the stat's definition does not allow greater values.

2.2 Stat Creation and Lifecycle

Function Signature	Purpose	Return Type	Notes
create_custom(stat_id, type, use_min_range, use_max_range, min_value, max_value)	Registers a new stat with its type, range configuration, and default min/max values.	-	Creation fails if the custom stat already exists.
custom_stats()	Returns a list containing all registered custom stat IDs.	Array[StringName]
custom_stat_exists(stat_id)	Returns true if the stat is registered in the catalog.	Bool
custom_stat_type(stat_id)	Returns the stat's built-in type (TYPE_INT or TYPE_FLOAT).	Integer	Returns TYPE_NIL if the stat doesn't exist.
erase_custom(stat_id)	Erases the custom stat from the global catalog.	-	Does not erase the stat from existing StatBlock instances.

2.3 Range and Constraint Management

These functions allow runtime adjustment and inspection of the stat's global boundaries.

Function Signature	Purpose	Return Type	Notes
set_custom_min_value(stat_id, new_min)	Sets the global minimum boundary value for the stat.	-
set_custom_max_value(stat_id, new_max)	Sets the global maximum boundary value for the stat.	-
get_custom_min_value(stat_id)	Returns the current global minimum boundary value.	Float	Returns 0.0 if the stat ID doesn't exist.
get_custom_max_value(stat_id)	Returns the current global maximum boundary value.	Float	Returns 0.0 if the stat ID doesn't exist.
custom_allows_lesser(stat_id)	Returns true if the stat's definition allows its value to be less than the minimum boundary.	Bool	Returns true if stat doesn't exist.
custom_allows_greater(stat_id)	Returns true if the stat's definition allows its value to be greater than the maximum boundary.	Bool	Returns true if stat doesn't exist.