b3dCreateCharacterController

Creates character controller with capsule collision (radius, height, padding, visualBottomOffset, returns characterHandle). Takes entityHandle (entity to attach controller to), radius (capsule radius in units), height (total capsule height including hemispheres in units), padding (collision padding for penetration recovery), visualBottomOffset (offset from entity center to visual mesh bottom for alignment). Returns characterHandle (character controller handle for subsequent operations, 0 on failure). Creates Jolt CharacterVirtual with capsule shape, enables player movement, collision, slopes, stairs. Powered by Jolt Physics CharacterVirtual system.

This function creates kinematic character controller. Controller parameters: radius (capsule radius, affects width of character collision, typical values 0.3-0.5 for human, smaller for tight spaces), height (full capsule height from bottom to top including hemispheres, typical values 1.8-2.0 for human standing, affects total character height), padding (collision padding for penetration recovery, typical values 0.02-0.05, prevents clipping into geometry), visualBottomOffset (distance from entity center to visual mesh bottom, used to align capsule bottom with mesh feet, typically height/2 if entity centered at origin). Character controller features: kinematic collision (CharacterVirtual moves with collision resolution, not affected by forces like rigid bodies), slope handling (45 degree max slope climbable, steeper slopes slide down), stair stepping (0.4 unit default step-up height for stairs), floor sticking (0.5 unit default step-down for staying on slopes), gravity simulation (vertical velocity with ground detection), predictive contacts (0.1 unit predictive contact distance prevents tunneling). Use cases: (1) Player character (third-person or first-person player movement with collision), (2) NPCs (AI-controlled characters walking around environment), (3) Vehicles (simple vehicle collision without full physics simulation), (4) Platformer character (jump, run, climb with precise control). Common patterns: create player controller = b3dCreateCharacterController(playerEntity, 0.4, 1.8, 0.03, 0.9), create NPC controller = b3dCreateCharacterController(npc, 0.35, 1.7, 0.03, 0.85), create small character controller = b3dCreateCharacterController(child, 0.25, 1.2, 0.02, 0.6). Typical usage: create after loading entity to enable character movement, use characterHandle with b3dMoveCharacter to apply horizontal velocity, use b3dCharacterJump to jump, query b3dIsCharacterGrounded before allowing jump. Capsule shape: CapsuleShape(halfHeight, radius) in Jolt (vertical capsule along Y-axis, two hemispheres separated by cylinder), total height = 2*halfHeight + 2*radius (cylinder height + hemispheres), capsule best for characters (smooth collision, doesn't catch on edges, realistic proportions). Visual alignment: entity center typically at character center (waist or torso), visual mesh bottom at feet level (visualBottomOffset = height from center to feet), capsule bottom aligned with feet (capsuleCenterY = entityY + capsuleBottomOffset - visualBottomOffset), ensures capsule collision matches visual appearance (capsule bottom = mesh feet location). Character settings: mMaxSlopeAngle = 45 degrees (climbs slopes up to 45 deg, slides on steeper), mMaxStrength = 100 (pushing force against dynamic objects), mCharacterPadding = user padding (penetration recovery distance), mPenetrationRecoverySpeed = 1.0 (speed at which character pushed out of geometry), mPredictiveContactDistance = 0.1 (how far ahead to check for collisions), mBackFaceMode = CollideWithBackFaces (collides with both sides of geometry). Default movement properties: walkSpeed = 5.0 units/sec (normal walking), runSpeed = 10.0 units/sec (sprinting), crouchSpeed = 2.5 units/sec (crouching), stepUp = 0.4 units (stair height), stepDown = 0.5 units (floor stick distance), airControl = 0.3 (30% horizontal control while airborne), movementState = 0 (starts in walk mode). Advanced features initialized: slope config (45 deg climb/slide, 0.6 friction), launch response (SLIDE mode for collisions), wind force/resistance (0 by default), impulse system (for applying forces to character), ledge grabbing (disabled by default), wall running (normal gravity 1.0 by default). Character data storage: g_characters[characterHandle] stores CharacterData struct (character pointer, entityHandle, velocity, inputVelocity, radius, halfHeight, capsuleCenterOffset, originalHeight, visualBottomOffset, movement settings, physics state), persists for character lifetime, accessed during physics updates and queries. Position coordinate system: entityY is entity center Y position (provided via b3dEntityY), capsuleCenterY is capsule physics center (offset from entity to match feet alignment), calculated as entityY + (capsuleBottomOffset - visualBottomOffset), ensures capsule bottom = entity bottom + visualBottomOffset. Character update: character updated in UpdatePhysicsSystem called by b3dRenderWorld (applies gravity, processes movement input, performs collision detection, updates entity position to match character position), runs every physics step (typically 60 Hz). Performance: O(1) creation (simple CharacterVirtual instantiation), character collision costs depend on environment complexity (more geometry = more collision checks), typically 0.1-0.5ms per character per frame for normal scenes. Validation: returns 0 if g_physicsSystem not initialized (b3dInitPhysics not called), no validation on radius/height (any positive values allowed, zero or negative may cause undefined behavior), padding should be small (0.01-0.1, too large causes excessive penetration recovery). Related: b3dMoveCharacter sets horizontal movement velocity (call each frame for character control), b3dCharacterJump applies upward velocity for jumping, b3dIsCharacterGrounded checks if on ground (required before jumping), b3dSetCharacterHeight changes height dynamically (crouch/stand transitions), b3dSetCharacterControllerShape changes collision shape (capsule/cylinder/sphere/box).