组件

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

内置组件

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

LocalTransform

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

属性	类型	说明
`position`	Vec3	世界坐标 `{ x, y, z }`
`rotation`	Quat	四元数 `{ w, x, y, z }`
`scale`	Vec3	缩放因子 `{ x, y, z }`

Sprite

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

Camera

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

属性	类型	说明
`projectionType`	number	0 = 透视，1 = 正交
`fov`	number	视角角度（仅透视）
`orthoSize`	number	半高世界单位（仅正交）
`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`	number	缓冲区清除模式：0=无, 1=颜色, 2=深度, 3=两者
`showFrustum`	boolean	在编辑器中显示相机视锥线框

Canvas

渲染表面的显示设置。

属性	类型	说明
`designResolution`	Vec2	设计分辨率 `{ x, y }`
`pixelsPerUnit`	number	每世界单位像素数
`scaleMode`	number	画布缩放模式
`matchWidthOrHeight`	number	宽高匹配平衡
`backgroundColor`	Color	清屏颜色 RGBA

Velocity

运动速度。

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

Parent / Children

场景图的实体层级关系。

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

SpineAnimation

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

BitmapText

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

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

Text

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

属性	类型	说明
`content`	string	文本内容
`fontFamily`	string	字体名称
`fontSize`	number	字号（像素）
`color`	Color	文本颜色 RGBA
`align`	TextAlign	水平对齐方式
`verticalAlign`	TextVerticalAlign	垂直对齐方式

UIRect

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

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

UIMask

将子实体裁剪到父级 UIRect 边界内。需要在同一实体上同时挂载 UIRect 和 LocalTransform。详见 UI 与文本指南。

属性	类型	默认值	说明
`enabled`	boolean	`true`	是否启用裁剪

Interactable

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

属性	类型	默认值	说明
`enabled`	boolean	`true`	是否启用交互

Button

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

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

ScreenSpace

标签组件，将实体标记为屏幕空间 UI 根节点。ScreenSpace 实体的子级通过 UIRect 在屏幕坐标中布局。需要 UIRect 和 LocalTransform。

Name

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

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

物理

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

RigidBody

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

属性	类型	默认值	说明
`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`	仅触发（无物理响应）

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`	仅触发（无物理响应）

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`	仅触发（无物理响应）

自定义组件

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(LocalTransform, Player)],
    (query) => {
        for (const [entity, transform] of query) {
            // 只处理带有 Player 标签的实体
        }
    }
));

运行时创建实体

需要在运行时创建实体时（如子弹、粒子、特效），使用 Commands：

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

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

运行时移除组件

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

下一步

系统 — 操作组件的逻辑
查询 — 按组件查找实体