Skip to main content
forge-attributes owns a character’s stats. An attribute has a base value plus any number of modifiers from other systems (equipment, effects, buffs). The final value is computed at read time, so callers always see the live total.

​
Concepts

  • Definition. A stable attr:<name> with a label, default, min, and max. Ships a generic six-attribute set (STR/DEX/INT/CON/WIS/CHA).
  • Base value. The character’s own stat, persisted.
  • Modifier. A contribution from a source, keyed by source_id so it can be removed exactly. op is add (more ops may follow).
  • Resolution. final = base + sum(add modifiers), clamped to the definition’s range.

​
Exports

ExportSignatureReturns
GetDefinitionsGetDefinitions()Result{ data = { ... } }
GetAttributeGetAttribute(character_id, attribute_id)Result with { base, bonus, final, definition }
GetAttributesGetAttributes(character_id)Result{ data = { attributes = { [id] = {...} } } }
SetBaseValueSetBaseValue(character_id, attribute_id, value)Result
AddModifierAddModifier(character_id, attribute_id, modifier)Result
RemoveModifierRemoveModifier(character_id, attribute_id, source_id)Result
GetModifiersGetModifiers(character_id, attribute_id)Result{ data = { modifiers } }
ClearModifiersClearModifiers(character_id, attribute_id?)clears one attribute, or all if omitted

​
Modifier shape

exports["forge-attributes"]:AddModifier(cid, "attr:strength", {
  source_id   = "equip:" .. instanceId,  -- unique; how you remove it later
  source_type = "equipment",
  value       = 5,
  op          = "add",
})
Attribute modifiers use attribute_id when supplied through forge-effects definitions, but AddModifier itself takes attribute_id as its second argument and a modifier table whose field is source_id. Match the shapes above exactly.

​
Events

EventPayload
forge-attributes:server:baseValueChanged{ character_id, attribute_id }
forge-attributes:server:modifierAdded{ character_id, attribute_id, source_id }
forge-attributes:server:modifierRemoved{ character_id, attribute_id, source_id }
forge-attributes:server:modifiersCleared{ character_id }
Modifiers are cleared automatically when a character deactivates; their owning system re-applies them on the next activation.

​
Configuration

The six default attributes live in editable shared/data/attributes.lua (ForgeAttributes.DefaultAttributes), gated by Config.ShipDefaults. Add or override by id via the data file or Config.Attributes. 
{ id = "attr:strength", label = "Strength", default = 10, min = 0, max = 100 }