godot-2d-physics
Expert patterns for Godot 2D physics including collision layers/masks, Area2D triggers, raycasting, and PhysicsDirectSpaceState2D queries. Use when implementing collision detection, trigger zones, line-of-sight systems, or manual physics queries. Trigger keywords: CollisionShape2D, CollisionPolygon2D, collision_layer, collision_mask, set_collision_layer_value, set_collision_mask_value, Area2D, body_entered, body_exited, RayCast2D, force_raycast_update, PhysicsPointQueryParameters2D, PhysicsShapeQueryParameters2D, direct_space_state, move_and_collide, move_and_slide.
thedivergentai · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add thedivergentai/GD-Agentic-Skills --skill godot-2d-physics技能说明
name: godot-2d-physics description: "Expert patterns for Godot 2D physics including collision layers/masks, Area2D triggers, raycasting, and PhysicsDirectSpaceState2D queries. Use when implementing collision detection, trigger zones, line-of-sight systems, or manual physics queries. Trigger keywords: CollisionShape2D, CollisionPolygon2D, collision_layer, collision_mask, set_collision_layer_value, set_collision_mask_value, Area2D, body_entered, body_exited, RayCast2D, force_raycast_update, PhysicsPointQueryParameters2D, PhysicsShapeQueryParameters2D, direct_space_state, move_and_collide, move_and_slide."
2D Physics
Expert guidance for collision detection, triggers, and raycasting in Godot 2D.
NEVER Do
- NEVER scale
CollisionShape2Dnodes — Use the shape handles in the editor, NOT the Node2D scale property. Scaling causes unpredictable physics behavior and incorrect collision normals [12]. - NEVER confuse
collision_layerwithcollision_mask— Layer = "What AM I?", Mask = "What do I DETECT?". Setting both to the same value is usually wrong [13]. - NEVER multiply velocity by delta when using
move_and_slide()—move_and_slide()automatically includes timestep. Only multiply gravity/acceleration by delta [14]. - NEVER forget
force_raycast_update()for manual mid-frame raycasts — Raycasts update once per physics frame. If you change target_position, you MUST force an update [15]. - NEVER use
get_overlapping_bodies()every frame — It is expensive. Cache results withbody_entered/body_exitedsignals instead [16]. - NEVER modify
RigidBody2Dstate directly in_process— Use_integrate_forces()for safe, synchronized access toPhysicsDirectBodyState2D[17, 411]. - NEVER move
PhysicsBody2Dnodes in_process()— Use_physics_process(). Moving bodies outside the physics step causes stutter and unreliable collision detection. - NEVER use
RigidBody2Dfor 1000+ simple entities — UsePhysicsServer2Dto bypass node overhead for massive performance gains (Swarms/Bullets) [18, 397]. - NEVER use
Area2Dfor high-frequency blocking (Bullets) — Area signals can be delayed. Usemove_and_collide()orShapeCast2Dfor frame-perfect results [19]. - NEVER ignore 'Physics Jitter' on high-refresh monitors — Enable Physics Interpolation to prevent micro-stutter in motion [21, 400].
- NEVER scale collision shapes directly at runtime — It causes major instability. Resize the shape resource (size/radius) instead.
- NEVER use
set_deferredfor immediate physics transform logic — It happens at the end of the frame. Useforce_raycast_update()orPhysicsServer2Dinstead. - NEVER leave Continuous CD (CCD) enabled for slow objects — It adds significant CPU overhead. Reserve it for high-speed projectiles to prevent tunneling.
- NEVER use a single collision layer for all tiles/entities — Separate layers (Ground, Walls, Enemies) to allow selective filtering via masks.
- NEVER forget to free
PhysicsServer2DRIDs manually — They are not garbage collected and will leak memory permanently.
Available Scripts
MANDATORY: Read the script matching your workflow branch before coding. Query/Area cookbook samples live in scripts — not in this body.
Workflow router (MANDATORY / Do NOT Load)
| Branch | Load | Do NOT Load |
|---|---|---|
| Layer/mask matrix setup | collision_bitmask_helper.gd or collision_setup.gd; matrix policy → collision_layer_matrix_manager.gd | Swarm / CCD scripts |
| LOS / vision cones | raycast_vision_stack.gd (+ physics_direct_query.gd for nodeless rays) | shapecast_aoe*.gd, physics_server_swarm.gd |
| AOE / melee volume | Prefer shapecast_aoe.gd (faction mask); ground/volume sensing → shapecast_aoe_detection.gd | Area2D spam + lava DoT tutorials; do not load both shapecast scripts for the same feature |
| Hitscan / point pick / one-shot shape | physics_queries.gd (canonical). Specialists: physics_direct_space_query.gd (LOS bool), raycast_hit_prediction.gd | Re-load all three query helpers at once |
| Bullet hell / 1000+ bodies | MANDATORY physics_server_swarm.gd (+ physics_server_direct_body.gd for RID shapes) | Per-bullet Area2D / RigidBody2D nodes |
| High-speed tunneling | continuous_collision_detection.gd + substepping_logic.gd | CCD on slow props |
| RigidBody safe mutate | safe_rigidbody_state.gd (_integrate_forces) | Direct transform writes in _process |
| Custom CharacterBody forces | custom_physics_2d.gd | custom_physics.gd (that file is RigidBody _integrate_forces) |
| Gravity zones | custom_gravity_area.gd (Area override) or custom_gravity_override.gd (character weight/zones) | Both unless you need Area + character paths |
| Overlap signal spam | collision_debouncer.gd | Polling get_overlapping_bodies every frame |
| Compound multi-shape RID | compound_body_sync.gd | Multiple nodes for one logical body |
| Debug contact normals | collision_visual_debugger.gd | Visible collision menu insufficient |
| High-refresh jitter | Prefer jitter_interpolation_fix.gd | physics_interpolation_smoothing.gd (legacy/manual; only if built-in interpolation is unavailable) |
| Precision bounce / slide | move_and_collide_precision.gd | — |
| Batch static movers | performance_batch_mover.gd | — |
| Query result cache | physics_query_cache.gd | Duplicate space queries same frame |
Canonical vs overlap (dedupe guide)
- ShapeCast AOE: load
shapecast_aoe.gdfor combat AOE;shapecast_aoe_detection.gdonly for grounded/volume checks — never both for one feature. - Space queries: start with
physics_queries.gd; addphysics_direct_query.gd/physics_direct_space_query.gdonly if that specialist matches. - Custom physics: CharacterBody →
custom_physics_2d.gd; RigidBody integrate →custom_physics.gd. - Interpolation:
jitter_interpolation_fix.gdwins over `physics_interp