Phaser Box2D

Creates a new physics body in the specified world based on the provided body definition. The body is added to the appropriate solver set based on its type and state. The function initializes the body's physical properties including position, rotation, velocities, damping values and other simulation parameters.

• Error: Throws assertion errors if:
  • Position vector is invalid
  • Rotation value is invalid
  • Linear velocity vector is invalid
  • Angular velocity is invalid
  • Linear damping is invalid or negative
  • Angular damping is invalid or negative
  • Sleep threshold is invalid or negative
  • Gravity scale is invalid

Destroys a body and all associated joints, contacts, shapes, and chains in the physics world. The function cleans up all resources and removes the body from the simulation system.

• Error: Throws assertion errors if body indices are invalid during removal

Retrieves the current number of contacts associated with the specified body. The function first validates the world reference before accessing the body's contact count.

Retrieves contact data for a specified body. For each active contact, stores the shape IDs of both bodies involved and the contact manifold. Only stores contacts that have the touching flag set.

• Error: If the world is locked or invalid

For bodies with no shapes, returns an AABB containing only the body's position. For bodies with shapes, computes the union of AABBs of all shapes attached to the body.

Retrieves the current position component of a body's transform from the physics world. The position is returned as a b2Vec2 representing the body's location in world space.

Retrieves the rotation component (q) from the body's transform. The returned b2Rot object represents the body's angular orientation in 2D space.

Retrieves the current transform (position and rotation) of a physics body from the specified Box2D world using the body's identifier.

• position {b2Vec2} The position vector (x, y)
• rotation {b2Rot} The rotation values (c, s)

Takes a point given in world coordinates and converts it to the body's local coordinate system by applying the inverse of the body's transform.

Takes a point given in body-local coordinates and converts it to world coordinates using the body's current transform (position and rotation).

Takes a vector defined in world coordinates and transforms it to be relative to the body's local coordinate system by applying the inverse of the body's rotation.

Transforms a vector from the body's local coordinate system to the world coordinate system. This operation only performs rotation (not translation) using the body's current rotation matrix.

Sets the position and rotation of a body, updating its transform and associated shape AABBs. The function updates the body's center, handles broad-phase movement, and adjusts collision bounds.

• Error: Throws assertion error if:
  • The position vector is invalid
  • The body ID is invalid
  • The world is locked
  • The rotation (if provided) is invalid

Retrieves the current linear velocity of a body from its state in the physics world. If the body state cannot be found, returns a zero vector. Linear velocity is often used for calculations (damping, direction, etc) and must be cloned to avoid unwanted effects in the Physics engine.

Retrieves the current angular velocity of a body from its state in the physics world. Angular velocity represents how fast the body is rotating.

Sets the linear velocity of a body. If the body is static, the function returns without making changes. If the new velocity has a non-zero magnitude, the body will be awakened. The function will return early if the body state cannot be retrieved.

Sets the angular velocity of a body. If the body is static or has fixed rotation, the function returns without making changes. The body is woken up if a non-zero angular velocity is set.

Applies a force at a world point to a body. If the force is not applied at the center of mass, it will generate a torque and affect angular motion.

Applies a force to the center of mass of a body. If the body is sleeping, it can optionally be woken up. The force is only applied if the body is in the awake set.

Adds the specified torque to the body's total torque. If the wake parameter is true and the body is sleeping, it will be awakened. The torque is only applied if the body is in the awake set.

Applies a linear impulse to a body at a specified world point, affecting both its linear and angular velocities.

• Error: Throws an assertion error if the body's local index is invalid

Applies a linear impulse to the center of mass of a body. If the body is sleeping, it can optionally be woken up.

Applies an angular impulse to a body, affecting its angular velocity. The impulse is scaled by the body's inverse inertia.

• Error: Throws an assertion error if the body ID is invalid or if the body revision doesn't match

Retrieves the body type (static, kinematic, or dynamic) for a given body ID by looking up the body in the physics world using the provided identifier.

Updates a body's type and handles all necessary simulation changes including:

• Destroying existing contacts
• Waking the body and connected bodies
• Unlinking and relinking joints
• Transferring the body between solver sets
• Updating broad-phase proxies
• Recalculating mass data If the body is disabled or the type is unchanged, minimal processing occurs. Special handling exists for transitions to/from static body type.

Associates arbitrary user data with a physics body. The user data can be retrieved later and can be of any type. The body is located using its world identifier and the user data is stored directly on the body object.

Retrieves the custom user data that was previously attached to the specified body. The function first gets the world from the body ID, then retrieves the full body object, and finally returns its user data.

Retrieves the mass value from a body's simulation data by accessing the world and body objects using the provided body identifier.

Retrieves the rotational inertia value from a body's simulation data using the body's ID. The inertia tensor represents the body's resistance to rotational acceleration.

Returns a copy of the body's local center of mass position vector. The local center is expressed in the body's local coordinate system.

Returns a copy of the body's center of mass position in world coordinates. The returned vector is a clone of the internal state, preventing external modification of the body's actual center position.

Sets the mass properties of a body including mass, rotational inertia, and center of mass. The function updates both the primary mass properties and derived values like inverse mass.

