Class ShapeComponent

This is a base component for other components. Most probably you don't need to use it directly, but use a derived component instead.

Hierarchy (View Summary)

Accessors

convexRadius debugDraw debugDrawDepth density halfExtent halfHeight hfActiveEdgeCosThresholdAngle hfBitsPerSample hfBlockSize hfOffset index isCompoundChild massOffset mesh radius renderAsset shape shapePosition shapeRotation useEntityScale

Methods

addShape fire hasEvent modifyShape off on once removeShape

Accessors

convexRadius

  • get convexRadius(): number

  • Internally the convex radius will be subtracted from the half extent, so the total size will not grow with the convex radius. You can increase this value to make the edges of the collision shape rounded.

    Note:

    • Only used by shapes with sharp edges: SHAPE_BOX and SHAPE_CYLINDER.
    • Cannot be changed after the shape is created.

    Returns number

    Number, representing the convex radius.

    Default Value

    0.05 (m)

debugDraw

  • get debugDraw(): boolean

  • Specifies, whether to debug draw the collision shape.

    Returns boolean

    Boolean, telling if the collision shape should be drawn using lines.

    Default Value

    false
  • set debugDraw(bool: boolean): void

  • Allows to turn on/off debug draw for this body. Only works with a debug build.

    Parameters

    • bool: boolean

      Boolean to enable/disable a debug draw.

    Returns void

debugDrawDepth

density

  • get density(): number

  • Density of the object. Affects the mass of the object, when BodyComponent.overrideMassProperties is set to OMP_CALCULATE_MASS_AND_INERTIA (default, which will auto-calculate the mass using the shape dimensions and this density value).

    Returns number

    Number, representing the density of this collision shape.

    Default Value

    1000 (kg / m^3)

halfExtent

halfHeight

  • get halfHeight(): number

  • Half-height of radius based shapes.

    Note: Only used by SHAPE_CAPSULE and SHAPE_CYLINDER.

    Returns number

    Number, representing half of the total height of the collision shape.

    Default Value

    0.5 (m)

hfActiveEdgeCosThresholdAngle

  • get hfActiveEdgeCosThresholdAngle(): number

  • Cosine of the threshold angle. If the angle between the two triangles in HeightField is bigger than this, the edge is active. note that a concave edge is always inactive. Setting this value too small can cause ghost collisions with edges. Setting it too big can cause depenetration artifacts (objects not depenetrating quickly). Valid ranges are between cos(0 degrees) and cos(90 degrees).

    Returns number

    Number, representing radians of the threshold angle.

    Default Value

    0.996195 (cos(5 degrees))

hfBitsPerSample

  • get hfBitsPerSample(): number

  • How many bits per sample to use to compress the HeightField. Can be in the range [1, 8]. Note that each sample is compressed relative to the min/max value of its block of hfBlockSize * hfBlockSize pixels so the effective precision is higher. Also note that increasing hfBlockSize saves more memory, than reducing the amount of bits per sample.

    Returns number

    Number, representing amount of compression bits.

    Default Value

    8

hfBlockSize

  • get hfBlockSize(): number

  • The HeightField is divided in blocks of hfBlockSize * hfBlockSize * 2 triangles and the acceleration structure culls blocks only, bigger block sizes reduce memory consumption, but also reduce query performance. Sensible values are [2, 8]. Does not need to be a power of 2. Note that at run-time Jolt performs one more grid subdivision, so the effective block size is half of what is provided here.

    Returns number

    Number, representing a block size.

    Default Value

    2

hfOffset

  • get hfOffset(): Vec3

  • Offsets the position of the HeightField, which is a surface defined by:

    hfOffset + hfScale * (x, hfHeightSamples[y * hfSampleCount + x], y)

    where x and y are integers in the range x and y e [0, hfSampleCount - 1].

    Returns Vec3

    Vec3 with position offset.

    Default Value

    Vec3(0, 0, 0) (m per axis)

