godot-platform-console

平台：主机

以控制器为先的设计、认证合规性和锁定帧率是主机开发的关键。

绝对不要

• 绝对不要显示鼠标光标 — 会导致认证（TRC/TCR）失败。使用 Input.set_mouse_mode(Input.MOUSE_MODE_HIDDEN) 将其隐藏。
• 绝对不要在焦点丢失时跳过暂停 — 监控 NOTIFICATION_APPLICATION_FOCUS_OUT 并强制暂停。
• 绝对不要对控制器断开连接不做处理 — 强制暂停并显示重新连接界面。
• 绝对不要使用未锁定的帧率 — 通过 Engine.max_fps 锁定为 30 或 60 FPS，并启用 VSync。
• 绝对不要忘记方向键导航 — 仅支持摇杆的菜单无法通过无障碍/TRC 检查。所有菜单都必须支持方向键。
• 绝对不要硬编码按钮标签 — 使用基于 GUID 的提示映射（controller_prompt_mapper.gd），而不是“按 A”。
• 绝对不要超出硬件内存限制 — 分析 RAM 使用情况；Switch 的预算非常严格。
• 绝对不要假设 Joypad 0 始终是 Player 1 — 查询 Input.get_connected_joypads()。
• 绝对不要公开分发主机导出模板或 SDK — 受 NDA 约束。
• 绝对不要用布尔值检查连续模拟摇杆输入 — 使用 get_vector() / get_action_strength()。
• 绝对不要在没有禁用选项的情况下持续振动 — 使用有限时长的 Input.start_joy_vibration() + 无障碍切换选项。
• 绝对不要指望主机上有操作系统窗口 API — DisplayServer.window_set_mode() 会被忽略或失败。
• 绝对不要将 UI 映射到原始按钮索引 — 使用 Project Input Map（ui_accept、ui_cancel、自定义操作）。
• 绝对不要依赖 NOTIFICATION_WM_CLOSE_REQUEST 处理终止 — 主机会进入挂起状态；应处理焦点丢失/挂起路径。
• 绝对不要在需要帧级精度时查询输入却不刷新 — 在关键检查前调用 Input.flush_buffered_events()。
• 绝对不要对模拟扳机轴使用 == / != — 使用 is_equal_approx()。
• 绝对不要在场景切换后留下孤立节点 — RAM 限制严格；调用 queue_free() 并断开循环引用。
• 绝对不要在运行时写入 res:// — 仅使用 user://。
• 绝对不要在主线程上同步保存 — 将保存操作移出主线程；先写入临时 .tmp 文件，再重命名。

---

可用脚本

必须：在实现相应模式前，先阅读对应脚本。

certification_manager.gd

专业级 TRC/TCR 合规性处理（焦点丢失、控制器断开连接）。

performance_scaler_fsr.gd

用于提升主机性能的动态分辨率缩放和 FSR 2.2 管理。

server_side_projectile.gd

绕过 RenderingServer/PhysicsServer，处理高频对象。

async_save_manager.gd

原子化、防损坏的多线程保存系统。

controller_prompt_mapper.gd

基于 GUID 的按钮提示检测（PlayStation/Xbox/Switch）。

memory_budget_guard.gd

严格监控特定平台硬件的 RAM 使用预算。

platform_dialog_invoker.gd

原生操作系统对话框和虚拟键盘抽象。

background_data_prefetcher.gd

使用 WorkerThreadPool 预取资源，避免关卡加载卡顿。

achievement_offline_queue.gd

成就/奖杯缓存与离线持久化。

console_boot_config.gd

感知硬件的初始化和渲染覆盖设置。

---

认证黄金路径（强制脚本）

按顺序运行此清单，完成可用于主机的垂直切片。除非下表标注为可选，否则不要加载可选脚本。

步骤	强制脚本	不要加载（除非需要）
1. 启动	console_boot_config.gd	server_side_projectile.gd — 绕过 RID，不用于认证
2. 焦点 / 断开连接	certification_manager.gd	—
3. 保存原子性	async_save_manager.gd	—
4. FPS / 缩放器 / RAM	performance_scaler_fsr.gd + memory_budget_guard.gd	Switch：将 ram_limit_mb 设为约 3072（零售版）/ 在 3584 时警告；PS/Xbox：根据 SKU 设为 4096–5120 — 参见脚本 @export
5. 提示词	controller_prompt_mapper.gd	—

仅限可选： achievement_offline_queue.gd、platform_dialog_invoker.gd、background_data_prefetcher.gd。除非成就、系统对话框或预取功能属于当前范围，否则在步骤 1–5 期间不要加载这些脚本。

输入处理（Input Map — 非原始索引）

func _unhandled_input(event: InputEvent) -> void:
    if event.is_action_pressed("ui_accept"):
        on_confirm()
    elif event.is_action_pressed("ui_cancel"):
        on_cancel()
    # Prompts: MANDATORY controller_prompt_mapper.gd for face-button glyphs

专家技巧

TRC 失败 → 修复（症状 → 脚本 → 文档）

