collider

FreeBodyEngine.core.collider

CircleCollider2D(position=Vector(), rotation=0, scale=Vector(1, 1))

Bases: Collider2D

A circular Collider2D, backed by a CircleCollisionShape.

Creates a CircleCollider2D, deriving the collision shape's radius from scale.x (half of it, so scale.x acts as the circle's diameter).

collision_shape instance-attribute

apply_transform()

Syncs the collision shape's position and rotation to the node's world transform, and derives its radius from the world scale's x component.

toggle_debug_visuals()

Adds a CircleColliderDebug child if this collider (already initialized) has none yet, otherwise removes any existing ones.

CircleCollisionShape(position, rotation, radius)

Bases: CollisionShape

A circular collision shape, defined by a center position and radius.

Stores the circle's position, rotation, and radius directly (rotation has no effect on a circle's shape, but is kept for a consistent CollisionShape interface).

position = position instance-attribute

radius = radius instance-attribute

rotation = rotation instance-attribute

collide_circle(other)

Checks whether the two circles overlap by comparing the distance between their centers to the sum of their radii.

collide_point(point)

Checks whether point lies within the circle's radius.

collide_polygon(other)

Checks collision against a polygon by delegating to the polygon's own circle-collision test.

collide_rectangle(other)

Checks collision against a rectangle by delegating to the rectangle's own circle-collision test.

compute_mass(density)

A solid disk's mass is density * pi * r^2; its moment of inertia about its own center is mass * r^2 / 2.

get_aabb()

The circle's bounding box: its position offset by radius on every side.

Collider2D(collision_shape_cls, position=Vector(), rotation=0, scale=Vector(1, 1))

Bases: Node2D

Base node for 2D colliders - wraps a CollisionShape and keeps it in sync with the node's world transform each update.

Creates the collision shape instance via collision_shape_cls(position, rotation, scale) - passing scale for whichever third parameter that shape class expects (size for RectangleCollisionShape). CircleCollider2D corrects this immediately afterward by overwriting collision_shape.radius, since a circle's constructor expects a radius, not a size vector.

collision_shape = collision_shape_cls(position, rotation, scale) instance-attribute

apply_transform()

Copies the node's world transform onto the underlying collision shape's position/rotation/size.

collide(other)

Checks collision against another Collider2D by delegating to the underlying collision shapes.

on_update()

Keeps the collision shape's position/rotation/size in sync with the node's world transform every frame.

toggle_debug_visuals()

Adds or removes this collider's debug-visualization child node, depending on whether one is already present.

CollisionShape(position, rotation)

A Collision Shape. Contains logic for basic arcade collisions.

:param position: The position of the collider. :type position: Vector

No-op base initializer - concrete shapes (Circle/RectangleCollisionShape) set their own position/rotation/size attributes directly instead of calling this.

collide(other)

Checks collision with any collider object or point.

:param other: Checked object. :type other: Collider | Vector

:rtype: bool

collide_circle(other)

Checks for collision against a circle collider.

:param other: The checked collider. :type other: CircleCollider

:return bool: collision?

collide_point(point)

Checks for collision against a point.

:param point: The checked point. :type point: Vector

:rtype: bool

collide_polygon(other)

Checks for collision against a general convex polygon collider.

collide_rectangle(other)

Checks for collision against a rectangle collider.

Parameters:

Name	Type	Description	Default
other	RectangleCollider	The checked collider.	required

Returns:

Name	Type	Description
bool	bool	collision?

compute_mass(density)

Returns (mass, moment_of_inertia) for this shape at the given density, both about this shape's own centroid - used by RigidBody2D to auto-derive mass/inertia from its collider rather than requiring them to be set by hand.

get_aabb()

Returns this shape's world-space axis-aligned bounding box as (min, max) corners - used by the physics broad phase to cheaply reject non-overlapping pairs before running real narrow-phase collision.

PolygonCollider2D(local_vertices, position=Vector(), rotation=0, scale=Vector(1, 1))

Bases: Collider2D

A general convex-polygon Collider2D, backed by a PolygonCollisionShape - unlike Rectangle/CircleCollider2D, its shape isn't derived from scale (a polygon's shape is its vertex list, not a single size), so local_vertices is a required constructor argument instead.

