Skip to content

Generated reference. This page mirrors Code/Items/README.md, this module's source-of-truth documentation (Standards/02_DOCUMENTATION_STANDARDS.md §1). Edit it there, not here -- this file is regenerated on every docs build and any local edit is silently overwritten.

Items

Purpose. The authored template for everything a player can carry, use, wear, or store things in — and the load-time machinery that turns .item assets into validated, inheritance-resolved ItemDefinitions. 131 real assets exist under Assets/Items/ as of Milestone 8's content migration — see that folder's own README for the full disposition. See Documentation/Architecture/09_ITEM_FRAMEWORK.md and ADR-0004.

Responsibilities. - ItemDefinition — a GameResource (.item asset), authored in the inspector or as JSON. No C# required to add an item; see Guides/02_ADDING_AN_ITEM.md. - ItemInstance, ItemId, ItemStateBag — a specific item's identity and per-instance state, as distinct from the shared ItemDefinition template it was created from. Declared here (not in Inventory) per 08_DATA_MODEL.md §2, which shows both types together deliberately — the relationship between template and instance is the point. Inventory consumes this type; it does not own it. - ItemCategory — first-class, gates manufacturing rights per Legacy/05_TEAMS_JOBS_FACTIONS.md §5. - ItemBehaviour and the library — Edible, Equippable, Container, WeaponAttachment (Milestone 12) — composable capabilities a definition attaches, not inline callbacks. See 09_ITEM_FRAMEWORK.md §2. ItemBehaviour.CreateUseInteraction builds a real Applejack.Interaction.InteractionRequest (Milestone 6) rather than resolving an effect itself -- Edible returns a zero-duration one (instant, matching the legacy source's own lack of a timer), Equippable a genuinely timed one. Both take an IServiceResolver parameter (Milestone 8) -- a behaviour is plain data deserialized from an asset, never constructed by DI, so this is the only way an OnComplete closure can reach a service; Edible's uses it to call the real INeedsService.RestoreAsync. ItemDefinition.CreateUseInteraction picks the first attached behaviour that has one to offer for a plain "use" -- the actual call site is CharacterInventoryComponent.RequestUseItem (Inventories), described below. WeaponAttachment deliberately does not implement CreateUseInteraction at all -- attaching is a two-item action, handled by CharacterInventoryComponent.RequestAttachItem/RequestDetachItem instead. See 09_ITEM_FRAMEWORK.md §2.2 for the full design reasoning. - AttachmentSlotKind, WeaponAttachmentState, WeaponJamState/WeaponFireOutcome, WeaponJamStateSerializer (Milestone 12) — Equippable's new attachment-slot and jam fields/logic. WeaponJamState is plain, engine-agnostic jam state and logic with no live caller yet (no shooting/combat module exists in this codebase) -- see UnitTests/Items/WeaponJamStateTests.cs and 09_ITEM_FRAMEWORK.md §2.2. WeaponAttachmentState nests real attached ItemInstances (mirroring Container's nested inventory) but its serializer lives in Inventories, not here — see that module's README. - ItemDefinition.BatchSize (Milestone 8) — legacy's ITEM.Batch, how many a single /manufacture produces. See "Not responsible for" below for why that command isn't built. - IItemRegistry / ItemRegistry — resolves inheritance once at load (explicit, validated, never falsy-vs-unset — the direct fix for D-04), and validates every definition, failing loudly and naming the asset. - ItemLoadException — the named, load-time failure for an unresolvable parent or an invalid definition. Never a silent empty merge. - ItemsModule — registers IItemRegistry.

Not responsible for. - Item instances and inventory storage — owned by Inventories. ItemDefinition is the shared template; ItemInstance (Inventories') is the per-object state. See 08_DATA_MODEL.md §2. - Actually running the interaction to completion — IInteractionRunner (Interaction module) owns the state machine; CreateUseInteraction only builds the request. The RPC entry point that calls it and passes the result to IInteractionRunner.TryStart is CharacterInventoryComponent.RequestUseItem (Inventories, Milestone 6), following 10_INTERACTION_FRAMEWORK.md §3/§6's pattern. - Contraband and the rest of the original's nine bases beyond Edible/Equippable/ Container — deferred; every Contraband/IllegalGoods/Drugs/Explosives item migrated in Milestone 8 is data-only precisely because this behaviour doesn't exist. See Assets/Items/README.md's per-category disposition table. - The /manufacture command — Legacy/01_FEATURE_INVENTORY.md's own "Not present at all" table already names Crafting as absent, and legacy's own implementation spawns the result at the manufacturer's eye trace, the same missing Transform/raycast binding named repeatedly since Milestone 6. BatchSize (this module) and JobDefinition.CanManufacture (Jobs) are the recipe data, ready for whenever that command exists.

Dependencies. Core (IServiceRegistry, IServiceResolver), Characters (Character), Interaction (InteractionRequest, for ItemBehaviour.CreateUseInteraction), Needs (INeedsService, resolved inside Edible.OnComplete from the IServiceResolver its caller passes in), the S&box engine (GameResource, [Property]) for ItemDefinition and its behaviours. ItemsModule itself declares no GameModule.DependsOn on Needs -- it never resolves the service directly; see Code/Inventories/InventoryModule.cs's own header comment for why that module is the one that declares the edge instead.

Public API. - ItemDefinition (+ CreateUseInteraction), ItemCategory, ItemBehaviour (+ Edible, Equippable, Container, WeaponAttachment). - AttachmentSlotKind, WeaponAttachmentState, WeaponJamState, WeaponFireOutcome (Milestone 12) — see 09_ITEM_FRAMEWORK.md §2.2. - IItemRegistry — Find, Get, All, InCategory. - ItemStateBag — per-instance state, keyed by the state class. - IItemStateRegistry — Register, FindByType, FindById; IItemStateSerializer and its typed base ItemStateSerializer<TState>. How a module (or a plugin) makes its own item state survive a save/load without Inventories knowing the state type exists. See 09_ITEM_FRAMEWORK.md §2.1. - ItemLoadException.

Persistence. None directly — definitions are GameResource assets under Assets/Items/, not SaveDocuments; see 01_PROJECT_LAYOUT.md §3.

Future improvements. - Contraband and the remaining legacy bases, once the systems they need exist: Economy's contraband-income loop, KnockOut/WakeUp (Crime), a lockpicking mechanic, the NPC framework, and a placeable/triggerable world entity for explosives. See Assets/Items/README.md's per-category disposition for exactly which of the 116 migrated items are waiting on which. - Equippable's equip-branch OnComplete is still a no-op -- it needs a weapon-holding/ holster-count service that doesn't exist yet. Edible's own equivalent no-op is fixed (Milestone 8): it now calls the real INeedsService.RestoreAsync via the IServiceResolver parameter ItemBehaviour.CreateUseInteraction gained for exactly this. - WeaponJamState.AttemptFire has no live caller -- it needs a weapon-firing/combat system this project's Roadmap does not currently build (legacy fired through a real Source-engine SWEP). The state and logic are real and unit-tested today; only the "roll on trigger pull" hook point is pending, the same "shape real, wiring pending" precedent as the bullet above. - The /manufacture command, once target-agnostic world-position resolution (Transform/raycast) exists -- see "Not responsible for" above.