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">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): voidN
bullet3d.shape.get_collision_object(shape: bullet3d.shape.BtCollisionShape): Opaque<"btCollisionObject" | "btRigidBody">N
- Since Defold 1.13.2
Get the owning collision object.
Parameters
shape:bullet3d.shape.BtCollisionShape— shape handle
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
shape:bullet3d.shape.BtCollisionShape— shape handle
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
shape:bullet3d.shape.BtCollisionShape— shape handle
Returns
position:Vector3— local positionrotation: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
shape:bullet3d.shape.BtCollisionShape— shape handle
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
shape:bullet3d.shape.BtCollisionShape— shape handle
Returns
type:bullet3d.shape.ShapeType— collision shape type
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
shape:bullet3d.shape.BtCollisionShape— shape handle
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 handleposition:Vector3— finite local positionrotation: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
endParameters
shape:bullet3d.shape.BtCollisionShape— shape handledata:bullet3d.shape.Definition— typed shape geometry in Defold units
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.