Guide4 min read3 sections

Equipment and animated attachments

docs/EQUIPMENT.mdSource updated 2026-10-24
Markdown
On this page 3 sections

The development player can carry or stow an owned item while keeping it in inventory. The isolated garden-ferry.4 preview includes a traveling lantern on a low stand beside the eastern landing. Take it with the interaction key, open the satchel, and select Carry lantern. Other travelers see its warm glass and flame attached to the animated right hand. Stowing removes the attachment and preserves the item.

#Authored definitions and state

A format-4 pickup can declare equipment: {slot, attachment, name}. The slot and attachment are game-defined IDs; the name is display text. Equipment pickup IDs are unique across the world. The catalog has at most 64 definitions. The independent games/engine-zoo/equipment.ts fixture defines a compass and scanner sharing a hand slot.

equipped is an optional array of owned pickup IDs in shared state and local player saves. A traveler can use up to four slots, with one item per slot and no duplicate attachment binding. Equipping another item in a slot replaces its previous selection atomically. It does not transfer, duplicate or consume the item. The local saved array contains only the local traveler's selections; shared state additionally uses the existing item-owner map. Invalid or unowned selections are rejected. Full native checkpoints preserve the same state; older saves without the optional field stay valid.

Room protocol 4 adds a boolean equipment field to interaction intents. The action ID names the item and the boolean specifies carry or stow, avoiding a retry-sensitive toggle. Equipment requests have the existing intent IDs, expected shared revision, authority epoch, durable receipts and retry path. The elected browser validates ownership and slots. Equipment does not require standing near the original pickup. Requests cannot combine equipment with prop or conversation operations. This remains the trusted cooperative authority model; trusted server simulation is still a separate roadmap requirement.

A handoff, reconnect or relay restart restores the accepted selection. The existing 30-second absent-owner item return also removes equipment for returned items. No inventory is created from pose packets or client-supplied attachment names. Old protocol 1–3 clients must reload a matching build.

#Canonical presentation and art binding

The simulation derives attachment IDs from accepted equipment and projects them through RemoteActor@3. Version-one and version-two descriptors migrate without inventing equipment. Equipment changes can update a stationary actor without a new motion sample. Remote actor removal also removes its equipment; local checkpoints do not retain departed session actors.

Presentation format 7 adds optional actor attachments. Older formats remain readable. Full actor snapshots and deltas update equipment; motion-only packets retain it. Snapshot and profile data are copied at their ownership boundaries.

ActorRigOptions.attachments maps an attachment ID to an imported model node and a bounded set of primitive objects. The rig validates node availability, transforms, materials and the existing 25-instance actor budget before installation. Each frame composes the animated socket transform, local prop transform and actor placement. Stowing removes the prop instances. These attachments use existing primitive meshes and add no skin palettes or GPU mesh buffers.

Darkwind supplies its eleven-part lantern geometry and right-hand socket in game files. The engine imports no Darkwind item IDs or art. Character mesh and animations remain unchanged, pending the user-requested final redesign.

#Verification and limits

tests/equipment.test.ts covers ownership, slot replacement, invalid data, independent game content, local saves, native checkpoints, stationary canonical actors, versioned presentation, animated sockets and real relay restart/handoff. The two-browser garden journey picks up and equips the lantern, observes it while walking, changes host, reloads, admits a new observer and stows/re-equips it. Acceptance records commands and results; the rendered lantern is an actual client capture.

The initial attachment catalog supports up to four bindings, with at most twelve primitive parts per binding and twenty-five total character/attachment instances. Imported equipment meshes, first-person held models, item-driven dynamic point lights, equipment collision, trading, persistent accounts and trusted server authority remain open. The lantern is emissive; it does not yet illuminate nearby surfaces as a moving point light. This is one completed equipment path, not the full gameplay-systems milestone.

End of Equipment