• Error: Throws assertion error if mass or rotationalInertia are invalid or negative, or if the center vector is invalid

Retrieves the mass properties of a body, including its total mass, center of mass position, and rotational inertia.

• mass: The total mass of the body
• center: A b2Vec2 representing the local center of mass
• rotationalInertia: The rotational inertia about the local center of mass

This function retrieves the body from the world using its ID and updates its mass data properties (mass, center of mass, and rotational inertia) based on the shapes attached to it. If the world cannot be accessed, the function returns without performing any operations.

Sets the linear damping coefficient for a body, which reduces its linear velocity over time. Linear damping is used to simulate air resistance or fluid friction.

• Error: Throws an assertion error if linearDamping is invalid or negative.

Returns the linear damping coefficient that reduces the body's linear velocity. Linear damping is used to reduce the linear velocity of the body in the absence of forces. The damping parameter can be used to simulate fluid/air resistance.

Sets the angular damping coefficient for a body, which reduces its angular velocity over time. Angular damping is a value between 0 and infinity that reduces the body's angular velocity.

• Error: Throws an assertion error if angularDamping is invalid or negative.

Returns the angular damping coefficient that reduces the body's angular velocity over time. Angular damping is specified in the range [0,1].

Sets a scale factor that modifies the effect of gravity on a specific body. A value of 1.0 indicates normal gravity, 0.0 indicates no gravity, and negative values reverse the effect of gravity on the body.

• Error: Throws an assertion error if bodyId is invalid or if gravityScale is not a valid number.

Gets the gravity scale of a body.

• Error: Throws an assertion error if the bodyId is invalid.

Determines if a body is currently in the awake set by checking its set index against the b2_awakeSet type. Bodies in the awake set are actively participating in the simulation.

Controls whether a physics body is awake (active) or asleep (inactive). When setting a body to sleep, it will split islands if there are pending constraint removals. When waking a body, it will be moved from the sleeping set to the awake set.

Determines if a physics body is enabled by checking if it belongs to the disabled set. A disabled body does not participate in collision detection or dynamics simulation.

Returns whether the specified body has sleep enabled. When sleep is enabled, the body can automatically enter a sleep state when it becomes inactive.

Sets the minimum velocity threshold that determines when a body can transition to a sleeping state. When a body's velocity falls below this threshold, it becomes eligible for sleeping.

Returns the minimum speed threshold below which a body can be put to sleep to optimize simulation performance.

Enables or disables sleep capability for a specific body. When sleep is disabled, the body will be woken if it was sleeping.

• Error: If the world associated with the bodyId is not found

Disables a body in the physics simulation by removing it from its current solver set and moving it to the disabled set. The function removes all contacts associated with the body, removes it from any island it belongs to, destroys shape proxies in the broad phase, and transfers associated joints to the disabled set.

• Error: Throws if the world is locked or invalid

Enables a previously disabled body in the physics world. When enabled, the body's shapes are added to the broad-phase collision system, and its joints are reconnected to the simulation. The body is moved from the disabled set to either the static set or awake set based on its type.

• Error: Throws an assertion error if joint connectivity validation fails

Sets the fixed rotation state of a body. When enabled, the body will not rotate and any existing angular velocity is cleared. The body's mass data is updated to reflect the change in rotational constraints.

Checks whether a body has fixed rotation enabled. When fixed rotation is enabled, the body will not rotate in response to torques or collisions.

Sets whether a body should be treated as a bullet for continuous collision detection. Bullet bodies are designed for fast moving objects that require more precise collision detection.

Retrieves the bullet status of a body from the physics simulation. Bullet bodies undergo continuous collision detection for improved accuracy with fast-moving objects.

Enables or disables hit event detection for all shapes attached to a body.

Returns the total count of shapes currently attached to the specified body in the physics world.

Retrieves all shapes attached to the specified body by traversing the linked list of shapes starting from the body's headShapeId. Each shape ID is stored in the provided shapeArray and the total count is returned. If shapeArray is already large enough we can avoid the overhead of growing the array.

Returns the total count of joints that are connected to the specified body.

Retrieves the IDs of all joints connected to the specified body, up to the given capacity. The joint IDs are stored in the provided jointArray. The function traverses the body's joint list and copies each joint's ID information including the index, world ID and revision.

Sets the global scaling factor that defines how many length units in the physics simulation correspond to one meter in the real world. This affects all subsequent physics calculations in the Box2D engine.

Returns the value of b2_lengthUnitsPerMeter, which defines the conversion factor between physics simulation units and real-world meters.

This function sets the global assertion handler used by Box2D for runtime checks. The assertion handler is called when a Box2D assertion fails.

This function creates and returns a new b2Version object initialized with Box2D version 3.0.0

This function is intended to set custom memory allocation and deallocation functions for Box2D. However, in the Phaser Box2D JS implementation, this functionality is not supported and will only generate a warning message.

• Warning: Outputs a console warning indicating lack of support

This function is a stub that warns users that byte count tracking is not supported in the JavaScript implementation of Box2D for Phaser.

This function creates a timer object but is not supported in the Phaser Box2D JS implementation. When called, it issues a console warning about lack of support.

