AngelScript插件泛型函数实现与编译期类型检查实战-代码聚汇网

AngelScript插件泛型函数实现与编译期类型检查实战

AngstEssenSeele·2026-09-07·阅读 22 GEO检测（免费）

AngelScript泛型函数编译期检查

|难度：普通|阅读约 41 分钟

1. 项目背景与整体设计思路

先说清楚我为什么会在项目里用 AngelScript。之前做过几个需要内嵌脚本的工具型和游戏型项目，Lua、Python、Squirrel 都用过一轮，各有各的爽点，但只要你做的是对类型比较敏感的 C++ 项目，AngelScript 的体验会非常微妙——它的语法几乎就是 C++ 的轻量版，类型系统、内存模型、引用语义都和 C++ 靠得很近。这就意味着宿主 C++ 里的结构体、枚举、回调、对象引用，都能以很小的摩擦搬到脚本侧。换句话说，用 AngelScript 写插件层脚本，跟在 C++ 里写业务代码的感觉差不多，但又能热更新、可动态下发。

我要说的这个插件，核心目标是给宿主程序提供一组“通用工具函数”——日志输出、资源加载、事件订阅这类功能。它们有一个共同特点：需要支持大量不同的类型。比如日志函数，既能打印 int，也能打印 float、string、自定义的 Vector3 结构，甚至某个脚本对象。如果用传统重载去逐个注册，注册代码会爆炸，而且每加一个类型就要改一遍插件代码。这种情况下，泛型函数就成了最自然的解法。但泛型函数又带来新的问题：类型到底怎么匹配？不符合约束的类型调用为什么常常编译期不报错，运行到一半才爆炸？这些坑我都在项目里踩过，所以这篇就围绕 AngelScript 插件的泛型函数展开，重点说实现原理和“编译时检查”的几种落地手段。

适合谁看？两个群体最对口：一是准备把 AngelScript 嵌入自己项目的 C++ 开发者，二是已经在用 AngelScript、但发现泛型函数失控、想加强类型安全的人。阅读之前，最好对 AngelScript 的基本语法和 asIScriptEngine 的注册流程有一点了解，不过我会把关键 API 都展开讲，零基础也能照着抄。

1.1 为什么是 AngelScript，而不是 Lua 或 Python 绑定

很多人一听内嵌脚本，默认就是 Lua 或者 Python。确实，Lua 轻、Python 生态大，但它们和 C++ 的类型系统之间存在一层“阻抗不匹配”。Lua 所有值都是表、number、string，传一个 C++ 结构体进去要 userdata 包一层，取出来再 unbox；Python 需要维护引用计数、处理 GIL。写业务逻辑的时候不觉得，一旦你要做编辑器工具、做复杂参数校验、做序列化，这种类型割裂感会拖慢进度。

AngelScript 不一样。它本身就是按“C++ 风格的强类型语言”设计的。你可以在脚本里直接写 Vector3 v; v.x = 1.0f;，而这个 Vector3 就是 C++ 的 Vector3，注册完之后，脚本访问成员变量的开销几乎可以忽略。更关键的是，AngelScript 的编译期会做比较严格的类型检查，函数参数、返回值类型不匹配，在模块 Build 阶段就会报错，而不是拖到运行时。这一点在插件体系里特别有价值：插件的内容是用户或策划写的，编译期越早发现问题，线上运行时就越省心。

泛型函数这块，AngelScript 虽然不支持 C++ 那种完整的模板元编程，但它提供了“泛型函数注册 + asIScriptGeneric 回调”这套机制，让你可以用较少的注册代码覆盖大量类型。再配合一些设计技巧，完全可以在编译期把不合法的类型调用拦下来。这个组合拳，是 Lua/Python 绑定里很难做到的。

1.2 插件边界的划分与模块设计

