-
Notifications
You must be signed in to change notification settings - Fork 3
04. Species tool: Kindred
The Species tool (Singleton: NexusForge.Species, Class: NFSpeciesManager) is the system for managing template-level data and base attributes for all entities.
- Role: Provides base attribute values (Stats, Skills, Traits).
- Common Data: Its primary purpose is to store attributes and Custom Data that is shared between every member of that species (e.g., base resistances, faction alignment). This prevents the need to duplicate this data across every individual character file, saving memory and simplifying maintenance.
Important
Inheritance & genetic dilution are applied on game start. Changing the setting in-game after the species catalogue has loaded won't have any effect.
Warning
The resource file that this tool uses gets cleaned on project export to remove old and redundant information. It is not recommended to manually edit the storage as the data could be removed from the exported copy.
This column is for creating and organizing the species templates.
- Search: A text field at the top allows for filtering the species tree.
- Top-Level Creation: A button next to the search bar (A DNA icon with a green +) creates a new top-level species, prompting the user for a unique ID.
- Hierarchy Tree: Displays all species and subspecies in a collapsible tree structure. You can edit a species ID by double-clicking it.
- Subspecies Creation: Each item in the tree has a button next to it, which creates a child nested under that species.
- Organization: Species and subspecies can be reorganized by dragging and dropping them within the tree structure.
Note
All species and subspecies items are always sorted alphabetically within their respective level.
When a species or subspecies is selected, its unique descriptive fields are displayed here.
- Name: The human-readable display name.
- Description: A text field for descriptive lore or notes.
- Custom Data Field: A dedicated tree view for storing unique, species-specific data that is intended to be shared across all characters of that type.
Tip
You can set up so that all new species created have default custom data entries by modifying the variable custom_data on the SpeciesSheet[1] resource.
This column lists all Stats, Skills, and Traits defined in the relevant external scripts.
Each individual attribute field is accompanied by a checkbox. This checkbox is the core of the inheritance logic.
For more information and examples on defining attributes see Defining Character Attributes.
Note
This system can be disabled by setting the Species Genetic Dilution setting on ProjectSettings to 1.0
The tool uses a recursive override system for inheritance, meaning it checks the entire parent chain, not just the immediate parent.
| State | Checkbox | Value Used | Logic Applied |
|---|---|---|---|
| Inherited | Unchecked (Disabled) | The system checks the parent, then the parent's parent, and so on, until it finds the highest ancestor that has the attribute enabled (checked). | |
| Overridden | Checked (Enabled) | The Subspecies' own input field value is used. | This breaks the inheritance chain below this point for this specific attribute. |
Example of Recursive Inheritance:
- Species A defines Health = 10 (Enabled).
- Species B defines Stamina = 10 (Enabled).
- Species C defines Mana = 10 (Enabled).
The final base attributes for each species (with a genetic dilution setting of 0.0) would be:
| Species | Parent Species | Health | Stamina | Mana |
|---|---|---|---|---|
| Species A | - | 10 | 0 | 0 |
| Species B | Species A | 10 (Inherited) | 10 | 0 |
| Species C | Species B | 10 (Inherited) | 10 (Inherited) | 10 |
Sometimes you don't want your species to inherit the full attribute from the parent species. The genetic dilution system works as a cumulative multiplier that weakens an attribute the farther it is from the species. The formula works like this:
-
dilution= 1.0 - (genetic dilution * number of generations) -
species stat= nearest generation with the stat *dilution
dilution can't go under 0.0.
This means that with a genetic dilution of 0.4, the base species will inherit the parent species' attributes at 60%, then the grandparent species at 20% and stop inheriting after that.
| Species | Distance | Dilution Multiplier (0.25) | With Dilution | Without Dilution |
|---|---|---|---|---|
| Ancient Dragon | Origin | 1.0 | 100 | 100 |
| Dragon | 1 Gen. | 0.75 | 75 | 100 |
| Dragonborn | 2 Gen. | 0.50 | 50 | 100 |
| Kobold | 3 Gen. | 0.25 | 25 | 100 |
| Hatchling | 4 Gen. | 0.0 | 0 | 100 |
The system allows you to assign 2 different parent species to a species, creating an "hybrid". Hybrids are semi-integrated in the inheritance system, where they will inherit from the dominant branch like other species, but their immediate parents' stats will be acquired in a 75% for the dominant species and 25% for the recessive species.
| Species | Dominant species | Recessive species | Attribute |
|---|---|---|---|
| Lion | - | - | 100 |
| Eagle | - | - | -20 |
| Gryphon | Lion | Eagle | +75 from lion (75% of 100) & -5 from eagle (25% of -20) = 70 |
| Function Signature | Purpose | Notes |
|---|---|---|
register_species(res: SpeciesSheet) |
Registers the given resource as a species. | Registration only happens if the sheet's id is not registered. |
has_species(species_id: StringName) |
Checks if the species is registered. | |
link_species(species_id: StringName, parent_species: StringName) |
Sets species_id (subspecies) to be a child of parent_species. |
If parent_species is an empty StringName (&"") it clears the link, making species_id a top-level species. |
get_dominant_species_of(species: StringName) |
Returns the immediate dominant parent species ID. | Parent species will return &"", but so will inexistent species. |
| Function Signature | Purpose | Return type |
|---|---|---|
get_species_[stat/skill/trait]_value(species_id, [stat/skill/trait]_id) |
Returns the raw value assigned to the species (or 0 if not assigned). |
[float/int/int] |
| Function Signature | Purpose |
|---|---|
set_species_[stat/skill/trait]_value(species_id, [stat/skill/trait]_id, new_value) |
Sets the new species attribute to new_value
|
| Function Signature | Purpose |
|---|---|
erase_species_[stat/skill/trait](species_id, attribute_id) |
Erases the given attribute from the provided species. |
| Function Signature | Purpose | Return Type | Notes |
|---|---|---|---|
get_species(species_id) |
Returns an object containing the species information. | SpeciesSheet |
The species can also be accessed directly. e.g. NexusForge.Species.my_species_id
|
get_species_name(species_id) |
Returns the name of a species. | String |
Returns an empty string if the species isn't registered. |
get_species_description(species_id) |
Returns the description of a species. | String |
Returns an empty string if the species isn't registered. |
get_species_data(species_id, data_key) |
Returns custom data assigned to a species. | Variant |
Returns null if the species of data_key don't exist. |
| Function Signature | Purpose | Notes |
|---|---|---|
set_species_name(species_id, new_name) |
Sets a species name. | |
set_species_description(species_id, description) |
Sets the species description. | |
set_species_data(species_id, data_key, data) |
Sets custom data for a species. | If data is null then the data entry will be erased if it exists. |
- The default path of the
SpeciesCatalogfile is:res://addons/nexus_forge/resources/species.gd