Physics module class. More...

Classes
struct	AABB
	Axis-aligned bounding box using half-open bounds [min, max). More...

Public Types
using	TileSolidCallback = bool ()(const SceneLayerTile pTileLayer, Sint32 iCellX, Sint32 iCellY, Uint32 iCellValue, void* pUserData)
	Callback used by tile-layer sweep/ground checks to decide if one tile is solid.

Public Member Functions
bool	sweepPointOnCollisionSet (Sint32 idCollisionSet, float fStartX, float fStartY, float fDX, float fDY, PhysicsSweepHit *pHit)
	Sweep a point against one Physics collision set.
bool	overlapsSprite (Sprite pS1, float fX1, float fY1, Sprite pS2, float fX2, float fY2, const SDL_FRect *pOverlap=nullptr, ePhysicsCollisionMode eMode=PCM_PIXEL)
	Check overlap between two sprites.
bool	overlapsSprite (Sprite pS1, float fX1, float fY1, const SDL_FRect &rRect, const SDL_FRect pOverlap=nullptr, ePhysicsCollisionMode eMode=PCM_PIXEL)
	Check overlap between a sprite and a rectangle.
bool	overlapsSprite (Sprite *pS1, float fX1, float fY1, float fPX, float fPY, ePhysicsCollisionMode eMode=PCM_PIXEL)
	Check overlap between a sprite and a point.
bool	resolve (SDL_FRect &rSubject, const SDL_FRect &rObstacle)
	Resolve overlap between two rectangular areas.
bool	sweepAABBOnLayerTile (const SDL_FRect &rRectStart, float fDX, float fDY, const SceneLayerTile pSceneLayer, SDL_FRect pRectResolved, bool pHitX=nullptr, bool pHitY=nullptr, bool pGrounded=nullptr, TileSolidCallback fnSolid=nullptr, void pUserData=nullptr)
	Sweep an AABB on a tile layer and resolve collisions (axis separated: X then Y).
bool	isGroundedOnLayerTile (const SDL_FRect &rRect, const SceneLayerTile pSceneLayer, float fProbeDistance=1.0f, TileSolidCallback fnSolid=nullptr, void pUserData=nullptr)
	Ground probe helper against a tile layer.
Sint32	createCollisionSet (const string &sName)
	Create a persistent collision set.
Sint32	closeCollisionSet (Sint32 idCollisionSet)
	Close and destroy a collision set.
Sint32	addColliderRectangle (Sint32 idCollisionSet, float fX, float fY, float fWidth, float fHeight)
	Add an axis-aligned rectangle collider.
Sint32	addColliderCircle (Sint32 idCollisionSet, float fCenterX, float fCenterY, float fRadius)
	Add a circle collider.
Sint32	addColliderEllipse (Sint32 idCollisionSet, float fCenterX, float fCenterY, float fRadiusX, float fRadiusY, float fRotationDeg=0.0f)
	Add an ellipse collider.
Sint32	addColliderSegment (Sint32 idCollisionSet, float fX1, float fY1, float fX2, float fY2)
	Add a segment collider.
Sint32	addColliderPolygon (Sint32 idCollisionSet, const float fVX, const float fVY, Sint32 iNV)
	Add a closed polygon collider.
Sint32	translateCollider (Sint32 idCollisionSet, Sint32 idCollider, float fDX, float fDY)
	Translate one collider in world space.
Sint32	removeCollider (Sint32 idCollisionSet, Sint32 idCollider)
	Remove one collider.
Sint32	clearCollisionSet (Sint32 idCollisionSet)
	Remove all colliders from a collision set.
Sint32	getColliderCount (Sint32 idCollisionSet) const
	Get the number of colliders in a collision set.
bool	info (Sint32 iMode=0) override
	Request Physics module information.

Static Public Member Functions
static bool	integrateVelocity (float &fV, float fA, float fDT)
	Integrate velocity using explicit Euler: v = v + a * dt.
static bool	applyLinearDamping (float &fV, float fDamping, float fDT)
	Apply linear damping to velocity: v = max(0, 1 - damping dt).
static bool	clampVelocity (float &fV, float fMaxV)
	Clamp a velocity value within a maximum magnitude.
static bool	isValidAABB (const AABB &aabb)
	Validate if an AABB contains finite values and non-inverted bounds.
