简介一套基于Cocos Creator开发的“水浒传”主题游戏完整工程源码面向个人开发者、毕业设计学生和小型游戏团队可满足技术学习、项目实战与快速原型参考等需求。压缩包共139个文件整体约7.13MB包含场景fire文件、预制体prefab、脚本js与ts、界面图片png与jpg、数据配置json与plist、音频mp3与ogg以及字体ttf等其中大量meta文件是Cocos Creator资源导入后自动生成的元数据保留后可直接打开工程运行。项目已有280人学习下载适合希望理解Cocos Creator工程组织、场景搭建、角色控制、UI登录与故事剧情等典型模块的读者。解压后在Cocos Creator中打开即可看到清晰的目录结构可参考完整游戏流程复用其中的资源管理和场景切换逻辑有助于缩短游戏开发入门周期也可作为毕业设计或商业小游戏的改造基础。无论是学习组件化开发还是研究小体量游戏的整体架构这份源码都能提供直观参考。1. 从一套水浒传源码看 Cocos Creator 项目该怎么拆Cocos Creator 在水浒传这类 2D 横版 RPG 里是出现频率很高的引擎原因不外乎编辑器上手快、2D 渲染管线和动画系统成熟、发布到小游戏和 APK 的路径短。这套源码包里有Menu.fire、Story.js、denglujiemian.jpg、shouye2.0_bg.jpg这类文件和场景图一眼能看出它覆盖了从登录界面、首页背景、故事脚本到菜单交互的完整游戏壳子。对个人开发者来说最有价值的不是把美术资源搬走而是看它如何处理场景切换、脚本挂载、UI 事件绑定和资源加载顺序对学生毕设来说这套包能直接支撑起游戏项目的选题对小公司做技术验证也可以用它测试 Cocos Creator 打包安卓和 Web 的完整链路。需要先说清楚一件事这包不是完整的商业级水浒传游戏它更像是一个可运行的项目骨架若干完成模块。把它下载到本地后第一步不是急着改代码而是先搞清楚场景结构、脚本依赖和资源引用关系。这样才能避免打开即报错、运行即黑屏的经典开局。2. 场景结构、资源映射与脚本挂载从静态资源还原项目逻辑2.1 先分清哪是场景、哪是素材、哪是脚本在 Cocos Creator 项目里一个场景文件就是这个游戏的一个运行状态。登录界面是一个场景首页是一个场景章节选择又是一个场景。这套包里出现的denglujiemian.jpg是登录界面底图shouye2.0_bg.jpg是首页背景Menu.fire注意后缀不是.scene这个要特别提醒Menu.fire是旧版Cocos Creator 2.x 之前或某类自定义编辑器配置遗留的资源描述文件很多从网上找的源码包会保留这种东西它不一定能被当前版本识别。真正能加载的核心是Story.js这是挂在某个节点上的场景控制脚本。常见的做法是cc.Class({ extends: cc.Component, properties: { storyText: cc.Label, nextButton: cc.Button, pageIndex: 0 }, onLoad() { this.storyData this.loadStoryData(); this.showPage(0); }, loadStoryData() { return [ { text: 洪太尉误走妖魔, bg: denglujiemian.jpg }, { text: 九纹龙大闹史家村, bg: shouye2.0_bg.jpg } ]; }, showPage(idx) { this.storyText.string this.storyData[idx].text; } });这里把storyText和nextButton声明为 properties是为了在编辑器里把这两个 UI 组件拖拽绑定到脚本上。loadStoryData方法模拟从 JSON 或远程接口拉取剧情数据实际开发中会替换成loadStoryDataFromJson() { let raw cc.resources.load(data/story, cc.JsonAsset); return raw.json.storyList; }这段代码的逻辑不复杂但要注意cc.resources.load的路径是相对于assets/resources目录的不带后缀名。this.showPage(idx)只更新 Label 的 string是因为要让剧情文本随用户点击切换而不是一次性全部渲染。如果你把源码包打开后发现剧情不显示先检查 Label 组件有没有被正确赋值到storyText属性上。2.2 场景切换和资源加载的坑位在哪场景切换是这类源码包最常见的报错点。比如从登录界面denglujiemian切到首页shouye2.0_bg你需要在Menu.js或对应登录控制脚本里写场景跳转cc.Class({ extends: cc.Component, properties: { usernameEdit: cc.EditBox, loginBtn: cc.Button }, onLogin() { let name this.usernameEdit.string; if (!name) { cc.warn(请输入账号); return; } cc.director.loadScene(shouye); } });注意cc.director.loadScene的参数是场景名字而不是场景文件名路径。很多从网上下的项目场景名和文件名不一致导致运行时报Failed to load scene。在你拿到这套水浒传源码时先去assets目录下找出所有.scene结尾的文件然后在项目设置-功能裁剪-场景里把需要用到的场景全部勾选进去。否则打包 APK 或 Web 版时未勾选的场景不会被构建进去动态加载时直接黑屏。资源加载顺序也是一个隐藏坑。Cocos Creator 2.x 里场景中的节点引用的贴图、预制体如果放在resources文件夹外只能通过场景静态引用方式加载不能动态cc.loader.loadRes。这套包里denglujiemian.jpg、shouye2.0_bg.jpg这种散图建议全部放进assets/resources/textures下然后用cc.resources.load统一加载cc.resources.load(textures/shouye2.0_bg, cc.SpriteFrame, (err, spriteFrame) { if (!err) { this.bgSprite.spriteFrame spriteFrame; } });这里bgSprite是场景中 Sprite 组件的引用。如果加载时报url is not in res那就是资源没放进resources目录。散图管理在这种老式项目里非常常见几乎每个从网上拿到的源码包都会踩到记住这个检查顺序路径 → 文件夹 → 后缀 → 场景勾选。3. UI 事件绑定、动画切换与剧情驱动把用户操作串成游戏流程3.1 Button 点击事件两种绑定方式与坑位对比水浒传这类剧情驱动游戏核心交互链条就是登录 → 首页 → 选择章节 → 阅读故事 → 进入战斗或下一页。所有动作都要靠 UI 事件串起来。Cocos Creator 里 Button 的点击事件有两种绑定方式源码包通常是第一种。第一种是编辑器里手动绑定在 Button 组件的Click Events列表里添加一条Target 拖入挂载脚本的节点Component 选择脚本组件Handler 选择onLogin方法。这种方式直观但有个致命缺陷节点改名或脚本重命名后绑定会变成失效状态运行时不报错但点击没反应。第二种是代码绑定onLoad() { this.loginBtn.node.on(cc.Node.EventType.TOUCH_END, this.onLogin, this); }这种方式的好处是逻辑集中在脚本里不会被编辑器的序列化数据搞坏。代码里cc.Node.EventType.TOUCH_END是触摸结束事件优先级高不会因为 Button 组件的过渡动画而拦截。很多新手在这个环节反复试错其实区别就在事件是TOUCH_END还是CLICK。CLICK事件由 Button 组件内部派发如果按钮的Interactable被设置成了 falseCLICK 不会触发但 TOUCH_END 会。对这套水浒传源码而言建议把所有剧情推进相关的按钮都改成代码绑定因为在Story.js里页面索引pageIndex需要同步更新用编辑器绑定没法传参数而代码绑定可以在回调里直接把参数带进去bindStoryBtn() { this.nextButton.node.on(cc.Node.EventType.TOUCH_END, () { this.pageIndex; this.showPage(this.pageIndex); }, this); }3.2 用动画组件做转场避免剧情切换太生硬剧情游戏对场景切换的流畅度要求不低。直接把整个界面换掉会显得断层常见做法是用淡入淡出或滑入滑出做一个转场过渡。Cocos Creator 里可以用cc.tween实现节点透明度渐变playFadeIn(node, duration) { node.opacity 0; cc.tween(node) .to(duration, { opacity: 255 }) .start(); }这里node.opacity控制节点整体透明度范围是 0 到 255。cc.tween(node)会创建一个跟随 node 的动画操作器.to(duration, { opacity: 255 })表示在duration秒内把透明度从当前值渐变到 255。注意cc.tween是 2.0.9 之后推荐的动画 API如果你拿到的是一个老版本项目可能需要用cc.sequence配合cc.fadeIn实现let fadeAction cc.fadeIn(0.5); node.runAction(fadeAction);两种写法的区别cc.tween支持链式调用、更易读而runAction是老 API不推荐新代码使用但老源码包里很常见。当你在水浒传的Story.js里看到runAction不要急着改成cc.tween先确认 Cocos Creator 的版本是 2.x 还是 3.x。3.x 的 API 变化很大cc.Class变成了cc class装饰器写法cc.Node.EventType移到了Node.EventType上源码包如果原始是基于 2.x 写的直接用 3.x 打开必然报一堆类型错误。3.3 剧情数据进行分层从硬编码到 JSON 驱动这套包里Story.js目前最可能的实现是硬编码剧情数组或者从某个配置读取。但合格的做法是拆成三层第一层是原始素材故事文本、角色立绘、背景图、音频。第二层是剧情配置文件描述每一幕出现哪些素材、显示顺序、点击后的跳转目标。第三层是执行脚本只关心如何渲染当前剧情节点。我一般会这样做把第二层抽成一个独立的 JSON{ storyId: shuihu_ch1, title: 高俅发迹, pages: [ { bg: textures/denglujiemian, text: 话说大宋哲宗皇帝在位时东京开封府有一个浮浪破落户子弟。, next: page_1 }, { bg: textures/shouye2.0_bg, text: 这人姓高名俅排行第二。, next: chapter_2 } ] }然后在 Story.js 里加载这个 JSONloadStoryConfig() { cc.resources.load(data/story_ch1, cc.JsonAsset, (err, asset) { if (err) { cc.error(剧情配置加载失败, err); return; } this.config asset.json; this.renderPage(0); }); }这样做的好处是美术和策划改剧情时只需要改 JSON不需要动代码。数据驱动的好处在这类源码里体现得很明显因为水浒传这种长篇故事如果把剧情全部写在 JS 里脚本会膨胀到几千行既难维护又容易在合并代码时出冲突。next字段的值是字符串而不是数字索引这个设计很关键。故事线不是永远线性的有时一段剧情根据玩家选择跳转到另一段。用字符串标识符做跳转比用数字索引健壮得多即使剧情顺序调整标识符不变跳转逻辑就不用改。渲染页面的方法可以写成renderPage(curPageId) { let pages this.config.pages; let pageData null; for (let i 0; i pages.length; i) { if (pages[i].next curPageId) { pageData pages[i]; break; } } if (!pageData) return; this.storyText.string pageData.text.replace(/\\n/g, \n); cc.resources.load(pageData.bg, cc.SpriteFrame, (err, sf) { if (!err) this.bgSprite.spriteFrame sf; }); }这里没有用findIndex是因为旧版 Cocos Creator 内置的 JS 引擎可能不支持高版本的 ES API用传统 for 循环兼容性最稳。pageData.text.replace(/\\n/g, \n)是为了处理 JSON 里写死的换行转义如果 JSON 里存的是真正的换行符这一步会破坏文本格式所以 JSON 里的换行必须写成\\n。3.4 登录界面逻辑本地校验还是服务端校验登录模块在这个源码包里以denglujiemian.jpg和denglujiemian.jpg两张图出现说明登录界面已经做过一版。单机演示项目的登录基本是假登录只在本地对比一下输入框内容。但如果你要拿这套源码做毕设建议补上服务端校验的流程至少做到账号密码从本地 JSON 读取比对这样比纯前端 if 判断更像一个完成品。checkLocalLogin(username, password) { return new Promise((resolve, reject) { cc.resources.load(data/users, cc.JsonAsset, (err, asset) { if (err) { reject(err); return; } let users asset.json.users; let matched users.find(u u.name username u.pwd password); if (matched) { cc.sys.localStorage.setItem(login_user, JSON.stringify(matched)); resolve(matched); } else { reject(new Error(账号或密码错误)); } }); }); }cc.sys.localStorage是引擎封装的本地存储接口底层是浏览器的localStorage或安卓的SharedPreferences跨平台能用一套 API。存login_user这个 key 时要把对象序列化成字符串读取时再JSON.parse回来。这里用 Promise 是为了让异步回调的流程可读性更强Cocos Creator 2.x 完全支持 Promise不需要引入额外的库。4. 日志分析、报错定位与项目迁移把源码包跑起来的关键操作4.1 从控制台日志反推项目状态拿到源码包后我建议先做三件事第一用 Cocos Creator 打开项目的根目录等待资源导入完成第二打开任意一个场景直接点击预览运行第三打开浏览器开发者工具或 Creator 自带控制台把现象和报错全部记录下来。这一步不需要理解全部代码但能快速暴露资源引用问题。常见的三类控制台日志对应完全不同的故障日志关键词含义处理方向Failed to load scene场景加载失败检查场景是否勾选、场景名是否一致url is not in res动态加载路径不对检查资源是否在 resources 目录下Can not find class脚本类未注册或脚本名不匹配检查脚本文件名与 cc.Class 注册名Can not find class这个报错最容易迷惑人脚本明明在 assets 里编辑器也能打开但运行时就是找不到类。原因通常是脚本文件名和类名不一致比如文件名是story.js但代码里cc.Class的名字是StoryCtrlCocos Creator 的序列化系统通过脚本文件名来匹配组件类型所以文件名必须和 class 名一致否则场景里挂载的组件会丢失引用。我在处理这套水浒传源码时遇到过一种情况场景里的节点挂了一个Story.js但项目里同时存在Story.js和Story.jsc后者是编译缓存文件有时没有被清理机制及时刷新导致加载了旧的编译结果。此时删除library目录和temp目录重新打开项目等引擎重新编译一次问题往往就解决了。4.2 场景迁移到 3.x 时的核心差异水浒传这套源码大概率是 2.x 时代产出的因为Menu.fire这个后缀在 3.x 项目里基本不存在。如果迫不得已要用 3.x 打开至少要处理四个层面的差异第一脚本写法从cc.Class变成类装饰器const { ccclass, property } cc._decorator; ccclass export default class Story extends cc.Component { property(cc.Label) storyText null; property(cc.Button) nextButton null; }第二资源配置从cc.resources.load变成resources.loadcc命名空间下不再直接挂resources。第三节点事件常量从cc.Node.EventType.TOUCH_END改成Node.EventType.TOUCH_END。第四cc.director.loadScene变成director.loadScene需要先import { director } from cc。这四个差异会让老代码大面积飘红。如果你没有充分的游戏开发经验不建议硬迁 3.x反而应该下载一个 Cocos Creator 2.4.x 或 2.3.x保持源码原运行环境这样省时省力且能确保功能正常。2.4 是 2.x 系列的最终版API 稳定遇到问题的资料也好搜。4.3 Android 打包前必做的三处配置很多人从网上下完源码后直接点构建结果报出各种 Android 相关错误。常见的是没有安装 Android SDK、NDK 版本不匹配、包名非法。按下面顺序排查先在项目设置-项目数据里修改包名。默认包名往往是com.creator.game这类极其普通的如果你的应用要上线包名必须唯一。然后确认构建发布平台选的是 Android并且勾选对应的 API Level。Cocos Creator 2.4 对 Android API Level 29 的兼容度较好超过 33 时旧版引擎可能会有编译问题。构建按钮点击后Creator 会生成一个build/jsb-link目录里面是原生工程。如果你最终要产出 APK需要用 Android Studio 打开jsb-link/frameworks/runtime-src/proj.android-studio这个目录在 Android Studio 里做 Gradle 构建。直接在 Creator 里点构建只是生成了原生工程和资源不等于生成了 APK。Cocos Creator 的日志面板如果显示build success只代表原生工程生成成功不代表 APK 生成成功。如果你没有接触过原生 Android 构建链路建议先看 Creators 的构建输出目录里有没有Android.apk文件通常路径是build/jsb-link/Android/apk/Android-debug.apk。如果找不到说明构建流程只走了一半需要回到 Android Studio 手动继续。5. 玩法模块扩展把静态剧情变成可操作的战斗原型5.1 从剧情节点衔接到战斗场景的接口设计水浒传只做剧情展示是不够的至少要有一个简单的战斗模块才算真正意义上的游戏。在这套源码基础上做扩展不建议在 Story.js 里堆代码而是新建一个Battle.js脚本挂在独立的战斗场景上。Story.js 在剧情跳转到战斗时传递一个起始数据startBattle(chapterId) { let battleInfo { chapterId: chapterId, enemyName: 镇关西, enemyHp: 100, heroHp: 120 }; cc.director.loadScene(battle, () { let battleScene cc.director.getScene(); let battleScript battleScene.getChildByName(BattleRoot) .getComponent(Battle); battleScript.initBattle(battleInfo); }); }第二个参数是场景加载完成的回调函数这种用法适合战斗数据不通过全局变量传递的场景。但要注意回调时机cc.director.loadScene的第二个参数在场景切换完成后马上触发此时通过cc.director.getScene()能拿到新场景的根节点再通过getChildByName找到战斗根节点。getComponent(Battle)返回脚本实例后调用initBattle传入数据。这种方式比用全局变量干净得多因为战斗数据是临时性的没必要挂到window上。用全局变量存储数据在热更新、场景销毁重建时容易出现脏数据残留比如玩家上一场战斗失败后重新挑战全局变量未被重置导致敌人血量还是上次残血的状态。5.2 序列帧动画与动作队列实现角色攻击战斗模块的核心表现是攻击动画。Cocos Creator 里最轻量的做法是使用序列帧动画组件cc.Animation播放预制的动画剪辑或者用代码控制 Sprite 的位移和透明度模拟攻击动作doAttack(heroNode, enemyNode, callback) { let originX heroNode.x; cc.tween(heroNode) .to(0.15, { x: enemyNode.x - 20 }) .to(0.1, { x: originX }) .call(() { this.showDamageNumber(30); if (callback) callback(); }) .start(); }这里heroNode.x是英雄节点的世界坐标横向位置。.to(0.15, { x: enemyNode.x - 20 })把英雄在 0.15 秒内移动到敌人左侧 20 像素处模拟突进.to(0.1, { x: originX })又用 0.1 秒拉回来模拟收招。.call(callback)是整个动画结束后执行的回调用来结算伤害。注意任何被cc.tween作用的节点如果中途要销毁或重置先调用cc.tween(node).stop()否则动画仍会尝试修改已销毁节点的属性控制台会报Destroying node相关的错误。这在快速点击攻击键时非常常见玩家连续攻击导致上一次的 tween 还在运行节点就发生了场景切换。5.3 小地图与关卡选择节点的数据组织如果你想把水浒传从单场景演示扩成多关卡游戏关卡选择界面是绕不开的。这套源码包的首页图shouye2.0_bg.jpg完全可以改造成章节选择地图在上面放置若干个可点击的标记点每个标记点挂一个ChapterNode脚本cc.Class({ extends: cc.Component, properties: { chapterId: 0, chapterName: }, onClick() { cc.log(进入章节, this.chapterId, this.chapterName); this.node.emit(chapter-selected, this.chapterId); } });this.node.emit是自定义事件派发可以在根节点或全局事件管理器里监听cc.find(Canvas).on(chapter-selected, (event) { let chapterId event.detail; this.startChapter(chapterId); }, this);event.detail就是emit的第二个参数这种自定义事件机制可以让脚本之间解耦不需要在ChapterNode里强引用Story或Battle组件。如果你不想用事件也可以用cc.find(Canvas/StoryLayer).getComponent(Story)这种方式直接访问其他组件但耦合度高项目变大后改一处就要改多处。多关卡数据也可以采用 JSON 驱动每个关卡配置对应的敌人、奖励、剧情文本、背景图。这套源码里的Story.js已经体现了剧情配置的思路战斗模块照搬这个设计模式即可。这样一来后续加新关卡美术出图、策划配数程序员只需要在 JSON 里加一段记录不用改代码项目交付效率会明显高出一截。6. 验证打包产物与检查资源引用完整性把项目跑起来只是第一步验证打包产物是否可用同样重要。构建完成后的 APK 安装到手机上第一件事不是玩而是看目录是不是齐全。针对 Web 打包产物构建完会出现build/web-mobile目录里面有一个index.html和assets文件夹。用 nginx 或任意静态文件服务器把web-mobile目录作为根目录在浏览器里访问http://localhost:8080/index.html打开控制台确认没有 404 的资源请求。Cocos Creator 的 Web 构建产物默认使用相对路径还是绝对路径取决于构建配置里的md5Cache和mainBundleCompressionType。如果资源请求全是assets/main这种压缩包格式说明开启了 bundle 合并如果请求的是assets/textures/shouye2.0_bg.png这种散文件说明资源未合并。两种都能跑但部署到 CDN 时合并包方式更利于缓存控制。针对 Android 的Android-debug.apk先安装到模拟器上然后执行adb logcat | grep -i cocosadb是安卓调试桥工具logcat是系统日志命令。grep -i cocos会把包含 cocos 关键字的所有日志行过滤出来。如果内存不足或贴图格式不支持日志里会直接打印资源加载失败信息。-i表示忽略大小写因为引擎在输出日志时有时写Cocos有时写cocos。验证完日志再检查 APK 的包名和签名信息aapt dump badging Android-debug.apk | head -n 10aapt是 Android SDK 自带的资源打包工具dump badging会输出 APK 的包名、版本号、启动 Activity、权限等信息。head -n 10只显示前 10 行避免一次输出太多。如果这一条命令报错说明 Android SDK 的 build-tools 没有配置到 PATH 环境变量里需要先export PATH$PATH:$ANDROID_HOME/build-tools/xx.xx.xx。如果aapt看不到启动入口原因多半是分包或自定义 Application 类没有正确集成 Cocos 的启动 Activity。可以打开jsb-link/frameworks/runtime-src/proj.android-studio/app/AndroidManifest.xml查看activity的android:name它在 Cocos 项目里通常是com.cocos.game.AppActivity如果被改成其他类名且未继承游戏入口逻辑APK 启动会白屏然后闪退。最后要强调一个测试点从网上拿到的源码包素材不少是跨项目复用的需要检查引用完整性。在场景文件中搜索未被引用的脚本组件名称比如场景里明明挂了Story.js但 Story.js 已经被删掉cc.Class注册不上的问题会在运行时表现为节点组件丢失。处理这类问题用一个脚本前置检查比人肉翻文件高效一些grep -r Story.js assets/scene/grep -r遍历assets/scene目录下所有.fire场景文件查找包含Story.js字样的行。如果场景文件里引用了这个脚本一定有对应记录没有任何输出说明场景与脚本之间没有引用关系可以放心删除这个脚本避免编译时白报错。grep在 Windows 上是findstr但 Cocos Creator 项目开发者大多会装 Git Bash直接在 Git Bash 里跑 Linux 命令会更顺手。这套水浒传源码说到底是一份能跑起来的 2D 剧情游戏脚手架。把它从头到尾拆一遍你收获的不是水浒传本身而是 Cocos Creator 从资源、脚本、场景到打包的整条链路。大厂经验在小项目里不一定用得上但小项目里把这条链路跑通后面接什么题材都只是换皮。本文还有配套的精品资源点击获取