做插件最忌讳的是把“脚本引擎”和“宿主功能”捆在一个模块里。刚开始做项目时我也图省事，把所有注册函数都写在一个 PluginInit 里，结果后来功能一多，每次改一行日志逻辑都要重新编译整个插件包子。后来我重新按三层梳理：

引擎层：负责 asIScriptEngine 的创建、模块加载、消息回调、通用类型注册。这一层基本稳定，不随业务变。
宿主功能层：负责把 C++ 侧的能力暴露给脚本，比如日志、资源、事件。这一层是插件的主体，泛型函数也主要在这一层注册。
业务脚本层：纯 .as 脚本，通过 import 或 interface 调用插件暴露的 API。

泛型函数放在宿主功能层有个明显好处：它面对的是“宿主能力该如何被脚本调用”的问题，而不是“脚本引擎本身该如何跑”的问题。比如 trace 日志函数，它该知道的是“如何把各种类型的参数转成字符串”，而不需要关心 AS 内部字节码怎么执行的。职责分离后，调试问题时的排查半径一下就小了。

模块与模块之间，我习惯用注册表来管理。每个功能模块在初始化时向注册表登记自己支持的类型 ID、支持的泛型约束条件，日志模块、资源模块各自独立。这样泛型函数在做编译期检查时，只需要查注册表，不需要反向依赖具体的业务模块。这个设计后面讲编译期检查时会再用到。

1.3 泛型函数在这里承担的角色

回到这个插件的具体场景。宿主程序里最常被脚本调用的几类能力，恰好都适合泛型化：

日志系统：trace(value)、warn(value)，参数可能是任意可打印类型。
缓存系统：cache.set(key, value)、value = cache.get(key)，key 和 value 都可能是不同类型。
事件总线：event.subscribe(handler)、event.emit(payload)，handler 和 payload 类型随事件变化。
资源加载：res.load(path)，返回值可能是 Texture、Sound、Mesh 等多种资源类型。

如果不泛型化，每个类型都要单独注册一个函数名，脚本侧还得记一堆 loadTexture、loadSound、loadMesh，啰嗦且难扩展。用泛型函数，一个 load 就对上全部资源类型，脚本侧写代码的体验和 C++ 模板很像。但泛型的自由也意味着风险，因为不是每个类型都能被日志系统打印、不是每个对象都能做缓存 key。所以必须在泛型的“灵活性”和编译时的“安全性”之间找平衡。这个平衡点，正是这篇文章想展开的核心。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 核心细节解析：AngelScript 泛型机制与注册原理

2.1 三种注册方式的取舍：CDECL、OBJECT 还是 GENERIC

AngelScript 注册全局函数时，最常用的是 asCALL_CDECL 和 asCALL_GENERIC，对象方法还会遇到 asCALL_THISCALL。它们区别不只是调用约定，而是注册函数入口的形态不同。

asCALL_CDECL 是最快的路径。你注册一个普通 C++ 函数，比如 void PrintLog(const std::string& msg)，引擎生成的字节码在调用时就是一次原生函数跳转，几乎零额外开销。代价是这个 C++ 函数的签名必须和脚本声明严格对应，不能动态分派，也不能处理“不固定类型”的参数。

asCALL_GENERIC 则走的是另一条路：注册的 C++ 函数签名统一是 void Func(asIScriptGeneric* gen)。所有参数、返回值、对象地址都从 gen 这个统一入口拿，开销比 CDECL 略高，但换来的是极致的灵活性。泛型函数几乎只能用这种方式实现，因为你没办法在一开始写死 C++ 参数类型。

我实际项目里的经验是：性能敏感的、参数类型固定的函数，一律 CDECL；泛型相关、需要动态检查类型的函数，用 GENERIC。不要为了省事把所有函数都注册成 GENERIC，AS 脚本本身已经比 C++ 慢，再把高频函数放进 GENERIC 会放大性能损耗。

注册方式	调用开销	参数动态性	典型场景
asCALL_CDECL	低	固定签名	日志、数学函数、对象方法
asCALL_GENERIC	中	支持任意类型	泛型函数、动态分发、反射工具
asCALL_THISCALL	低	固定签名	注册 C++ 类方法给脚本

