[아카데미 라이프 리뷰] 판정은 웹이, 그리기는 Cocos 가 맡는 게임

// 규칙층은 브라우저를 모른다. 저장 백엔드와 사람의 화면 설정만 예외다.
const ruleRoots = ['src/run', 'src/core', 'src/lobby'].map(dir => path.join(webRoot, dir));
const allowed = new Set(['SaveStore.ts', 'AutoPreference.ts']);
for (const root of ruleRoots) {
  if (!fs.existsSync(root)) continue;
  for (const file of walkFiles(root)) {
    if (allowed.has(path.basename(file))) continue;
    const source = fs.readFileSync(file, 'utf8');
    if (/\b(window|document|localStorage|sessionStorage)\./.test(source)) {
      throw new Error(
        `규칙층은 브라우저 API 를 쓰지 않아야 합니다(서버 이식 대비): ${path.relative(webRoot, file)}`);
    }
  }
}

protected async start(): Promise<void> {
    if (EDITOR) await this.editorDriver?.prepare();
    const initial = await this.waitForInitialPresentation();
    if (!initial) return;
    /*
     * 원격 자산 길은 첫 로드보다 먼저 세워야 한다.
     *
     * 게임에서 가장 큰 로드는 첫 존이고, 그것은 update 가 아니라 여기서
     * 일어난다. update 에서만 세우면 첫 존의 캐릭터·NPC·몬스터 프레임이
     * 전부 번들로 가고, 그 뒤로는 새 로드가 없어 원격은 한 번도 불리지
     * 않는다 - 실제로 그랬다. 호스트 창에 요청이 0이었다.
     */
…
    if (!this.playerActorView || !await this.playerActorView.load(initial.playerCharacterId, initial.playerVisual)) return;
    this.ready = await this.showZone(initial);
    // 첫 장면이 실제로 섰다. Web 은 이 신호까지 "내리는 중" 을 보여 준다.
    if (this.ready) this.platformBridge?.reportStageLoaded();

public async connect(): Promise<boolean> {
    this.embedded = typeof window !== 'undefined' && window.parent !== window;
    if (!this.embedded) {
        console.error('[WebFirstPlatformBridge] Cocos 단독 실행은 지원하지 않습니다. ClientWeb에서 실행하세요.');
        return false;
    }
    if (!this.initialized) {
        window.addEventListener('message', this.receive);
        this.initialized = true;
        this.send('gameReady', {
            protocolVersion: ACADEMY_PROTOCOL_VERSION,
            rendererRevision: ACADEMY_RENDERER_REVISION,
        });
…
private readonly receive = (event: MessageEvent): void => {
    if (event.source !== window.parent || event.origin !== window.location.origin) return;
    const message = event.data as BridgeMessage | undefined;
    if (!message || message.source !== 'academy-web' || message.type !== 'setRoamPresentation') return;
    const next = message.payload as Partial<RoamPresentationSnapshot>;
    if (!this.isValidPresentation(next)) return;
    if (this.currentPresentation && next.sequence < this.currentPresentation.sequence) return;

    this.currentPresentation = next as RoamPresentationSnapshot;

const offReady = bridge.on<{ protocolVersion: number; rendererRevision?: string }>('gameReady', payload => {
  if (payload.protocolVersion !== ACADEMY_PROTOCOL_VERSION) {
    console.error(`[RoamStage] 프로토콜 불일치: web ${ACADEMY_PROTOCOL_VERSION} / game ${payload.protocolVersion}`);
    return;
  }
  if (payload.rendererRevision !== ACADEMY_RENDERER_REVISION) {
    console.error(`[RoamStage +${Date.now() - logStartedAtRef.current}ms] Cocos 렌더러 빌드 불일치:`
      + ` web=${ACADEMY_RENDERER_REVISION} game=${payload.rendererRevision ?? 'missing'}`);
  }
  readyRef.current = true;
  setConnected(true);
  onStageReadyRef.current?.();
  bridge.send('setRoamPresentation', snapshotOf(roamRef.current));

export interface SaveStore {
  load(key: string): string | null;
  save(key: string, value: string): void;
  remove(key: string): void;
}

/** 시뮬·테스트용. 프로세스 안에서만 산다. */
export function createMemorySaveStore(): SaveStore {
  const entries = new Map<string, string>();
  return {
    load: key => entries.get(key) ?? null,
    save: (key, value) => { entries.set(key, value); },
    remove: key => { entries.delete(key); },
  };
}

/** 브라우저 기본 백엔드. SSR/비브라우저 환경에서는 조용히 메모리로 동작한다. */
export function createLocalStorageSaveStore(prefix: string): SaveStore {
  if (typeof window === 'undefined' || !window.localStorage) {
    return createMemorySaveStore();
  }
  const storage = window.localStorage;
  return {
    load: key => storage.getItem(prefix + key),
    save: (key, value) => { storage.setItem(prefix + key, value); },
    remove: key => { storage.removeItem(prefix + key); },
  };
}

let version = typeof raw.schemaVersion === 'number' ? raw.schemaVersion : 0;
while (version < currentVersion) {
  const migrate = migrations[version];
  if (!migrate) {
    throw new Error(`[SaveSlot] ${key}: v${version} → v${version + 1} 마이그레이터가 없습니다.`);
  }
  raw = migrate(raw);
  version += 1;
  raw.schemaVersion = version;
}

export interface RunGateway {
  /** 이 입학 캐릭터로 이어 할 회차가 있는가. */
  hasRun(playerCharacterId: string): boolean;
  /** 이 입학 캐릭터의 회차를 읽는다. 없으면 null. */
  loadRun(playerCharacterId: string): RunSaveData | null;
  /** 회차를 남긴다. 서버가 규칙을 쥐게 되면 여기서 결과를 보내고 받는다. */
  saveRun(save: RunSaveData): void;
  /** 이 입학 캐릭터의 회차를 접는다(졸업·퇴학·새 회차). */
  clearRun(playerCharacterId: string): void;

  /** 계정(로비)을 읽는다. 없으면 null - 새 계정을 만드는 것은 부르는 쪽 몫이다. */
  loadAccount(): AccountSaveData | null;
  saveAccount(account: AccountSaveData): void;
}

export function createRng(seed: number, restoredStates?: Record<string, number>): Rng {
  const streams = new Map<string, MulberryStream>();
  const normalizedSeed = seed >>> 0;

  return {
    seed: normalizedSeed,
    stream(key: string): RngStream {
      let stream = streams.get(key);
      if (!stream) {
        const restored = restoredStates?.[key];
        stream = new MulberryStream(restored ?? (normalizedSeed ^ hashKey(key)));
        streams.set(key, stream);
      }
      return stream;
    },
    serialize(): Record<string, number> {
      const states: Record<string, number> = {};
      for (const [key, stream] of streams) states[key] = stream.state();
      return states;
    },
  };
}

/** 이 경로가 원격에서 올 것인가. 뿌리가 없으면 언제나 아니다. */
private static _isRemote(path: string): boolean {
    return !!ElAssetBundles._remoteRoot
        && ElAssetBundles._remotePrefixes.some(prefix => path.startsWith(prefix));
}