> ## Documentation Index
> Fetch the complete documentation index at: https://fluxon.tabooproject.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 运行时注册 API

> FluxonRuntime 中可用的函数/扩展注册入口

基于 `FluxonRuntime.java` 的登记手册，帮助你在宿主启动时向脚本注入函数、变量或扩展。

## 适用场景

* 暴露宿主能力（文件/网络/游戏对象等）给脚本。
* 设置函数的线程模型（异步或主线程）。
* 在不改核心源码的情况下增量添加命名空间或扩展函数。

## 单例访问

```java theme={null}
FluxonRuntime runtime = FluxonRuntime.getInstance();
```

* `newEnvironment()`：创建新的解释器环境（自动 bake 缓存）。
* `getSystemFunctions()` / `getExtensionFunctions()` / `getSystemVariables()`：调试或导出当前注册表。
* `setPrimaryThreadExecutor(Executor executor)`：替换主线程执行器，供主线程函数使用。

## 函数注册

| 方法                                                       | 用途                                  |
| -------------------------------------------------------- | ----------------------------------- |
| `registerFunction(name, signature, callable)`            | 注册同步函数。                             |
| `registerFunction(namespace, name, signature, callable)` | 带命名空间的函数，例如 `fs:crypto`。            |
| `registerAsyncFunction(name, signature, callable)`       | 异步函数，`Function#isAsync()` 为 `true`。 |
| `registerPrimarySyncFunction(name, signature, callable)` | 主线程函数，`isPrimarySync = true`。       |
| `exportFunction(name, handle)`                           | 导出函数到跨 CL 共享注册表。                    |
| `exportRegisteredFunction(name)`                         | 导出已注册的函数到共享注册表。                     |
| `importSharedFunction(owner, name)`                      | 从共享注册表导入函数。                         |
| `importAllSharedFunctions(owner)`                        | 导入指定来源的所有共享函数。                      |
| `importAllSharedFunctions()`                             | 导入所有共享函数。                           |
| `registerVariable(name, value)`                          | 注入全局变量，可在脚本中直接访问。                   |

每次注册都会设置脏标记，下一次 `newEnvironment()` 时自动重建缓存数组。

### FunctionSignature 构建

使用 `FunctionSignature` 定义函数的返回类型和参数类型：

```java theme={null}
import static org.tabooproject.fluxon.runtime.FunctionSignature.returns;
import org.tabooproject.fluxon.runtime.Type;

// 返回 int，接收两个 int 参数
returns(Type.I).params(Type.I, Type.I)

// 返回 Object，无参数
returns(Type.OBJECT).noParams()

// 返回 void，接收一个 String 参数
returns(Type.VOID).params(Type.STRING)

// 简写形式
FunctionSignature.returnsObject().params(Type.OBJECT)
FunctionSignature.returnsVoid().noParams()
```

### Type 常量参考

| 常量            | 对应类型    |
| ------------- | ------- |
| `Type.VOID`   | void    |
| `Type.OBJECT` | Object  |
| `Type.STRING` | String  |
| `Type.I`      | int     |
| `Type.J`      | long    |
| `Type.F`      | float   |
| `Type.D`      | double  |
| `Type.Z`      | boolean |
| `Type.NUMBER` | Number  |
| `Type.LIST`   | List    |
| `Type.MAP`    | Map     |
| `Type.FILE`   | File    |
| `Type.PATH`   | Path    |

## 扩展函数（`target::method()`）

### Builder 链式注册

```java theme={null}
import static org.tabooproject.fluxon.runtime.FunctionSignature.returns;
import org.tabooproject.fluxon.runtime.Type;

runtime.registerExtension(File.class, "fs:io")
       .function("exists", returns(Type.Z).noParams(), ctx -> {
           ctx.setReturnBool(ctx.getTarget().exists());
       })
       .asyncFunction("length", returns(Type.J).noParams(), ctx -> {
           ctx.setReturnLong(ctx.getTarget().length());
       })
       .syncFunction("getName", returns(Type.STRING).noParams(), ctx -> {
           ctx.setReturnRef(ctx.getTarget().getName());
       });
```

### Builder 方法说明

| 方法                                               | 说明                  |
| ------------------------------------------------ | ------------------- |
| `function(name, signature, callable)`            | 同步扩展。               |
| `asyncFunction(name, signature, callable)`       | 异步扩展。               |
| `syncFunction(name, signature, callable)`        | 主线程同步扩展。            |
| `sharedFunction(name, signature, callable)`      | 同步扩展 + 导出到共享注册表。    |
| `sharedAsyncFunction(name, signature, callable)` | 异步扩展 + 导出到共享注册表。    |
| `sharedSyncFunction(name, signature, callable)`  | 主线程同步扩展 + 导出到共享注册表。 |

扩展函数同样参与 `fluxon-functions.json` 导出，供 IDE/文档消费。

## 变量与全局对象

* 运行时默认注册了 `g()`，返回 `GlobalObject.INSTANCE`，便于上下文调用（如 `g() :: someExtension(...)`）。
* 其他全局对象可通过 `Environment#getRootVariables()` 验证。

## 调试与导出

* 直接打印 `runtime.getSystemFunctions()` / `getExtensionFunctions()` 查看注册结果。
* 使用 `./gradlew :core:dumpFluxonCatalog` 导出最新函数目录，保持 VS Code 补全与文档同步。

## 相关链接

* [扩展函数 API](/developer/extension-api)
* [跨 ClassLoader 函数共享](/developer/cross-cl-sharing)
* [Command 接口](/developer/commands)
* [@Export 与桥接](/developer/export-bridge)
* [运行时配置与调试](/developer/runtime-config)
* [函数目录（canonical）](/appendix/function-catalog)