Cocos Graphics Visual Prototyping

Cocos Creator 3.x Graphics Visual Prototyping

Use when: you need runtime-visible visual feedback for a game feature but have NO image assets yet. The cc.Graphics component draws procedurally — circles, ellipses, lines, polygons — using only code.

Two Approaches: Editor Binding vs. Self-Contained VisualUI Wrapper

Approach A: Editor Binding (@property) — Use when you have Editor access

1. Add empty Node children to Canvas (e.g., PondNode, TreeNode, LotusNode, AuraNode)
2. Use @property({type: Node}) in your Component to expose these for Editor binding
3. In start(), get or auto-add Graphics component on each node
4. Define a draw config array — one entry per game state
5. Call graphics.clear() + draw commands + graphics.fill()/graphics.stroke() on state change
6. Use Tween for smooth transitions between states

Approach B: Self-Contained VisualUI Wrapper — Use when you want zero Editor steps

Create a wrapper Component that dynamically creates all Graphics nodes + Labels + Buttons in start(), then self-binds to an existing Controller. No Editor drag-drop, no @property setup — just addComponent(VisualUI) and it works.

// MeritForestVisualUI.ts — Self-contained wrapper
import { _decorator, Component, Node, Label, Button, UITransform, Color, Vec3, tween, Tween, Graphics } from 'cc';
import { MyController } from '../control/MyController';

const { ccclass } = _decorator;
const UI_LAYER = 33554432;

@ccclass('MeritForestVisualUI')
export class MeritForestVisualUI extends Component {
    private _controller: MyController | null = null;
    private _meritLabel: Label | null = null;
    private _pondNode: Node = null!;
    private _treeNode: Node = null!;

    start() {
        this._buildUI();
        this._initController();
    }

    private _buildUI(): void {
        const root = new Node('VisualRoot');
        root.parent = this.node;
        root.layer = UI_LAYER;

        // Graphics nodes (no Editor binding needed — created dynamically)
        this._pondNode = this._createGfxNode('Pond', 0, -40, 200, 150);
        this._treeNode = this._createGfxNode('Tree', 0, 60, 200, 150);

        // Labels
        this._meritLabel = this._createLabel('功德值：0', 0, 180, 32);
        
        // Buttons
        this._createButton('+100', -100, -160, () => this._addMerit(100));
    }

    private _createGfxNode(name: string, x: number, y: number, w: number, h: number): Node {
        const n = new Node(name);
        n.parent = this._root;
        n.layer = UI_LAYER;
        n.setPosition(x, y, 0);
        n.addComponent(UITransform).setContentSize(w, h);
        n.addComponent(Graphics);
        return n;
    }

    private _initController(): void {
        this._controller = MyController.instance;
        if (!this._controller) {
            this._controller = this.node.addComponent(MyController);
        }
        // Self-bind: pass our dynamically-created nodes to the Controller
        this._controller.bindPondNode(this._pondNode);
        this._controller.bindTreeNode(this._treeNode);
    }

    private _addMerit(amount: number): void {
        this._controller?.addMerit(amount);
    }

    private _createLabel(text: string, x: number, y: number, size: number): Label {
        const n = new Node();
        n.parent = this._root;
        n.layer = UI_LAYER;
        n.setPosition(x, y, 0);
        n.addComponent(UITransform).setContentSize(400, 30);
        const l = n.addComponent(Label);
        l.string = text;
        l.fontSize = size;
        l.lineHeight = size + 6;
        l.horizontalAlign = Label.HorizontalAlign.CENTER;
        l.color = new Color(255, 215, 0, 255);
        return l;
    }

    private _createButton(text: string, x: number, y: number, cb: () => void): void {
        const n = new Node();
        n.parent = this._root;
        n.layer = UI_LAYER;
        n.setPosition(x, y, 0);
        n.addComponent(UITransform).setContentSize(95, 36);
        n.addComponent(Button);
        const l = n.addComponent(Label);
        l.string = text;
        l.fontSize = 14;
        l.lineHeight = 20;
        l.horizontalAlign = Label.HorizontalAlign.CENTER;
        l.color = new Color(255, 255, 255, 220);
        n.on(Node.EventType.TOUCH_END, cb, this);
    }

    onDestroy(): void {
        // Clean up event subscriptions
        MeritVisualEventBus.clear();
    }
}

Key differences from Approach A:

• ❌ No @property decorators needed
• ❌ No Editor steps (no drag-drop, no Add Component, no config)
• ✅ The Controller must expose bindXxx() methods (not just @property slots)
• ✅ The Controller must be a Singleton or already exist on this.node
• ✅ Best for test rigs / Bootstrap patterns where you want instant Preview

Step-by-Step

1. Expose Visual Nodes as @property

import { _decorator, Component, Node, Graphics, Color, Vec3, Tween, tween } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('MyVisualController')
export class MyVisualController extends Component {
    @property({ type: Node, tooltip: '樹節點（掛 Graphics）' })
    public treeNode: Node | null = null;

