1. 项目概述从“Hello World”到你的第一个游戏世界很多刚接触 Cocos Creator 的朋友在安装好编辑器后面对那个简洁的 Dashboard仪表盘界面常常会感到一丝迷茫接下来该做什么点击“新建项目”后面对一堆模板和选项又该如何选择这第一步看似简单实则决定了你后续开发体验的顺畅与否。今天我就以一个过来人的身份和你详细聊聊在 Cocos Creator 中“创建第一个项目”这件事这不仅仅是点几下鼠标更是为你未来的游戏开发之旅打下坚实的地基。创建项目远不止是生成一个文件夹那么简单。它涉及到项目类型的选择是 2D 还是 3D、模板的参考价值、引擎版本的兼容性以及项目目录结构的初始化。一个配置得当的初始项目能让你在后续添加资源、编写脚本、构建发布时事半功倍避免很多因初期设置不当而导致的“历史遗留问题”。无论你是想做一个简单的 2D 跳跃游戏还是一个有复杂场景的 3D 演示正确的开始都是成功的一半。2. 项目创建前的核心决策2D、3D 与模板解析在点击那个绿色的“新建”按钮之前有几个关键决策需要你做出。这些选择没有绝对的对错但不同的选择会导向不同的工作流和资源处理方式。2.1 2D 与 3D 项目的本质区别首先最根本的选择是项目类型2D 还是 3D这决定了编辑器默认的坐标系、摄像机、渲染管线以及一系列默认组件的配置。2D 项目坐标系使用二维的笛卡尔坐标系 (X, Y)。节点Node的 Position位置只有 X 和 Y 值Z 轴通常用于控制渲染层级即谁在前谁在后。默认摄像机是一个正交投影Orthographic摄像机。这意味着物体的大小不会因为距离摄像机的远近而改变非常适合 UI、平面精灵动画和传统的 2D 卷轴游戏。渲染与组件默认启用的是适合 2D 的渲染器并且资源管理器里会默认提供internal资源库其中包含常用的 2D 组件如Sprite精灵、Label文本、Button按钮的默认材质和着色器。适用场景休闲小游戏如消除类、跑酷类、UI 密集型应用、2D 动画演示、电子绘本等。3D 项目坐标系使用三维坐标系 (X, Y, Z)。节点在场景中拥有完整的三维位置、旋转和缩放。默认摄像机是一个透视投影Perspective摄像机。物体会产生“近大远小”的视觉效果营造出空间感和深度感。渲染与组件启用的是基于物理渲染PBR的 3D 渲染管线。默认资源会更偏向 3D 材质和模型。你会接触到MeshRenderer网格渲染器、DirectionalLight方向光等 3D 专用组件。适用场景3D 角色扮演游戏、模拟经营游戏、产品三维展示、虚拟现实VR或增强现实AR应用原型。注意Cocos Creator 是“由 2D 和 3D 融合的引擎”这意味着在 2D 项目中你完全可以添加 3D 模型和摄像机反之亦然。但选择正确的初始类型能让编辑器为你配置好最合适的默认环境减少后续的手动调整。2.2 项目模板空项目 vs. 示例项目Cocos Creator 提供了几种初始模板Empty (空项目)一个最干净的项目只包含最基础的场景和一个主摄像机。这是我最推荐新手使用的模板。因为它没有任何预设逻辑和资源强迫你从零开始理解和搭建一切学习路径最清晰。你不会被模板中复杂的预设脚本和节点关系搞晕。Simple (简单模板)对于 2D可能包含一个背景和一个可点击的按钮对于 3D可能包含一个基础地形和一个立方体。它比空项目多了一点点内容适合想快速看到一点效果的初学者但依然保持了结构的简洁。Example (示例项目)这是一个宝藏但我不建议在“第一个项目”时直接使用。它包含了大量官方制作的示例场景和脚本展示了引擎的几乎全部功能。更适合在你对基础有了一定了解后作为功能参考和代码范本来查阅和学习。直接用它作为起点项目会过于臃肿且目录结构复杂。我的建议是对于纯粹的学习和第一个项目毫不犹豫地选择Empty (空项目)。从零开始构建你遇到的每一个问题都会成为你理解引擎运作原理的契机。2.3 项目名称、路径与引擎版本项目名称使用英文、数字和下划线的组合不要使用中文和特殊字符如空格、、#等。例如MyFirstGame或test_project_01。这能避免后续在脚本引用、路径处理和平台构建时可能出现的各种编码问题。项目路径选择一个空间充足的磁盘位置。路径同样不要包含中文。建议专门建立一个文件夹如D:\CocosProjects或~/Documents/CocosProjects用来存放所有 Cocos 项目便于管理。引擎版本Dashboard 会列出你已安装的 Cocos Creator 版本。通常选择最新的稳定版LTS长期支持版。例如在撰写本文时3.8.x LTS 是一个很好的选择。LTS 版本意味着它有更长的维护周期和更好的稳定性适合项目开发。3. 详解创建流程与初始项目结构理论说完了我们动手操作。假设你已经在 Dashboard 中并且已经安装好了 Cocos Creator 编辑器。3.1 逐步操作指南启动 Dashboard打开 Cocos Dashboard你会看到“项目”和“商店”等标签页。我们关注“项目”页。点击“新建”按钮通常在页面右上角或左上方有一个显眼的“新建”按钮点击它。填写项目信息项目名称输入HelloCocos遵循上述命名规范。项目路径点击“浏览”或手动输入指向你准备好的英文路径例如D:\CocosProjects\HelloCocos。模板在下拉菜单中选择Empty。项目类型根据你的学习目标选择2D或3D。这里我们以2D为例。引擎版本选择你已安装的、最新的稳定版如3.8.1。点击“创建并打开”耐心等待编辑器初始化项目。这个过程会生成所有必要的文件夹和配置文件。3.2 初始化后的项目结构深度解析项目创建成功后编辑器会自动打开。左侧是“资源管理器”面板这里展示了你项目的整个目录结构。理解这个结构至关重要HelloCocos项目根目录 ├── assets核心资源目录 │ ├── main通常存放首个场景相关资源 │ │ ├── scene场景文件如 main.fire │ │ └── scripts脚本文件如 GameCtrl.ts │ ├── resources动态加载资源目录 │ └── ...你后续创建的其他资源文件夹 ├── settings项目设置目录 │ ├── builder.json构建流程配置 │ ├── packages插件包配置 │ └── settings.json编辑器偏好设置**不建议手动修改** ├── extensions扩展插件目录 ├── temp临时文件目录可忽略 ├── library本地资源库和导入数据**切勿提交到版本控制** ├── local本地设置和日志**切勿提交到版本控制** ├── profiles构建配置方案 ├── tsconfig.jsonTypeScript 编译配置 ├── project.json项目标识文件 └── ...其他配置文件关键目录说明assets这是你的工作目录。所有场景、脚本、纹理、声音、预制体等游戏资源都应该放在这里或它的子文件夹下。只有放在这里的资源才会被编辑器识别和管理。你可以在此目录下自由创建文件夹来分类管理资源例如assets/textures,assets/scripts,assets/prefabs。assets/resources这是一个特殊的文件夹。只有放在这个文件夹内的资源才能通过引擎的resources.load等 API 在游戏运行时进行动态加载。如果你需要从网络下载或根据条件加载资源就需要把它们放在这里。library和local这两个是由编辑器自动生成的本地缓存和设置目录。它们的内容依赖于本地开发环境如图片压缩的中间文件、导入的模型数据等。绝对不要将它们提交到 Git 等版本控制系统。通常我们会通过.gitignore文件来忽略它们。settings存放项目级别的配置。builder.json里可以配置不同平台如 Web、iOS、Android的构建选项比如包名、屏幕方向、图标等。project.json项目的“身份证”包含了项目名称、使用的引擎版本等基本信息。3.3 认识编辑器核心界面项目打开后你会看到 Cocos Creator 的主界面。它由多个面板组成可以通过“窗口”菜单打开或关闭。主要的面板包括场景编辑器Scene中央最大的区域。你在这里通过拖拽节点Node来搭建游戏场景。对于 2D 项目你看到的是一个二维画布对于 3D则是一个三维视图。层级管理器Hierarchy通常位于左上。以树状结构展示当前场景中的所有节点。节点是 Cocos Creator 中最基本的组织单位一切摄像机、精灵、灯光、甚至空物体都是节点。资源管理器Assets通常位于左下。展示你的assets目录下的所有文件。你可以在这里创建、导入、删除和管理资源。属性检查器Inspector通常位于右侧。当你选中场景中的一个节点或资源管理器中的一个资源时这里会显示该对象所有可编辑的属性。这是你配置节点和组件的核心区域。控制台Console通常位于底部。输出日志、警告和错误信息。调试脚本时你的console.log信息就会显示在这里。第一个操作在“层级管理器”中你会看到一个叫Canvas的节点和一个叫Main Camera的节点。Canvas是 2D UI 的根容器Main Camera是渲染场景的摄像机。试着在“场景编辑器”中点击它们观察“属性检查器”里内容的变化。4. 创建并运行你的第一个场景现在让我们让这个空项目“动”起来哪怕只是显示一行字。4.1 创建与保存场景在“资源管理器”中右键点击assets文件夹或你希望存放场景的文件夹比如assets/main选择“创建 - Scene”。给新场景命名为Main。你会看到一个Main.scene文件。重要习惯立即保存场景。快捷键是CtrlS(Windows) 或CmdS(Mac)。编辑器不会自动保存场景养成随手保存的习惯能避免心血白费。4.2 添加一个文本标签Hello World!确保Main.scene在场景编辑器中打开双击它。在“层级管理器”中右键点击Canvas节点选择“创建 - Node - Label”。这会在Canvas下创建一个新的文本节点。在“层级管理器”中选中这个新节点在右侧的“属性检查器”中找到Label组件。修改String属性将默认的“Label”改成“Hello, Cocos Creator!”。你还可以调整Font Size字体大小、Color颜色等属性让它看起来更醒目。使用场景编辑器顶部的移动工具快捷键 W在画布上拖动这个 Label 节点把它放到屏幕中央。4.3 创建并挂载第一个脚本游戏不能只有静态文字我们需要一点交互逻辑。在“资源管理器”中右键点击assets或assets/scripts选择“创建 - TypeScript”。命名为HelloScript。双击这个HelloScript.ts文件它会在你的默认代码编辑器如 VSCode中打开。你会看到一些默认生成的代码。我们修改它让点击文本时文本内容发生变化。将脚本内容替换为以下代码import { _decorator, Component, Node, Label, EventTouch } from cc; const { ccclass, property } _decorator; ccclass(HelloScript) export class HelloScript extends Component { property(Label) // 声明一个属性类型是Label组件用于在编辑器里关联节点 myLabel: Label | null null; // 初始化为null start() { // 为当前节点添加触摸事件监听 this.node.on(Node.EventType.TOUCH_START, this.onTouchStart, this); } onTouchStart(event: EventTouch) { if (this.myLabel) { this.myLabel.string 你点到我啦; } } onDestroy() { // 记得在组件销毁时移除监听避免内存泄漏 this.node.off(Node.EventType.TOUCH_START, this.onTouchStart, this); } }保存脚本文件CtrlS。回到 Cocos Creator 编辑器。在“层级管理器”中选中我们之前创建的 Label 节点。在“属性检查器”的最下方点击“添加组件 - 用户脚本组件 - HelloScript”。这样就把脚本挂载到了这个节点上。挂载后你会看到“属性检查器”中出现了HelloScript组件。因为我们在代码里用property(Label)声明了一个myLabel属性所以这里会显示一个“My Label”的拖拽框。我们需要将 Label 组件自身赋值给它。在“属性检查器”的上半部分找到Label组件看到其旁边有一个小小的“齿轮”图标或类似设置图标点击它选择“复制组件引用”。然后点击HelloScript组件里My Label属性右侧的“粘贴组件引用”按钮一个回形针图标。这样就将这个节点上的 Label 组件引用赋值给了脚本里的myLabel变量。这是 Cocos Creator 中非常常见的编辑器-脚本数据绑定方式。4.4 设置启动场景并预览游戏在“资源管理器”中找到你的Main.scene。右键点击它选择“设置为启动场景”。这样每次运行游戏都会默认加载这个场景。点击编辑器正上方的三角形“预览”按钮或者按CtrlP。Cocos Creator 会启动一个本地浏览器窗口来运行你的游戏。在预览窗口中用鼠标点击那行“Hello, Cocos Creator!”的文字看看它是否变成了“你点到我啦”。恭喜你已经完成了从创建项目到编写简单交互逻辑的完整流程。虽然功能简单但你已经走通了 Cocos Creator 开发的核心链路创建场景 - 添加节点与组件 - 编写脚本逻辑 - 关联脚本与节点属性 - 预览测试。5. 常见问题与排查技巧实录在实际操作中你几乎一定会遇到下面这些问题。别担心它们都是学习路上的“标配”。5.1 项目创建失败或打开缓慢问题点击创建后卡住或提示失败。排查路径问题首先检查项目路径和名称是否包含中文或特殊字符。这是最常见的原因。权限问题确保你对目标磁盘文件夹有写入权限。可以尝试在用户目录如“文档”下创建。引擎损坏在 Dashboard 中尝试重新安装或修复 Cocos Creator 编辑器。杀毒软件/防火墙干扰临时关闭它们再试。磁盘空间不足检查目标磁盘是否有足够空间。5.2 脚本编译错误或找不到组件问题保存脚本后编辑器控制台报红提示“Cannot find module ‘cc”或“Property ‘xxx’ does not exist on type ‘Node”。排查TypeScript 环境确保你的项目根目录下有tsconfig.json文件创建项目时自动生成。如果丢失可以从其他正常项目复制一个。VSCode 智能提示失效在 VSCode 中打开命令面板CtrlShiftP运行“TypeScript: Select TypeScript Version”然后选择“Use Workspace Version”使用工作区版本这会让 VSCode 使用项目node_modules里的 TypeScript。组件名拼写错误检查脚本中的ccclass(‘HelloScript’)里的名字是否和你在编辑器“添加组件”时看到的名字完全一致包括大小写。属性声明错误property(Label)中的Label必须是从cc模块正确导入的。确保文件顶部有import { Label } from ‘cc’;。5.3 预览时看不到变化或点击无效问题修改了场景或脚本但预览时还是老样子。排查场景未保存这是最最最常见的原因养成CtrlS的习惯。编辑器预览的是最后一次保存的场景状态。脚本未编译保存脚本文件CtrlS后观察编辑器底部状态栏通常会有一个编译过程。等编译完成进度条消失后再预览。预览浏览器缓存有时浏览器会缓存旧内容。可以尝试关闭预览窗口重新点击预览。在预览窗口按F12打开开发者工具在“Network”网络选项卡中勾选“Disable cache”禁用缓存然后刷新页面。事件监听目标错误检查脚本中this.node.on监听的是否是正确节点。我们的例子是监听挂载脚本的节点即 Label 节点。如果你监听的是其他节点如 Canvas点击 Label 就不会触发。节点层级与遮挡确认你的 Label 节点在Canvas之下并且没有被其他更大、透明的节点如图片遮挡。在“层级管理器”中越靠下的节点渲染在越上面。5.4 资源导入与管理混乱问题图片、声音等资源导入后显示为红色问号或在脚本中引用不到。排查导入位置确保资源文件.png,.jpg,.mp3等是直接复制到assets目录下的某个子文件夹中。编辑器会自动检测并导入生成对应的.meta文件。不要手动在操作系统里创建assets外的文件夹再拖进去。meta文件每个资源文件旁边都有一个同名的.meta文件它存储了该资源在引擎内的 UUID 和导入设置。务必将其与源文件一同提交到版本控制系统。丢失.meta文件会导致资源引用断裂。资源引用在脚本中动态加载资源必须把资源放在assets/resources目录或它的子目录下并使用resources.load路径。例如如果图片在assets/resources/images/hero.png加载路径就是images/hero。5.5 项目迁移或分享后出错问题把项目拷贝给同事或换一台电脑打开报各种资源丢失错误。解决方案提交正确的文件确保将assets,settings,project.json,tsconfig.json等目录和文件提交。务必忽略library,local,temp以及node_modules如果有目录。一个标准的.gitignore文件对于 Cocos Creator 项目至关重要。重新导入如果对方打开后资源显示红色可以尝试在“资源管理器”中右键点击assets根目录选择“重新导入全部资源”。编辑器会重新扫描并生成.meta文件如果源文件还在。引擎版本一致尽量保证团队使用相同的主要版本如都是 3.8.x的 Cocos Creator。不同大版本之间可能存在不兼容的改动。创建第一个项目的旅程到此告一段落。回顾一下我们不仅学会了点击按钮更深入理解了 2D/3D 的选择、项目模板的意义、目录结构背后的逻辑以及从场景搭建到脚本交互的完整闭环。记住在 Cocos Creator 中一切皆节点功能靠组件。当你遇到问题时多利用控制台的报错信息多查阅官方文档虽然有些地方可能比较简略并且善用社区搜索。这个小小的“Hello World”项目就是你庞大游戏世界的第一个像素点。接下来试着改变文本的颜色、位置添加一张背景图或者让文字动起来每一步尝试都会让你对引擎的理解更深一分。