b3dGetCharacterGroundEntity

Returns entity handle character is standing on (0 if airborne or not on entity). Takes characterHandle (character controller from b3dCreateCharacterController). Returns entity handle of ground surface (entity character is currently standing on), returns 0 if not grounded or ground is not an entity. Use to detect which platform character is on for moving platforms, material detection, or gameplay triggers.

This function queries ground entity. Ground entity detection: gets ground body from Jolt CharacterVirtual (CharacterVirtual.GetGroundBodyID() returns physics body character is touching), looks up entity handle from body ID (searches g_entityToBody map to find entity handle for that body), returns entity handle if found (entity that owns the ground physics body). Return value meaning: positive entity handle (character is standing on that entity, valid entity with physics body), zero (character is airborne, or standing on non-entity static geometry), ground entity updated by physics (UpdatePhysicsSystem updates ground contact each frame). Use cases: (1) Moving platforms (detect when character on platform entity, move character with platform), (2) Trap triggers (detect when character steps on trap floor entity), (3) Material effects (get entity to determine surface properties like ice or lava), (4) Sound selection (different footstep sounds per surface entity), (5) Damage zones (hurt character standing on damage floor entity). Common patterns: platform check platformEntity = b3dGetCharacterGroundEntity(char) If platformEntity > 0 Then onPlatform = True, moving platform If onPlatform Then moveCharacterWithPlatform(platformEntity), damage floor If platformEntity = lavaTileEntity Then ApplyDamage(char, 10). Typical usage: query each frame to detect platform changes (character steps on or off moving platform), check for gameplay triggers (standing on button or pressure plate entity), determine surface type for audio/visual effects (entity-specific footstep sounds).

Ground body ID lookup: calls CharacterVirtual.GetGroundBodyID() (Jolt function returns BodyID of ground contact), checks if BodyID valid (BodyID.IsInvalid() returns false if grounded, true if airborne), searches entity map for body (loops g_entityToBody to find entity handle matching BodyID). Entity to body mapping: g_entityToBody maps entity handles to Jolt BodyIDs (created when entity gets physics body via b3dCreatePhysicsBody), only entities with physics bodies are in map (static mesh entities without bodies not mapped), returned handle is entity that created the ground body. Return zero cases: character airborne (GetGroundBodyID returns invalid BodyID, no ground contact), ground is static world geometry (physics body exists but no entity owns it, not in g_entityToBody map), character on non-physics entity (mesh without collision body, shouldn't happen if character is grounded). Moving platform example: detect platform contact (platformEntity = b3dGetCharacterGroundEntity(char)), track previous platform (if platformEntity != lastPlatformEntity then platform changed), get platform movement (platformVelocity = b3dGetPhysicsBodyVelocity(platformEntity)), move character with platform (add platform velocity to character movement input), creates platform riding (character follows platform motion automatically). Damage floor example: check ground entity each frame (groundEntity = b3dGetCharacterGroundEntity(char)), compare to damage entities (If groundEntity = lavaFloorEntity Or groundEntity = spikeTrapEntity Then inDanger = True), apply damage while standing on hazard (If inDanger Then health -= damagePerSecond * deltaTime), hurt player on contact (lava floors, spike pits, electrified surfaces). Pressure plate example: detect plate contact (plateEntity = b3dGetCharacterGroundEntity(char)), activate if on plate (If plateEntity = pressurePlateEntity Then ActivateDoor()), deactivate when leaving plate (If previousGroundEntity = pressurePlateEntity And groundEntity != pressurePlateEntity Then DeactivateDoor()), simple trigger mechanism (step on plate activates, step off deactivates). Footstep sound selection: get ground entity (groundEntity = b3dGetCharacterGroundEntity(char)), select sound based on entity (If groundEntity = metalFloorEntity Then PlayMetalStep() ElseIf groundEntity = woodFloorEntity Then PlayWoodStep()), entity-specific audio (different materials have different sounds), realistic audio feedback (footsteps match surface type). Ground entity vs ground material: this returns entity handle (which entity owns ground surface, useful for identifying specific objects), b3dGetCharacterGroundMaterial returns material type (0-4 material enum, useful for surface properties like friction), both query ground contact (different information about same surface). Entity handle usage: returned handle is valid entity (can use with b3dEntityX/Y/Z to get entity position, can use with b3dGetPhysicsBody to get physics properties), handle remains valid until entity deleted (check b3dEntityExists if entity might be destroyed), zero means no entity (airborne or on static geometry, not a valid entity handle). Ground update timing: ground entity updated during UpdatePhysicsSystem (physics step detects contacts, updates CharacterVirtual ground state), character must be grounded for valid entity (b3dIsCharacterGrounded should return true), entity may change mid-frame if character moves (stepping from one entity to another updates ground). Multiple entity contacts: character can contact multiple entities (touching wall and floor simultaneously), this returns only ground entity (entity character is standing on, not wall contacts), ground determined by Jolt physics (surface character is supported by, typically highest contact point). Airborne detection: if character airborne GetGroundBodyID returns invalid BodyID (no ground contact, character in air), function returns 0 immediately (short-circuit return, no entity map search), combine with b3dIsCharacterGrounded for reliable check (isGrounded = b3dIsCharacterGroundEntity(char) > 0 Or b3dIsCharacterGrounded(char)). Platform following: previous ground entity (lastPlatform = currentPlatform before update), current ground entity (currentPlatform = b3dGetCharacterGroundEntity(char)), detect platform change (If currentPlatform != lastPlatform Then onPlatformChange()), trigger events on platform transitions (step onto platform play sound, step off platform stop following). Entity lifetime: returned entity may be deleted (entity destroyed while character standing on it), check entity validity (If b3dEntityExists(groundEntity) Then safe to use), handle gracefully (treat deleted entity like 0, character likely falling after entity removal). Performance: O(N) operation where N is number of entities with physics bodies (searches g_entityToBody map linearly for matching BodyID), typical N is small (few hundred entities, fast search), returns immediately if airborne (no search needed if no ground contact), negligible overhead for typical use (call once per frame acceptable). Validation: returns 0 if characterHandle not found in g_characters (invalid or freed character, safe default), returns 0 if ground body not in entity map (static geometry or non-entity body), no error messages (silent failure, returns reasonable fallback). Related: b3dGetCharacterGroundMaterial returns material type of ground (complementary surface info), b3dIsCharacterGrounded checks if character has ground contact (prerequisite for valid ground entity), b3dGetPhysicsBodyVelocity can query ground entity velocity (useful for moving platforms), b3dEntityExists verifies returned entity is still valid (safety check for entity lifetime).