This is a stub function that exists for compatibility with Box2D but is not implemented in the Phaser Box2D JS port. It logs a warning when called.

• Warning: Logs a console warning that the function is not supported

This function is a stub that warns that millisecond timing is not supported in the Phaser Box2D JS implementation.

• Warning: Console warning indicating lack of support.

This function returns the elapsed milliseconds from a Box2D timer object and resets it. In the JavaScript implementation for Phaser Box2D, this functionality is not supported and will trigger a warning.

• Warning: Logs a console warning that this function is not supported

This function is a stub that issues a warning message when called, as the sleep functionality is not supported in the Phaser Box2D JS implementation.

This function serves as a placeholder for Box2D's b2Yield functionality, which is not supported in the Phaser Box2D JS implementation. When called, it emits a warning to the console.

Creates a debug drawing interface for Box2D that renders shapes to a canvas context.
The canvas is automatically sized to 1280x720 or 720x1280 based on window orientation.
All coordinates are transformed from Box2D world space to screen space.
This feature isn't meant for production. It is purely for debugging and testing. The code is not optimized, stable or extensible. Implement your own drawing code for production.

• Polygons (outlined and filled)
• Circles (outlined and filled)
• Capsules (outlined and filled)
• Images mapped to shapes
• Line segments
• Points
• Transforms

Creates an animation loop using requestAnimationFrame that tracks timing information and FPS. The callback is invoked each frame with the time delta, total time, and current FPS. Frame delta time is capped at 100ms to avoid large time steps.

Attaches an image to the last shape of a Box2D body. The function loads a PNG image asynchronously and sets up drawing parameters including offset, scale, and source rectangle coordinates. The image is stored in the shape's properties for later rendering.

Converts screen/canvas coordinates to world space coordinates in the Box2D physics system.

// Convert mouse click position to world coordinates
const worldPos = ConvertScreenToWorld(myCanvas, 30, mousePos);

Transforms a position from world space to screen space, taking into account the canvas dimensions, aspect ratio, and zoom level. The function maps the world coordinates to normalized coordinates (0-1) and then scales them to screen pixels.

Calculates an intermediate transform by linearly interpolating between two states defined in a sweep motion. The resulting transform accounts for both translation and rotation, adjusted by the local center offset.

Calculates the minimum distance between two line segments defined by their endpoints.

• fraction1: {number} Parameter along segment 1 for closest point (0-1)
• fraction2: {number} Parameter along segment 2 for closest point (0-1)
• distanceSquared: {number} Square of the minimum distance between segments

• Error: Throws assertion error if count exceeds B2_MAX_POLYGON_VERTICES

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

Computes the distance between two convex shapes using the GJK (Gilbert-Johnson-Keerthi) algorithm.

• pointA: Closest point on shape A
• pointB: Closest point on shape B
• distance: Distance between the shapes
• iterations: Number of iterations performed
• simplexCount: Number of simplexes stored

Uses an iterative algorithm to determine if and when two convex shapes will collide during a linear motion. Shape B is translated while shape A remains stationary. The algorithm uses support points and simplexes to determine the closest points between the shapes.

Computes when two moving shapes first collide during their motion sweeps. Uses conservative advancement and binary search to find the first time of impact or determine that no impact occurs during the time interval.

• state: The termination state (Unknown, Failed, Overlapped, Hit, Separated)
• t: Time of impact (between 0 and tMax)

• Error: Throws assertion error if input sweeps are not normalized

Sets the target length of a distance joint. The length value is automatically clamped between b2_linearSlop and B2_HUGE. After setting the length, the joint's impulse values are reset to zero.

• Error: Throws if the joint type is not b2_distanceJoint.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

Returns the current length of a distance joint. The joint must be of type b2_distanceJoint.

• Error: Throws an error if the joint is not of type b2_distanceJoint.

Sets the enable/disable state of the limit constraint for a distance joint. The joint must be of type b2_distanceJoint or an error will occur.

• Error: Throws an error if the joint type is not b2_distanceJoint.

• Error: Throws an error if the joint is not a distance joint.

Sets the minimum and maximum length constraints for a distance joint. The values are clamped between b2_linearSlop and B2_HUGE. The function resets all impulse values to zero after updating the length range.

• Error: If the joint type is not b2_distanceJoint

Gets the minimum length of a distance joint.

• Error: If the joint type is not b2_distanceJoint.

Gets the maximum length of a distance joint.

• Error: If the joint is not of type b2_distanceJoint.

Calculates the current distance between the two anchor points of a distance joint in world coordinates. The function transforms the local anchor points of both bodies to world coordinates and computes the distance between them.

• Error: Returns 0 if the world is locked

Sets the spring behavior state of a distance joint. When enabled, the joint acts like a spring between two bodies. When disabled, the joint maintains a fixed distance between the connected bodies.

• Error: Throws an error if the joint is not of type b2_distanceJoint.

Returns the state of the spring enable flag for the specified distance joint. The function validates that the joint is of type b2_distanceJoint before accessing the spring enable property.

• Error: Throws an error if the joint is not of type b2_distanceJoint.

