跳转到内容
ESEngine

场景

场景是实体、组件和父子关系的集合。你可以在 ESEngine 编辑器中可视化地创建场景，场景以 JSON 文件保存。运行时引擎会加载场景并生成所有实体及其配置的组件。

场景结构

场景文件包含：

  • 实体 — 每个实体都有唯一 ID 和名字
  • 组件 — 附加到实体上的数据（变换、精灵、碰撞体等）
  • 层级 — 实体之间的父子关系
{
  "version": "1.0",
  "name": "Level1",
  "entities": [
    {
      "id": 1,
      "name": "Player",
      "parent": null,
      "children": [2],
      "components": [
        { "type": "LocalTransform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
        { "type": "Sprite", "data": { "texture": "player.png", "size": { "x": 32, "y": 32 } } }
      ]
    }
  ]
}

加载场景

在编辑器中，场景会自动加载 — 你只需编写定义组件和系统的脚本。

构建项目后，引擎会自动加载场景、解析所有引用的资源（纹理、材质、Spine），并在没有相机时创建默认相机。你不需要手动处理场景加载。

查找实体

按名字查找

从场景加载的每个实体都会自动获得内置的 Name 组件，包含在编辑器中指定的名字。通过查询 Name 来查找实体：

import { defineSystem, addStartupSystem, Query, Name, LocalTransform } from 'esengine';


addStartupSystem(defineSystem(
    [Query(Name, LocalTransform)],
    (query) => {
        for (const [entity, name, transform] of query) {
            if (name.value === 'Player') {
                // 找到了玩家实体
            }
        }
    }
));

按组件或标签查找

使用 Query 按组件查找实体：

import { defineSystem, addSystem, defineTag, Query, Mut, LocalTransform } from 'esengine';


const Player = defineTag('Player');


addSystem(defineSystem(
    [Query(Mut(LocalTransform), Player)],
    (query) => {
        for (const [entity, transform] of query) {
            // 处理每个玩家
        }
    }
));

遍历层级

使用 Children 组件遍历实体树：

import { defineSystem, addSystem, Query, Children, LocalTransform } from 'esengine';


addSystem(defineSystem(
    [Query(Children, LocalTransform)],
    (query) => {
        for (const [entity, children, transform] of query) {
            // children.entities 包含子实体 ID
        }
    }
));

实体层级

场景实体可以通过父子关系形成树状结构。在编辑器中设置父子关系 — 引擎会自动管理 Parent 和 Children 组件。

当父实体的 LocalTransform 变化时，引擎会通过 WorldTransform 组件将变换传播到所有后代。

动态实体

你可以在运行时使用 Commands 生成和销毁实体：

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


addSystem(defineSystem(
    [Commands],
    (commands) => {
        // 生成一个带组件的新实体
        commands.spawn()
            .insert(LocalTransform, { position: { x: 100, y: 0, z: 0 }, rotation: { w: 1, x: 0, y: 0, z: 0 }, scale: { x: 1, y: 1, z: 1 } })
            .insert(Sprite, { texture: bulletTexture, color: { r: 1, g: 1, b: 1, a: 1 }, size: { x: 8, y: 8 } });


        // 销毁实体
        commands.despawn(entity);
    }
));

场景数据类型

类型字段
SceneDataversion: string, name: string, entities: SceneEntityData[], textureMetadata?: Record<string, TextureMetadata>
SceneEntityDataid: number, name: string, parent: number | null, children: number[], components: SceneComponentData[]
SceneComponentDatatype: string, data: Record<string, unknown>