constants.h

// SPDX-FileCopyrightText: 2026 Erin Catto
// SPDX-License-Identifier: MIT

#pragma once

#include "math_functions.h"

/**
 * @defgroup constants Constants
 * Constants. Some can be configured. I try to include most internal constants here for convenience
 * and clarity. This is why they are not all configurable.
 * @{
 */

/// Used to detect bad values. Positions greater than about 16km will have precision problems in
/// single precision, so 100km as a limit should be fine in all cases. In large world mode the
/// broad-phase starts to have excessive padding at 10,000km, so a value beyond 100,000km is
/// extreme.
#if defined( BOX2D_DOUBLE_PRECISION )
#define B2_HUGE ( ( 100000.0f * 1000.0f ) * b2_lengthUnitsPerMeter )
#else
#define B2_HUGE ( ( 100.0f * 1000.0f ) * b2_lengthUnitsPerMeter )
#endif

/// Maximum parallel workers. Used for some fixed size arrays.
#define B2_MAX_WORKERS 32

/// Maximum number of tasks queued per world step. b2EnqueueTaskCallbackFcn will never be called
/// more than this per world step. This is related to B2_MAX_WORKERS. With 32 workers, the maximum
/// observed task count is 130. This allows an external task system to use a fixed size array for
/// Box2D tasks, which may help with creating stable user task pointers.
#define B2_MAX_TASKS 256

/// Maximum number of colors in the constraint graph. Constraints that cannot find a color are added
/// to the overflow set, which is solved single-threaded. The compound barrel benchmark has minor
/// overflow with 24 colors
#define B2_GRAPH_COLOR_COUNT 24

/// A small length used as a collision and constraint tolerance. Usually it is chosen to be
/// numerically significant, but visually insignificant. In meters. Normally this is 0.5cm.
/// @warning modifying this can have a significant impact on stability
#define B2_LINEAR_SLOP ( 0.005f * b2_lengthUnitsPerMeter )

/// Maximum number of simultaneous worlds that can be allocated
#ifndef B2_MAX_WORLDS
#define B2_MAX_WORLDS 128
#endif

/// Maximum length of the body name. Can be 0 if you don't need names.
#ifndef B2_NAME_LENGTH
#define B2_NAME_LENGTH 10
#endif

/// The maximum rotation of a body per time step. This limit is very large and is used to prevent
/// numerical problems. You shouldn't need to adjust this.
/// @warning increasing this to 0.5f * B2_PI or greater will break continuous collision.
#define B2_MAX_ROTATION ( 0.25f * B2_PI )

/// Box2D uses limited speculative collision. This reduces jitter. Normally this is 2cm.
/// @warning modifying this can have a significant impact on performance and stability
#define B2_SPECULATIVE_DISTANCE ( 4.0f * B2_LINEAR_SLOP )

/// The default contact recycling distance.
#define B2_CONTACT_RECYCLE_DISTANCE ( 10.0f * B2_LINEAR_SLOP )

/// The default contact recycling world angle threshold. 0.98 ~= 11.5 degrees
#define B2_CONTACT_RECYCLE_COS_ANGLE ( 0.98f )

/// This is used to fatten AABBs in the dynamic tree. This allows proxies to move by a small amount
/// without triggering a tree adjustment. This is in meters. Normally this is 5cm. This has been
/// tuned on benchmarks and I found that keeping the margin small improves performance by reducing
/// the number of contacts. I used to keep this larger in the past to avoid tree insert and remove
/// churn. But the broad-phase no longer works that way and now uses a two-phase refit and rebuild
/// setup similar to Jolt.
/// @warning modifying this can have a significant impact on performance
#define B2_MAX_AABB_MARGIN ( 0.05f * b2_lengthUnitsPerMeter )

/// For small objects the margin is limited to this fraction times the maximum extent
#define B2_AABB_MARGIN_FRACTION 0.125f

/// The time that a body must be still before it will go to sleep. In seconds.
#define B2_TIME_TO_SLEEP 0.5f

/// The maximum number of restitution iterations. Needed to avoid a solver overflow.
#define B2_MAX_RESTITUTION_ITERATIONS 63

/** @} */