godot-platform-console

Platform: Console

Controller-first design, certification compliance, and locked frame rates define console development.

NEVER Do

• NEVER show a mouse cursor — Certification (TRC/TCR) failure. Hide with Input.set_mouse_mode(Input.MOUSE_MODE_HIDDEN).
• NEVER skip pausing on focus loss — Monitor NOTIFICATION_APPLICATION_FOCUS_OUT and force a pause.
• NEVER let a controller disconnect go unhandled — Force pause and show reconnect UI.
• NEVER use an unlocked frame rate — Lock 30 or 60 FPS via Engine.max_fps and enable VSync.
• NEVER forget D-Pad navigation — Analog-only menus fail accessibility/TRC. Support D-Pad for all menus.
• NEVER hardcode button labels — Use GUID-based prompt mapping (controller_prompt_mapper.gd), not "Press A".
• NEVER exceed hardware memory limits — Profile RAM; Switch budgets are rigid.
• NEVER assume Joypad 0 is always Player 1 — Query Input.get_connected_joypads().
• NEVER distribute console export templates or SDKs publicly — NDA-bound.
• NEVER handle continuous analog sticks with boolean checks — Use get_vector() / get_action_strength().
• NEVER vibrate continuously without a disable option — Finite Input.start_joy_vibration() + accessibility toggle.
• NEVER expect OS window APIs on consoles — DisplayServer.window_set_mode() is ignored/fails.
• NEVER map UI to raw button indices — Use Project Input Map (ui_accept, ui_cancel, custom actions).
• NEVER rely on NOTIFICATION_WM_CLOSE_REQUEST for termination — Consoles suspend; handle focus/suspend paths.
• NEVER query inputs without flushing when frame-perfect — Input.flush_buffered_events() before critical checks.
• NEVER use == / != on analog trigger axes — Use is_equal_approx().
• NEVER leave orphaned nodes across scene transitions — Strict RAM; queue_free() and break cycles.
• NEVER write to res:// at runtime — Use user:// only.
• NEVER save synchronously on the main thread — Offload; atomic .tmp then rename.

---

Available Scripts

> MANDATORY: Read the appropriate script before implementing the corresponding pattern.

[certification_manager.gd](scripts/certification_manager.gd)

Expert TRC/TCR compliance (focus loss, controller disconnects).

[performance_scaler_fsr.gd](scripts/performance_scaler_fsr.gd)

Dynamic Resolution Scaling and FSR 2.2 management for console performance.

[server_side_projectile.gd](scripts/server_side_projectile.gd)

Direct RenderingServer/PhysicsServer bypass for high-frequency objects.

[async_save_manager.gd](scripts/async_save_manager.gd)

Atomic, corruption-resistant threaded save system.

[controller_prompt_mapper.gd](scripts/controller_prompt_mapper.gd)

GUID-based button prompt detection (PlayStation/Xbox/Switch).

[memory_budget_guard.gd](scripts/memory_budget_guard.gd)

Strict RAM monitoring for platform-specific hardware budgets.

[platform_dialog_invoker.gd](scripts/platform_dialog_invoker.gd)

Native OS dialog and virtual keyboard abstraction.

[background_data_prefetcher.gd](scripts/background_data_prefetcher.gd)

Asset pre-fetching using WorkerThreadPool to avoid level-load stutters.

[achievement_offline_queue.gd](scripts/achievement_offline_queue.gd)

Achievement/Trophy caching with offline persistence.

[console_boot_config.gd](scripts/console_boot_config.gd)

Hardware-aware hardware initialization and rendering overrides.

---

Certification Golden Path (MANDATORY scripts)

Run this checklist in order for a console-ready vertical slice. Do NOT Load optional scripts unless the row below says optional.

| Step | MANDATORY script | Do NOT Load (unless needed) |

| :--- | :--- | :--- |

| 1. Boot | [console_boot_config.gd](scripts/console_boot_config.gd) | [server_side_projectile.gd](scripts/server_side_projectile.gd) — RID bypass, not cert |

| 2. Focus / disconnect | [certification_manager.gd](scripts/certification_manager.gd) | — |

| 3. Save atomicity | [async_save_manager.gd](scripts/async_save_manager.gd) | — |

| 4. FPS / scaler / RAM | [performance_scaler_fsr.gd](scripts/performance_scaler_fsr.gd) + [memory_budget_guard.gd](scripts/memory_budget_guard.gd) | Switch: set ram_limit_mb ≈ 3072 (retail) / warn at 3584; PS/Xbox: 4096–5120 per SKU — see script @export |

| 5. Prompts | [controller_prompt_mapper.gd](scripts/controller_prompt_mapper.gd) | — |

Optional only: [achievement_offline_queue.gd](scripts/achievement_offline_queue.gd), [platform_dialog_invoker.gd](scripts/platform_dialog_invoker.gd), [background_data_prefetcher.gd](scripts/background_data_prefetcher.gd). Do NOT Load these during steps 1–5 unless achievements, system dialogs, or prefetch are in scope.

Input Handling (Input Map — not raw indices)

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

