Game Objects API

Spawn and manage reusable Studio-authored entity hierarchies.

A Game Object is a reusable hierarchy of normal ECS entities authored in Pixscape Studio. Use api.gameObjects() to spawn one into the active scene:

GameObjectsAPI gameObjects = api.gameObjects();

Spawn a hierarchy

Use spawn(...) when gameplay cares about the Game Object as one hierarchy and lifecycle unit:

GameObjectInstance enemy =
        api.gameObjects().spawn("Enemy", x, y);

EntityRef root = enemy.root();

GameObjectInstance.exists() reports whether the captured root still exists. despawn() safely schedules removal of the surviving hierarchy and dependent Physics joints; repeated calls after the instance becomes stale do nothing.

Use requireRoot(...) when gameplay primarily wants the root entity:

EntityRef enemy =
        api.gameObjects().requireRoot("Enemy", x, y);

enemy.animation().play("idle");

root(...) is the tolerant counterpart: it returns the spawned real root, which can be an invalid EntityRef if spawning creates no entity. requireRoot(...) throws IllegalStateException in that case.

The position is a world-space offset applied to the real root. Names can use the Game Object name, its .gameobject filename, or the canonical gameobjects/name.gameobject asset ID.

Hierarchy semantics

A Game Object has one real root and zero or more child entities:

• The root owns global world and Universal Layer placement.
• A member’s transform() is local to its parent, not a resolved world transform.
• Members inherit their effective Layer from the top-level root and keep their own local z-index.
• A member cannot change renderOrder().layerIndex(...); move the root when the hierarchy belongs on another Layer.
• Children remain normal editable entities with their own applicable facades and components.
• Physics bodies and joints can belong to the hierarchy.
• Spatial actors can be hierarchy members and retain their own footprints and vertical volumes.

Game Objects remain ECS-backed. They organize ordinary entities; they are not a separate non-ECS object system.

Hierarchy lifecycle

Removing a hierarchy node through EntityRef.remove() removes that node’s surviving descendant subtree. Removing the root therefore removes the surviving Game Object. Physics joints made invalid by removed bodies or source joints are removed as part of the same lifecycle.

Prefer GameObjectInstance.despawn() when application code owns the spawned Game Object as a complete unit. Use child EntityRef.remove() only when gameplay intentionally removes one branch.

Entity handles still follow the normal stable-ID and stale-reference rules described in Entities and EntityRef.

Runtime Availability

A dynamically spawned Game Object must be prepared for the scene. If it is not otherwise part of the scene’s discovered resources, declare it through Runtime Availability before loading the scene.

Spawning is synchronous and requires a loaded project and active scene. Missing or invalid Game Object assets, disabled required scene Physics, or unavailable visual resources fail before the hierarchy is published.