> For the complete documentation index, see [llms.txt](https://roogame.gitbook.io/roogame/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://roogame.gitbook.io/roogame/roo-gameplay-framework/api-or-blueprint-reference.md).

# API OR Blueprint Reference

## Roo Stats Component

### Initialization

| Node                  | Purpose                                                               |
| --------------------- | --------------------------------------------------------------------- |
| Set Stat Value Config | Assign a Stats Set configuration to the component.                    |
| Reinitialize Stats    | Rebuild runtime Stats and Attributes from the assigned configuration. |

Reinitialization replaces current runtime values with newly initialized values. Use it deliberately rather than as a routine update call.

### Stat Queries and Changes

| Node                         | Purpose                                                             |
| ---------------------------- | ------------------------------------------------------------------- |
| Has Stat                     | Test whether a Stat tag exists in the component.                    |
| Get Stat Value By Tag        | Return the final calculated Stat value.                             |
| Get Stat Value By Name       | Resolve a Stat name and return its final value.                     |
| Get Stat Base By Tag         | Return the authored or current base value before runtime modifiers. |
| Set Stat Base By Tag         | Replace the Stat base value.                                        |
| Change Stat Base By Tag      | Add a signed delta to the Stat base value.                          |
| Add Modifier                 | Add a runtime Stat modifier and return its handle.                  |
| Remove Modifier              | Remove one modifier by handle.                                      |
| Remove Modifier By Tag       | Remove modifiers identified by Gameplay Tag.                        |
| Remove Modifier By Name      | Remove modifiers identified by Name.                                |
| Remove Modifiers From Source | Remove modifiers created by a specific source object.               |
| Clear Stat Modifiers         | Remove all runtime modifiers from a Stat.                           |

Use the Tag variants for stable production references. Name variants resolve against the component's runtime entries and remain independent of the Stats Designer namespace.

### Attribute Queries and Changes

| Node                   | Purpose                                                     |
| ---------------------- | ----------------------------------------------------------- |
| Has Attribute          | Test whether an Attribute tag exists.                       |
| Get Attribute Value    | Return the current value.                                   |
| Get Attribute Min      | Return the current minimum bound.                           |
| Get Attribute Max      | Return the current maximum bound.                           |
| Get Attribute Ratio    | Return the normalized position between minimum and maximum. |
| Set Attribute Value    | Replace the current value and apply its bounds.             |
| Change Attribute Value | Add a signed delta and apply its bounds.                    |

An Attribute can use a directly assigned Stat asset as its maximum. Initialization creates Stats before Attributes so Start Percent can be evaluated against that runtime Stat value.

### General Value Queries

| Node              | Purpose                                                       |
| ----------------- | ------------------------------------------------------------- |
| Get Value By Tag  | Resolve a unique tag as either a Stat or Attribute.           |
| Get Value By Name | Resolve a unique name as either a Stat or Attribute.          |
| Get Max Value     | Return the applicable maximum value for UI or gameplay logic. |

Tags and short names must remain unique across the Stat and Attribute entries when using general value queries.

### Stat Actions

| Node              | Purpose                                                                         |
| ----------------- | ------------------------------------------------------------------------------- |
| Apply Stat Action | Execute a Roo Stat Action Data Asset using source and target component context. |

Stat Actions are suitable for reusable damage, healing, resource changes, and formula-driven operations.

### Status Effects

| Node                                     | Purpose                                                  |
| ---------------------------------------- | -------------------------------------------------------- |
| Add Status Effect                        | Apply a Status Effect Data Asset and return the result.  |
| Remove Status Effect                     | Remove an active effect.                                 |
| Clear Status Effects                     | Remove every active effect from the component.           |
| Has Status Effect                        | Test whether an effect is active.                        |
| Get Status Effect Stack Count            | Return the current group stack count.                    |
| Get Status Effect Remaining Time         | Return remaining time for a specific runtime stack.      |
| Get Status Effect Progress               | Return normalized progress for a specific runtime stack. |
| Get Status Effect Display Remaining Time | Return the group-level remaining time intended for UI.   |
| Get Status Effect Display Progress       | Return group-level normalized progress intended for UI.  |

Use the Display queries for a single Buff icon that represents an effect group. Per-stack queries are intended for interfaces that visualize each stack independently.

### Stats Component Events

| Event                | Important Data                                       |
| -------------------- | ---------------------------------------------------- |
| On Stat Changed      | Stat tag, new value, delta                           |
| On Attribute Changed | Attribute tag, new value, maximum value, delta       |
| Modifier events      | Changed Stat and modifier context                    |
| Status Effect events | Added, removed, refreshed, or updated effect context |

Bind UI once during widget initialization, then update only the affected display when an event fires.

## Roo Inventory Component

### Inventory Operations

| Node                      | Purpose                                                       |
| ------------------------- | ------------------------------------------------------------- |
| Add Item                  | Add an item definition to the inventory.                      |
| Remove Item               | Remove an item entry or quantity.                             |
| Move Item                 | Move or swap an item between inventory positions.             |
| Refresh Inventory         | Rebuild registered inventory UI from current component state. |
| Register Inventory Widget | Register the main inventory widget with the component.        |
| Register Equipment Widget | Register the equipment widget with the component.             |

### Equipment Operations

| Node              | Purpose                                                      |
| ----------------- | ------------------------------------------------------------ |
| Can Equip Item    | Validate item and equipment-slot tag compatibility.          |
| Equip Item        | Equip an inventory item and apply its configured effects.    |
| Unequip Item      | Return an equipped item to inventory and remove its effects. |
| Toggle Equip Item | Equip or unequip based on current state.                     |

Assign the character's Roo Stats Component to the Inventory Component, or ensure the expected automatic lookup can find it, before relying on equipment stat modifiers.

### Inventory Events

Use inventory and equipment change events to refresh slot contents, selection, tooltips, and equipment state. Avoid rebuilding the entire interface every frame.

## Formula Context

Formula Data Assets evaluate with Self Component and optional Target Component context. The Blueprint pin may display as **Self** even though the C++ parameter uses a non-reserved name.

Examples using short names:

```
5 + 3 * self.stat[Level]
clamp(target.attr[Health], 0, self.stat[MaxHealth])
pow(1.1, self.stat[Level] - 1)
```

A complete custom-namespace tag is also valid:

```
self.stat[MyGame.Stats.Stat.Level]
```

See Formulas and Progression Tables for supported functions and references.