b3dLaunchCharacterToTarget

Launches character to target with calculated trajectory velocity (ballistic arc, gravity compensated). Takes characterHandle (character to launch), targetX/Y/Z (world position to reach), flightTime (duration in seconds to reach target). Returns nothing. Calculates velocity (vx,vy,vz) to reach target in specified time, applies as pendingImpulse, marks isInTrajectoryFlight true. Use for jump pads, launchers, catapults, grappling hooks, or scripted character arcs.

This function launches character to target. Launch calculation: ballistic trajectory (parabolic arc accounting for gravity, projectile motion physics), horizontal velocity vx = dx / flightTime (constant horizontal speed to cover distance), horizontal velocity vz = dz / flightTime (constant horizontal speed), vertical velocity vy = (dy / flightTime) - (0.5 * gravity * flightTime) (compensates for gravity pulling down during flight). Flight time: user specifies desired duration (seconds to reach target), shorter time = faster launch (higher velocity, steeper arc), longer time = slower launch (lower velocity, shallow arc), typical range 0.5-3.0 seconds. Use cases: (1) Jump pads (launch player upward and forward to platform), (2) Catapults (scripted launch from point to point), (3) Grappling hooks (swing to anchor point with calculated arc), (4) Scripted jumps (cutscene or triggered character launch), (5) Launch pads (momentum-based traversal mechanics). Common patterns: jump pad b3dLaunchCharacterToTarget(player, padX, padY + 10, padZ + 5, 1.5) launch upward and forward, catapult b3dLaunchCharacterToTarget(character, targetX, targetY, targetZ, 2.0) long arc, grapple swing b3dLaunchCharacterToTarget(player, anchorX, anchorY, anchorZ, 0.8) quick swing. Typical usage: call on trigger activation (player steps on jump pad), call for scripted events (cutscene launch), call for grappling mechanics (player grapples to point).

Trajectory calculation: ballistic projectile motion (parabolic arc, gravity-affected flight), horizontal velocity constant (vx = dx / flightTime, vz = dz / flightTime cover horizontal distance), vertical velocity compensated (vy = (dy / flightTime) - (0.5 * gravity * flightTime) accounts for gravity pulling down), mathematically correct trajectory (reaches target at specified flight time, precise). Gravity compensation: gravity pulls down during flight (character falls while moving forward, parabolic arc), compensation term -0.5 * gravity * flightTime (adds upward velocity to counteract fall, ensures target height reached), without compensation character lands below target (falls too much during flight), with compensation character reaches exact target height. Flight time parameter: shorter time faster launch (flightTime 0.5 seconds = quick fast arc, high velocity), longer time slower launch (flightTime 3.0 seconds = slow gentle arc, low velocity), typical range 0.5-3.0 seconds (0.5 fast launch, 1.0-1.5 moderate, 2.0-3.0 slow), negative or zero silently returns (invalid flight time, no launch). Trajectory flight flag: sets data.isInTrajectoryFlight = true (marks character in scripted flight, special state), disables air control damping (character follows trajectory precisely, no air resistance), momentum preservation (character reaches target exactly at flight time, no interference), flag cleared when grounded or manually (automatic on landing, or manually via other functions). Impulse application: adds velocity to pendingImpulse (accumulated velocity applied next physics update, instant launch), replaces current velocity (character velocity becomes trajectory velocity, overrides current movement), immediate launch (takes effect next frame, no delay), one-time impulse (applies once, not continuous force).

Jump pad example: player steps on pad (trigger detects player on jump pad), launch upward and forward (b3dLaunchCharacterToTarget(player, padX, padY + 10, padZ + 5, 1.5) 1.5 second flight), player follows parabolic arc (launched upward and forward, lands on platform), typical jump pad mechanic. Catapult example: player activates catapult (trigger or button press), launch to distant target (b3dLaunchCharacterToTarget(player, castleX, castleY, castleZ, 2.5) long 2.5 second arc), player flies over obstacle (scripted traversal, lands at castle entrance), cinematic launch effect. Grappling hook example: player grapples to anchor (anchor point selected, grapple button pressed), swing to anchor (b3dLaunchCharacterToTarget(player, anchorX, anchorY, anchorZ, 0.8) quick 0.8 second swing), player swings to anchor position (fast arc, momentum-based traversal), grapple traversal mechanic. Launch pad traversal: multiple launch pads in sequence (pad1 to pad2 to pad3 chain), each pad launches to next (b3dLaunchCharacterToTarget at each pad, calculated targets), momentum-based navigation (player follows launch chain, reaches destination), traversal puzzle or mechanic. Scripted cutscene: scripted character launch (NPC or player during cutscene), precise trajectory (b3dLaunchCharacterToTarget(character, cutsceneX, cutsceneY, cutsceneZ, 1.2) exact timing), character follows arc (cinematic launch, lands at scripted position), cutscene control.

