我不是第一个在 Godot 里折腾 C# 网络通信的人,如果你搜过相关关键词,大概也发现了:官方文档里的网络示例几乎全是 GDScript,社区里问 C# 版本的人一抓一大把,回答却经常是“你可以把 GDScript 翻译成 C#”。这句话听起来简单,真翻译起来全是坑——异步委托、线程切换、Mono 对象生命周期、信号回调在主线程还是子线程执行,这些问题没人给你划重点。
这份笔记是我的 Godot 引擎基础学习系列第 10 篇,主题锁定在 C# 环境下实现 TCP 通信的完整链路:服务端、客户端、粘包处理、跨线程回传、断线重连,以及打包发布后连不上服务器这类诡异问题。适合那些已经能用 Godot 摆弄场景、挂脚本,但对 C# 网络编程还停留在“大概知道”阶段的开发者。我会尽量把每一步的“为什么”讲清楚,而不只是贴代码让你抄。
如果你只是想把 Godot 当作一个可视化前端,对接自己用 C# 写的上位机或后端服务,这篇笔记会很有用。
1. 写这篇笔记的动机:Godot C# 的网络开发为何如此别扭
1.1 为什么从第 10 篇才开始写网络
说句实在话,网络通信并不是 Godot 游戏开发最优先要学的东西。做单机游戏、做工具型应用、做 UI 原型,都碰不到 Socket。但我个人走到第 10 篇时,基本玩法、信号系统、场景树、资源加载这些基础都过了一遍,再往后想深入应用场景,网络就绕不开了——尤其是你想用 Godot 做“真实项目”的时候。
打个比方:单机游戏是你在自己家里做饭,锅碗瓢盆都在手边,不需要跟任何人沟通。但一旦涉及多人对战、远程配置下发、数据上报,甚至只是把一个设备上的运行状态实时同步到另一个设备上,你就得跟“网络”这个外部世界打交道。Godot 对 GDScript 的网络封装看似很友好,到了 C# 这边一换语言,体验直接打折扣。
这段经历也解释了一个我在搜索时频繁看到的现象:几乎每个 C# 开发者遇到 Godot 网络问题,第一反应都是去查 C# 原生的 TcpClient、TcpListener 能不能直接用。 答案是能,但用起来比在控制台程序里多了不少讲究。
1.2 C# 版 Godot 网络的“文档荒漠”与破局思路
我自己踩坑时翻了官方文档、Godot 源码、GitHub issues、Reddit 帖子,发现一个规律:官方推荐 C# 项目使用 Godot 封装好的 ENet 或 WebSocket,但文档给的示例基本以 GDScript 为主,C# 很少有人系统整理。
而社区里的 C# 教程,更多的是教你用 System.Net.Sockets 直接造轮子,因为这样最灵活——你可以对接任何自定义协议,不依赖 Godot 的 high-level multiplayer 机制。
我的建议是:如果你是要做游戏里的联机功能,优先学习 Godot 官方的高层网络 API;但如果你是想让 Godot 当一个客户端,去连你已有的 C# 服务端(比如上位机、后端服务、别的设备的 Socket 程序),那就直接走底层 Socket,反而少走弯路。 这篇笔记的示例就按第二种场景来。
1.3 我采用的整体架构:Godot 客户端 + C# 服务端
为了让结构清晰,本篇做一个最简单但完整的演示:
- 服务端:用普通的 C# 控制台程序写,监听某个端口,收到客户端消息后回一条确认。
- 客户端:Godot 4.x .NET 版,里面写一个 C# 脚本挂在 Node 上,启动时连接服务端,界面层用 Label 显示连接状态,用一个 LineEdit 输入要发送的消息。
- 通信协议:为了讲清楚“粘包”问题,我故意采用自定义格式——每个消息前 4 字节表示消息体长度,后面跟着 UTF-8 编码的消息体。
这套结构不涉及 ENet,完全用 System.Net.Sockets,目标是让你真正理解底层机制。如果你后续想对接真实设备或已有服务,这些代码可以直接当模板改。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与项目结构:.NET 版 Godot 的最小可行配置
2.1 用官方模板创建 C# 工程
Godot 4.x 从某个版本开始把 .NET 支持整合得很好,但是有一个细节你必须注意:不要在普通版 Godot 里新建 C# 脚本,那些选项根本不存在。 你需要下载 .NET 版(Godot 官方命名为 .NET 版本,Windows 下通常文件名带 _mono 或 .net)。
创建项目的步骤很简单:
- 打开 Godot .NET 版。
- 新建项目时,渲染器可以选 Forward Plus 或 Mobile,跟网络通信无关。
- 项目创建完成后,在
Project > Project Settings > General > Dotnet里可以看到项目相关的 .NET 配置。 - 打开项目后,直接往场景里挂 C# 脚本会提示你需要先生成解决方案文件——Godot 会在项目目录下自动生成一个
.sln文件,只要你在 “Build” 菜单里点一下 “Build Solution” 或者用 Visual Studio 打开编译。
这里有个容易踩坑的点:如果你用 Visual Studio 打开 .sln 编译,别用太老的 .NET SDK。Godot 4 的 C# 版基于 .NET 6 以上,建议直接装 .NET 8 SDK。用 dotnet --version 能直接查到本机版本。
2.2 程序集、脚本类与节点的挂接方式
在 Godot 里,C# 脚本本身是一个继承自 Node 的类,编译好后会生成一个和类名同名的资源。你把它拖拽到节点上即可。
下面是一个极小的网络客户端脚本框架:
csharp复制using Godot;
using System;
using System.Net.Sockets;
public partial class TcpClientNode : Node
{
private TcpClient _client;
private NetworkStream _stream;
public override void _Ready()
{
GD.Print("TcpClientNode ready");
}
}
这个脚本挂到任意节点上后,_Ready 会在场景加载完成后执行。但注意一个关键点:_Ready 是在 Godot 主线程上执行的。C# 脚本里的事件委托、异步回调则不一定。这是贯穿整篇笔记的核心问题,后面我会专门开一节讲线程桥接。
2.3 为什么 C# 版里应该多用 GodotObject 的调度机制
在 GDScript 里,你调用一个方法、改一个节点属性,引擎会自动帮你处理线程问题吗?不会,GDScript 同样不能跨线程访问场景树。但 GDScript 的协程和信号写起来方便,大家潜移默化地避开了坑。C# 这边一上来就是 async/await、Task.Run,很容易写出一个后台线程里直接改 Label.Text 的代码,然后就等崩溃吧。
所以我在项目里约定了一条纪律:所有直接操作 Godot 节点的代码,必须回到主线程执行。 方法有三种:
CallDeferred:把方法调用推迟到当前帧处理的合适时机。GodotObject.SynchronizationContext:配合异步方法把上下文切回主线程。- 自建线程安全队列:子线程往队列丢数据,主线程每帧消费。
在写正式代码前,先把这条纪律刻在脑子里,后面很多问题都能避免。