index

  • get index(): number

  • Unique body index. This can change during entity lifecycle, e.g. every time entity is enabled, a new index is assigned and a new body is created. The index is used to map entity to body. Index can be re-used by another component if this component is disabled or destroyed (destroying related body as a result).

    Returns number

    Integer number, representing the unique body index.

    Default Value

    -1

isCompoundChild

  • get isCompoundChild(): boolean

  • Specifies if the component describes a child of a compound shape.

    Returns boolean

    Boolean, telling if this component describes a child shape of a compound shape.

    Default Value

    false

massOffset

mesh

radius

renderAsset

  • get renderAsset(): null | number

  • This field contains the render asset ID, when a render asset is used for collision mesh or a convex hull.

    Returns null | number

    Asset or its ID number. Will be null if render asset is not used.

    Default Value

    null
  • set renderAsset(asset: number | Asset): void

  • Sets render asset as a collider. Note:

    • shape must be SHAPE_MESH or SHAPE_CONVEX_HULL in order for the render asset to be used.
    • If the render asset has multiple mesh instances, only the mesh from the first mesh instance is used. If you need multiple meshes, consider creating a compound collider.

    Parameters

    • asset: number | Asset

      Render asset or its id number.

    Returns void

shape

  • get shape(): number

  • Current shape type.

    Returns number

    Number, representing the shape type.

    Default Value

    SHAPE_BOX
  • set shape(shapeNum: number): void

  • Changes the shape type. Following constants available:

    SHAPE_EMPTY

    SHAPE_PLANE

    SHAPE_BOX

    SHAPE_CAPSULE

    SHAPE_TAPERED_CAPSULE

    SHAPE_CYLINDER

    SHAPE_TAPERED_CYLINDER

    SHAPE_SPHERE

    SHAPE_MESH

    SHAPE_CONVEX_HULL

    SHAPE_HEIGHTFIELD

    SHAPE_STATIC_COMPOUND

    SHAPE_MUTABLE_COMPOUND

    Parameters

    • shapeNum: number

      Shape type number.

    Returns void

shapePosition

shapeRotation

useEntityScale

  • get useEntityScale(): boolean

  • Applies entity scale on the shape. This makes it easier to adjust the size of the collision shape by simply scaling the entity.

    Note: Some shapes do not support non-uniformed scales, like SHAPE_SPHERE. Works best with SHAPE_BOX which you can scale on any axis. Others, like capsule and cone, can't have a different radius on X and Z axis, but allow scaling Y for their height.

    Returns boolean

    Boolean, telling if the entity scale is applied on this collision shape.

    Default Value

    true

Methods

addShape

  • addShape(
        shapeIndex: number,
        localPos?: Vec3,
        localRot?: Quat,
        userData?: number,
    ): void

  • Allows to add a shape to a mutable compound shape.

    Parameters

    • shapeIndex: number

      The index of a shape to add. It can be created by createShape.

    • OptionallocalPos: Vec3 = Vec3.ZERO

      Local position of the shape.

    • OptionallocalRot: Quat = Quat.IDENTITY

      Local rotation of the shape.

    • OptionaluserData: number = 0

      User defined unsigned integer.

    Returns void

fire

  • fire(
        name: string,
        arg1?: any,
        arg2?: any,
        arg3?: any,
        arg4?: any,
        arg5?: any,
        arg6?: any,
        arg7?: any,
        arg8?: any,
    ): EventHandler

  • Fire an event, all additional arguments are passed on to the event listener.

    Parameters

    • name: string

      Name of event to fire.

    • Optionalarg1: any

      First argument that is passed to the event handler.

    • Optionalarg2: any

      Second argument that is passed to the event handler.

    • Optionalarg3: any

      Third argument that is passed to the event handler.

    • Optionalarg4: any

      Fourth argument that is passed to the event handler.

    • Optionalarg5: any

      Fifth argument that is passed to the event handler.

    • Optionalarg6: any

      Sixth argument that is passed to the event handler.

    • Optionalarg7: any

      Seventh argument that is passed to the event handler.

    • Optionalarg8: any

      Eighth argument that is passed to the event handler.

    Returns EventHandler

    Self for chaining.

    Example

    obj.fire('test', 'This is the message');

