cortico 0.1.0

package/src/worlds/minecraft/chests.ts

@@ -0,0 +1,292 @@
+/**
+ * 按维度与坐标保存容器上次读取的内容，供容器选择、快照和蓝图材料统计使用。
+ * 炉子另外记录槽位与预计完成时间；工作站记录放置时刻。
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { ItemStack } from './terrain.ts';
+
+/** 炉子族方块名(原版三种炉子;槽位名照原版 input/fuel/output) */
+export const FURNACE_BLOCKS = ['furnace', 'smoker', 'blast_furnace'] as const;
+
+/** 箱子族方块名(能当仓库用的那些);工作台、炉子族、酿造台都不在内 */
+export const CHEST_BLOCKS = ['chest', 'trapped_chest', 'barrel', 'ender_chest'] as const;
+
+const CHEST_KINDS = new Set<string>(CHEST_BLOCKS);
+
+/** 炉子槽位与预计完成时间的上次读数；未开窗时不持续同步。 */
+interface FurnaceState {
+  input: ItemStack | null;
+  fuel: ItemStack | null;
+  output: ItemStack | null;
+  /** 下料(或最近一次读到槽位)的时刻 */
+  loadedAt: number;
+  /** 预计完成时间；null 表示未记录预计时间。 */
+  expectedDoneAt: number | null;
+  /** 到期事件已经发过,不重复发 */
+  notified?: boolean;
+}
+
+export interface ChestRecord {
+  x: number;
+  y: number;
+  z: number;
+  dimension: string;
+  items: ItemStack[];
+  usedSlots: number;
+  slots: number;
+  /** 方块名;旧档案没有这个字段,读档按 chest 兜底 */
+  name?: string;
+  /** 我们自己放下的时刻;捡现成的没有 */
+  placedAt?: number;
+  /** 炉子族的三槽位;箱子族没有 */
+  furnace?: FurnaceState;
+}
+
+/** 缺少 name 的记录按 chest 处理。 */
+export function chestBlockName(rec: ChestRecord): string {
+  return rec.name ?? 'chest';
+}
+
+/** 类别名按整词或 `_query` 后缀匹配，与 collect 共用此规则。 */
+export function matchItemName(query: string, name: string): boolean {
+  return name === query || name.endsWith(`_${query}`);
+}
+
+/** 物品和方块名字的注册表接口；缺失时回退到后缀匹配。 */
+export interface NameRegistry {
+  itemsByName?: Record<string, unknown>;
+  blocksByName?: Record<string, unknown>;
+}
+
+/** 名字是否存在于当前注册表。 */
+export function isRealId(reg: NameRegistry | null | undefined, name: string): boolean {
+  return reg != null
+    && (reg.itemsByName?.[name] !== undefined || reg.blocksByName?.[name] !== undefined);
+}
+
+/**
+ * 注册表中存在的物品 id 只作精确匹配；其余查询按 `_query` 后缀匹配类别。
+ * 材料选择与放置核对共用此规则。
+ */
+export function matchMaterialName(
+  reg: NameRegistry | null | undefined,
+  query: string,
+  name: string,
+): boolean {
+  if (name === query) return true;
+  if (isRealId(reg, query)) return false;
+  return name.endsWith(`_${query}`);
+}
+
+function chestKey(dimension: string, p: { x: number; y: number; z: number }): string {
+  return `${dimension}:${p.x},${p.y},${p.z}`;
+}
+
+/** 容量包括空槽和同种物品的未满栈；stackMax 必须取自物品注册表。 */
+export function hasRoom(rec: ChestRecord, item: string, stackMax: number): boolean {
+  if (rec.usedSlots < rec.slots) return true;
+  return rec.items.some((i) => matchItemName(item, i.name) && i.count % stackMax !== 0);
+}
+
+export function hasItem(rec: ChestRecord, item: string): boolean {
+  return rec.items.some((i) => matchItemName(item, i.name) && i.count > 0);
+}
+
+export class ChestBook {
+  private readonly map = new Map<string, ChestRecord>();
+
+  constructor(private readonly file: string | null) {
+    this.load();
+  }
+
+  get(dimension: string, p: { x: number; y: number; z: number }): ChestRecord | undefined {
+    return this.map.get(chestKey(dimension, p));
+  }
+
+  remember(
+    dimension: string,
+    p: { x: number; y: number; z: number },
+    items: ItemStack[],
+    usedSlots: number,
+    slots: number,
+  ): void {
+    /** 刷新内容时保留原 placedAt。 */
+    const prev = this.map.get(chestKey(dimension, p));
+    const rec: ChestRecord = {
+      x: p.x, y: p.y, z: p.z, dimension, items, usedSlots, slots,
+      ...(prev?.name !== undefined ? { name: prev.name } : {}),
+      ...(prev?.placedAt !== undefined ? { placedAt: prev.placedAt } : {}),
+    };
+    this.map.set(chestKey(dimension, p), rec);
+    this.save();
+  }
+
+  /** 更新方块名及可选的放置时间，保留原内容记录。 */
+  rememberStation(
+    dimension: string,
+    p: { x: number; y: number; z: number },
+    name: string,
+    placedAt?: number,
+  ): void {
+    const k = chestKey(dimension, p);
+    const prev = this.map.get(k);
+    this.map.set(k, {
+      x: p.x, y: p.y, z: p.z, dimension,
+      items: prev?.items ?? [],
+      usedSlots: prev?.usedSlots ?? 0,
+      slots: prev?.slots ?? 0,
+      name,
+      ...(placedAt !== undefined ? { placedAt } : prev?.placedAt !== undefined ? { placedAt: prev.placedAt } : {}),
+      ...(prev?.furnace !== undefined ? { furnace: prev.furnace } : {}),
+    });
+    this.save();
+  }
+
+  /** expectedDoneAt 由调用方计算；槽位读数同步到 items。 */
+  rememberFurnace(
+    dimension: string,
+    p: { x: number; y: number; z: number },
+    name: string,
+    state: { input: ItemStack | null; fuel: ItemStack | null; output: ItemStack | null },
+    loadedAt: number,
+    expectedDoneAt: number | null,
+  ): void {
+    const k = chestKey(dimension, p);
+    const prev = this.map.get(k);
+    const items = [state.input, state.fuel, state.output].filter((s): s is ItemStack => s !== null);
+    this.map.set(k, {
+      x: p.x, y: p.y, z: p.z, dimension,
+      items, usedSlots: items.length, slots: 3,
+      name,
+      ...(prev?.placedAt !== undefined ? { placedAt: prev.placedAt } : {}),
+      furnace: { ...state, loadedAt, expectedDoneAt },
+    });
+    this.save();
+  }
+
+  due(now: number): ChestRecord[] {
+    const out: ChestRecord[] = [];
+    for (const rec of this.map.values()) {
+      const f = rec.furnace;
+      if (f && f.expectedDoneAt !== null && f.expectedDoneAt <= now && !f.notified) out.push(rec);
+    }
+    return out;
+  }
+
+  markNotified(dimension: string, p: { x: number; y: number; z: number }): void {
+    const rec = this.map.get(chestKey(dimension, p));
+    if (!rec?.furnace || rec.furnace.notified) return;
+    rec.furnace.notified = true;
+    this.save();
+  }
+
+  loadedFurnaces(dimension: string): ChestRecord[] {
+    const out: ChestRecord[] = [];
+    for (const rec of this.map.values()) {
+      const f = rec.furnace;
+      if (rec.dimension !== dimension || !f) continue;
+      if (f.input || f.output) out.push(rec);
+    }
+    return out;
+  }
+
+  /**
+   * 当前维度账上的箱子族，不含炉子族与工作台。
+   * 记录表示上次看见的状态，调用方须按历史读数措辞。
+   */
+  chestsIn(dimension: string): ChestRecord[] {
+    const out: ChestRecord[] = [];
+    for (const rec of this.map.values()) {
+      if (rec.dimension !== dimension || rec.furnace) continue;
+      if (CHEST_KINDS.has(chestBlockName(rec))) out.push(rec);
+    }
+    return out;
+  }
+
+  forget(dimension: string, p: { x: number; y: number; z: number }): boolean {
+    const removed = this.map.delete(chestKey(dimension, p));
+    if (removed) this.save();
+    return removed;
+  }
+
+  inCells(dimension: string, cells: ReadonlyArray<{ x: number; y: number; z: number }>): ChestRecord[] {
+    if (this.map.size === 0) return [];
+    const keys = new Set(cells.map((c) => chestKey(dimension, c)));
+    const out: ChestRecord[] = [];
+    for (const [k, rec] of this.map) {
+      if (keys.has(k)) out.push(rec);
+    }
+    return out;
+  }
+
+  /** 汇总当前维度容器的上次观测数量，供蓝图材料统计使用。 */
+  tally(dimension: string): Record<string, number> {
+    const out: Record<string, number> = {};
+    for (const rec of this.map.values()) {
+      if (rec.dimension !== dimension) continue;
+      for (const it of rec.items) out[it.name] = (out[it.name] ?? 0) + it.count;
+    }
+    return out;
+  }
+
+  stat(): string {
+    const n = this.map.size;
+    if (!this.file || !existsSync(this.file)) return n === 0 ? '(无文件)' : `${n} 个(未落盘)`;
+    const kb = (this.fileSize() / 1024).toFixed(1);
+    return `${n} 个 / ${kb}KB`;
+  }
+
+  clear(): string {
+    const n = this.map.size;
+    this.map.clear();
+    if (this.file) {
+      mkdirSync(dirname(this.file), { recursive: true });
+      writeFileSync(this.file, '{}\n', 'utf8');
+    }
+    return n === 0 ? '容器账本是空的' : `容器账本已清空(${n} 个)`;
+  }
+
+  private fileSize(): number {
+    return statSync(this.file!).size;
+  }
+
+  private load(): void {
+    if (!this.file || !existsSync(this.file)) return;
+    const raw = readFileSync(this.file, 'utf8').trim();
+    if (!raw) return;
+    const data = JSON.parse(raw) as Record<string, ChestRecord>;
+    for (const [k, v] of Object.entries(data)) {
+      if (typeof v?.x === 'number' && typeof v.y === 'number' && typeof v.z === 'number') {
+        const f = v.furnace;
+        this.map.set(k, {
+          x: v.x, y: v.y, z: v.z,
+          dimension: typeof v.dimension === 'string' ? v.dimension : 'overworld',
+          items: Array.isArray(v.items) ? v.items : [],
+          usedSlots: typeof v.usedSlots === 'number' ? v.usedSlots : 0,
+          slots: typeof v.slots === 'number' ? v.slots : 27,
+          ...(typeof v.name === 'string' ? { name: v.name } : {}),
+          ...(typeof v.placedAt === 'number' ? { placedAt: v.placedAt } : {}),
+          ...(f && typeof f === 'object' ? {
+            furnace: {
+              input: f.input ?? null,
+              fuel: f.fuel ?? null,
+              output: f.output ?? null,
+              loadedAt: typeof f.loadedAt === 'number' ? f.loadedAt : 0,
+              expectedDoneAt: typeof f.expectedDoneAt === 'number' ? f.expectedDoneAt : null,
+              ...(f.notified === true ? { notified: true } : {}),
+            },
+          } : {}),
+        });
+      }
+    }
+  }
+
+  private save(): void {
+    if (!this.file) return;
+    mkdirSync(dirname(this.file), { recursive: true });
+    const obj: Record<string, ChestRecord> = {};
+    for (const [k, v] of this.map) obj[k] = v;
+    writeFileSync(this.file, `${JSON.stringify(obj)}\n`, 'utf8');
+  }
+}

