Items

Give the player items that can be equipped, held in the right hand, put away and used. In this guide you create an item container, add items to it, and control switching with the keyboard and mouse wheel.

On this page

1. How the parts fit together
2. Add items
3. Item hold data
4. Equip, switch, holster and use
5. Pick up and drop
6. Definitions and categories
7. Grips and IK
8. Tune an item in the scene
9. IK presets
10. Item events
11. Common pitfalls

How the parts fit together#

ItemContainer on a child of the right hand

The list of items. Its order defines the slots: the first item is slot 1. Items stay inactive until they are equipped.

HandItemSocket on the player root

Holds the equipped item in the hand and owns the equip and unequip events.

ItemSwitcher on the player root

Reads the number keys, Q and the mouse wheel, and calls the container.

ItemHoldData on each item

The item's id, its grip and IK settings, its world prefab and its item-local events.

ItemDefinition optional asset

A shared description of an item: id, name, categories and prefabs. Covered in Definitions and categories.

Add items#

Use the Item Container Setup window, or set up each item by hand.

1. Open Tools › FBSystem › Item Container Setup.
2. Set Target Container, or click Scan Scene for Container. The container must be in the scene.
3. Drag an item prefab into Item Prefab and click 🚀 ADD ITEM. The window creates the item as an inactive child of the container. If the prefab has no ItemHoldData, one is added.
4. Optional: open Advanced IK Offsets to set the hold layer, grip offsets, hand and elbow offsets, hold style, pitch influence and vertical limits. Load IK Preset with Apply Preset fills the same fields from an ItemIKPreset.
5. The Inventory list shows the items in slot order. Extract copies the IK settings of an existing item into the form. X removes an item from the container.

To set up an item by hand, add an ItemHoldData with a unique itemId to the item prefab, then add the item to the container's Items list.

Item hold data#

ItemHoldData is the item's configuration. Its itemId defaults to NewItem, so change it for every item. EquipItemById and world item pickups use this id.

itemId string default NewItem

Unique id. A pickup matches a WorldItem to the item by this id.

definition ItemDefinition

Optional. When set, the id, categories and world prefab come from the definition.

category ItemCategory default None

Category flags, used when no definition is set.

worldItemPrefab GameObject

The prefab spawned when the item is dropped. It needs a WorldItem component.

attachmentData ItemAttachmentData

Grip, hold style and IK settings. See Grips and IK.

OnEquip, OnUnequip, OnUse UnityEvent

The item's own reactions, for example switching a light on. OnEquip and OnUnequip only fire for items that are shown.

Equip, switch, holster and use#

Switching plays a holster animation. The current item is lowered out of view, and then the new one is raised. The timings are on PlayerHandIK under Holster:

holsterDuration float default 0.2

Seconds to lower the hand out of view.

drawDuration float default 0.25

Seconds to raise the hand into view.

drawStartWeight float default 0.6

The hand IK weight that must be reached before the draw starts, so the arm does not swing up from the idle pose.

holsterOffset, holsterTiltAngle default tilt 50

Where the hand goes when lowered, and how far the item tips.

To turn the animation off, disable Smooth Transitions on HandItemSocket (on by default). Stow Timeout (default 1 second) completes a put-away even if the hand never reaches the lowered pose.

Pick up and drop#

The demo scripts add pickup and drop. The core package does not include them.

• E picks up the item you look at (PlayerInteraction). Only colliders on the layers in its Interactable Layer count.
• G drops the held item (PlayerDropSystem). The item's World Item Prefab is spawned in front of the camera and the item leaves the hand at once.

Definitions and categories#

An ItemDefinition describes an item in one place. Create one with Create › Player › Item Definition.

• Id: until you press Lock, the id follows the asset name. Lock it before you use the id in save data.
• Display Name: shown in pickup prompts. It falls back to the asset name.
• Category: flags Tool, Electric and Consumable. An item can have several. Check them with Is(ItemCategory).
• Held Prefab, World Prefab and Network Prefab: the hand item, the dropped item and the networked variant of the dropped item (used by the add-ons).

Assign the definition to ItemHoldData, to WorldItem or to the starter items of the demo PlayerInventory. Item id fields then show a picker with all definitions, and items without a definition keep working with a plain id.

Grips and IK#

Each item has its own grip and IK settings in ItemAttachmentData. The most common fields:

holdStyle HoldStyle default OneHandedRight

OneHandedRight or TwoHanded. Two-handed items use the left-hand offsets.

gripPositionOffset, gripRotationOffset Vector3

Where the item sits in the palm, relative to the hand socket.

overrideHandOffset, handOffset default 0.25, −0.15, 0.4

Turns on a custom hand position while standing. The value is relative to the camera.

overrideElbowOffset, elbowHintOffset

Custom elbow position while standing. Crouch variants exist for the hand and elbow.

pitchInfluence, pitchRotationInfluence default 0.3 and 0.5

How much looking up or down moves and tilts the hand.

fingerPoseRight, fingerPoseLeft

Finger grip templates. See Finger grips.

Tune an item in the scene#

1. On the item's ItemHoldData, enable Debug Mode and Tune Grip Mode.
2. Enter Play Mode and equip the item.
3. Move the item in the Scene view. Its transform is captured into the grip offsets.

For the hand and elbow targets, enable Tune Handles Mode instead. Handles then move the targets for the current stance (standing or crouching). Handles work only in Play Mode with the item equipped, Debug Mode on and the player standing still. A label shows why the handles are locked.

IK presets#

An ItemIKPreset stores a complete set of ItemAttachmentData so several items can share it. Create one with Create › Player › Item IK Preset. In the item's Inspector, the Preset Management section works with it:

• Load Preset: copies the preset into the item.
• Update Preset: copies the item's current settings into the preset.
• Create New Preset Asset: saves the item's settings as a new preset.

Item events#

With smooth transitions, ItemUnequipped fires while the old item is still visible. ItemEquipped can fire for an item that is still waiting to be drawn. Code and listeners are covered in Event API.

Common pitfalls#