Item views - Kinemation

What an ItemView represents

An ItemView is the presentation component on an equipped item prefab. It coordinates what the player sees and hears when gameplay equips, uses, aims, inspects, or holsters that item. The view does not represent an inventory record or authoritative gameplay object. It does not decide ownership, damage, hit detection, ammunition persistence, networking, or whether an action is allowed.

Layer	Owns
Your gameplay code	Inventory, input policy, authority, damage, cooldowns, ammo persistence, spawning, and networking.
Example component	A small reference implementation of gameplay state that calls the view.
ItemView	Paired character/item animation, procedural profile, item scale, visibility, audio, VFX, FOV, recoil, and camera feedback.

Base ItemView

GameplayItemView is the base presentation class. Keep it on the same GameObject as the item’s Animator. During Awake, the view:

Caches its original local scale and parent GameplayAnimationController.
Finds the item Animator.
Builds an animation slot mixer over the Animator’s playable graph, or creates a graph when the Animator has none.
Caches child transforms for bone visibility.
Plays itemIdleClip as the base item pose.

Without an Animator on the ItemView GameObject, the item animation graph is not initialized. Lifecycle calls still exist, but PlayItemAnimation returns false and paired item actions do not play.

Paired character and item actions

GameplayCharacterItemClip groups a character-side GameplayAnimationAsset, an item-side asset, and an optional sound. PlayCharacterItemAnimation starts both animation assets together and plays the sound through the player’s AudioSource. Use paired assets for draw, holster, fire, reload, inspect, throw, and other actions where the hands and equipped object must remain synchronized.

Equip context

OnEquipItem(player) resolves the active presentation context from the supplied player. When the argument is null, it uses the item’s transform root. The method then:

Finds a child GameplayAnimationController and GameplayCamera.
Applies the view’s proceduralAsset to the character controller.
Resolves any retargeted item scale from that procedural asset.
Finds the context root’s AudioSource for item sounds.

Call the base method from custom overrides before starting product-specific draw logic.

Lifecycle contract

Method	When gameplay calls it	Base behavior
`OnEquipItem(player)`	The item becomes active.	Resolves the player context and applies the procedural profile. Returns an action duration.
`OnUnEquipItem()`	The item is being holstered or replaced.	Extension point that returns a duration.
`OnUseItem()`	Use begins or a one-shot action fires.	Extension point.
`OnStopUsingItem()`	A held use input ends.	Extension point.
`OnAim(isAiming)`	Aim state changes.	Extension point.
`OnInspect()`	Inspect begins.	Extension point that returns a duration.
`SetItemVisibility(visible, delay)`	Draw or holster controls when the object appears.	Activates or deactivates the item immediately or through a delayed call.
`PlayItemAnimation(asset, startTime)`	A custom view needs an item-only animation.	Plays the asset through the view’s animation slot mixer.
`PlayCharacterItemAnimation(clip)`	A custom view needs a synchronized action.	Plays character animation, item animation, and sound together.

Return the animation length for actions that should block other actions. Return zero for no blocking action. A specialized sequence may return a negative duration and stop the controller action itself when the sequence actually finishes.

Bone visibility

HideBoneByName and UnhideBoneByName preserve the transform hierarchy and animation bindings. Hidden transforms are scaled to 0.001 during LateUpdate. Use this for magazines, cartridges, or throwable parts that animation events need to hide without deleting or disabling the animated transform.

In the current implementation, UnhideBoneByName stops forcing the small scale but does not restore the cached default scale itself. The animation or your event code must write the visible scale again.

GameplayItemExample

GameplayItemExample is a reference adapter, not the item presentation itself. It finds GameplayItemView on the same GameObject and forwards equip, unequip, aim, use, stop-use, and inspect calls. The supplied GameplayControllerExample uses that adapter to demonstrate one complete loop:

It instantiates each configured item prefab below the mapped weapon bone.
It hides every item and equips the active one.
It forwards Input System callbacks to the active Example component.
It uses durations returned by equip, holster, and inspect to block overlapping actions.
On item change, it waits for the current view’s holster duration before equipping the next item.

Use this as executable reference code. Your production controller can call an ItemView directly or provide its own adapter with the same lifecycle.

using UnityEngine;
using KINEMATION.Shared.GameplayFramework.Scripts.Runtime;

public sealed class InventoryItemPresentation : MonoBehaviour
{
    [SerializeField] private GameplayItemView itemView;

    public float Equip(GameObject player)
    {
        return itemView.OnEquipItem(player);
    }

    public float Holster()
    {
        return itemView.OnUnEquipItem();
    }

    public void SetAiming(bool isAiming)
    {
        itemView.OnAim(isAiming);
    }

    public void BeginUse()
    {
        itemView.OnUseItem();
    }

    public void EndUse()
    {
        itemView.OnStopUsingItem();
    }
}

The inventory system still decides when these methods are legal and how their returned durations affect its state.

Included Sci-Fi item views

Every supplied item prefab combines a concrete ItemView with the Example component that drives it in the demo player.

Prefab	ItemView	Example component	What it demonstrates
`W_ARX_Mk2`	`ChargeWeaponView`	`ChargeWeaponExample`	Energy charge rifle. Burst mode becomes hold-to-charge; release fires and resets the charge presentation.
`W_Gepard`	`WeaponView`	`WeaponExample`	Standard firearm lifecycle with recoil, muzzle flash, camera shake, fire audio, reload, inspect, and ADS.
`W_M97`	`ThrowableItemView`	`GameplayItemExample`	Held throwable sequence with throw-start, repeating hold loop, release delay, throw-end, and redraw.
`W_Onyx`	`RevolverWeaponView`	`WeaponExample`	Revolver presentation that selects a partial reload from the number of missing rounds.
`W_RPG90`	`WeaponView`	`WeaponExample`	Launcher presentation using the same standard firearm view contract with launcher-specific clips and data.
`W_TP12`	`ShotgunWeaponView`	`WeaponExample`	Shell-by-shell reload, pump sequencing, multi-round fire length, and the product-specific cartridge display.

Choose a reference implementation

Start from the prefab whose presentation sequence matches your item:

Use W_Gepard or W_RPG90 for a conventional weapon using WeaponView.
Use W_ARX_Mk2 for an energy weapon that charges while use is held.
Use W_Onyx when reload selection depends on missing rounds.
Use W_TP12 for an open-ended, shell-by-shell reload.
Use W_M97 for a held throwable or another start-loop-release interaction.

Duplicate the prefab, preserve the ItemView and Example pairing while testing, and replace the Example component when your gameplay implementation is ready.

Charge Weapon View with charge-start, charge-loop, and charge audio settings — ARX Mk2 energy charge rifle presentation fields.

Revolver Weapon View with partial reload animation entries — Onyx partial reload entries on Revolver Weapon View.

Weapon runtime

Configure the Shooter Core view fields and specialized firearm behavior.

Example implementations

Adapt the supplied Example classes to your gameplay architecture.

​What an ItemView represents

​Base ItemView

​Paired character and item actions

​Equip context

​Lifecycle contract

​Bone visibility

​GameplayItemExample

​Included Sci-Fi item views

​Choose a reference implementation

Weapon runtime

Example implementations

What an ItemView represents

Base ItemView

Paired character and item actions

Equip context

Lifecycle contract

Bone visibility

GameplayItemExample

Included Sci-Fi item views

Choose a reference implementation