2.2 asIScriptGeneric 回调到底是怎么跑起来的

泛型函数注册的方式是这样的：

cpp复制engine->RegisterGlobalFunction(
    "void trace(const T&in value)",
    asFUNCTION(ScriptTrace),
    asCALL_GENERIC);

字符串里的 T 是泛型占位符，脚本侧可以在任意类型上调用 trace(value)，AngelScript 在编译脚本时会为具体调用类型生成一个泛型调用点。真正执行时，引擎会构造出一个 asIScriptGeneric 对象，然后回调到你注册的 C++ 函数上。

在这个回调里，你可以拿到：

GetArgCount()：当前调用实际传了几个参数。
GetArgTypeId(index)：第 index 个参数的具体类型 ID。
GetAddressOfArg(index)：第 index 个参数的地址。注意，引用参数和值参数的取地址方式有差异，后面单独讲。
SetReturnAddress()、SetReturnObject()：设置返回值。

把这些 API 理解为“万能接线板”最合适。编译器不关心你的 C++ 函数内部到底怎么处理参数，它只负责把参数打包进 gen，再把返回值从 gen 里取出来。这个模型天然适合泛型，因为你的 C++ 代码可以在运行时判断实际类型，再分派到具体的处理逻辑。

2.3 类型 ID、类型信息与泛型实例化

AngelScript 里每个类型都有一个整数类型 ID，比如 asTYPEID_INT32 是 int，asTYPEID_FLOAT 是 float，自定义的结构体和类则通过 engine->GetTypeIdByDecl("Vector3") 获取。这个 ID 不是固定的，引擎在注册新类型或者模块编译时可能会变化，所以不要硬编码，要在初始化阶段缓存下来。

泛型函数在运行时分派的核心逻辑，其实就是“比对类型 ID”。我在日志泛型函数里会写这样的代码：

cpp复制void ScriptTrace(asIScriptGeneric* gen)
{
    int typeId = gen->GetArgTypeId(0);
    void* argPtr = gen->GetAddressOfArg(0);
    std::string output;

    if (typeId == cachedInt32TypeId)
    {
        int value = *static_cast<int*>(argPtr);
        output = std::to_string(value);
    }
    else if (typeId == cachedFloatTypeId)
    {
        float value = *static_cast<float*>(argPtr);
        output = std::to_string(value);
    }
    else if (typeId == cachedStringTypeId)
    {
        std::string* strPtr = static_cast<std::string*>(argPtr);
        output = *strPtr;
    }
    else
    {
        gen->SetException("trace(): unsupported type");
        return;
    }

    logger_->Write(output);
}

GetAddressOfArg 返回的是 void*，语义是“参数所在内存地址”。对引用类型 const T&in，这个地址就是真实对象地址；对值类型，它指向一个临时变量。无论哪种情况，你都要依据 typeId 把它正确还原成对应类型的指针，再取值。

更高级的用途是配合 engine->GetTypeInfoByTypeId(typeId) 拿到 asITypeInfo*。这个接口能让你查类型名、查父类型、查是不是模板实例，是判断“这个类型能不能作为缓存 key”这类约束的利器。

2.4 泛型函数的“编译期”到底发生了什么

AngelScript 虽然强类型，但对 asCALL_GENERIC 注册的泛型函数，引擎在脚本编译期能做的检查是很有限的。它只知道“这个调用点用了一个具体类型替换了 T”，但不会知道你的 C++ 实现内部接不接受这个类型。所以经常出现这种情况：脚本 Build 通过了，运行到某一帧突然抛异常，提示 trace(): unsupported type。这对线上环境是不可接受的。

所谓“泛型函数编译时检查”，本质上是要在模块 Build 之前或 Build 过程中，把不合法的类型调用拦截下来。实现思路有三条，我在项目里都试过，效果从弱到强分别是：

