Godot 引擎项目里用 C# 的人这几年明显变多了但网上的资料大多停在“装好环境跑个 Hello World”就结束真到自己写逻辑时在 GDScript 和 C# 之间切换的那道坎反而没人细讲。这篇基础学习笔记是我自己在完成第七个练习项目后用 C# 重写核心模块时攒下的记录适合已经会一点 GDScript、想转 C# 的开发者也适合纯 C# 背景、第一次碰 Godot 的新手。我会从环境选型讲到角色控制器的完整实现最后把那些文档里没写透的坑一个个翻出来。1. 为什么在 Godot 里选 C#不只是“换一门语言”1.1 从 GDScript 到 C# 的真实动机先说动机不然后面所有细节都失去方向。我最初跟着官方文档学的时候用的也是 GDScript毕竟教程、别人的开源 Demo、插件脚本基本都是它。但项目从“写着玩”进入“正经做系统”阶段后GDScript 的几个短板会逐渐放大。第一是类型安全。GDScript 支持类型标注但本质上还是动态语言重构一个类名或改一个方法签名编辑器不会主动告诉你哪里调用了它。脚本少的时候靠记忆没问题几十个脚本互相引用之后改一次就提心吊胆。C# 在编译期就能把这些低级错误抓干净。第二是 IDE 体验。用 Visual Studio 或者 Rider 写 C# 时跳转定义、重命名、查找引用都是可靠的断点调试也远比脚本编辑器的调试器顺手。F12 看源码、CtrlR 重命名这个习惯一旦养成就回不去了。第三是性能。虽然多数 2D 小游戏用 GDScript 也不卡但遇到物理计算密集、大量数组遍历、频繁字符串拼接的场景C# 的优势是体感级别的。尤其是等以后要做玩法原型、工具链或者算法模块时用 C# 写的代码能直接复用这个长期收益很值。当然C# 的代价也摆在那里代码改动后要经过编译才能运行快速原型阶段那种“改完立刻 F6 跑起来看效果”的节奏比 GDScript 重。所以我的分配方式是临时验证玩法的脚本、编辑器工具类的小功能用 GDScript需要长期维护的系统层、复杂数据结构、跨模块接口用 C#。工具不嫌多关键是知道每个工具适合干什么。1.2 版本选择搞错版本一切都白搭下载 Godot 时最容易犯的错就是下了标准版然后发现项目里根本没有 C# 相关选项。带 .NET 支持和标准版是两套独立的引擎构建官方下载页分开列出一定要认准名字里带 .NET 的那一版。这一点看起来废话但我在社区里见过太多人卡在这一步。版本选对之后还有一层兼容性问题Godot 4 不同小版本要求的 .NET SDK 版本不一样。4.2 之前常见的是 .NET 64.2 之后官方推荐 .NET 8。用命令行dotnet --list-sdks看下本机版本如果和编辑器要求不匹配轻则无法加载程序集重则构建时报一堆莫名其妙的错误。机器上同时装多个 SDK 没关系只要构建时用的是满足要求的那一个。还有个小细节.NET 版 Godot 打开项目时会自动生成 GodotSharp 文件夹和 .csproj / .sln 文件。这些文件是引擎帮你管理的很多人第一次看到会以为是自己该维护的东西手贱去清理或改名结果项目直接没法打开。正确的姿势是编辑器第一次构建时让这些文件自然生成之后用 IDE 打开 .sln 参与开发但不要移动 GodotSharp 和项目根目录的 .csproj 路径关系。1.3 环境搭建实战从零到第一个能跑的 C# 节点环境搭建我给一份可以直接照抄的清单安装 .NET SDK版本按当前 Godot 要求来建议直接装 .NET 8。下载 .NET 版 Godot 编辑器并解压。窗口项目管理器里新建项目选带 C# 的模板。如果模板列表里只有 GDScript说明引擎装错。打开项目后先让编辑器执行一次构建此时会自动生成 C# 解决方案文件。底部输出面板出现 “Build succeeded” 后才算环境通了。用 Visual Studio 或 Rider 打开生成的 .sln里面会有 GodotSharp 的 API 提示。回到编辑器F6 重新编译或者直接运行当前场景验证。这一步我最推荐的验证方法新建场景添加一个 Node 节点给它挂一个自动生成的 C# 脚本脚本里在_Ready里打一条输出运行场景后看控制台是否打印。能打印就说明整条 C# 链路已经通了后面再谈语法和框架才有意义。2. 第一个 C# 脚本类、节点与生命周期2.1 脚本文件与类声明的约定Godot 里新建 C# 脚本时编辑器会生成一个形如Player.cs的文件内容大致是using Godot; public partial class Player : Node2D { public override void _Ready() { } }第一眼看上去和普通 C# 类区别不大但有几个点值得琢磨。类是partial的。这不是随口加的修饰符Godot 4 的 C# 支持靠源生成器在后台补充很多引擎集成代码partial 允许编译器把你自己写的部分和生成的部分合成一个完整类。所以不要手贱把 partial 去掉去掉之后轻则编辑器识别异常重则直接编译失败。类名和文件名建议严格保持一致。Godot 在加载 C# 脚本资源时是靠文件路径关联脚本如果类名偏离了文件名编辑器里的脚本图标和节点挂载都可能出现识别不到的问题。C# 习惯里“一个文件一个类”本来也是通用风格顺水推舟就行。另外注意命名空间。Godot 4 的 C# 模板默认不强制要求命名空间但项目规模上来之后所有脚本挤在全局命名空间里迟早打架。我的习惯是项目初期就按模块建命名空间比如MyGame.Player、MyGame.UI然后在 .csproj 里保持根命名空间统一这样 IDE 的 using 管理也顺畅。2.2 C# 的节点生命周期方法迁移从 GDScript 转 C# 时生命周期方法的写法变化是第一道坎。GDScript 里是func _ready(): pass func _process(delta): passC# 里是public override void _Ready() { } public override void _Process(double delta) { }有三个差异要注意。一是方法名首字母大写这是 C# 命名规范和 Godot 内部方法名之间妥协的结果。凡是 GDScript 里下划线开头的方法转成 C# 后首字母大写其余保持不变。二是_Process的 delta 参数类型。Godot 4 里统一改成了double而在 Godot 3 时代是float。这意味着很多旧的第三方代码里写float dt delta直接编译不过需要主动改成(float)delta或让变量类型跟随引擎。三是 override 关键字。这些方法本质上是基类方法的虚方法用 override 才能正确覆盖。写完发现方法没生效先检查是不是忘了写 override这个错误编译期不会拦因为 C# 允许隐藏父类方法而不报错但运行时调用的就不是你的实现。常用生命周期的对应关系我整理成表GDScript 方法C# 覆盖方法触发时机_Ready_Ready节点进入场景树后第一次调用适合初始化_Process(delta)_Process(double delta)每帧调用和渲染帧率一致_PhysicsProcess(delta)_PhysicsProcess(double delta)每物理帧调用默认 60Hz物理相关操作放这_EnterTree_EnterTree节点进入场景树时调用比 Ready 早_ExitTree_ExitTree节点退出场景树时调用_UnhandledInput(event)_UnhandledInput(InputEvent)输入事件未被 UI 等处理时触发_Input(event)_Input(InputEvent)所有输入事件最先经过这里有个新手常犯的错移动玩家时不区分_Process和_PhysicsProcess。处理输入和物理碰撞相关时必须用_PhysicsProcess否则在渲染帧率不稳定时会出现移动抖动、穿墙等情况。判断原则很简单凡是和CharacterBody2D、RigidBody、Area2D的碰撞结果打交道的逻辑全放物理帧纯视觉动画、UI 摆位可以用渲染帧。2.3 导出变量和属性从 GDScript 搬过来的姿势GDScript 里用export把变量暴露到编辑器面板C# 里对应的是[Export]特性export var speed: float 300.0 export var max_health: int 100[Export] public float Speed { get; set; } 300.0f; [Export] public int MaxHealth { get; set; } 100;面板显示的名称默认直接用属性名。想用带下划线的命名风格可以在[Export(PropertyHint.Range, 0,1000)]这样的参数里做调整但新手阶段直接保持简单。几个要注意的细节[Export]只能加在 public 字段或 public 属性上private 字段即便标了特性也不会出现在面板里。这一点和直觉相反很多人习惯把所有字段设为 private结果发现面板空荡荡。支持的类型比你想的广。基础 int、float、string、bool 之外Color、Vector2、Resource、数组、字典甚至自定义的枚举都能导出。枚举导出后编辑器面板会显示下拉框比手填数字舒服得多。属性访问器可以用 get/set模板里的{ get; set; }是自动属性语法和 GDScript 的 var 语义最接近。如果需要在赋值时做额外处理比如血量变了刷新 UI可以改成完整属性体在 set 里插入逻辑[Export] public float CurrentHealth { get _currentHealth; set { _currentHealth value; UpdateHealthBar(); } }这一步理解透了就从“照着模板写”过渡到“按需写”了。3. 信号与事件C# 里三种连接方式的取舍3.1 编辑器连线最直观但最容易被忽略的细节GDScript 里连接信号最无脑的方式是在编辑器里选中节点切到“节点”面板找到信号列表双击信号弹出连接窗口再选目标节点和方法。这个流程在 C# 项目里依然可用但目标方法需要是 C# 脚本里的方法而且方法签名要匹配。一个经常被忽略的点编辑器连线生成的连接依赖场景里存储的连接信息。如果脚本的类名改了或者方法的访问级别从 public 改成 private这些连接在加载场景时可能静默失效表现出来就是“为什么信号没触发”。排查时优先看场景里的连接列表别一开始就怀疑信号机制本身。编辑器连线适合在一个稳定场景里做一次性接线比如按钮点击、定时器超时。它最大的优点是接线关系肉眼可见队友拿到场景文件就能理解逻辑。缺点是按引用关系藏在场景里代码里看不到全局搜索也搜不到属于“隐形代码”。3.2 代码连接 与 Callable 的差别C# 项目里更推荐在代码中显式连接信号因为调用关系和逻辑在一起可追踪性更好。Godot 4 的 C# 对信号支持两种写法第一种是把信号当事件订阅信号名去掉了下划线之后成为事件GetNodeTimer(Timer).Timeout OnTimerTimeout; private void OnTimerTimeout() { GD.Print(计时结束); }第二种是用内置的连接方法配合 CallableGetNodeTimer(Timer).Timeout OnTimerTimeout; // 等价写法 // 或者 GetNode(Timer).Connect(timeout, Callable.From(OnTimerTimeout));这两种写法在大多数场景下效果一样但语义上有个区分走的是 C# 事件机制连接和断开都很自然还能用-断开Connect返回的错误码需要自己关心比如重复连接会返回错误。我写业务代码一律用风格只在写插件或需要动态桥接时才用ConnectCallable。还有一点值得强调Godot 4 里信号名在 C# 中映射为去掉下划线的 PascalCase。比如 GDScript 里的hit_detected在 C# 里访问就成为HitDetected。对外宣告信号时的名称保持 GDScript 风格下划线小写但在 C# 里调用时用 PascalCase 事件名。这个命名转换规则很多人一开始不知道导致找半天 API。3.3 事件泄漏跨场景引用时最容易踩的雷C# 的事件机制有个经典陷阱订阅了事件但没取消订阅发布者被 GC 回收时订阅者还被事件引用着于是内存无法释放越跑越卡。在 Godot 里这个问题的表现形式更隐蔽。举个实际场景玩家对象在死亡后从场景树移除它身上有一个订阅了全局管理器事件的处理器忘记取消订阅。之后管理器继续广播事件每次都会调用一个已经不存在的玩家实例方法轻则控制台刷错误重则编辑器崩溃。规避办法有三条在_ExitTree里把该断的事件全部断掉养成对称编码的习惯哪里订阅就在哪里取消订阅。事件源的生命周期比订阅者长时优先考虑用弱事件模式或信号总线代替强引用事件。如果纯粹是同场景内父子节点的通信别用全局事件直接用节点路径调用方法简单可靠。性能排查时可以在调试器里看事件持有的目标对象数量或者干脆定期检查场景树里是否有“幽灵节点”残留。这个经验不算高深但真能让项目在长时间运行后稳定不少。4. 实操写一个带输入缓冲的 2D 角色控制器4.1 输入映射与 Input.GetVector光讲语法和信号不落地笔记就没价值。我用一个最典型的 2D 角色控制器来说明 C# 在 Godot 里怎么组合各种机制。先设置输入映射。项目设置里定义move_left、move_right、move_up、move_down四个动作分别绑键盘的 WASD 或方向键。在 C# 里读二维输入最省事的 API 是Vector2 inputDirection Input.GetVector(move_left, move_right, move_up, move_down);这行代码一次性返回一个归一化的二维向量水平方向和垂直方向的值范围是 -1 到 1。它的好处是自动处理了“同时按左右键”的场景如果左右都按下x 分量为 0不会出现原地发抖。注意返回值是Vector2这是 Godot 自带的结构体和 System.Numerics 的 Vector2 不是同一个类型别混用。Godot 场景里的坐标、碰撞、渲染全用 Godot.Vector2项目里如果引用了 System.Numerics要小心类型歧义。4.2 物理帧里的移动计算拿到输入向量后控制器的核心逻辑放在_PhysicsProcess里。一个带加速度、减速度的移动模式比直接设置速度的体感好得多public partial class Player : CharacterBody2D { [Export] public float MaxSpeed { get; set; } 300.0f; [Export] public float Acceleration { get; set; } 1200.0f; [Export] public float Friction { get; set; } 1800.0f; private Vector2 _velocity; public override void _PhysicsProcess(double delta) { Vector2 inputDirection Input.GetVector(move_left, move_right, move_up, move_down); if (inputDirection ! Vector2.Zero) { _velocity _velocity.MoveToward(inputDirection * MaxSpeed, Acceleration * (float)delta); } else { _velocity _velocity.MoveToward(Vector2.Zero, Friction * (float)delta); } Velocity _velocity; MoveAndSlide(); } }这段代码里有个关键的 API 叫MoveToward它把当前速度向量逐步向目标向量靠拢每次最多变化“速率 * delta”那么快。用加速度 1200 和最大速度 300 的话角色从静止到全速大约需要 0.25 秒手感不突兀松开按键后摩擦力 1800 让它迅速停下但又不至于瞬间冻结。MoveAndSlide是 CharacterBody2D 的经典移动方法它会自动处理与环境的碰撞滑动碰到斜坡会贴着坡面走碰到墙会沿墙滑行这一切由引擎内部完成。这也是为什么角色控制器要把速度和碰撞拆开处理而不是直接改 Position。有一个细节必须提MoveToward的第三个参数是“最大距离增量”物理帧的 delta 现在是 double速度值是 float计算乘积时如果不显式转 float编译器会提示精度损失。上面代码里我写了(float)delta这是 C# 转 Godot 后最常见的编译警告来源之一。4.3 完整脚本拆解与扩展思路上面的控制器只能算“能跑”离“好用”还差几个常见增强点。我加一个输入缓冲的概念进来这个在格斗类、平台跳跃类游戏里特别有用玩家在落地前 0.1 秒内按了跳跃键落地后仍然立即起跳避免了“明明按了却不跳”的挫败感。实现思路是记录按键时间戳private double _jumpPressedAt double.MinValue; public override void _UnhandledInput(InputEvent event) { if (event.IsActionPressed(jump)) { _jumpPressedAt Time.GetTicksMsec() / 1000.0; } } public override void _PhysicsProcess(double delta) { // 其他移动逻辑... double now Time.GetTicksMsec() / 1000.0; if (IsOnFloor() (now - _jumpPressedAt) 0.12) { Jump(); _jumpPressedAt double.MinValue; } } private void Jump() { _velocity.Y -500.0f; }输入缓冲的时间窗口 0.12 秒是我试过的比较舒服的经验值太短没效果太长会让连跳显得“粘”。这种用时间差缓存输入的模式在纯 GDScript 里也能写但放 C# 里因为变量类型清晰逻辑读起来意外地舒服。扩展方向上还可以在这个基础控制器上叠加冲刺、二段跳、斜坡速度衰减等机制。原理都是围绕_velocity做加减法然后交给MoveAndSlide处理碰撞。结构保持不变扩展只在局部函数里做这就是把移动逻辑集中在一处的好处。5. 我踩过的坑C# 与 GDScript 的差异清单5.1 Signal 委托定义命名规则会要命在 C# 里声明一个自定义信号需要写委托类型加特性[Signal] public delegate void HealthChangedEventHandler(float currentHealth);这个写法有个严格的命名约定委托名必须以EventHandler结尾前面的部分会被当作信号名。上面这个委托产生的信号名是HealthChanged在 GDScript 侧调用时是health_changed在 C# 侧订阅时用HealthChanged。如果不按约定以 EventHandler 结尾编译器可能不报错但 Godot 的源生成器会假装没看见信号就“神秘消失”了。另一个坑是参数类型尽量用 Godot 自带类型或基础类型自定义的复杂类在信号参数里序列化会有额外约束项目早期用不上就别硬用。还有信号参数名建议和 GDScript 端保持一致跨语言调试时可以少很多混乱。5.2 热重载和构建流程F6 不是刷新GDScript 项目里修一行代码回到编辑器直接运行场景新版代码立刻生效。C# 项目里则必须重新编译否则跑的永远是上一次构建的程序集。Godot 4 的编辑器中重新构建的快捷键是 F6构建成功后 IDE 里的错误列表会同步。很多人切到 C# 后还保持“改完就跑”的习惯结果发现改动没生效以为是运行缓存问题折腾半天才想起来没按 F6。更精细的流程是写代码都在 IDE 里进行改完后按 F6 构建构建成功再按 F5 运行当前场景。如果 F6 构建失败了运行按钮会直接不能用或者更糟——编辑器还在用旧程序集表现成“上次的 bug 还在”。这时候先看输出面板的编译错误修完再构建别反复重启编辑器浪费时间。还有一个体会调试时把断点打在 C# 代码里是可行的但必须用 IDE 的“附加到进程”功能附加到 Godot 编辑器进程或者直接以调试模式启动项目。断点有时会显示“命中断点但源码不匹配”这通常是因为程序集版本和 PDB 不同步按 F6 重新编译一次就好。5.3 NuGet 依赖与导出时的连锁问题C# 项目里用 NuGet 包是家常便饭比如引入 JSON 库、网络库、序列化工具。开发时一切正常一导出桌面平台就出各种问题这是我在社区里看到的高频求助。Godot 的桌面导出会把 C# 程序集和相关依赖一起打进包里但 NuGet 包里的原生 dll 并不会自动全部打包。例如某些库依赖原生运行时导出后目标机器上没有这些原生库启动时直接崩溃错误信息往往还很隐晦。遇到这类问题的排查顺序确认该 NuGet 包是否有托管的纯 .NET 实现优先选这类包。如果必须用带原生依赖的包确认导出目录里存在对应运行库文件必要时手动加入导出配置。导出前先在开发机上跑发版配置的构建产物开发环境能跑不代表发布包能跑。精简依赖能用 Godot 自带的 JSON 解析就别引第三方 JSON 库能省则省。我现在的策略是核心游戏逻辑尽量零第三方依赖所有数据结构都走 Godot 自带的序列化或简单的二进制协议。依赖越少导出越稳这句话在 C# 项目和 GDScript 项目里同样成立。5.4 工具脚本与编辑器状态GDScript 里脚本标注tool后可以直接在编辑器里运行C# 对应的是[Tool]特性。工具脚本功能强大但坑也多。最大的问题是编辑器进程和游戏运行进程共用同一套脚本脚本里如果写了访问场景节点的代码在编辑器里可能因为节点还没准备好而报错。我遇到过一种典型情况给一张地图生成脚本加了[Tool]原本想在编辑器里点击按钮自动生成所有房间。结果因为脚本的_Ready在编辑器加载场景时也执行了一次生成逻辑跑了一半就预告警。后来把生成逻辑全部放进一个公开方法只在用户点击时调用_Ready里只做状态判断问题才解决。给工具脚本的规矩是编辑器状态下只做“读”和“安全的写”涉及资源创建、节点增删的敏感操作要显式判断Engine.IsEditorHint()并且确保操作可以被撤销。另外工具脚本抛异常时编辑器容易卡住写代码时多做边界判断别让NullReferenceException在编辑器里裸奔。6. 给新人的几条实在建议学 C# 和 Godot 组合的路径我自己走下来最大的感受是不要一上来就纠结谁好谁坏先让两种语言在同一项目里共存边做边体会各自的边界。手感培养的第一步是做出一个能在屏幕上移动、跳跃、和地图碰撞的小角色本文的代码足够你跑通这一关。我个人在实际操作中的体会是每当你从 GDScript 迁移一个功能到 C#都值得写一条对照笔记——语法差异、API 名称、编译行为、运行结果记录成自己的速查表。这份笔记的价值会随着时间越来越大因为网上零散的资料很难覆盖“引擎版本变化后 API 又改了”这类现实问题。最后再分享一个小技巧无论是 GDScript 还是 C#项目里统一命名风格都要尽早做。我的做法是文件路径体现模块类名前缀体现类型方法名用动词开头变量名风格跟随各自语言惯例。看起来是小事但在跨语言项目里它能帮你少问很多“这个变量到底在哪定义”的蠢问题。下一步我打算把这套 C# 经验扩展到多场景切换和数据持久化上等有沉淀了再继续写第八篇。