20 术语表与文档索引 — H5 游戏厅（html5-games）

项目：html5-games ｜ 版本：v1.2 ｜ 生成日期：2026-10-06 ｜ 依据：源码分析

本篇是文档集（00-20 共 21 篇）的收官工具篇，服务两类高频检索：「这个词是什么意思」（第 1 节术语表，收录项目内被赋予特定含义或承载特定实现的词汇）与**「这个文件该读哪篇 / 这个任务该读哪几篇」**（第 2 节源码反索引、第 3 节按任务阅读路径）。术语表每条给出「一句话定义 + 首次深度阐述的篇章 + 源码落点」；定义只保证与当前源码一致，演进展望建议不在此重复（统一见《13-技术债务与演进建议》）。

1. 术语表

GameShell（统一外壳）：src/components/games/GameShell.vue（729 行含样式），79 款游戏共用的页面骨架组件——氛围背景、顶栏（标题 + HUD + 控制按钮）、按宽高比最大化的舞台、可折叠玩法说明栏、底部提示与浮层容器；以五插槽（默认舞台 / hud / actions / info / overlay）、八 props、两事件（restart / togglePause）构成「软契约」。深度解析见《07-模块详解》第 2 节、《18-代码走读实录》第 2 节，契约全表见《03-接口设计》第 3 节与《15-接口全量参考》第 2 节。

注册表（registry）：src/games/registry.ts 的 20 行模块——gameModules（import.meta.glob('@/games/*.vue') 构建期生成的「路径 → 动态 import」映射，key 形如 /src/games/<id>.vue）与 prefetchGame(id)（预取游戏 chunk 与详情页 chunk，失败静默）。文件落盘即注册，「加游戏不改注册表」是本项目接入模型的支点。见《01-系统架构》第 2 节、《18-代码走读实录》第 1 节。

单局制：产品边界术语——79 款游戏一律没有中断续玩（进度存档），局内状态随组件卸载丢弃，localStorage 只保存跨局沉淀（最高分/战绩/统计/偏好）。roguelike 地牢也是 permadeath。定义与延展方向（h5g:<id>-save 预留）见《04-数据模型》第 3 节、《16-决策记录ADR》ADR-008。

短键（短键偏差）：8 款早期游戏的存档键沿用「无 -game 后缀」短形态的历史命名现象（多数游戏的键形如 h5g:<id>-game-best）——如 h5g:snake-best（id 是 snake，本身即无后缀）、h5g:whack-a-mole-best（id 是 whack-a-mole-game，唯一的真键名漂移）。完整清单见《04-数据模型》2.3；处置原则是「不迁移、不模仿、枚举键需求走豁免表双读」，参考实现见《19-数据契约与示例集》3.5。

确定性作曲（种子作曲）：useGameBgm.ts 的 BGM 生成方式——createBgmPlan(seedKey) 是纯函数，以游戏标题为种子经 FNV-1a 哈希 + mulberry32 PRNG 确定性生成曲谱（tempo 82-118、三调式、五种和弦走向、32 步三层编制），同一游戏永远同一首曲子且零存储成本。见《07-模块详解》第 4 节、《16-决策记录ADR》ADR-004。

离屏绘制：封面管线的第一阶段——gameCoverRender.ts 在主线程于一块 640×400 的离屏 canvas 上执行 drawCover 八步绘制（暗色基底→分类色双辉光→点阵→哈希选定的几何符号→分类 pill→底部压暗→自适应标题→内描边），约 2ms，随后位图转移给 worker 编码。见《07-模块详解》第 3 节、《18-代码走读实录》第 3 节。

worker 编码（webp）：封面管线第二阶段——coverEncode.worker.ts 接收 createImageBitmap 转移来的位图，在 OffscreenCanvas 上 convertToBlob({ type: 'image/webp', quality: 0.9 })，把编码成本（软件渲染 45-65ms/张）移出主线程；worker 不可用时经 workerBroken 单向降级为主线程同步 toDataURL。见《10-性能设计与优化》第 2 节。

五插槽：GameShell 向游戏开放的五个内容出口——默认（舞台）、hud（顶栏数据区）、actions（顶栏自定义按钮）、info（玩法说明栏）、overlay（舞台浮层）；完整用法模板见《19-数据契约与示例集》第 2 节。

