API 稳定性

Estella 还在 1.0 之前，API 各部分的稳定程度并不一致。与其让你去猜哪些能依赖，每个导出符号都在自己的声明上带一个稳定性标记 —— 它会随 .d.ts 一起进入你的项目，在编辑器里悬停就能看到。

等级	标记	承诺
稳定候选	`@public`	我们预计 1.0 不会破坏它。要改动或移除，必须先经过一个弃用版本。
Beta	`@beta`	已发布并受支持，但形状在 1.0 前仍可能调整。
实验性	`@experimental`	不作兼容性承诺，任何版本都可能改动或消失。
内部	`@internal`	请勿依赖。它被导出本身就是一个构建错误。

没有「默认稳定」这回事。未标记的符号一律是实验性 —— 冻结一个 API 是我们主动做出的决定，而不是忘了阻止的结果。

一个符号要升到稳定候选，必须同时满足三件事：有文档、有测试钉住它的行为、并且被我们用来验收发布的那几个游戏真实调用。这道门槛是构建门禁而不是习惯；承诺本身也一样，每次推送都会与上一个发布 tag 比对。

下面的清单由守卫读取的同一份快照生成。

115稳定候选

103Beta

2140实验性

共 2358 个导出符号。实验性是默认值——一个符号只有在有人明确决定时才会升级，所以这份清单是一步步长出来的。

按子系统

同一个答案，但按你真正在用的粒度给出。表里每条裁定都被它的入口符号的标签钉住，所以它不会悄悄和标签说不一样的话。

子系统	分级	理由
ECS	稳定候选	已冻结——它必须跨过的门槛见下。
应用生命周期	稳定候选	已冻结——它必须跨过的门槛见下。
变换与层级	稳定候选	已冻结——它必须跨过的门槛见下。
精灵与文本	稳定候选	已冻结——它必须跨过的门槛见下。
输入动作	稳定候选	动作与绑定的词汇表已冻结；它下面的每帧原始状态是 Beta —— 见 InputState
布局单位	稳定候选	已冻结——它必须跨过的门槛见下。
原始输入状态	Beta	每帧触摸状态只能通过原始集合拿到，started/ended 没有访问器，也没有写入门 —— 冻结它等于把这两个缺口一起冻进去
UI	Beta	115 个 UI 符号里只有 33 个到得了被认证的游戏，而这套面最新的部分恰恰是创作者最先碰的：锚点、inset、主题 token
场景	Beta	只有一个被认证的项目在驱动场景，而 SceneManagerState 有 26 个签名
预制体	Beta	instantiate 没有动过，但它的结果和覆盖形状属于磁盘格式，所以名字比形状先定下来
资产	Beta	只有一个被认证的项目用 Res(Assets)，且只用了 4 个成员；而宿主接线（resolver、registry、manifest、设备丢失恢复）必须先离开面向游戏的这一面
物理	Beta	语料只触到 37 个物理符号里的 3 个
相机	Beta	clearFlags 是位掩码，而它的 C++ enum 在 TypeScript 侧没有拼写；cullingMask 指的图层没有任何导出常量能标识 —— 两个字段被打成 number 是因为缺词汇
Spine	Beta	只有一个被认证的项目在播骨骼；运行时是项目自行选用的 side module
音频	Beta	已有被认证的运行会驱动一个循环并读取 master 总线的 analyser，所以它坏了会被发现——但语料只触到 23 个音频符号里的少数几个
动画与时间轴	Beta	sprite-animation 现在端到端认证了它，但语料只触到 80 个动画符号里的 2 个，而其中时间轴那一半完全没被碰过
瓦片地图	Beta	两个游戏认证了它，其中一个每次改动都跑 —— 这比几个已经在这一级的子系统证据还多；还没定下来的是多 tileset 的图层，单数字段仍为旧场景保留着
粒子	Beta	有一个被认证的游戏在驱动它，与 spine、scene 当初发布时的证据同级；年轻的那一半是可编辑曲线 —— 它们会覆盖 start/end，而只有一个游戏真的编过
世界 residency —— 按格子流送世界	实验性	端到端证明的只有一种世界形状：cook 时切出的方形 XZ 网格，同步加载。一个游戏怎么提要求已经定了；大世界在它之后还需要的东西——优先级、预算、缺席内容的细节层次——还没有
视频	实验性	各平台路径差异仍大，这套面还在收敛
Gameplay —— 第三人称角色与相机	实验性	引擎里最新的一层，也是最被具体游戏塑形的一层：角色欠动画什么已经定了，它之上的还没有
AI —— 导航、状态机、行为树	实验性	刻意排在后面：0.50 冻的是「一个游戏由什么构成」，建立在其上的层要等下面这些定下来
脚本图 —— 可视化逻辑	实验性	节点词汇表还在长：一个名字多一个输出就改变了已画好的图能读到什么，形状还不到冻结的时候
网络与状态复制	实验性	同 AI —— 高层要等它下面的层
材质、光照、后处理	实验性	同 AI —— 一个游戏是由它下面那几层构成的,那些先冻;它当初等的那个 render graph 已经定下来了
3D 物理	实验性	它的门（插件、世界资源、碰撞事件）到这个版本才第一次进入口，所以游戏真正会调用的那一半还没有被任何东西建立在上面
3D 模型与蒙皮	实验性	导入链路已经端到端认证，但游戏用来驱动模型的运行时面（几何体、逐子网格材质、关节实体）还没有被拿来定级
贴花	实验性	裁剪本身已经证明是对的,但还没有任何创作面去做一个贴花,所以这套接口的形状要跟着投影盒面板最终需要什么走
烘焙光照	实验性	烘焙跑得起来，但编辑器里还没有什么去触发它，所以这套接口的形状要跟着创作面最终需要什么走
DragonBones	实验性	第二个 2D 骨骼运行时，也是没有任何被认证的游戏在用的那个 —— 证据在 Spine 那边，这边一点也没分到
数学库	实验性	类型本身已冻结 —— Vec2、Vec3、Quat 是 @public，Transform 就是由它们构成的 —— 但它们之上的运算没有，而判决必须按更弱的那一半来说
本地化	实验性	有一个游戏端到端认证了它，但用到的只是「切语言 + 查 key」；围绕它的复数、格式化、回退这一圈没有任何消费者
平台服务	实验性	每个服务都是与某个平台的契约而非与引擎的契约，而它们之间的差异大到共同形状还没找出来