hasEvent

  • hasEvent(name: string): boolean

  • Test if there are any handlers bound to an event name.

    Parameters

    • name: string

      The name of the event to test.

    Returns boolean

    True if the object has handlers bound to the specified event name.

    Example

    obj.on('test', () => {}); // bind an event to 'test'
    obj.hasEvent('test'); // returns true
    obj.hasEvent('hello'); // returns false

modifyShape

  • modifyShape(
        childIndex: number,
        localPos?: Vec3,
        localRot?: Quat,
        shapeIndex?: number,
    ): void

  • Allows to modify a child shape of a mutable compound shape.

    Parameters

    • childIndex: number

      The child shape index. Children indices are zero based and have no gaps.

    • OptionallocalPos: Vec3 = Vec3.ZERO

      Local position of the shape.

    • OptionallocalRot: Quat = Quat.IDENTITY

      Local rotation of the shape.

    • OptionalshapeIndex: number = -1

      The index of a shape to add. It can be created by createShape.

    Returns void

off

  • off(name?: string, callback?: HandleEventCallback, scope?: object): EventHandler

  • Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.

    Parameters

    • Optionalname: string

      Name of the event to unbind.

    • Optionalcallback: HandleEventCallback

      Function to be unbound.

    • Optionalscope: object

      Scope that was used as the this when the event is fired.

    Returns EventHandler

    Self for chaining.

    Example

    const handler = () => {};
    obj.on('test', handler);

    obj.off(); // Removes all events
    obj.off('test'); // Removes all events called 'test'
    obj.off('test', handler); // Removes all handler functions, called 'test'
    obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this

on

  • on(name: string, callback: HandleEventCallback, scope?: object): EventHandle

  • Attach an event handler to an event.

    Parameters

    • name: string

      Name of the event to bind the callback to.

    • callback: HandleEventCallback

      Function that is called when event is fired. Note the callback is limited to 8 arguments.

    • Optionalscope: object

      Object to use as 'this' when the event is fired, defaults to current this.

    Returns EventHandle

    Can be used for removing event in the future.

    Example

    obj.on('test', (a, b) => {
        console.log(a + b);
    });
    obj.fire('test', 1, 2); // prints 3 to the console

    Example

    const evt = obj.on('test', (a, b) => {
        console.log(a + b);
    });
    // some time later
    evt.off();

once

  • once(name: string, callback: HandleEventCallback, scope?: object): EventHandle

  • Attach an event handler to an event. This handler will be removed after being fired once.

    Parameters

    • name: string

      Name of the event to bind the callback to.

    • callback: HandleEventCallback

      Function that is called when event is fired. Note the callback is limited to 8 arguments.

    • Optionalscope: object

      Object to use as 'this' when the event is fired, defaults to current this.

    Returns EventHandle

    • can be used for removing event in the future.

    Example

    obj.once('test', (a, b) => {
        console.log(a + b);
    });
    obj.fire('test', 1, 2); // prints 3 to the console
    obj.fire('test', 1, 2); // not going to get handled

removeShape

  • removeShape(childIndex: number): void

  • Allows to remove a child shape from a mutable compound shape. The children are indexed in order they were added. Indices are zero based and have no gaps. If you remove a child, then the next child takes its index.

    For example, if you remove child under index 0, then all children shift there indices, so that the child with index 1, becomes a child with index 0, etc.

    Parameters

    • childIndex: number

      The index of a child shape to remove.

    Returns void

Settings

Member Visibility

On This Page

Accessors
Methods