Groups
Related references:
Groups are useful when you want to manage multiple objects as a single unit.
A group is also a 3D object, so any capability supported by 3D objects can also be used on a group.
Because it is only a container, a group cannot be seen directly.
In fact, ordinary 3D objects are also a kind of grouping structure. They can also use addChild(), removeChild(), and getChildren().
The main reason to use an explicit group is code readability.
Create a Group
const group = await api.createGroup();
await api.add(group);Attach Objects to a Group
const image = await api.getObject('image');
const model = await api.createGltfModel(glbBuffer);
await api.add(model);
await api.addChild(group, image);
await api.addChild(group, model);After that, changes to the group's position, rotation, or scale affect its children as a whole.
Groups can also be nested under other groups to form a multi-level tree.
Common Use Cases
Treat "Title + Icon + Button" as One Unit
If you add multiple images or models dynamically and want them to move together, groups are very handy.
Temporarily Replace Editor Preset Structure
Some projects do not want to pre-build every hierarchy in the scene editor. In those cases, you can assemble a simple tree at runtime with createGroup().
Query Group Children
const children = await api.getChildren(group);Or search by property:
const child = await api.getChildByProperty(group, 'name', 'title-image');Detach Children
await api.removeChild(group, image);The object is only removed from the group. Like remove(), this does not destroy resources, so you can still call add() or addChild() later.
If you want to remove it completely, call destroyObject() as well.
Recommended Habits
- Give objects clear names before attaching them to a group.
- It is also a good idea to name the group itself for debugging.
- If you need to show or hide a whole cluster together, change the group object first instead of toggling children one by one.