docs: update scripting API docs

This commit is contained in:
2026-04-02 22:23:29 +08:00
parent ec2891b16b
commit 3f9e286637
25 changed files with 776 additions and 76 deletions

View File

@@ -10,18 +10,20 @@
## 概览
`NullScriptRuntime`作用不是执行脚本,而是让整个脚本系统在“没有真实脚本后端”的情况下仍然保持接口闭合:
`NullScriptRuntime`职责不是执行脚本,而是在“没有真实托管环境”时维持脚本系统接口闭合:
- `ScriptEngine` 仍然可以安全持有一个运行时对象
- 场景和脚本组件的原生数据层仍然可以工作。
- 测试或工具链不需要为“没有运行时时指针为空”额外兜底
- `ScriptEngine` 默认就持有它,因此不会出现运行时指针为空的问题
- `ScriptComponent``ScriptFieldStorage`、场景序列化和字段编辑流程都仍然可以工作。
- 编辑器或测试可以先走完整的脚本数据链路,再按需接入真实 Mono 后端
这是一种很典型的 Null Object 模式,在商业引擎底层模块中很常见
这是标准的 Null Object 模式,但它的“成功”语义必须按真实实现理解
## 当前实现行为
- 运行时启停是 no-op。
- 可用脚本类查询总是失败,并清空输出数组。
- 元数据查询总是失败,并清空输出数组。
- 默认值查询总是失败,并清空输出数组。
- 托管写字段总是返回 `true`,相当于“我接受这个请求,但没有实际后端可写”。
- 托管读字段总是返回 `false`
- 同步字段是 no-op。
@@ -43,7 +45,9 @@
|------|------|
| [OnRuntimeStart](OnRuntimeStart.md) | 空实现。 |
| [OnRuntimeStop](OnRuntimeStop.md) | 空实现。 |
| [TryGetAvailableScriptClasses](TryGetAvailableScriptClasses.md) | 始终失败并清空输出。 |
| [TryGetClassFieldMetadata](TryGetClassFieldMetadata.md) | 始终失败并清空输出。 |
| [TryGetClassFieldDefaultValues](TryGetClassFieldDefaultValues.md) | 始终失败并清空输出。 |
| [TrySetManagedFieldValue](TrySetManagedFieldValue.md) | 始终返回 `true`。 |
| [TryGetManagedFieldValue](TryGetManagedFieldValue.md) | 始终返回 `false`。 |
| [SyncManagedFieldsToStorage](SyncManagedFieldsToStorage.md) | 空实现。 |

View File

@@ -0,0 +1,28 @@
# NullScriptRuntime::TryGetAvailableScriptClasses
**命名空间**: `XCEngine::Scripting`
**类型**: `method`
**头文件**: `XCEngine/Scripting/NullScriptRuntime.h`
## 签名
```cpp
bool TryGetAvailableScriptClasses(
std::vector<ScriptClassDescriptor>& outClasses) const override;
```
## 当前实现行为
- 清空 `outClasses`
- 直接返回 `false`
## 含义
空运行时不会伪造脚本类列表。需要可绑定脚本类时,调用方必须接入真实后端,如 `MonoScriptRuntime`
## 相关文档
- [NullScriptRuntime](NullScriptRuntime.md)
- [ScriptEngine::TryGetAvailableScriptClasses](../ScriptEngine/TryGetAvailableScriptClasses.md)

View File

@@ -0,0 +1,32 @@
# NullScriptRuntime::TryGetClassFieldDefaultValues
**命名空间**: `XCEngine::Scripting`
**类型**: `method`
**头文件**: `XCEngine/Scripting/NullScriptRuntime.h`
## 签名
```cpp
bool TryGetClassFieldDefaultValues(
const std::string& assemblyName,
const std::string& namespaceName,
const std::string& className,
std::vector<ScriptFieldDefaultValue>& outFields) const override;
```
## 当前实现行为
- 忽略输入参数
- 清空 `outFields`
- 直接返回 `false`
## 含义
空运行时不会提供类默认值,因此 `ScriptEngine` 在这种模式下会回退到按字段类型生成默认值。
## 相关文档
- [NullScriptRuntime](NullScriptRuntime.md)
- [IScriptRuntime::TryGetClassFieldDefaultValues](../IScriptRuntime/TryGetClassFieldDefaultValues.md)