Components

Components are data attached to entities. In Estella, you define components in code and attach them to entities in the scene editor.

Builtin Components

Builtin components are always available in the editor. They are backed by the C++ backend.

Transform

Position, rotation, and scale of an entity.

Property	Type	Description
position	Vec3	Local position { x, y, z }
rotation	Quat	Quaternion { w, x, y, z }
scale	Vec3	Scale factor { x, y, z }
worldPosition	Vec3	Computed world position (read-only)
worldRotation	Quat	Computed world rotation (read-only)
worldScale	Vec3	Computed world scale (read-only)

Note

In previous versions, LocalTransform and WorldTransform were separate components. They have been unified into a single Transform. The old names still work as aliases but Transform is the recommended import.

Sprite

2D sprite rendering. Requires Transform to be visible. See Sprite guide for full details.

Camera

View settings. At least one active camera is required to see anything. The editor’s default scene includes one.

Property	Type	Description
projectionType	ProjectionType	Orthographic — use ProjectionType.Perspective (0) or ProjectionType.Orthographic (1)
fov	number	Field of view in degrees (perspective only)
orthoSize	number	Half-height in world units (orthographic only). Default: 540
nearPlane	number	Near clipping plane
farPlane	number	Far clipping plane
isActive	boolean	Whether this camera is used for rendering
aspectRatio	number	Camera aspect ratio
priority	number	Render order — lower priority renders first, higher renders on top
viewportX	number	Viewport left edge (0–1). Default: 0
viewportY	number	Viewport bottom edge (0–1). Default: 0
viewportW	number	Viewport width (0–1). Default: 1
viewportH	number	Viewport height (0–1). Default: 1
clearFlags	ClearFlags	ClearFlags.ColorAndDepth (3) — None (0), ColorOnly (1), DepthOnly (2), ColorAndDepth (3)
showFrustum	boolean	Draw the camera frustum wireframe in the editor

Canvas

Display settings for the rendering surface.

Property	Type	Description
designResolution	Vec2	Design resolution { x, y }
pixelsPerUnit	number	Pixels per world unit
scaleMode	ScaleMode	ScaleMode.FixedHeight (1) — FixedWidth (0), FixedHeight (1), Expand (2), Shrink (3), Match (4)
matchWidthOrHeight	number	Balance between width/height matching
backgroundColor	Color	Clear color RGBA

Velocity

Movement velocity.

Property	Type	Description
linear	Vec3	Linear velocity
angular	Vec3	Angular velocity

Parent / Children

Entity hierarchy for scene graphs.

Component	Property	Type	Description
Parent	entity	Entity	Parent entity ID
Children	entities	Entity[]	List of child entity IDs

SpineAnimation

Spine skeletal animation playback. Requires Transform. See Spine Animation guide for full details.

BitmapText

GPU-rendered text using pre-baked bitmap font atlases (BMFont format). Requires Transform. See Bitmap Text guide for full details.

Property	Type	Description
text	string	Text content
color	Color	Tint color RGBA
fontSize	number	Scale factor relative to the font’s native size
align	number	Horizontal alignment: 0=Left, 1=Center, 2=Right
spacing	number	Extra spacing between characters
layer	number	Render layer
font	number	Font handle from assets.loadBitmapFont()
enabled	boolean	Whether this text is rendered

Text

UI text rendering. Works with UIRect and Sprite to display text. See Text & Image for full details.

Property	Type	Description
content	string	Text content
fontFamily	string	Font family
fontSize	number	Font size in pixels
color	Color	Text color RGBA
align	TextAlign	Horizontal alignment
verticalAlign	TextVerticalAlign	Vertical alignment
wordWrap	boolean	Enable word wrapping
overflow	TextOverflow	Overflow behavior: Visible (0), Clip (1), Ellipsis (2)
lineHeight	number	Line height multiplier

UIRect

UI layout rectangle. Defines anchored layout for UI elements.

Property	Type	Description
anchorMin	Vec2	Lower-left anchor (0–1)
anchorMax	Vec2	Upper-right anchor (0–1)
offsetMin	Vec2	Pixel offset from anchorMin
offsetMax	Vec2	Pixel offset from anchorMax
size	Vec2	Width and height
pivot	Vec2	Pivot point for rotation

UIMask

Clips child entities to the parent’s UIRect bounds. Requires UIRect and Transform on the same entity. See Masking & SafeArea for details.

Property	Type	Default	Description
enabled	boolean	true	Whether clipping is active
mode	number	0	Masking technique: 0=Scissor, 1=Stencil

Interactable

Marks a UI element as interactive (receives pointer events). Requires UIRect.

