Develop

Entity

Updated: Jul 22, 2026

An Entity is a lightweight container for Components. In IWSDK, Entities may also carry a Three.js object3D.

Creating Entities

const e = world.createEntity();
const t = world.createTransformEntity(); // adds an Object3D and a Transform component

Parenting options:

const child = world.createTransformEntity(undefined, { parent: t });
const persistent = world.createTransformEntity(undefined, { persistent: true }); // parented under scene

Object3D Attachment

import { Mesh, BoxGeometry, MeshStandardMaterial } from '@iwsdk/core';

const geometry = new BoxGeometry(1, 1, 1);
const material = new MeshStandardMaterial({ color: 0x00ff00 });
const mesh = new Mesh(geometry, material);

const entity = world.createTransformEntity(mesh);

createTransformEntity is the recommended way to attach Three.js objects to entities. It ensures object3D is properly managed and detached when the entity is released.

Component Operations

e.addComponent(Health, { current: 100 });
e.removeComponent(Health);
e.has(Health); // boolean

Reading and Writing Data (in Systems)

const v = e.getValue(Health, 'current'); // number | undefined
e.setValue(Health, 'current', 75);

// For vector fields (Types.Vec3) use a typed view:
const pos = e.getVectorView(Transform, 'position'); // Float32Array
pos[1] += 1; // move up

Destroying Entities

IWSDK provides two ways to destroy entities:

`entity.destroy()`

Removes the entity from the ECS and detaches its object3D from the scene graph:

entity.destroy();

This is safe and non-destructive to GPU resources. The geometry, materials, and textures remain in GPU memory and can be reused by other entities.

`entity.dispose()`

Destroys the entity AND disposes all GPU resources (geometry, materials, textures):

entity.dispose();

Warning

**Use with caution!** `dispose()` is destructive and will free GPU memory for: - All geometries attached to the entity's `object3D` and its children. - All materials (including shared materials). - All textures referenced by those materials. If other entities share the same geometry, material, or texture, they will break after calling `dispose()`.

When to use each

Scenario	Method
Removing an entity that uses shared/reusable assets	`destroy()`
Removing an entity with unique, one-off geometry/materials	`dispose()`
Level unloading with asset reuse	`destroy()`
Full cleanup of procedurally generated content	`dispose()`

Example: Safe cleanup pattern

// If you created unique resources, dispose them
const geometry = new BoxGeometry(1, 1, 1);
const material = new MeshStandardMaterial({ color: 0xff0000 });
const mesh = new Mesh(geometry, material);
const entity = world.createTransformEntity(mesh);

// Later: full cleanup since resources aren't shared
entity.dispose();

// If using loaded/shared assets, just destroy
const gltf = await AssetManager.loadGLTF('model.glb');
const entity = world.createTransformEntity(gltf.scene.clone());

// Later: don't dispose - other entities may use the same materials
entity.destroy();

See ECS concepts for related component, query, and system guidance.