Back to Details

find-examples

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Official examples

官方示例

Use official examples as version-matched recipes. Engine and Web Components examples are standalone applications to adapt, not modules to import.
Use the 
reuse-scripts
skill instead when the installed Engine ships a production script for the required behavior.
将官方示例视为版本匹配的参考方案。Engine和Web Components示例是可适配的独立应用，而非可导入的模块。
当已安装的Engine提供了对应功能的生产脚本时，请改用
reuse-scripts
技能。

Find the matching example

查找匹配的示例

When 
node_modules/playcanvas
is a local source checkout or linked build — a symlink, a workspace, or a path dependency — its 
examples/src/examples/**
are already on disk. Read them directly and skip the GitHub fetch below. A linked engine can sit ahead of any published tag, and a pre-release version (
-alpha
, 
-beta
) may have no matching public tree, so the on-disk source is the ground truth. Fall back to GitHub only when the examples are absent locally; the published npm package omits 
examples/
.
sh
ls node_modules/playcanvas/examples/src/examples 2>/dev/null && echo "linked engine: read local examples, skip the fetch"
Search the active surface's own catalog first, then the Engine catalog. Engine examples are the largest set and port to every surface; the per-surface catalogs are smaller but need no translation.
SurfaceRepositoryPackageRefExample paths
direct Engine
playcanvas/engine
playcanvas
v<version>
examples/src/examples/<category>/<name>.example.mjs
Web Components
playcanvas/web-components
@playcanvas/web-components
v<version>
examples/<name>.html
React
playcanvas/developer-site
@playcanvas/react
main
docs/user-manual/react/examples/<name>.mdx
Resolve the installed version instead of assuming the newest API:
sh
PKG=playcanvas # or @playcanvas/web-components
TAG="v$(node -p "JSON.parse(require('fs').readFileSync('node_modules/$PKG/package.json')).version")" || exit 1
gh api "repos/playcanvas/engine/git/trees/$TAG?recursive=1" \
  | grep -o '"examples/src/examples/[^"]*\.example\.mjs"'
Read the resolved package rather than the dependency list; 
playcanvas
is often a transitive dependency of 
@playcanvas/react
or 
@playcanvas/web-components
. Stop on a failed read instead of requesting an invalid tag: an unresolved version produces an empty example list, not an error. When the package is not below the project root's 
node_modules
, run the command from the workspace that depends on it.
List a different surface by substituting its repository and path pattern, such as 
'"examples/[^"]*\.html"'
for Web Components. Fetch a candidate from the same ref:
sh
gh api "repos/playcanvas/engine/contents/examples/src/examples/<category>/<name>.example.mjs?ref=$TAG" \
  --jq .content | base64 --decode
Use 
main
only when the installed version has no tag. It may contain unsupported APIs. Example asset URLs refer to 
examples/assets/
; fetch assets from the same ref or substitute project assets.
The React catalog is documentation rather than a tagged release: it is small, tracks the latest package, and its snippets are page fragments. Verify every prop and hook it uses against the installed 
@playcanvas/react
declarations, and port an Engine example when no React example covers the feature.
当
node_modules/playcanvas
是本地源码检出或链接构建（符号链接、工作区或路径依赖）时，其
examples/src/examples/**
目录已存在于本地磁盘。直接读取这些文件，跳过下方的GitHub获取步骤。链接的Engine版本可能领先于已发布的标签，且预发布版本（
-alpha
、
-beta
）可能没有对应的公开代码树，因此本地磁盘中的源码是最准确的参考。仅当本地无示例文件时才回退到GitHub获取；已发布的npm包不包含
examples/
目录。
sh
ls node_modules/playcanvas/examples/src/examples 2>/dev/null && echo "linked engine: read local examples, skip the fetch"
优先搜索当前使用的Surface自身的示例目录，再搜索Engine的示例目录。Engine示例数量最多，可适配到所有Surface；各Surface专属的示例目录规模较小，但无需转换即可直接使用。
SurfaceRepositoryPackageRefExample paths
direct Engine
playcanvas/engine
playcanvas
v<version>
examples/src/examples/<category>/<name>.example.mjs
Web Components
playcanvas/web-components
@playcanvas/web-components
v<version>
examples/<name>.html
React
playcanvas/developer-site
@playcanvas/react
main
docs/user-manual/react/examples/<name>.mdx
请获取已安装的版本，而非默认使用最新API：
sh
PKG=playcanvas # or @playcanvas/web-components
TAG="v$(node -p "JSON.parse(require('fs').readFileSync('node_modules/$PKG/package.json')).version")" || exit 1
gh api "repos/playcanvas/engine/git/trees/$TAG?recursive=1" \
  | grep -o '"examples/src/examples/[^"]*\.example\.mjs"'
请读取已解析的包文件，而非依赖列表；
playcanvas
通常是
@playcanvas/react
或
@playcanvas/web-components
的间接依赖。若读取失败则停止操作，不要请求无效的标签：未解析的版本会返回空的示例列表，而非错误。如果该包不在项目根目录的
node_modules
下，请在依赖它的工作区中运行该命令。
若要列出其他Surface的示例，请替换对应的仓库和路径模式，例如Web Components使用
'"examples/[^"]*\.html"'
。从同一引用中获取候选示例：
sh
gh api "repos/playcanvas/engine/contents/examples/src/examples/<category>/<name>.example.mjs?ref=$TAG" \
  --jq .content | base64 --decode
仅当已安装版本无对应标签时才使用
main
分支。该分支可能包含未受支持的API。示例中的资源URL指向
examples/assets/
；请从同一引用中获取资源，或替换为项目自有资源。
React示例目录属于文档而非带标签的发布版本：它规模较小，跟踪最新包版本，且代码片段是页面片段。请对照已安装的
@playcanvas/react
声明验证其中使用的每个prop和hook；若没有React示例覆盖所需功能，请移植Engine示例。

Adapt the recipe

适配参考方案

Keep component options, scene construction, materials, shaders, assets, and update logic. Drop the example browser's controls and context imports.
When one example integrates several required systems, reproduce that integration as one baseline before splitting or customizing it. Copying one script's parameters while omitting its layers, depth map, camera frame, sky, or assets is not an adaptation of the example.
Read exactly one reference matching the code being edited: direct Engine, React, or Web Components. Choose from imports and markup, not installed dependencies alone.
保留组件配置、场景构建、材质、着色器、资源和更新逻辑。移除示例浏览器的控件和上下文导入。
如果一个示例集成了多个所需系统，请先完整复现该集成作为基准，再进行拆分或定制。仅复制脚本参数却忽略其图层、深度图、相机帧、天空或资源，不属于对示例的适配。
请仅阅读与当前编辑代码匹配的参考文档：direct Engine, React, 或Web Components。请根据导入语句和标记选择参考文档，而非仅依赖已安装的依赖项。