mirror of
https://github.com/galacean/engine.git
synced 2026-05-22 17:00:49 +08:00
98 lines
4.8 KiB
Plaintext
98 lines
4.8 KiB
Plaintext
---
|
|
order: 10
|
|
title: Prefab
|
|
type: Core Concept
|
|
label: Core
|
|
---
|
|
|
|
## Introduction
|
|
|
|
Prefabs are assets that can be considered as templates storing **[entities](/en/docs/core/entity)** (including their child entities and components) data. Prefabs allow developers to create and update this template, which can then be instantiated into the scene as needed.
|
|
|
|
If you want to reuse entities configured in a specific way across multiple locations in a scene or multiple scenes in a project, such as non-player characters (NPCs), props, or landscapes, you should convert this game object into a prefab. This approach is better than simply copying and pasting game objects because prefabs can keep all copies synchronized.
|
|
|
|
### Main Features of Prefabs:
|
|
|
|
#### Reusability:
|
|
The same prefab can be used in multiple scenes, and any modifications to the prefab can be automatically applied to all instances.
|
|
|
|
#### Easy Management:
|
|
Prefabs can package complex entities (including their child entities and components) into a single asset, making them easy to manage and organize.
|
|
|
|
#### Consistency:
|
|
By using prefabs, you can ensure that objects used in different scenes or different parts maintain consistency.
|
|
|
|
#### Increased Efficiency:
|
|
Extensive use of prefabs can reduce repetitive work, making the development process more efficient.
|
|
|
|
## Editor Usage
|
|
|
|
### Creating a Prefab
|
|
|
|
There are two ways to create a prefab:
|
|
|
|
1. Right-click an entity to create a prefab using this entity as a template.
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*1D-6TpXqDWcAAAAAAAAAAAAADsJ_AQ/original" />
|
|
2. Drag the entity from the **[Hierarchy Panel](/en/docs/interface/hierarchy)** to the **[Asset Panel](/en/docs/assets/interface)** to create a prefab using this entity as a template.
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*IXI9Q4ljEu8AAAAAAAAAAAAADsJ_AQ/original" />
|
|
|
|
### Updating a Prefab
|
|
|
|
There are two ways to update a prefab:
|
|
|
|
#### Global Replacement
|
|
|
|
Drag the entity from the **Hierarchy Panel** onto an existing prefab asset in the **Asset Panel**. The prefab asset will be updated with the new content, and all instances created from this prefab will also be updated with the latest content.
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*o0WAR77vPbIAAAAAAAAAAAAADsJ_AQ/original" />
|
|
|
|
The entity can also be an instance of this prefab.
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*A0TpTZs7i3EAAAAAAAAAAAAADsJ_AQ/original" />
|
|
|
|
#### Apply Instance Modifications
|
|
|
|
Instances of a prefab are generated based on the prefab template. All instances will change as the template changes, but each instance may have its own modifications: addition, deletion, or updates of child entities and components. To make the modifications of an instance part of the template, you can do the following:
|
|
|
|
1. Add child nodes
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*mnm8SIA8MXIAAAAAAAAAAAAADsJ_AQ/original" />
|
|
|
|
2. Delete child nodes
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*AN5YQpYSoNsAAAAAAAAAAAAADsJ_AQ/original" />
|
|
|
|
3. Modify child nodes
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*CoZKT4O9mzMAAAAAAAAAAAAADsJ_AQ/original" />
|
|
|
|
4. Add components
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*XFz3TrsJjBoAAAAAAAAAAAAADsJ_AQ/original" />
|
|
|
|
5. Update components
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*mM2dS70ZR7cAAAAAAAAAAAAADsJ_AQ/original" />
|
|
|
|
6. Delete components
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*WC8ZTIv5MK4AAAAAAAAAAAAADsJ_AQ/original" />
|
|
|
|
### Unlink Prefab Instance
|
|
|
|
If you want a prefab instance to disconnect from the prefab so that it no longer changes with the prefab, you can unlink the prefab instance.
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*vtpERpaqb_AAAAAAAAAAAAAADsJ_AQ/original" />
|
|
|
|
### Deleting a Prefab
|
|
|
|
A prefab is an asset, and it can be deleted just like other assets. Note that when a prefab is deleted, there are two ways to handle its instances:
|
|
|
|
1. Delete all prefab instances
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*EJEGSZMi7ZAAAAAAAAAAAAAADsJ_AQ/original" />
|
|
2. Unlink all prefab instances
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*54i3QYBUsaQAAAAAAAAAAAAADsJ_AQ/original" />
|
|
|
|
## Script Usage
|
|
|
|
### Loading a Prefab
|
|
The engine object of a prefab asset is [PrefabResource](/apis/loader/#PrefabResource}). After loading a prefab ([Asset Loading](/en/docs/assets/load)), you can instantiate it using the [instantiate](/apis/loader/#PrefabResource-instantiate}) method.
|
|
|
|
```typescript
|
|
engine.resourceManager
|
|
.load({ url: "Prefab's URL", type: AssetType.Prefab })
|
|
.then((prefab: PrefabResource) => {
|
|
const prefabInstanceEntity = prefab.instantiate();
|
|
scene.addRootEntity(prefabInstanceEntity);
|
|
}); |