利用函数重载：不注册泛型函数，而是注册一组同名但参数类型固定的函数，让 AngelScript 编译器自己去重载决议。类型不合法时，编译器自然会报“没有匹配的重载”。
注册期约束检查：在注册泛型函数时，用 C++ 模板特化或 if constexpr 去限制允许的类型，不满足条件的类型干脆不生成注册项。
Build 期消息拦截：通过 SetMessageCallback 捕获编译错误，在回调里结合泛型约束注册表做二次过滤，输出可读的错误提示。

这三种方案不是互斥的，生产级插件我建议按组合方式用。具体怎么落地，下面实操章节直接给代码。

3. 实操过程：从零实现一个带编译时检查的泛型插件

3.1 插件基础框架与注册入口

假定你已经有环境，asIScriptEngine* engine 已创建好，模块也已初始化。插件入口长这样：

cpp复制// 插件入口，在宿主程序初始化时调用
void RegisterPlugin(asIScriptEngine* engine)
{
    engine->SetMessageCallback(asFUNCTION(MessageCallback), nullptr, asCALL_CDECL);

    // 缓存常用 typeId
    cachedInt32TypeId = engine->GetTypeIdByDecl("int");
    cachedFloatTypeId  = engine->GetTypeIdByDecl("float");
    cachedStringTypeId = engine->GetTypeIdByDecl("string");
    cachedVec3TypeId   = engine->GetTypeIdByDecl("Vector3");

    // 注册泛型工具函数
    RegisterTraceFunctions(engine);
    RegisterResourceFunctions(engine);
    RegisterEventFunctions(engine);
}

这个入口是被宿主动态调用的，所以插件可以做成 DLL，也可以静态链接。个人建议在开发期先静态链接，方便打断点，成熟后再拆 DLL。

3.2 方案一：用 GENERIC 实现真正的泛型分发

第一个要做的功能是日志系统的 trace。它采用真正的泛型函数，脚本侧任意类型都可传入，但支持类型由 C++ 侧决定。代码前面展示过核心部分，这里补全一下：

cpp复制void RegisterTraceFunctions(asIScriptEngine* engine)
{
    engine->RegisterGlobalFunction(
        "void trace(const T&in value)",
        asFUNCTION(ScriptTrace),
        asCALL_GENERIC);
}

void ScriptTrace(asIScriptGeneric* gen)
{
    int typeId = gen->GetArgTypeId(0);
    void* argPtr = gen->GetAddressOfArg(0);

    std::string output;
    if (!ConvertToString(typeId, argPtr, output))
    {
        gen->SetException("trace(): unsupported type, please check the plugin docs");
        return;
    }

    plugin_logger_->Write(output);
}

ConvertToString 是一个根据 typeId 做分派的工具函数，我建议把所有类型的转字符串逻辑都集中到它里面，方便统一维护。

这种方案的好处是注册代码极简，加一个可打印类型只需在 ConvertToString 里加一个分支。但注意，SetException 是在运行时抛异常，不是编译期。也就是说，脚本里如果写了 trace(SomeUnsupportedType)，Build 不会失败，运行到这一行才炸。功能是能用的，但对插件提供方来说，排查成本偏高。

3.3 方案二：用模板生成一组同名重载，拿到编译期检查

为了把类型不合法的问题从运行期提前到编译期，我第二个方案是干脆不注册真正的泛型函数，而是用 C++ 模板批量注册一组“看上去一样”的重载。

举例，资源加载模块的 load 函数：我只想让脚本侧允许加载 Texture、Sound、Mesh 三种类型。写法拆成注册端和脚本端：

cpp复制template <typename T>
T* LoadResource(const std::string& path)
{
    return ResourceManager::Get().Load<T>(path);
}

template <typename T>
void RegisterLoadOverload(asIScriptEngine* engine)
{
    std::string decl = "T@ load(const string&in path)";
    engine->RegisterGlobalFunction(
        decl.c_str(),
        asFUNCTION(LoadResource<T>),
        asCALL_CDECL);
}

