← ExekiteCONTENT HISTORY

Update to Exekite

Snapshot Nov 17, 2026 · 12:11 UTC · version 1.0.0

Collection source: downloaded plugin package.

WHAT CHANGED

First saved snapshot

No earlier snapshot is available to establish a change.

Save Exekite and check future changes in Following.

Up to 3 plugins free · no card required.

Compare saved observations

Download comparison JSON
Full technical diff · 0 changed fields
Full snapshot data
{
  "description": "For Exekite-hosted Godot games only. Godot 4 collision system — Area2D vs bodies, collision layers + masks, enter/exit signals, hitbox/hurtbox split. Use when an overlap misfires, things collide with the wrong things, or when unsure whether a pickup, hazard or hitbox is an Area2D or a solid body.",
  "included_files": [],
  "name": "collisions-and-areas",
  "skill_md_contents": "---\nname: collisions-and-areas\ndescription: \"For Exekite-hosted Godot games only. Godot 4 collision system — Area2D vs bodies, collision layers + masks, enter/exit signals, hitbox/hurtbox split. Use when an overlap misfires, things collide with the wrong things, or when unsure whether a pickup, hazard or hitbox is an Area2D or a solid body.\"\n---\n\n# Collisions and areas\n\nThree concerns: **what kind of body is this**, **what does it collide with**, and **how does it react**.\n\n## Body types — pick one per node\n\n| Body | Used for | Auto-physics? | Collision response? |\n|---|---|---|---|\n| `StaticBody2D` | Walls, ground, immobile platforms | No | Other bodies bounce off |\n| `CharacterBody2D` | Player, NPCs, anything you control | No (you set velocity) | Slides via `move_and_slide()` |\n| `RigidBody2D` | Physics props, debris, dice | Yes (forces, gravity) | Engine-driven |\n| `Area2D` | Triggers, hurtboxes, pickups, sensors | No | NONE — just detects overlap |\n\nPicking the wrong body class is the #1 collision bug. **`Area2D` for \"did X enter Y\", everything else for solid presence.**\n\n## CollisionShape2D / CollisionPolygon2D\n\nEvery body needs at least one collision shape as a child:\n\n```\nCoin (Area2D)\n├── Sprite2D\n└── CollisionShape2D       (with a CircleShape2D resource)\n```\n\nCommon shapes: `CircleShape2D`, `RectangleShape2D`, `CapsuleShape2D` (good for character bodies), `WorldBoundaryShape2D` (infinite plane), `ConvexPolygonShape2D`, `ConcavePolygonShape2D` (concave only on `StaticBody2D`).\n\nShapes can be enabled/disabled per-frame:\n```gdscript\n$CollisionShape2D.set_deferred(\"disabled\", true)   # safe inside a signal handler\n```\n\nThe `set_deferred` form is required when toggling INSIDE a body_entered/area_entered handler — toggling synchronously confuses the physics step.\n\n## Layers and masks\n\nTwo integers per body, each a bitfield over 32 named \"physics layers\":\n\n- **Layer**: which layers does this body live in?\n- **Mask**: which layers does this body scan for collisions?\n\nAn Area2D detects B when `A.mask & B.layer != 0`; B does not need to scan A.\nBody collision response also depends on the body types and their movement.\n\n**This platform's `project.godot` declares NO `[layer_names]`.** You cannot add\nany — the harness owns that file and you may not write it. So layers are bare\nnumbers here, and the only place their meaning can live is your code.\n\nSet them numerically, and say what each one means where you set it:\n\n```gdscript\nconst LAYER_WORLD := 1\nconst LAYER_PLAYER := 2\nconst LAYER_ENEMY := 3\n\nfunc _ready() -> void:\n    # set_collision_layer_value / _mask_value take a 1-based INDEX, not a bitmask\n    collision_layer = 0  # clear default layer 1 before choosing membership\n    collision_mask = 0\n    set_collision_layer_value(LAYER_PLAYER, true)\n    set_collision_mask_value(LAYER_WORLD, true)\n    set_collision_mask_value(LAYER_ENEMY, true)\n```\n\n`collision_layer = 3` (raw bitmask: layers 1 AND 2) and `set_collision_layer_value(3, true)`\n(the index: adds layer 3, bit value 4) mean DIFFERENT things — for values 1 and 2\nthe values happen to coincide, but the helper preserves other set bits. Pick the index\nhelpers and stay with them.\n\nA typical setup:\n\n| Thing | Layer | Mask |\n|---|---|---|\n| World walls / ground | world | (nothing — it doesn't move) |\n| Player | player | world |\n| Enemy | enemy | world, player |\n| Player hitbox (sword swing) | player_hitbox | enemy_hurtbox |\n| Enemy hurtbox | enemy_hurtbox | (nothing — only hit detects it) |\n| Coin pickup | pickup | player (the coin handles `body_entered`) |\n\nSet layer/mask in code, or as `collision_layer` / `collision_mask` integer properties on the node's section in the `.tscn`:\n```gdscript\ncollision_layer = 0b0010    # layer 2\ncollision_mask  = 0b0001    # scans layer 1\n# Equivalent using 1-based indices, starting from cleared bits:\ncollision_layer = 0\ncollision_mask = 0\nset_collision_layer_value(2, true)\nset_collision_mask_value(1, true)\n```\n\n## Detecting overlaps with Area2D\n\nArea2D has two pairs of signals:\n- `body_entered(body: Node2D)` / `body_exited` — for `*Body2D` collisions\n- `area_entered(area: Area2D)` / `area_exited` — for area-on-area\n\nConnect in `_ready`:\n```gdscript\nextends Area2D\n\nsignal collected(amount: int)\n\nfunc _ready() -> void:\n    collision_layer = 0\n    collision_mask = 0\n    set_collision_layer_value(4, true)  # pickup\n    set_collision_mask_value(2, true)   # player; match the player's layer\n    body_entered.connect(_on_body_entered)\n\nfunc _on_body_entered(body: Node) -> void:\n    if not body.is_in_group(\"player\"):\n        return\n    collected.emit(1)  # the level owner counts; freeform games have no GameState autoload\n    queue_free()\n```\n\nEnter signals fire once when an overlap begins. If contact damage should repeat\nafter invulnerability expires, check the continuing overlaps on physics ticks or\ntrack enter/exit membership; waiting for another enter event leaves a player safe\ninside the hazard. Route one contact representation through the damage handler so\nbody and hurtbox notifications cannot independently charge the same hit.\n\nDamage feedback must reach the visible renderer: the CanvasItem that owns the\n2D `_draw()` or sprite (or its ancestor), or the material of the visible 3D mesh.\nModulating an empty child does not change drawing on its parent. Observe a hit\nand the feedback's reset; a timer named invulnerability does not prove a flash.\n\nGroup-based filtering (`is_in_group(\"player\")`) decouples the area from a specific class. Add the player to the `\"player\"` group in its `.tscn`.\n\n## Hitbox / hurtbox split\n\nFor combat, separate the thing that DEALS damage from the thing that TAKES damage:\n\n- **Hitbox**: an Area2D on the attacker. Active during the attack frames.\n- **Hurtbox**: an Area2D on the target. Active whenever the target is vulnerable.\n\nThe hitbox detects overlap with the hurtbox; the hurtbox notifies the parent.\n\n```gdscript\n# Hitbox.gd (Area2D, on attacker)\n@export var damage: int = 10\n\nfunc _ready() -> void:\n    area_entered.connect(_on_area_entered)\n    monitoring = false   # hitbox starts disabled; AnimationPlayer toggles it\n\nfunc _on_area_entered(area: Area2D) -> void:\n    if area is Hurtbox:\n        area.take_hit(damage)\n```\n\n```gdscript\n# Hurtbox.gd (Area2D, on target)\nclass_name Hurtbox\nextends Area2D\nsignal hit_taken(damage: int)\n\nfunc take_hit(amount: int) -> void:\n    hit_taken.emit(amount)\n```\n\nThe attacker's AnimationPlayer enables the hitbox via a method track (frame 12 of the swing) and disables it on frame 16. Outside those frames, the box is dormant.\n\n## Querying without signals — direct intersect\n\nSometimes you want a one-shot \"what's in this region right now?\" instead of an enter signal:\n\n```gdscript\nvar space := get_world_2d().direct_space_state\nvar query := PhysicsShapeQueryParameters2D.new()\nquery.shape = $CollisionShape2D.shape\nquery.transform = global_transform\nquery.collision_mask = collision_mask\nvar hits := space.intersect_shape(query, 32)   # max results\nfor hit in hits:\n    print(hit.collider)\n```\n\nUseful for \"find all enemies in a 100-pixel radius around the explosion\" without creating a temporary Area2D.\n\n## RigidBody2D — when you want the engine to drive\n\nForces, torque, gravity all auto-apply. You're typically not setting velocity directly.\n\n```gdscript\nextends RigidBody2D\n\nfunc _ready() -> void:\n    apply_central_impulse(Vector2(200, -300))   # initial pop\n```\n\nFor a platform or door that moves on rails and pushes bodies, use `AnimatableBody2D` — set `position`; it sweeps correctly (see moving-things-that-collide).\n\n## Per-instance shapes and reachable patrols\n\nA scene's embedded Shape2D/Shape3D resource is shared between its instances unless\nit is local to the scene. Mutating one instance's shape can silently resize every\nwall while each wall still draws its own dimensions. Before changing a shape's\nsize or radius, mark its sub-resource `resource_local_to_scene = true` in the\n`.tscn`, or assign an instance-owned copy:\n\n```gdscript\nextends StaticBody2D\n\n@export var wall_size := Vector2(80, 40)\n\nfunc _ready() -> void:\n    var collision := $CollisionShape2D as CollisionShape2D\n    var local_shape := collision.shape.duplicate() as RectangleShape2D\n    local_shape.size = wall_size\n    collision.shape = local_shape\n```\n\nVerify two differently sized instances retain different collision dimensions after\nboth enter the tree. Test movement against several points along the outer walls,\nnot just their centers; a narrow shared shape can block the center yet leave most\nof the visible boundary open.\n\nPatrol waypoints must connect through free space with clearance for the enemy's\ncollision radius. `move_and_slide()` does not navigate around a hedge: an enemy\nthat advances only when it reaches the target will stay blocked forever. Observe\none complete patrol loop against the actual wall shapes. A passed build gate and\none successful movement sample do not prove a loop or a win/lose condition.\nKeep the patroller's world collision mask enabled when walls should block it;\nfix the route and clearance instead of disabling collision to pass through a wall.\n\n## Anti-patterns\n\n- Using `Area2D` and trying to make it block movement. Areas don't block. You want `StaticBody2D` or a tile collision.\n- Using `CharacterBody2D` for a pickup. You want `Area2D` — pickups don't block; they detect.\n- Toggling `disabled` synchronously inside a body_entered handler. Use `set_deferred(\"disabled\", true)`.\n- Everything left on the default (layer 1, mask 1). Everything collides with everything and interactions cannot be filtered. Set layers/masks deliberately.\n- Connecting `body_entered` for `Area2D` overlap with another `Area2D`. That fires `area_entered`, not `body_entered`. Read the body class.\n- A single Area2D doing both pickup-detection AND hurtbox AND wall-trigger. Each role wants its own area (different mask, different signal handler).\n"
}

SHA-256 of public snapshot: ea35158a794224d7a5bdb80e5dd8181cb3ee1fdde88b29d24a941f123bd107a2