b3dSetCharacterControllerShape

Changes character controller collision shape (0=capsule 1=cylinder 2=sphere 3=box, recreates CharacterVirtual). Takes characterHandle (character controller from b3dCreateCharacterController), shapeType (0=capsule default, 1=cylinder, 2=sphere, 3=box), radius (shape radius or half-extent for box), height (total height for capsule/cylinder/box, ignored for sphere). Returns nothing. Recreates CharacterVirtual with new shape, preserves state and position, prints shape change to console. Use for gameplay shape changes, different character types, dynamic collision modification.

This function changes collision shape. Shape types: 0 (Capsule: default character shape, vertical capsule along Y-axis, smooth collision, doesn't catch on edges, best for humanoid characters), 1 (Cylinder: flat top and bottom, vertical cylinder along Y-axis, useful for robots or mechanical characters), 2 (Sphere: spherical collision, radius defines sphere size, height ignored, rolls easily, good for ball characters), 3 (Box: rectangular collision, radius defines X/Z half-extent, height defines Y full height, sharp corners may catch on geometry, good for cube characters or vehicles). Shape creation details: Capsule CapsuleShape(halfHeight, radius) creates vertical capsule (total height = 2*halfHeight + 2*radius including hemispheres), Cylinder CylinderShape(halfHeight, radius) creates vertical cylinder (total height = 2*halfHeight flat cylinder), Sphere SphereShape(radius) creates sphere (halfHeight set to radius for offset calculations, diameter = 2*radius), Box BoxShape(Vec3(radius, halfHeight, radius)) creates box (X/Z extent = radius, Y extent = halfHeight, total size = 2*radius x height x 2*radius). Use cases: (1) Character type variation (capsule for humans, cylinder for robots, sphere for rolling enemies), (2) Gameplay powerups (sphere shape for ball mode, box for tank mode), (3) Vehicle shapes (box for cars, cylinder for barrels), (4) Animation-driven shapes (change shape to match animation state). Common patterns: default character b3dSetCharacterControllerShape(char, 0, 0.4, 1.8), robot character b3dSetCharacterControllerShape(char, 1, 0.3, 1.5), ball mode b3dSetCharacterControllerShape(char, 2, 0.5, 0), vehicle b3dSetCharacterControllerShape(char, 3, 1.0, 1.5). Typical usage: set at character creation for non-capsule shapes (robots, vehicles), change during gameplay for powerups or transformations (player morphs into ball), match shape to visual appearance (sync collision with visual mesh shape). State preservation: saves current state before recreation (position, velocity, inputVelocity, impulseVelocity, pendingImpulse, windForce, windResistance, padding, gravityScale, customForce), restores state after recreation (assigns to new CharacterVirtual's CharacterData), prevents state loss during shape change (maintains all physics and movement data). Character recreation: deletes old CharacterVirtual (frees Jolt resources), creates new CharacterVirtual with new shape at same position, updates CharacterData with new shape dimensions (radius, halfHeight, shapeBottomOffset), copies all settings to new character (slope config, padding, max strength, etc.). Bottom offset calculation: shape-specific bottom offset from center (Capsule: halfHeight + radius, Cylinder: halfHeight, Sphere: radius, Box: halfHeight), used to calculate capsuleCenterOffset for position alignment (keeps feet at same location), ensures shape bottom matches visual bottom regardless of shape type. Position preservation: keeps character at same world position (currentPos saved and restored), capsule center adjusted based on shape bottom offset (compensates for different shape extents), feet position remains constant (character doesn't teleport vertically when shape changes). Settings preservation: copies from old character (mMaxSlopeAngle, mCharacterPadding, mMaxStrength, mPenetrationRecoverySpeed, mPredictiveContactDistance, mBackFaceMode), ensures new character behaves identically (only shape changes, movement properties unchanged). Console logging: prints shape change message "[PHYSICS] Character X shape changed to Y (params)" for debugging (helps track shape transitions in development), includes shape-specific parameters (radius, height for capsule/cylinder/box, radius only for sphere), useful for verifying shape changes occur correctly. Invalid shape handling: if shapeType not in 0-3 prints error "[PHYSICS] Invalid shape type: X (using capsule)", defaults to capsule shape (shapeType=0) for unknown values, ensures function always succeeds (no crash on bad input). Sphere special case: for sphere halfHeight = radius (used in offset calculations since sphere has no separate height), height parameter ignored (sphere defined by radius only), ensures sphere collision center calculated correctly. Box dimensions: radius defines X and Z half-extents (box width and depth = 2*radius), height defines full Y height (box height = height), creates square footprint box (X extent = Z extent = radius, non-uniform box requires different approach). Performance: O(1) operation (CharacterVirtual creation is fast), recreation overhead ~0.1ms typically (delete old, create new, copy settings), safe to call during gameplay (no frame drop for single shape change). Shape collision differences: Capsule smoothest collision (rounded edges never catch), Cylinder catches on edges slightly (flat top/bottom can snag), Sphere rolls on slopes (may slide uncontrollably), Box catches on corners frequently (sharp edges catch on geometry, use carefully). Shape-specific uses: Capsule best for bipedal characters (smooth movement, doesn't catch on stairs), Cylinder for rolling barrels or robots (flat base for stability), Sphere for balls or rolling gameplay (natural rolling physics), Box for vehicles or crates (matches visual geometry). Validation: silently returns if characterHandle not found in g_characters (invalid or freed character), defaults to capsule if invalid shapeType (ensures function always succeeds), no validation on radius/height (any positive values allowed, zero or negative may cause issues). Related: b3dCreateCharacterController creates character controller with default capsule shape, b3dSetCharacterHeight changes height only (preserves shape type, faster than full shape change), b3dMoveCharacter sets movement velocity (works with any shape type), b3dIsCharacterGrounded checks ground contact (works with all shape types).