void RegisterResourceFunctions(asIScriptEngine* engine)
{
    RegisterLoadOverload<Texture>(engine);
    RegisterLoadOverload<Sound>(engine);
    RegisterLoadOverload<Mesh>(engine);
}

这段代码的关键在于：T@ load(const string&in path) 声明了一个泛型风格的函数声明，但 asFUNCTION(LoadResource<T>) 传入的是一个具体的 C++ 模板实例。AngelScript 注册多个同名函数只要参数或返回类型不同即可重载，这里靠返回类型不同来区分多个 load 版本。当然，AS 的重载决议对返回类型参与并不像 C++ 那样直观，如果遇到歧义，建议把函数名拆成更明确的语义，比如 loadTexture、loadSound，或者把资源类型作为第一个参数传入。

测试效果时，脚本侧写：

as复制Texture@ tex = load("ui/icon.png");    // 编译通过
Sound@ snd = load("bgm/main.ogg");     // 编译通过
Vector3@ v = load("bad");              // 编译失败，提示没有匹配的load重载

这个方案让我得到了真正的编译期类型检查。脚本调用不合法的资源类型时，构建模块会直接报错，错误位置、调用行号都能打印出来。这个体验对内容开发人员非常友好。

3.4 方案三：注册元数据约束，做一个可扩展的类型白名单

有了重载方案打底，我发现还可以进一步扩展：让插件支持“自定义类型也能通过注册表进入 load 白名单”。这需要把资源类型管理从硬编码改为查表，配合脚本编译时的消息回调。

做法是：

cpp复制// 资源类型注册表
struct ResourceTypeInfo
{
    std::string scriptDecl;
    asIObjectType* objType = nullptr;
};

std::unordered_map<std::string, ResourceTypeInfo> resourceRegistry;

// 注册一个资源类型
void RegisterResourceType(asIScriptEngine* engine, const std::string& scriptDecl)
{
    ResourceTypeInfo info;
    info.objType = engine->GetObjectTypeByName(scriptDecl.c_str());
    info.scriptDecl = scriptDecl;
    resourceRegistry[scriptDecl] = info;

    // 为该类型注册一个 load 重载
    std::string decl = scriptDecl + "@ load(const string&in path)";
    engine->RegisterGlobalFunction(decl.c_str(), asFUNCTION(LoadResourceByType), asCALL_GENERIC);
}

void LoadResourceByType(asIScriptGeneric* gen)
{
    std::string* path = static_cast<std::string*>(gen->GetAddressOfArg(0));
    int retTypeId = gen->GetReturnTypeId();
    // 根据 retTypeId 反查注册表并调用对应资源加载器
    // ...
}

这样外部模块想暴露新的资源类型，只需调用 RegisterResourceType(engine, "AudioClip")，不用改现有泛型函数代码。同时，脚本侧如果调用了注册表里不存在的类型，AngelScript 编译器在重载决议时找不到匹配函数，会产生编译错误。

这里补充一个细节：泛型函数声明里，返回类型用 T@ load(...) 时，返回的对象类型不同也会影响重载决议。如果你遇到“返回类型明明是 A 却选到了返回 B 的函数”这种诡异现象，多半是类型注册命名冲突了，检查一下不同类型的 name 是否完全一致。

3.5 把编译期检查完整接入 Build 流程

上面三步只解决了“注册”层面，真正把编译期检查落到实处，还得靠一个东西：SetMessageCallback。

cpp复制void MessageCallback(const asSMessageInfo* msg, void* param)
{
    const char* type = "INFO";
    if (msg->type == asMSGTYPE_ERROR)      type = "ERROR";
    else if (msg->type == asMSGTYPE_WARNING) type = "WARNING";

    plugin_logger_->Write("%s [line %d] %s", type, msg->row, msg->message);
}

