Airi stage-tamagotchi-godot 引擎 C# 开发方法薄场景脚本、类型驱动边界与 dotnet format 校验【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本文围绕 Airi 仓库中engines/stage-tamagotchi-godot这个 Godot C# 舞台引擎的本地开发技能文档展开介绍该引擎的 C# 代码分层模型场景脚本 / 运行时核心 / 契约与传输 / 注册与发现 / 工具与编辑器支持、反射只用于发现、LINQ 只用于冷路径、async 只用于 I/O 边界的功能使用准则以及配套的.editorconfig风格基线与dotnet format --verify-no-changes校验流程。读完后你可以直接按照这套引擎本地规范审查或编写 Godot 侧 C# 代码并知道如何验证改动。1. 适用范围引擎本地技能不是仓库级 C# 标准该技能的边界定义非常明确只有当改动全部位于engines/stage-tamagotchi-godot目录之下时才使用这套 C# 开发方法作为治理性指令。具体覆盖范围包括Godot 场景脚本.cs文件项目文件.csproj引擎本地的.editorconfig该引擎内的 Godot 特定 C# 结构决策文档明确列出了不适用场景TypeScript、Electron 渲染层代码、共享的 workspace 配置、仓库根目录的 C# 约定或engines/stage-tamagotchi-godot之外的任何文件。一旦任务跨越这条目录边界就应当停止使用这套规范。配套的 开发方法文档 也在开头重复了这一限定This guide applies only toengines/stage-tamagotchi-godot并且专门强调不要把本指南当成仓库级 C# 标准。这一改动局部化于引擎的原则同样适用于反向操作不要把这套 C# 规则推入仓库根配置或其他工作区。2. 三级文档体系先读结构再读风格修改 C# 文件之前规范要求的阅读顺序是engines/stage-tamagotchi-godot/docs/csharp-development-method.md —— 结构与功能使用的首要事实来源primary source of truthengines/stage-tamagotchi-godot/.editorconfig —— 格式与命名的次级指导engines/stage-tamagotchi-godot/docs/csharp-style.md —— 仅用于低层代码风格的次级参考。csharp-style.md 自身也声明了这种从属关系先读docs/csharp-development-method.md获取结构、分层与功能使用指导本文件仅用于低层代码风格。风格文档的基线来源包括 Microsoft 通用 C# 代码约定、.NET 代码风格规则选项以及 Godot C# 风格指南但它不定义运行时结构、nullable 策略、命名空间策略或更广泛的架构规则——这些全部归开发方法文档所有。3. 编写前先分类改动五层模型在动代码之前规范第一步是对改动分类。开发方法文档把引擎 C# 代码划分为五个层次层职责引擎内对应源码位置从源码结构看1. Scene ScriptGodot 拥有的Node/Node3Dpartial 类、生命周期入口点、场景绑定scripts/StageRoot.cs2. Runtime Core纯 C# 运行时逻辑控制器、协调器、状态持有者、服务scripts/scene/StageSceneController.cs、scripts/view/ 下的StageViewRuntime、StageViewStateStore等3. Contract and Transport消息类型、设置快照、ready/fatal/shutdown/状态更新载荷scripts/transport/ 下的StageEnvelope、StageBridge、StageSceneApplyPayload等4. Registry and Discovery描述符、启动期发现、目录与查找表规范列为预留层用于启动期模块发现类代码5. Tooling and Editor Support面向 inspector 的辅助、导入/导出辅助、仅编辑器/调试用的数据装配scripts/dev/StageDevObservationAdapter.cs文档同时给出了一条硬约束默认不要把上述职责坍缩进单个 Godot 脚本。4. 本地设计方法六条准则与源码印证技能文档给出的本地设计方法可以概括为六条每一条都能在该引擎的实际源码中找到落地样本。4.1 保持场景脚本薄keep scene scripts thin场景脚本只用于Godot 生命周期入口点如_Ready节点查找与场景接线把控制权交给运行时对象把 Godot 回调桥接进显式的运行时代码而以下内容不应直接写进场景脚本除非代码极为简单传输协议处理、注册表构建、复杂状态迁移、业务/游戏规则、大型数据变换管线。判断信号也很明确——如果一个场景脚本同时拥有生命周期、运行时状态、协议处理和工具配置就应该拆。StageRoot.cs 是这一准则的直接样本。它的 XML 注释显式记录了调用链Godot scene tree - _Ready - StageBridge.Connect - _Process - StageBridge.Poll - HandleMessage其_Ready只做接线解析AvatarRoot/Camera3D节点然后构造StageSceneController、StageViewRuntime、StageRenderEffectsRuntime等纯 C# 运行时对象_Process只是逐帧Poll各协调器。消息分发集中在HandleMessageStageRoot.cs#L185-L226通过switch (envelope.Type)把host.scene.apply、host.view.patch、host.shutdown等消息类型路由到各自的专用方法——场景脚本本身不承载协议语义之外的持久逻辑。4.2 把持久逻辑下沉到纯 C# 运行时对象开发方法文档的 Runtime Core 规则偏好小的协调器而非大而全的类、显式状态对象而非隐藏可变标志、依赖通过构造器或方法注入、显式调用流而非隐式控制转移并且运行时核心代码应当便于在调试器中追踪用显式的 map、状态与控制流优先于精巧的抽象。StageSceneController.cs 是一个典型的纯 C# 运行时对象它是sealed class不是 Node通过构造器注入Node3D avatarRoot与VrmAvatarLoader职责是持有当前展示的 avatar 节点并原子地应用新的场景输入——其注释明确写了前一个 avatar 只在新导入成功之后才被移除。scripts/view/目录下还有StageCameraPoseController、StageCameraInputController、StageViewStateRules、StageViewStateStore等按职责切分的控制器与状态持有者体现了小协调器的思路。4.3 用类型显式化子系统边界契约与传输层规则要求跨边界通信必须类型驱动传输消息、载荷、设置快照、描述符、注册表条目、运行时状态快照都要有显式类型。明确禁止以Dictionarystring, object?作为默认契约形状、魔法字符串协议散落各文件、匿名对象跨越子系统边界、用注释代替真正的类型定义。文档给出的原则一句话就是先用类型定义边界再围绕这些类型实现传输。引擎中的信封契约就是一个最小化的类型化例子——StageEnvelope.cs 仅一行核心定义public sealed record StageEnvelope(string Type, JsonElement? Payload);而具体消息载荷则各自有独立类型文件StageSceneApplyPayload、StageViewPayloads、StageViewJson等位于 scripts/transport/StageBridge.cs 这个 sealed 纯 C# 类负责持有WebSocketPeer、逐帧Poll并经由SendEnvelope发送类型化的 JSON 信封{ type, payload }。4.4 反射用于发现不用于执行LINQ 用于冷路径查询开发方法文档对反射与 LINQ 的边界划得很清反射的正当用途启动期模块发现、特性元数据读取、描述符生成、编辑器/工具支持。反射的禁区逐帧逻辑、运行时热路径分发、核心状态机执行、稳态运行中的重复动态调用。LINQ 的正当用途构建注册表、过滤描述符、配置投影、调试或工具视图。LINQ 的禁区热路径、逐帧循环、反复执行的运行时查询——此时显式索引或字典更清晰也更廉价。文档给出的心智模型值得直接引用reflection builds the catalogue反射构建目录 LINQ shapes and queries the catalogueLINQ 塑形并查询目录 runtime executes through explicit structures运行时通过显式结构执行4.5 async 只用于 I/O 与进程边界异步策略同样以边界为判据适合 async 的边界socket 与传输建立、文件 I/O、宿主机侧进程交互、天然异步的启动加载不适合下推 async 的位置逐帧更新、核心运行时循环、应当保持显式的时序敏感行为明确禁止用 async 掩盖生命周期或顺序问题。这一点与 StageBridge.cs 的实现方式一致WebSocket 采用 Godot 的WebSocketPeer非阻塞模型由_Process逐帧Poll()泵出连接状态与消息包而不是在帧循环中引入 async 状态机——异步止步于 I/O 边界帧内执行保持显式同步。5. 低层风格基线.editorconfig 与 csharp-style.md在结构规则之上引擎本地还有一份低层风格基线csharp-style.md的 Rules 与 .editorconfig 对应规则说明.editorconfig中的落地4 空格缩进、LF、UTF-8全文件生效indent_style space、indent_size 4、end_of_line lf、charset utf-8对*.cs,*.csproj,*.props,*.targets,*.sln限定 100 列上限Allman 大括号开括号另起一行csharp_new_line_before_open_brace allSystem.*using 置顶之后按字母排序dotnet_sort_system_directives_first true、dotnet_separate_import_directive_groups false关键字类型优先string、int、bool而非String等dotnet_style_predefined_type_for_locals_parameters_members true:suggestion等var仅在类型显然时内建类型一律不用varcsharp_style_var_for_built_in_types false、csharp_style_var_when_type_is_apparent true、csharp_style_var_elsewhere false命名约定类型/成员PascalCase局部/参数camelCase私有字段_camelCasedotnet_naming_rule.private_fields_should_be_underscore_camel_caseseverity 为suggestion移除未使用的 using触碰到的文件中dotnet_diagnostic.IDE0005.severity warning移除 Godot 模板注释触碰到的文件中由人工/dotnet format清理移除空的 lifecycle 方法除非有意保留同上保持 using 显式不启用 implicit usings测试工程 tests/stage-tamagotchi-godot.tests/stage-tamagotchi-godot.tests.csproj 中也显式设置了ImplicitUsingsfalse/ImplicitUsings注意 StageRoot.cs 的 using 顺序与string/int关键字类型、_camelCase私有字段如_bridge、_shutdownRequested都能逐条对上这份基线。6. 运行环境前提Godot 4.7、.NET 10 与固定的 C# 语言版本从当前仓库的工程文件可以确认这套 C# 规范的适用前提stage-tamagotchi-godot.csproj使用Godot.NET.Sdk/4.7.1TargetFramework为net10.0RootNamespace为StageTamagotchiGodot并显式把.godot生成源码与tests/**排除在游戏程序集之外Directory.Build.props把LangVersion固定为14.0注释说明其意图是防止更新的 SDK 悄悄改变引擎的语言版本同时保证 Godot 程序集与其本地验证宿主共用同一运行时契约global.json锁定 .NET SDK10.0.100rollForward: latestFeatureallowPrerelease: false。也就是说阅读或修改该引擎 C# 代码时前提是具备 .NET 10 SDK 与 Godot 4.7 工具链且语言特性以 C# 14 为上限。7. 校验流程dotnet format 与本地测试宿主修改 C# 文件或引擎本地.editorconfig之后规范要求从engines/stage-tamagotchi-godot目录内执行校验命令dotnet format --verify-no-changes若校验失败是由改动范围之外的既有文件引起的规范的处理方式是明确报告这一点而不是悄悄扩大编辑集——这避免了以格式修复为名把无关文件卷入本次变更。结合 package.json 中的脚本定义完整的查看/构建/测试方式为构建与类型检查dotnet build ./stage-tamagotchi-godot.slnxbuild与typecheck脚本均为该命令引擎本地验证宿主dotnet run --project ./tests/stage-tamagotchi-godot.tests/stage-tamagotchi-godot.tests.csprojtest脚本该测试工程通过ProjectReference引用主程序集自身不启用 implicit usings、不生成AssemblyInfo只作为验证宿主存在此外引擎还配有 tests/material-rendering-check/ 的场景化渲染检查与 tools/ 下的渲染阶段导出脚本用于渲染管线相关的开发验证。8. 暂缓决策清单不要凭风格工具猜测开发方法文档第 8 节专门列出了有意暂缓、不应被猜测的决策项可空引用类型NRT的推行策略命名空间策略record的使用边界required成员的使用边界主构造函数的使用边界;辅助层helper-layer与场景脚本各自的功能许可范围。文档的要求是当其中某一项真正变得相关时显式做出决策并把它写进引擎本地指导而不是从风格工具如 IDE 建议里反推。这保证了规范演进的显式性——当前源码中StageEnvelope已经用到了record与可空类型属于既成实现但整体推行策略仍以文档显式决策为准。9. 小结这套引擎本地 C# 开发技能可以压缩为一张检查清单边界检查所有触碰的文件都在engines/stage-tamagotchi-godot之内否则换用别的治理指令先读文档csharp-development-method.md结构→.editorconfig/csharp-style.md风格分类改动场景脚本 / 运行时核心 / 契约与传输 / 注册与发现 / 工具与编辑器支持执行设计方法薄场景脚本、逻辑下沉纯 C#、类型化边界、反射只做发现、LINQ 只做冷路径、async 止步 I/O 边界对齐风格基线4 空格、LF、UTF-8、100 列、Allman、System.*置顶、关键字类型、var从紧、_camelCase私有字段跑校验dotnet format --verify-no-changes范围外的既有失败如实报告而不扩大编辑集。整套规范的设计意图在于让一个多进程、多引擎协作的 monorepo 中Godot 侧的 C# 代码保持自身可追踪调试器友好、边界可编译类型驱动契约、风格可机器验证dotnet format同时不向仓库其余部分扩散。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