Sets the spring oscillation frequency for a distance joint. The frequency determines how quickly the spring oscillates when disturbed from equilibrium.

• Error: Throws an error if the joint is not a distance joint.

Sets the damping ratio parameter for a distance joint's spring mechanism. The joint must be of type b2_distanceJoint.

• Error: Throws if the joint type is not b2_distanceJoint

Gets the hertz frequency parameter of a distance joint.

• Error: If the joint is not a distance joint or the jointId is invalid.

Gets the damping ratio of a distance joint.

• Error: If the joint is not a distance joint or the jointId is invalid.

Enables or disables the motor on a distance joint. When the motor state changes, the motor impulse is reset to zero.

• Error: If the joint is not a distance joint type

• Error: Throws an error if the joint is not a distance joint.

Sets the motor speed for a distance joint.

• Error: Throws if the joint is not a distance joint type.

Gets the motor speed of a distance joint.

• Error: If the joint is not a distance joint or the joint ID is invalid.

Calculates the motor force by dividing the joint's motor impulse by the inverse time step (inv_h). The joint must be of type b2_distanceJoint.

• Error: Throws if the joint type is not b2_distanceJoint.

Sets the maximum motor force for a distance joint.

• Error: Throws if the joint is not a distance joint type.

Gets the maximum motor force of a distance joint.

• Error: If the joint is not a distance joint or the joint ID is invalid.

Creates a b2DynamicTree data structure used for efficient spatial partitioning. The tree is initialized with a pre-allocated pool of nodes linked in a free list.

• Initial node capacity of 16
• Empty root (B2_NULL_INDEX)
• Initialized node array with parent/next pointers
• All nodes set to height -1
• Free list starting at index 0
• Zero proxy count
• Null leaf indices and centers
• Zero rebuild capacity

Clears the nodes, leaf indices, and leaf centers arrays of the dynamic tree, effectively destroying the tree's data structure.

Creates a proxy in a dynamic tree for collision detection. The proxy is added as a leaf node.

• Error: Throws assertion error if AABB bounds are outside valid range

Removes a leaf node from the tree, frees the node's memory, and decrements the proxy count. The proxy must be a valid leaf node in the tree.

• Error: Throws an assertion error if:
  • proxyId is out of bounds
  • the node is not a leaf
  • the tree has no proxies

Returns the number of proxies currently stored in the dynamic tree by accessing the proxyCount property.

Updates the position of a proxy in the dynamic tree by removing and reinserting it with a new AABB.

• Error: Throws assertion errors if:
  • The AABB is invalid
  • The AABB dimensions exceed B2_HUGE
  • The proxyId is out of bounds
  • The node at proxyId is not a leaf node

Updates a proxy's AABB in the dynamic tree and rebalances the tree structure by enlarging parent nodes' AABBs as needed.

• Error: Throws assertion errors if:
  • The AABB is invalid
  • The AABB dimensions exceed B2_HUGE
  • The proxyId is out of bounds
  • The node is not a leaf
  • The new AABB is contained within the old one

Returns the height of the specified dynamic tree by accessing the height property of the root node. The height represents the maximum number of levels from the root to any leaf node.

Computes the sum of all internal node perimeters (excluding leaves and root) divided by the root node perimeter. This ratio provides a measure of the tree's spatial organization.

Performs validation checks on a b2DynamicTree data structure to ensure its internal state is consistent. This is typically used for debugging and testing purposes.

Iterates through all non-leaf nodes in the tree and calculates the absolute height difference between their child nodes. Returns the largest height difference found.

Rebuilds a dynamic tree from the bottom up by iteratively combining nodes with the lowest perimeter cost. The function first identifies all leaf nodes, then pairs them based on minimum combined AABB perimeter, creating parent nodes until a single root node remains.

Updates the axis-aligned bounding boxes (AABBs) of all nodes in the tree by subtracting the newOrigin vector from both their lower and upper bounds.

Calculates the memory footprint by summing:

• Base object properties
• Node array storage
• Rebuild capacity storage

Queries a dynamic tree to find all nodes that overlap with the given AABB and match the category mask bits. Uses a stack-based traversal to efficiently search the tree structure.

Traverses the dynamic tree and finds all leaf nodes that intersect with the input ray. For each intersection, calls the callback function which can control continuation of the search. Uses an AABB overlap test and separating axis test to efficiently cull branches.

Performs a shape cast query against nodes in a dynamic tree, testing for overlaps between a moving shape and static shapes in the tree.

Rebuilds a dynamic tree by collecting all leaf nodes and reconstructing the tree structure. The function deallocates internal nodes during traversal and builds a new balanced tree from the collected leaf nodes.

Checks if a ray cast input is valid by verifying:

• The origin vector is valid
• The translation vector is valid
• The maxFraction is a valid number
• The maxFraction is between 0 and B2_HUGE(exclusive)

Creates a b2Polygon from a convex hull. If the hull has fewer than 3 points, returns a square shape. The function computes the polygon's vertices, edge normals, and centroid. Each edge normal is a unit vector perpendicular to the corresponding edge.

• Error: Throws an assertion error if the hull is invalid