Flight time tradeoffs: short time (0.5-1.0 seconds) fast arc (high velocity, quick travel, steep trajectory), long time (2.0-3.0 seconds) slow arc (low velocity, gentle travel, shallow trajectory), moderate time (1.0-1.5 seconds) balanced arc (moderate velocity, typical for most gameplay). Horizontal distance: far targets need longer time or higher velocity (long distance with short time = very fast launch), near targets shorter time (short distance with long time = very slow gentle arc), adjust flight time based on distance (balance speed and arc shape). Vertical height: high targets need more upward velocity (tall vertical component, gravity compensation critical), low targets less upward velocity (small vertical component or downward launch), gravity compensation ensures height (vy calculation accounts for fall during flight). Trajectory shape: short flight time steep arc (high velocity, sharp parabola, fast travel), long flight time shallow arc (low velocity, gentle parabola, slow travel), parabolic shape (apex at mid-flight, symmetric ascent and descent unless interrupted). Launch accuracy: mathematically precise trajectory (reaches target exactly at flight time if uninterrupted), assumes no collisions (character flies through air, doesn't account for obstacles mid-flight), collision handling (if character hits wall mid-flight trajectory interrupted, doesn't reach target), typical use cases assume clear path (jump pads, launchers have clear arcs). Multiple launches: can call repeatedly (launch character multiple times, relaunch while in flight), last launch wins (newest velocity replaces previous, character follows new trajectory), chain launches (launch from pad1, relaunch from pad2 mid-flight for complex paths), creative traversal mechanics. Launch vs force: launch instant velocity (applies trajectory velocity immediately, one-time impulse), force continuous acceleration (applies force over time, gradual velocity change), launch for precise arcs (ballistic trajectory to target), force for dynamic effects (wind, explosions, etc.).

Air control during flight: trajectory flight flag set (isInTrajectoryFlight = true during launch), air control damping disabled (character follows trajectory precisely, no air resistance interference), player input ignored or limited (depends on air control settings, typically disabled for trajectory), precise arc (character reaches target exactly, no deviation from calculated path). Landing detection: character lands when grounded (trajectory flight ends on ground contact), trajectory flag cleared automatically (isInTrajectoryFlight reset on landing), normal movement resumes (player regains control, standard physics apply), smooth transition (from trajectory flight to ground movement). Mid-air interruption: collision with wall interrupts trajectory (character stops mid-flight if hits obstacle, trajectory aborted), character enters normal falling (falls downward after interruption, doesn't continue to target), handle interruptions gracefully (detect collision, switch to appropriate state), recovery mechanics (player regains control after interruption). Gravity scale interaction: character gravity scale affects trajectory (gravityScale 0.5 = half gravity, trajectory calculation uses global gravity), compensation based on global gravity (vy calculation uses g_physicsSystem->GetGravity(), not per-character scale), low gravity longer flights (half gravity = character falls slower, may overshoot with same flight time), high gravity shorter flights (double gravity = character falls faster, may undershoot). Wind and forces interaction: wind and forces apply during flight (environmental forces affect trajectory mid-flight), trajectory may deviate (strong wind pushes character off course, doesn't reach exact target), minimize interference (disable wind or set trajectory flight immune to forces), or embrace deviation (wind-affected trajectories for dynamic gameplay). Launch from moving platform: launch position relative to character (calculates from current character position, not platform), character velocity independent of platform (trajectory overwrites platform movement, absolute world velocity), moving platform launch (character leaves platform with trajectory velocity, platform motion doesn't add), static launch (use current position at launch time).

Flight time zero or negative: invalid flight time (zero or negative causes divide by zero or undefined), function silently returns (no launch, character unaffected), validation (check flightTime > 0 before calling, ensure positive flight time), typical minimum 0.1-0.2 seconds (very fast launch, avoid zero). Target same as current position: zero displacement (dx = dy = dz = 0, character already at target), zero velocity calculated (vx = vy = vz = 0, no launch), character stationary (no impulse applied, stays in place), edge case (avoid launching to current position, check distance first). Very short flight time: extremely fast launch (flightTime 0.1 seconds = very high velocity, nearly instant), steep arc (high upward velocity to compensate for short time), may overshoot or look unnatural (too fast for gameplay, jarring visual), typical minimum 0.5 seconds for smooth gameplay. Very long flight time: extremely slow launch (flightTime 5.0 seconds = very low velocity, gentle float), shallow arc (low upward velocity, gradual ascent and descent), may look unnatural (floaty slow motion, unrealistic), typical maximum 3.0 seconds for normal gameplay. Horizontal friction compensation: horizontalFrictionCompensation = 1.0 (no compensation, trajectory calculation already correct), momentum preservation (trajectory flight disables air control damping, no friction loss), mathematically correct (horizontal velocity vx/vz reaches target exactly without compensation), comment in code (notes that compensation not needed due to momentum preservation).

Pendingimpulse accumulation: data.pendingImpulse += trajectoryImpulse (adds to pending impulse, accumulated velocity), applied next physics update (impulse applied to character during next UpdatePhysicsSystem), instant launch (takes effect next frame after call, immediate), single-frame impulse (applied once, not continuous). Character position: launch from current position (uses character->GetPosition() at call time, not future position), moving character (if character moving when launched, launch from current position not future), stationary launch (typical use, character stationary on pad before launch). Target position: world space coordinates (targetX/Y/Z in global world space, not relative), absolute target (specific world position to reach, not direction), requires known target (must calculate or specify exact target position before launch). Performance: O(1) operation (simple arithmetic and assignment, constant time), negligible cost (safe to call for gameplay events, not per-frame), typical use (launch on trigger activation, scripted events, infrequent calls). Validation: silently returns if character handle not found (invalid or deleted character, no error message), no other validation (any target position or flight time accepted, user responsible for reasonable values), graceful failure (invalid handle doesn't crash, returns silently).

Related: b3dApplyCharacterForce applies custom force (continuous acceleration, alternative to impulse launch), b3dSetCharacterGravityScale sets gravity multiplier (affects trajectory if called before launch, changes gravity), b3dMoveCharacter moves character immediately (teleport vs launch, different mechanics), b3dSetCharacterVelocity sets velocity directly (instant velocity without trajectory calculation, alternative approach).