API Host NativeTypeAttribute

NativeTypeAttribute

标记导出静态成员构成脚本 Type、可选实例表面使用原生 CLR 存储的 sealed partial CLR 类。

命名空间：AuroraScript.Hosting。类型：class。

返回 .NET 宿主 API 参考 · 脚本原生类型

概述

含实例导出或导出构造函数的类型必须派生 ScriptObject。生成代码会加上 IAuroraNativeInstance 标记。普通实例方法会注册到该 NativeType 独享的惰性原型；只有不存在可写导出槽时才冻结。原生字段和 getter/setter 则由生成的属性访问重写直接处理。恰好一个 public 构造函数可标 [Export] 以启用脚本 new；没有导出构造函数时该 Type 不可构造。引擎自有的值接收者通过 NativeReceiverType 声明 CLR 表示，用 [ReceiverExport] 标记实例 Core，并可用 NativeConstructor 命名已导出的静态 Core，供 Type(...) 与 new Type(...) 共用。

[NativeType("Vec2")]
public sealed partial class Vec2 : ScriptObject
{
    [Export("x")] public double X;
    [Export("y")] public double Y;

    [Export]
    public Vec2(double x, double y) : base(NativePrototype)
    {
        X = x;
        Y = y;
    }

    [Export("length")]
    public double LengthCore() => Math.Sqrt((X * X) + (Y * Y));
}

通过 EngineOptions.WithCompiler(c => c.WithNativeTypes(typeof(Vec2))) 加入引擎 catalog。需要挂到嵌套对象时再调用 Vec2.Register(target)。

脚本侧在 @global() 文件中手写匹配的 declare type，仅供编辑器使用。

构造函数

NativeTypeAttribute(string typeName)

属性

• string TypeName — 脚本全局名，同时也是 Type 的 typeof 结果（值为 "type" 的 Type 对象名，例如 Vec2）。
• Type NativeReceiverType — 可选；引擎自有值实例的 CLR 表示，目前支持 string、double、long 和 ulong。
• string NativeConstructor — 可选；值接收者的调用/new 工厂 Core 名。它必须指向静态 Type 导出，返回类型必须匹配 NativeReceiverType。

规则

• 类必须是 public sealed 顶层类型。Persistence / OnlyRun 会把直调发到独立生成程序集，因此不支持 internal NativeType。
• 实例字段必须是 public 的 double、int、bool 或 string。
• 实例方法使用与静态导出相同的 Core 签名，但没有 thisObject 参数。
• 存在普通实例方法时，生成器生成 NativePrototype 和 RegisterNativeMembers。用户编写的每个构造函数必须显式调用 base(NativePrototype)；生成器创建的构造函数会自动调用。
• 仅含原生字段、getter/setter 或静态导出的类型不生成 NativePrototype，可以使用普通 ScriptObject 构造函数。
• 方法默认不可写且不可枚举；可通过 Writable、Enumerable 显式改变。可写方法不进入 Native 直调目录。
• 静态工厂返回原生实例时保留具体类型推断与直调。
• 详见脚本原生类型。

参见

• IAuroraNativeInstance
• ReceiverExportAttribute
• ExportAttribute
• CompilerOptionsBuilder.WithNativeTypes