API 稳定性

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

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

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

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

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

113稳定候选

73Beta

1562实验性

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

按子系统

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

子系统	分级	理由
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 个，而其中时间轴那一半完全没被碰过
瓦片地图	实验性	有两个游戏端到端认证了它，但它的运行时面还没有被拿来定级
粒子	实验性	同瓦片地图 —— 有被认证的游戏在用，但还没被拿来定级
视频	实验性	各平台路径差异仍大，这套面还在收敛
AI —— 导航、状态机、行为树	实验性	刻意排在后面：0.50 冻的是「一个游戏由什么构成」，建立在其上的层要等下面这些定下来
网络与状态复制	实验性	同 AI —— 高层要等它下面的层
材质、光照、后处理	实验性	同 AI —— 而且它背后的 render graph 还在动

稳定候选

我们预计 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
`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
`Assets`	const
`AssetsData`	type
`Audio`	const
`Camera`	const
`CameraData`	interface
`CameraFields`	interface
`CameraTransformFields`	interface
`CharacterController`	const
`CharacterController3D`	const
`ConvexCollider3D`	const
`DistanceJoint3D`	const
`FixedJoint3D`	const
`GraphNodeType`	type
`GraphType`	type
`HingeJoint3D`	const
`Input`	const
`InputState`	class
`InstantiatePrefabResult`	interface
`MaterialGraph`	interface
`MaterialGraphNode`	interface
`MeshCollider3D`	const
`NODE_SPECS`	const
`NativeBridge`	interface
`NativeFetchResult`	interface
`NativeInputListener`	interface
`NativePlatformAdapter`	class
`NodeParamSpec`	interface
`NodePort`	interface
`NodeSpec`	interface
`Physics`	const
`PhysicsEvents`	const
`PointJoint3D`	const
`PrefabOverride`	interface
`PrefabServer`	class
`Prefabs`	const
`SceneConfig`	interface
`SceneContext`	interface
`SceneLoadProgressCallback`	type
`SceneManager`	const
`SceneManagerState`	class
`SceneStatus`	type
`SliderJoint3D`	const
`SpawnOverride`	type
`Spine`	const
`SpineAnimation`	const
`SpriteAnimator`	const
`ThemeColors`	interface
`TouchPoint`	interface
`TransitionConfig`	interface
`TransitionOptions`	interface
`UICameraData`	interface
`UICameraInfo`	const
`UINode`	const
`UIVisual`	const
`acquireWebGPUDevice`	function
`addNode`	function
`cameraFrustumCorners`	function
`captureFramePixels`	function
`compileMaterialGraph`	function
`connect`	function
`createHeadlessApp`	function
`disconnect`	function
`installNativePlatform`	function
`loadEsengineModule`	function
`moveNode`	function
`newMaterialGraph`	function
`nodeAdapter`	const
`removeNode`	function
`runHeadless`	function
`spawnUIEntity`	function
`themeColors`	function
`transitionTo`	function

实验性

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

这里没有覆盖的部分

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