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: rewrite the Timeline guide to the complete-reference template
yhh8e0bbb861df4
diff --git a/docs/astro/src/content/docs/guides/timeline.mdx b/docs/astro/src/content/docs/guides/timeline.mdxindex 4ce1832c9..a8bdcbeaf 100644--- a/docs/astro/src/content/docs/guides/timeline.mdx+++ b/docs/astro/src/content/docs/guides/timeline.mdx@@ -1,23 +1,20 @@---title: Timeline-description: Sequencer animations — attach a timeline and control playback.+description: The complete guide to Sequencer timelines — the TimelinePlayer component, the Timeline playback API, and keyframe tracks.----A timeline is a **Sequencer animation** — tracks of keyframes over time (moving a-Transform, swapping sprites, firing audio, toggling entities, driving Spine). You-author it in the editor's Sequencer, attach it to an entity with a-`TimelinePlayer` component, and control playback through the `Timeline` resource.+import { Aside } from '@astrojs/starlight/components';-## Attach a timeline--The `TimelinePlayer` component points an entity at a timeline asset:+A timeline is a **Sequencer animation** — tracks of keyframes over time that move a+Transform, swap sprites, fire audio, toggle entities, or drive Spine. You author it+in the editor's Sequencer, attach it with a `TimelinePlayer` component, and control+playback through the `Timeline` resource. Because one timeline drives many things at+once, it's the tool for cutscenes and scripted sequences.-- `timeline` — the timeline asset path.-- `playing` — whether it starts playing.-- `speed` — playback rate (default `1.0`).-- `wrapMode` — `'once'`, loop, etc.+## Attach a timeline-You usually set this in the editor; in code, insert it with `Commands`:+The `TimelinePlayer` component points an entity at a timeline asset. Usually set in+the editor; in code, insert it with `Commands`:```typescriptimport { defineSystem, Commands, TimelinePlayer } from 'esengine';@@ -32,6 +29,13 @@ const attach = defineSystem([Commands()], (cmds) => {});```+| Property | Type | Default | Description |+|---|---|---|---|+| `timeline` | asset | `''` | The timeline asset (`.estimeline`). |+| `playing` | boolean | `false` | Whether it starts playing on attach. |+| `speed` | number | `1` | Playback rate multiplier. |+| `wrapMode` | string | `'once'` | `'once'`, `'loop'`, or `'pingpong'`. |+## Control playbackRead the `Timeline` resource to drive an entity's timeline:@@ -51,5 +55,42 @@ const control = defineSystem([Query(TimelinePlayer), Res(Timeline)], (q, timelin});```-Because one timeline can drive many things at once, it's the tool for cutscenes-and scripted sequences.+| Method | Description |+|---|---|+| `play(entity)` | Start or resume playback. |+| `pause(entity)` | Pause, keeping the current time. |+| `stop(entity)` | Stop and reset to the start. |+| `setTime(entity, seconds)` | Seek to a time (scrubs all tracks). |+| `getCurrentTime(entity)` | Current playhead time in seconds. |+| `isPlaying(entity)` | Whether it's currently playing. |++## Track types++A timeline is a set of tracks evaluated together each frame:++| Track | Drives |+|---|---|+| Transform | Position / rotation / scale keyframes (hermite / linear / step). |+| Sprite frames | Swap sprite-sheet frames over time. |+| Audio | Fire one-shot sounds at keyframes. |+| Activation | Toggle entities on/off. |+| Spine | Play Spine animations as clips. |++## Best practices++- **Author in the Sequencer** — the timeline asset holds the tracks; code just plays+ and seeks it.+- **`wrapMode: 'once'`** for cutscenes, `'loop'` for ambient/idle sequences.+- **Scrub with `setTime`** to preview or sync a cutscene to gameplay state.+- **Use a timeline (not tweens)** when many properties/entities animate in lockstep;+ reach for [tweens](/docs/guides/animation/) for one-off single-property juice.++<Aside type="note">+ Timeline playback is gameplay — it advances in play mode and the standalone+ runtime, and is frozen in the editor's edit mode.+</Aside>++## See also++- [Animation](/docs/guides/animation/) — tweens and the animator state machine.+- [Spine Animation](/docs/guides/spine/) — timelines can drive Spine clips.diff --git a/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx b/docs/astro/src/content/docs/zh-cn/guides/timeline.mdxindex 7266cd17a..88f8cbeee 100644--- a/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx@@ -1,22 +1,18 @@---title: 时间轴-description: Sequencer 动画 —— 附加时间轴并控制播放。+description: Sequencer 时间轴的完整指南——TimelinePlayer 组件、Timeline 播放 API,以及关键帧轨道。----时间轴是一段 **Sequencer 动画**——随时间排布的关键帧轨道(移动 Transform、切换精灵、-触发音频、开关实体、驱动 Spine)。你在编辑器的 Sequencer 里编排它,用 `TimelinePlayer`-组件把它附加到实体上,再通过 `Timeline` 资源控制播放。+import { Aside } from '@astrojs/starlight/components';-## 附加时间轴--`TimelinePlayer` 组件把实体指向一个时间轴资源:+时间轴是一段 **Sequencer 动画**——随时间排布的关键帧轨道,可以移动 Transform、切换精灵、+触发音频、开关实体或驱动 Spine。你在编辑器的 Sequencer 里编辑它,用 `TimelinePlayer` 组件+附加,并通过 `Timeline` 资源控制播放。因为一条时间轴能同时驱动很多东西,它是过场与脚本化+序列的工具。-- `timeline` —— 时间轴资源路径。-- `playing` —— 是否开始播放。-- `speed` —— 播放速率(默认 `1.0`)。-- `wrapMode` —— `'once'`、循环等。+## 附加时间轴-通常你在编辑器里设置它;用代码则用 `Commands` 插入:+`TimelinePlayer` 组件把实体指向一个时间轴资源。通常在编辑器里设;用代码则以 `Commands` 插入:```typescriptimport { defineSystem, Commands, TimelinePlayer } from 'esengine';@@ -31,9 +27,16 @@ const attach = defineSystem([Commands()], (cmds) => {});```+| 属性 | 类型 | 默认 | 说明 |+|---|---|---|---|+| `timeline` | asset | `''` | 时间轴资源(`.estimeline`)。 |+| `playing` | boolean | `false` | 附加时是否开始播放。 |+| `speed` | number | `1` | 播放速率倍率。 |+| `wrapMode` | string | `'once'` | `'once'`、`'loop'` 或 `'pingpong'`。 |+## 控制播放-读取 `Timeline` 资源来驱动某个实体的时间轴:+读 `Timeline` 资源来驱动某个实体的时间轴:```typescriptimport { defineSystem, Query, Res, TimelinePlayer, Timeline } from 'esengine';@@ -43,11 +46,47 @@ const control = defineSystem([Query(TimelinePlayer), Res(Timeline)], (q, timelintimeline.play(entity);timeline.pause(entity);timeline.stop(entity);- timeline.setTime(entity, 1.5); // 跳到 1.5 秒+ timeline.setTime(entity, 1.5); // seek to 1.5sconst t = timeline.getCurrentTime(entity);const playing = timeline.isPlaying(entity);}});```-因为一条时间轴能同时驱动很多东西,它是做过场动画和脚本化序列的工具。+| 方法 | 说明 |+|---|---|+| `play(entity)` | 开始或恢复播放。 |+| `pause(entity)` | 暂停,保留当前时间。 |+| `stop(entity)` | 停止并重置到开头。 |+| `setTime(entity, seconds)` | 定位到某时间(scrub 所有轨道)。 |+| `getCurrentTime(entity)` | 当前播放头时间(秒)。 |+| `isPlaying(entity)` | 是否正在播放。 |++## 轨道类型++时间轴是一组每帧一起求值的轨道:++| 轨道 | 驱动 |+|---|---|+| Transform | 位置 / 旋转 / 缩放关键帧(hermite / linear / step)。 |+| 精灵帧 | 随时间切换精灵表帧。 |+| 音频 | 在关键帧触发一次性声音。 |+| 激活 | 开关实体。 |+| Spine | 把 Spine 动画作为片段播放。 |++## 最佳实践++- **在 Sequencer 里编辑**——时间轴资源持有轨道,代码只负责播放与定位。+- 过场用 **`wrapMode: 'once'`**,环境/待机序列用 `'loop'`。+- **用 `setTime` scrub** 来预览,或把过场与玩法状态同步。+- 当很多属性/实体需要同步动画时**用时间轴(而非补间)**;一次性的单属性手感用+ [补间](/docs/zh-cn/guides/animation/)。++<Aside type="note">+ 时间轴播放属于玩法——它在播放模式和独立运行时里推进,在编辑器编辑模式下冻结。+</Aside>++## 参见++- [动画](/docs/zh-cn/guides/animation/) —— 补间与动画状态机。+- [Spine 动画](/docs/zh-cn/guides/spine/) —— 时间轴可以驱动 Spine 片段。