跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
演示文稿

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 CollisionShape2D nodes — 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_layer with collision_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 with body_entered/body_exited signals instead [16].
  • NEVER modify RigidBody2D state directly in _process — Use _integrate_forces() for safe, synchronized access to PhysicsDirectBodyState2D [17, 411].
  • NEVER move PhysicsBody2D nodes in _process() — Use _physics_process(). Moving bodies outside the physics step causes stutter and unreliable collision detection.
  • NEVER use RigidBody2D for 1000+ simple entities — Use PhysicsServer2D to bypass node overhead for massive performance gains (Swarms/Bullets) [18, 397].
  • NEVER use Area2D for high-frequency blocking (Bullets) — Area signals can be delayed. Use move_and_collide() or ShapeCast2D for 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_deferred for immediate physics transform logic — It happens at the end of the frame. Use force_raycast_update() or PhysicsServer2D instead.
  • 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 PhysicsServer2D RIDs 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)

BranchLoadDo NOT Load
Layer/mask matrix setupcollision_bitmask_helper.gd or collision_setup.gd; matrix policy → collision_layer_matrix_manager.gdSwarm / CCD scripts
LOS / vision conesraycast_vision_stack.gd (+ physics_direct_query.gd for nodeless rays)shapecast_aoe*.gd, physics_server_swarm.gd
AOE / melee volumePrefer shapecast_aoe.gd (faction mask); ground/volume sensing → shapecast_aoe_detection.gdArea2D spam + lava DoT tutorials; do not load both shapecast scripts for the same feature
Hitscan / point pick / one-shot shapephysics_queries.gd (canonical). Specialists: physics_direct_space_query.gd (LOS bool), raycast_hit_prediction.gdRe-load all three query helpers at once
Bullet hell / 1000+ bodiesMANDATORY physics_server_swarm.gd (+ physics_server_direct_body.gd for RID shapes)Per-bullet Area2D / RigidBody2D nodes
High-speed tunnelingcontinuous_collision_detection.gd + substepping_logic.gdCCD on slow props
RigidBody safe mutatesafe_rigidbody_state.gd (_integrate_forces)Direct transform writes in _process
Custom CharacterBody forcescustom_physics_2d.gdcustom_physics.gd (that file is RigidBody _integrate_forces)
Gravity zonescustom_gravity_area.gd (Area override) or custom_gravity_override.gd (character weight/zones)Both unless you need Area + character paths
Overlap signal spamcollision_debouncer.gdPolling get_overlapping_bodies every frame
Compound multi-shape RIDcompound_body_sync.gdMultiple nodes for one logical body
Debug contact normalscollision_visual_debugger.gdVisible collision menu insufficient
High-refresh jitterPrefer jitter_interpolation_fix.gdphysics_interpolation_smoothing.gd (legacy/manual; only if built-in interpolation is unavailable)
Precision bounce / slidemove_and_collide_precision.gd—
Batch static moversperformance_batch_mover.gd—
Query result cachephysics_query_cache.gdDuplicate space queries same frame

Canonical vs overlap (dedupe guide)

  • ShapeCast AOE: load shapecast_aoe.gd for combat AOE; shapecast_aoe_detection.gd only for grounded/volume checks — never both for one feature.
  • Space queries: start with physics_queries.gd; add physics_direct_query.gd / physics_direct_space_query.gd only if that specialist matches.
  • Custom physics: CharacterBody → custom_physics_2d.gd; RigidBody integrate → custom_physics.gd.
  • Interpolation: jitter_interpolation_fix.gd wins over `physics_interp
阅读完整来源 ↗