agentleFS
pbzonapbzona/godot-skills/skills/godot-3d-gameplay/SKILL.md

godot-3d-gameplay

Skill2 starsChanged 4 months agoMITView on GitHub

Builds and troubleshoots Godot 4.x 3D gameplay, including CharacterBody3D controllers, jumping and slopes, third-person cameras, SpringArm3D collision, WorldEnvironment, lights, shadows, and 3D verification. Use when a request mentions 3D movement, camera follow or orbit, environments, lighting, or gameplay feel.

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. About 0 are common, 10 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do not write scenes, scripts, or project settings until this inspection is complete.

    line 16
  2. Very specific:

    Run the project's established Godot executable with --version when available.

    line 19
  3. Distinctive:

    If the editor version, project feature tag, and requested API disagree, stop and resolve the version mismatch before authoring resources.

    line 25
  4. Very specific:

    Use CharacterBody3D for script-directed avatars that need floor, wall, slope, and moving-platform behavior.

    line 29
  5. Very specific:

    Use AnimatableBody3D for script- or animation-driven platforms that should carry characters.

    line 30
  6. Very specific:

    Use RigidBody3D for bodies whose motion should come from forces and impulses.

    line 31
  7. Distinctive:

    Keep collision, gameplay state, visuals, and camera pivots in separate child branches when they change for different reasons.

    line 32
  8. Distinctive:

    Use Input Map actions, not physical key constants, so keyboard and gamepad bindings can share gameplay code.

    line 33
  9. Very specific:

    Use a SpringArm3D camera rig when level geometry can move between the subject and camera.

    line 34
  10. Very specific:

    Start with one WorldEnvironment and one primary light.

    line 35
  11. Distinctive:

    Test controller, camera, and lighting together in representative geometry before polishing animation or effects.

    line 45
  12. Distinctive:

    Run the project's own checks first, then perform all applicable steps:

    line 106
  13. Very specific:

    Import and parse with the matching editor.

    line 108
  14. Distinctive:

    Run the player scene and at least one integrated level.

    line 109
  15. Distinctive:

    Test start, stop, reverse, diagonal input, no-input deceleration, jump press versus hold, ceiling contact, ledges, stairs, shallow and …

    line 110
  16. Distinctive:

    Test at low and high rendered frame rates while keeping physics behavior stable.

    line 112
  17. Distinctive:

    Use visible collision shapes and the remote scene tree to verify collider alignment, layers, masks, active environment, and runtime …

    line 113

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Godot 3D Gameplay

Implement 3D gameplay as a coordinated physics, camera, and rendering system. Preserve the project's existing architecture and tune from observed behavior rather than replacing working systems with a generic controller.

Inspect Before Editing

Do not write scenes, scripts, or project settings until this inspection is complete.

  1. Find project.godot and confirm the project root. Read config/features, the rendering method, physics tick rate, display settings, 3D physics layer names, and existing Input Map actions.
  2. Run the project's established Godot executable with --version when available. Match APIs to that exact Godot 4.x release; do not silently upgrade the project or its resource formats.
  3. Inspect representative .tscn, .gd, and imported 3D assets. Record scene ownership, node naming, typed GDScript style, signal style, groups, autoloads, folder layout, and whether node references use exported nodes, unique names, or paths.
  4. Inspect the current player, camera, level, environment, collision layers and masks, model scale, applied transforms, and input bindings. Check whether meshes or resources are shared before editing them.
  5. Identify the target renderer and hardware. A Forward+ desktop scene, a Mobile-renderer game, and a Compatibility project require different lighting and environment choices.
  6. Establish a runnable baseline and note existing warnings. Do not attribute pre-existing errors to the requested change.

If the editor version, project feature tag, and requested API disagree, stop and resolve the version mismatch before authoring resources.

Choose the Smallest Suitable Design

  • Use CharacterBody3D for script-directed avatars that need floor, wall, slope, and moving-platform behavior.
  • Use AnimatableBody3D for script- or animation-driven platforms that should carry characters.
  • Use RigidBody3D for bodies whose motion should come from forces and impulses. Do not drive one like a character by overwriting its transform every frame.
  • Keep collision, gameplay state, visuals, and camera pivots in separate child branches when they change for different reasons.
  • Use Input Map actions, not physical key constants, so keyboard and gamepad bindings can share gameplay code.
  • Use a SpringArm3D camera rig when level geometry can move between the subject and camera.
  • Start with one WorldEnvironment and one primary light. Add post-processing and extra shadowed lights only after the base image reads clearly.

