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.
In this repository14 other files it gives its agents.
- game-balanceSkill
- game-design-vocabularySkill
- gamedev-mathSkill
- game-mechanics-designSkill
- game-systems-designSkill
- godot-2d-gameplaySkill
- godot-desktop-appsSkill
- godot-fundamentalsSkill
- godot-game-architectureSkill
- godot-mobileSkill
- godot-navigation-aiSkill
- godot-procedural-generationSkill
- godot-programming-patternsSkill
- godot-uiSkill
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
- Distinctive: line 16
Do not write scenes, scripts, or project settings until this inspection is complete.
- Very specific: line 19
Run the project's established Godot executable with --version when available.
- Distinctive: line 25
If the editor version, project feature tag, and requested API disagree, stop and resolve the version mismatch before authoring resources.
- Very specific: line 29
Use CharacterBody3D for script-directed avatars that need floor, wall, slope, and moving-platform behavior.
- Very specific: line 30
Use AnimatableBody3D for script- or animation-driven platforms that should carry characters.
- Very specific: line 31
Use RigidBody3D for bodies whose motion should come from forces and impulses.
- Distinctive: line 32
Keep collision, gameplay state, visuals, and camera pivots in separate child branches when they change for different reasons.
- Distinctive: line 33
Use Input Map actions, not physical key constants, so keyboard and gamepad bindings can share gameplay code.
- Very specific: line 34
Use a SpringArm3D camera rig when level geometry can move between the subject and camera.
- Very specific: line 35
Start with one WorldEnvironment and one primary light.
- Distinctive: line 45
Test controller, camera, and lighting together in representative geometry before polishing animation or effects.
- Distinctive: line 106
Run the project's own checks first, then perform all applicable steps:
- Very specific: line 108
Import and parse with the matching editor.
- Distinctive: line 109
Run the player scene and at least one integrated level.
- Distinctive: line 110
Test start, stop, reverse, diagonal input, no-input deceleration, jump press versus hold, ceiling contact, ledges, stairs, shallow and …
- Distinctive: line 112
Test at low and high rendered frame rates while keeping physics behavior stable.
- Distinctive: line 113
Use visible collision shapes and the remote scene tree to verify collider alignment, layers, masks, active environment, and runtime …
≈ “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.
Files
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.
- Find
project.godotand confirm the project root. Readconfig/features, the rendering method, physics tick rate, display settings, 3D physics layer names, and existing Input Map actions. - Run the project's established Godot executable with
--versionwhen available. Match APIs to that exact Godot 4.x release; do not silently upgrade the project or its resource formats. - 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. - 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.
- Identify the target renderer and hardware. A Forward+ desktop scene, a Mobile-renderer game, and a Compatibility project require different lighting and environment choices.
- 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
CharacterBody3Dfor script-directed avatars that need floor, wall, slope, and moving-platform behavior. - Use
AnimatableBody3Dfor script- or animation-driven platforms that should carry characters. - Use
RigidBody3Dfor 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
SpringArm3Dcamera rig when level geometry can move between the subject and camera. - Start with one
WorldEnvironmentand one primary light. Add post-processing and extra shadowed lights only after the base image reads clearly.
Implementation Workflow
- Define observable behavior: movement reference frame, top speed, acceleration, air control, slope limit, jump rules, camera range, camera collision, and visual target.
- 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.
- Confirm action names and deadzones in the Input Map. Reuse project actions where their semantics match.
- Implement physics in
_physics_process(delta). TreatCharacterBody3D.velocityas units per second and callmove_and_slide()once per physics tick. - 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. - Establish the environment and lighting for readability first. Tune sky or background, ambient contribution, key-light direction, exposure, fog, and shadows as one composition.
- 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 --quitand 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.velocitybydeltabeforemove_and_slide(); the body expects velocity, not per-frame displacement. - Moving a physics body by
positionorglobal_transformand 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 previousmove_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
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
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.

