Skip to content

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.

docs: add Timeline guide (TimelinePlayer + Res(Timeline))

yhh3f80c951a5ab
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 0fd749f0d..30dd12378 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -53,6 +53,7 @@ export default defineConfig({
{ label: 'Camera', translations: { 'zh-CN': '相机' }, slug: 'guides/camera' },
{ label: 'Physics', translations: { 'zh-CN': '物理' }, slug: 'guides/physics' },
{ label: 'Animation', translations: { 'zh-CN': '动画' }, slug: 'guides/animation' },
+ { label: 'Timeline', translations: { 'zh-CN': '时间轴' }, slug: 'guides/timeline' },
{ label: 'Spine Animation', translations: { 'zh-CN': 'Spine 动画' }, slug: 'guides/spine' },
],
},
diff --git a/docs/astro/src/content/docs/guides/timeline.mdx b/docs/astro/src/content/docs/guides/timeline.mdx
new file mode 100644
index 000000000..4ce1832c9
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/timeline.mdx
@@ -0,0 +1,55 @@
+---
+title: Timeline
+description: Sequencer animations — attach a timeline and control playback.
+---
+
+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.
+
+## Attach a timeline
+
+The `TimelinePlayer` component points an entity at a timeline asset:
+
+- `timeline` — the timeline asset path.
+- `playing` — whether it starts playing.
+- `speed` — playback rate (default `1.0`).
+- `wrapMode` — `'once'`, loop, etc.
+
+You usually set this in the editor; in code, insert it with `Commands`:
+
+```typescript
+import { defineSystem, Commands, TimelinePlayer } from 'esengine';
+
+const attach = defineSystem([Commands()], (cmds) => {
+ cmds.spawn().insert(TimelinePlayer, {
+ timeline: 'timelines/intro.estimeline',
+ playing: true,
+ speed: 1.0,
+ wrapMode: 'once',
+ });
+});
+```
+
+## Control playback
+
+Read the `Timeline` resource to drive an entity's timeline:
+
+```typescript
+import { defineSystem, Query, Res, TimelinePlayer, Timeline } from 'esengine';
+
+const control = defineSystem([Query(TimelinePlayer), Res(Timeline)], (q, timeline) => {
+ for (const [entity] of q) {
+ timeline.play(entity);
+ timeline.pause(entity);
+ timeline.stop(entity);
+ timeline.setTime(entity, 1.5); // seek to 1.5s
+ const t = timeline.getCurrentTime(entity);
+ const playing = timeline.isPlaying(entity);
+ }
+});
+```
+
+Because one timeline can drive many things at once, it's the tool for cutscenes
+and scripted sequences.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx b/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx
new file mode 100644
index 000000000..7266cd17a
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx
@@ -0,0 +1,53 @@
+---
+title: 时间轴
+description: Sequencer 动画 —— 附加时间轴并控制播放。
+---
+
+时间轴是一段 **Sequencer 动画**——随时间排布的关键帧轨道(移动 Transform、切换精灵、
+触发音频、开关实体、驱动 Spine)。你在编辑器的 Sequencer 里编排它,用 `TimelinePlayer`
+组件把它附加到实体上,再通过 `Timeline` 资源控制播放。
+
+## 附加时间轴
+
+`TimelinePlayer` 组件把实体指向一个时间轴资源:
+
+- `timeline` —— 时间轴资源路径。
+- `playing` —— 是否开始播放。
+- `speed` —— 播放速率(默认 `1.0`)。
+- `wrapMode` —— `'once'`、循环等。
+
+通常你在编辑器里设置它;用代码则用 `Commands` 插入:
+
+```typescript
+import { defineSystem, Commands, TimelinePlayer } from 'esengine';
+
+const attach = defineSystem([Commands()], (cmds) => {
+ cmds.spawn().insert(TimelinePlayer, {
+ timeline: 'timelines/intro.estimeline',
+ playing: true,
+ speed: 1.0,
+ wrapMode: 'once',
+ });
+});
+```
+
+## 控制播放
+
+读取 `Timeline` 资源来驱动某个实体的时间轴:
+
+```typescript
+import { defineSystem, Query, Res, TimelinePlayer, Timeline } from 'esengine';
+
+const control = defineSystem([Query(TimelinePlayer), Res(Timeline)], (q, timeline) => {
+ for (const [entity] of q) {
+ timeline.play(entity);
+ timeline.pause(entity);
+ timeline.stop(entity);
+ timeline.setTime(entity, 1.5); // 跳到 1.5 秒
+ const t = timeline.getCurrentTime(entity);
+ const playing = timeline.isPlaying(entity);
+ }
+});
+```
+
+因为一条时间轴能同时驱动很多东西,它是做过场动画和脚本化序列的工具。