《Cocos 游戏开发入门》3.2 绘制顺序、层级与遮罩

// src/render/render-list.ts
import { Node } from '../core/node';

export interface RenderItem {
  node: Node;
  layer: number;
  zIndex: number;
  order: number; // 遍历序号，保证同层同级稳定
}

export function buildRenderList(root: Node): RenderItem[] {
  const items: RenderItem[] = [];
  let order = 0;
  root.visit((node) => {
    if (!node.active || !node.sprite) return; // 只收集可绘制节点
    items.push({ node, layer: node.layer, zIndex: node.zIndex, order: order++ });
  });
  items.sort((a, b) => {
    if (a.layer !== b.layer) return a.layer - b.layer;
    if (a.zIndex !== b.zIndex) return a.zIndex - b.zIndex;
    return a.order - b.order; // 同层同级：保持遍历先后
  });
  return items;
}

// src/render/clip.ts
import { Node } from '../core/node';

export interface ClipRect { x: number; y: number; w: number; h: number; }

// 沿父链向上找最近的非空裁剪框
export function resolveClip(node: Node): ClipRect | null {
  let cur: Node | null = node;
  while (cur) {
    if (cur.clipRect) return cur.clipRect;
    cur = cur.parent;
  }
  return null;
}

// src/render/draw-list.ts
import type { RenderItem } from './render-list';
import { resolveClip } from './clip';
import { Node } from '../core/node';

export function drawList(
  items: RenderItem[],
  ctx: CanvasRenderingContext2D,
  drawSprite: (ctx: CanvasRenderingContext2D, node: Node) => void,
): void {
  for (const item of items) {
    const clip = resolveClip(item.node);
    if (clip) {
      ctx.save();
      ctx.beginPath();
      ctx.rect(clip.x, clip.y, clip.w, clip.h);
      ctx.clip();
    }

    const m = item.node.worldMatrix;
    ctx.save();
    ctx.setTransform(m.a, m.b, m.c, m.d, m.tx, m.ty);
    drawSprite(ctx, item.node);
    ctx.restore();

    if (clip) ctx.restore(); // 与上面的 save 配对
  }
}

// test/render-list.test.ts
import { describe, it, expect } from 'vitest';
import { Node } from '../src/core/node';
import { buildRenderList } from '../src/render/render-list';

function spriteNode(name: string, layer: number, z: number): Node {
  const n = new Node(name);
  n.layer = layer;
  n.zIndex = z;
  n.sprite = { frame: name };
  return n;
}

describe('render list', () => {
  it('先按 layer 再按 zIndex 排序', () => {
    const root = new Node('root');
    const hud = spriteNode('hud', 5, 0);
    const ground = spriteNode('ground', 1, 0);
    const player = spriteNode('player', 3, 0);
    root.addChild(hud);
    root.addChild(ground);
    root.addChild(player);

    const list = buildRenderList(root).map((i) => i.node.name);
    expect(list).toEqual(['ground', 'player', 'hud']);
  });

  it('同层同级保持遍历先后（稳定）', () => {
    const root = new Node('root');
    const a = spriteNode('coin-a', 2, 20);
    const b = spriteNode('coin-b', 2, 20);
    root.addChild(a);
    root.addChild(b);
    const list = buildRenderList(root).map((i) => i.node.name);
    expect(list).toEqual(['coin-a', 'coin-b']);
  });
});

// test/clip.test.ts
import { describe, it, expect } from 'vitest';
import { Node } from '../src/core/node';
import { buildRenderList } from '../src/render/render-list';
import { drawList } from '../src/render/draw-list';

function fakeCtx(): { calls: string[] } & Record<string, unknown> {
  const calls: string[] = [];
  const rec = (name: string) => (..._args: unknown[]) => { calls.push(name); };
  return {
    calls,
    save: rec('save'), restore: rec('restore'),
    beginPath: rec('beginPath'), rect: rec('rect'), clip: rec('clip'),
    setTransform: rec('setTransform'),
  };
}

describe('clip stack', () => {
  it('带裁剪框的节点会配对 save/restore', () => {
    const root = new Node('root');
    const view = new Node('minimap');
    view.clipRect = { x: 500, y: 20, w: 120, h: 80 };
    view.sprite = { frame: 'map' };
    root.addChild(view);

    const ctx = fakeCtx();
    drawList(buildRenderList(root), ctx as never, () => {});
    expect(ctx.calls).toEqual([
      'save', 'beginPath', 'rect', 'clip', 'save',
      'setTransform', 'restore', 'restore',
    ]);
  });
});

import { _decorator, Component, Node, Mask, UIOpacity, Graphics, Color } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('HudRoot')
export class HudRoot extends Component {
  @property(Mask)
  minimapMask: Mask | null = null;

  start(): void {
    // 顺序 = 兄弟下标，越大越晚画、越靠上
    const n: Node = this.node;
    const parent = n.parent;
    if (parent) n.setSiblingIndex(parent.children.length - 1);
  }

  fadeIn(): void {
    const op = this.node.getComponent(UIOpacity);
    if (op) op.opacity = 255;
  }

  drawFrame(): void {
    const g = this.node.getComponent(Graphics);
    if (!g) return;
    g.lineWidth = 2;
    g.strokeColor = new Color(255, 255, 255, 255);
    g.clear();
    g.rect(0, 0, 120, 80);
    g.stroke();
  }
}

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

@ccclass('RoundAvatar')
export class RoundAvatar extends Component {
  @property(Mask)
  mask: Mask | null = null;

  start(): void {
    if (!this.mask) return;
    this.mask.type = Mask.Type.GRAPHICS_ELLIPSE; // 椭圆裁剪
    this.mask.inverted = false;
  }
}