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

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

performance_scaler_fsr.gd

Dynamic Resolution Scaling and FSR 2.2 management for console performance.

server_side_projectile.gd

Direct RenderingServer/PhysicsServer bypass for high-frequency objects.

async_save_manager.gd

Atomic, corruption-resistant threaded save system.

controller_prompt_mapper.gd

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

memory_budget_guard.gd

Strict RAM monitoring for platform-specific hardware budgets.

platform_dialog_invoker.gd

Native OS dialog and virtual keyboard abstraction.

background_data_prefetcher.gd

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

achievement_offline_queue.gd

Achievement/Trophy caching with offline persistence.

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.

Optional only: achievement_offline_queue.gd, platform_dialog_invoker.gd, 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)

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

Prefer platform_dialog_invoker.gd / 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 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; 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

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.