[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6KRCTQTGP8PV48EER1PH4BD":3,"skill-same:01M6KRCTQTGP8PV48EER1PH4BD":106},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":28,"linkOnly":29,"markdownContent":30,"markdownBody":31,"frontMatter":32,"refName":33,"commitSha":34,"skillDirectory":35,"forksCount":36,"repositoryHtmlUrl":37,"repositoryHomepageUrl":6,"ownerHtmlUrl":38,"ownerBlogUrl":39,"ownerDescription":40,"updatedAt":41,"install":42,"resources":55},"01M6KRCTQTGP8PV48EER1PH4BD","physics-system",null,"Use when working with physics bodies, collision shapes, raycasting, areas, rigid bodies, ragdolls, soft bodies, Jolt physics, and physics interpolation in Godot 4.3+","jame581\u002FGodotPrompter","jame581","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F21112138?v=4","01M6KR3KEQ9Z30WVJRR2E2ZVXE","Jan Mesarč","01M6KR3KJVRMPDSMASQPBCBVK3",964,"MIT","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fphysics-system\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27],"physics","system","physics system","use","with","godot 4","godot","when","interpolation","2026-11-10 10:12:30",false,"---\nname: physics-system\ndescription: Use when working with physics bodies, collision shapes, raycasting, areas, rigid bodies, ragdolls, soft bodies, Jolt physics, and physics interpolation in Godot 4.3+\n---\n\n# Physics System in Godot 4.3+\n\nAll examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.\n\n> **Related skills:** **player-controller** for CharacterBody2D\u002F3D movement patterns, **component-system** for hitbox\u002Fhurtbox composition, **godot-optimization** for physics performance tuning, **camera-system** for camera follow and interpolation, **multiplayer-sync** for networked physics, **2d-essentials** for tile collision setup and 2D canvas layers.\n\n---\n\n## 1. Physics Body Types\n\nFour collision-object types (the last three extend `PhysicsBody2D`\u002F`3D`):\n\n| Type | Moved by | Use for |\n|------|----------|---------|\n| `Area2D\u002F3D` | Code | Overlap detection, gravity zones, audio zones |\n| `StaticBody2D\u002F3D` | Not moved (or `constant_linear_velocity`) | Walls, floors, conveyor belts |\n| `RigidBody2D\u002F3D` | Physics engine | Crates, projectiles, debris, ragdolls |\n| `CharacterBody2D\u002F3D` | Code | Players, enemies, NPCs (see **player-controller**) |\n\nEvery collision object needs at least one `CollisionShape2D`\u002F`3D` (or `CollisionPolygon2D`\u002F`3D`) child. **Jolt Physics is built in since 4.4 (experimental, opt-in) and is the default 3D engine for projects created in 4.6+** — see Section 8; existing projects keep GodotPhysics until switched. 2D always uses GodotPhysics.\n\n> **Critical rule:** NEVER scale collision shapes or physics bodies via `scale`. Use the shape's own size parameters (radius, extents, height) — scaling breaks collision accuracy.\n\n---\n\n## 2. RigidBody2D\u002F3D\n\n### Forces vs Impulses\n\n| Method | Effect | When to use |\n|---|---|---|\n| `apply_force(force, position)` | Continuous accel at point | Thrusters, wind, magnets |\n| `apply_central_force(force)` | Continuous accel at center | Gravity, constant push |\n| `apply_impulse(impulse, position)` | Instant velocity change at point | Bullet hit, explosion |\n| `apply_central_impulse(impulse)` | Instant velocity change at center | Jump, knockback |\n| `apply_torque(torque)` | Continuous angular accel | Steering, spinning |\n| `apply_torque_impulse(impulse)` | Instant angular velocity change | Impact spin |\n\n> See [references\u002Frigidbody-recipes.md](references\u002Frigidbody-recipes.md) for a thrust-and-spin example (GDScript + C#) using `apply_force` + `apply_central_impulse` + `apply_torque`.\n\n### _integrate_forces() — Safe Physics Modification\n\nUse `_integrate_forces(state)` instead of `_physics_process()` to read\u002Fmodify a RigidBody's transform, velocity, or angular velocity. Setting `position` or `linear_velocity` directly in `_physics_process()` fights the physics engine.\n\n> **Warning:** `_integrate_forces()` is NOT called while the body is sleeping. Set `can_sleep = false` if you need continuous callbacks; otherwise let bodies sleep for performance.\n\n> See [references\u002Frigidbody-recipes.md](references\u002Frigidbody-recipes.md) for the thrust + torque example using `state.apply_force` \u002F `state.apply_torque` (GDScript + C#).\n\n### Contact Monitoring, PhysicsMaterial, Freeze, look_at\n\n- **Contact signals** require `contact_monitor = true` + `max_contacts_reported > 0`. Then `body_entered`\u002F`body_exited` fire.\n- **`PhysicsMaterial`** resource controls `friction` (0 ice → 1 rubber) and `bounce` (0 → 1).\n- **Freeze modes:** `FREEZE_MODE_STATIC` (acts like a StaticBody) or `FREEZE_MODE_KINEMATIC` (code-moved, pushes others).\n- **RigidBody3D orientation:** never `look_at()` a RigidBody — use `_integrate_forces` and set `state.angular_velocity` from a cross-product steering term.\n\n> See [references\u002Frigidbody-recipes.md](references\u002Frigidbody-recipes.md) for full GDScript + C# recipes (contact handler with `take_damage`, PhysicsMaterial property table, freeze toggle, RigidBody3D homing-via-angular-velocity).\n\n---\n\n## 3. StaticBody2D\u002F3D\n\n`StaticBody` is not moved by the physics engine but can push other bodies via `constant_linear_velocity` (e.g. conveyor belts). For platforms that move via code AND push CharacterBodies, use **`AnimatableBody2D`\u002F`3D`** — a code-moved `StaticBody` won't push CharacterBodies reliably.\n\n> See [references\u002Fstaticbody-recipes.md](references\u002Fstaticbody-recipes.md) for the conveyor belt and moving-platform recipes (GDScript + C#, with Tween-driven AnimatableBody2D loop).\n\n---\n\n## 4. Area2D\u002F3D\n\nAreas detect overlaps and override physics properties within their bounds. They do NOT produce collision responses — bodies pass through them. An area reports a body only when `monitoring` is on and its `collision_mask` includes the body's `collision_layer` — a mismatch is the usual reason `body_entered` never fires, so name both settings even when the defaults (layer 1, mask 1) happen to match. Connect `body_entered` \u002F `body_exited` for body overlaps; use `area_entered` \u002F `area_exited` for Area-to-Area (hitbox vs hurtbox — see **component-system**). Areas can also override gravity (zero-G zones, point gravity \u002F black holes), `linear_damp` \u002F `angular_damp` (water, slow-mo), and redirect audio to a specific `AudioBus`. When multiple areas overlap, `priority` decides order; pick a `space_override` mode (`COMBINE`, `REPLACE`, `COMBINE_REPLACE`, `REPLACE_COMBINE`).\n\n> See [references\u002Farea-recipes.md](references\u002Farea-recipes.md) for the GDScript + C# overlap-detection canonical example, the space-override mode reference table, and zero-G + point-gravity recipes.\n\n> ⚠️ **Changed in Godot 4.7:** With Jolt Physics, `Area3D` now reports overlaps with `SoftBody3D` from its signals and methods. Configure collision layers\u002Fmasks so any unwanted `Area3D` ↔ `SoftBody3D` interactions are ignored. See the [4.7 migration guide](https:\u002F\u002Fdocs.godotengine.org\u002Fen\u002Flatest\u002Ftutorials\u002Fmigrating\u002Fupgrading_to_godot_4.7.html).\n\n---\n\n## 5. Collision Shapes\n\n| Shape (2D \u002F 3D) | Use case |\n|---|---|\n| `Rectangle` \u002F `Box` | Crates, platforms, rooms |\n| `Circle` \u002F `Sphere` | Balls, projectiles, simple characters, trigger zones |\n| `Capsule` (2D & 3D) | Characters — rounded, slides over edges |\n| `Segment2D` \u002F — | Thin walls, laser beams |\n| `SeparationRay2D` \u002F `3D` | Character ground snapping |\n| `WorldBoundary2D` \u002F `3D` | Infinite floor\u002Fwall\u002Fceiling |\n| — \u002F `Cylinder3D` | Pillars, barrels (known bugs on GodotPhysics — prefer Jolt) |\n\nPrefer primitives for dynamic bodies. `ConvexPolygonShape` is fast but cannot express holes or inward curves; `ConcavePolygonShape` is accurate for level geometry but is **StaticBody-only** and the slowest. Never translate, rotate, or scale a CollisionShape node — an untransformed shape unlocks a broad-phase optimization. Godot 4.7+ adds `one_way_collision_direction` for sideways one-way platforms.\n\nConvex\u002Fconcave cost table, shape-generation menus, the full performance rules, and the 4.7+ one-way direction API (GDScript + C#): [references\u002Fcollision-shapes.md](references\u002Fcollision-shapes.md)\n\n---\n\n## 6. Collision Layers and Masks\n\nGodot provides 32 physics layers per dimension (2D and 3D separately).\n\n- **collision_layer** — which layers this object **exists on** (others scan for it here)\n- **collision_mask** — which layers this object **scans** (what it detects)\n\n> **Mental model:** Layer = \"I am\", Mask = \"I scan for\". A collision happens when object A's mask includes object B's layer, OR vice versa.\n\nName layers in **Project Settings → Layer Names → 2D Physics** (or 3D Physics); set them in code with `set_collision_layer_value(N, true)` \u002F `set_collision_mask_value(N, true)` (1-indexed).\n\n> See [references\u002Fcollision-layers.md](references\u002Fcollision-layers.md) for layer naming conventions, bitmask shorthand, Inspector export flags, and the GDScript + C# examples.\n\n---\n\n## 7. Raycasting and Physics Queries\n\nTwo ways to cast: a `RayCast2D`\u002F`RayCast3D` child node (casts every physics frame; read `is_colliding()`, `get_collider()`, `get_collision_point()`, `get_collision_normal()`), or an on-demand `intersect_ray(PhysicsRayQueryParameters2D\u002F3D.create(from, to))` on `direct_space_state` (`query.exclude = [get_rid()]` to skip self). **Query inside `_physics_process()`** — the space is locked during the physics step. `PhysicsDirectSpaceState` also offers `intersect_point`, `intersect_shape`, `cast_motion`, `collide_shape`, `get_rest_info`. **Godot 4.8+:** each has an allocation-free `*_into` variant filling a reusable result object ([recipe](references\u002Fraycasting-recipes.md#allocation-free-queries-godot-48)); `RigidBody2D\u002F3D.get_velocity_at_position()` gives a point's velocity.\n\n> See [references\u002Fraycasting-recipes.md](references\u002Fraycasting-recipes.md) for the RayCast node and code-based raycast examples (GDScript + C#), the `intersect_ray` result keys, `query.exclude` \u002F `collision_mask` filtering, and 3D mouse picking.\n\n---\n\n## 8. Jolt Physics\n\nJolt is a built-in alternative physics engine, available since Godot 4.4 as an experimental opt-in. **(Godot 4.6+)** Jolt is no longer marked experimental and is the default for newly created 3D projects; projects upgraded from earlier versions keep `DEFAULT` (GodotPhysics3D) until changed.\n\n### Enabling Jolt\n\n**Project Settings → Physics → 3D → Physics Engine** → `Jolt Physics` → Save → Restart editor. (3D only; 2D always uses GodotPhysics.)\n\n### Why & Differences\n\n**Wins:** better stacking stability, `CylinderShape3D` without GodotPhysics' known cylinder bugs, better `SoftBody3D`, active-edge detection (reduces ghost collisions).\n\n> See [references\u002Fjolt-differences.md](references\u002Fjolt-differences.md) for the behavioral differences from GodotPhysics (stabilization, collision margins, single-body joints, `face_index`, unsupported joint properties).\n\n> ⚠️ **Changed in Godot 4.7:** With Jolt Physics, `WorldBoundaryShape3D.plane.d` now follows the same sign convention as Godot Physics — the plane distance is interpreted with the opposite sign compared to Godot 4.6. Flip the sign yourself to keep the 4.6 behavior. See the [4.7 migration guide](https:\u002F\u002Fdocs.godotengine.org\u002Fen\u002Flatest\u002Ftutorials\u002Fmigrating\u002Fupgrading_to_godot_4.7.html).\n\n---\n\n## 9. Physics Interpolation\n\nSmooths visual motion between physics ticks, eliminating \"staircase\" jitter when tick rate ≠ frame rate. Enable in **Project Settings → Physics → Common → Physics Interpolation** (4.3 interpolates 2D only; 3D from 4.4). **Godot 4.5+** restructured the 3D interpolation pipeline (`RenderingServer` → `SceneTree`) for more accurate results in nested transforms — no API change, automatic improvement on upgrade.\n\n### Core Rules\n\n1. **Move all game logic to `_physics_process()`** — transforms set outside physics ticks cause jitter\n2. **Tweens and AnimationPlayer** that move physics objects must use physics tick timing\n3. **Call `reset_physics_interpolation()`** after teleporting or initial placement to prevent \"streaking\"\n\n> See [references\u002Finterpolation-tuning.md](references\u002Finterpolation-tuning.md) for the teleport-reset example (GDScript + C#), per-node `physics_interpolation_mode` control, and tick-rate guidance.\n\n### Camera Interpolation\n\nCameras need special handling under physics interpolation. Make the camera independent (or `top_level = true`), update it in `_process()` (not `_physics_process()`), and read the target's smooth position with `Node3D.get_global_transform_interpolated()` (4.4+).\n\n> See [references\u002Finterpolation-camera.md](references\u002Finterpolation-camera.md) for the full smooth-follow Camera3D recipe (GDScript + C#).\n\n---\n\n## 10. Ragdoll System\n\nRagdolls replace animation with physics for procedural death, explosions, or limp characters. Generate via `Skeleton3D` → **Skeleton** menu → **Create Physical Skeleton**. Use `ConeJoint` for shoulders\u002Fhips\u002Fneck, `HingeJoint` for elbows\u002Fknees — `PinJoint` (default) tends to crumple. Drive via `physical_bones_start_simulation()`, blend with `Influence`.\n\n> See [references\u002Fragdoll-recipes.md](references\u002Fragdoll-recipes.md) for setup, joint guidance, full GDScript + C# control, animation blending, and collision exceptions.\n\n---\n\n## 11. SoftBody3D\n\n`SoftBody3D` simulates deformable objects (cloth, capes, jelly). Mesh subdivision drives the simulation; no `CollisionShape` child needed. **Jolt Physics recommended.** Set `Simulation Precision ≥ 5` to prevent collapse. `Pressure > 0.0` only on closed meshes.\n\nGodot 4.5+ adds `apply_central_impulse()` \u002F `apply_central_force()` for `RigidBody3D`-style force application — distributes across all simulation points.\n\n> See [references\u002Fsoftbody-recipes.md](references\u002Fsoftbody-recipes.md) for the cloth\u002Fcape walk-through (PlaneMesh, BoneAttachment3D pinning, Parent Collision Ignore) and the 4.5+ force\u002Fimpulse API with GDScript and C# (explosion knockback, continuous wind).\n\n> ⚠️ **Changed in Godot 4.7:** With Jolt Physics, `SoftBody3D` mass no longer defaults to `0` (which auto-calculated 1 kg *per point*, giving a very high total mass) — it now defaults to 1 kg for the entire body, matching Godot Physics. `linear_stiffness` is also applied differently, so re-tweak `linear_stiffness` and `damping_coefficient` after upgrading. See the [4.7 migration guide](https:\u002F\u002Fdocs.godotengine.org\u002Fen\u002Flatest\u002Ftutorials\u002Fmigrating\u002Fupgrading_to_godot_4.7.html).\n\n---\n\n## 12. Troubleshooting Physics Issues\n\nSymptom → causes & fixes quick table covering tunneling, wobbly stacks, scaled shapes, tile collision bumps, unstable cylinders, the physics spiral of death, and float-precision issues far from origin.\n\n> See [references\u002Ftroubleshooting.md](references\u002Ftroubleshooting.md) for the full table.\n\n---\n\n## 13. Implementation Checklist\n\n- [ ] Dynamic bodies use primitive collision shapes; concave shapes only on StaticBodies\n- [ ] Collision layers named in Project Settings; layer\u002Fmask set correctly per body\n- [ ] No `scale` on collision shapes or bodies — use shape size parameters directly\n- [ ] RigidBodies modify state via `_integrate_forces()`, not `_physics_process()`\n- [ ] RigidBodies needing contact signals set `contact_monitor = true` + `max_contacts_reported > 0`\n- [ ] Moving platforms use `AnimatableBody2D\u002F3D` (not manually moved StaticBody)\n- [ ] Code raycasts use `PhysicsDirectSpaceState` inside `_physics_process()` only\n- [ ] Physics interpolation enabled; `reset_physics_interpolation()` called after teleport \u002F initial placement\n- [ ] Ragdoll bones on a separate collision layer from the character capsule\n- [ ] 3D projects use Jolt (non-experimental default in Godot 4.6+)\n","# Physics System in Godot 4.3+\n\nAll examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.\n\n> **Related skills:** **player-controller** for CharacterBody2D\u002F3D movement patterns, **component-system** for hitbox\u002Fhurtbox composition, **godot-optimization** for physics performance tuning, **camera-system** for camera follow and interpolation, **multiplayer-sync** for networked physics, **2d-essentials** for tile collision setup and 2D canvas layers.\n\n---\n\n## 1. Physics Body Types\n\nFour collision-object types (the last three extend `PhysicsBody2D`\u002F`3D`):\n\n| Type | Moved by | Use for |\n|------|----------|---------|\n| `Area2D\u002F3D` | Code | Overlap detection, gravity zones, audio zones |\n| `StaticBody2D\u002F3D` | Not moved (or `constant_linear_velocity`) | Walls, floors, conveyor belts |\n| `RigidBody2D\u002F3D` | Physics engine | Crates, projectiles, debris, ragdolls |\n| `CharacterBody2D\u002F3D` | Code | Players, enemies, NPCs (see **player-controller**) |\n\nEvery collision object needs at least one `CollisionShape2D`\u002F`3D` (or `CollisionPolygon2D`\u002F`3D`) child. **Jolt Physics is built in since 4.4 (experimental, opt-in) and is the default 3D engine for projects created in 4.6+** — see Section 8; existing projects keep GodotPhysics until switched. 2D always uses GodotPhysics.\n\n> **Critical rule:** NEVER scale collision shapes or physics bodies via `scale`. Use the shape's own size parameters (radius, extents, height) — scaling breaks collision accuracy.\n\n---\n\n## 2. RigidBody2D\u002F3D\n\n### Forces vs Impulses\n\n| Method | Effect | When to use |\n|---|---|---|\n| `apply_force(force, position)` | Continuous accel at point | Thrusters, wind, magnets |\n| `apply_central_force(force)` | Continuous accel at center | Gravity, constant push |\n| `apply_impulse(impulse, position)` | Instant velocity change at point | Bullet hit, explosion |\n| `apply_central_impulse(impulse)` | Instant velocity change at center | Jump, knockback |\n| `apply_torque(torque)` | Continuous angular accel | Steering, spinning |\n| `apply_torque_impulse(impulse)` | Instant angular velocity change | Impact spin |\n\n> See [references\u002Frigidbody-recipes.md](references\u002Frigidbody-recipes.md) for a thrust-and-spin example (GDScript + C#) using `apply_force` + `apply_central_impulse` + `apply_torque`.\n\n### _integrate_forces() — Safe Physics Modification\n\nUse `_integrate_forces(state)` instead of `_physics_process()` to read\u002Fmodify a RigidBody's transform, velocity, or angular velocity. Setting `position` or `linear_velocity` directly in `_physics_process()` fights the physics engine.\n\n> **Warning:** `_integrate_forces()` is NOT called while the body is sleeping. Set `can_sleep = false` if you need continuous callbacks; otherwise let bodies sleep for performance.\n\n> See [references\u002Frigidbody-recipes.md](references\u002Frigidbody-recipes.md) for the thrust + torque example using `state.apply_force` \u002F `state.apply_torque` (GDScript + C#).\n\n### Contact Monitoring, PhysicsMaterial, Freeze, look_at\n\n- **Contact signals** require `contact_monitor = true` + `max_contacts_reported > 0`. Then `body_entered`\u002F`body_exited` fire.\n- **`PhysicsMaterial`** resource controls `friction` (0 ice → 1 rubber) and `bounce` (0 → 1).\n- **Freeze modes:** `FREEZE_MODE_STATIC` (acts like a StaticBody) or `FREEZE_MODE_KINEMATIC` (code-moved, pushes others).\n- **RigidBody3D orientation:** never `look_at()` a RigidBody — use `_integrate_forces` and set `state.angular_velocity` from a cross-product steering term.\n\n> See [references\u002Frigidbody-recipes.md](references\u002Frigidbody-recipes.md) for full GDScript + C# recipes (contact handler with `take_damage`, PhysicsMaterial property table, freeze toggle, RigidBody3D homing-via-angular-velocity).\n\n---\n\n## 3. StaticBody2D\u002F3D\n\n`StaticBody` is not moved by the physics engine but can push other bodies via `constant_linear_velocity` (e.g. conveyor belts). For platforms that move via code AND push CharacterBodies, use **`AnimatableBody2D`\u002F`3D`** — a code-moved `StaticBody` won't push CharacterBodies reliably.\n\n> See [references\u002Fstaticbody-recipes.md](references\u002Fstaticbody-recipes.md) for the conveyor belt and moving-platform recipes (GDScript + C#, with Tween-driven AnimatableBody2D loop).\n\n---\n\n## 4. Area2D\u002F3D\n\nAreas detect overlaps and override physics properties within their bounds. They do NOT produce collision responses — bodies pass through them. An area reports a body only when `monitoring` is on and its `collision_mask` includes the body's `collision_layer` — a mismatch is the usual reason `body_entered` never fires, so name both settings even when the defaults (layer 1, mask 1) happen to match. Connect `body_entered` \u002F `body_exited` for body overlaps; use `area_entered` \u002F `area_exited` for Area-to-Area (hitbox vs hurtbox — see **component-system**). Areas can also override gravity (zero-G zones, point gravity \u002F black holes), `linear_damp` \u002F `angular_damp` (water, slow-mo), and redirect audio to a specific `AudioBus`. When multiple areas overlap, `priority` decides order; pick a `space_override` mode (`COMBINE`, `REPLACE`, `COMBINE_REPLACE`, `REPLACE_COMBINE`).\n\n> See [references\u002Farea-recipes.md](references\u002Farea-recipes.md) for the GDScript + C# overlap-detection canonical example, the space-override mode reference table, and zero-G + point-gravity recipes.\n\n> ⚠️ **Changed in Godot 4.7:** With Jolt Physics, `Area3D` now reports overlaps with `SoftBody3D` from its signals and methods. Configure collision layers\u002Fmasks so any unwanted `Area3D` ↔ `SoftBody3D` interactions are ignored. See the [4.7 migration guide](https:\u002F\u002Fdocs.godotengine.org\u002Fen\u002Flatest\u002Ftutorials\u002Fmigrating\u002Fupgrading_to_godot_4.7.html).\n\n---\n\n## 5. Collision Shapes\n\n| Shape (2D \u002F 3D) | Use case |\n|---|---|\n| `Rectangle` \u002F `Box` | Crates, platforms, rooms |\n| `Circle` \u002F `Sphere` | Balls, projectiles, simple characters, trigger zones |\n| `Capsule` (2D & 3D) | Characters — rounded, slides over edges |\n| `Segment2D` \u002F — | Thin walls, laser beams |\n| `SeparationRay2D` \u002F `3D` | Character ground snapping |\n| `WorldBoundary2D` \u002F `3D` | Infinite floor\u002Fwall\u002Fceiling |\n| — \u002F `Cylinder3D` | Pillars, barrels (known bugs on GodotPhysics — prefer Jolt) |\n\nPrefer primitives for dynamic bodies. `ConvexPolygonShape` is fast but cannot express holes or inward curves; `ConcavePolygonShape` is accurate for level geometry but is **StaticBody-only** and the slowest. Never translate, rotate, or scale a CollisionShape node — an untransformed shape unlocks a broad-phase optimization. Godot 4.7+ adds `one_way_collision_direction` for sideways one-way platforms.\n\nConvex\u002Fconcave cost table, shape-generation menus, the full performance rules, and the 4.7+ one-way direction API (GDScript + C#): [references\u002Fcollision-shapes.md](references\u002Fcollision-shapes.md)\n\n---\n\n## 6. Collision Layers and Masks\n\nGodot provides 32 physics layers per dimension (2D and 3D separately).\n\n- **collision_layer** — which layers this object **exists on** (others scan for it here)\n- **collision_mask** — which layers this object **scans** (what it detects)\n\n> **Mental model:** Layer = \"I am\", Mask = \"I scan for\". A collision happens when object A's mask includes object B's layer, OR vice versa.\n\nName layers in **Project Settings → Layer Names → 2D Physics** (or 3D Physics); set them in code with `set_collision_layer_value(N, true)` \u002F `set_collision_mask_value(N, true)` (1-indexed).\n\n> See [references\u002Fcollision-layers.md](references\u002Fcollision-layers.md) for layer naming conventions, bitmask shorthand, Inspector export flags, and the GDScript + C# examples.\n\n---\n\n## 7. Raycasting and Physics Queries\n\nTwo ways to cast: a `RayCast2D`\u002F`RayCast3D` child node (casts every physics frame; read `is_colliding()`, `get_collider()`, `get_collision_point()`, `get_collision_normal()`), or an on-demand `intersect_ray(PhysicsRayQueryParameters2D\u002F3D.create(from, to))` on `direct_space_state` (`query.exclude = [get_rid()]` to skip self). **Query inside `_physics_process()`** — the space is locked during the physics step. `PhysicsDirectSpaceState` also offers `intersect_point`, `intersect_shape`, `cast_motion`, `collide_shape`, `get_rest_info`. **Godot 4.8+:** each has an allocation-free `*_into` variant filling a reusable result object ([recipe](references\u002Fraycasting-recipes.md#allocation-free-queries-godot-48)); `RigidBody2D\u002F3D.get_velocity_at_position()` gives a point's velocity.\n\n> See [references\u002Fraycasting-recipes.md](references\u002Fraycasting-recipes.md) for the RayCast node and code-based raycast examples (GDScript + C#), the `intersect_ray` result keys, `query.exclude` \u002F `collision_mask` filtering, and 3D mouse picking.\n\n---\n\n## 8. Jolt Physics\n\nJolt is a built-in alternative physics engine, available since Godot 4.4 as an experimental opt-in. **(Godot 4.6+)** Jolt is no longer marked experimental and is the default for newly created 3D projects; projects upgraded from earlier versions keep `DEFAULT` (GodotPhysics3D) until changed.\n\n### Enabling Jolt\n\n**Project Settings → Physics → 3D → Physics Engine** → `Jolt Physics` → Save → Restart editor. (3D only; 2D always uses GodotPhysics.)\n\n### Why & Differences\n\n**Wins:** better stacking stability, `CylinderShape3D` without GodotPhysics' known cylinder bugs, better `SoftBody3D`, active-edge detection (reduces ghost collisions).\n\n> See [references\u002Fjolt-differences.md](references\u002Fjolt-differences.md) for the behavioral differences from GodotPhysics (stabilization, collision margins, single-body joints, `face_index`, unsupported joint properties).\n\n> ⚠️ **Changed in Godot 4.7:** With Jolt Physics, `WorldBoundaryShape3D.plane.d` now follows the same sign convention as Godot Physics — the plane distance is interpreted with the opposite sign compared to Godot 4.6. Flip the sign yourself to keep the 4.6 behavior. See the [4.7 migration guide](https:\u002F\u002Fdocs.godotengine.org\u002Fen\u002Flatest\u002Ftutorials\u002Fmigrating\u002Fupgrading_to_godot_4.7.html).\n\n---\n\n## 9. Physics Interpolation\n\nSmooths visual motion between physics ticks, eliminating \"staircase\" jitter when tick rate ≠ frame rate. Enable in **Project Settings → Physics → Common → Physics Interpolation** (4.3 interpolates 2D only; 3D from 4.4). **Godot 4.5+** restructured the 3D interpolation pipeline (`RenderingServer` → `SceneTree`) for more accurate results in nested transforms — no API change, automatic improvement on upgrade.\n\n### Core Rules\n\n1. **Move all game logic to `_physics_process()`** — transforms set outside physics ticks cause jitter\n2. **Tweens and AnimationPlayer** that move physics objects must use physics tick timing\n3. **Call `reset_physics_interpolation()`** after teleporting or initial placement to prevent \"streaking\"\n\n> See [references\u002Finterpolation-tuning.md](references\u002Finterpolation-tuning.md) for the teleport-reset example (GDScript + C#), per-node `physics_interpolation_mode` control, and tick-rate guidance.\n\n### Camera Interpolation\n\nCameras need special handling under physics interpolation. Make the camera independent (or `top_level = true`), update it in `_process()` (not `_physics_process()`), and read the target's smooth position with `Node3D.get_global_transform_interpolated()` (4.4+).\n\n> See [references\u002Finterpolation-camera.md](references\u002Finterpolation-camera.md) for the full smooth-follow Camera3D recipe (GDScript + C#).\n\n---\n\n## 10. Ragdoll System\n\nRagdolls replace animation with physics for procedural death, explosions, or limp characters. Generate via `Skeleton3D` → **Skeleton** menu → **Create Physical Skeleton**. Use `ConeJoint` for shoulders\u002Fhips\u002Fneck, `HingeJoint` for elbows\u002Fknees — `PinJoint` (default) tends to crumple. Drive via `physical_bones_start_simulation()`, blend with `Influence`.\n\n> See [references\u002Fragdoll-recipes.md](references\u002Fragdoll-recipes.md) for setup, joint guidance, full GDScript + C# control, animation blending, and collision exceptions.\n\n---\n\n## 11. SoftBody3D\n\n`SoftBody3D` simulates deformable objects (cloth, capes, jelly). Mesh subdivision drives the simulation; no `CollisionShape` child needed. **Jolt Physics recommended.** Set `Simulation Precision ≥ 5` to prevent collapse. `Pressure > 0.0` only on closed meshes.\n\nGodot 4.5+ adds `apply_central_impulse()` \u002F `apply_central_force()` for `RigidBody3D`-style force application — distributes across all simulation points.\n\n> See [references\u002Fsoftbody-recipes.md](references\u002Fsoftbody-recipes.md) for the cloth\u002Fcape walk-through (PlaneMesh, BoneAttachment3D pinning, Parent Collision Ignore) and the 4.5+ force\u002Fimpulse API with GDScript and C# (explosion knockback, continuous wind).\n\n> ⚠️ **Changed in Godot 4.7:** With Jolt Physics, `SoftBody3D` mass no longer defaults to `0` (which auto-calculated 1 kg *per point*, giving a very high total mass) — it now defaults to 1 kg for the entire body, matching Godot Physics. `linear_stiffness` is also applied differently, so re-tweak `linear_stiffness` and `damping_coefficient` after upgrading. See the [4.7 migration guide](https:\u002F\u002Fdocs.godotengine.org\u002Fen\u002Flatest\u002Ftutorials\u002Fmigrating\u002Fupgrading_to_godot_4.7.html).\n\n---\n\n## 12. Troubleshooting Physics Issues\n\nSymptom → causes & fixes quick table covering tunneling, wobbly stacks, scaled shapes, tile collision bumps, unstable cylinders, the physics spiral of death, and float-precision issues far from origin.\n\n> See [references\u002Ftroubleshooting.md](references\u002Ftroubleshooting.md) for the full table.\n\n---\n\n## 13. Implementation Checklist\n\n- [ ] Dynamic bodies use primitive collision shapes; concave shapes only on StaticBodies\n- [ ] Collision layers named in Project Settings; layer\u002Fmask set correctly per body\n- [ ] No `scale` on collision shapes or bodies — use shape size parameters directly\n- [ ] RigidBodies modify state via `_integrate_forces()`, not `_physics_process()`\n- [ ] RigidBodies needing contact signals set `contact_monitor = true` + `max_contacts_reported > 0`\n- [ ] Moving platforms use `AnimatableBody2D\u002F3D` (not manually moved StaticBody)\n- [ ] Code raycasts use `PhysicsDirectSpaceState` inside `_physics_process()` only\n- [ ] Physics interpolation enabled; `reset_physics_interpolation()` called after teleport \u002F initial placement\n- [ ] Ragdoll bones on a separate collision layer from the character capsule\n- [ ] 3D projects use Jolt (non-experimental default in Godot 4.6+)\n",{"name":5,"description":7},"master","60c28fdc40706a24576731e9fb3508b9c95258ad","skills\u002Fphysics-system",63,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter","https:\u002F\u002Fgithub.com\u002Fjame581","https:\u002F\u002Fjanmesarc.online\u002F","Software engineer. My biggest passion is game development.","2026-11-14 20:45:49",{"source":8,"skillName":5,"commands":43,"prompt":53,"zipAvailable":54},[44,47,50],{"tool":45,"command":46},"npx","npx skills add jame581\u002FGodotPrompter --skill physics-system",{"tool":48,"command":49},"bunx","bunx skills add jame581\u002FGodotPrompter --skill physics-system",{"tool":51,"command":52},"pnpm","pnpm dlx skills add jame581\u002FGodotPrompter --skill physics-system","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fphysics-system\u002FSKILL.md",true,[56,62,66,70,74,78,82,86,90,94,98,102],{"path":57,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":60,"sourceHtmlUrl":61},"references\u002Farea-recipes.md","REFERENCE","参考文档",2233,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fphysics-system\u002Freferences\u002Farea-recipes.md",{"path":63,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":64,"sourceHtmlUrl":65},"references\u002Fcollision-layers.md",1053,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fphysics-system\u002Freferences\u002Fcollision-layers.md",{"path":67,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002Fcollision-shapes.md",1869,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fphysics-system\u002Freferences\u002Fcollision-shapes.md",{"path":71,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":72,"sourceHtmlUrl":73},"references\u002Finterpolation-camera.md",1856,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fphysics-system\u002Freferences\u002Finterpolation-camera.md",{"path":75,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":76,"sourceHtmlUrl":77},"references\u002Finterpolation-tuning.md",990,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fphysics-system\u002Freferences\u002Finterpolation-tuning.md",{"path":79,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":80,"sourceHtmlUrl":81},"references\u002Fjolt-differences.md",606,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fphysics-system\u002Freferences\u002Fjolt-differences.md",{"path":83,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":84,"sourceHtmlUrl":85},"references\u002Fragdoll-recipes.md",2551,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fphysics-system\u002Freferences\u002Fragdoll-recipes.md",{"path":87,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":88,"sourceHtmlUrl":89},"references\u002Fraycasting-recipes.md",6934,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fphysics-system\u002Freferences\u002Fraycasting-recipes.md",{"path":91,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":92,"sourceHtmlUrl":93},"references\u002Frigidbody-recipes.md",6026,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fphysics-system\u002Freferences\u002Frigidbody-recipes.md",{"path":95,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":96,"sourceHtmlUrl":97},"references\u002Fsoftbody-recipes.md",3376,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fphysics-system\u002Freferences\u002Fsoftbody-recipes.md",{"path":99,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":100,"sourceHtmlUrl":101},"references\u002Fstaticbody-recipes.md",1879,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fphysics-system\u002Freferences\u002Fstaticbody-recipes.md",{"path":103,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":104,"sourceHtmlUrl":105},"references\u002Ftroubleshooting.md",1285,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fphysics-system\u002Freferences\u002Ftroubleshooting.md",[107,125,146,176,199,217],{"skillNo":108,"name":109,"nameZh":6,"description":110,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":28},"01M6KRFE5BR2PSD08ZKDAS66R7","xr-development","Use when building VR\u002FAR\u002FXR applications — OpenXR setup, XROrigin3D, hand tracking, controllers, passthrough, and Meta Quest deployment in Godot 4.3+","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fxr-development\u002FSKILL.md",[],[114,115,26,116,25,117,118,119,24,120,121,22,122,123,124],"xr development","development","deployment","vr","setup","tracking","ar","hand","Meta","applications","quest",{"skillNo":126,"name":127,"nameZh":6,"description":128,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":129,"categories":130,"keywords":131,"publishedAt":28},"01M6KRF8GZTG1TAS506MFBSGFC","web-services","Use when a Godot game calls a web server — HTTPRequest, downloads, REST\u002FJSON APIs, auth headers, WebSocketPeer clients, TLS, retries, and keeping secrets out of the build. Not for game networking\u002FRPCs (multiplayer-basics) or browser export (web-export)","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fweb-services\u002FSKILL.md",[],[132,133,134,135,136,137,138,139,22,26,25,140,141,142,143,144,145],"web services","web","services","tls","retries","calling","auth","downloads","clients","headers","secrets","json","build","REST",{"skillNo":147,"name":148,"nameZh":6,"description":149,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":150,"categories":151,"keywords":157,"publishedAt":28},"01M6KRF38Q4WSKAYFS56PG87T0","web-export","Use when shipping a Godot game to the browser — Web export preset options, threads vs no-threads and COOP\u002FCOEP headers, hosting on itch.io or your own server, PWA, JavaScriptBridge, user:\u002F\u002F persistence, audio and input limits, and load size","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fweb-export\u002FSKILL.md",[152],{"categoryNo":153,"categoryName":154,"taxonomyType":155,"taxonomyTypeDesc":156},"01JBSEEDCAT000000000000016","图像与多媒体","SCENARIO","使用场景",[133,158,159,160,161,162,163,164,141,165,166,26,167,168,169,170,171,172,22,173,174,175],"export","web export","threads","limits","shipping","size","options","hosting","input","Coop","preset","browser","game","io","load","pwa","Audio","server",{"skillNo":177,"name":178,"nameZh":6,"description":179,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":180,"categories":181,"keywords":190,"publishedAt":28},"01M6KREYFETEBH62ZTN6EZH2X3","using-godot-prompter","Bootstrap skill — establishes how to find and use GodotPrompter skills, with platform-specific tool mapping","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fusing-godot-prompter\u002FSKILL.md",[182,185],{"categoryNo":183,"categoryName":184,"taxonomyType":155,"taxonomyTypeDesc":156},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":186,"categoryName":187,"taxonomyType":188,"taxonomyTypeDesc":189},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[25,191,192,23,193,22,194,195,196,197,198],"using godot prompter","find","bootstrap","tool","platform","mapping","how","how to",{"skillNo":200,"name":201,"nameZh":6,"description":202,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":203,"categories":204,"keywords":205,"publishedAt":28},"01M6KRER5G7EQWKGAFN8QJKQ69","tween-animation","Use when implementing tweens — property animation, method tweening, chaining, parallel sequences, easing, and common UI\u002Fgameplay motion recipes","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Ftween-animation\u002FSKILL.md",[],[206,207,22,208,209,210,211,212,213,214,215,26,216],"tween animation","Animation","motion","parallel","gameplay","chaining","ui","recipes","common","implementing","sequences",{"skillNo":218,"name":219,"nameZh":6,"description":220,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":221,"categories":222,"keywords":223,"publishedAt":28},"01M6KREKGCQMVDV8WX7HWX8BZG","state-machine","Use when building a state machine or refactoring logic into one — enum, node, and resource-based FSM patterns with trade-offs. Not for adding states to an existing one","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fstate-machine\u002FSKILL.md",[],[224,225,226,25,26,227,228,229,230,231,23,22,215,232],"state","state machine","machine","patterns","node","fsm","state machines","trade","trade-offs"]