b3dAlignToVector

Aligns entity axis to direction vector (surface alignment, gravity, slopes). Takes entity (entity handle), vectorX/Y/Z (target direction vector), axis (0=X-axis/right, 1=Y-axis/up, 2=Z-axis/forward), rate (interpolation factor 0.0-1.0). Returns nothing. Validates entity exists, normalizes target vector, calculates target rotation based on axis alignment (different math for each axis), interpolates rotation (rate controls blend), marks worldMatrixDirty=true. Orientation to align entity axis with world direction.

This function aligns entity axes to direction vectors. Target vector: direction to align axis toward (doesn't need to be normalized, function normalizes), if vector length < 0.0001 (zero vector), function returns without change (can't align to zero vector). Axis parameter: specifies which entity local axis aligns to vector, axis=0 (X-axis): entity's right vector points along target direction, axis=1 (Y-axis): entity's up vector points along target direction, axis=2 (Z-axis): entity's forward vector points along target direction (standard look-at). Target rotation calculation: uses trigonometry to calculate pitch/yaw that aligns specified axis, axis=0 (X-axis alignment): targetPitch = -asin(vy) * 180/PI, targetYaw = atan2(vx, vz) * 180/PI - 90 (rotate so right points at vector), axis=1 (Y-axis alignment): targetPitch = -atan2(vz, vy) * 180/PI + 90, targetYaw = atan2(vx, vy) * 180/PI (rotate so up points at vector), axis=2 (Z-axis alignment): targetPitch = -asin(vy) * 180/PI, targetYaw = atan2(vx, vz) * 180/PI (standard look-at, same as b3dPointEntity). Roll preservation: function only calculates pitch/yaw (roll unchanged, entity stays upright around aligned axis). Rate interpolation: rate parameter controls blend (clamped to 0.0-1.0), rate=0.0: no rotation change, rate=1.0: instant alignment, 0.0<rate<1.0: lerps between current and target: newPitch = currentPitch + (targetPitch - currentPitch) * rate, newYaw = currentYaw + (targetYaw - currentYaw) * rate. Use cases: (1) Surface alignment (vehicles on slopes, align Y-axis to surface normal), (2) Wall walking (spiders align Y-axis to wall normal), (3) Banking/tilting (vehicles lean into turns, align to combined gravity+centrifugal), (4) Rope/chain links (align to next link direction), (5) Custom orientation constraints (align axis to velocity, wind, custom vectors). Common pattern: get surface normal, b3dAlignToVector(vehicle, normalX, normalY, normalZ, 1, 0.1) smooth alignment to slope (Y-axis follows normal), or get velocity vector, b3dAlignToVector(projectile, velX, velY, velZ, 2, 1.0) instant forward alignment. Typical usage: call every frame with low rate for smooth alignment (animated transitions), or call once with rate=1.0 for instant alignment, combine with b3dMoveEntity for aligned movement. Surface alignment workflow: perform collision detection/raycasting, get surface normal from collision, align entity Y-axis to normal (vehicles stand on surface), adjust position to stay on surface. Performance: vector normalization (sqrt, fast), trigonometric calculations (asin, atan2, moderate cost), interpolation is simple lerp. Related: b3dPointEntity orients toward position (Z-axis alignment with interpolation), b3dPointEntityAt orients toward entity, b3dRotateEntity sets absolute rotation.