Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Defold

bullet3d.shape

Borrowed shape handles identify a one-based child slot on a Defold-owned collision object. They remain attached to that logical slot when its native shape is replaced and become invalid with their owning collision object. Shape mutation is copy-on-write, so instances sharing a collision resource are not modified together. Lengths use Defold world units.

Functions

bullet3d.shape.get_collision_object(shape: bullet3d.shape.BtCollisionShape): Opaque<"btCollisionObject" | "btRigidBody">N

  • Since Defold 1.13.2

Get the owning collision object.

Parameters

Returns

  • object: Opaque<"btCollisionObject" | "btRigidBody"> — owning collision object

bullet3d.shape.get_index(shape: bullet3d.shape.BtCollisionShape): numberN

  • Since Defold 1.13.2

Get the one-based child index.

Parameters

Returns

  • shape_index: number — one-based shape index. ⚠️ 1-based; passed to Defold unchanged.

bullet3d.shape.get_local_transform(shape: bullet3d.shape.BtCollisionShape): LuaMultiReturn<[Vector3, Quaternion]>N

  • Since Defold 1.13.2

A non-compound collision object's only shape has no child transform, so this function returns the identity transform for it.

Parameters

Returns

  • position: Vector3 — local position
  • rotation: Quaternion — local rotation

bullet3d.shape.get_shape(shape: bullet3d.shape.BtCollisionShape): bullet3d.shape.Definition | { type: typeof bullet3d.shape.SHAPE_TYPE_MESH }N

  • Since Defold 1.13.2

The returned table always contains type, one of bullet3d.shape.SHAPE_TYPE_*. A sphere also contains numeric diameter; a box contains vector3 dimensions; a capsule contains numeric diameter and cylindrical-section height; a hull contains a vertices array of vector3 values; and a triangle mesh contains only type. Primitive and hull tables use Defold units and can be passed to a bullet3d.world shape query after adding the desired position and optional rotation fields.

Parameters

Returns

  • data: bullet3d.shape.Definition | { type: typeof bullet3d.shape.SHAPE_TYPE_MESH } — typed shape geometry in Defold units

bullet3d.shape.get_type(shape: bullet3d.shape.BtCollisionShape): bullet3d.shape.ShapeTypeN

  • Since Defold 1.13.2

Get the normalized Defold shape type.

Parameters

Returns

bullet3d.shape.is_valid(shape: bullet3d.shape.BtCollisionShape): booleanN

  • Since Defold 1.13.2

Test whether a shape handle and its owner still exist.

Parameters

Returns

  • valid: boolean — validity

bullet3d.shape.set_local_transform(shape: bullet3d.shape.BtCollisionShape, position: Vector3, rotation: Quaternion): voidN

  • Since Defold 1.13.2

A non-compound collision object's only shape has no child transform and is rejected. The binding normalizes the supplied rotation.

Parameters

  • shape: bullet3d.shape.BtCollisionShape — shape handle
  • position: Vector3 — finite local position
  • rotation: Quaternion — finite non-zero local rotation

bullet3d.shape.set_shape(shape: bullet3d.shape.BtCollisionShape, data: bullet3d.shape.Definition): voidN

  • Since Defold 1.13.2

The table uses the same format as get_shape. Its type must match the existing shape because changing native shape type is not supported. Primitive dimensions must be finite and greater than zero. Hulls require at least four finite vertices. Triangle mesh geometry cannot be changed with this function.

// Increase the dimensions of the first box shape by 50 percent for this instance:
export default defineScript({
  init() {
    const object = bullet3d.get_collision_object("#collisionobject");
    if (object === undefined) return;
    const shape = bullet3d.collision_object.get_shape(object, 1);
    const data = bullet3d.shape.get_shape(shape);

    if (data.type === bullet3d.shape.SHAPE_TYPE_BOX && "dimensions" in data) {
      data.dimensions = data.dimensions.mul(1.5);
      bullet3d.shape.set_shape(shape, data);
    }
  },
});
function init(self)
    local object = bullet3d.get_collision_object("#collisionobject")
    local shape = bullet3d.collision_object.get_shape(object, 1)
    local data = bullet3d.shape.get_shape(shape)

    if data.type == bullet3d.shape.SHAPE_TYPE_BOX then
        data.dimensions = data.dimensions * 1.5
        bullet3d.shape.set_shape(shape, data)
    end
end

Parameters

Constants

bullet3d.shape.SHAPE_TYPE_BOX: number & { readonly __brand: "bullet3d.shape.SHAPE_TYPE_BOX" }N

  • Since Defold 1.13.2

Box shape type Value 1. Shape data contains positive vector3 dimensions in Defold units.

bullet3d.shape.SHAPE_TYPE_CAPSULE: number & { readonly __brand: "bullet3d.shape.SHAPE_TYPE_CAPSULE" }N

  • Since Defold 1.13.2

Capsule shape type Value 2. Shape data contains a positive numeric diameter and positive numeric cylindrical-section height in Defold units.

bullet3d.shape.SHAPE_TYPE_HULL: number & { readonly __brand: "bullet3d.shape.SHAPE_TYPE_HULL" }N

  • Since Defold 1.13.2

