《移动游戏产品的架构·客户端与移动运行时》6.2 内存水位与低端机降级

// file: src/resource/memory-budget.ts
// tier: L1
// verify: node --test test/resource/memory-budget.test.ts

export type DeviceTier = "low" | "mid" | "high";
export type ProductId = "match3" | "ark";
export type PressureLevel = "normal" | "elevated" | "high" | "critical";

export interface TierRule {
  readonly tier: DeviceTier;
  readonly belowMb: number;
  readonly budgetPercent: number;
}

export const TIER_RULES: readonly TierRule[] = [
  { tier: "low", belowMb: 4096, budgetPercent: 35 },
  { tier: "mid", belowMb: 6144, budgetPercent: 45 },
  { tier: "high", belowMb: Number.MAX_SAFE_INTEGER, budgetPercent: 50 },
];

export const PRESSURE_THRESHOLDS = {
  normal: 70,
  elevated: 85,
  high: 95,
} as const;

export interface ProductCase {
  readonly product: ProductId;
  readonly steadyLowEndMb: number;
  readonly alarmMb: number;
  readonly lowEndSharePercent: number;
}

export const PRODUCT_CASES: readonly ProductCase[] = [
  { product: "match3", steadyLowEndMb: 420, alarmMb: 520, lowEndSharePercent: 35 },
  { product: "ark", steadyLowEndMb: 1150, alarmMb: 1450, lowEndSharePercent: 15 },
];

export type DegradeStepId = "scene-unload" | "atlas-trim" | "audio-bitrate" | "texture-scale";

export interface DegradeStep {
  readonly id: DegradeStepId;
  readonly savingsPercent: number;
  readonly visibleToPlayer: "none" | "low" | "medium" | "high";
  readonly reversible: boolean;
}

export const DEGRADE_ORDER: readonly DegradeStep[] = [
  { id: "scene-unload", savingsPercent: 8, visibleToPlayer: "none", reversible: true },
  { id: "atlas-trim", savingsPercent: 6, visibleToPlayer: "low", reversible: true },
  { id: "audio-bitrate", savingsPercent: 3, visibleToPlayer: "low", reversible: true },
  { id: "texture-scale", savingsPercent: 12, visibleToPlayer: "high", reversible: false },
];

export interface AppliedStep {
  readonly id: DegradeStepId;
  readonly beforeMb: number;
  readonly afterMb: number;
  readonly savedMb: number;
}

export interface DegradePlan {
  readonly beforeMb: number;
  readonly targetMb: number;
  readonly afterMb: number;
  readonly applied: readonly AppliedStep[];
  readonly reachedTarget: boolean;
}

export interface CaseBudget {
  readonly product: ProductId;
  readonly tier: DeviceTier;
  readonly budgetMb: number;
  readonly alarmMb: number;
  readonly headroomMb: number;
  readonly fits: boolean;
}

function requireInteger(value: number, label: string): void {
  if (!Number.isInteger(value) || value < 0) {
    throw new RangeError(`${label} must be a non-negative integer, got ${value}`);
  }
}

export function tierFor(ramMb: number): DeviceTier {
  requireInteger(ramMb, "ramMb");
  for (const rule of TIER_RULES) {
    if (ramMb < rule.belowMb) {
      return rule.tier;
    }
  }
  return "high";
}

export function budgetMbFor(ramMb: number): number {
  const tier = tierFor(ramMb);
  const rule = TIER_RULES.find((item) => item.tier === tier);
  if (rule === undefined) {
    throw new Error(`no tier rule for ${tier}`);
  }
  return Math.floor((ramMb * rule.budgetPercent) / 100);
}

export function pressureLevel(usedMb: number, budgetMb: number): PressureLevel {
  requireInteger(usedMb, "usedMb");
  requireInteger(budgetMb, "budgetMb");
  if (budgetMb === 0) {
    throw new RangeError("budgetMb must be positive");
  }
  const scaled = usedMb * 100;
  if (scaled <= budgetMb * PRESSURE_THRESHOLDS.normal) {
    return "normal";
  }
  if (scaled <= budgetMb * PRESSURE_THRESHOLDS.elevated) {
    return "elevated";
  }
  if (scaled <= budgetMb * PRESSURE_THRESHOLDS.high) {
    return "high";
  }
  return "critical";
}

export function needsAlarm(level: PressureLevel): boolean {
  return level === "high" || level === "critical";
}

export function planDegradation(
  usedMb: number,
  budgetMb: number,
  targetPercent = PRESSURE_THRESHOLDS.normal,
  steps: readonly DegradeStep[] = DEGRADE_ORDER,
): DegradePlan {
  requireInteger(usedMb, "usedMb");
  requireInteger(budgetMb, "budgetMb");
  requireInteger(targetPercent, "targetPercent");
  if (targetPercent > 100) {
    throw new RangeError("targetPercent must be <= 100");
  }

  const targetMb = Math.floor((budgetMb * targetPercent) / 100);
  let current = usedMb;
  const applied: AppliedStep[] = [];

  for (const step of steps) {
    if (current <= targetMb) {
      break;
    }
    const saved = Math.max(1, Math.floor((current * step.savingsPercent) / 100));
    const next = current - saved;
    applied.push({ id: step.id, beforeMb: current, afterMb: next, savedMb: saved });
    current = next;
  }

  return {
    beforeMb: usedMb,
    targetMb,
    afterMb: current,
    applied,
    reachedTarget: current <= targetMb,
  };
}

export function caseBudget(product: ProductId, ramMb: number): CaseBudget {
  const preset = PRODUCT_CASES.find((item) => item.product === product);
  if (preset === undefined) {
    throw new Error(`unknown product: ${product}`);
  }
  const budgetMb = budgetMbFor(ramMb);
  const headroomMb = budgetMb - preset.alarmMb;
  return {
    product,
    tier: tierFor(ramMb),
    budgetMb,
    alarmMb: preset.alarmMb,
    headroomMb,
    fits: headroomMb >= 0,
  };
}

export function watermarkRows(ramMb: number): readonly CaseBudget[] {
  return PRODUCT_CASES.map((item) => caseBudget(item.product, ramMb));
}