症状	修复脚本	文档
游戏 UI 中显示鼠标指针	通过 Input Map 流程隐藏，并在启动时使用 Input.MOUSE_MODE_HIDDEN	自定义鼠标光标
按下仪表板 / 主页按钮后游戏仍在运行	certification_manager.gd 焦点移出时暂停	处理退出请求
Switch 上硬编码“按 A”	controller_prompt_mapper.gd GUID 按键图标	控制器、游戏手柄和操纵杆
断电导致存档损坏	async_save_manager.gd .tmp 重命名	保存游戏
帧时间峰值 / TRC 性能测试失败	performance_scaler_fsr.gd + RAM 守卫	分辨率缩放

1. Platform-Overlay-Manager（原生 UI 对话框）

对于 TRC 系统消息，优先使用 platform_dialog_invoker.gd / platform_overlay_manager.gd / DisplayServer.dialog_show()，而不是自定义模态对话框栈。

2. Shader-Binary-Caching（RenderingDevice）

在固定配置的主机 GPU 上启用着色器 / 管线缓存；参见 console_shader_manager.gd 和“参考”中的官方文档管线编译指南。

3. Controller-Battery-Telemetry Hook

通过 controller_telemetry.gd 使用 Input.joy_connection_changed + Input.get_joy_info()；电池电量通常需要使用 NDA 下的平台 GDExtension。

深入了解（按需）

• Joypad 代码片段、原生覆盖层对话框、着色器缓存 UUID、控制器遥测 → console-cert-patterns.md

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；路由到相关领域时加载相关技能 — 不要预先加载整个技能体系。

官方文档

• 控制器、游戏手柄和操纵杆 — Joypad 索引、死区、get_vector/get_connected_joypads，以及为何在主机上不能假设设备 0 就是玩家 1。
• 控制器编号与振动 — start_joy_vibration 的有限时长、连接信号，以及 TRC/TCR 要求提供的触觉无障碍开关。
• 使用 InputEvent — InputEventJoypadButton/Motion 的事件流、Input Map 操作，以及在帧关键检查前刷新缓冲区。
• 自定义鼠标光标 — Input.set_mouse_mode / 隐藏光标，避免可见指针导致主机认证失败。
• 处理退出请求 — 失去焦点 / 挂起路径与 NOTIFICATION_WM_CLOSE_REQUEST 的区别；主机通常不会触发后者。
• 键盘、鼠标和控制器 UI 导航 — 模拟摇杆专用菜单无法满足无障碍 / TRC 要求时所需的焦点邻居和方向键 / 游戏手柄 UI 导航。
• 分辨率缩放 — 用于在性能较弱的 SKU 上维持锁定 30/60 FPS 的视口 FSR2 / scaling_3d_scale 配置。
• 保存游戏 — user:// 持久化、保存指示器，以及为何在导出的主机版本中写入 res:// 无效。
• 后台加载 — 使用多线程 ResourceLoader 预加载，避免主机存储速度较慢导致关卡切换卡顿。
• 使用多个线程 — 使用 WorkerThreadPool 执行原子保存和预加载，避免主线程出现 TCR 帧峰值。
• 功能标签 — 用于控制主机启动覆盖设置（VSync、最大 FPS、低端 GI）的 OS.has_feature / 导出标签。
• 减少着色器 / 管线编译造成的卡顿 — 在固定配置的主机 GPU 上缓存着色器 / 管线，避免因首次使用时卡顿而被拒绝。

相关技能

前置条件

• godot-project-foundations — 在添加认证钩子和主机启动覆盖设置前，了解项目布局、Input Map 以及导出 / 用户路径。
• godot-input-handling — 以控制器为先的 UI 和提示词映射器所依赖的 Joypad 操作、死区和设备重新映射。
• godot-gdscript-mastery — 合规管理和异步保存管理器所使用的类型化通知、信号和线程安全调用模式。

补充技能

• godot-export-builds — 导出预设、功能标签和模板规范（控制台 SDK 受 NDA 约束，不在此技能范围内）。
• godot-save-load-systems — 原子重命名、支持云端的存档槽，以及 TRC 存档指示器所依托的存档 UX。
• godot-ui-containers — 可聚焦的 Control 树和 D-Pad 邻居图，用于纯手柄菜单。
• godot-performance-optimization — 帧预算、FSR 缩放和服务端实体模式，确保锁定的 FPS 符合 TCR 要求。
• godot-debugging-profiling — 用于确保符合 Switch 级别 RAM 上限的内存/分析器标签页和监视器。
• godot-scene-management — 积极使用 queue_free / 加载队列，确保场景切换符合控制台 RAM 预算。
• godot-resource-data-patterns — 配合内存预算检查器使用的资源缓存和卸载策略。

下游 / 使用方

• godot-platform-desktop — 同时发布 PC 版本时，需共享 Input Map/操作，同时保留控制台专用的隐藏鼠标和锁定 FPS 路径。
• godot-platform-mobile — 同一款游戏也面向掌机时，采用共享的焦点丢失 / 挂起暂停模式。
• godot-multiplayer-networking — 与成就队列和平台叠加层并行的在线匹配/好友功能接口。
• godot-genre-party — 本地多人游戏使用的多手柄支持，可动态发现手柄插槽并映射提示词。

主模块

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。