The InventoryItem component defines properties and logic for an object carried or held within the game's inventory system. It manages the item's state, lifespan, physical presence, and network synchronization.
using Sandbox;
using Sandbox.Citizen;
using System.Linq;
public enum ItemType
{
Primary,
Secondary,
Utility
}
public sealed class InventoryItem : Component
{
private const float DroppedLifetime = 15f;
[Sync] private float DespawnAt { get; set; }
/// <summary>Which inventory slot category this item can be placed in.</summary>
[Property] public ItemType Type { get; set; }
/// <summary>Icon material shown for this item in the inventory HUD.</summary>
[Property] public string ItemIconPath { get; set; } = "/materials/default.webp";
/// <summary>Citizen hold pose used while this item is in hand (desktop bodies and proxies).</summary>
[Property] public CitizenAnimationHelper.HoldTypes HoldType { get; private set; }
/// <summary>Which hand the citizen holds this item in.</summary>
[Property] public CitizenAnimationHelper.Hand Handedness { get; private set; }
[Property] public Vector3 RightHandPosition { get; private set; }
[Property] public Rotation RightHandRotation { get; private set; } = Rotation.Identity;
/// <summary>Local offset from the holster slot. Zero sits on the slot origin.</summary>
[Property, Group( "Stow" )] public Vector3 StowedPosition { get; private set; }
/// <summary>Local rotation applied when this item is holstered. Rotate this so a flashlight beam points forward while stowed.</summary>
[Property, Group( "Stow" )] public Rotation StowedRotation { get; private set; } = Rotation.Identity;
[Sync]
public GameObject SlotObject { get; private set; }
[Sync, Change( nameof( OnIsStowedChanged ) )]
public bool IsStowed { get; set; }
[Sync, Change( nameof( OnIsPhysicsEnabledChanged ) )]
public bool IsPhysicsEnabled { get; set; } = true;
public InventorySlot Slot => SlotObject?.Components.Get<InventorySlot>();
private Player Carrier => Slot?.Components.GetInAncestorsOrSelf<Player>()
?? Components.GetInAncestorsOrSelf<Player>();
/// <summary>True while any grip on this item is still held by a hand.</summary>
public bool IsHeld => GameObject.Components.GetAll<GrabPoint>( FindMode.InDescendants ).Any( g => g.IsGrabbed );
protected override void OnStart()
{
OnIsPhysicsEnabledChanged( IsPhysicsEnabled, IsPhysicsEnabled );
// An item can spawn in already stowed (initial loadout, or a proxy of someone
// else's carried item), so apply that state once instead of waiting for a change.
if ( IsStowed )
OnIsStowedChanged( false, true );
}
protected override void OnUpdate()
{
if ( IsProxy || DespawnAt <= 0f )
return;
if ( IsStowed || IsHeld )
{
CancelDespawnTimer();
return;
}
if ( Time.Now >= DespawnAt )
GameObject.Destroy();
}
/// <summary>Starts a fresh cleanup timer after the last hand releases the item into the world.</summary>
public void StartDespawnTimer()
{
if ( IsProxy || IsStowed || IsHeld )
return;
DespawnAt = Time.Now + DroppedLifetime;
}
/// <summary>Picking up or holstering an item cancels its pending cleanup.</summary>
public void CancelDespawnTimer()
{
if ( !IsProxy )
DespawnAt = 0f;
}
public void AssignSlot( GameObject slotObject )
{
SlotObject = slotObject;
}
public void ClearSlot()
{
var slot = Slot;
if ( slot is not null && slot.StoredItemObject == GameObject )
slot.ClearStoredItem();
SlotObject = null;
IsStowed = false;
}
/// <summary>
/// Detaches this item from the player and restores its world model. Physics is only
/// re-enabled once nothing holds it; <see cref="GrabPoint.Drop"/> does that for the
/// last hand to let go, so a two-handed grip keeps driving the item.
/// </summary>
public void DropToWorld()
{
ClearSlot();
GameObject.SetParent( null, true );
SetWorldModelVisible( true );
if ( !IsHeld )
{
IsPhysicsEnabled = true;
StartDespawnTimer();
}
}
/// <summary>
/// Shows or hides the item's world model for the local client only; rendering isn't
/// networked, so each machine decides what its own player gets to see.
/// </summary>
public void SetWorldModelVisible( bool visible )
{
var modelRenderer = GetComponent<ModelRenderer>();
if ( modelRenderer?.SceneObject is not null )
modelRenderer.SceneObject.RenderingEnabled = visible;
}
private void OnIsStowedChanged( bool wasStowed, bool isStowed )
{
if ( isStowed )
{
// A stowed item is only drawn for the VR player carrying it: desktop owners see a
// viewmodel instead, and nobody else should see items pinned to another body.
SetWorldModelVisible( !IsProxy && Game.IsRunningInVR && Carrier == Player.CurrentPlayer );
return;
}
// Out of the slot: other players see it in the carrier's hands again, while a local
// desktop player stays on their viewmodel until the item is dropped into the world.
SetWorldModelVisible( IsProxy || Game.IsRunningInVR || Carrier is { IsBot: true } );
}
public Rotation GetStowedRotation()
{
// Older items (including hot-reloaded instances) can still contain a zero quaternion.
return StowedRotation == default( Rotation ) ? Rotation.Identity : StowedRotation;
}
public void Stow()
{
CancelDespawnTimer();
IsStowed = true;
}
public void Unstow()
{
IsStowed = false;
}
private void OnIsPhysicsEnabledChanged( bool oldValue, bool newValue )
{
var modelCollider = GetComponent<Collider>( includeDisabled: true );
modelCollider?.Enabled = newValue;
var rigidBody = GetComponent<Rigidbody>( includeDisabled: true );
rigidBody?.Enabled = newValue;
}
}