b3dSetCharacterHeight

Changes character controller height dynamically (recreates capsule, keeps feet at same position, scales entity). Takes characterHandle (character controller from b3dCreateCharacterController), newHeight (new total capsule height in units), newVisualBottomOffset (new offset from entity center to visual bottom for alignment). Returns nothing. Recreates CharacterVirtual with new height, adjusts position to keep feet grounded, scales entity vertically. Use for crouch/stand transitions, dynamic height changes.

This function changes controller height. Height change behavior: recreates capsule with new height (deletes old CharacterVirtual, creates new with newHeight), keeps feet position constant (calculates old feet Y, positions new capsule so feet stay at same location), scales visual entity proportionally (newScale = newHeight / originalHeight applied to Y-axis only, preserves X and Z scale), preserves velocity and state (saves velocity, inputVelocity, impulseVelocity before recreation, restores after). Use cases: (1) Crouch/stand transitions (reduce height when crouching, increase when standing), (2) Dynamic character scaling (grow/shrink effects, powerups), (3) Animation-driven height (sync collision with crouch animation), (4) Crawl spaces (reduce height to fit through low passages). Common patterns: crouch if crouchPressed then b3dSetCharacterHeight(char, 0.9, 0.45), stand if not crouchPressed then b3dSetCharacterHeight(char, 1.8, 0.9), gradual resize b3dSetCharacterHeight(char, Lerp(currentH, targetH, alpha), targetOffset). Typical usage: call when crouch button pressed/released for instant height change, interpolate height smoothly over time for gradual transitions, combine with animation system to match visual crouch pose. Height validation: checks if height unchanged (fabs(newHeight - oldHeight) < 0.001 tolerance), skips recreation if height same (optimization, avoids unnecessary CharacterVirtual deletion/creation), always recreates if height different (even small changes). Feet position preservation: calculates old feet Y = currentCapsuleCenterY - (oldHalfHeight + radius) (bottom of old capsule), calculates new capsule center Y = oldFeetY + newCapsuleCenterOffset (bottom stays at oldFeetY), ensures character doesn't teleport vertically when height changes (feet planted, torso raises/lowers). Capsule center offset: newCapsuleBottomOffset = newHalfHeight + radius (distance from capsule center to bottom), newCapsuleCenterOffset = newCapsuleBottomOffset - newVisualBottomOffset (offset from entity center to capsule center), ensures capsule bottom aligns with visual mesh bottom at newVisualBottomOffset. Entity scaling: heightScale = newHeight / originalHeight (proportion of new to original height, originalHeight stored at creation), applies to entity Y-scale only (b3dScaleEntity with scaleX, heightScale, scaleZ), preserves horizontal proportions while changing vertical (doesn't squash or stretch horizontally). Entity position update: calculates new entity Y = oldFeetY + newVisualBottomOffset (positions entity so visual bottom at feet location), calls b3dPositionEntity to sync visual with physics (maintains X and Z, updates only Y), ensures visual mesh bottom matches capsule bottom. State preservation: saves before recreation (currentVel, currentInputVel, currentImpulseVel, currentPendingImpulse), restores after recreation (assigns to new CharacterVirtual's CharacterData), prevents velocity loss during height change (maintains momentum through transition). Character settings preservation: copies settings from old character (mMaxSlopeAngle from defaultSlope.maxClimbXZ, mCharacterPadding, mMaxStrength=100, mPenetrationRecoverySpeed=1.0, mPredictiveContactDistance=0.1), ensures new character behaves identically to old (only height changes, all other properties same). Capsule recreation: creates new CapsuleShape(newHalfHeight, oldRadius) (height changes, radius preserved), creates new CharacterVirtual with new shape at adjusted position, deletes old CharacterVirtual (frees Jolt resources), updates CharacterData with new pointers and dimensions. Dimensions update: data.halfHeight = newHalfHeight (stores new half-height for future calculations), data.capsuleCenterOffset = newCapsuleCenterOffset (stores new offset for position sync), data.visualBottomOffset = newVisualBottomOffset (stores new visual offset for future height changes), data.originalHeight unchanged (preserves original for scaling calculations). Performance: O(1) operation (CharacterVirtual creation is fast), recreation overhead ~0.1ms typically (delete old, create new, copy settings), safe to call every frame if needed (e.g., smooth interpolation between heights). Crouch example workflow: detect crouch input then b3dSetCharacterHeight(char, crouchHeight, crouchOffset) then set crouch animation then adjust camera height, detect stand input then b3dSetCharacterHeight(char, standHeight, standOffset) then set stand animation then restore camera height. Smooth transition pattern: targetHeight and currentHeight then each frame currentHeight = Lerp(currentHeight, targetHeight, smoothing) then b3dSetCharacterHeight(char, currentHeight, Lerp(currentOffset, targetOffset, smoothing)), creates gradual crouch/stand over multiple frames. Validation: silently returns if characterHandle not found in g_characters (invalid or freed character), skips recreation if height change < 0.001 (optimization for tiny changes or no change), no validation on newHeight (any value allowed, very small or zero may cause collision issues). Related: b3dCreateCharacterController creates character controller (sets original height), b3dSetCharacterControllerShape changes collision shape (alternative to height-only change), b3dMoveCharacter sets movement velocity (works with any height), b3dScaleEntity scales entity visually (called automatically by this function).