Creates a polygon shape from a hull with specified radius and transform

• Error: Throws assertion error if hull validation fails

Creates a square polygon by calling b2MakeBox with equal dimensions. The square is centered at the origin with sides of length 2h.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

Creates a rectangular polygon shape centered at the origin with specified half-widths. The vertices are arranged counter-clockwise starting from the bottom-left corner. The shape includes pre-computed normals for each edge.

• 4 vertices at (-hx,-hy), (hx,-hy), (hx,hy), (-hx,hy)
• 4 normals pointing outward from each edge
• radius of 0
• centroid at (0,0)

• Error: Throws an assertion error if hx or hy are not valid positive numbers

Creates a rounded box shape by generating a box with specified dimensions and corner radius.

Creates a b2Polygon representing a rectangle with the given dimensions. The box is centered at the specified position and rotated by the given angle. The resulting polygon includes 4 vertices, 4 normals, and has its centroid set to the center position.

Applies a rigid body transformation to a polygon by:

1. Transforming each vertex using the full transform
2. Rotating each normal vector using only the rotation component
3. Transforming the centroid using the full transform

Calculates the mass, center of mass, and rotational inertia for a circle shape with given density. The rotational inertia is computed about the center of mass using the parallel axis theorem when the circle's center is offset from the origin.

• mass: The total mass of the circle
• center: The center of mass (copied from shape.center)
• rotationalInertia: The rotational inertia about the center of mass

Computes mass properties for a capsule shape, including total mass, center of mass, and rotational inertia. A capsule consists of a rectangle with semicircles at both ends.

• mass: The total mass of the capsule
• center: A b2Vec2 representing the center of mass
• rotationalInertia: The moment of inertia about the center of mass

Computes mass properties for a polygon shape, including mass, center of mass, and rotational inertia. Handles special cases for 1-vertex (circle) and 2-vertex (capsule) polygons. For polygons with 3 or more vertices, calculates properties using triangulation.

• mass: Total mass of the shape
• center: Center of mass as b2Vec2
• rotationalInertia: Moment of inertia about the center of mass

• Error: Throws assertion error if shape.count is 0 or exceeds B2_MAX_POLYGON_VERTICES

Calculates the AABB by transforming the circle's center point using the provided transform and extending the bounds by the circle's radius in each direction.

Calculates the minimum and maximum bounds of a capsule after applying a transform. The AABB is computed by transforming the capsule's center points and extending the bounds by the capsule's radius in all directions.

Computes the Axis-Aligned Bounding Box (AABB) for a polygon shape after applying a transform. The AABB includes the polygon's radius in its calculations.

Transforms the segment's endpoints using the provided transform, then creates an AABB that encompasses the transformed segment by finding the minimum and maximum coordinates of the transformed endpoints.

Tests if a point lies within a circle by comparing the squared distance between the point and circle's center against the circle's squared radius.

A capsule is defined by two end centers (center1 and center2) and a radius. The function calculates if the given point lies within the capsule by:

1. Testing if the capsule has zero length (centers are identical)
2. If not, finding the closest point on the line segment between centers
3. Checking if the distance from the test point to the closest point is within the radius

Tests if a point lies inside a polygon shape by calculating the minimum distance between the point and the polygon.

Calculates the intersection point between a ray and a circle shape. Returns early with no hit if the ray length is 0 or if the ray passes outside the circle radius.

• hit: boolean whether the ray intersects the circle
• point: b2Vec2 point of intersection if hit is true
• normal: b2Vec2 surface normal at intersection point if hit is true
• fraction: number intersection distance as a fraction of ray length if hit is true

Performs a ray cast against a capsule shape. A capsule is defined by two centers and a radius. If the capsule length is near zero, it degrades to a circle ray cast.

• fraction: number intersection distance as a fraction of ray length
• point: b2Vec2 point of intersection
• normal: b2Vec2 surface normal at intersection
• hit: boolean whether an intersection occurred

Performs a ray cast against a line segment, determining if and where the ray intersects the segment. For one-sided segments, intersections are only detected from one side based on a cross product test.

Performs a ray cast against a polygon shape, detecting intersection points and normals. For non-zero radius polygons, converts the ray cast into a shape cast operation.

• hit: boolean indicating if intersection occurred
• point: intersection point (if hit is true)
• normal: surface normal at intersection (if hit is true)
• fraction: fraction of translation where intersection occurred (if hit is true)

• Error: Throws assertion error if input ray is invalid

Performs shape casting between a circle and a set of points with radius.

Performs shape casting for a capsule shape against a set of points.

Performs a shape cast operation between a segment and another shape. The function creates proxies for both shapes, sets up their initial transforms, and performs the cast operation using the specified translation and maximum fraction.

Performs shape casting between a polygon shape and a set of points, checking for collisions along a translation path.

Computes the convex hull of a set of 2D points. The function:

• Filters duplicate points within a tolerance
• Finds extreme points to establish initial hull edges
• Recursively adds points to build the complete hull
• Removes collinear/near-collinear points from final hull

• Error: If count < 3 or count > B2_MAX_POLYGON_VERTICES

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