Implementation Workflow

  1. Define observable behavior: movement reference frame, top speed, acceleration, air control, slope limit, jump rules, camera range, camera collision, and visual target.
  2. Build or adapt a reusable player scene. Align the capsule or other simple collider to the feet, keep the visual model transform local, and leave the root at identity for clean instancing.
  3. Confirm action names and deadzones in the Input Map. Reuse project actions where their semantics match.
  4. Implement physics in _physics_process(delta). Treat CharacterBody3D.velocity as units per second and call move_and_slide() once per physics tick.
  5. Implement look events in _unhandled_input(event) unless the project has an input router. Keep yaw and pitch on separate pivots and exclude the player collider from the spring arm.
  6. Establish the environment and lighting for readability first. Tune sky or background, ambient contribution, key-light direction, exposure, fog, and shadows as one composition.
  7. Test controller, camera, and lighting together in representative geometry before polishing animation or effects.

Typed Controller Example

Adapt names and structure to the inspected project. Assign view_camera in the Inspector and define move_left, move_right, move_forward, move_back, and jump actions.

extends CharacterBody3D

@export_range(0.1, 30.0, 0.1) var move_speed: float = 7.0
@export_range(0.1, 100.0, 0.1) var ground_acceleration: float = 28.0
@export_range(0.1, 100.0, 0.1) var air_acceleration: float = 9.0
@export_range(0.1, 30.0, 0.1) var jump_velocity: float = 8.5
@export var view_camera: Camera3D

var gravity: float = float(
    ProjectSettings.get_setting("physics/3d/default_gravity", 9.8)
)

func _ready() -> void:
    assert(is_instance_valid(view_camera), "Assign the movement camera")

func _physics_process(delta: float) -> void:
    var move_input: Vector2 = Input.get_vector(
        &"move_left", &"move_right", &"move_forward", &"move_back"
    )

    # Camera +Z points backward, matching the positive Y returned for move_back.
    var camera_back: Vector3 = view_camera.global_transform.basis.z
    var camera_right: Vector3 = view_camera.global_transform.basis.x
    camera_back.y = 0.0
    camera_right.y = 0.0
    camera_back = camera_back.normalized()
    camera_right = camera_right.normalized()

    var wish_direction: Vector3 = (
        camera_right * move_input.x + camera_back * move_input.y
    ).limit_length(1.0)
    var target_velocity: Vector3 = wish_direction * move_speed
    var response: float = (
        ground_acceleration if is_on_floor() else air_acceleration
    )

    velocity.x = move_toward(velocity.x, target_velocity.x, response * delta)
    velocity.z = move_toward(velocity.z, target_velocity.z, response * delta)

    if is_on_floor():
        if velocity.y < 0.0:
            velocity.y = 0.0
        if Input.is_action_just_pressed(&"jump"):
            velocity.y = jump_velocity
    else:
        velocity.y -= gravity * delta

    move_and_slide()

Tune floor_max_angle, floor_snap_length, floor_stop_on_slope, platform layers, and platform_on_leave on the body rather than recreating those behaviors ad hoc. Add coyote time, jump buffering, sprinting, or root motion only when the game specification calls for them.

Verification

Run the project's own checks first, then perform all applicable steps:

  • Import and parse with the matching editor. If the project supports headless validation, use <godot> --headless --path <project> --editor --quit and inspect the full output.
  • Run the player scene and at least one integrated level. Confirm there is exactly one active gameplay camera.
  • Test start, stop, reverse, diagonal input, no-input deceleration, jump press versus hold, ceiling contact, ledges, stairs, shallow and over-limit slopes, walls, corners, and moving platforms.
  • Rotate the camera through its full range. Check movement orientation, pitch clamps, camera collision, recovery after an obstruction, near-clip intersections, and mouse capture release.
  • Test at low and high rendered frame rates while keeping physics behavior stable. Look for frame-dependent camera smoothing and animation code.
  • Use visible collision shapes and the remote scene tree to verify collider alignment, layers, masks, active environment, and runtime transforms.
  • Compare representative dark, bright, indoor, and outdoor views. Check exposure, silhouettes, shadow acne, peter-panning, fog readability, and material response.
  • Profile on target-class hardware before retaining expensive shadows, volumetric effects, screen-space effects, or many dynamic lights.
  • Re-run the baseline and report changed files, settings, tests, and any device or visual checks that could not be performed.

Pitfalls

  • Multiplying CharacterBody3D.velocity by delta before move_and_slide(); the body expects velocity, not per-frame displacement.
  • Moving a physics body by position or global_transform and then expecting slide collisions or floor state to be reliable.
  • Using the camera's pitched forward vector directly, which adds unwanted vertical movement.
  • Parenting the camera directly to animated visual bones or rotating the entire player to aim the camera.
  • Giving detailed render meshes equally detailed collision, or using non-uniformly scaled collision shapes.
  • Reading is_on_floor() as a predictive query; it describes the previous move_and_slide() result.
  • Hard-coding keys, collision layer numbers, node paths, or gravity when project settings already define them.
  • Enabling every environment effect before checking renderer support and GPU cost.
  • Editing a shared Environment, material, mesh, or shape resource when only one scene instance should change.
  • Treating a headless parse as visual verification; cameras, materials, shadows, and fog still require rendered inspection.

References

  • Controllers and cameras
  • Environments and lighting
  • Physics testing and debugging

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.