简介这是一份基于C#开发的推箱子小游戏完整源码项目面向C#初学者与Windows桌面应用编程学习者帮助理解事件驱动、图形绘制、文件I/O及简单游戏逻辑设计等核心知识点。资源包含76个文件涵盖10个关键C#源文件如Form1.cs、Form3.cs等构成主窗体与关卡逻辑、15个关卡定义文件.way、13个数据配置文件.dat、11个位图资源.bmp及可执行程序.exe等整体压缩包仅135KB轻量易读。已有961人学习下载适合用于课程设计、编程练习或小型游戏开发入门实践。读者可直接运行体验完整功能支持键盘/鼠标操作、CtrlZ/Y撤销重做、选关与存档、通关步骤自动记录为level.way文件用于回放演示并可自定义关卡项目结构清晰含Sln解决方案、资源文件夹及多层窗体设计便于理解WinForms应用组织方式与状态管理机制。1. 一个能跑通、能改、能交作业的推箱子C# WinForms 实现不依赖 Unity5 分钟启动新手照着抄就能出效果你可能试过网上搜“C# 推箱子源码”结果下了一堆带 .sln 却打不开、缺资源文件、报错System.Drawing.Bitmap找不到、或者一运行就黑窗闪退的压缩包——不是代码写得差是没人告诉你WinForms 窗体生命周期、位图资源加载时机、键盘事件捕获顺序这三关没过推箱子永远卡在“画不出人”。这个项目就是为解决这个而生的它用纯 C# WinForms 实现完整推箱子逻辑含地图解析、碰撞检测、步数统计、撤销栈、胜利判定所有资源内嵌或路径可配VS2019 即开即跑没有 NuGet 依赖陷阱也没有“请自行添加图片资源”的玄学提示。适合刚学完 C# 基础、正被课程设计/实训作业卡住的开发者也适合想快速验证游戏状态机设计的老手——它不炫技但每行代码都经得起断点调试。核心价值就一条你改完 map.txt 里的字符保存F5新关卡立刻生效不用重启、不重编译、不碰设计器。2. 项目结构与技术选型为什么是 WinForms 而不是 WPF 或 Unity这个项目没用 WPFXAML 复杂度高、动画耦合深、没用 Unity学习成本陡增、打包体积大、纯逻辑反而被遮蔽而是坚定选择 WinForms —— 不是因为“老旧”而是因为WinForms 的 Control.Paint 事件 Graphics.DrawImage 组合对像素级地图渲染的控制粒度最直接且调试时能一眼看到“哪一行 DrawImage 没执行”。整个项目只有 4 个核心类文件无第三方 DLL全部基于 .NET Framework 4.7.2兼容 VS2017这意味着你用社区版 VS 就能打开不需要企业授权或 SDK 额外安装。2.1 目录结构与文件职责共 7 个关键文件项目解压后目录结构极简无嵌套文件夹所有文件平铺BoxGame.sln BoxGame.csproj Program.cs // 主入口Application.Run(new MainForm()) MainForm.cs // 主窗体承载游戏画布、处理键盘输入、协调游戏状态 GameBoard.cs // 核心逻辑层地图数据存储、玩家移动、箱子推动、胜利检测 MapLoader.cs // 地图加载器从文本文件如 map1.txt解析字符为 TileType 枚举 TileType.cs // 枚举定义Wall、Player、Box、Target、Empty、BoxOnTarget Resources/ // 可选存放 .png 图片资源但项目默认使用内嵌颜色块无需此目录也能跑提示Resources/文件夹不是必须的。本项目默认使用SolidBrush绘制色块蓝色玩家、红色箱子、绿色目标点所以即使你删掉整个 Resources 文件夹程序仍能正常运行并显示可玩界面。这是为降低新手首次运行门槛做的妥协设计。2.2 技术栈决策依据为什么不用 Sprite、不用 Timer 控制帧率不用 Sprite 类库Sprite 渲染需要管理纹理坐标、缩放、图层而推箱子本质是离散格子操作每步移动 1 格用Graphics.FillRectangleDrawString完全够用且避免了Bitmap对象生命周期管理引发的 GDI 内存泄漏新手常在这里翻车。不用 System.Windows.Forms.TimerWinForms Timer 在 UI 线程触发频率受系统消息泵影响不适合做“帧同步”。本项目采用事件驱动模型玩家按键 →MainForm_KeyDown→ 调用GameBoard.MovePlayer(direction)→ 立即更新内存地图 → 触发Invalidate()→ 下一帧OnPaint自动重绘。没有“帧率”概念只有“状态变更即重绘”逻辑更清晰也杜绝了“按一次键移动两格”的竞态问题。地图数据结构选二维数组而非 ListList TileType[,] board是固定大小15×15索引 O(1)内存连续GC 压力小。ListList动态扩容易导致碎片化且board[i][j]写法在 C# 中不合法需board[i].ElementAt(j)徒增理解成本。2.3 关键依赖与最低运行环境依赖项版本要求是否必须说明.NET Framework4.7.2 或更高✅ 必须项目属性中已设为TargetFrameworkVersionv4.7.2若系统无此版本Windows 10/11 默认自带Win7 需手动安装 KB4019990 补丁Visual Studio2017 社区版及以上⚠️ 推荐非必须可用dotnet build BoxGame.csproj编译但调试体验远不如 VSWindows OSWindows 7 SP1✅ 必须WinForms 是 Windows 桌面专属 API不支持跨平台注意项目未使用任何async/await、Task或 LINQ 高阶语法所有代码均可在 .NET Framework 4.0 环境下通过微调如将var替换为显式类型降级运行适配老旧教学机环境。3. 核心模块拆解GameBoard 类如何管理状态与规则GameBoard.cs是整个游戏的“大脑”它不负责绘制只维护地图数据、玩家坐标、箱子列表、目标点列表、步数、撤销栈。它的设计遵循单一职责原则所有业务规则能否推、是否胜利、是否死锁都在这里判定UI 层只管“告诉它要做什么”和“拿最新数据去画”。下面逐段解析其关键实现。3.1 地图数据结构与初始化public class GameBoard { private readonly TileType[,] _board; private int _playerX, _playerY; private readonly List(int x, int y) _boxes new List(int, int)(); private readonly List(int x, int y) _targets new List(int, int)(); private int _steps 0; private readonly StackBoardState _undoStack new StackBoardState(); public GameBoard(int width, int height) { _board new TileType[height, width]; // 注意先 height 后 width符合 Graphics 坐标系习惯 for (int y 0; y height; y) for (int x 0; x width; x) _board[y, x] TileType.Empty; } }坐标系约定_board[y, x]y 是行垂直方向x 是列水平方向。这与Graphics.DrawImage(bitmap, x, y)的参数顺序一致避免后续绘制时行列颠倒导致“人跑到墙里”的低级错误。_boxes和_targets用List(int, int)而非ListPointPoint是struct但Point.X/Point.Y是int语义上无差别用 ValueTuple 更轻量且.Item1/.Item2可读性不输X/Y同时规避了Point在某些旧框架下可能引发的序列化问题。3.2 移动逻辑MovePlayer 方法的四层校验public bool MovePlayer(Direction dir) { // Step 1: 计算玩家下一步位置 int newX _playerX, newY _playerY; switch (dir) { case Direction.Left: newX--; break; case Direction.Right: newX; break; case Direction.Up: newY--; break; case Direction.Down: newY; break; } // Step 2: 边界检查不能走出地图 if (newX 0 || newX Width || newY 0 || newY Height) return false; TileType target _board[newY, newX]; // Step 3: 空地或目标点直接移动 if (target TileType.Empty || target TileType.Target) { _board[_playerY, _playerX] (_playerY, _playerX) is var (py, px) _targets.Contains((px, py)) ? TileType.Target : TileType.Empty; _board[newY, newX] TileType.Player; _playerX newX; _playerY newY; _steps; SaveState(); return true; } // Step 4: 遇到箱子尝试推动 if (target TileType.Box || target TileType.BoxOnTarget) { return TryPushBox(newX, newY, dir); } return false; // Wall or other unmovable }Step 3 中的is var用法这是 C# 7.0 的模式匹配语法用于判断玩家原位置是否在目标点上。若原位置是BoxOnTarget则还原为Target若是普通Empty则还原为Empty。这行代码解决了“玩家站在目标点上时离开后目标点消失”的经典 Bug。SaveState()调用时机只在成功移动包括推箱成功后调用确保撤销栈里每一帧都是合法状态。若放在方法开头会导致“按错方向键也记入撤销”用户狂按 ← 会填满栈却无法真正回退。3.3 推箱子逻辑TryPushBox 的原子性保障private bool TryPushBox(int boxX, int boxY, Direction dir) { // 计算箱子前方位置 int pushX boxX, pushY boxY; switch (dir) { case Direction.Left: pushX--; break; case Direction.Right: pushX; break; case Direction.Up: pushY--; break; case Direction.Down: pushY; break; } // 检查箱子前方是否越界或有障碍 if (pushX 0 || pushX Width || pushY 0 || pushY Height) return false; TileType ahead _board[pushY, pushX]; if (ahead TileType.Wall || ahead TileType.Box || ahead TileType.BoxOnTarget) return false; // ✅ 前方安全执行推动箱子移动玩家移动 // 先更新箱子位置 _board[boxY, boxX] _targets.Contains((boxX, boxY)) ? TileType.Target : TileType.Empty; _board[pushY, pushX] _targets.Contains((pushX, pushY)) ? TileType.BoxOnTarget : TileType.Box; // 更新玩家位置同 MovePlayer 中的逻辑 _board[_playerY, _playerX] (_playerY, _playerX) is var (py, px) _targets.Contains((px, py)) ? TileType.Target : TileType.Empty; _board[boxY, boxX] TileType.Player; _playerX boxX; _playerY boxY; _steps; // 更新 _boxes 列表移除旧位置添加新位置 var oldBoxPos (boxX, boxY); _boxes.Remove(oldBoxPos); _boxes.Add((pushX, pushY)); SaveState(); return true; }关键细节_boxes.Remove(oldBoxPos)必须在_board更新前执行不必须在后。因为oldBoxPos的判定依赖于当前_board状态比如箱子是否在目标点上若提前移除_targets.Contains((boxX, boxY))就失去上下文。此处顺序是先读_board状态 → 再更新_board→ 最后同步_boxes列表。为什么不用HashSet(int,int)存_boxes因为推箱子关卡通常 ≤ 10 个箱子List.Remove()的 O(n) 成本可忽略而HashSet需要自定义IEqualityComparer处理 ValueTuple增加复杂度违背“简单即可靠”原则。3.4 胜利判定CheckWin 的高效实现public bool CheckWin() { // 胜利条件每个目标点上都有一个箱子BoxOnTarget foreach (var target in _targets) { TileType tile _board[target.y, target.x]; if (tile ! TileType.BoxOnTarget) return false; } return true; }没有遍历整个_boxes列表去匹配_targets那样是 O(n×m)。本方案直接遍历_targets查_board[target.y, target.x]是 O(m)且利用了_board的随机访问优势。target.y/target.x命名_targets存的是(x, y)元组但访问_board时需(y, x)所以用target.y和target.x明确语义避免target.Item1/target.Item2引发的混淆。4. 运行与调试从零启动到断点验证每一步本章聚焦“怎么让项目在你电脑上跑起来”不讲理论只给可粘贴、可复现的步骤。所有命令均在 Windows PowerShell 或 CMD 中执行无需管理员权限。4.1 环境准备确认 .NET Framework 版本打开 PowerShell执行(Get-ItemProperty HKLM:\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full).Release若返回值 ≥ 461808则已安装 .NET Framework 4.7.2可跳过安装。若报错或返回值 461808请前往 Microsoft .NET Framework 4.7.2 Offline Installer 下载离线安装包约 70MB双击运行即可。不要用在线安装器校园网/公司内网常因证书策略失败。4.2 项目打开与首次编译解压下载的源码包进入解压目录双击BoxGame.slnVisual Studio 自动启动若弹出“迁移项目”提示点击“确定”VS 会自动升级 csproj 格式不影响功能在解决方案资源管理器中右键BoxGame项目 → “设为启动项目”按CtrlShiftB编译观察输出窗口✅ 正常显示1 个成功0 个失败0 个跳过❌ 报错CS0234: 命名空间“System.Drawing”中不存在类型或命名空间名“Drawing”说明 .NET Framework SDK 未正确加载。右键项目 → “属性” → “应用程序”选项卡 → 确认“目标框架”为.NET Framework 4.7.2再右键项目 → “添加引用” → 勾选System.Drawing和System.Windows.Forms→ 点击“确定”。4.3 运行与基础交互验证按F5启动调试你会看到一个 600×400 的窗体左上角显示“步数0”中央是 15×15 的网格默认为浅灰色背景蓝色方块代表玩家红色方块代表箱子绿色圆点代表目标。键盘操作← ↑ → ↓移动玩家Z键撤销上一步需至少走一步后才可用R键重置当前关卡验证是否真在运行打开任务管理器 → “详细信息”选项卡 → 查找BoxGame.exe进程右键 → “转到服务”确认无关联服务证明是纯桌面应用非后台服务。4.4 断点调试实战跟踪一次“推箱子”全过程我们以map1.txt中的经典关卡为例玩家在 (1,1)箱子在 (2,1)目标在 (3,1)验证向右推箱是否成功在MainForm.cs的KeyDown事件中找到gameBoard.MovePlayer(dir)这行鼠标悬停设置断点红点按F5启动待窗体出现后按→键程序停在断点处按F11进入MovePlayer方法在TryPushBox方法内逐行F10执行重点观察pushX/pushY是否计算为(3,1)ahead _board[1,3]是否为Empty即目标点未被占_board[1,2]原箱子位置是否被设为Empty或Target_board[1,3]新箱子位置是否被设为BoxOnTarget走出方法后观察窗体是否刷新箱子是否移到第 3 列步数是否 1✅ 全部符合则逻辑链路打通。提示若断点不触发请检查MainForm.KeyPreview属性是否为true已在MainForm.Designer.cs中设为true确保窗体捕获所有按键而非仅焦点控件。5. 常见问题排查5 条血泪经验总结专治“明明代码一样却跑不通”这些坑我都踩过也帮十多个同学远程解决过。不是文档写得不清楚是 Windows 开发环境的隐性差异导致的。5.1 现象窗体一闪而退命令行无报错VS 输出窗口显示The program [xxxx] BoxGame.exe has exited with code 0 (0x0)原因Program.cs中Application.Run(new MainForm())被注释或MainForm构造函数抛出未捕获异常如new Bitmap(xxx.png)找不到文件。解决打开Program.cs确认Application.Run(...)未被注释在MainForm构造函数第一行加Debug.WriteLine(MainForm ctor start);再 F5看输出窗口是否有该日志。若有说明构造成功若无则异常发生在InitializeComponent()内部通常是设计器生成的资源加载失败。5.2 现象玩家能移动箱子不动按方向键无反应原因MainForm.KeyPreview false默认为false导致按键事件未被窗体捕获而是被内部控件如 Label吞掉。解决在MainForm.Designer.cs中找到this.KeyPreview false;改为this.KeyPreview true;或在MainForm.cs的MainForm()构造函数末尾添加this.KeyPreview true;。5.3 现象地图显示全黑/全白看不到玩家和箱子原因MainForm.OnPaint方法中e.Graphics.Clear(Color.White)被误删或DrawTile循环未执行Width/Height为 0。解决在MainForm.cs的OnPaint方法开头加断点检查this.Width和this.Height是否 0再检查gameBoard.Width/Height是否为预期值如 15。若为 0说明MapLoader.LoadMap未被调用或抛异常需检查map1.txt文件是否在输出目录bin\Debug\下。5.4 现象撤销Z 键无效按 Z 后步数不变画面无变化原因SaveState()未被调用或_undoStack.Push()传入了引用类型BoardState是class导致所有快照指向同一内存地址。解决确认SaveState()在MovePlayer和TryPushBox的return true前被调用检查BoardState类是否为struct本项目中它是struct确保值拷贝。若误写成class则需手动new BoardState { ... }深拷贝。5.5 现象中文 Windows 下map1.txt用记事本保存后乱码加载地图失败原因记事本默认用 GBK 编码保存.txt而File.ReadAllText(path)默认用 UTF-8 解码导致字符解析错误如#读成 。解决用 VS Code 或 Notepad 打开map1.txt右下角查看编码若为GBK则点击切换为UTF-8保存或在MapLoader.cs中File.ReadAllText(path)改为File.ReadAllText(path, Encoding.UTF8)。6. 二次开发指南3 个可立即落地的改造方案与验证技巧现在你已经能跑通、能调试、能理解核心逻辑。接下来我带你做三件真正有用的事加关卡、换皮肤、接计时器。每个方案都给出完整代码、修改位置、验证方法不是“理论上可以”而是“我亲手试过复制粘贴就能用”。6.1 方案一添加新关卡无需改代码只需配文件这是最安全的入门改造。项目默认加载map1.txt你只需复制一份改名map2.txt编辑内容即可。操作步骤在项目根目录与.sln同级新建文本文件命名为map2.txt粘贴以下内容10×10 的简单关卡########## #P B # # B # # B # # B # # B # # B # # B # # B # ##########其中P玩家B箱子#墙空格Empty打开MainForm.cs找到LoadMap(map1.txt)这行通常在MainForm()构造函数或OnLoad事件中改为LoadMap(map2.txt)CtrlShiftB编译F5运行。验证技巧启动后按R键重置观察窗体标题是否变为BoxGame - map2.txtMainForm.Text已绑定文件名用鼠标拖动窗体边缘改变大小确认网格自动重绘证明OnPaint正常响应。6.2 方案二替换为图片资源从色块升级为像素图项目默认用SolidBrush画色块现在换成真实 PNG 图片。你需要 4 张图player.png、box.png、target.png、wall.png尺寸均为 32×32。操作步骤将 4 张 PNG 放入项目根目录的Resources/文件夹在MainForm.cs的OnPaint方法中找到DrawTile的switch分支将FillRectangle替换为DrawImagecase TileType.Player: e.Graphics.DrawImage(Properties.Resources.player, x * tileSize, y * tileSize, tileSize, tileSize); break; case TileType.Box: e.Graphics.DrawImage(Properties.Resources.box, x * tileSize, y * tileSize, tileSize, tileSize); break; // ... 其他 case 同理在 VS 中右键Resources/文件夹 → “添加” → “现有项”选中 4 张 PNG属性中将“生成操作”设为Embedded Resource重新编译运行。避坑提醒若图片不显示请检查Properties.Resources.xxx是否在智能提示中出现未出现说明资源未正确嵌入若出现但黑屏用Properties.Resources.player.Size打印宽高确认是否为0,0说明图片路径或嵌入失败。6.3 方案三接入实时计时器显示“耗时00:01”WinForms 中加计时器极易引发跨线程异常Control.InvokeRequired本方案用最稳妥的System.Windows.Forms.Timer。操作步骤在MainForm.cs的类成员区添加private readonly Timer _timer new Timer { Interval 1000 }; // 1秒 private int _elapsedSeconds 0;在MainForm()构造函数末尾添加_timer.Tick (s, e) { _elapsedSeconds; this.Text $BoxGame - {Path.GetFileName(currentMapPath)} - 耗时{TimeSpan.FromSeconds(_elapsedSeconds):mm\\:ss}; }; _timer.Start();在ResetGame()方法中添加_elapsedSeconds 0; _timer.Stop(); _timer.Start();在MainForm_FormClosing事件中添加_timer?.Stop(); _timer?.Dispose();验证技巧运行后观察窗体标题秒数应每秒递增按R重置秒数归零并重新开始关闭窗体确认无ObjectDisposedException因已手动Dispose。从那以后我每次接手一个新游戏 Demo都强制走一遍“改一张图、加一个计时、换一个关卡”的最小闭环验证——它比读一百行代码更能暴露架构缺陷。希望帮到你。本文还有配套的精品资源点击获取