build-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build an Engine application

构建Engine应用

Read

package.json

and the application entry point before changing its structure. Choose the authoring surface from the code being edited:

read references/react.md for
```
@playcanvas/react
```
imports and JSX;
read references/web-components.md for
```
pc-*
```
elements or
```
@playcanvas/web-components
```
imports;
read references/direct-engine.md for direct
```
playcanvas
```
bootstrap code without a wrapper-owned lifecycle.

Installed dependencies alone are insufficient when a project contains more than one surface. Preserve the surface that owns the current entry point and lifecycle.

在修改应用结构前，请先阅读

package.json

和应用入口文件。根据正在编辑的代码选择对应的创作界面：

若代码包含
```
@playcanvas/react
```
导入和JSX，请阅读references/react.md；
若代码包含
```
pc-*
```
元素或
```
@playcanvas/web-components
```
导入，请阅读references/web-components.md；
若代码为无封装生命周期的直接
```
playcanvas
```
引导代码，请阅读references/direct-engine.md。

当项目包含多个创作界面时，仅依赖已安装的包是不够的。请保留拥有当前入口点和生命周期的创作界面。

Render at an intentional density

按预期密度渲染

PlayCanvas defaults

graphicsDevice.maxPixelRatio

to 1 for predictable fill-rate cost. In a quality-oriented browser app, set it deliberately after the application exists and before its initial automatic resize;

Math.min(window.devicePixelRatio, 2)

is a practical high-DPI starting point. Keep 1 only as a measured performance decision, and resize the canvas again after changing the value.

Verify the real backbuffer in a browser: for automatic resolution,

canvas.width / canvas.clientWidth

and the height ratio should match the chosen pixel ratio. CSS dimensions and a screenshot filepath do not prove rendering density.

For every surface:

verify version-sensitive APIs against installed declarations or source;
keep one owner for application creation, assets, entities, update callbacks, and teardown;
prefer the surface's declarative or lifecycle primitives before reaching into the Engine;
put per-entity and per-frame behavior in an Engine
```
Script
```
when page or view state is not its natural owner;
clamp the per-frame delta before advancing gameplay, timers, physics, or a state clock, so a backgrounded tab or a slow frame cannot inject one large integration step;
clean up external events and resources in the lifecycle that created them.

为了可控的填充率成本，PlayCanvas将

graphicsDevice.maxPixelRatio

默认值设为1。对于注重画质的浏览器应用，请在应用实例化后、首次自动调整大小前手动设置该值；

Math.min(window.devicePixelRatio, 2)

是一个实用的高DPI起始值。仅在经过性能测试后，才考虑将其保留为1，并且修改该值后需再次调整画布大小。

在浏览器中验证实际的后台缓冲区：若使用自动分辨率，

canvas.width / canvas.clientWidth

及高度比例应与所选像素比一致。CSS尺寸和截图路径无法证明渲染密度。

对于所有创作界面：

根据已安装的声明文件或源代码，验证版本敏感的API；
为应用创建、资源、实体、更新回调及销毁流程保留单一所有者；
在直接调用Engine之前，优先使用创作界面的声明式或生命周期原语；
当页面或视图状态并非行为的天然所有者时，将每个实体和每帧的行为放入Engine
```
Script
```
中；
在推进游戏玩法、计时器、物理系统或状态时钟之前，限制每帧的时间增量，避免后台标签页或卡顿帧导致单次集成步长过大；
在创建外部事件和资源的生命周期中清理这些资源。