How-To: Author an Item Definition
Goal: create an item as a Blueprint class, compose it from fragments, give it per-instance state, and make it discoverable at runtime.
1. Create the class and set its identity
Inside a scanned folder: right-click -> Blueprint Class -> `CrimsonInventoryItemDefinition`. In Class Defaults set Display Name and Item Type (a gameplay tag; the type drives context menus, type filters, and sorting).
2. Add fragments
Fragments are static, shared data on the definition. Add the ones you need under Fragments with the + button.
| Fragment | Display name | Properties | Read by |
|---|---|---|---|
UCrimsonInventoryItemFragment_Data | Inventory Data | bUnique, bStackable, MaxStackSize | Merging and splitting. Without it an item is a non-stackable single. |
UCrimsonInventoryItemFragment_Visuals | Item Visuals | ItemIcon, SlotWidgetClass, PickupActorClass, PickupMesh | UI; DropItemByEntry spawns PickupActorClass. |
UCrimsonInventoryItemFragment_Tooltip | Item Tooltip | TooltipWidgetClass, Description, RarityColor | UI. |
UCrimsonInventoryItemFragment_Footprint | Inventory Footprint | Dimensions, Weight, SlotCost, bAllowRotation | Grid layouts and the float-tag (weight) constraint. Default is 1x1, weight 0, 1 slot. |
UCrimsonInventoryItemFragment_Equippable | Equippable | EquipmentDefinition, PreferredSlotTag | The Equip context action. See How-To: Bridge to Equipment. |
UCrimsonInventoryItemFragment_Consumable | Consumable | UseEventTag, EffectsToApply, Application, DurationSeconds, DurationSetByCallerTag, ConsumeCount, CooldownTag, CooldownSeconds, CooldownEffect | The Use context action and the action bar. Adding it is the whole integration - the item then answers ICrimsonUsableObject and one shared use-ability serves it. See How-To: Make an Item Usable. |
UCrimsonInventoryItemFragment_Bag | Inventory Bag | Layout, IntCapacities, FloatCapacities, Constraints, bAllowNestedBags, MaxNestingDepth, Mode, GroupDisplayName | The layout runtime. See How-To: Nest Bags. |
UCrimsonInventoryItemFragment_GrantCurrency | Grant Currency On Pickup | CurrencyType, AmountPerItem | AddItemDefinition: the item converts to currency instead of occupying a slot. |
UCrimsonInventoryItemFragment_ContextActions | Context Actions | Actions | Context menus. See How-To: Add Context Actions. |
UCrimsonInventoryItemFragment_Constraint | Inventory Constraints | ConstraintsToCheck | Extra per-item rules evaluated when this item is placed. |
Click + on Fragments, pick the fragment class from the dropdown, expand it, fill the fields.
Stackable and MaxStackSize = 20, giving 25 produces two entries: x20 and x5.3. Add per-instance state (optional)
State fragments are replicated subobjects created per UCrimsonInventoryItemInstance. Their SaveGame properties serialize into the save struct and OnStateRestored fires after a load.
| State fragment | Properties | Behavior |
|---|---|---|
UCrimsonInventoryStateFragment_Durability | MaxDurability, CurrentDurability (replicated, SaveGame) | ApplyDurabilityChange, GetDurabilityPercentage, IsBroken. Server-only mutation. |
UCrimsonInventoryStateFragment_Lifetime | TotalLifetime, TimeRemaining (replicated, SaveGame) | Counts down on the server; resumes from TimeRemaining after OnStateRestored. |
Under State Fragments click + and pick State Fragment: Item Durability; set Max Durability. To write your own, create a Blueprint child of CrimsonInventoryStateFragment and override Initialize From Definition, Tick State, On State Restored, or Resume State Logic.
4. Discover definitions at runtime
Get All Item Definition Ids returns Primary Asset Ids from the scan paths; Load Item Definition By Id turns one into a class. Get All Item Definitions In Editor loads everything (editor and uncooked builds only).
See also
- How-To: Nest Bags
- How-To: Bridge to Equipment
- How-To: Add Context Actions
- Concept: Entries, Instances and Definitions