package/src/worlds/minecraft/client-launch.ts

@@ -0,0 +1,272 @@
+/**
+ * 从 Mojang 版本 JSON 生成客户端 Java 命令，支持 inheritsFrom 继承。
+ * client.ts 管理进程生命周期。
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+interface Rule {
+  action?: 'allow' | 'disallow';
+  os?: { name?: string; arch?: string; version?: string };
+  features?: Record<string, boolean>;
+}
+
+interface Artifact {
+  path?: string;
+  url?: string;
+}
+
+interface LibraryEntry {
+  name?: string;
+  rules?: Rule[];
+  downloads?: { artifact?: Artifact };
+}
+
+type ArgEntry = string | { rules?: Rule[]; value?: string | string[] };
+
+interface VersionJson {
+  id?: string;
+  inheritsFrom?: string;
+  jar?: string;
+  mainClass?: string;
+  assetIndex?: { id?: string };
+  arguments?: { game?: ArgEntry[]; jvm?: ArgEntry[] };
+  libraries?: LibraryEntry[];
+  type?: string;
+}
+
+interface ClientLaunchInput {
+  /** .minecraft 目录 */
+  gameDir: string;
+  /** versions/<id>/<id>.json 的 id;空 = 目录里唯一那个版本 */
+  versionId: string;
+  javaPath: string;
+  username: string;
+  /** 额外 JVM 参数(内存等),空格分隔 */
+  jvmArgs?: string[];
+  width: number;
+  height: number;
+  /** 进游戏直连的服务器;null = 停在主菜单 */
+  joinServer?: { host: string; port: number } | null;
+  /** natives 解压目录;缺省 <gameDir>/natives/<versionId> */
+  nativesDir?: string;
+  os?: NodeJS.Platform;
+  arch?: string;
+}
+
+interface ClientLaunch {
+  command: string;
+  args: string[];
+  cwd: string;
+  nativesDir: string;
+  mainClass: string;
+  /** 需要解压 dll 的 jar 绝对路径(client.ts 启动前处理) */
+  nativeJars: string[];
+  /** 实际用到的版本 id 链,child → root */
+  versionChain: string[];
+}
+
+const OS_NAMES: Partial<Record<NodeJS.Platform, string>> = {
+  win32: 'windows',
+  darwin: 'osx',
+  linux: 'linux',
+};
+
+/** 离线账号 UUID：以 OfflinePlayer:<名字> 的 MD5 生成版本 3 UUID。 */
+export function offlineUuid(username: string): string {
+  const h = createHash('md5').update(`OfflinePlayer:${username}`).digest();
+  h[6] = (h[6] & 0x0f) | 0x30;
+  h[8] = (h[8] & 0x3f) | 0x80;
+  const hex = h.toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/** maven 坐标 → libraries 下的相对路径(Fabric 的库常常只给名字不给 downloads) */
+export function mavenPath(name: string): string {
+  const [coords, ext = 'jar'] = name.split('@');
+  const parts = coords.split(':');
+  const [group, artifact, version, classifier] = parts;
+  const file = `${artifact}-${version}${classifier ? `-${classifier}` : ''}.${ext}`;
+  return [...group.split('.'), artifact, version, file].join('/');
+}
+
+export function rulesAllow(
+  rules: Rule[] | undefined,
+  ctx: { os: string; arch: string; features: Record<string, boolean> },
+): boolean {
+  if (!rules || rules.length === 0) return true;
+  let allowed = false;
+  for (const rule of rules) {
+    let match = true;
+    if (rule.os) {
+      if (rule.os.name && rule.os.name !== ctx.os) match = false;
+      if (rule.os.arch && rule.os.arch !== ctx.arch) match = false;
+      // os.version 是 osx 专用的正则,windows 上一律不匹配
+      if (rule.os.version && ctx.os !== 'osx') match = false;
+    }
+    if (rule.features) {
+      for (const [key, want] of Object.entries(rule.features)) {
+        if (Boolean(ctx.features[key]) !== want) match = false;
+      }
+    }
+    if (match) allowed = (rule.action ?? 'allow') === 'allow';
+  }
+  return allowed;
+}
+
+function flattenArgs(
+  entries: ArgEntry[] | undefined,
+  ctx: { os: string; arch: string; features: Record<string, boolean> },
+): string[] {
+  const out: string[] = [];
+  for (const entry of entries ?? []) {
+    if (typeof entry === 'string') { out.push(entry); continue; }
+    if (!rulesAllow(entry.rules, ctx)) continue;
+    if (typeof entry.value === 'string') out.push(entry.value);
+    else if (Array.isArray(entry.value)) out.push(...entry.value);
+  }
+  return out;
+}
+
+function substitute(arg: string, vars: Record<string, string>): string {
+  return arg.replace(/\$\{([\w.]+)\}/g, (whole, key: string) => vars[key] ?? whole);
+}
+
+/** child → root 的版本 JSON 链;循环继承与缺文件都当错误 */
+function loadVersionChain(gameDir: string, versionId: string): VersionJson[] | { error: string } {
+  const chain: VersionJson[] = [];
+  const seen = new Set<string>();
+  let id = versionId;
+  while (id) {
+    if (seen.has(id)) return { error: `版本继承成环: ${[...seen].join(' → ')} → ${id}` };
+    seen.add(id);
+    const file = join(gameDir, 'versions', id, `${id}.json`);
+    if (!existsSync(file)) return { error: `找不到版本文件 ${file}` };
+    let json: VersionJson;
+    try {
+      json = JSON.parse(readFileSync(file, 'utf8')) as VersionJson;
+    } catch (err) {
+      return { error: `版本文件解析失败 ${file}: ${(err as Error).message}` };
+    }
+    chain.push(json);
+    id = json.inheritsFrom ?? '';
+  }
+  return chain;
+}
+
+/** 只装了一个版本时不必填版本号 */
+export function soleVersionId(gameDir: string): string | null {
+  const dir = join(gameDir, 'versions');
+  if (!existsSync(dir)) return null;
+  // 目录名即版本 id;有 <id>.json 的才算装好了
+  const ids = readdirSync(dir).filter((name) => existsSync(join(dir, name, `${name}.json`)));
+  return ids.length === 1 ? ids[0] : null;
+}
+
+export function buildClientLaunch(input: ClientLaunchInput): ClientLaunch | { error: string } {
+  const { gameDir } = input;
+  if (!gameDir) return { error: '未配置客户端游戏目录(worlds.minecraft.client.gameDir)' };
+  if (!existsSync(gameDir)) return { error: `客户端游戏目录不存在: ${gameDir}` };
+  const versionId = input.versionId || soleVersionId(gameDir) || '';
+  if (!versionId) {
+    return { error: `${join(gameDir, 'versions')} 下不是恰好一个版本,请在 worlds.minecraft.client.versionId 里指定` };
+  }
+  const chain = loadVersionChain(gameDir, versionId);
+  if ('error' in chain) return chain;
+
+  const os = OS_NAMES[input.os ?? process.platform] ?? 'linux';
+  const arch = (input.arch ?? process.arch) === 'ia32' ? 'x86' : (input.arch ?? process.arch);
+  const features: Record<string, boolean> = {
+    is_demo_user: false,
+    has_custom_resolution: true,
+    has_quick_plays_support: false,
+    is_quick_play_singleplayer: false,
+    is_quick_play_multiplayer: Boolean(input.joinServer),
+    is_quick_play_realms: false,
+  };
+  const ctx = { os, arch, features };
+
+  // child 在前:mainClass / assetIndex 取最先声明的那个,classpath 也让 loader 排在前面
+  const pick = <K extends keyof VersionJson>(key: K): VersionJson[K] | undefined =>
+    chain.find((v) => v[key] !== undefined)?.[key];
+  const mainClass = pick('mainClass');
+  if (!mainClass) return { error: `版本 ${versionId} 没有 mainClass` };
+  const root = chain[chain.length - 1];
+  const jarId = pick('jar') ?? root.id ?? versionId;
+  const versionJar = join(gameDir, 'versions', jarId, `${jarId}.jar`);
+  if (!existsSync(versionJar)) return { error: `找不到版本主 jar: ${versionJar}` };
+  const assetIndexId = pick('assetIndex')?.id;
+  if (!assetIndexId) return { error: `版本 ${versionId} 没有 assetIndex` };
+
+  const librariesDir = join(gameDir, 'libraries');
+  const classpath: string[] = [];
+  const nativeJars: string[] = [];
+  const seenPaths = new Set<string>();
+  for (const version of chain) {
+    for (const lib of version.libraries ?? []) {
+      if (!rulesAllow(lib.rules, ctx)) continue;
+      const rel = lib.downloads?.artifact?.path ?? (lib.name ? mavenPath(lib.name) : null);
+      if (!rel) continue;
+      const abs = join(librariesDir, rel);
+      if (seenPaths.has(abs)) continue;
+      seenPaths.add(abs);
+      if (!existsSync(abs)) continue;
+      if (/natives/i.test(rel)) nativeJars.push(abs);
+      classpath.push(abs);
+    }
+  }
+  classpath.push(versionJar);
+
+  const nativesDir = input.nativesDir ?? join(gameDir, 'natives', versionId);
+  const separator = os === 'windows' ? ';' : ':';
+  const vars: Record<string, string> = {
+    auth_player_name: input.username,
+    version_name: versionId,
+    game_directory: gameDir,
+    assets_root: join(gameDir, 'assets'),
+    game_assets: join(gameDir, 'assets'),
+    assets_index_name: assetIndexId,
+    auth_uuid: offlineUuid(input.username),
+    auth_access_token: '0',
+    auth_session: '0',
+    clientid: '',
+    auth_xuid: '',
+    user_type: 'msa',
+    user_properties: '{}',
+    version_type: pick('type') ?? 'release',
+    resolution_width: String(input.width),
+    resolution_height: String(input.height),
+    natives_directory: nativesDir,
+    launcher_name: 'cortico',
+    launcher_version: '1',
+    classpath: classpath.join(separator),
+    classpath_separator: separator,
+    library_directory: librariesDir,
+    quickPlayMultiplayer: input.joinServer ? `${input.joinServer.host}:${input.joinServer.port}` : '',
+    quickPlayPath: '',
+  };
+
+  /** 继承链均未声明 JVM 参数时，使用默认的三项参数。 */
+  const jvmEntries = chain.flatMap((v) => flattenArgs(v.arguments?.jvm, ctx));
+  const jvmArgs = jvmEntries.length > 0
+    ? jvmEntries
+    : ['-Djava.library.path=${natives_directory}', '-cp', '${classpath}'];
+  const gameEntries = chain.flatMap((v) => flattenArgs(v.arguments?.game, ctx));
+
+  const args = [
+    ...jvmArgs.map((a) => substitute(a, vars)),
+    ...(input.jvmArgs ?? []),
+    mainClass,
+    ...gameEntries.map((a) => substitute(a, vars)),
+  ];
+  return {
+    command: input.javaPath || 'java',
+    args,
+    cwd: gameDir,
+    nativesDir,
+    mainClass,
+    nativeJars,
+    versionChain: chain.map((v, i) => v.id ?? (i === 0 ? versionId : '?')),
+  };
+}

package/src/worlds/minecraft/client-options.ts

@@ -0,0 +1,85 @@
+/**
+ * 启动前写入 options.txt 和 SpectatorPlus 客户端配置。
+ * 共用 gameDir 的客户端共用设置文件；独立设置需要不同目录。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { Logger } from '../../core/types.ts';
+
+/**
+ * 合并 options.txt 时保留行序与未覆盖键,缺失键追加到末尾。
+ * 值允许包含冒号,解析时只分割第一个冒号。
+ */
+export function mergeOptions(prev: string, overrides: Record<string, string>): string {
+  const remaining = new Map(Object.entries(overrides));
+  const lines = prev.split(/\r?\n/).map((line) => {
+    const at = line.indexOf(':');
+    if (at <= 0) return line;
+    const key = line.slice(0, at);
+    if (!remaining.has(key)) return line;
+    const value = remaining.get(key)!;
+    remaining.delete(key);
+    return `${key}:${value}`;
+  });
+  while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  for (const [key, value] of remaining) lines.push(`${key}:${value}`);
+  return `${lines.join('\n')}\n`;
+}
+
+/** 写入 options.txt，保留未覆盖键；缺失文件只包含传入键。 */
+function writeOptions(gameDir: string, overrides: Record<string, string>, note: string, log: Logger): void {
+  const file = join(gameDir, 'options.txt');
+  try {
+    const prev = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    const next = mergeOptions(prev, overrides);
+    if (next === prev) return;
+    writeFileSync(file, next, 'utf8');
+    log.info(`已调整 ${file}:${note}`);
+  } catch (err) {
+    log.warn(`options.txt 调整失败(不影响启动): ${(err as Error).message}`);
+  }
+}
+
+export function applyLaunchOptions(gameDir: string, log: Logger): void {
+  writeOptions(
+    gameDir,
+    { pauseOnLostFocus: 'false', onboardAccessibility: 'false', soundCategory_master: '1.0' },
+    '失焦不弹暂停菜单,跳过首启引导屏,主音量拉满',
+    log,
+  );
+}
+
+/** 将 chatVisibility 设为 FULL，以启用聊天框和命令输入。 */
+export function applyChatVisible(gameDir: string, log: Logger): void {
+  writeOptions(gameDir, { chatVisibility: '0' }, '聊天框与命令行可用', log);
+}
+
+/** SpectatorPlus 的 openScreens 控制附身目标的 GUI 同步，由 client.syncGui 配置。 */
+export function mergeSpectatorPlusConfig(prev: string, overrides: Record<string, boolean>): string {
+  let obj: Record<string, unknown> = {};
+  if (prev.trim()) {
+    const parsed: unknown = JSON.parse(prev);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      obj = parsed as Record<string, unknown>;
+    }
+  }
+  for (const [k, v] of Object.entries(overrides)) obj[k] = v;
+  return `${JSON.stringify(obj, null, 2)}\n`;
+}
+
+/** 启动前合并 config/spectatorplus/client.json；缺失文件只写 openScreens。 */
+export function applySpectatorPlusConfig(gameDir: string, log: Logger, openScreens: boolean): void {
+  const file = join(gameDir, 'config', 'spectatorplus', 'client.json');
+  try {
+    const prev = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    const next = mergeSpectatorPlusConfig(prev, { openScreens });
+    if (next === prev) return;
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, next, 'utf8');
+    log.info(`已调整 ${file}:${openScreens
+      ? 'bot 开箱子/合成/熔炉时把界面同步到摄像机画面上(GUI 演出)'
+      : 'bot 开箱子/熔炉时不把界面同步到摄像机画面上'}`);
+  } catch (err) {
+    log.warn(`SpectatorPlus 配置调整失败(不影响启动): ${(err as Error).message}`);
+  }
+}