Validates that a hull meets the requirements for a valid convex polygon:

• Has between 3 and B2_MAX_POLYGON_VERTICES points
• Points are in counter-clockwise order
• All points are behind the edges
• No collinear points within b2_linearSlop tolerance

• Warning: Console warnings are issued explaining validation failures

Creates and returns a new b2DistanceJointDef object initialized with specific default values. The length is set to 1 unit and the maxLength is set to B2_HUGE. All other properties of the joint definition retain their default values from the b2DistanceJointDef constructor.

• length set to 1
• maxLength set to B2_HUGE
• all other properties at their default values

Initializes a new b2MotorJointDef with common default values. The joint definition includes preset values for maximum force, maximum torque, and correction factor while using default values for linear and angular offsets.

• maxForce: 1
• maxTorque: 1
• correctionFactor: 0.3
• linearOffset: (0,0)
• angularOffset: 0

Creates and returns a new b2MouseJointDef object initialized with default values for frequency (hertz), damping ratio, and maximum force parameters.

• hertz = 4
• dampingRatio = 1
• maxForce = 1

Creates and returns a new b2PrismaticJointDef instance with localAxisA initialized to a unit vector pointing along the x-axis (1,0). All other properties retain their default values from the b2PrismaticJointDef constructor.

Creates and initializes a new b2RevoluteJointDef with default values. Sets the drawSize property to 0.25 for visualization purposes.

Creates and returns a new b2WeldJointDef object initialized with default values. A weld joint essentially glues two bodies together at a reference point.

• localAnchorA: b2Vec2(0,0)
• localAnchorB: b2Vec2(0,0)
• referenceAngle: 0
• stiffness: 0
• damping: 0

Creates and returns a new b2WheelJointDef with common default values. The joint's local axis is set to point upward, and spring behavior is enabled with standard frequency and damping values.

• localAxisA set to (0,1)
• enableSpring set to true
• hertz set to 1
• dampingRatio set to 0.7

• Error: Throws assertion error if world is locked, bodies are invalid, or length <= 0

• Error: If the world is locked when attempting to create the joint

Creates a mouse joint between two bodies at a specified target point. The joint transforms the target point into local coordinates for both bodies and initializes the joint properties including frequency, damping ratio, and maximum force.

• Error: Throws an assertion error if the world is locked

• Error: If the world is locked

Creates a prismatic joint between two bodies in a Box2D world. A prismatic joint constrains two bodies to move relative to each other along a specified axis.

Creates a weld joint between two bodies in a Box2D world.

• Error: Throws an assertion error if the world is locked

Creates a wheel joint between two bodies in a Box2D world. A wheel joint provides two degrees of freedom: translation along a specified axis and rotation about an orthogonal axis. The joint can be configured with a spring and damper mechanism, translation limits, and a motor.

• Error: Throws an assertion error if the world is locked

Destroys a joint in the physics world. If the world is locked (e.g. during collision detection or integration), the function will return without destroying the joint. The function internally calls b2DestroyJointInternal to handle the actual joint destruction.

• Error: Throws an assertion error if attempting to destroy a joint in a locked world

Retrieves the joint type from the world using the provided joint ID. The function first gets the world reference from the joint ID, then retrieves the full joint object to access its type property.

This function retrieves the identifier of the first body (body A) that is connected to the specified joint. The joint must exist in the world referenced by the jointId.

This function retrieves the identifier of the second body (body B) that is connected to the specified joint. The joint must exist in the world referenced by the jointId.

Retrieves the local anchor point A from a joint's simulation data. The anchor point is expressed in the local coordinate system of body A.

Retrieves the local anchor point B of a joint, which represents the connection point on the second body (body B) in that body's local coordinate system.

When enabled, the bodies connected by the joint can collide with each other. When disabled, collisions between the connected bodies are filtered out. The function updates the broadphase when enabling collisions and destroys existing contacts between the bodies when disabling collisions.

Gets the collideConnected flag for the specified joint. This flag determines if the two bodies connected by this joint are allowed to collide with each other.

Associates arbitrary user data with a specified joint in the physics world. The joint is located using its world and joint identifiers, and its user data property is updated with the provided value.

Retrieves the user data that was previously attached to the specified joint. The function first gets the world object from the joint ID, then retrieves the joint using the full joint ID, and finally returns the userData property of that joint.

Wakes up both bodies connected by a joint in the physics simulation.

• Error: If the world reference in the jointId is invalid or cannot be accessed.

Returns the constraint force for different joint types including distance, motor, mouse, prismatic, revolute, weld, and wheel joints. The force is retrieved from the corresponding joint-specific force getter function.

• Error: Throws an assertion error for unknown joint types.

Returns the constraint torque for different joint types including motor, mouse, prismatic, revolute, weld and wheel joints. For distance joints, it always returns 0.

• Error: Throws an assertion error if an unsupported joint type is provided.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

Computes collision information between two circles transformed by their respective transforms.

Computes collision information between a capsule shape and a circle shape.

Computes collision information between a polygon and a circle.

Computes the collision manifold between two capsule shapes in 2D space. A capsule is defined by two endpoints and a radius.

