b3dGetCharacterGroundMaterial

Returns material type of ground surface (0=none, 1-4=material, for audio/effects). Takes characterHandle (character controller from b3dCreateCharacterController). Returns material type integer (0=MATERIAL_NONE no material or airborne, 1-4=material types set via b3dSetPhysicsBodyMaterial), reflects surface material of ground contact. Use to select footstep sounds, particle effects, or surface-specific gameplay behaviors.

This function queries ground material. Ground material detection: gets ground body from Jolt CharacterVirtual (CharacterVirtual.GetGroundBodyID() returns physics body character is touching), looks up body handle from BodyID (searches g_bodyHandleToBodyID map to find body handle for that BodyID), retrieves material from creation data (looks up materialType in g_bodyCreationData for that body handle). Material types: 0 = MATERIAL_NONE (no material assigned, airborne, or body without material), 1-4 = material types (set via b3dSetPhysicsBodyMaterial, user-defined material categories), materials user-defined (no built-in meaning, user assigns semantic like 1=metal 2=wood 3=stone 4=grass). Use cases: (1) Footstep audio (play different footstep sounds per surface material), (2) Particle effects (spawn dust for dirt, sparks for metal, splash for water), (3) Movement speed (reduce speed on mud material, increase on ice material), (4) Damage effects (lava material hurts character, healing grass material restores health), (5) Visual feedback (different footprint decals per material type). Common patterns: footstep sound mat = b3dGetCharacterGroundMaterial(char) Select mat Case 1 PlayMetalStep() Case 2 PlayWoodStep(), particle spawn If mat = dirtMaterial Then SpawnDust(), damage floor If mat = lavaMaterial Then ApplyDamage(10). Typical usage: query each frame or on footstep events (select appropriate audio and effects), check for surface-specific behaviors (ice slippery, mud slow, grass normal), combine with entity detection for complete surface identification.

Material assignment: materials set via b3dSetPhysicsBodyMaterial when body created (assigns integer material type to physics body), stored in g_bodyCreationData.materialType (persists with body creation parameters), returned by this function when character contacts that body. Material vs entity: material describes surface type (wood, metal, stone, generic property of surface), entity identifies specific object (platform, floor, wall, unique game object), both can be queried (get material for audio/effects, get entity for gameplay logic). Return zero cases: character airborne (GetGroundBodyID returns invalid BodyID, no ground contact, returns 0 MATERIAL_NONE), ground body not in creation data map (body created outside BambooBasic system, no material assigned, returns 0), material never set (body created but b3dSetPhysicsBodyMaterial not called, defaults to 0). Footstep audio example: get ground material each footstep (mat = b3dGetCharacterGroundMaterial(char) when foot contacts ground), select sound based on material (Select mat: Case 1 metalSound, Case 2 woodSound, Case 3 stoneSound, Case 4 grassSound), play appropriate sound (PlaySound(selectedSound)), realistic audio (footsteps match surface material). Particle effect example: spawn particles when moving (If speed > 0.5 Then spawnParticles()), get ground material (mat = b3dGetCharacterGroundMaterial(char)), select particle type (If mat = 4 Then SpawnGrassParticles() Else If mat = 3 Then SpawnDustParticles()), material-specific effects (grass spawns leaves, dirt spawns dust, metal spawns sparks). Surface speed modification: get ground material (mat = b3dGetCharacterGroundMaterial(char)), modify movement speed based on material (If mat = mudMaterial Then speedMultiplier = 0.5 Else If mat = iceMaterial Then speedMultiplier = 1.2), apply to movement (actualSpeed = baseSpeed * speedMultiplier), gameplay variety (different surfaces affect movement differently). Damage material example: check material each frame (mat = b3dGetCharacterGroundMaterial(char)), apply damage for hazard materials (If mat = lavaMaterial Then health -= 10 * deltaTime), healing for beneficial materials (If mat = healingGrassMaterial Then health += 5 * deltaTime), material-based gameplay (certain surfaces help or harm). Material lookup process: function gets CharacterVirtual.GetGroundBodyID() (Jolt BodyID of ground contact), searches g_bodyHandleToBodyID for matching BodyID (finds body handle that maps to that BodyID), looks up g_bodyCreationData[bodyHandle].materialType (retrieves material assigned during body creation), returns material type or 0 if not found. Body handle vs body ID: BodyID is Jolt physics identifier (internal physics engine reference, transient across sessions), body handle is BambooBasic identifier (user-facing integer handle from b3dCreatePhysicsBody, persistent), material stored with body handle (g_bodyCreationData keyed by handle not BodyID). Material semantics: function returns integer 0-4 (no built-in meaning, user defines what each material represents), typical assignment (1=metal hard surface, 2=wood medium surface, 3=stone hard rough, 4=grass soft natural), consistent assignment recommended (use same material values for same surface types across all bodies). Ground update timing: ground material updated during UpdatePhysicsSystem (physics step detects contacts, updates CharacterVirtual ground state), character must be grounded for valid material (b3dIsCharacterGrounded should return true), material may change mid-frame if character moves (stepping from one surface to another updates ground material). Material vs slope response: material describes surface audio/visual type (wood, metal, for effects), slope response describes surface physics behavior (climbable angle, friction via b3dSetCharacterSlopeResponse), both can be set per entity (entity can have material 1 and custom slope response). Default material: bodies created without b3dSetPhysicsBodyMaterial have material 0 (MATERIAL_NONE default), material 0 indicates no specific material (generic surface, use default sounds and effects), explicitly setting material 0 same as not setting (both return 0 MATERIAL_NONE). Airborne detection: if character airborne GetGroundBodyID returns invalid BodyID (no ground contact, character in air), function returns 0 immediately (short-circuit return, no map searches), reliable airborne indicator (material 0 usually means airborne unless standing on material-0 body). Multiple materials: character can only have one ground material at a time (single ground contact point, one body touched), even if touching multiple bodies only ground body queried (CharacterVirtual determines which body is ground), material switches instantly when ground changes (step from wood to metal changes material immediately). Material persistence: material stored in g_bodyCreationData (persists with body for its lifetime), material doesn't change unless body recreated (static property of body, not dynamic), body deletion removes material (g_bodyCreationData entry removed, no longer queryable). Performance: O(N) + O(M) operation where N is bodies and M is entities (searches g_bodyHandleToBodyID then g_bodyCreationData), typical N and M small (few hundred, fast search), returns immediately if airborne (no searches needed if no ground contact), negligible overhead for typical use (call once per frame or per footstep acceptable). Validation: returns 0 if characterHandle not found in g_characters (invalid or freed character, safe default MATERIAL_NONE), returns 0 if ground body not found in maps (body outside BambooBasic or no material set), no error messages (silent failure, returns reasonable fallback). Related: b3dSetPhysicsBodyMaterial assigns material to physics body (sets material type 0-4), b3dGetCharacterGroundEntity returns entity handle of ground (complementary surface info), b3dIsCharacterGrounded checks if character has ground contact (prerequisite for valid ground material), b3dCreatePhysicsBody creates body (material can be set during or after creation).