static bool	containsPoint (const AABB &aabb, float fX, float fY)
	Test if a point is inside an AABB using half-open bounds [min, max).
static bool	overlapsAABB (const AABB &aabb1, const AABB &aabb2, SDL_FRect *pOverlap=nullptr)
	Test if two AABBs overlap using half-open bounds [min, max).
static bool	overlapsObjectAABB (const SceneObject pObjA, const SceneObject pObjB, SDL_FRect *pOverlap=nullptr)
	Fast object-object broad phase using cached object AABBs.
static bool	containsObjectPoint (const SceneObject *pObj, float fPX, float fPY)
	Precise point-in-object check using object shape geometry.
static bool	overlapsObject (const SceneObject pObjA, const SceneObject pObjB, ePhysicsCollisionMode eMode=PCM_SHAPE, SDL_FRect *pOverlap=nullptr)
	Object-object overlap with selectable narrow phase.
static bool	overlapsObjectTrigger (const SceneObject pOwnerObj, const SceneShapeData &triggerLocalShape, const SceneObject pOther, ePhysicsCollisionMode eMode=PCM_SHAPE, SDL_FRect *pOverlap=nullptr)
	Trigger-local-shape versus object overlap.
static bool	sweepPointOnObject (const SceneObject pObject, float fStartX, float fStartY, float fDX, float fDY, PhysicsSweepHit pHit)
	Sweep a point against one Scene object shape.
static bool	matchTypeHash (Uint32 iObjectTypeHash, const vector< Uint32 > &vIncludeHashes, const vector< Uint32 > &vExcludeHashes)
	Fast hash filter helper for trigger/object-type matching.

Detailed Description

Physics module class.

Member Typedef Documentation

◆ TileSolidCallback

using CRM64Pro::Physics::TileSolidCallback = bool (*)(const SceneLayerTile* pTileLayer, Sint32 iCellX, Sint32 iCellY, Uint32 iCellValue, void* pUserData)

Callback used by tile-layer sweep/ground checks to decide if one tile is solid.

Parameters

pTileLayer	Tile layer being queried.
iCellX	Tile cell X.
iCellY	Tile cell Y.
iCellValue	Tile GID/value at the queried cell (0 for out-of-bounds).
pUserData	User payload passed through helper call.

Returns: true if the tile should be treated as solid.

Member Function Documentation

◆ integrateVelocity()

bool CRM64Pro::Physics::integrateVelocity	(	float &	fV,
		float	fA,
		float	fDT )

static

Integrate velocity using explicit Euler: v = v + a * dt.

Parameters

fV	Reference to velocity.
fA	Acceleration.
fDT	Delta time in seconds (must be >= 0).

Returns: true if velocity changed.

◆ applyLinearDamping()

bool CRM64Pro::Physics::applyLinearDamping	(	float &	fV,
		float	fDamping,
		float	fDT )

static

Apply linear damping to velocity: v *= max(0, 1 - damping * dt).

Parameters

fV	Reference to velocity.
fDamping	Damping factor in 1/seconds (must be >= 0).
fDT	Delta time in seconds (must be >= 0).

Returns: true if velocity changed.

◆ clampVelocity()

bool CRM64Pro::Physics::clampVelocity	(	float &	fV,
		float	fMaxV )

static

Clamp a velocity value within a maximum magnitude.

Parameters

fV	Reference to the velocity value to be clamped.
fMaxV	The maximum allowed velocity magnitude. Must be >= 0.

Returns: true if the value was clamped, false if unchanged or if fMaxV is invalid.

◆ isValidAABB()

bool CRM64Pro::Physics::isValidAABB ( const AABB & aabb )

static

Validate if an AABB contains finite values and non-inverted bounds.

Parameters

aabb	AABB to validate.

Returns: true if bounds are finite and min<=max on both axes, otherwise false.

◆ containsPoint()

bool CRM64Pro::Physics::containsPoint	(	const AABB &	aabb,
		float	fX,
		float	fY )

static

Test if a point is inside an AABB using half-open bounds [min, max).

Parameters

aabb	AABB to test against.
fX	Point X coordinate in world space.
fY	Point Y coordinate in world space.

Returns: true if point lies inside the half-open AABB, otherwise false.

◆ overlapsAABB()