稳定候选

我们预计 1.0 不会破坏这些。每一个都有文档、有测试钉住、并被我们用来验收发布的游戏真实调用；要改动或移除，必须先经过一个弃用版本。

符号	种类
`ActionDef`	interface
`ActionType`	type
`AddedWrapper`	interface
`AnyComponentDef`	type
`AssetFieldMeta`	interface
`AssetFieldType`	type
`AssetRef`	interface
`Axis1D`	const
`Axis2D`	const
`Binding`	type
`BuiltinComponentDef`	interface
`Button`	const
`ChangedWrapper`	interface
`Children`	const
`ChildrenData`	interface
`Color`	interface
`Commands`	function
`CommandsDescriptor`	interface
`CommandsInstance`	class
`ComponentData`	type
`ComponentDef`	interface
`ComponentMetadata`	interface
`ComponentsData`	type
`Dimension`	interface
`DimensionUnit`	type
`Entity`	type
`EntityCommands`	class
`EventDef`	interface
`EventReader`	function
`EventReaderDescriptor`	interface
`EventReaderInstance`	class
`EventWriter`	function
`EventWriterDescriptor`	interface
`EventWriterInstance`	class
`FieldMeta`	interface
`FilterExpr`	type
`GamepadAxis`	enum
`GamepadButton`	enum
`GetWorld`	function
`GetWorldDescriptor`	interface
`GpAxis`	const
`GpButton`	const
`InferParam`	type
`InferParams`	type
`InputMap`	class
`InputMapAsset`	interface
`Key`	const
`Keys1D`	const
`Keys2D`	const
`ListenOptions`	interface
`MouseButton`	const
`Mut`	function
`MutWrapper`	interface
`Name`	const
`NameData`	interface
`Parent`	const
`ParentData`	interface
`Quat`	interface
`Query`	function
`QueryArg`	type
`QueryBuilder`	interface
`QueryDescriptor`	interface
`QueryInstance`	class
`QueryResult`	type
`RemovedQueryDescriptor`	interface
`RemovedQueryInstance`	class
`Res`	function
`ResDescriptor`	interface
`ResMut`	function
`ResMutDescriptor`	interface
`ResMutInstance`	class
`ResourceDef`	interface
`RunCondition`	type
`RuntimeOnly`	const
`Schedule`	enum
`SkeletalFieldMeta`	interface
`Sprite`	const
`SpriteData`	interface
`SpriteDrawMode`	enum
`SpriteMaskInteraction`	enum
`Stick`	const
`SystemDef`	interface
`SystemOptions`	interface
`SystemParam`	type
`SystemSet`	interface
`SystemSetOptions`	interface
`SystemTouches`	interface
`Text`	const
`TextAlign`	type
`TextData`	interface
`TextOverflow`	type
`TextRenderMode`	type
`TextVerticalAlign`	type
`Time`	const
`TimeData`	interface
`Transform`	const
`TransformData`	interface
`UnwrapQueryArg`	type
`Vec2`	interface
`Vec3`	interface
`Vec4`	interface
`Virtual`	const
`World`	class
`addStartupSystem`	function
`addSystemSetToSchedule`	function
`addSystemToSchedule`	function
`defineComponent`	function
`defineEvent`	function
`defineInputMap`	function
`defineResource`	function
`defineSystem`	function
`defineSystemSet`	function
`defineTag`	function
`percent`	const
`px`	const