gs- 工具类*：GameShell.vue 542-729 行非 scoped 样式定义的类名约定（gs-chip/gs-info/gs-overlay/gs-card/gs-btn/gs-action/gs-title 等），供游戏插槽内容复用，靠 .gshell 前缀限定作用域；是「样式层面的隐式契约」，自创类名会视觉漂移。见《03-接口设计》第 7 节。

构建期注册表：对 registry 机制的设计学称呼——注册发生在 Vite 构建期（glob 扫描 + 映射内联进产物），运行时零扫描零清单零编译器；与「运行时 SFC 编译」「单一巨型 bundle」等被否决方案的对比见《01-系统架构》2.4、《16-决策记录ADR》ADR-001。

预取（prefetch）：悬停/聚焦卡片时后台下载游戏 chunk 的纯优化，GameCard.vue 的 @mouseenter/@focusin 触发 prefetchGame；预取路径刻意「钝感」（失败静默），正式打开路径负责错误兜底。见《05-核心流程》流程一。

pixi-vendor：vite.config.ts manualChunks 给 pixi.js 划分的独立 chunk 名——只有 3 款 pixi 游戏按需加载 WebGL 引擎，普通玩家不下载；同族还有 vendor（vue 全家桶）与 vueuse-vendor。见《16-决策记录ADR》ADR-009、《17-依赖全景》2.2。

世界与镜像分离：游戏状态建模纪律——高频世界数据（蛇身数组、棋盘、实体池）放普通 let 每帧原地改，只有驱动 HUD/浮层的低频标量才用 ref，避免 60fps 循环里的响应式开销。见《04-数据模型》第 3 节模式二。

状态机 ref：游戏局 lifecycle 的建模惯例——一个字符串 ref（如 'idle' | 'running' | 'paused' | 'over'）驱动 overlay 切换、输入守卫与循环节拍；「先找状态变量」是读任何陌生游戏的第一步。见《04-数据模型》第 3 节模式一。

输入缓冲：方向类输入的「下一 tick 生效」惯例（如贪吃蛇 nextDir），防止一帧内两次转向导致的自杀回穿；触屏滑动以 24px 死区过滤微抖。见《04-数据模型》第 3 节模式三、《05-核心流程》流程五。

dt clamp：帧循环里对 dt 的上限截断（Math.min(ts - last, 100) 级别）——切后台回来的一帧巨大 dt 不再导致穿模/瞬移；与 pauseWhenHidden（隐藏期跳帧不停循环）配合构成循环治理。见《07-模块详解》第 5 节。

Lookahead 调度：BGM 的精确节拍方案——调度器每 90ms 醒来，把「从当前到 0.4 秒后」该响的音符按精确 ac.currentTime 提前排入音频线程，吸收 setInterval 的毫秒级抖动。见《07-模块详解》第 4 节。

手势解锁（unlock）：浏览器自动播放策略的应对——AudioContext 必须在用户手势内创建/resume；GameShell 监听首个 pointerdown/keydown 调 unlock() 并起 BGM，随后自我注销监听。「刷新后没声音」属预期行为。见《05-核心流程》流程四。

模块级单例：无 Pinia 前提下的共享状态形态——muted（useGameAudio.ts 39 行）、bgmMuted（useGameBgm.ts 139 行）、coverCache（gameCoverRender.ts 23 行）均定义在模块顶层，import 即共享同一实例；缓存写在组件 setup 内则随实例销毁失效（源码注释的自我警告）。见《16-决策记录ADR》ADR-006。

静默降级（fire-and-forget）：存储与音频的铁律——localStorage 读写全 try/catch（隐私模式仅内存生效）、play() 音频异常吞掉、预取失败忽略；「存档失败绝不比存档丢失更贵」。见《16-决策记录ADR》ADR-007。

死字段：接口里仍在登记但无任何运行时消费的字段——engine（固定 'game'）、library（固定 'showcase'）、difficulty（全空）；新增游戏照抄即可，清理方案见《13-技术债务与演进建议》E-02/E-03。

五连（提交前五连）：质量门禁俗称——pnpm typecheck && pnpm lint && pnpm test && pnpm build（与 CI 五关对应）；触碰危险修改区（registry/GameShell/全局 composable）时加做全范式手工回归。见《09-测试与质量保障》第 3 节、《05-核心流程》第 6 节。