bool CRM64Pro::Physics::overlapsAABB	(	const AABB &	aabb1,
		const AABB &	aabb2,
		SDL_FRect *	pOverlap = nullptr )

static

Test if two AABBs overlap using half-open bounds [min, max).

Parameters

aabb1	First AABB.
aabb2	Second AABB.
pOverlap	Optional output pointer. When overlap exists, receives intersection rectangle in world space.

Returns: true if AABBs overlap, otherwise false.

Note: Uses half-open bounds semantics [min, max).

◆ overlapsObjectAABB()

bool CRM64Pro::Physics::overlapsObjectAABB	(	const SceneObject *	pObjA,
		const SceneObject *	pObjB,
		SDL_FRect *	pOverlap = nullptr )

static

Fast object-object broad phase using cached object AABBs.

Parameters

pObjA	First object.
pObjB	Second object.
pOverlap	Optional output pointer. When overlap exists, receives intersection rectangle in world space.

Returns: true if both objects are valid and their AABBs overlap, otherwise false.

◆ containsObjectPoint()

bool CRM64Pro::Physics::containsObjectPoint	(	const SceneObject *	pObj,
		float	fPX,
		float	fPY )

static

Precise point-in-object check using object shape geometry.

Parameters

pObj	Object to test.
fPX	Point X coordinate in world space.
fPY	Point Y coordinate in world space.

Returns: true if point is inside object shape, otherwise false.

◆ overlapsObject()

bool CRM64Pro::Physics::overlapsObject	(	const SceneObject *	pObjA,
		const SceneObject *	pObjB,
		ePhysicsCollisionMode	eMode = PCM_SHAPE,
		SDL_FRect *	pOverlap = nullptr )

static

Object-object overlap with selectable narrow phase.

PCM_AABB uses only cached AABB overlap. PCM_SHAPE uses precise per-point shape checks inside the overlap region. PCM_PIXEL currently falls back to PCM_SHAPE when no sprite alpha source is available.

Parameters

pObjA	First object.
pObjB	Second object.
eMode	Overlap mode.
pOverlap	Optional output pointer. Receives AABB intersection when broad-phase overlap exists.

Returns: true if overlap is detected according to selected mode, otherwise false.

◆ overlapsObjectTrigger()

bool CRM64Pro::Physics::overlapsObjectTrigger	(	const SceneObject *	pOwnerObj,
		const SceneShapeData &	triggerLocalShape,
		const SceneObject *	pOther,
		ePhysicsCollisionMode	eMode = PCM_SHAPE,
		SDL_FRect *	pOverlap = nullptr )

static

Trigger-local-shape versus object overlap.

The trigger shape is defined in owner-local coordinates and transformed to world space using owner transform.

Parameters

pOwnerObj	Owner object that defines trigger transform space.
triggerLocalShape	Trigger shape in owner-local coordinates.
pOther	Object tested against trigger shape.
eMode	Overlap mode.
pOverlap	Optional output pointer. Receives trigger/object AABB overlap rectangle when broad-phase overlap exists.

Returns: true if overlap is detected according to selected mode, otherwise false.

◆ sweepPointOnObject()

bool CRM64Pro::Physics::sweepPointOnObject	(	const SceneObject *	pObject,
		float	fStartX,
		float	fStartY,
		float	fDX,
		float	fDY,
		PhysicsSweepHit *	pHit )

static

Sweep a point against one Scene object shape.

Parameters

pObject	Scene object tested as a world-space collider.
fStartX	World X coordinate of the movement start.
fStartY	World Y coordinate of the movement start.
fDX	Horizontal movement in world units.
fDY	Vertical movement in world units.
pHit	Output collision information. Must not be nullptr.

Returns: true when a collision is written to pHit, or false when there is no collision or input is invalid.

Note: A point starting inside the object does not generate a collision.

◆ sweepPointOnCollisionSet()

bool CRM64Pro::Physics::sweepPointOnCollisionSet	(	Sint32	idCollisionSet,
		float	fStartX,
		float	fStartY,
		float	fDX,
		float	fDY,
		PhysicsSweepHit *	pHit )

Sweep a point against one Physics collision set.

Parameters

