godot-physics
Godot 4.7 physics API in 2D and 3D: body and Area types, collision_layer and mask bits, Area signals for hurtboxes, RayCast and space queries, and Jolt (3D default since 4.6)
Install / Use
npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill godot-physicsInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of godot-physics
godot-physics scores 95/100 on our quality scale, 288th of 4,700 Development & Engineering skills we index (top 7%).
Its SKILL.md is 8.1 KB long, well organised into 15 sections with 4 code examples: a thorough specification that gives an agent plenty to work with.
With 8,904 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated 4 days ago, so godot-physics is actively maintained.
- Our last check on 2026-11-15 found the source still online.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
godot-physics compared with similar skills
All 4 of these similar skills score higher than godot-physics; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| godot-physics (this skill)by gamedev-skills | 95 | 8.9k | 4d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
Frequently asked questions
- How do I install godot-physics?
- Run
npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill godot-physics. The install tabs above show the steps for each supported agent. - Which AI agents does godot-physics work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is godot-physics safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is godot-physics still maintained?
- The repository was last updated 4 days ago, so godot-physics is actively maintained.
Skill content
View source on GitHubname: godot-physics description: > Use Godot 4.7 physics bodies and detection in 2D and 3D: RigidBody, StaticBody, Area, and CharacterBody; collision layers vs masks; contact/overlap signals; and raycasts (RayCast nodes and direct space-state queries). Use when configuring collision layers/masks, detecting overlaps with Area2D/Area3D, applying forces to a RigidBody, or casting rays in a Godot project (.tscn with physics bodies), including 3D projects running Jolt Physics, the default 3D engine for projects created in 4.6+.
Godot Physics (4.x, 2D + 3D)
Pick the right physics body, wire up collision layers/masks, detect overlaps, and cast
rays. Concepts apply to both 2D and 3D (swap the 2D/3D suffix). Targets
Godot 4.7. In 3D, projects created with Godot 4.6 or later run Jolt Physics by
default; older projects keep GodotPhysics3D unless someone switched them. 2D always
uses Godot's own 2D engine.
When to use
- Use when choosing between body types, setting collision layers/masks so the right
things collide, detecting overlaps (triggers, hurtboxes) with
Area, applying forces/impulses to aRigidBody, or casting rays for line-of-sight/ground checks.
When not to use: kinematic character controllers (move_and_slide) →
godot-2d-movement; tile collision setup → godot-tilemap; tuning the feel of physics
(timestep, mass, jitter) → physics-tuning.
Core workflow
- For 3D, check which engine runs before debugging behavior: Project Settings >
Physics > 3D > Physics Engine (
[physics]3d/physics_engine="Jolt Physics"inproject.godot). The API is the same, but joints, ray-cast face indices, kinematic contacts, and collision margins behave differently (see Pitfalls). - Choose the body type:
StaticBody— never moves (floors, walls). Collides, no simulation.RigidBody— fully simulated (gravity, forces, bouncing). Don't set itspositiondirectly; apply forces/impulses or setlinear_velocity.CharacterBody— script-driven kinematic (seegodot-2d-movement).Area— detects overlaps and can apply gravity/damping; no solid collision. Every body needs aCollisionShape(orCollisionPolygon) child.
- Configure layers and masks. A body is on its layers and scans for its masks. Two bodies interact only if one's layer is in the other's mask. Name layers in Project Settings > Layer Names for clarity.
- Detect overlaps with
Areasignals (body_entered,area_entered). - Drive RigidBodies with forces/impulses, or override
_integrate_forcesfor full control. - Cast rays with a
RayCast2D/3Dnode (polled each frame) or a one-shot space-state query from code.
Patterns
1. Collision layers vs masks (set from code)
# Player is on layer 1, scans layers 2 (walls) and 3 (enemies).
func _ready() -> void:
set_collision_layer_value(1, true) # I am on layer 1
set_collision_mask_value(2, true) # I collide with things on layer 2
set_collision_mask_value(3, true) # ...and layer 3
# Bit-field forms also exist: collision_layer = 1; collision_mask = 0b110
2. Area2D as a trigger / hurtbox
extends Area2D # e.g. a damage zone
func _ready() -> void:
body_entered.connect(_on_body_entered)
area_entered.connect(_on_area_entered)
func _on_body_entered(body: Node2D) -> void:
if body.has_method("take_damage"):
body.take_damage(10)
func _on_area_entered(area: Area2D) -> void:
print("Overlapped area: ", area.name)
3. Applying force and impulse to a RigidBody3D
extends RigidBody3D
func push(direction: Vector3) -> void:
apply_central_impulse(direction * 8.0) # instantaneous velocity change
func _physics_process(_delta: float) -> void:
apply_central_force(Vector3.FORWARD * 4.0) # continuous force (per tick)
# Never set `position` on a RigidBody to move it; use forces/impulses or
# set linear_velocity. Use freeze=true if you must hold it in place.
4. Raycast two ways
# A) RayCast2D node: enable it, then poll after physics has updated.
@onready var ray: RayCast2D = $RayCast2D # set target_position in the editor
func _physics_process(_delta: float) -> void:
if ray.is_colliding():
var hit := ray.get_collider()
var point := ray.get_collision_point()
# B) One-shot query from code (no node needed).
func ground_under(global_from: Vector2) -> Dictionary:
var space := get_world_2d().direct_space_state
var query := PhysicsRayQueryParameters2D.create(global_from, global_from + Vector2(0, 64))
query.collision_mask = 1 # only layer 1
return space.intersect_ray(query) # {} if nothing hit, else collider/position/normal
Pitfalls
- Layer vs mask confusion is the #1 bug. Layer = "what I am"; mask = "what I look for". For A to detect B, B's layer must be in A's mask. Detection can be one-directional.
- Moving a RigidBody by
positionfights the solver and causes tunneling/jitter. Use impulses/forces, setlinear_velocity, orfreezeit. To teleport, set position and zero the velocities inside_integrate_forces. Areadoesn't fire when neither monitoring nor monitorable is set, or layers/masks don't overlap.monitoringmust be on for the Area to detect;monitorablelets others detect it.- RayCast2D/3D read stale or no data if
enabledis false, or if you read it before physics updated — read in_physics_process, and callforce_raycast_update()after moving it within the same tick. - Forgetting a
CollisionShape(or leaving it empty) means the body never collides. - Fast objects tunnel through thin walls; enable continuous CD on the RigidBody
(
continuous_cd) or use a raycast-based check. intersect_rayexcludes its own body? Passquery.exclude = [self.get_rid()](anArray[RID], not an array of nodes) to skip self-hits.
Jolt Physics (3D) differences
face_indexis always-1inintersect_ray()/RayCast3Dresults under Jolt. Turn on Project Settings > Physics > Jolt Physics 3D > Queries > Enable Ray Cast Face Index if you need it (it costs roughly 25% more memory forConcavePolygonShape3D).- A joint with only one body gets inverted limits after switching engines. Jolt treats
the lone body as
node_bwithnode_aas the world; GodotPhysics3D always treats it asnode_a. Assign the body to the slot Jolt expects, or use Physics > Jolt Physics 3D > Joints > World Node for compatibility with an older project. - Joint soft-limit properties do nothing under Jolt (e.g.
bias/softness/relaxationon Pin, Hinge and ConeTwist joints; limit softness/restitution/damping on Slider and Generic6DOF joints). Godot warns when they are set to non-default values. - A frozen kinematic
RigidBody3Dreports no contacts with static or kinematic bodies, even withmax_contacts_reported > 0. Enable Physics > Jolt Physics 3D > Simulation > Generate All Kinematic Contacts if gameplay depends on those contacts. - Shape
marginshrinks the shape instead of padding it under Jolt, so sizes stay true but shape queries can return odd normals on small shapes; the effective margin comes from Physics > Jolt Physics 3D > Collisions > Collision Margin Fraction. Area3Dnow firesbody_enteredforSoftBody3Dunder Jolt (GodotPhysics3D never did). Filter soft bodies out with layers/masks if the old behavior is expected.
References
- For
_integrate_forces, joints, one-way collision,PhysicsServerdirect access, shape queries (intersect_shape), and 3Dmove_and_collide, readreferences/bodies-and-queries.md. - Jolt specifics: Godot docs "Using Jolt Physics"
(
https://docs.godotengine.org/en/stable/tutorials/physics/using_jolt_physics.html).
Related skills
godot-2d-movement— kinematicCharacterBody2Dcontrollers.godot-tilemap— tile collision shapes and their layers.physics-tuning— engine-agnostic feel: timestep, mass, drag, CCD.godot-3d-essentials— 3D scene setup these bodies live in.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
