Intermact API Reference

本文档总览 v0.1–v1.0（Phase-1 / Phase-2 / Phase-3） 公共 API 的架构与入口；各符号页由 TypeDoc 从 packages/*/src 的导出项与 TSDoc 注释自动生成。Phase-3（PCG / 3D / 序列化导出 / 插件）的 API 地图见下文 §Phase-3，概念教程见 PCG / 3D / 导出嵌入 / 性能 / 扩展系统。

完整契约与修订记录见仓库 dev-docs/design.md。概念性教程见指南 · 架构概览。

愿景与 API 边界

阶段	版本	主题	与本文档关系
Phase-1	v0.1	可交互 Manim 替代品：2D 图元、可 seek 时间线、坐标轴、响应式调参	总览 §Phase-1
Phase-2	v0.2	数理工具箱：Scale、LaTeX、Morph matching、交互拾取、布局	总览 §Phase-2
Phase-3	v1.0	PCG、3D 全量、序列化/导出/嵌入、插件	符号页 + 插件指南

核心执行模型：可 seek 时间线

Intermact 采用保留模（retained-mode）时间线（design.md §3.2）：

阶段	职责	关键 API
构建期	注册对象；`scene.play` 向 Storyboard 追加轨道	`createProgram`, `buildProgram`, `Scene2D`
播放期	`seek` / `update` 纯函数求值；确定性快照	`Player`, `Track`, `RenderSnapshot`

await scene.play(...) 是构建期语法糖，逻辑时钟瞬间推进，不消耗墙钟时间。

对象三层：定义 · 实例 · 运行时态

text

IMObject2D（不可变定义：几何 + trait）
    └── scene.register(...) → RegisteredObject2D（动画句柄：create / moveTo / morphTo …）
            └── Track 求值 → RuntimeState2D（位置、reveal、opacity、geometryOverride …）

定义层：IMObject2D + trait（stroke / fill / morphable / textLayout）；图元工厂如 circle、polygon。
实例层：RegisteredObject2D——动画方法返回 Animation 数据，在 play 时编译。
运行时层：RuntimeState2D + applyPatch2D；渲染器消费 RenderSnapshot。

Scene · Camera · Canvas 解耦

与 Manim 不同，场景、相机、画布分层（design.md §9–10）：

层	角色	关键 API
Scene2D	坐标域、对象注册、`getAxes`、编排 `play`	`Scene2D`
Camera	正交相机描述，挂载到视口	`createCamera2D`
Canvas	React 入口：构建 program、R3F 画布、时间线叠层	`IntermactCanvas`

坐标变换：CoordinateTransform2D（abs/rel、极坐标）。轴对象通过 Scene2D.getAxes 注册，刻度由 Scale 生成（Phase-2）。

包分层与渲染管线

text

@intermact/react
  └── @intermact/render-r3f     SceneView、computeFit
        └── @intermact/render-three   stroke/fill 几何、ThreeSceneView
              └── @intermact/core     禁止 React / three / DOM

包	职责
`@intermact/core`	模型、几何、时间线、响应式、Scale/构件/文本/交互；可 Node 无头运行
`@intermact/render-three`	`RenderSnapshot` → three.js 几何（stroke trim、earcut fill）
`@intermact/render-r3f`	R3F 内 diff 更新、相机 fit、HiDPI
`@intermact/react`	`IntermactCanvas`、`useSignal`、时间线控件、Inspector

数据流：Player.getSnapshot() → ThreeSceneView diff → R3F SceneView。

Phase-1（v0.1）：基础 2D 叙事

指南：程序与场景 · 时间线 · 几何 · 渲染 · 动画 · 坐标系 · 响应式

能力	API 入口
2D 图元	`circle`, `rectangle`, `polygon`, `bezierCurve`, `arrow`
Create / Fade / Move / Tween	`RegisteredObject2D`, `compileSpec`
编排	`sequence`, `parallel`, `stagger`, `wait`
坐标与轴	`CoordinateTransform2D`, `Scene2D.getAxes`
响应式调参	`signal`, `derived`, `tweenSignal`, `useSignal`
副作用（不可 seek）	`call`

Phase-2（v0.2）：数理工具箱

指南：Scale · 数理构件 · Morph · 文本与 LaTeX · 交互 · 布局与 Inspector

Scale 与刻度（M7）

能力	API 入口
标度类型	`linearScale`, `logScale`, `normalizeScale`
刻度生成	`numericTicks`
轴句柄	`createAxesHandle`, `AxesHandle`（`c2p` / `xScale` / `yScale`）

数理构件库（M8）

能力	API 入口
坐标平面	`numberLine`, `numberPlane`, `polarPlane`, `complexPlane`
曲线与积分	`functionGraph`, `parametricGraph`, `areaUnderCurve`, `riemannRectangles`, `tangentLine`
表达与标注	`matrixObject`, `tableObject`, `brace`, `decimalNumber`

Morph 与分部匹配（M9）

策略	API 入口
`arc-length` / `anchor` / `matching` / `cross-fade`	`morph`, `transformMatching`
复合对象部件 key	`group2D`
实例方法	`RegisteredObject2D.morphTo`, `transformMatchingTo`

文本与 LaTeX（M10）

能力	API 入口
字体	`loadOutlineFontFromBuffer`, `setDefaultFont`, `createAssetManager`
文本对象	`textObject`, `glyphText`
LaTeX	`layoutMathJaxLatex`, `latexObjectFromGlyphs`
Writing 动画	`glyphLocalReveal`, `computeGlyphRevealSpans`
公式分部变形	`transformMatchingTex`（token → 部件 key，复用 matching）

交互系统（M11）

能力	API 入口
可拖拽源	`draggablePoint`, `draggableValue`, `draggablePointSource`, `draggableValueSource`
命中测试	`hitTest`, `hitProxy`, `interactive`
拾取辅助	`pickRectFromObject`, `pickBandFromObject`

布局与 Inspector（M12）

能力	API 入口
相对排版	`LayoutHandle`（`RegisteredObject2D.layout`：`alignTo` / `nextTo` / `arrange` / `fitTo`）
布局句柄工厂	`createLayoutHandle`
开发工具	`Inspector`（React 侧场景树 / 信号 / 快照调试）

Phase-3（v1.0）：PCG · 3D · 序列化导出 · 插件

指南：程序化生成 · 3D 场景与相机 · 导出、分享与嵌入 · 性能与大数据 · 扩展系统

PCG 程序化生成（M13）

能力	API 入口
参数 / 点阵 / 铺砌	`parametricCurve2D`, `lattice`, `tiling`
分形 / 规则	`fractal`, `recursiveTree`, `lSystem`, `cellularAutomaton`, `cellularAutomatonFrames`
场	`functionGraph`, `isoline`, `heatmap`, `streamlines`
图 / 数据	`graphObject`, `barChart`, `scatter`, `lineChart`, `mapData`
组合算子	`transformObject`, `repeatObject`, `instanceField`, `mapPoints`, `along`, `booleanOp`

3D 全量（M14）

能力	API 入口
场景 / 相机	`Scene3D`, `RegisteredCamera3D`, `CoordinateTransform3D`
3D 工厂	`polyline3D`, `curve3D`, `meshObject`, `surface3D`, `pointCloud3D`, `axes3D`
标量场等值面	`isosurface`, `marchingCubes`
嵌套子场景	`RegisteredObject2D.layout` · `render(scene, camera)`（render-r3f `RenderedScene`）

序列化 / 导出 / 嵌入（M15）

能力	API 入口
序列化	`serialize`, `deserialize`
分享链接	`encodeShareUrl`, `decodeShareUrl`, `SerializedCanvas`
无头定帧	`snapshotToSVG`, `sampleFrames`, `sampleFrameHashes`
视频 / GIF	`recordCanvasVideo`, `captureFrameSequencePng`, `encodeGif`, `exportCanvasGif`
嵌入	`defineIntermactEmbed`, `buildEmbedIframe`

性能与扩展（M16 / M17）

能力	API 入口
GPU 实例化 / 点云	`instanceField`, `pointCloud3D`
注册表	`createRegistries`, `globalRegistries`
插件	`definePlugin`, `installPlugin`, `defineObjectType`, `defineGenerator`
生成器分发	`runGenerator`, `selectRenderer`

响应式层（交互态）

对齐 Manim ValueTracker + add_updater（design.md §8），用于参数驱动的几何重算：

每帧：Player.prepareFrame → ReactiveEngine.flush → 再生成 RenderSnapshot。

如何查阅符号

从下方 Packages 进入各包索引页。
侧边栏按 Classes / Interfaces / Functions 浏览（含 Phase-2 全部导出）。
修改 API 文档请编辑源码 TSDoc，运行 pnpm run gen:reference 重新生成。

Intermact API Reference ​

愿景与 API 边界 ​

核心执行模型：可 seek 时间线 ​

对象三层：定义 · 实例 · 运行时态 ​

Scene · Camera · Canvas 解耦 ​

包分层与渲染管线 ​

Phase-1（v0.1）：基础 2D 叙事 ​

Phase-2（v0.2）：数理工具箱 ​

Scale 与刻度（M7） ​

数理构件库（M8） ​

Morph 与分部匹配（M9） ​

文本与 LaTeX（M10） ​

交互系统（M11） ​

布局与 Inspector（M12） ​

Phase-3（v1.0）：PCG · 3D · 序列化导出 · 插件 ​

PCG 程序化生成（M13） ​

3D 全量（M14） ​

序列化 / 导出 / 嵌入（M15） ​

性能与扩展（M16 / M17） ​

响应式层（交互态） ​

如何查阅符号 ​

Packages ​