API Entity Inventories and Relationships

Entity inventories and relationships

Lua API / Entities / Entity inventories and relationships

Props and living entities can opt into saved inventories, logical equipment, ownership, teams, and a native single-passenger mount.

Inventories and logical equipment

Props and living entities can declare a saved native container. size is required and must be 9-54 slots in rows of nine. title defaults to displayName; openOnInteract defaults to true. When interaction returns "pass" or nil, an enabled container opens for the player. Returning "handled" or "deny" suppresses that automatic opening.

inventory = {
    size = 27,
    title = "Supply Drone",
    openOnInteract = true,
    dropOnDeath = true
}

Inventory slots are one-based. getInventoryStack(slot) returns a detached { id, count, damage } or nil. setInventoryStack(slot, stack) accepts an item reference, item ID, or stack table and accepts nil to clear. removeInventoryStack(slot, count) returns the removed detached stack. getInventorySize() returns the declared size. openInventory(player) explicitly opens the container for a player in the same world and within 8 blocks. Capability methods return nil or false when unavailable. Changing an existing type's inventory size on reload is rejected so saved slots cannot be silently reassigned.

equipment supplies saved logical slots: "hand", "head", "chest", "legs", and "feet". Omit slots to enable all five. Use getEquipmentStack(slot) and setEquipmentStack(slot, stack); passing nil clears a slot. These stacks do not automatically render, add armor, or change attacks. Scripts can inspect them from gameplay callbacks and decide their effects. Changing the enabled slot set on reload is rejected.

Both capabilities accept dropOnDeath = true. Configured contents are dropped and cleared before onDeath or by an explicit dropLoot() call; other content remains saved. Repeated dropLoot() calls can drop contents added since the previous call.

Ownership and teams

Props and living entities can declare relations = { ownership = true }, a default namespaced team, or both. Owners and per-instance team overrides are saved.

Method	Result
getOwner()	Loaded owner handle, or nil. On projectiles this remains the launch owner.
getOwnerIdentity()	Stable player:<name> or entity:<identity> token, even when the owner is unloaded.
setOwner(owner)	Save a player or BetaMoon entity owner; pass nil to clear.
getTeam()	Current namespaced team key, or nil.
setTeam(team)	Set an instance override; pass nil to restore the declaration default.
isAlliedWith(other)	True for self, the direct owner, matching non-empty teams, or two entities with the same owner.

Persistent relations.ownership accepts players and BetaMoon entities. Native and modded non-player entities cannot be stored as persistent relationship owners. A BetaMoon entity owner resolves only while that instance is loaded; use getOwnerIdentity() when the stable relationship matters across chunks. Projectile launch attribution can separately use any loaded entity for that projectile's lifetime.

Mounts and passengers

mount enables a native single seat on a prop or living entity. passengerOffset defaults to 75 percent of entity height and accepts -16-16 blocks. allowPlayers defaults to true and allowEntities to false; at least one must be enabled.

addPassenger(passenger) mounts one allowed, live passenger when both entities are in the same world and neither is already involved in an incompatible riding relationship. Cycles are rejected. removePassenger() clears the seat. Every entity handle can inspect getPassenger() and getVehicle() and call dismount().

Riding supports one passenger and is transient across save/load.