b3dGetCharacterWallEntity

Returns entity handle of wall character is touching (0 if no wall or not entity). Takes characterHandle (character controller from b3dCreateCharacterController). Returns entity handle of wall surface (entity character is currently touching on vertical surface), returns 0 if no wall contact or wall is not an entity. Use for wall-specific gameplay mechanics, entity interaction, or wall type detection.

This function queries wall entity. Wall detection: searches CharacterVirtual active contacts (all current collision points from physics update), identifies wall contacts (contact normal Y component < 0.5 means >60 degrees from horizontal, mostly vertical surface), looks up entity from contact BodyID (uses g_bodyToEntity map to find entity handle for wall body). Entity lookup: gets BodyID from wall contact (contact.mBodyB from CharacterVirtual contact list), searches g_bodyToEntity map (reverse lookup from Jolt BodyID to BambooBasic entity handle), returns entity handle if found (entity that owns the wall physics body). Return value meaning: positive entity handle (character is touching that entity's wall, valid entity with physics body), zero (character not on wall, or wall is static geometry without entity, or wall body not mapped to entity), wall entity updated by physics (UpdatePhysicsSystem updates contacts each frame). Use cases: (1) Moving walls (detect when character touches moving wall entity, attach character to wall movement), (2) Interactive walls (trigger events when touching specific wall entities like doors or switches), (3) Special wall types (different wall entities have different properties like ice walls or lava walls), (4) Wall-specific mechanics (certain walls allow running, others don't, based on entity), (5) Entity-based effects (spawn entity-specific particles when touching particular wall). Common patterns: wall entity check wallEntity = b3dGetCharacterWallEntity(char) If wallEntity > 0 Then touchingWall = True, specific wall If wallEntity = specialWallEntity Then activateWallRun(), moving wall If wallEntity > 0 Then attachToWall(wallEntity). Typical usage: query when wall contact detected (check b3dIsCharacterOnWall first), use entity handle for gameplay logic (moving platforms, interactive walls, special wall types), combine with entity properties for wall-specific behaviors.

Wall entity detection process: function gets CharacterVirtual active contacts (all current collision points), finds first wall contact (normal Y < 0.5, mostly vertical surface), retrieves contact BodyID (Jolt physics body identifier for wall), looks up entity handle in g_bodyToEntity map (maps BodyID to entity handle). Body to entity mapping: g_bodyToEntity populated when entity gets physics body (b3dCreatePhysicsBody associates entity with body), only entities with physics bodies are mapped (static mesh entities without bodies not in map), returned handle is entity that created the wall body. Return zero cases: no wall contact (character not touching any vertical surfaces, airborne or on ground only), wall is static world geometry (physics body exists but no entity owns it, not in g_bodyToEntity map), invalid character handle (characterHandle not found in g_characters map). Moving wall example: detect wall entity contact (wallEntity = b3dGetCharacterWallEntity(char)), check if wall is moving platform (If wallEntity = movingPlatformEntity Then onMovingWall = True), get wall velocity (wallVel = b3dGetPhysicsBodyVelocity(wallEntity)), attach character to wall (add wall velocity to character movement, character moves with wall). Interactive wall example: detect wall entity (wallEntity = b3dGetCharacterWallEntity(char)), check for specific wall types (If wallEntity = doorEntity Then openDoor(), If wallEntity = switchEntity Then activateSwitch()), entity-specific interactions (different walls trigger different events based on entity handle). Special wall types: ice wall entity has low friction (If wallEntity = iceWallEntity Then reduceFriction()), lava wall entity causes damage (If wallEntity = lavaWallEntity Then ApplyDamage(10)), climbing wall entity allows wall running (If wallEntity = climbableWallEntity Then enableWallRun()), entity handle determines wall properties. Wall-specific mechanics: certain entities allow wall running (If wallEntity = wallRunEntity Then canWallRun = True), certain entities block wall running (If wallEntity = slipperyWallEntity Then cannotWallRun = True), entity-based validation (check entity handle before allowing special wall mechanics). Entity vs ground entity: this returns wall entity (entity character touches vertically, mostly vertical surface), b3dGetCharacterGroundEntity returns ground entity (entity character stands on, mostly horizontal surface), both can be non-zero simultaneously (character on ground touching wall, two different entities). Wall entity validity: returned entity may be deleted (entity destroyed while character touching it), check entity validity (If b3dEntityExists(wallEntity) Then safe to use), handle gracefully (treat deleted entity like 0, character likely sliding off destroyed wall). Wall entity lifetime: entity handle valid until entity deleted (entity lifetime independent of wall contact), contact tracking (wallEntity changes when character switches walls, different wall different entity), multiple walls may be same entity (large wall entity, multiple contact points same handle). Moving platform mechanics: detect platform wall (platformEntity = b3dGetCharacterWallEntity(char)), track platform movement (platformVelocity = b3dGetPhysicsBodyVelocity(platformEntity)), apply platform motion to character (character velocity += platform velocity, character follows platform), realistic platform interaction (character adheres to moving wall). Wall entity persistence: entity handle valid only while wall contact exists (wallEntity changes or becomes 0 when character leaves wall), store entity if needed (save wallEntity when leaving wall for delayed logic), entity may change rapidly (switching between walls updates entity handle). Multiple wall contacts: character may contact multiple walls (corner or complex geometry), function returns first wall entity only (not necessarily closest or most significant), consider checking multiple frames (collect wall entities over time for complete picture). Wall entity vs wall material: this returns entity handle (which entity owns wall surface, useful for identifying specific objects), b3dGetCharacterGroundMaterial returns material type (0-4 material enum for ground, no wall material function currently), entity handle more specific than material (unique entity vs generic material category). Entity-based effects: spawn entity-specific particles (If wallEntity = metalWallEntity Then SpawnSparks() else SpawnDust()), entity-specific sounds (different wall entities play different touch sounds), entity-specific visuals (decals match wall entity type). Wall run validation: check if wall entity allows running (If IsWallRunnable(wallEntity) Then canRun = True), entity whitelist approach (only specific wall entities allow wall running, others don't), gameplay variety (some walls climbable, others slippery or blocked). Contact tracking: store previous wall entity (lastWall = currentWall before update), current wall entity (currentWall = b3dGetCharacterWallEntity(char)), detect wall changes (If currentWall != lastWall Then onWallChange()), trigger events on wall transitions (step onto new wall entity, play sound or effect). Wall entity properties: query entity properties using handle (wallMaterial = GetEntityMaterial(wallEntity), wallFriction = GetEntityFriction(wallEntity)), entity-specific configuration (each wall entity has custom properties), properties affect gameplay (wall friction affects sliding, wall material affects sounds). Coordinate system: entity handle is integer identifier (not position or direction, reference to entity object), entity has position in world (b3dEntityX/Y/Z get entity location), wall entity position is wall location (entity position represents wall placement in world). Performance: O(N) + O(1) operation where N is active contacts (searches contact list for wall O(N), then map lookup O(1)), returns immediately when wall found (short-circuits on first wall, no further iteration), typically fast (N is small 1-4 contacts, map lookup constant time). Validation: returns 0 if characterHandle not found (invalid or freed character, safe default), returns 0 if wall body not in entity map (static geometry or non-entity body), no error messages (silent failure, returns reasonable fallback). Related: b3dGetCharacterGroundEntity returns entity character stands on (ground entity, complementary to wall entity), b3dIsCharacterOnWall checks for wall contact (prerequisite for valid wall entity), b3dGetPhysicsBodyVelocity can query wall entity velocity (useful for moving walls), b3dEntityExists verifies returned entity is still valid (safety check for entity lifetime).