Expert Techniques

TRC failure → fix (symptom → script → doc)

| Symptom | Fix script | Doc |

| :--- | :--- | :--- |

| Mouse pointer visible in game UI | Hide via Input Map flow + Input.MOUSE_MODE_HIDDEN in boot | Custom mouse cursor |

| Game runs when dashboard/home pressed | [certification_manager.gd](scripts/certification_manager.gd) focus-out pause | Handling quit requests |

| "Press A" hardcoded on Switch | [controller_prompt_mapper.gd](scripts/controller_prompt_mapper.gd) GUID glyphs | Controllers, gamepads, and joysticks |

| Save corruption on power loss | [async_save_manager.gd](scripts/async_save_manager.gd) .tmp rename | Saving games |

| Frame time spikes / TRC perf fail | [performance_scaler_fsr.gd](scripts/performance_scaler_fsr.gd) + RAM guard | Resolution scaling |

1. Platform-Overlay-Manager (Native UI Dialogs)

Prefer [platform_dialog_invoker.gd](scripts/platform_dialog_invoker.gd) / [platform_overlay_manager.gd](scripts/platform_overlay_manager.gd) / DisplayServer.dialog_show() for TRC system messages over custom modal stacks.

2. Shader-Binary-Caching (RenderingDevice)

Enable shader/pipeline cache on fixed console GPUs; see [console_shader_manager.gd](scripts/console_shader_manager.gd) and Official Docs pipeline compilation guidance in Reference.

3. Controller-Battery-Telemetry Hook

Use Input.joy_connection_changed + Input.get_joy_info() via [controller_telemetry.gd](scripts/controller_telemetry.gd); battery level often needs a platform GDExtension under NDA.

Deep dives (on demand)

• Joypad snippets, native overlay dialogs, shader cache UUID, controller telemetry → [console-cert-patterns.md](references/console-cert-patterns.md)

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Controllers, gamepads, and joysticks — Joypad indexing, deadzones, get_vector/get_connected_joypads, and why device 0 is never assumed Player 1 on consoles.
• Controller number and vibration — Finite start_joy_vibration durations, connection signals, and haptic accessibility toggles required by TRC/TCR.
• Using InputEvent — Event flow for InputEventJoypadButton/Motion, Input Map actions, and buffered flush before frame-critical checks.
• Custom mouse cursor — Input.set_mouse_mode / hidden cursor so a visible pointer does not fail console certification.
• Handling quit requests — Focus-out / suspend paths versus NOTIFICATION_WM_CLOSE_REQUEST, which consoles often never emit.
• Keyboard, mouse, and controller UI navigation — Focus neighbors and D-Pad/gamepad UI traversal required when analog-only menus fail accessibility/TRC.
• Resolution scaling — Viewport FSR2 / scaling_3d_scale profiles used to hold locked 30/60 FPS on weak SKUs.
• Saving games — user:// persistence, save indicators, and why res:// writes are invalid on exported console builds.
• Background loading — Threaded ResourceLoader prefetch so slow console storage does not hitch level transitions.
• Using multiple threads — WorkerThreadPool offload for atomic saves and prefetch without main-thread TCR frame spikes.
• Feature tags — OS.has_feature / export tags that gate console boot overrides (VSync, max FPS, low-end GI).
• Reducing stutter from shader/pipeline compilations — Shader/pipeline caching on fixed console GPUs to avoid first-use hitch rejections.

Related Skills

Prerequisites

• godot-project-foundations — Project layout, Input Map, and export/user paths before certification hooks and console boot overrides.
• godot-input-handling — Joypad actions, deadzones, and device remapping that controller-first UI and prompt mappers build on.
• godot-gdscript-mastery — Typed notifications, signals, and thread-safe call patterns used by compliance and async save managers.

Complements

• godot-export-builds — Export presets, feature tags, and template discipline (console SDKs stay NDA-bound outside this skill).
• godot-save-load-systems — Atomic rename, cloud-ready slots, and save UX that TRC save indicators wrap.
• godot-ui-containers — Focusable Control trees and D-Pad neighbor graphs for gamepad-only menus.
• godot-performance-optimization — Frame budgets, FSR scaling, and Server-side entity patterns that keep locked FPS under TCR.
• godot-debugging-profiling — Memory/profiler tabs and monitors used to enforce Switch-class RAM ceilings.
• godot-scene-management — Aggressive queue_free / load queues so scene transitions stay inside console RAM budgets.
• godot-resource-data-patterns — Resource caching and unload strategies paired with memory budget guards.

Downstream / consumers

• godot-platform-desktop — Dual-ship PC builds that must share Input Map/actions while keeping console mouse-hidden and FPS-locked paths.
• godot-platform-mobile — Shared focus-loss / suspend pause patterns when the same title also targets handhelds.
• godot-multiplayer-networking — Online matchmaking/friends hooks that sit beside achievement queues and platform overlays.
• godot-genre-party — Multi-pad local play that consumes dynamic joypad slot discovery and prompt mapping.

Master

• godot-master — Library router and mirrored module entry for cross-skill discovery.