b3dSetCollisionMode

Sets entity collision detection mode (0=Polygon, 1=Box, 2=Sphere). Takes entity (entity handle), mode (0=Polygon, 1=AABB/Box, 2=Sphere). Returns nothing. Stores mode in entity.collisionMode field. Modes outside 0-2 range are ignored (silent fail).

This function sets collision shape. Collision modes: 0 = Polygon (per-triangle collision, most accurate but slowest), 1 = AABB/Box (axis-aligned bounding box, faster than polygon), 2 = Sphere (spherical collision volume, fastest and smoothest). Mode affects: collision detection algorithm used, accuracy vs performance tradeoff, how entity responds to obstacles (sphere slides smoothly, polygon catches on edges). Mode 0 (Polygon): per-triangle collision detection, traces against actual mesh geometry, most accurate (respects mesh shape exactly), slowest performance (tests all triangles), use for static level geometry (walls, floors, terrain), can catch on edges/corners (geometric precision), requires mesh data (doesn't work on pivots/cameras). Mode 1 (Box/AABB): uses axis-aligned bounding box, box oriented to world axes (not entity rotation), faster than polygon (single box test vs many triangles), less accurate (box may be larger than mesh), use for rectangular objects (crates, buildings, platforms), bounding box calculated from mesh bounds, rotated entities still use axis-aligned box (box rotates with entity conceptually but collision uses AABB). Mode 2 (Sphere): uses spherical collision volume, sphere radius from entity.collisionRadius (set by b3dSetEntityRadius), fastest collision mode (simple sphere tests), smoothest response (no edge catching, natural sliding), use for characters/players (smooth movement), use for rolling objects (balls, wheels), uniform response in all directions (isotropic). Use cases: (1) Player character (mode 2 for smooth walking), (2) Static walls (mode 0 or 1 for accuracy), (3) Moving enemies (mode 2 for smooth AI movement), (4) Crates/props (mode 1 for performance), (5) Terrain (mode 0 for accurate ground collision). Common patterns: player setup = b3dSetCollisionMode(player, 2) + b3dSetEntityRadius(player, 0.5) for capsule-like behavior, level geometry = b3dSetCollisionMode(wall, 0) for precise collision, AI entities = b3dSetCollisionMode(enemy, 2) for smooth navigation, physics objects = b3dSetCollisionMode(crate, 1) for simple box collision. Typical usage: call after entity creation (before collision needed), set once during initialization (rarely changed at runtime), combine with b3dEntityType for collision filtering, combine with b3dSetEntityRadius for sphere mode. Performance: mode 2 (sphere) = fastest (simple distance tests), mode 1 (box) = medium (AABB intersection tests), mode 0 (polygon) = slowest (per-triangle swept tests), use mode 2 for moving entities, mode 0 for static level geometry. Collision response: mode affects detection shape but not response behavior, response still controlled by b3dCollisions (none/stop/slide), sphere mode slides more naturally (no edge snagging), polygon mode can catch on triangle edges (geometric precision). Sphere radius: sphere mode uses entity.collisionRadius field, set via b3dSetEntityRadius(entity, radius), radius in world units (not affected by scale), defaults to 1.0 if not set, too small radius = falls through floors, too large radius = can't fit through gaps. Box calculation: box mode uses mesh bounding box, calculated from vertex min/max coordinates, bounding box in entity local space, transformed to world space during collision, axis-aligned in world coordinates (not rotated bounding box). Polygon mode details: traces against mesh triangles, uses swept collision (continuous detection), prevents tunneling through thin walls, requires valid mesh data (vertex/index buffers), doesn't work on pivots/lights/cameras (no geometry). Mode validation: modes outside 0-2 are rejected, function returns early if mode < 0 or mode > 2, no error message (silent fail), invalid entity also returns silently, mode unchanged if invalid input. Mode persistence: collision mode persists until changed, survives position/rotation changes, reset when entity copied (b3dCopyEntity preserves mode), defaults to 0 (polygon) for new entities. Relationship to collision type: b3dSetCollisionMode sets HOW entity collides (shape), b3dEntityType sets WHAT it collides with (filtering), both are independent (can mix sphere shape with any type), both needed for full collision setup. Common combinations: player = mode 2 (sphere) + type 1 (player) + radius 0.5, walls = mode 0 (polygon) + type 2 (walls), enemies = mode 2 (sphere) + type 3 (enemies), pickups = mode 2 (sphere) + type 4 (pickups) + response 0 (pass-through). Edge catching: polygon mode can catch on coplanar triangle edges (precision issue), sphere mode slides smoothly over edges (no catching), workaround = use sphere for moving entities, use polygon only for static geometry. Rotation handling: polygon mode respects entity rotation (mesh rotates), box mode uses AABB (axis-aligned, box extents rotate but collision uses world-aligned box), sphere mode ignores rotation (sphere is isotropic). Related: b3dSetEntityRadius sets sphere collision radius (required for mode 2), b3dEntityType sets collision type for filtering (independent of mode), b3dCollisions defines collision response (works with any mode), b3dEntityCollided detects collisions (works with any mode).