Convex hull shape type Value 3. Shape data contains a vertices array with at least four finite vector3 values in Defold units.

bullet3d.shape.SHAPE_TYPE_MESH: number & { readonly __brand: "bullet3d.shape.SHAPE_TYPE_MESH" }N

  • Since Defold 1.13.2

Triangle mesh shape type Value 4. Shape data contains only the type; triangle geometry is read-only.

bullet3d.shape.SHAPE_TYPE_SPHERE: number & { readonly __brand: "bullet3d.shape.SHAPE_TYPE_SPHERE" }N

  • Since Defold 1.13.2

Sphere shape type Value 0. Shape data contains a positive numeric diameter in Defold units.

Types

type bullet3d.shape.BtCollisionShape = Opaque<"btCollisionShape">

type bullet3d.shape.Definition = { type: typeof bullet3d.shape.SHAPE_TYPE_SPHERE; diameter: number; position?: Vector3; rotation?: Quaternion; target_rotation?: Quaternion } | { type: typeof bullet3d.shape.SHAPE_TYPE_BOX; dimensions: Vector3; position?: Vector3; rotation?: Quaternion; target_rotation?: Quaternion } | { type: typeof bullet3d.shape.SHAPE_TYPE_CAPSULE; diameter: number; height: number; position?: Vector3; rotation?: Quaternion; target_rotation?: Quaternion } | { type: typeof bullet3d.shape.SHAPE_TYPE_HULL; vertices: Vector3[]; position?: Vector3; rotation?: Quaternion; target_rotation?: Quaternion }

type bullet3d.shape.ShapeType = typeof bullet3d.shape.SHAPE_TYPE_BOX | typeof bullet3d.shape.SHAPE_TYPE_CAPSULE | typeof bullet3d.shape.SHAPE_TYPE_HULL | typeof bullet3d.shape.SHAPE_TYPE_MESH | typeof bullet3d.shape.SHAPE_TYPE_SPHERE

On this page

Functionsbullet3d.shape.get_collision_object(shape: bullet3d.shape.BtCollisionShape): Opaque<"btCollisionObject" | "btRigidBody">Nbullet3d.shape.get_index(shape: bullet3d.shape.BtCollisionShape): numberNbullet3d.shape.get_local_transform(shape: bullet3d.shape.BtCollisionShape): LuaMultiReturn<[Vector3, Quaternion]>Nbullet3d.shape.get_shape(shape: bullet3d.shape.BtCollisionShape): bullet3d.shape.Definition | { type: typeof bullet3d.shape.SHAPE_TYPE_MESH }Nbullet3d.shape.get_type(shape: bullet3d.shape.BtCollisionShape): bullet3d.shape.ShapeTypeNbullet3d.shape.is_valid(shape: bullet3d.shape.BtCollisionShape): booleanNbullet3d.shape.set_local_transform(shape: bullet3d.shape.BtCollisionShape, position: Vector3, rotation: Quaternion): voidNbullet3d.shape.set_shape(shape: bullet3d.shape.BtCollisionShape, data: bullet3d.shape.Definition): voidNConstantsbullet3d.shape.SHAPE_TYPE_BOX: number & { readonly __brand: "bullet3d.shape.SHAPE_TYPE_BOX" }Nbullet3d.shape.SHAPE_TYPE_CAPSULE: number & { readonly __brand: "bullet3d.shape.SHAPE_TYPE_CAPSULE" }Nbullet3d.shape.SHAPE_TYPE_HULL: number & { readonly __brand: "bullet3d.shape.SHAPE_TYPE_HULL" }Nbullet3d.shape.SHAPE_TYPE_MESH: number & { readonly __brand: "bullet3d.shape.SHAPE_TYPE_MESH" }Nbullet3d.shape.SHAPE_TYPE_SPHERE: number & { readonly __brand: "bullet3d.shape.SHAPE_TYPE_SPHERE" }NTypestype bullet3d.shape.BtCollisionShape = Opaque<"btCollisionShape">type bullet3d.shape.Definition = { type: typeof bullet3d.shape.SHAPE_TYPE_SPHERE; diameter: number; position?: Vector3; rotation?: Quaternion; target_rotation?: Quaternion } | { type: typeof bullet3d.shape.SHAPE_TYPE_BOX; dimensions: Vector3; position?: Vector3; rotation?: Quaternion; target_rotation?: Quaternion } | { type: typeof bullet3d.shape.SHAPE_TYPE_CAPSULE; diameter: number; height: number; position?: Vector3; rotation?: Quaternion; target_rotation?: Quaternion } | { type: typeof bullet3d.shape.SHAPE_TYPE_HULL; vertices: Vector3[]; position?: Vector3; rotation?: Quaternion; target_rotation?: Quaternion }type bullet3d.shape.ShapeType = typeof bullet3d.shape.SHAPE_TYPE_BOX | typeof bullet3d.shape.SHAPE_TYPE_CAPSULE | typeof bullet3d.shape.SHAPE_TYPE_HULL | typeof bullet3d.shape.SHAPE_TYPE_MESH | typeof bullet3d.shape.SHAPE_TYPE_SPHERE