• normalX/Y: Collision normal vector
• pointCount: Number of contact points (0-2)
• points[]: Contact point data including:
• anchorA/B: Contact points in local coordinates
• separation: Penetration depth
• id: Contact ID

Converts the segment to a zero-radius capsule and delegates to b2CollideCapsules for the actual collision computation.

Computes collision manifold between a polygon and a capsule by converting the capsule to a polygon and using polygon-polygon collision detection.

Detects collision between two polygons and generates contact information. Transforms the polygons into a common frame, finds the separating axes, and generates contact points. The manifold includes contact points with anchor positions, separation distance, contact IDs and collision normal.

Computes collision detection between a line segment and a circle by converting the segment to a zero-radius capsule and using capsule-circle collision.

Computes collision manifold between a line segment and a polygon by converting the segment into a zero-width capsule and using polygon collision detection.

Computes collision detection between a chain segment and a circle.

• normalX/Y: collision normal in world coordinates
• points: array with contact point data including:
• anchorA/B: contact points in local coordinates
• point: contact point in world coordinates
• separation: distance between shapes
• id: contact ID
• pointCount: number of contact points

Computes collision between a chain segment and a capsule by converting the capsule to a polygon and delegating to the segment-polygon collision function.

Computes the collision manifold between a chain segment (a segment with rounded corners) and a polygon. The function handles edge cases including convex/concave corners and determines contact points and normals. The manifold is populated with contact points and can contain 0, 1 or 2 contact points depending on the collision configuration.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

Calculates the length of a vector and returns its normalized form.

• length: The original length of the vector
• normal: A normalized vector (unit length) in the same direction as v. Returns (0,0) if the input vector length is below epsilon

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

FUNCTIONS

FUNCTIONS

An implementation of absolute value that returns the positive magnitude of the input number.

Returns lower if a < lower, upper if a > upper, otherwise returns a.

A comparison function that returns the minimum value between two integers using a ternary operator.

Computes the absolute value of an integer using conditional logic rather than Math.abs().

Returns lower if a < lower, upper if a > upper, otherwise returns a.

Computes the dot product (scalar product) of two 2D vectors using the formula: dot = a.x * b.x + a.y * b.y

Calculates the cross product between two 2D vectors, which represents the signed area of the parallelogram formed by these vectors.

Computes the cross product of a vector and scalar, returning a new vector that is perpendicular to the input vector and scaled by the scalar value.

Computes s × v, where × denotes the cross product. The result is a new vector (-s * v.y, s * v.x).

Creates a new vector that is perpendicular to the input vector by rotating it 90 degrees counter-clockwise. The new vector is computed by setting the x component to the negative y component of the input, and the y component to the x component of the input.

Creates a new vector that is perpendicular (rotated 90 degrees clockwise) to the input vector. For a vector (x,y), returns (y,-x).

Creates a new b2Vec2 where the x and y components are the sums of the corresponding components of the input vectors.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

Creates a new 2D vector by subtracting the components of vector b from vector a. The resulting vector has coordinates (a.x - b.x, a.y - b.y).

Creates a new b2Vec2 with the negated x and y components of the input vector.

Calculates a point that lies on the straight line between vectors a and b, where t=0 returns a, t=1 returns b, and values in between return proportionally interpolated points.

Multiplies the x components of both vectors together and the y components of both vectors together, returning a new b2Vec2 with these products as its components.

Performs scalar multiplication on a 2D vector, where each component of the vector is multiplied by the scalar value.

Returns a new b2Vec2 with the absolute values of the input vector's components.

Creates a new b2Vec2 where:

• x component is the maximum of a.x and b.x
• y component is the maximum of a.y and b.y

Creates a new 2D vector where each component (x,y) is clamped between the corresponding components of vectors a and b. Uses b2ClampFloat internally to clamp individual components.

Computes the Euclidean length of a 2D vector using the formula sqrt(x² + y²).

Computes the dot product of a vector with itself, which gives the squared length of the vector without performing a square root operation.

Computes the straight-line distance between two points using the Pythagorean theorem.

Computes the squared Euclidean distance between two points without taking the square root. The calculation is (b.x - a.x)² + (b.y - a.y)²

Constructs a b2Rot object by computing the cosine and sine of the provided angle. The resulting b2Rot contains these values as its 'c' and 's' components respectively.

Computes the magnitude of the rotation vector and divides both components by it to create a normalized rotation. If the magnitude is 0, returns a default rotation.

Verifies that the sum of squares of the sine and cosine components equals 1 within a tolerance of ±6e-4, which indicates a valid rotation.

This file includes code that is:

• Copyright 2023 Erin Catto, released under the MIT license.
• Copyright 2024 Phaser Studio Inc, released under the MIT license.

Linearly interpolates between two rotations and normalizes the result. When t=0 returns q12, when t=1 returns q22.

Performs rotation integration while ensuring the resulting rotation remains normalized through magnitude scaling. The function handles the case where magnitude could be zero by returning a default rotation.

Calculates the angular velocity by comparing two rotations and dividing by the time step. Uses the formula (θ2 - θ1)/dt where θ is extracted from the rotations using their sine and cosine components.