idCollisionSet	Positive collision-set handle returned by createCollisionSet().
fStartX	World X coordinate of the movement start.
fStartY	World Y coordinate of the movement start.
fDX	Horizontal movement in world units.
fDY	Vertical movement in world units.
pHit	Output collision information. Must not be nullptr.

Returns: true when a collision is written to pHit, or false when there is no collision or input is invalid.

Note: A point starting inside a collider does not generate a collision.

◆ matchTypeHash()

bool CRM64Pro::Physics::matchTypeHash	(	Uint32	iObjectTypeHash,
		const vector< Uint32 > &	vIncludeHashes,
		const vector< Uint32 > &	vExcludeHashes )

static

Fast hash filter helper for trigger/object-type matching.

Parameters

iObjectTypeHash	32-bit type hash for tested object.
vIncludeHashes	Include filter hashes. Empty means include all.
vExcludeHashes	Exclude filter hashes. Matching any excludes the object.

Returns: true if hash passes include/exclude filters, otherwise false.

◆ overlapsSprite() [1/3]

bool CRM64Pro::Physics::overlapsSprite	(	Sprite *	pS1,
		float	fX1,
		float	fY1,
		Sprite *	pS2,
		float	fX2,
		float	fY2,
		const SDL_FRect *	pOverlap = nullptr,
		ePhysicsCollisionMode	eMode = PCM_PIXEL )

Check overlap between two sprites.

Parameters

pS1	Pointer to the first Sprite.
fX1	X position of the first sprite.
fY1	Y position of the first sprite.
pS2	Pointer to the second Sprite.
fX2	X position of the second sprite.
fY2	Y position of the second sprite.
pOverlap	Optional input pointer to a precomputed intersection rectangle used as a cache to speed up math. It is not modified.
eMode	Overlap mode. PCM_AABB performs rectangle overlap only, PCM_PIXEL performs pixel-perfect overlap, PCM_SHAPE is not supported for sprites in this version.

Returns: true if an overlap is detected according to selected mode.

◆ overlapsSprite() [2/3]

bool CRM64Pro::Physics::overlapsSprite	(	Sprite *	pS1,
		float	fX1,
		float	fY1,
		const SDL_FRect &	rRect,
		const SDL_FRect *	pOverlap = nullptr,
		ePhysicsCollisionMode	eMode = PCM_PIXEL )

Check overlap between a sprite and a rectangle.

Parameters

pS1	Pointer to the Sprite.
fX1	X position of the sprite.
fY1	Y position of the sprite.
rRect	Reference to the SDL_FRect defining the overlap area.
pOverlap	Optional input pointer to a precomputed intersection rectangle used as a cache to speed up math. It is not modified.
eMode	Overlap mode. PCM_AABB performs rectangle overlap only, PCM_PIXEL performs pixel-perfect overlap, PCM_SHAPE is not supported for sprites in this version.

Returns: true if an overlap is detected according to selected mode.

◆ overlapsSprite() [3/3]

bool CRM64Pro::Physics::overlapsSprite	(	Sprite *	pS1,
		float	fX1,
		float	fY1,
		float	fPX,
		float	fPY,
		ePhysicsCollisionMode	eMode = PCM_PIXEL )

Check overlap between a sprite and a point.

Parameters

pS1	Pointer to the Sprite.
fX1	X position of the sprite.
fY1	Y position of the sprite.
fPX	X coordinate of the point.
fPY	Y coordinate of the point.
eMode	Overlap mode. PCM_AABB performs sprite bounds test only, PCM_PIXEL performs pixel test, PCM_SHAPE is not supported for sprites in this version.

Returns: true if an overlap is detected according to selected mode.

◆ resolve()

bool CRM64Pro::Physics::resolve	(	SDL_FRect &	rSubject,
		const SDL_FRect &	rObstacle )

Resolve overlap between two rectangular areas.

Note: Not implemented in this version.

Parameters

rSubject	Reference to the subject rectangle (to be moved).
rObstacle	Reference to the static obstacle rectangle.

Returns: true if overlap was resolved.

◆ sweepAABBOnLayerTile()

bool CRM64Pro::Physics::sweepAABBOnLayerTile	(	const SDL_FRect &	rRectStart,
		float	fDX,
		float	fDY,
		const SceneLayerTile *	pSceneLayer,
		SDL_FRect *	pRectResolved,
		bool *	pHitX = nullptr,
		bool *	pHitY = nullptr,
		bool *	pGrounded = nullptr,
		TileSolidCallback	fnSolid = nullptr,
		void *	pUserData = nullptr )