Creates a PolygonCollider2D from local_vertices (centroid- relative, in the shape's own unrotated local space).

Deliberately doesn't go through Collider2D.init's usual collision_shape_cls(position, rotation, scale) pattern - that reuses one scale argument for both this NODE's own transform and the shape constructor's third argument, which works for Rectangle/CircleCollider2D (where that third argument IS a scale) but not here, where PolygonCollisionShape's third argument is the vertex list instead. Passing local_vertices through as if it were scale would silently corrupt this node's own transform.scale into a vector built from two Vectors instead of two floats.

collision_shape = PolygonCollisionShape(position, rotation, local_vertices) instance-attribute

apply_transform()

Syncs the collision shape's position and rotation to the node's current world transform (the polygon's local vertices, and hence its size, don't change with the node's scale).

toggle_debug_visuals()

Adds a PolygonColliderDebug child if this collider (already initialized) has none yet, otherwise removes any existing ones.

PolygonCollisionShape(position, rotation, local_vertices)

Bases: CollisionShape

A general convex collision shape, defined by an ordered, centroid- relative list of local vertices (local_vertices) plus a world position/rotation - RectangleCollisionShape's fixed-4-corner shape is a common enough special case to keep as its own simpler class, but anything else convex (a hexagon, an octagon standing in for a rounded capsule via regular_polygon_vertices, a custom hull) goes through this one instead. Vertices must be wound consistently (order doesn't matter which way, just that it's consistent) and the shape must actually be convex - SAT and the mass formula below both assume it.

Stores local_vertices (centroid-relative, in the shape's own unrotated local space) alongside position/rotation - world-space corners are recomputed from these on every query rather than cached, matching RectangleCollisionShape's approach.

local_vertices = local_vertices instance-attribute

position = position instance-attribute

rotation = rotation instance-attribute

collide_circle(other)

Checks for overlap with a circle: if the circle's center is inside the polygon it's automatically a collision (the closest- boundary-point check below only makes sense for a center outside the polygon - otherwise it'd measure to whichever edge happens to be nearest, which can be much farther away than the circle's own radius, missing the case where a small circle sits deep inside a larger polygon).

collide_point(point)

Checks whether point lies inside the polygon via the SAT containment test.

collide_polygon(other)

Checks for overlap with another convex polygon via SAT.

collide_rectangle(other)

Checks for overlap with a rectangle by delegating to the rectangle's own polygon-collision test.

compute_mass(density)

Standard convex-polygon mass/inertia formula (as used by e.g. Box2D's b2PolygonShape::ComputeMass): triangulates the polygon into a fan from its own centroid and sums each triangle's area and second-moment contribution, rather than assuming a closed-form shape like the circle/box formulas above can.

get_aabb()

The polygon's bounding box: the min/max of its world-space vertices.

Ray2D(origin, direction, scene)

A 2D ray object.

:param origin: The starting position of the ray. :type origin: Vector

:param direction: The direction of the ray.
:type direction: Vector

Normalizes direction and stores it along with origin and the scene the ray will be cast against.

direction = direction.normalized instance-attribute

origin = origin instance-attribute

scene = scene instance-attribute

cast(max_dist=100)

Finds the closest collider in the scene that this ray intersects.

Only considers colliders whose own position is within max_dist of the ray's origin (a cheap broad-phase filter, not a check on the actual intersection point) before running the real intersection test on each.

Returns:

Type	Description
Vector | None	Vector | None: The closest intersection point found, or None if
Vector | None	the ray hits nothing.

intersect(collider)

Dispatches to intersect_circle()/intersect_rectangle() based on collider's (or its collision_shape's) concrete type.

Raises:

Type	Description
ValueError	If collider is not a supported Collider2D/CollisionShape type.

intersect_circle(circle)

Checks for intersection with a circle collider.

:param circle: The checked circle. :type circle: CircleCollider

:returns: The point of intersection (Vector), or None if there is no intersection. :rtype: Vector or None

intersect_rectangle(rect)

Checks for intersection with an axis-aligned rectangle collider (ignores rect.rotation - only correct for an unrotated rectangle, same as this method's previous implementation) via the standard slab method.

:param rect: The rectangle collider. :returns: The point of intersection, or None if there is no intersection.

Raycaster2D(max_distance)

Bases: Node2D

A node that casts a ray from its own world position, facing its own world rotation, every update.

Initializes the node; the ray itself isn't created until on_initialize(), once the node has a world transform to read.

debug_visuals_active = False instance-attribute

max_distance = max_distance instance-attribute

on_initialize()

Creates the ray, facing the node's current world rotation from its current world position.

on_update()

Re-aims the ray at the node's current world transform and casts it.

toggle_debug_visuals()

update_debug_visuals()

RectangleCollider2D(position=Vector(), rotation=0, scale=Vector(1, 1))

Bases: Collider2D

A rectangular Collider2D, backed by a RectangleCollisionShape.

Creates a RectangleCollider2D with the collision shape's size taken directly from scale.

collision_shape instance-attribute

apply_transform()

Syncs the collision shape's position, rotation, and size to the node's current world transform.

toggle_debug_visuals()

Adds a RectangleColliderDebug child if this collider (already initialized) has none yet, otherwise removes any existing ones.

RectangleCollisionShape(position, rotation, size)

Bases: CollisionShape

An oriented (rotatable) rectangular collision shape, defined by a center position, size, and rotation.

Stores the rectangle's position, size, and rotation directly.

position = position instance-attribute

rotation = rotation instance-attribute

size = size instance-attribute

collide_circle(other)

Checks for overlap with a circle by clamping the circle's center onto the rectangle's bounds along each axis to find the closest point on the rectangle, then comparing that distance to the circle's radius.

Returns:

Name	Type	Description
bool	bool	True if the circle overlaps the rectangle.

collide_point(point)

Checks whether point lies inside the rectangle by projecting it onto the rectangle's two (rotated) axes and testing against the rectangle's extent on each.

Returns:

Name	Type	Description
bool	bool	True if the point is inside the rectangle.

collide_polygon(other)

Checks for overlap with a general convex polygon via SAT, treating this rectangle as its own 4-corner polygon.

collide_rectangle(other)

Checks for overlap with another rectangle using the separating axis theorem (SAT): tests both rectangles' face normals as candidate separating axes, and reports a collision only if no axis separates them.

Returns:

Name	Type	Description
bool	bool	True if the rectangles overlap.

compute_mass(density)

A solid wxh box's mass is density * w * h; its moment of inertia about its own center is mass * (w^2 + h^2) / 12.

get_aabb()

The rectangle's bounding box: the min/max of its (possibly rotated) corners.

cast_ray(position, direction, max_distance, scene=None)

Casts a ray.

:param position: The point the ray is cast from. :type position: Vector

:param direction: The direction that the ray is cast in. :type direction: Vector

:param scene: The scene that the ray will be cast in, defaults to the curent scene. :type scene: Scene

regular_polygon_vertices(sides, radius)

Returns sides local vertices (centered on the origin, first vertex pointing along +X) for a regular polygon inscribed in a circle of radius - a convenient way to build a PolygonCollisionShape that approximates a circle/capsule more closely than a box does (e.g. for a rounded-looking limb segment), without needing true curved-edge collision support.