Item effects

Module PulseInventoryEffects (PulseInventory + PulseAttributes + Gameplay Ability System). Items act on the character: food and potions that heal, buffs, and stats while an item is equipped. No combat system is needed.

Consumables

Give the item the trait Consumable (FPulseItemTrait_Consumable):

Field Meaning
Effects, EffectLevel Gameplay effects applied to the user (instant heals, buffs over time)
Healing Health restored directly: a change of Pulse.Stat.Health through the attribute contract, for any attribute source of the user
UseTime Seconds the use takes (eating, drinking); 0 = instant
bCancelOnDamage, CancelTags Damage or one of the tags on the user cancels the use; nothing is used up
CooldownTag, Cooldown Cooldown group (Pulse.Item.Cooldown.*): all items of a group wait together
Cue Gameplay cue when the item takes effect
bConsume Uses up one item

Put Pulse Item User (UPulseItemUserComponent) on the pawn next to the ability system. Then:

  • UseFromInventory(Inventory, ItemId) or UseEquipped(Equipment, Slot) (empty slot = active hotbar slot) on the authority; clients call RequestUseFromInventory, RequestUseActiveHotbarItem, RequestCancelUse, or RequestItemUse(Request, Callback) / the node Request Item Use with the result: a request with an id that the server lets in with its guard (kinds Pulse.Request.Inventory.Use, .CancelUse) and answers; a failure also arrives as Pulse.Message.Request.Failed.
  • Results are FPulseResult: success with FPulseItemUseDetails in the details (bStarted and Duration while the use takes its UseTime, else it took effect at once), or a reason with a text: Pulse.Result.Failure.Inventory.Use.NotUsable (“This cannot be used.”), .Use.Cooldown (“This is not ready yet.”), .Use.NoAbilitySystem (“This cannot be used here.”), Busy while another item is used and NotFound for a missing item (PulseFoundation). The rules keep EPulseItemUseResult; Pulse::Inventory::Effects::ToResult maps it.
  • OnUseStarted / OnUseFinished(bCompleted) and GetUseProgress() on every machine for a progress bar; the user has Pulse.Item.State.Using while using. GetCooldownRemaining(Tag) for cooldown displays.
  • The use state (FPulseItemUseState) replicates the id of the item (DefinitionId, see the item catalog); clients find Definition through the catalog, and the started and finished events wait until it arrived, so an item made at runtime shows its name and icon there too. They fire once then, for every change that arrived while the item loaded, against the state before the first of them (spec PulseInventoryEffects.Catalog).
  • A completed use sends Pulse.Message.Inventory.ItemUsed on the authority (payload FPulseItemUsedMessage with User and Item; context: the user’s owner as Player and Instigator, the item definition as Source, its tags, amount 1), for quests (“drink a potion”) and statistics.
  • Other traits of the item add their own effects to a use: once the use took effect on the authority (instant, or when its UseTime is over; never for a refused or cancelled use), after the effects of the Consumable trait and before the message, the user calls FPulseItemTrait::OnUsed(const FPulseItemUseContext&) of every trait the item sees (Pulse::Inventory::NotifyItemUsed, see Inventory system). The context names the user, the item, the inventory stack or equipment slot it came from and holds a copy of the instance traits of the stack from before the use, so a food trait can read the freshness of the eaten stack (Context.FindItemTrait<FPulseItemTrait_Perishable>()) and fill hunger without listening to the message (spec PulseInventoryEffects.Trait hooks).

To use consumables through the inventory’s own UseItem / RequestUseItem (a “Use” button in the inventory UI), make the item definitions of class UPulseEffectItemDefinition: its UseItem hands the item to the user’s Pulse Item User.

Tuning: the tuning knob Pulse.Tuning.Inventory.UseCooldown of PulseFoundation multiplies the cooldown of a consumable; the tags of the item and its cooldown group are the tags of the context, the user is the player.

Stats while equipped

Put Pulse Equipment Effects (UPulseEquipmentEffectsComponent) next to the equipment. It applies, on the authority:

  • the trait Equipped Stats (FPulseItemTrait_EquippedStats): fixed stats (Pulse.Stat.* with a value) and infinite gameplay effects;
  • the Rolled Stats of the item instance (see Loot).

Hotbar items count only while their slot is active (bOnlyWhileActive). Everything is removed again when the item is unequipped. GetEquippedStat(Tag) sums a stat over all counting items.

The stats are gathered with Pulse::Inventory::GatherItemStats (Items/PulseItemRules.h, shared with the combat stats of PulseCombatInventory): nothing while the item is broken or its hotbar slot inactive, else the stats of every trait the item sees (instance traits first, definition traits they do not override). Own stat traits override FPulseItemTrait::AddEquippedStats (add Pulse.Stat.* values) and, to decide when the stats count, GetStatsOnlyWhileActive (the first trait that answers decides; without an answer the stats count only while active).

Stats that are Pulse attributes of the user (Pulse.Stat.MaxHealth, .MaxShield, .MaxStamina, or any attribute of its source) become Pulse modifiers with one source key per equipment slot, through the attribute contract: the same for the GAS adapter (the modifier lives in GAS as an active effect) and for the Pulse Attributes component. Which attribute a stat changes is set in Project Settings > Pulse > Gameplay > Inventory Effects > Stat Modifiers (FPulseStatModifier: attribute, target, op): MaxHealth, MaxShield and MaxStamina add to their stat, Pulse.Stat.HealthRegen and .StaminaRegen to the Rate of health and stamina. A stat without an entry adds to the attribute of the same tag when the user’s source knows it (armor of a game). Other stats are ignored here; other modules can use them (combat stats in PulseCombatInventory). The stats are named and written in tooltips and menus by the stat register of Pulse Foundation.

Cheats

Command Does
PulseInventoryUse <item\|hotbar> Uses a consumable by its item id (adds the two components to the pawn when missing)
PulseInventoryCancelUse Cancels the current use
PulseItemUseRequest <item\|hotbar\|cancel> Asks like the UI does (request with an id on a client; the stack is found by its item id) and prints the result with its text
PulseInventoryStats Prints health and the stats of the equipped items

PulseGameplay plugin documentation.

This site uses Just the Docs, a documentation theme for Jekyll.