// 构建脚本模块时
int BuildModule(asIScriptModule* mod)
{
    int r = mod->Build();
    if (r < 0)
    {
        // 这里有错误输出，能精确定位到脚本里出错的行号
        return r;
    }
    return 0;
}

通过消息回调，脚本中的错误会被统一收集。比如重载决议失败时，回调里会给出类似“No matching overload found for function 'load'”的提示，行号也是准确的。插件侧要做的只是把这些信息格式化后展示给开发者。

更进一步，如果要在 Build 之前主动执行前置检查，比如扫描脚本 AST（AngelScript 没开放完整 AST，但可以通过 module->GetFunctionCount()+GetFunctionByIndex 做后置扫描，再结合脚本手动标记 // @resource 注释做约定检查），这类高级玩法视项目需求再补齐。大多数情况下，重载注册表 + 消息回调已经能覆盖 90% 的编译期类型检查需求。

4. 常见问题与排查技巧实录

4.1 “编译通过但运行时报错”的类型不匹配该怎么查

这是泛型函数最常见的病症：脚本 Build 完全正常，运行到某个调用点突然异常。原因一般是两种：一类是我在 3.2 节说的，用 asCALL_GENERIC 注册的泛型函数，内部运行时才发现类型不支持；另一类是参数是对象引用时，GetAddressOfArg 拿到的是句柄地址而不是对象地址，类型一不对就访问越界。

排查套路我是这么走的：

先在 SetMessageCallback 里把 AS 原生报错打开，看运行时有没有 out-of-bounds 或 null handle 异常。
在泛型回调入口处临时加日志，打印 typeId 和参数数量，看实际收到的类型是否和预期一致。
因为 AngleScript 会为泛型调用生成独立的调用点，你可以用 engine->GetTypeInfoByTypeId(typeId)->GetName() 把类型名打印出来，快速定位是哪一个脚本类型不符合约束。

如果是为了线上稳定性，我强烈建议把“运行时不支持类型”也设计成可恢复的异常，比如 SetException 之前先把错误写入日志，再正常抛异常，这样不会白屏或闪退，还能保留现场。

4.2 类型 ID 里的 const 和引用修饰符是怎么回事

我最初写泛型日志函数时，踩过一个很隐蔽的坑：注册声明里写的是 const T&in value，但实际运行时 GetArgTypeId(0) 返回的类型 ID 和 engine->GetTypeIdByDecl("int") 对不上。一度百思不解，后来打印出来才发现，脚本里传 int 字面量时，引擎传给 generic 的类型 ID 是 int 的引用或 const 变体。

AngelScript 的类型 ID 包含类型的基本信息，但像 const、& 这类修饰符由额外的类型标志位表示。比较类型时不能只看整型 ID 相等，要先把修饰符位去掉，或者直接用 engine->GetTypeInfoByTypeId() 后比较类型对象指针。我封装了一个工具函数，专门做“剥掉修饰符后的类型匹配”：

cpp复制bool IsSameType(int typeIdA, int typeIdB)
{
    // 去掉类型标志位中的引用/句柄/const位
    int flagMask = asTYPEID_OBJHANDLE | asTYPEID_HANDLETOCONST | asTYPEID_MASK_OBJECT;
    return (typeIdA & ~flagMask) == (typeIdB & ~flagMask);
}

这段代码能解决大多数误导性的不匹配。顺带一提，AngelScript 版本迭代中类型标志位的定义有细微变化，我是基于 2.34 左右版本的 API 写的，如果你用的版本更早或更新，注意查一下 asTYPEID_* 常量的定义。

4.3 重载决议不按预期走的几种情况

用重载方案模拟泛型时，最难受的就是脚本里的隐式类型转换。比如注册了 void foo(float) 和 void foo(int)，脚本里写 foo(1)，你觉得会调 int 版本，但 AS 的隐式转换规则可能直接选了 float 版本，因为整型字面量可以被隐式转换成 float。这类问题没有银弹，只能靠“注册时就避免模糊重载”。我的经验是：

