Skip to content

surface-following.entity overview

Table of contents

utils

SurfaceFollowFunc (type alias)

Represents a function that calculates the surface position and normal for a given point in 3D space.

Signature

export type SurfaceFollowFunc = (p: Point3) => { position: Point3; normal: Point3 }

SurfaceFollowingEntity (class)

Represents an entity that follows a surface dynamically by adjusting its position and orientation based on a given surface function.

Every collider added gets its own infinite plane, in a collision group only that collider and the plane share, moved under the collider every tick to followFunc's position and normal. The planes are static bodies: a road surface doesn't move, so a plane must have zero velocity even though it is teleported every tick. A kinematic plane would get a velocity derived from each teleport (the collider's own speed, plus a spin whenever the orientation changes), and the solver would push that velocity into the collider's chassis on every contact. A plane's orientation is the shortest-arc rotation from +Z to the surface normal (Qtrn.fromTo), so it has no twist around the normal that could change from tick to tick.

Signature

export declare class SurfaceFollowingEntity<PTypeDoc> {
  constructor(
    /** Function that determines surface position and normal. */
    public followFunc: SurfaceFollowFunc,
    /** Optional body configuration. */
    protected bodyOptions: Partial<
      Omit<BodyOptions, 'bodyType' | 'mass' | 'ownCollisionGroups' | 'interactWithCollisionGroups'>
    > = {}
  )
}

setupCollider (method)

Sets up a collider by assigning it a collision group and a dynamic plane.

Signature

private setupCollider(collider: PTypeDoc['rigidBody'])

addCollider (method)

Adds a collider to the entity, registering it immediately if the entity is already in a world.

Signature

addCollider(collider: PTypeDoc['rigidBody'])

removeCollider (method)

Removes a collider and deregisters its associated collision group.

Signature

removeCollider(collider: PTypeDoc['rigidBody'])

onSpawned (method)

Called when the entity is added to a world.

Signature

onSpawned(world: Gg3dWorld<Gg3dWorldTypeDocPPatch<PTypeDoc>>)

updateDebugView (method)

Updates debug visualization if active.

Signature

private updateDebugView()

onRemoved (method)

Called when the entity is removed from the world.

Signature

onRemoved()

positionPlanes (method)

Positions planes based on the surface-follow function.

Signature

protected positionPlanes()

tickOrder (property)

Determines the execution order for physics simulation.

Signature

readonly tickOrder: number

debugBodySettings (property)

Debugging settings for the surface-following entity.

Signature

readonly debugBodySettings: SurfaceFollowingEntityDebugSettings

SurfaceFollowingEntityDebugSettings (class)

Stores debug settings for a SurfaceFollowingEntity, allowing customization of the debug mesh.

Signature

export declare class SurfaceFollowingEntityDebugSettings {
  constructor(
    private _hexMeshStepDistance: number = 4,
    private _hexMeshDepth: number = 6,
    private _customGlobalShape: Shape3DDescriptor | null = null
  )
}