addPhysicsBody
Add physics properties to 3D objects in Spline scenes to enable realistic movement, collisions, and interactions based on mass, body type, and collision shape.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sceneId | Yes | Scene ID | |
| objectId | Yes | Object ID | |
| type | No | Physics body type | dynamic |
| mass | No | Object mass | |
| collisionShape | No | Collision shape | auto |
Implementation Reference
- src/tools/design/physics-tools.js:61-88 (handler)Executes the addition of a physics body to the specified object via the Spline API POST request to /scenes/{sceneId}/objects/{objectId}/physics endpoint.
async ({ sceneId, objectId, bodyType, shape, mass, parameters }) => { try { await fetchFromSplineApi(`/scenes/${sceneId}/objects/${objectId}/physics`, { method: "POST", body: JSON.stringify({ bodyType, shape, mass, parameters, }), }); return { content: [{ type: "text", text: `Added ${bodyType} physics body to object ${objectId}` }] }; } catch (error) { return { content: [{ type: "text", text: `Error adding physics body: ${error.message}` }], isError: true }; } } - Zod schema defining the input parameters for the addPhysicsBody tool, including sceneId, objectId, bodyType, shape, mass, and detailed parameters object.
{ sceneId: z.string().min(1).describe("Scene ID"), objectId: z.string().min(1).describe("Object ID"), bodyType: z.enum(["dynamic", "static", "kinematic"]).describe("Physics body type"), shape: z.enum(["auto", "box", "sphere", "capsule", "cylinder", "convex", "mesh"]) .default("auto").describe("Collision shape type"), mass: z.number().min(0).default(1).describe("Mass in kg (0 for static bodies)"), parameters: z.object({ // Friction properties friction: z.number().min(0).max(1).default(0.5).describe("Friction coefficient"), restitution: z.number().min(0).max(1).default(0.2).describe("Bounciness/restitution"), // Linear properties linearDamping: z.number().min(0).max(1).default(0.01).describe("Linear damping"), angularDamping: z.number().min(0).max(1).default(0.01).describe("Angular damping"), linearVelocity: z.object({ x: z.number().default(0), y: z.number().default(0), z: z.number().default(0), }).optional().describe("Initial linear velocity"), angularVelocity: z.object({ x: z.number().default(0), y: z.number().default(0), z: z.number().default(0), }).optional().describe("Initial angular velocity"), // Collision properties collisionGroup: z.number().int().min(0).max(31).default(0).describe("Collision group (0-31)"), collidesWith: z.array(z.number().int().min(0).max(31)).optional() .describe("Collision groups to collide with (0-31)"), isTrigger: z.boolean().default(false).describe("Is this a trigger volume"), // Constraints fixedRotation: z.boolean().default(false).describe("Lock rotation"), lockAxisX: z.boolean().default(false).describe("Lock movement along X axis"), lockAxisY: z.boolean().default(false).describe("Lock movement along Y axis"), lockAxisZ: z.boolean().default(false).describe("Lock movement along Z axis"), // Advanced properties ccdEnabled: z.boolean().default(false).describe("Enable continuous collision detection"), sleepThreshold: z.number().positive().default(0.005).describe("Sleep velocity threshold"), autoSleep: z.boolean().default(true).describe("Enable automatic sleeping"), }).optional().describe("Physics body parameters"), }, - src/tools/design/physics-tools.js:15-89 (registration)Registers the addPhysicsBody tool on the MCP server with the defined schema and handler.
server.tool( "addPhysicsBody", { sceneId: z.string().min(1).describe("Scene ID"), objectId: z.string().min(1).describe("Object ID"), bodyType: z.enum(["dynamic", "static", "kinematic"]).describe("Physics body type"), shape: z.enum(["auto", "box", "sphere", "capsule", "cylinder", "convex", "mesh"]) .default("auto").describe("Collision shape type"), mass: z.number().min(0).default(1).describe("Mass in kg (0 for static bodies)"), parameters: z.object({ // Friction properties friction: z.number().min(0).max(1).default(0.5).describe("Friction coefficient"), restitution: z.number().min(0).max(1).default(0.2).describe("Bounciness/restitution"), // Linear properties linearDamping: z.number().min(0).max(1).default(0.01).describe("Linear damping"), angularDamping: z.number().min(0).max(1).default(0.01).describe("Angular damping"), linearVelocity: z.object({ x: z.number().default(0), y: z.number().default(0), z: z.number().default(0), }).optional().describe("Initial linear velocity"), angularVelocity: z.object({ x: z.number().default(0), y: z.number().default(0), z: z.number().default(0), }).optional().describe("Initial angular velocity"), // Collision properties collisionGroup: z.number().int().min(0).max(31).default(0).describe("Collision group (0-31)"), collidesWith: z.array(z.number().int().min(0).max(31)).optional() .describe("Collision groups to collide with (0-31)"), isTrigger: z.boolean().default(false).describe("Is this a trigger volume"), // Constraints fixedRotation: z.boolean().default(false).describe("Lock rotation"), lockAxisX: z.boolean().default(false).describe("Lock movement along X axis"), lockAxisY: z.boolean().default(false).describe("Lock movement along Y axis"), lockAxisZ: z.boolean().default(false).describe("Lock movement along Z axis"), // Advanced properties ccdEnabled: z.boolean().default(false).describe("Enable continuous collision detection"), sleepThreshold: z.number().positive().default(0.005).describe("Sleep velocity threshold"), autoSleep: z.boolean().default(true).describe("Enable automatic sleeping"), }).optional().describe("Physics body parameters"), }, async ({ sceneId, objectId, bodyType, shape, mass, parameters }) => { try { await fetchFromSplineApi(`/scenes/${sceneId}/objects/${objectId}/physics`, { method: "POST", body: JSON.stringify({ bodyType, shape, mass, parameters, }), }); return { content: [{ type: "text", text: `Added ${bodyType} physics body to object ${objectId}` }] }; } catch (error) { return { content: [{ type: "text", text: `Error adding physics body: ${error.message}` }], isError: true }; } } );