泛型场景里尽量少用基础类型的同名重载，改成 fooInt、fooFloat 这种语义明确的函数名。
如果确实需要同名重载，参数必须带上显式的类型标记，比如把 int 版本声明成 void foo(int value, bool = true)，用默认参数区分。
用 RegisterGlobalFunction 注册时，参数的默认值也可以参与重载决议，这反而能模糊匹配，注意不要滥用。

一般内容团队会更喜欢明确的、一眼能看出类型的函数名。我们做插件的人不要为了表面上的“通用”而牺牲可读性，毕竟编译期检查是为了减少沟通成本，而不是制造新的心智负担。

4.4 插件卸载与函数指针生命周期

插件做成 DLL 之后，卸载顺序非常重要。AngelScript 引擎持有注册函数的 C++ 函数指针，如果插件先卸载 DLL，再释放引擎，回调函数地址就变成了悬挂指针，任何一次调用都会导致崩溃。这个问题我见过不止一次，排查起来还特别隐蔽，往往表现为“退出程序时才崩溃”。

正确顺序是：

先销毁所有 asIScriptModule，清理所有脚本上下文。
再释放 asIScriptEngine。
最后卸载插件 DLL。

如果宿主程序对插件热更新有要求，建议用独立线程加载/卸载插件，并把引擎实例和插件 DLL 的存活周期绑定。更稳妥的做法是，注册函数不直接写在插件 DLL 的导出函数里，而是注册到一个静态函数表中，由插件 DLL 内的生命周期管理对象统一维护，引擎回调时先查表，表里没有就不调用。这样即使 DLL 已被卸载，也只是查表失败，不至于直接崩。

4.5 泛型函数的性能实测与优化建议

很多人担心 asCALL_GENERIC 的开销。我做过一次粗测：同样一个“两个 int 相加”的简单函数，CDECL 调用大概比 GENERIC 快 20%~30%。这是有道理的，GENERIC 要把所有参数包进 asIScriptGeneric，再在回调里解包，多了一层间接跳转。

但如果泛型函数内部做的事情本身就很重，比如日志格式化和 IO 输出，这点性能差异可以忽略。真正要避免的是在每帧高频调用路径上使用 GENERIC 泛型，比如每帧更新位置的函数。这类函数建议注册成 CDECL 的固定签名，预留脚本层调用，不要图一时方便写一个通用 Transform 处理接口。做插件和做业务一样，性能和安全都是设计出来的，不是优化出来的。

5. 实操心得与后续扩展思路

项目做完回头看，AngelScript 泛型函数这套机制最让我省心的，是它把“脚本侧的开发自由”和“宿主侧的类型安全”揉在了一起。真正让我避免线上事故的，不是更聪明的运行时判断，而是那套重载注册表配合消息回调的编译期拦截。每次脚本开发者写错类型，构建阶段就能看到“No matching overload”和行号，基本不用再来回找我问“为什么这里运行时才炸”。

如果再给我一次机会，我会在一开始就把类型注册表设计好，而不是写一堆 if-else 的分派逻辑。注册表的好处不只是扩展方便，它还能充当文档：打开注册表文件，就能看到这个插件支持哪些类型、有哪些泛型约束。后续如果要把这套机制迁移到别的脚本引擎，注册表的数据结构也能直接复用。

一个还想继续做的方向是：把编译期检查从“函数重载决议”推进到“脚本侧泛型类约束”。比如让脚本开发者可以自己声明一个泛型函数，但加上类似 where T : ITraceable 的约束，在模块 Build 时通过 asITypeInfo 的父类型接口检查来自动拒绝不符合约束的类型。这个功能 AngelScript 原生没有，但结合消息回调和自定义的预处理脚本是可以拼出来的。目前原型我已经跑通了一版，效果还不错，等打磨稳定之后我再单独写一篇。