Physics Components
    Preparing search index...

    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)

    Index

    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 setShape

    Accessors

    • 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.

      0.05 (m)
    • get debugDraw(): boolean

      Specifies, whether to debug draw the collision shape.

      Returns boolean

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

      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

    • 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.

      1000 (kg / m^3)
    • get halfHeight(): number

      Half-height of radius based shapes, e.g. SHAPE_CAPSULE.

      Returns number

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

      0.5 (m)
    • 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.

      0.996195 (cos(5 degrees))
    • 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.

      8
    • 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.

      2
    • 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.

      Vec3(0, 0, 0) (m per axis)
    • 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.

      -1
    • 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.

      false
    • 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.

      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

    • get shape(): number

      Current shape type.

      Returns number

      Number, representing the shape type.

      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

    • 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.

      true

    Methods

    • 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 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.

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

    • 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.

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

    • 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

    • 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.

      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

    • 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.

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

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

    • 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.
      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

    • 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

    • Allows changing the current shape to a custom one.

      Note: once set, you won't be able to destroy this shape using destroyShape. The shape will be destroyed when either the body gets destroyed, or when you change it to another shape.

      Parameters

      • shapeIndex: number

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

      Returns void

      const customShapeIdx = app.physics.createShape(SHAPE_SPHERE, {
          radius: 2,
          shapePosition: new Vec3(0, 1, 0)
      });
      entity.body.setShape(customShapeIdx);

    Settings

    Member Visibility

    On This Page

    Accessors
    Methods