Beta

已发布并受支持，但形状在 1.0 前仍可能调整。可以用，但升级时请读 changelog。

符号	种类
`Animator`	const
`AnimatorData`	interface
`Assets`	const
`AssetsData`	type
`Audio`	const
`Camera`	const
`CameraCommit`	const
`CameraCommitData`	interface
`CameraCommitListener`	type
`CameraData`	interface
`CameraFields`	interface
`CameraLens`	interface
`CameraTransformFields`	interface
`CharacterController2D`	const
`CharacterController2DData`	interface
`ClearFlags`	enum
`EmitterShape`	enum
`FillMethod`	enum
`FillOrigin`	enum
`GraphNodeType`	type
`GraphType`	type
`Input`	const
`InputState`	class
`InstantiatePrefabResult`	interface
`LiveBindings`	const
`LiveBindingsData`	interface
`MaterialGraph`	interface
`MaterialGraphNode`	interface
`NODE_SPECS`	const
`NativeBridge`	interface
`NativeFetchResult`	interface
`NativeInputListener`	interface
`NativePlatformAdapter`	class
`NodeParamSpec`	interface
`NodePort`	interface
`NodeSpec`	interface
`OccluderData`	interface
`ParticleEasing`	enum
`ParticleEmitter`	const
`ParticleEmitterData`	interface
`Physics2D`	const
`Physics2DEvents`	const
`Physics2DEventsData`	interface
`PrefabOverride`	interface
`PrefabServer`	class
`Prefabs`	const
`PresentedCameraView`	const
`ProjectionType`	enum
`ReflectionProbeData`	interface
`SceneConfig`	interface
`SceneContext`	interface
`SceneLoadProgressCallback`	type
`SceneManager`	const
`SceneManagerState`	class
`SceneStatus`	type
`SimulationSpace`	enum
`SortingGroupData`	interface
`SpawnOverride`	type
`Spine`	const
`SpineAnimation`	const
`SpineAnimationData`	interface
`SpriteAnimator`	const
`SpriteAnimatorData`	interface
`SpriteMaskData`	interface
`SubEmitterTrigger`	enum
`ThemeColors`	interface
`TilemapLayer`	const
`TilemapLayerData`	interface
`TilemapOrientation`	enum
`TilemapStaggerAxis`	enum
`TilemapStaggerIndex`	enum
`TouchPoint`	interface
`TransitionConfig`	interface
`TransitionOptions`	interface
`UICameraData`	interface
`UICameraInfo`	const
`UINode`	const
`UIVisual`	const
`UIVisualData`	interface
`UIVisualFit`	enum
`UIVisualType`	enum
`acquireWebGPUDevice`	function
`addNode`	function
`cameraCommitChanged`	function
`cameraFrustumCorners`	function
`captureFramePixels`	function
`compileMaterialGraph`	function
`connect`	function
`createHeadlessApp`	function
`disconnect`	function
`exact`	const
`installNativePlatform`	function
`loadEsengineModule`	function
`moveNode`	function
`newMaterialGraph`	function
`nodeAdapter`	const
`onCameraCommitChanged`	function
`presentedCameraView`	const
`removeNode`	function
`runHeadless`	function
`spawnUIEntity`	function
`themeColors`	function
`transitionTo`	function

实验性

其余全部，也就是这个面的绝大部分。它们能用，编辑器本身就建立在它们之上，但不附带任何兼容性承诺：任何版本都可能改动或消失。编辑器里悬停即可看到分级，仓库中的 sdk/etc/*.api.md 是完整清单。

这里没有覆盖的部分

以上分级描述的是 TypeScript API。Estella 的 1.0 承诺还包括项目与资源格式、WASM 运行时契约，以及有文档的构建 CLI —— 每一项的「破坏性改动」如何定义，见版本策略。