This manual will provide a detailed explanation of the contact-related settings between an object’s collision shape (CollisionShape2D) and tiles or other objects.
Overview of Collision Detection and Ray Casting (RayCast)
In ACTION GAME MAKER, collision detection generates a rectangular detection area based on the size of the object’s CollisionShape2D, and then emits normals (called Rays) from the four sides of this area for detection.
Rays can be understood as invisible “bullets” fired at fixed intervals. When these “bullets” hit other collision shapes or tiles, they are considered a “hit.” This process is called Ray Casting (RayCast).
Ray Casting Settings
Ray casting can be configured in the conditions “Contact with Object Collision Shape,” “Contact with Tile,” and “Contact with Slope Tile.”
Ray Count (ray_number):
Set using an integer. The ray count indicates the number of rays emitted along each side of the detection area.
Rays are arranged equally spaced based on the side length.
For example, when a side is 24 pixels long:
- With a ray count of 3, a detection ray is generated every 12 pixels;
- With a ray count of 4, a detection ray is generated every 8 pixels.
More rays result in more reliable detection, but may also increase processing load—be mindful of performance impact.
Detection Method (detect_method):
Choose between Any (any one) or All (all).
- Any: If any one of the generated rays successfully contacts, it is判定 as “contacted.”
- All: Only when all rays successfully contact is it判定 as “contacted.”
As shown in the figure below, when only touching the corner: - Any will判定 as “in contact”;
- All will判定 as “not in contact.”
Ray Length (ray_length):
Specify using a float value, indicating how far the ray will extend in pixels.
In other words, it defines the distance within which contact is still判定.
This is mainly adjusted when detecting objects like elevators that move up and down.
For example, when a downward-moving elevator processes “elevator movement → character follows movement,” there may be a brief moment where the character slightly separates from the platform. If the ray is too short, it may be判定 as “not in contact.”
On the other hand, if the ray is set too long, it may result in contact being判定 even when separation has occurred.
Therefore, it is usually adjusted based on the GameObject > CharacterBody2D > Floor > Snap Length (snap distance) and the speed of the elevator object being used.
Ray Offset (ray_offset):
Specify using a float value to set how many pixels the ray is offset inward from the corner when generated.
As mentioned earlier, the detection area is always rectangular, but the collision shape may be a capsule, polygon, or multiple collisions combined—not necessarily rectangular.
Offsetting allows the ray detection to better match the actual collision shape.
The offset value represents the number of pixels inward from each end of the side.
That is, when a side is 24 pixels long and 3 rays are emitted, it will look like the figure below:
Coordinate Space (coord_space):
This setting determines which coordinate space is used as the basis for judging the contact direction.
It is primarily used when an object contacts another while rotated, to decide how to judge the direction.
For example: when a 180°-rotated, upside-down object contacts the ground,
should the contact direction be判定 as “down” or “up”?
The answer depends on your needs.
If you want to判定 “hit the head,” you should判定 as “up”;
if you just want to判定 landing, then “down” is more appropriate.
There is also a case where the object itself does not rotate, but only the collision body rotates.
This setting can be chosen from three modes: Global, Local is Game Object, and Local is Collision.
The following two figures illustrate this:
① When the game object rotates 45° and contacts the ground
② When the game object remains stationary, but the collision body rotates 90° and contacts the ground
-
Global (Global Coordinates: based on the entire game scene’s coordinate system)
Direction is judged based on the global coordinates of the game object’s origin and the contact object’s origin.
Rotation is completely ignored, so in both Figure ① and Figure ②, the contact is判定 as “down.” -
Local is Game Object (Based on the game object’s local coordinates)
Direction is judged based on the game object’s local coordinates.
That is, only the game object’s own rotation is considered.- In Figure ①, contact is判定 as “right” and “down”;
- In Figure ②, contact is判定 as “down.”
-
Local is Collision (Based on the collision shape’s local coordinates)
Direction is judged based on the collision shape’s local coordinates.
That is, only the collision shape’s own rotation is considered.- In Figure ①, contact is判定 as “right” and “down”;
- In Figure ②, contact is判定 as “right.”
This is a slightly complex concept, but once mastered, you can achieve precise detection that matches your expectations.