Artheru：Initial bilingual draft (auto-published)

2026-05-16T11:42:52Z

Initial bilingual draft (auto-published)

新页面

<languages/>

== 概述 / Overview ==
LessokajiWeaver 是 MDCS 用到的 ''编译后处理''工具链（基于 Fody）。它在 C# 程序集编译完成后做 IL 注入，自动生成 ''字段代理类''、''属性序列化代码''、''反射加速''等基础设施代码，让插件作者只需写少量声明性属性，剩下的"管道"由 Weaver 自动织入。

LessokajiWeaver is MDCS's post-compile IL-weaving toolchain (Fody-based). It runs after C# assembly compilation and injects IL to generate ''field-proxy classes'', ''property serialisation'', ''reflection accelerators'', etc. Plugin authors write a few declarative attributes; the plumbing is woven in automatically.

== 主要场景 / Main scenarios ==
{| class="wikitable"
! 场景 / Scenario !! Weaver 做的 / What Weaver does
|-
| Medulla `[AsUpperIO]` / `[AsLowerIO]` 字段 || 生成代理 setter / getter，自动同步到 DObject
|-
| Medulla `[AsInitParam]` || 生成 JSON 序列化代码，绑定到启动配置加载
|-
| Medulla `[IOObjectMonitor]` || 注册到监控面板 + Web API
|-
| CycleGUI `[Cyclic]` 协程方法 || 自动包装为 IEnumerable<Cycle> 安全宿主
|-
| Clumsy `[MovementTest]` || 注册到测试 UI 面板
|-
| 多语言（i18n）字符串字段 || 生成查表逻辑（见 [[Special:MyLanguage/自动I18N（多语言功能）|自动 I18N]]）
|}

== 工作流程 / Pipeline ==

开发者 .cs → csc 编译 → .dll
│
▼
LessokajiWeaver.Fody (post-build)
│
▼
织入后的 .dll
│
▼
Medulla / Clumsy 运行时加载

工程引用方式（已由 [[Special:MyLanguage/MDCS-plugin-helper|MDCS-plugin-helper]] 模板自动配置）：

In a plugin's .csproj (auto-configured by the plugin-helper template):

<syntaxhighlight lang="xml">
<ItemGroup>
<PackageReference Include="Fody" Version="6.x" />
<Reference Include="LessokajiWeaver.Fody">
<HintPath>..\tools\LessokajiWeaver.Fody.dll</HintPath>
</Reference>
<Reference Include="LessokajiWeaverUtilities">
<HintPath>..\tools\LessokajiWeaverUtilities.dll</HintPath>
</Reference>
</ItemGroup>
</syntaxhighlight>

`FodyWeavers.xml` 在工程根目录：
<syntaxhighlight lang="xml">
<Weavers>
<LessokajiWeaver/>
</Weavers>
</syntaxhighlight>

== 为什么用 Weaver / Why weave ==
不用 Weaver 也能用反射做同样的事，但每次访问字段都付反射开销（~100x getter）。Weaver 在编译期把反射调用 ''变成普通 IL''，运行时零开销：

Without Weaver you'd use reflection at runtime, paying ~100× cost per access. Weaver moves the reflection to compile-time, generating direct IL with zero runtime overhead:

<syntaxhighlight lang="csharp">
// 开发者写：
[AsUpperIO]
public float vCmd;

// 编译后 Weaver 注入相当于：
private float _vCmd;
public float vCmd
{
get => _vCmd;
set
{
_vCmd = value;
IOSync.PostToDObject(this, "vCmd", value); // 自动 IPC
}
}
</syntaxhighlight>

== 调试 / Debugging ==
* 织入失败：检查 `bin\<config>\` 下是否有 `FodyWeavers.xml` 编译报错；通常是属性用法错误（如把 `[AsUpperIO]` 加在 readonly 字段上）。
* 织入产物可视化：用 ILSpy / dnSpy 打开织入后的 dll，查看 setter / getter 注入逻辑。
* 性能 / Performance: Weaver 不引入额外运行时依赖；增加的体积通常 < 5%。

== 兼容性 / Compatibility ==
* .NET Framework 4.6.2+ / .NET 6+
* 必须用 ''Release 模式''发布插件（Weaver 在 Debug 也运行，但 Debug 会保留更多调试符号导致体积偏大）。
* 与 ''AOT 编译''不兼容（IL 注入依赖 JIT）。

== 与 LessokajiWeaverUtilities 的关系 / Utilities ==
`LessokajiWeaverUtilities.dll` 是 Weaver 注入代码运行时依赖的小库（attribute 定义 + 工具方法）。插件 csproj 必须引用，但开发者一般不直接调用。

`LessokajiWeaverUtilities.dll` is the runtime support library (attribute definitions + helpers). Plugin csproj must reference it but developers rarely call into it directly.

== 相关页面 / See also ==
* [[Special:MyLanguage/Medulla|Medulla]] / [[Special:MyLanguage/Medulla软件架构|Medulla软件架构]]
* [[Special:MyLanguage/自动I18N（多语言功能）|自动I18N（多语言功能）]]
* [[Special:MyLanguage/如何使用LessokajiWeaver的多语言功能|如何使用LessokajiWeaver的多语言功能]]
* [[Special:MyLanguage/MDCS引擎适配机器人入门教学|MDCS引擎适配机器人入门教学]]

[[Category:二次开发相关说明]]

LessokajiWeaver编译后处理工具 - 版本历史

Artheru：​Initial bilingual draft (auto-published)

Artheru：Initial bilingual draft (auto-published)