组件

组件是附加在实体上的数据。在 Estella 中，你在代码中定义组件，然后在场景编辑器中挂载到实体上。

内置组件

内置组件在编辑器中始终可用，由 C++ 后端支持。

Transform

实体的位置、旋转和缩放。

属性	类型	说明
position	Vec3	局部坐标 { x, y, z }
rotation	Quat	四元数 { w, x, y, z }
scale	Vec3	缩放因子 { x, y, z }
worldPosition	Vec3	世界坐标（只读）
worldRotation	Quat	世界旋转（只读）
worldScale	Vec3	世界缩放（只读）

注意

在之前的版本中，LocalTransform 和 WorldTransform 是两个独立组件。现在已统一为单一的 Transform。旧名称仍可作为别名使用，但推荐导入 Transform。

Sprite

2D 精灵渲染。需要 Transform 才能显示。详见精灵指南。

Camera

视图设置。至少需要一个激活的相机才能看到内容。编辑器的默认场景已包含一个。

属性	类型	说明
projectionType	ProjectionType	Orthographic — 使用 ProjectionType.Perspective (0) 或 ProjectionType.Orthographic (1)
fov	number	视角角度（仅透视）
orthoSize	number	半高世界单位（仅正交）。默认：540
nearPlane	number	近裁剪面
farPlane	number	远裁剪面
isActive	boolean	是否用于渲染
aspectRatio	number	相机宽高比
priority	number	渲染顺序 — 低优先级先渲染，高优先级覆盖在上
viewportX	number	视口左边缘（0–1）。默认：0
viewportY	number	视口底边缘（0–1）。默认：0
viewportW	number	视口宽度（0–1）。默认：1
viewportH	number	视口高度（0–1）。默认：1
clearFlags	ClearFlags	ClearFlags.ColorAndDepth (3) — None (0)、ColorOnly (1)、DepthOnly (2)、ColorAndDepth (3)
showFrustum	boolean	在编辑器中显示相机视锥线框

Canvas

渲染表面的显示设置。

属性	类型	说明
designResolution	Vec2	设计分辨率 { x, y }
pixelsPerUnit	number	每世界单位像素数
scaleMode	ScaleMode	ScaleMode.FixedHeight (1) — FixedWidth (0)、FixedHeight (1)、Expand (2)、Shrink (3)、Match (4)
matchWidthOrHeight	number	宽高匹配平衡
backgroundColor	Color	清屏颜色 RGBA

Velocity

运动速度。

属性	类型	说明
linear	Vec3	线速度
angular	Vec3	角速度

Parent / Children

场景图的实体层级关系。

组件	属性	类型	说明
Parent	entity	Entity	父实体 ID
Children	entities	Entity[]	子实体 ID 列表

SpineAnimation

Spine 骨骼动画播放。需要 Transform。详见 Spine 动画指南。

BitmapText

使用预烘焙位图字体图集（BMFont 格式）进行 GPU 渲染的文本。需要 Transform。详见位图文本指南。

属性	类型	说明
text	string	文本内容
color	Color	着色 RGBA
fontSize	number	相对于字体原始大小的缩放因子
align	number	水平对齐：0=左对齐，1=居中，2=右对齐
spacing	number	字符间额外间距
layer	number	渲染层级
font	number	assets.loadBitmapFont() 返回的字体句柄
enabled	boolean	是否渲染该组件

Text

UI 文本渲染。配合 UIRect 和 Sprite 组件显示文本。详见文本与图片。

属性	类型	说明
content	string	文本内容
fontFamily	string	字体名称
fontSize	number	字号（像素）
color	Color	文本颜色 RGBA
align	TextAlign	水平对齐方式
verticalAlign	TextVerticalAlign	垂直对齐方式
wordWrap	boolean	是否启用自动换行
overflow	TextOverflow	溢出行为：Visible (0)、Clip (1)、Ellipsis (2)
lineHeight	number	行高倍率

UIRect

UI 布局矩形。定义 UI 元素的锚点布局。

属性	类型	说明
anchorMin	Vec2	左下锚点（0–1）
anchorMax	Vec2	右上锚点（0–1）
offsetMin	Vec2	相对 anchorMin 的像素偏移
offsetMax	Vec2	相对 anchorMax 的像素偏移
size	Vec2	宽高
pivot	Vec2	旋转中心点