    @property({ type: Node, tooltip: '蓮花節點（掛 Graphics）' })
    public lotusNode: Node | null = null;

    private _treeGfx: Graphics | null = null;
    private _lotusGfx: Graphics | null = null;

    start() {
        // Auto-get-or-add Graphics on each bound node
        this._treeGfx = this._getOrAddGraphics(this.treeNode);
        this._lotusGfx = this._getOrAddGraphics(this.lotusNode);
        this._redrawAll();
    }

    private _getOrAddGraphics(node: Node | null): Graphics | null {
        if (!node) return null;
        return node.getComponent(Graphics) || node.addComponent(Graphics);
    }
}

2. Define State-to-Visual Config Array

Each state has its own draw functions:

interface VisualConfig {
    pondColor: string;       // hex color string
    drawTree: (g: Graphics) => void;
    drawLotus: ((g: Graphics) => void) | null;
    drawAura: ((g: Graphics) => void) | null;
}

const VISUAL_CONFIGS: VisualConfig[] = [
    {  // Stage 0: Barren — gray ground, dead branches
        pondColor: '#3a3a3a',
        drawTree: (g) => {
            g.strokeColor = Color.hex('#504028');
            g.lineWidth = 2;
            g.moveTo(0, -60); g.lineTo(10, -30);
            g.moveTo(0, -60); g.lineTo(-10, -30);
            g.stroke();
        },
        drawLotus: null,
        drawAura: null,
    },
    {  // Stage 1: Seed — green dot
        pondColor: '#5a7a5a',
        drawTree: (g) => {
            g.fillColor = Color.hex('#50B450');
            g.circle(0, -30, 8); g.fill();
            g.strokeColor = Color.hex('#78643C');
            g.lineWidth = 1;
            g.moveTo(0, -22); g.lineTo(0, -60); g.stroke();
        },
        drawLotus: null,
        drawAura: null,
    },
    // ... more stages ...
];

3. Redraw on State Change

private _currentStage = 0;

private _redrawAll(): void {
    const cfg = VISUAL_CONFIGS[this._currentStage];
    this._redrawTree(cfg);
    this._redrawLotus(cfg);
    this._redrawAura(cfg);
}

private _redrawTree(cfg: VisualConfig): void {
    if (!this._treeGfx) return;
    const g = this._treeGfx;
    g.clear();
    cfg.drawTree(g);
}

// Animate transition
private _animateTransition(): void {
    const nodes = [this.treeNode, this.lotusNode, this.auraNode];
    for (const node of nodes) {
        if (!node) continue;
        node.setScale(0.95, 0.95, 1);
        Tween.stopAllByTarget(node);
        tween(node)
            .to(0.6, { scale: new Vec3(1, 1, 1) }, {
                onComplete: () => this._redrawAll()
            })
            .start();
    }
}

Graphics API Quick Reference

Note: Color.hex() takes a 6-char hex string WITHOUT #. For colors with alpha, use new Color(r, g, b, a).

Common Pitfalls

• New Nodes default to wrong layer. In Creator 3.8.8, new Node() gets layer = 1073741824 (DEFAULT). The orthographic Camera only sees layer = 33554432 (UI_2D). Always set node.layer = canvas.layer after creating visual nodes.
• Always import all referenced classes. In Creator 3.8 runtime (ES Module), getComponent('ClassName') with a string may work, but getComponent(UnimportedClass) or node.getComponent(PracticeMoteCanvas) without import { PracticeMoteCanvas } from '...' throws ReferenceError: PracticeMoteCanvas is not defined. Every class used in getComponent() / addComponent() must be explicitly imported at the top of the file.
• schedule() may not fire as expected in Creator 3.8 Preview runtime when called from a non-root component. For reliable periodic UI updates, use an update(dt) loop with a manual timer accumulator instead: if ((this._timer += dt) >= 1.0) { this._timer = 0; /* update UI */ }.
• Graphics draws in node local space. Position (0,0) is the node's pivot. Use node.setPosition(x, y, 0) to place the drawing on screen.
• Graphics has no depth sorting within one node. Draw order = call order. Draw background (pond) first, then foreground (lotus) last.
• node.active = false hides Graphics. The component does not auto-clear on deactivation. Call g.clear() before hiding if needed.
• Tween on scale works well for transitions. Combine with onComplete callback to redraw after the animation finishes. This masks the instant g.clear() + redraw with a smooth scale bounce.
• For complex scenes, use multiple Graphics nodes (one per visual element) so they can be independently positioned, scaled, and toggled.
• @property({type: Node}) slots are visible in Editor Inspector. The user drags the corresponding node from Hierarchy into the slot. This replaces manual bindXxx() methods.

Example: Director's Cut (6-Stage Forest Evolution from BuddhaHeart)

The six stages from the BuddhaHeart project demonstrate full Graphics visual range:

Each stage's draw functions are stored in a config array — adding a 7th stage requires only appending to the array.