This manual explains the detailed settings for collision detection between an object’s collision shape (CollisionShape2D) and tiles or other objects.
Overview of Collision Detection and Raycasting
In ACTION GAME MAKER, collision detection generates a rectangular detection area based on the size of the object’s collision shape (CollisionShape2D). It then casts rays—called “Ray”—from each of the four edges of this area to detect collisions. A “Ray” is like an invisible bullet fired at regular intervals; if it hits another collision shape or tile, it registers a collision. This process is called “Raycast.”
Raycast Settings
Raycast settings can be configured under the conditions: “Collision with Object’s Collision Shape,” “Collision with Tile,” and “Collision with Slope Tile.”
Number of Rays (ray_number):
Set as an integer. This value indicates the number of rays cast per side of the detection area. Rays are evenly spaced along each side according to its length.
For example, if one side is 24 pixels long and ray_number is 3, rays are cast every 12 pixels; if ray_number is 4, rays are cast every 8 pixels.
Note: More rays increase detection accuracy but may also increase processing load.
Detection Method (detect_method):
Choose between “Any” (at least one ray must hit) or “All” (all rays must hit).
- With “Any,” if any ray successfully detects a collision, the system registers a collision.
- With “All,” a collision is registered only if all rays successfully detect a collision.
As shown below, when contacting a corner, “Any” registers a collision, while “All” does not.
Ray Length (ray_length):
Set as a float value. This specifies how far (in pixels) each ray extends—i.e., how far away an object can be and still register as a collision.
This setting is particularly important when adjusting detection for moving platforms (e.g., elevators).
For example, when descending on a moving platform, the character may briefly separate from the platform during movement. If the ray length is too short, the system may incorrectly register “no collision.”
Conversely, if the ray length is too long, it may falsely register collisions with distant objects. Typically, adjust this value to match the GameObject’s CharacterBody2D > Floor > Snap Length property or the speed of the platform object being used.
Ray Offset (ray_offset):
Set as a float value. This specifies the offset (in pixels) from each corner when generating rays.
As mentioned, the detection area is always rectangular, but collision shapes may be capsules, polygons, or combinations of multiple shapes—not necessarily rectangular. Using an offset allows raycasting to more closely match the actual collision shape.
The offset value is measured in pixels from both ends of each side.
For example, if one side is 24 pixels long and you cast 3 rays, the rays will be positioned as shown below:
Coordinate Space (coord_space):
This setting determines which coordinate space to use as the reference for directional collision detection—especially important when the object is rotated.
For example, if an object rotated 180 degrees (upside down) touches the ground, should the system register it as touching “down” or “up”? The desired result depends on your intent.
If you want to detect head contact, you need “up”; if you simply want to detect landing, “down” is preferable.
Additionally, there are cases where only the collision shape rotates while the object remains stationary.
You can choose from three options: Global, Local is Game Object, and Local is Collision. The following diagrams illustrate these:
① When the game object itself is rotated 45 degrees and contacts the ground:
② When the game object remains stationary, but only the collision shape rotates 90 degrees and contacts the ground:
-
Global (Global coordinates, using the entire game scene’s coordinate system):
Collision is determined based on the global coordinates of the game object’s origin and the target’s origin. Rotation is ignored entirely. Thus, in both diagrams ① and ②, the system registers “down” as the contact direction. -
Local is Game Object (Using the game object’s local coordinates):
Collision is determined based on the game object’s local coordinates. Only the game object’s rotation is considered.- In diagram ①, the system registers “right” and “down” as contact directions.
- In diagram ②, the system registers “down” as the contact direction.
-
Local is Collision (Using the collision shape’s local coordinates):
Collision is determined based on the collision shape’s local coordinates. Only the collision shape’s rotation is considered.- In diagram ①, the system registers “right” and “down” as contact directions.
- In diagram ②, the system registers “right” as the contact direction.
Although this concept may seem complex, mastering it will allow you to create collision detection exactly as you envision.