Cocos Creator 3.8 for Beginners: Build Your First Mini-Game

PHT — Fri, 09 Oct 2026 09:37:23 +0000

description: "A hands-on walkthrough to your first Cocos Creator 3.8 WeChat mini-game — project setup, the node + component model, your first TypeScript script, and the build-to-DevTools flow, with the gotchas I hit shipping a real game."

Cross-post note: This is the original article from my blog, Indie Game Lab. Read it there for the properly styled version, or keep reading here — it's identical.

TL;DR: You don't need a game-design degree to ship something on Cocos Creator 3.8 — you need the flow: create a WeChat mini-game project, understand that everything is a node with components, write one tiny TypeScript script, then build and preview in WeChat DevTools. I shipped a full survival/crafting game on this exact pipeline (the post-mortem is here), and the beginner path below is the same five steps I wish someone had handed me on day one — plus the three gotchas that cost me real hours.

This guide assumes zero Cocos experience. If you're still deciding whether Cocos is even the right engine, my engine comparison makes the call for a solo indie. If you've already built a prototype, skip to the build-and-preview section — but read the gotchas even if you skip everything else.

1. What you'll have at the end

By the end of this walkthrough you'll have a mini-game you can tap to play in WeChat DevTools: a character sprite that moves when you press a key or tap the screen, sitting in a scene you assembled yourself. It won't be the next hit — but it will be real, running code, and every game I've shipped started as exactly this: one sprite that does one thing.

More importantly, you'll internalize the one mental model Cocos is built around, because almost every beginner confusion (why doesn't my image show up? why won't it move? where do I put my code?) comes from not seeing it yet.

2. Step 1 — Create the project (and pick the right template)

Open Cocos Creator 3.8 LTS and hit New Project. Two choices matter:

Template: pick the 2D template (or the "Empty" 2D one if you want zero boilerplate). Most mini-games — including mine — are 2D.
Save path: avoid deep paths with spaces or Chinese characters. A short ASCII path like D:/dev/my-first-game saves you from cryptic build errors later.

You do not need to pick "WeChat Mini Game" as a template — that's not a starting template, it's a build target you choose later. Start in the editor like any other project; the WeChat part is a one-click build at the end.

3. Step 2 — The node + component model (the thing to understand)

This is the core. In Cocos, the scene is a tree of nodes. A node is just a position in space with a transform. It does nothing by itself. To make a node do something — show an image, play sound, run logic — you attach components to it. A sprite on screen is a node that happens to carry a Sprite component (which points at a texture) and a Transform component (where it sits).

This separation is why beginners get stuck: they add an image but forget the Sprite component, or write code but never attach the script component to a node. The rule is simple — code lives in components, components live on nodes, nodes live in the scene tree. Nothing runs unless it's attached to a node in the tree.

The whole engine in one picture: a node in the tree, the components that give it behavior, and the update loop that runs your script ~60 times a second.

4. Step 3 — Your first script (make it move)

Right-click the assets panel → New → TypeScript → name it MoveScript. Double-click to open it. Cocos gives you a stub with start() and update(). Edit it to:

import { _decorator, Component, Node } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('MoveScript')
export class MoveScript extends Component {
  update(deltaTime: number) {
    // move right at 100 units per second
    this.node.setPosition(
      this.node.position.x + 100 * deltaTime,
      this.node.position.y,
      0
    );
  }
}

Now the crucial step beginners miss: attach the script to the node. Drag MoveScript.ts from the assets panel onto your Player node in the Hierarchy, or select the node and click Add Component → Custom → MoveScript in the Inspector. Hit the play button at the top — the sprite drifts right. That's your first game logic.

5. Step 4 — Build for WeChat Mini Game

Top menu → Project → Build…. Set:

Platform: WeChat Mini Game
Start Scene: your main scene
Appid: your WeChat mini-game appid (or use the "test" appid while learning — Cocos accepts a placeholder for local preview)

Two flags matter for real projects and trip up everyone eventually:

Separate Engine: ON. It splits the engine from your code so the engine is cached by WeChat and your updates stay tiny. I left this off once and wondered why every upload was huge.
MD5 Cache: ON for production. It lets WeChat cache unchanged files so players re-download less on update.

Click Build. Cocos outputs a folder (default build/wechatgame/). You don't open that folder directly — you open it with DevTools, next step.

6. Step 5 — Preview in WeChat DevTools (the gotcha)

Install WeChat DevTools (the mini-program IDE, not the consumer WeChat app). In Cocos Preferences → Engine Manager, point "WeChat DevTools Path" at the installed executable — Cocos uses it to auto-launch the preview.

The gotcha: never open WeChat DevTools first and then build. Build from Cocos first, then let Cocos (or the "Preview" button) launch DevTools and import the folder. If DevTools is already open on a stale build, it silently shows the old version and you'll think your code didn't take. Close DevTools, build, then preview.

Five steps, in order. The only non-obvious part is step 5: build before you open DevTools, or you'll be debugging yesterday's code.

7. Three gotchas that cost me real hours

The WeChat size ceiling is real. A mini-game's main package is capped at 4 MB, with subpackages adding more. My first build blew past it in a weekend. The fix isn't "make fewer features" — it's engine subpackaging, an asset audit, and a device-tier split, which I wrote up in my bundle-size teardown. Learn the ceiling now, not at launch.
Perf is a device problem, not an editor problem. It runs smooth on your laptop and stutters on a three-year-old phone. Draw calls and overdraw dominate the frame on mobile — my runtime perf teardown shows the three moves that fixed mine. Profile on a real device early.
Code that isn't attached to a node doesn't exist. If your script "does nothing," 9 times out of 10 it's not on a node in the scene tree, or the node isn't in the active scene. Check the Hierarchy, not the code, first.

8. Where to go next

You now have a sprite that moves. That's the seed of everything. From here the natural path is: add input (tap/keyboard) to control direction, add a second node as an obstacle, then a score. When you're ready to ship something bigger than a demo, the two articles that saved my real release are the bundle-size teardown and the draw-call optimization piece — read them before your build crosses a few megabytes or your frame time crosses 16 ms.

9. Takeaways

Cocos Creator 3.8 is approachable: create a 2D project, internalize that nodes carry components and components carry your code, write one update() loop, then build to WeChat and preview through DevTools (build first, open DevTools second). The engine hides the hard parts — package ceilings and mobile perf — until launch day, so learn those constraints early via the bundle and draw-call write-ups. Everything you ship later is just more nodes, more components, and more loops. Start small, ship the sprite that moves, then grow it.

Originally published on Indie Game Lab. If you found this useful, that's where the deeper teardowns (bundle size, draw calls, the full game post-mortem) live.

DEV Community: PHT