Utility Scripts
Introduction
Optional helpers that simplify common gameplay tasks without becoming part of the extension's physics core.
Utility Scripts are convenience features built around the public JoltPhysics API. They combine several lower-level operations into a focused, reusable workflow so projects can implement familiar interactions with less repeated GML code. The native simulation, bodies, queries and collision rules remain the authoritative foundation beneath them.
What belongs here#
- A helper solves a practical gameplay problem by coordinating existing core features rather than defining a new fundamental physics primitive.
- It may provide validation, sensible defaults, result aggregation or managed lifetime behaviour that would otherwise be repeated in individual projects.
- Using a helper is optional. The same underlying behaviour can still be assembled directly from the relevant public body, query, force and world APIs.
- Helpers follow the same public Z-up coordinate system, collision layers, managed error reporting and resource-validity rules as the rest of JoltPhysics.
Core API and utility scripts#
| Area | Responsibility |
|---|---|
| Physics core | Owns worlds, bodies, shapes, simulation steps, collisions, constraints and direct physics operations. |
| Utility Scripts | Compose those operations into optional higher-level gameplay tools with a smaller and more convenient interface. |
| Your project | Chooses whether a helper fits the required behaviour and remains responsible for input, game rules, effects and presentation. |
Available helpers#
Physical Controls has its own category in this tree: begin with Overview and Quick Start. Its GML interface manages native mechanisms within the normal simulation step; you do not update each control from a game Step event.
| Helper | Purpose |
|---|---|
| jolt_control_* / JoltControl | Nine physical controls: button, lever, pedal, slider, knob, pull handle, joystick, wheel and crank; outputs, return, locking, resistance, detents and continuous motors. |
| jolt_explosion | Finds eligible bodies in an area and applies a filtered radial or directional impulse. |
| jolt_penetration_target / jolt_penetrator_tip | Physical tip insertion and extraction with directional resistance, a depth limit and actual-entry events. The Body Penetration subsection provides the full guide and API. |
| jolt_grabber | Creates a managed, force-limited point grabber for picking up and moving Dynamic bodies. |
| jolt_conveyor | Turns a Static or Kinematic body's upper surface into a physical conveyor belt. |
| jolt_scale | Creates an owned physical load-cell platform that measures solver reaction force and equivalent load. |
| jolt_socket / jolt_socket_group | Defines invisible docking points, physical attraction, and one managed connection between two bodies. |
| JoltCharacter.attachment_attach | Makes a CharacterVirtual follow a rigid body's complete local transform for seats, vehicles and moving machinery. |
| body.data | Stores project-owned gameplay metadata directly on a managed JoltBody wrapper. |
| jolt_closest_point | Finds the nearest real collision surface to a world-space point. |
When to use a helper#
- Use a helper when its documented behaviour and limits match the interaction your game needs.
- Use the lower-level API when you need a different force model, query strategy, lifecycle or result format.
- Read the helper's own page before use because each utility documents its defaults, eligible targets, performance costs and failure contract separately.