Property	Type	Default	Description
enabled	boolean	true	Whether interaction is active
blockRaycast	boolean	true	Block raycast from reaching entities behind
raycastTarget	boolean	true	Whether this entity is a valid raycast hit target

Button

Button behavior for UI elements. Requires Interactable and UIRect.

Property	Type	Default	Description
state	number	0 (Normal)	0=Normal, 1=Hovered, 2=Pressed, 3=Disabled
transition	ButtonTransition | null	null	Color transition for each state

Name

A string identifier for the entity. Useful for finding entities by name at runtime.

Property	Type	Default	Description
value	string	''	Entity name

Physics

Physics components require the PhysicsPlugin. See Physics guide for setup and usage.

RigidBody

Physics body attached to an entity. Requires Transform.

Property	Type	Default	Description
bodyType	number	2 (Dynamic)	0=Static, 1=Kinematic, 2=Dynamic
gravityScale	number	1.0	Gravity multiplier
linearDamping	number	0.0	Linear velocity damping
angularDamping	number	0.0	Angular velocity damping
fixedRotation	boolean	false	Lock rotation
bullet	boolean	false	Continuous collision detection for fast objects
enabled	boolean	true	Enable physics body

BoxCollider

Property	Type	Default	Description
halfExtents	Vec2	{x: 0.5, y: 0.5}	Half size in meters
offset	Vec2	{x: 0, y: 0}	Local offset
density	number	1.0	Mass density
friction	number	0.3	Surface friction
restitution	number	0.0	Bounciness
isSensor	boolean	false	Trigger-only (no physical response)
enabled	boolean	true	Enable this collider

CircleCollider

Property	Type	Default	Description
radius	number	0.5	Circle radius in meters
offset	Vec2	{x: 0, y: 0}	Local offset
density	number	1.0	Mass density
friction	number	0.3	Surface friction
restitution	number	0.0	Bounciness
isSensor	boolean	false	Trigger-only (no physical response)
enabled	boolean	true	Enable this collider

CapsuleCollider

Property	Type	Default	Description
radius	number	0.25	Capsule radius
halfHeight	number	0.5	Half height of the capsule body
offset	Vec2	{x: 0, y: 0}	Local offset
density	number	1.0	Mass density
friction	number	0.3	Surface friction
restitution	number	0.0	Bounciness
isSensor	boolean	false	Trigger-only (no physical response)
enabled	boolean	true	Enable this collider

Component Enabled Toggle

Components that have an enabled property in their definition display a checkbox in the Inspector header. Unchecking it sets enabled to false, which the corresponding system can use to skip processing.

This applies to builtin components like Interactable, UIMask, and RigidBody, as well as any custom component that includes an enabled field:

const MyComponent = defineComponent('MyComponent', {
    enabled: true,
    speed: 100,
});

When disabled, the component header in the Inspector is visually dimmed.

Custom Components

defineComponent

Define a data component in code. After saving, it appears in the editor’s “Add Component” menu.

import { defineComponent } from 'esengine';

export const Health = defineComponent('Health', {
    current: 100,
    max: 100
});

Then in the editor: select an entity → Add Component → Health → set values in the inspector.

Systems query entities with this component:

import { defineSystem, addSystem, Query } from 'esengine';
import { Health } from './components/Health';

addSystem(defineSystem(
    [Query(Health)],
    (query) => {
        for (const [entity, health] of query) {
            if (health.current <= 0) {
                // handle death
            }
        }
    }
));

defineTag

A tag component has no data — it’s used purely for filtering entities.

import { defineTag } from 'esengine';

export const Player = defineTag('Player');
export const Enemy = defineTag('Enemy');

Attach Player to an entity in the editor, then query it:

addSystem(defineSystem(
    [Query(Transform, Player)],
    (query) => {
        for (const [entity, transform] of query) {
            // only processes entities with the Player tag
        }
    }
));

Caution

Custom components are stored in TypeScript only. Builtin components are synced with the C++ backend for rendering.

Runtime Entity Spawning

For entities created at runtime (bullets, particles, effects), use Commands:

import { addStartupSystem, defineSystem, Commands, Sprite, Transform } from 'esengine';

addStartupSystem(defineSystem(
    [Commands()],
    (cmds) => {
        const entity = cmds.spawn()
            .insert(Sprite, { size: { x: 10, y: 10 } })
            .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
            .id();
    }
));

Removing Components at Runtime

cmds.entity(entity).remove(Velocity);

Next Steps

• Systems — logic that operates on components
• Queries — finding entities by component
• Change Detection — reacting to component changes