Calculates the angle of a rotation by computing the arctangent of the sine component divided by the cosine component using Math.atan2.

Extracts the x-axis direction vector from a rotation matrix by returning a vector containing the cosine component in x and sine component in y.

Extracts the Y axis vector from a rotation matrix by returning the vector (-sin, cos). This represents the vertical basis vector of the rotated coordinate system.

Performs rotation multiplication by combining the cosine and sine components of two b2Rot objects using the formula: result.c = q4.c * r.c - q4.s * r.s result.s = q4.s * r.c + q4.c * r.s

Computes the product of the inverse of rotation q with rotation r. For rotations, the inverse multiplication is equivalent to using the transpose of the rotation matrix.

Computes the angle between two rotations by using their sine and cosine components. The result is the angle needed to rotate from rotation 'a' to rotation 'b'.

This function takes an angle in radians and ensures it falls within the range [-π, π] by adding or subtracting 2π as needed. If the input angle is already within the valid range, it is returned unchanged.

Applies a 2D rotation to a vector using the formula: x' = cx - sy y' = sx + cy where (x,y) is the input vector and (c,s) represents the rotation

Applies the inverse of the rotation defined by q4 to vector v. The operation is equivalent to multiplying the vector by the transpose of the rotation matrix represented by q4.

Applies a rigid body transformation to a 2D point. The transformation consists of a rotation followed by a translation. The rotation is applied using the rotation matrix stored in t.q (cosine and sine components), and the translation is applied using the position vector stored in t.p.

Computes the inverse transform of a point by first translating relative to the transform's position, then applying the inverse rotation. The rotation inverse is computed using the transpose of the rotation matrix.

Combines two transforms by first multiplying their rotations (q components), then rotating B's position vector by A's rotation and adding it to A's position. The result represents the combined transformation of first applying B, then A.

Calculates A^-1 * B, where A^-1 is the inverse of transform A. The result combines both the rotational and translational components of the transforms using their quaternion and position vectors.

Performs matrix-vector multiplication of the form Av, where A is a 2x2 matrix and v is a 2D vector. The result is a new 2D vector.

Computes the inverse of a 2x2 matrix using the formula: For matrix [[a,b],[c,d]], inverse = (1/det) * [[d,-c],[-b,a]] where det = ad-bc

Solves the system using the formula: x = (1/det) * [a22 -a12] * [b.x] [-a21 a11] [b.y] where det = a11a22 - a12a21

Tests if AABB 'b' is completely contained within AABB 'a' by comparing their bounds. An AABB contains another if its lower bounds are less than or equal to the other's lower bounds and its upper bounds are greater than or equal to the other's upper bounds.

Computes the center point of an AABB by averaging its lower and upper bounds in both X and Y dimensions.

Computes the extents of an AABB by calculating half the difference between its upper and lower bounds in both x and y dimensions.

Computes the union of two axis-aligned bounding boxes by creating a new AABB with a lower bound at the minimum coordinates and an upper bound at the maximum coordinates of both input boxes.

This function performs a validation check on a number by ensuring it is both finite and not NaN (Not a Number).

This function performs a validation check on a number by ensuring it is both finite and not NaN (Not a Number).

Validates a b2Vec2 object by checking if it exists and its components are valid numbers.

Validates a b2Vec2 object by checking if it exists and its components are valid numbers.

Checks if a b2Rot object is valid by verifying:

1. The object exists
2. Both sine and cosine components contain valid numbers
3. The rotation is properly normalized (s² + c² = 1)

Checks if a b2Rot object is valid by verifying:

1. The object exists
2. Both sine and cosine components contain valid numbers
3. The rotation is properly normalized (s² + c² = 1)

Checks if an AABB is valid by verifying:

1. The AABB object exists
2. The width (upperBoundX - lowerBoundX) is non-negative
3. The height (upperBoundY - lowerBoundY) is non-negative
4. All coordinate values are valid numbers

Checks if an AABB is valid by verifying:

1. The AABB object exists
2. The width (upperBoundX - lowerBoundX) is non-negative
3. The height (upperBoundY - lowerBoundY) is non-negative
4. All coordinate values are valid numbers

Normalizes the input vector by dividing its components by its length. If the vector's length is greater than the epsilon value, the function returns a new vector with the same direction but unit length.

Normalizes the input vector by dividing its components by its length. If the vector's length is greater than the epsilon value, the function returns a new vector with the same direction but unit length.

Normalizes a 2D vector and performs length validation.

• Error: Throws an assertion error if the vector length is less than or equal to eps.

Normalizes a 2D vector and performs length validation.

• Error: Throws an assertion error if the vector length is less than or equal to eps.

Updates the target linear offset of a motor joint. The linear offset represents the desired translation between the two bodies connected by the joint.

• Error: Throws if the joint is not a motor joint or if the jointId is invalid.

Gets the linear offset of a motor joint.

• Error: If the joint is not a motor joint or the joint ID is invalid.

Sets the target angular offset for a motor joint, which defines the desired relative rotation between the connected bodies. The input angle is automatically clamped to the range [-π, π].

• Error: Throws if the joint is not a motor joint type.