godot-gameplay-systems

name	godot-gameplay-systems
description	Build and iterate playable Godot game systems. Combines starter scaffold creation, architecture, gameplay implementation, and game-feel tuning. Use for first playable slices, new Godot 4.6 project/scene/GDScript setup, game loops, entity systems, input, collision/physics, scoring, objectives, audio hooks, camera, controls, difficulty, feedback, and maintainable structure.

Godot Gameplay Systems

Godot Reference Links

Targets Godot 4.6.x (latest stable 4.6.3, June 2026). These links use /en/stable/, so they always resolve to the current stable docs — fetch them for up-to-date nodes, classes, and method signatures rather than relying on memory.

• Latest stable docs: https://docs.godotengine.org/en/stable/
• Class reference: https://docs.godotengine.org/en/stable/classes/index.html
• GDScript reference: https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/index.html
• Step by step (nodes, scenes, scripting): https://docs.godotengine.org/en/stable/getting_started/step_by_step/index.html
• Your first 3D game: https://docs.godotengine.org/en/stable/getting_started/first_3d_game/index.html
• Idle and physics processing (_process vs _physics_process): https://docs.godotengine.org/en/stable/tutorials/scripting/idle_and_physics_processing.html
• Physics introduction: https://docs.godotengine.org/en/stable/tutorials/physics/physics_introduction.html
• Using Jolt Physics: https://docs.godotengine.org/en/stable/tutorials/physics/using_jolt_physics.html
• Inputs (InputMap, events, touch): https://docs.godotengine.org/en/stable/tutorials/inputs/index.html

Purpose

Create or evolve a playable Godot game loop with clear ownership, responsive controls, deterministic update order, and verified player-facing behavior.

Use When

Starting a new game, repairing a weak prototype, adding mechanics/entities, designing architecture, tuning camera/controls, implementing rules/objectives, or improving game feel.

Workflow

Load references/gameplay-workflows.md as the first action when the task includes first playable setup, architecture, mechanics, entities, input, camera, collision/physics, scoring, objectives, feedback, or feel tuning.

Load references/physics-engine-selection.md before adding or changing physics, collision-heavy gameplay, vehicle movement, rolling balls, mini-golf, pool/snooker, pinball, rigid-body puzzles, character controllers, sensors, high-speed projectiles, moving platforms, or physics QA. Track both references in a reference ledger with yes/no, path, and failure reason. Do not mark the gameplay phase complete while a required reference is skipped.

Load references/checklists/new-game-definition-of-done.md before claiming a new game or first playable slice is complete.

Load references/checklists/endless-runner-premium-quality.md for endless runner work.

Load references/prompt-templates.md only when the user asks for reusable prompts, starter prompts, or a task template.

Load godot-audio-generator when implementing real SFX, ambience, UI sounds, voice/TTS, or audio cleanup beyond simple placeholder hooks. Gameplay code should emit audio events; the audio skill should generate or process the actual assets and define the runtime audio matrix.

1. Inspect project structure (project.godot, scenes, autoloads), input map, current loop, camera, entities, state, UI, and diagnostics.
2. Define the one-sentence playable loop: verb, objective, feedback, fail/retry.
3. Choose small architecture boundaries via scenes/scripts: core, game, entities, systems, assets, ui, tools.
4. Implement mechanics in playable increments: input, state, entity, collision/physics, feedback, HUD/audio hook, diagnostics.
5. Tune feel: movement, acceleration, camera follow/FOV/shake, impact, cooldowns, difficulty, restart loop.
6. Keep hot paths allocation-light and the update order explicit across _process and _physics_process.
7. Verify with import/parse, a windowed run, viewport pixels, SCRIPT ERROR/ERROR: lines, and one real input path.

Packaged Scaffold

Use the bundled scaffold when starting a new project or when the user asks for a starter game:

python3 <this-skill-dir>/scripts/create_godot_game.py ./my-game

The script copies assets/godot-game/, rewrites the project name in project.godot, and keeps generated games self-contained with their own QA harness (tools/qa_capture.gd) and diagnostics autoload. Use --force only when the target directory may be overwritten. The scaffold is a Godot 4.6 GDScript "collect the relays" arena built in code: scenes/main.tscn -> scripts/game.gd orchestrator, scripts/entities/ (player, pickup), scripts/systems/ (camera rig, collision, HUD, audio, debug tools), scripts/autoload/diagnostics.gd, and tools/qa_capture.gd for -- --qa viewport capture.

Library Guidance

Godot

• Use Godot 4.6, scenes (.tscn) and GDScript (.gd); compose behavior as a node tree, not one monolithic script. Reuse PackedScene instances for entities.
• Pick a rendering method per target in project.godot (rendering/renderer/rendering_method): Forward+ for desktop, Mobile for phones/tablets, Compatibility for the Web/HTML5 export and low-end GPUs.
• Choose a physics engine in project.godot (physics/3d/physics_engine): built-in Godot Physics is the default; switch to Jolt for heavier rigid-body simulation, many contacts, stacks, and demanding stability.
• Bodies: CharacterBody3D with move_and_slide() for arcade/kinematic characters; RigidBody3D (enable continuous_cd for fast bodies) for simulated rigid bodies; StaticBody3D for level geometry; Area3D for sensors/triggers (pickups, goals, holes, damage zones). Use CollisionShape3D/CollisionPolygon3D with primitive/compound shapes, never detailed visual meshes.
• Custom distance/overlap collision stays valid for simple arcade triggers, pickups, lanes, and bullets when authored feel matters more than simulation.
• Input: define InputMap actions in project.godot, read them with the Input singleton in _physics_process, and handle discrete events in _unhandled_input/_input. Add touch (InputEventScreenTouch/InputEventScreenDrag, TouchScreenButton, or a Control virtual stick) when mobile is in scope.
• Expose tunable constants as @export vars (live-editable in the Inspector) plus an in-game debug overlay; gate debug UI from release.
• Audio: AudioStreamPlayer / AudioStreamPlayer3D routed through AudioServer buses; .ogg for looping ambience, .wav for short SFX, AudioStreamGenerator for procedural feedback. Web export still needs a user gesture before audio plays.

Common Failure Modes

• Static demo instead of playable loop.
• Mechanic parses but cannot be triggered by a real InputMap action.
• Camera/controls feel delayed or hide the next decision.
• State changes do not drive UI/audio/VFX.
• Architecture abstractions (autoloads, manager nodes) appear before mechanics need them.

Final Response

Report the reference ledger, gameplay checklist outcome, behavior, controls, changed files, architecture choices, tuned values, verification evidence, artifacts, and remaining edge cases.