godot-platform-console

name

godot-platform-console

description

Expert blueprint for console platforms (PlayStation, Xbox, Nintendo Switch) covering controller-first UI, certification requirements (TRCs/TCRs), platform services (achievements, cloud saves), and performance compliance. Use when targeting console releases or implementing gamepad-only interfaces. Keywords console, PlayStation, Xbox, Switch, TRC, TCR, certification, controller, gamepad, achievements.

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.

Step	MANDATORY script	Do NOT Load (unless needed)
1. Boot	console_boot_config.gd	server_side_projectile.gd — RID bypass, not cert
2. Focus / disconnect	certification_manager.gd	—
3. Save atomicity	async_save_manager.gd	—
4. FPS / scaler / RAM	performance_scaler_fsr.gd + 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	—

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)

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 focus-out pause	Handling quit requests
"Press A" hardcoded on Switch	controller_prompt_mapper.gd GUID glyphs	Controllers, gamepads, and joysticks
Save corruption on power loss	async_save_manager.gd .tmp rename	Saving games
Frame time spikes / TRC perf fail	performance_scaler_fsr.gd + RAM guard	Resolution scaling

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.

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.