跳转到内容
Estella

预制体

预制体（Prefab） 是存储为 .esprefab 文件的可复用实体模板。你可以在编辑器中从现有实体创建预制体，然后在场景中实例化多个副本。每个实例可以覆盖单独的属性，同时保持与源预制体的关联。

编辑器工作流

创建预制体

  1. 在层级面板中搭建好实体（或实体树）
  2. 右键点击根实体 → Prefab → Save as Prefab…
  3. 在内容浏览器中选择保存位置

也可以直接将实体从层级面板拖拽到内容浏览器的文件夹中。

该实体及其子实体会变为预制体实例 — 关联到保存的 .esprefab 文件。

实例化预制体

将 .esprefab 文件从内容浏览器拖拽到层级面板中，即可创建包含所有原始实体和组件的新实例。

编辑预制体

在内容浏览器中双击 .esprefab 文件进入预制体编辑模式。编辑器会将预制体加载为临时场景，你可以直接修改实体。退出时更改会保存回 .esprefab 文件，当前场景中的所有实例会自动同步更新。

属性覆盖

当你修改预制体实例上的属性时，该属性成为覆盖值（Override）。被覆盖的属性在检查器中会有视觉标记。

  • Apply to Prefab — 将实例的覆盖值写回 .esprefab 文件，并更新所有其他实例
  • Revert Prefab — 丢弃所有覆盖值，将实例恢复为与源预制体一致
  • Unpack Prefab — 移除预制体关联，将实例转为普通实体

通过右键点击预制体根实体 → Prefab 访问这些操作。

运行时 API

使用 Prefabs 资源在系统中加载和实例化预制体，一次调用完成资源加载和实体创建。

import { addStartupSystem, defineSystem, Res, Prefabs } from 'esengine';


addStartupSystem(defineSystem(
    [Res(Prefabs)],
    async (prefabs) => {
        // 支持文件路径或 addressable 地址
        const { root, entities } = await prefabs.instantiate('prefabs/Enemy.esprefab');
    }
));

选项

选项类型说明
baseUrlstring解析资源路径的基础 URL
parentEntity预制体根实体要挂载到的父实体
overridesPrefabOverride[]实例化时应用的属性覆盖

应用覆盖值

通过传入覆盖值在生成时自定义实例：

const { root } = await prefabs.instantiate('prefabs/Enemy.esprefab', {
    parent: parentEntity,
    overrides: [
        {
            prefabEntityId: 1,
            type: 'property',
            componentType: 'Transform',
            propertyName: 'position',
            value: { x: 200, y: 100, z: 0 },
        },
    ],
});

PrefabOverride

字段类型说明
prefabEntityIdnumber预制体内的目标实体 ID
typestring'property' | 'component_added' | 'component_removed' | 'name' | 'visibility'
componentTypestring要修改的组件（用于 property 和 component_removed）
propertyNamestring属性名（用于 property）
valueunknown新值（用于 property、name、visibility）
componentDataobject组件类型和数据（用于 component_added）

InstantiatePrefabResult

字段类型说明
rootEntity实例化后的预制体根实体
entitiesMap<number, Entity>预制体实体 ID 到世界实体的映射

嵌套预制体

预制体可以包含对其他预制体的引用。高层 prefabs.instantiate() API 自动处理嵌套预制体 — 所有引用的预制体会递归加载并展开为单一实体树。对于高级用例，可使用底层 instantiatePrefab() 函数：

import { instantiatePrefab } from 'esengine';


const result = await instantiatePrefab(world, prefab, {
    assetServer: assets,
    assetBaseUrl: 'https://cdn.example.com/game',
    parent: parentEntity,
    overrides: [
        { prefabEntityId: 1, type: 'property', componentType: 'Transform', propertyName: 'position', value: { x: 100, y: 50, z: 0 } },
    ],
});
选项类型说明
assetServerAssetServer用于加载引用资源的资源服务器
assetBaseUrlstring解析资源路径的基础 URL
parentEntity预制体根实体要挂载到的父实体
overridesPrefabOverride[]实例化时应用的属性覆盖

下一步