危险修改区：改一处波及全站的三个位置——registry glob 与详情页/测试的字符串协议、GameShell 插槽与工具类语义、全局 composable（useGameAudio/useGameBgm 单例）的行为语义。见《05-核心流程》第 6 节。

文案三同步：改游戏总数（79→80）必须同步的三处——README、index.html meta description、package.json description；games.test.ts 头注释声明其为防漂移哨兵。见《06-部署运行》第 5 节第 3 步。

2. 源码文件 ↔ 篇目反向索引

3. 按任务阅读路径

任务 A：给站点加一款新游戏（最高频）。 主线四步：《06-部署运行》第 5 节 SOP（复制范式组件 → 写组件 → 登记元数据 → 同步三处文案与验证）→《19-数据契约与示例集》第 1/2/4 节（登记对象、插槽模板、骨架三份可粘贴模板）→《11-扩展开发指南》第 1 节表 1 的十条坑位（canvas 聚焦、触屏三件套、dt clamp、清理四类、GameSfx、存档键、id 命名、Shell 参数、gs-* 类、sortOrder 接尾）→《03-接口设计》第 2-3 节（两份契约的违反后果）。完成标志：五连全绿 + 手工清单过完（拼错 id 验证兜底、静音后刷新验证恢复）。

任务 B：新增或调整一个分类。《00-项目总览》2.1（现有四分类与颜色语义）→《11-扩展开发指南》场景二（图标连字实测、分类色协调、搜索硬边界三个坑）→《03-接口设计》1.2（分类色的三处消费方）。若只改分类归属（游戏搬家）：改 category 字段即可，但注意分类色透传三处（卡片描边/封面辉光/外壳 accent 默认）的视觉抽查。

任务 C：修存档/最高分问题（读不到、写不上、键名疑惑）。《04-数据模型》全篇（键全景、best 不保证方向、8 处短键清单与不迁移裁定）→《05-核心流程》流程三（读写时序与边界：严格大于、浮点精度）→《12-FAQ与故障排查》第 5 节（故障树）→ 若涉及「按 id 枚举键」的新功能，《19-数据契约与示例集》3.5 的 bestKeyOf 双读实现 +《11-扩展开发指南》场景五。禁改清单：不批量改名旧键、不模仿短键、不复用 best 键装非纪录语义。

任务 D：上线前检查（发版清单）。《06-部署运行》第 3-4 节（构建产物结构与部署步骤、CI 五关）→《05-核心流程》第 6 节（危险修改区回归：若本版触碰 registry/GameShell/全局 composable，需每类范式点开一款手工回归）→《10-性能设计与优化》第 5 节（优化项核对：预取是否生效、pixi-vendor 是否仍隔离）→《08-安全与权限设计》第 8 节（安全清单：无运行时编译、外部引用仅字体与 Umami）→《14-配置与环境详解》第 5 节（产物实测口径）。发布后验证：旧版本停留页刷新能自愈（router.onError 路径，见《01-系统架构》2.3）。

任务 E：读懂整个项目（新接手者 60 分钟版）。《00-项目总览》第 4/5 节（目录与快速上手）→《01-系统架构》第 2 节（游戏加载机制，全书最重要的一节）→《18-代码走读实录》第 1 节（registry 逐行，20 行读懂支点）→《03-接口设计》第 2-3 节（游戏与外壳契约）→《07-模块详解》第 2-3 节（外壳与封面管线机制）→《16-决策记录ADR》通读（为什么是这样）→《13-技术债务与演进建议》第 1 节台账（哪里有坑）。之后按手头任务进入第 3 节 A-D 的专项路径。

任务 F：给项目引入新依赖或新能力（引擎/页面/主题/进度存档）。 先读《17-依赖全景》第 4-5 节（版本策略与升级敏感度排序）确认依赖面纪律 → 按《11-扩展开发指南》场景三（存档形态）/场景四（引擎接入）/场景五（新页面）/场景六（主题化）执行 → 若新能力触及「零素材」「纯静态」「单局制」三条产品边界，先读《16-决策记录ADR》ADR-004/005/007/008 与《08-安全与权限设计》第 5 节的重新设计警告——它们是边界变更评审的依据，不是可以绕过的建议。

4. 文档集总目（00-20）