UIMask

将子实体裁剪到父级 UIRect 边界内。需要在同一实体上同时挂载 UIRect 和 Transform。详见遮罩与安全区。

属性	类型	默认值	说明
enabled	boolean	true	是否启用裁剪
mode	number	0	遮罩模式：0=Scissor，1=Stencil

Interactable

将 UI 元素标记为可交互（接收指针事件）。需要 UIRect。

属性	类型	默认值	说明
enabled	boolean	true	是否启用交互
blockRaycast	boolean	true	阻止事件传递到后面的元素
raycastTarget	boolean	true	是否参与射线检测

Button

UI 元素的按钮行为。需要 Interactable 和 UIRect。

属性	类型	默认值	说明
state	number	0（Normal）	0=正常, 1=悬停, 2=按下, 3=禁用
transition	ButtonTransition | null	null	各状态的颜色过渡

Name

实体的字符串标识符，用于在运行时按名称查找实体。

属性	类型	默认值	说明
value	string	''	实体名称

物理

物理组件需要 PhysicsPlugin。详见物理指南。

RigidBody

附加到实体的物理刚体。需要 Transform。

属性	类型	默认值	说明
bodyType	number	2（Dynamic）	0=静态，1=运动学，2=动态
gravityScale	number	1.0	重力倍率
linearDamping	number	0.0	线速度阻尼
angularDamping	number	0.0	角速度阻尼
fixedRotation	boolean	false	锁定旋转
bullet	boolean	false	高速物体连续碰撞检测
enabled	boolean	true	启用物理刚体

BoxCollider

属性	类型	默认值	说明
halfExtents	Vec2	{x: 0.5, y: 0.5}	半尺寸（米）
offset	Vec2	{x: 0, y: 0}	局部偏移
density	number	1.0	质量密度
friction	number	0.3	表面摩擦力
restitution	number	0.0	弹性（弹力）
isSensor	boolean	false	仅触发（无物理响应）
enabled	boolean	true	启用碰撞体

CircleCollider

属性	类型	默认值	说明
radius	number	0.5	圆形半径（米）
offset	Vec2	{x: 0, y: 0}	局部偏移
density	number	1.0	质量密度
friction	number	0.3	表面摩擦力
restitution	number	0.0	弹性（弹力）
isSensor	boolean	false	仅触发（无物理响应）
enabled	boolean	true	启用碰撞体

CapsuleCollider

属性	类型	默认值	说明
radius	number	0.25	胶囊半径
halfHeight	number	0.5	胶囊体半高
offset	Vec2	{x: 0, y: 0}	局部偏移
density	number	1.0	质量密度
friction	number	0.3	表面摩擦力
restitution	number	0.0	弹性（弹力）
isSensor	boolean	false	仅触发（无物理响应）
enabled	boolean	true	启用碰撞体

组件启用开关

定义中包含 enabled 属性的组件会在 Inspector 的组件标题栏显示一个复选框。取消勾选会将 enabled 设为 false，对应的系统可以据此跳过处理。

这适用于内置组件（如 Interactable、UIMask、RigidBody），也适用于任何包含 enabled 字段的自定义组件：

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

禁用时，Inspector 中的组件标题栏会变暗显示。

自定义组件

defineComponent

在代码中定义数据组件。保存后会出现在编辑器的”添加组件”菜单中。

import { defineComponent } from 'esengine';

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

在编辑器中：选择实体 → 添加组件 → Health → 在检查器中设置值。

系统查询拥有该组件的实体：

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) {
                // 处理死亡
            }
        }
    }
));

defineTag

标签组件没有数据 — 纯粹用于筛选实体。

import { defineTag } from 'esengine';

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

在编辑器中将 Player 挂载到实体上，然后查询它：

addSystem(defineSystem(
    [Query(Transform, Player)],
    (query) => {
        for (const [entity, transform] of query) {
            // 只处理带有 Player 标签的实体
        }
    }
));

警告

自定义组件仅存储在 TypeScript 中。内置组件与 C++ 后端同步用于渲染。

运行时创建实体

需要在运行时创建实体时（如子弹、粒子、特效），使用 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();
    }
));

运行时移除组件

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

下一步

• 系统 — 操作组件的逻辑
• 查询 — 按组件查找实体
• 变更检测 — 响应组件变更