Item group
An item group is a feature where multiple items have a common owner.
When a player performs an ownership-related action (such as interacting, grabbing, or riding) on one item belonging to the item group, that player becomes the owner of all items in the item group. While the player is grabbing or riding, they remain the owner of the item group. As a result, note that another player will not be able to perform ownership-related actions on any item in the same group during this time.
Creating an item group
An item group consists of one host item and multiple member items. When an item is a host or member item, it is said to belong to the item group.
Only one host item must exist in the item group. You can create a host item in the following ways:
- Attach Item Group Host component to a world-placed item.
- Attach Item Group Host component to a world item template, and use Create Item Gimmick component or ClusterScript.createItem to generate it.
If the host item is deleted, the item group becomes invalid.
Member items are the items in the group that are not the host item. An item group can have multiple member items. You can create member items in the following ways:
- Attach Item Group Member component to a world-placed item and specify a host item.
- The host item can use ClusterScript.createItem with CreateItemOption to generate items as member items.
Limitations
- Craft items cannot be used as host items.
- An item cannot belong to multiple item groups at the same time.
- An item cannot be both a host item and a member item simultaneously.
- If a host item is a world-placed item, it cannot be deleted using Destroy Item Gimmick component.
ClusterScript API
There are ClusterScript APIs available that can be used when items belong to an item group.
- Items in an item group can share states within the group using ClusterScript.groupState. This API is currently in beta.
- The host item can generate member items by specifying options in ClusterScript.createItem. This API is currently in beta.