A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
docs: deepen the Camera guide (component fields, zoom, multi-camera)
yhh60f4e16d2e57
diff --git a/docs/astro/src/content/docs/guides/camera.mdx b/docs/astro/src/content/docs/guides/camera.mdxindex 3233c81aa..30dc8b1e1 100644--- a/docs/astro/src/content/docs/guides/camera.mdx+++ b/docs/astro/src/content/docs/guides/camera.mdx@@ -1,27 +1,41 @@---title: Camera-description: Follow a target, convert screen/world coordinates, and shake the view.+description: The camera component, following, zoom, screen/world coordinates, shake, and multiple cameras.---+import { Aside } from '@astrojs/starlight/components';+Every scene renders through a camera — an entity with a `Camera` component. You-control how it moves and how it maps the screen to the world.+control zoom, follow a target, convert between screen and world space, shake the+view, and switch between multiple cameras.++## The `Camera` component++Key fields for a 2D game:++- `orthoSize` — the vertical half-height in world units: **this is your zoom**+ (smaller = zoomed in).+- `isActive` / `priority` — which camera is the active one when several exist+ (highest priority active camera wins).+- `viewport` (a `Vec4`, `x/y/w/h` in 0–1) — the screen rectangle the camera draws+ to, for split-screen or picture-in-picture.+- `clearFlags`, `pixelPerfect`, `aspectRatio`.## Follow a target-Add a `FollowTarget` component to the camera and point it at an entity. The-camera damps toward the target each frame, with a dead zone and smoothing.-Usually you add it in the editor and pick the target; in code:+Add a `FollowTarget` to the camera and point it at an entity. Usually you set this+in the editor; in code:```typescriptimport { defineSystem, Query, Commands, Camera, FollowTarget } from 'esengine';-const followPlayer = defineSystem([Query(Camera), Commands()], (cameras, cmds) => {+const follow = defineSystem([Query(Camera), Commands()], (cameras, cmds) => {for (const [cameraEntity] of cameras) {cmds.entity(cameraEntity).insert(FollowTarget, {target: playerEntity, // the Entity to follow (from your player Query)- offsetY: 40, // look a little above it- deadzone: 24, // the target can roam this far before the camera moves- damping: 0.25, // smoothing time-constant (0 = snap)+ offsetY: 40,+ deadzone: 24, // roam this far before the camera moves+ damping: 0.25, // smoothing (0 = snap)});}});@@ -29,26 +43,24 @@ const followPlayer = defineSystem([Query(Camera), Commands()], (cameras, cmds) =## Screen ↔ world-Read `CameraView` to convert between screen pixels and world coordinates — for-placing entities under the cursor, or checking what's on screen:+Read `CameraView` to convert coordinates — for placing entities under the cursor+or checking what's on screen:```typescriptimport { defineSystem, Res, CameraView, Input } from 'esengine';const pick = defineSystem([Res(CameraView), Res(Input)], (view, input) => {- const worldPos = view.screenToWorld(input.mouseX, input.mouseY); // { x, y } | null- const bounds = view.getWorldBounds(); // visible { left, right, bottom, top }+ const world = view.screenToWorld(input.mouseX, input.mouseY); // { x, y } | null+ const screen = view.worldToScreen(x, y); // { x, y } | null+ const mouse = view.getWorldMousePosition(); // { x, y } | null+ const bounds = view.getWorldBounds(); // { left, right, bottom, top }});```-For the mouse specifically, `Res(UICameraInfo)` already gives you `worldMouseX` /-`worldMouseY` — see [Input](/docs/guides/input/).-## Shake the camera-`shakeCamera` adds a decaying perturbation to the **rendered** view — it never-touches the camera's Transform, so it always recovers and never dirties the-scene:+`shakeCamera` adds a decaying perturbation to the **rendered** view (never to the+Transform, so it always recovers):```typescriptimport { shakeCamera } from 'esengine';@@ -56,5 +68,14 @@ import { shakeCamera } from 'esengine';shakeCamera(app, { amplitude: 12, rotation: 0, frequency: 22, duration: 0.4 });```-Call it wherever you hold the `app` — for example on a hit or an explosion. All-four options are optional (they default to a short punchy shake).+## Multiple cameras++With several `Camera` entities, `isActive` + `priority` decide which is live. The+camera director can **blend** the view from one camera to another over time+(rather than cutting) — for cinematic hand-offs — and `viewport` lets two cameras+share the screen for split-screen play.++<Aside type="tip">+ Animate `orthoSize` with a [tween](/docs/guides/animation/)+ (`TweenTarget.CameraOrthoSize`) for a smooth zoom in/out.+</Aside>diff --git a/docs/astro/src/content/docs/zh-cn/guides/camera.mdx b/docs/astro/src/content/docs/zh-cn/guides/camera.mdxindex 58db2c5d0..57a3ed752 100644--- a/docs/astro/src/content/docs/zh-cn/guides/camera.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/camera.mdx@@ -1,26 +1,36 @@---title: 相机-description: 跟随目标、屏幕/世界坐标转换,以及震屏。+description: 相机组件、跟随、缩放、屏幕/世界坐标、震屏与多相机。----每个场景都通过一个相机来渲染——一个带 `Camera` 组件的实体。你控制它如何移动,以及它-如何把屏幕映射到世界。+import { Aside } from '@astrojs/starlight/components';++每个场景都通过一个相机来渲染——一个带 `Camera` 组件的实体。你可以控制缩放、跟随目标、+在屏幕与世界空间之间转换、震屏,以及在多个相机之间切换。++## `Camera` 组件++2D 游戏的关键字段:++- `orthoSize` —— 以世界单位计的垂直半高:**这就是你的缩放**(越小越放大)。+- `isActive` / `priority` —— 存在多个相机时哪个是活动相机(优先级最高的活动相机胜出)。+- `viewport`(一个 `Vec4`,`x/y/w/h` 取 0–1)—— 相机绘制到的屏幕矩形,用于分屏或画中画。+- `clearFlags`、`pixelPerfect`、`aspectRatio`。## 跟随目标-给相机加一个 `FollowTarget` 组件并指向某个实体。相机每帧向目标阻尼移动,带死区和平滑。-通常你在编辑器里添加它并选择目标;用代码:+给相机加一个 `FollowTarget` 并指向某个实体。通常在编辑器里设置;用代码:```typescriptimport { defineSystem, Query, Commands, Camera, FollowTarget } from 'esengine';-const followPlayer = defineSystem([Query(Camera), Commands()], (cameras, cmds) => {+const follow = defineSystem([Query(Camera), Commands()], (cameras, cmds) => {for (const [cameraEntity] of cameras) {cmds.entity(cameraEntity).insert(FollowTarget, {target: playerEntity, // 要跟随的实体(来自你的玩家 Query)- offsetY: 40, // 稍微看它上方一点- deadzone: 24, // 目标在此范围内游走时相机不动- damping: 0.25, // 平滑时间常数(0 = 直接吸附)+ offsetY: 40,+ deadzone: 24, // 游走超过这个距离相机才移动+ damping: 0.25, // 平滑(0 = 直接吸附)});}});@@ -28,25 +38,22 @@ const followPlayer = defineSystem([Query(Camera), Commands()], (cameras, cmds) =## 屏幕 ↔ 世界-读 `CameraView` 在屏幕像素与世界坐标之间转换——用于把实体放到光标处,或判断什么在-屏幕上:+读 `CameraView` 转换坐标——用于把实体放到光标处,或判断什么在屏幕上:```typescriptimport { defineSystem, Res, CameraView, Input } from 'esengine';const pick = defineSystem([Res(CameraView), Res(Input)], (view, input) => {- const worldPos = view.screenToWorld(input.mouseX, input.mouseY); // { x, y } | null- const bounds = view.getWorldBounds(); // 可见范围 { left, right, bottom, top }+ const world = view.screenToWorld(input.mouseX, input.mouseY); // { x, y } | null+ const screen = view.worldToScreen(x, y); // { x, y } | null+ const mouse = view.getWorldMousePosition(); // { x, y } | null+ const bounds = view.getWorldBounds(); // { left, right, bottom, top }});```-若只是鼠标,`Res(UICameraInfo)` 已经直接给你 `worldMouseX` / `worldMouseY`——见-[输入](/docs/zh-cn/guides/input/)。-## 震屏-`shakeCamera` 给**渲染**视图加一个衰减扰动——它不碰相机的 Transform,所以总能恢复,-也不会弄脏场景:+`shakeCamera` 给**渲染**视图加一个衰减扰动(不碰 Transform,所以总能恢复):```typescriptimport { shakeCamera } from 'esengine';@@ -54,5 +61,13 @@ import { shakeCamera } from 'esengine';shakeCamera(app, { amplitude: 12, rotation: 0, frequency: 22, duration: 0.4 });```-在你持有 `app` 的地方调用它——例如在受击或爆炸时。四个选项都是可选的(默认是一次短促-有力的震动)。+## 多相机++存在多个 `Camera` 实体时,`isActive` + `priority` 决定哪个生效。相机导演器可以在两个相机+之间随时间**混合**视图(而不是硬切)——用于电影化的镜头交接;`viewport` 则让两个相机+共享屏幕做分屏。++<Aside type="tip">+ 用[补间](/docs/zh-cn/guides/animation/)(`TweenTarget.CameraOrthoSize`)动画化+ `orthoSize`,即可实现平滑的推近/拉远。+</Aside>