About this manual
This manual explains the Collision Compatibility Check and the collision role (collision template) you pick when creating an object. They exist so you can confirm and fix problems caused by layers and masks not lining up — “my attacks do not hit the enemy”, “the player bumps into an enemy and cannot get past” — without having to read bit numbers.
How layers and masks work in ACTION GAME MAKER
A collision has a layer (what I am) and a mask (what I care about), and what matters is whether one side’s mask contains the other side’s layer. If that does not line up, no amount of adjusting collision shapes will make anything connect.
| Which check | What makes it work |
|---|---|
| Walls (bumping and pushing) | My wall mask ∩ their wall layer |
| Attacks | The attacker’s attack mask ∩ the receiver’s hit layer |
| The visual script’s “came into contact with …” | My wall mask ∩ their wall layer |
Walls are decided independently for each side. It is entirely possible to have “A bumps into B, but B is not stopped by A”, and in that case B pushes A aside one-sidedly. To pass through each other you have to clear both sides.
Some fields are never used at runtime. Attacks look only at the mask; hits look only at the layer. Changing an attack collision’s layer or a hit collision’s mask does not change what connects.
The Collision Compatibility Check
A window where you pick two objects and it tells you in plain language whether they bump, whether attacks connect, and whether contact conditions fire. Instead of comparing bits, you read the result.
Opening it
- The “Collision Compatibility Check” button in the Inspector (it appears when a game object, an attack collision or a hit collision is selected)
- In the object editing view, the same button is on the fixed toolbar at the top
It opens with A set to the object you are currently editing and B set to Tile (terrain).
How the window is laid out
- A is on the upper left and B on the upper right. The “⇄” in the middle swaps them.
- “Select object…” on each panel picks a scene (
.tscn). The default location isres://objects/gameobjects. - The “Tile” button turns that side into a tile (terrain). Tiles are treated as layer 1.
- The results appear along the bottom.
The four editable fields
Each panel shows only the four fields that are actually used at runtime.
| Field | Meaning |
|---|---|
| Wall Layer | What this object is (the side picked up by the other’s mask) |
| Wall Mask | What this object wants to bump into |
| Attack Mask | The hit layer of whoever you want your attacks to land on |
| Hit Layer | What this object’s hit collision is |
Pressing a numbered button (layers 1–8) toggles it on the spot, and the results below update immediately. If you are using layer 9 or above, those settings are preserved but cannot be edited on this screen.
Nothing has been written to the scene at this point. If you are only pressing buttons to compare, closing the window leaves the original object untouched. Inside the window, Ctrl+Z / Ctrl+Shift+Z undo and redo your changes.
Reading the results
The results come in three parts.
Walls (bumping and pushing)
- “A and B collide and push each other”
- “A bumps into B and stops, but B is not stopped by A” → B can push A aside one-sidedly
- “A and B pass through each other”
- When the other side is a tile, it comes down purely to whether the object’s wall mask contains layer 1 (tiles do not move)
- For lightweight objects, or when there is no valid wall collision shape, it says so
Attack → hit
- “A’s attacks hit B” / “do not hit”, shown in both directions, A→B and B→A
- If the receiving side has no hit collision (HitArea2D), a warning says “no hit collision, so nothing connects”
- Tiles have neither attack nor hit collisions, so they are out of scope
- Picking the same object for A and B shows it as “the relationship when several of the same kind exist” (attacks never hit the attacker itself)
Visual script contact conditions
- “A’s contact condition can detect B” / “cannot”, in both directions
- Conditions of the “came into contact with …” kind use that object’s wall mask by default. So changing the wall mask also changes whether contact conditions fire
- Turn on “Use Collide Mask Settings” on the condition and that one condition gets its own independent mask
- If the other side is a lightweight object (Area2D), you have to turn on “collide_with_areas” on the condition
Writing it to the object
- “Apply Template” loads the recommended settings for a role into the working copy (see below).
- “Apply to Object” writes your changes into the object. This can be undone.
- Only the object you are currently editing can be written to. The side where you picked a different scene is a trial change only and is not saved to that scene.
- Trying to close with unapplied changes asks whether you want to apply them.
Collision roles (templates)
A scheme where the meaning of each layer number is fixed in advance, so picking a role sets walls, attacks and hits all at once.
What the layer numbers mean
Only when you use templates, they are set according to this assignment.
| Layer | Role |
|---|---|
| 1 | Tiles (terrain) |
| 2 | Player |
| 3 | Player bullets |
| 4 | Enemies |
| 5 | Enemy bullets |
| 6 | Ally NPCs |
| 7 and up | Reserved (yours to use) |
This does not rewrite the settings in an existing project. Objects you have built so far are left alone; only objects you apply a template to follow this assignment. Mixing the two makes things stop lining up, so if you start using it partway through, bring all the related objects into line together.
The available templates
| Name | What you get | Wall Layer | Wall Mask | Attack Mask | Hit Layer |
|---|---|---|---|---|---|
| Standard player | Pushes against tiles and enemies; attacks hit enemies and enemy bullets; takes enemy attacks | 2 | 1, 4 | 4, 5 | 2 |
| Player not blocked by enemies | Walks through enemies without bumping | 2 | 1 | 4, 5 | 2 |
| Standard enemy | Pushes against tiles and the player; enemies pass through each other | 4 | 1, 2 | 2, 3 | 4 |
| Enemy that also pushes other enemies | As the standard enemy, plus enemies push each other | 4 | 1, 2, 4 | 2, 3 | 4 |
| Enemy not blocked by the player | Walks through the player without bumping | 4 | 1 | 2, 3 | 4 |
| Enemy that passes through walls (complete pass-through) | Bumps into nothing at all — not walls, not other objects | none | none | 2, 3 | 4 |
| Player bullet | Attacks hit enemies and enemy bullets (cancelling them out) | 3 | 1 | 4, 5 | 3 |
| Enemy bullet | Attacks hit the player and player bullets (cancelling them out) | 5 | 1 | 2, 3 | 5 |
| Ally NPC | Pushes against tiles and enemies; passes through the player | 6 | 1, 4 | 4, 5 | 6 |
| Item / contact gimmick | No physical pushing; detects the player with its own contact condition | none | 2 | none | none |
| Destructible platform | Same wall layer as tiles, so you can stand on it, and the player’s attacks break it | 1 | 1 | none | 4 |
The “not blocked by” entries produce a one-sided pushing relationship if you apply them to only one side. To have both pass through each other, apply a “not blocked by” template to both.
Picking one when creating an object
The object creation dialog has a “Collision role” dropdown.
- The candidates are narrowed by the selected object group. The Player group shows only player-related roles, the Enemy group only enemy-related ones; with no group set, or another group, everything is listed.
- Each group starts with its default role already selected (“Standard player” for the player, and so on). Create it as-is and the settings line up.
- Choosing “Template default” uses the values the template originally came with (the role assignment is not applied).
- If you selected a lightweight object, the wall layer becomes “none” (it does no physical pushing).
Applying one to an existing object
Load it with “Apply Template” in the Collision Compatibility Check, then confirm with “Apply to Object”. Right after loading it is only a working copy, so you can read the result text before committing.
Worked examples
The player’s attacks hit their allies
By long-standing convention, walls, attacks and hits were all given the same value at creation time, which means the player’s attack mask often contains the player’s own layer.
- Select the player and open the Collision Compatibility Check.
- Pick an ally (or the player again) for B.
- If “Attack → hit” says “hits”, that is your cause.
- Remove the ally’s layer from the player’s attack mask and press “Apply to Object”.
Applying a role template to both sides stops this combination arising at all.
You want to walk through enemies
- Line the player and an enemy up as A / B.
- Confirm that “Walls (bumping and pushing)” reads “push each other”.
- Apply “Player not blocked by enemies” to the player and “Enemy not blocked by the player” to the enemy.
- You are done once the result changes to “pass through each other”.
Doing only one side gives you the “pushes aside one-sidedly” state, which can bury the pushed side in a wall.
Bullets do not hit enemies
- Set the bullet as A and the enemy as B.
- Under “Attack → hit”, check whether the bullet’s attack mask contains the enemy’s hit layer.
- If it does not, apply “Player bullet” to the bullet.
Making a bullet disappear when it hits a wall is not part of the template. Build “disappear on contact” in the visual script.
Things to watch out for
- Changing the wall mask also changes the outcome of visual script contact conditions. That is because “came into contact with …” conditions use the wall mask by default. If you only want to change pushing, make the condition independent with “Use Collide Mask Settings”.
- Attacks use only the mask, hits use only the layer. Changing an attack collision’s layer or a hit collision’s mask changes nothing (which is why they are not shown in the compatibility check either).
- “Apply to Object” can only write to the object you are editing. The scene you picked for the other side is a trial change only. To fix that one too, open it and do the same thing there.
- The role templates’ assignment is a separate system from your existing project’s settings. Mixing them breaks compatibility, so if you use them, bring all the related objects into line together.
- Tiles are layer 1. Remove layer 1 from a wall mask and the object falls straight through the terrain.
- “Enemy that passes through walls” sets the wall layer to 0 as well. It then cannot be detected by other objects’ contact conditions either, so it is no use if something needs to react to touching it.
- Lightweight objects do no pushing. To have another object’s contact condition pick them up, you need “collide_with_areas” turned on for that condition.
- Settings that use layer 9 or above cannot be edited in the compatibility check window (they are preserved).