Sweep an AABB on a tile layer and resolve collisions (axis separated: X then Y).

Parameters

rRectStart	Initial world-space rectangle.
fDX	Desired movement on X axis in world units.
fDY	Desired movement on Y axis in world units.
pSceneLayer	Tile layer used as collision map.
pRectResolved	Output resolved rectangle after collision response.
pHitX	Optional output flag set to true when X movement is blocked.
pHitY	Optional output flag set to true when Y movement is blocked.
pGrounded	Optional output flag set when downward movement collides with ground.
fnSolid	Optional solidity callback (default: any non-zero tile is solid, out-of-bounds sides/bottom are solid, above top is non-solid).
pUserData	User payload passed to fnSolid.

Returns: true on valid execution, false on invalid inputs.

Note: Uses edge-sweep traversal across crossed tile columns/rows to avoid tunneling on large deltas.; Under the default solidity rule, value 0 is empty and any non-zero tile occupies its complete cell. Tile image transparency and Tiled per-tile collision geometry are not inspected.; Sweeps exceeding the fixed safety cell budget return false.; Designed for platform/top-down kinematic movement and deterministic fixed-step updates.

◆ isGroundedOnLayerTile()

bool CRM64Pro::Physics::isGroundedOnLayerTile	(	const SDL_FRect &	rRect,
		const SceneLayerTile *	pSceneLayer,
		float	fProbeDistance = 1.0f,
		TileSolidCallback	fnSolid = nullptr,
		void *	pUserData = nullptr )

Ground probe helper against a tile layer.

Parameters

rRect	Object/world rectangle.
pSceneLayer	Tile layer used as collision map.
fProbeDistance	Thickness of the feet probe strip in world units below rect bottom. Typical values: 0.5 to 4.0.
fnSolid	Optional solidity callback (same semantics as sweepAABBOnLayerTile()).
pUserData	User payload passed to fnSolid.

Returns: true if a solid tile overlaps the feet probe strip.

◆ createCollisionSet()

Sint32 CRM64Pro::Physics::createCollisionSet ( const string & sName )

Create a persistent collision set.

Parameters

sName Unique collision-set name. It must be non-empty, shorter than 64 characters and cannot use a reserved prefix.

Returns: Positive collision-set handle on success, or a negative error code on failure.

◆ closeCollisionSet()

Sint32 CRM64Pro::Physics::closeCollisionSet ( Sint32 idCollisionSet )

Close and destroy a collision set.

Parameters

idCollisionSet Positive collision-set handle returned by createCollisionSet().

Returns: 0 on success, or a negative error code on failure.

Note: Unbind the handle from every ParticleEmitter before closing it.

◆ addColliderRectangle()

Sint32 CRM64Pro::Physics::addColliderRectangle	(	Sint32	idCollisionSet,
		float	fX,
		float	fY,
		float	fWidth,
		float	fHeight )

Add an axis-aligned rectangle collider.

Parameters

idCollisionSet	Positive collision-set handle.
fX	World X coordinate of the rectangle top-left corner.
fY	World Y coordinate of the rectangle top-left corner.
fWidth	Rectangle width in world units. Must be greater than 0.
fHeight	Rectangle height in world units. Must be greater than 0.

Returns: Positive collider ID on success, or a negative error code on failure.

◆ addColliderCircle()

Sint32 CRM64Pro::Physics::addColliderCircle	(	Sint32	idCollisionSet,
		float	fCenterX,
		float	fCenterY,
		float	fRadius )

Add a circle collider.

Parameters

idCollisionSet	Positive collision-set handle.
fCenterX	World X coordinate of the circle center.
fCenterY	World Y coordinate of the circle center.
fRadius	Circle radius in world units. Must be greater than 0.

Returns: Positive collider ID on success, or a negative error code on failure.

◆ addColliderEllipse()

Sint32 CRM64Pro::Physics::addColliderEllipse	(	Sint32	idCollisionSet,
		float	fCenterX,
		float	fCenterY,
		float	fRadiusX,
		float	fRadiusY,
		float	fRotationDeg = 0.0f )

Add an ellipse collider.

