《Cocos 游戏开发实战》8.2 数值表加载与校验

// assets/scripts/game/level-loader.ts
import { _decorator, Component, JsonAsset, AssetManager, assetManager, error } from 'cc';
const { ccclass, property } = _decorator;

const BUNDLE = 'bundle-levels';

@ccclass('LevelLoader')
export class LevelLoader extends Component {
  @property({ tooltip: '关卡表在 Bundle 内的路径，不含扩展名' })
  tablePath = 'levels';

  private bundle: AssetManager.Bundle | null = null;
  private cached: JsonAsset | null = null;

  loadTable(cb: (raw: unknown, err: Error | null) => void): void {
    if (this.cached) { cb(this.cached.json, null); return; }
    if (this.bundle) { this.readFrom(this.bundle, cb); return; }
    assetManager.loadBundle(BUNDLE, (err: Error | null, bundle: AssetManager.Bundle) => {
      if (err) { error(`加载分包 ${BUNDLE} 失败: ${err.message}`); cb(null, err); return; }
      this.bundle = bundle;
      this.readFrom(bundle, cb);
    });
  }

  private readFrom(bundle: AssetManager.Bundle, cb: (raw: unknown, err: Error | null) => void): void {
    bundle.load(this.tablePath, JsonAsset, (err: Error | null, asset: JsonAsset) => {
      if (err) { error(`读取 ${this.tablePath} 失败: ${err.message}`); cb(null, err); return; }
      this.cached = asset;
      cb(asset.json, null);
    });
  }

  releaseTable(): void {
    if (!this.bundle || !this.cached) return;
    this.bundle.release(this.tablePath, JsonAsset);
    this.cached = null;
  }
}

// assets/scripts/core/validate-level.ts
import type { LevelDef, LevelTable, ObstacleDef } from './level-def';

export interface ValidationIssue { path: string; message: string; }
export interface ValidationResult { ok: boolean; issues: ValidationIssue[]; }

/** 关卡 y 的可用区间：地面线附近，允许浮空障碍但不允许埋进地里。 */
const Y_MIN = -200;
const Y_MAX = 400;

export function validateLevelTable(raw: unknown): ValidationResult {
  const issues: ValidationIssue[] = [];
  if (typeof raw !== 'object' || raw === null) {
    return { ok: false, issues: [{ path: '$', message: '根节点不是对象' }] };
  }
  const table = raw as Partial<LevelTable>;
  if (table.version !== 1) {
    issues.push({ path: 'version', message: `不支持的版本 ${String(table.version)}，期望 1` });
  }
  if (!Array.isArray(table.levels) || table.levels.length === 0) {
    issues.push({ path: 'levels', message: 'levels 必须是非空数组' });
    return { ok: false, issues };
  }

  table.levels.forEach((lv: LevelDef, i: number) => {
    const base = `levels[${i}]`;
    if (typeof lv.id !== 'string' || lv.id.length === 0) {
      issues.push({ path: `${base}.id`, message: 'id 缺失或为空' });
    }
    if (!(lv.speed > 0)) issues.push({ path: `${base}.speed`, message: 'speed 必须大于 0' });
    if (!(lv.goalX > 0)) issues.push({ path: `${base}.goalX`, message: 'goalX 必须大于 0' });

    const obstacles: ObstacleDef[] = Array.isArray(lv.obstacles) ? lv.obstacles : [];
    obstacles.forEach((ob, j) => {
      const p = `${base}.obstacles[${j}]`;
      if (!(ob.w > 0) || !(ob.h > 0)) issues.push({ path: p, message: 'w 与 h 必须为正数' });
      if (ob.y < Y_MIN || ob.y > Y_MAX) {
        issues.push({ path: `${p}.y`, message: `y=${ob.y} 超出可用区间 [${Y_MIN}, ${Y_MAX}]` });
      }
    });

    const lastX = obstacles.reduce((m, ob) => Math.max(m, ob.x), 0);
    if (lastX >= lv.goalX) {
      issues.push({ path: `${base}.goalX`, message: `终点 ${lv.goalX} 早于最后一个障碍 ${lastX}` });
    }
  });

  return { ok: issues.length === 0, issues };
}

// assets/scripts/core/validate-level.test.ts
import { describe, it, expect } from 'vitest';
import { validateLevelTable } from './validate-level';

const base = {
  version: 1,
  levels: [{
    id: 'level-01', name: 'T', speed: 300, goalX: 3600,
    obstacles: [{ type: 'block', x: 900, y: -120, w: 200, h: 40 }],
    coins: [{ x: 700, y: 40 }],
  }],
};

describe('validateLevelTable', () => {
  it('合法表通过', () => {
    expect(validateLevelTable(base).ok).toBe(true);
  });

  it('goalX 早于最后障碍时报关系错误', () => {
    const bad = structuredClone(base);
    bad.levels[0].goalX = 800;
    const r = validateLevelTable(bad);
    expect(r.ok).toBe(false);
    expect(r.issues.some((i) => i.path.endsWith('.goalX'))).toBe(true);
  });

  it('y 越界时报字段错误', () => {
    const bad = structuredClone(base);
    bad.levels[0].obstacles[0].y = -260;
    const r = validateLevelTable(bad);
    expect(r.ok).toBe(false);
  });

  it('levels 为空数组直接失败', () => {
    expect(validateLevelTable({ version: 1, levels: [] }).ok).toBe(false);
  });
});

// assets/scripts/game/level-service.ts
import { _decorator, Component, Node } from 'cc';
const { ccclass, property } = _decorator;

/** 与 core/validate-level.ts 的 ValidationResult 结构一致。 */
interface Issue { path: string; message: string; }
interface Result { ok: boolean; issues: Issue[]; }

@ccclass('LevelService')
export class LevelService extends Component {
  @property({ type: Node, tooltip: '关卡挂载根节点' })
  levelRoot: Node | null = null;

  private raw: unknown = null;

  /** validator 由 core/validate-level.ts 注入，便于单测与替换。 */
  accept(raw: unknown, validator: (v: unknown) => Result): boolean {
    const result = validator(raw);
    if (!result.ok) {
      for (const issue of result.issues) {
        console.error(`[levels] ${issue.path}: ${issue.message}`);
      }
      return false;
    }
    this.raw = raw;
    return true;
  }

  get ready(): boolean { return this.raw !== null; }
  get table(): unknown { return this.raw; }
}