Parameters

idCollisionSet	Positive collision-set handle.
fCenterX	World X coordinate of the ellipse center.
fCenterY	World Y coordinate of the ellipse center.
fRadiusX	Horizontal radius in world units. Must be greater than 0.
fRadiusY	Vertical radius in world units. Must be greater than 0.
fRotationDeg	Clockwise rotation in degrees around the ellipse center.

Returns: Positive collider ID on success, or a negative error code on failure.

◆ addColliderSegment()

Sint32 CRM64Pro::Physics::addColliderSegment	(	Sint32	idCollisionSet,
		float	fX1,
		float	fY1,
		float	fX2,
		float	fY2 )

Add a segment collider.

Parameters

idCollisionSet	Positive collision-set handle.
fX1	World X coordinate of the first endpoint.
fY1	World Y coordinate of the first endpoint.
fX2	World X coordinate of the second endpoint.
fY2	World Y coordinate of the second endpoint.

Returns: Positive collider ID on success, or a negative error code on failure.

◆ addColliderPolygon()

Sint32 CRM64Pro::Physics::addColliderPolygon	(	Sint32	idCollisionSet,
		const float *	fVX,
		const float *	fVY,
		Sint32	iNV )

Add a closed polygon collider.

Parameters

idCollisionSet	Positive collision-set handle.
fVX	Array containing world X coordinates.
fVY	Array containing world Y coordinates.
iNV	Number of vertices in the range [3, 4096].

Returns: Positive collider ID on success, or a negative error code on failure.

Note: Vertex arrays are copied and may be released after this method returns.

◆ translateCollider()

Sint32 CRM64Pro::Physics::translateCollider	(	Sint32	idCollisionSet,
		Sint32	idCollider,
		float	fDX,
		float	fDY )

Translate one collider in world space.

Parameters

idCollisionSet	Positive collision-set handle.
idCollider	Positive collider ID returned by an add method.
fDX	Horizontal displacement in world units.
fDY	Vertical displacement in world units.

Returns: 0 on success, or a negative error code on failure.

◆ removeCollider()

Sint32 CRM64Pro::Physics::removeCollider	(	Sint32	idCollisionSet,
		Sint32	idCollider )

Remove one collider.

Parameters

idCollisionSet	Positive collision-set handle.
idCollider	Positive collider ID returned by an add method.

Returns: 0 on success, or a negative error code on failure.

◆ clearCollisionSet()

Sint32 CRM64Pro::Physics::clearCollisionSet ( Sint32 idCollisionSet )

Remove all colliders from a collision set.

Parameters

idCollisionSet Positive collision-set handle.

Returns: 0 on success, or a negative error code on failure.

◆ getColliderCount()

Sint32 CRM64Pro::Physics::getColliderCount ( Sint32 idCollisionSet ) const

Get the number of colliders in a collision set.

Parameters

idCollisionSet Positive collision-set handle.

Returns: Collider count greater than or equal to 0, or a negative error code on failure.

◆ info()

bool CRM64Pro::Physics::info ( Sint32 iMode = 0 )

override

Request Physics module information.

Logs Physics information using the default log.

Parameters

iMode Reserved for future use. Pass 0.

Returns: true on success, or false on failure.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ TileSolidCallback

Member Function Documentation

◆ integrateVelocity()

◆ applyLinearDamping()

◆ clampVelocity()

◆ isValidAABB()

◆ containsPoint()

◆ overlapsAABB()

◆ overlapsObjectAABB()

◆ containsObjectPoint()

◆ overlapsObject()

◆ overlapsObjectTrigger()

◆ sweepPointOnObject()

◆ sweepPointOnCollisionSet()

◆ matchTypeHash()

◆ overlapsSprite() [1/3]

◆ overlapsSprite() [2/3]

◆ overlapsSprite() [3/3]

◆ resolve()

◆ sweepAABBOnLayerTile()

◆ isGroundedOnLayerTile()

◆ createCollisionSet()

◆ closeCollisionSet()

◆ addColliderRectangle()

◆ addColliderCircle()

◆ addColliderEllipse()

◆ addColliderSegment()

◆ addColliderPolygon()

◆ translateCollider()

◆ removeCollider()

◆ clearCollisionSet()

◆ getColliderCount()

◆ info()