Surfaces

Create a display in the 3D world and draw your own text, images or interface on it.

What Are Render Surfaces?#

A Render Surface is a rectangular display attached to a physics body. Draw ordinary 2D content onto it in GameMaker, and BBMOD displays that content in the 3D scene. You can use it for a device screen, dashboard or information panel.

Blender defines where the display sits and how large it is. GameMaker defines what appears on it. The display follows its body as it moves and rotates.

Create in Blender#

Select your JoltPhysics Root and add a Render Surface from Add → JoltPhysics → Helpers. Give it a Key such as dashboard_display; use that same Key to find the display in GameMaker.

Position and Size#

Select the Render Surface to open its settings. Key is the identifier used in code; Display Name is a descriptive label. For the example below, set Key to dashboard_display. Use Position and Rotation to place and orient the display.

Move and rotate the display to fit your object. Set its full width and height in metres using Width and Height, rather than scaling the object with Scale.

The rectangle is centered on its origin and lies in its local XY plane. Its front points along local +Z and its top along +Y. Use the direction guides to face it toward the viewer; the display is one-sided.

Run Validate and export the configuration as Jolt JSON. If you will create the owning body from this same asset, include collision shapes as well: a Render Surface alone does not define a collision body.

Use in GameMaker#

First load the exported asset and create its body as described in Getting Started. The example below assumes asset contains that loaded data, body is a live managed physics body, and your BBMOD renderer is already available. Replace o_control_bbmod_renderer with your project's renderer object if it has a different name.

• Getting Started: export and load an asset›

In the owning object's Create event, after those prerequisites are ready, create and register the display:

display = jolt_asset_create_surface(asset, "dashboard_display", body);
if (is_undefined(display)) {
    show_debug_message(jolt_get_error().message);
} else {
    display.set_resolution(512, 256);
    display.set_update_rate(30);
    display.set_renderer(o_control_bbmod_renderer.renderer);
}

Draw Your Content#

Put this code in Draw Begin, before BBMOD renders the scene. It draws a dark background and the word Ready. Coordinates are in texture pixels, starting at the top-left corner.

if (!is_undefined(display) && display.draw_begin()) {
    try {
        draw_clear(c_black);
        draw_set_color(c_white);
        draw_text(20, 20, "Ready");
    } finally {
        display.draw_end();
    }
}

Draw only when draw_begin() returns true, and finish every successful call with draw_end(). A false result can simply mean the display is not due for a refresh. Keep the block free of changes to render targets or the display's settings.

Display Settings#

Cleanup#

In Clean Up, release the display before destroying its body or stopping the physics world:

if (!is_undefined(display)) {
    display.destroy();
    display = undefined;
}

Technical Notes#

Render Surfaces use the surfaces[] records in JSON v4. Blender stores the placement and dimensions; pixel content, resolution and drawing callbacks are configured at runtime. The current display is opaque, so drawing transparent pixels does not create holes.

Resolution accepts 1–2048 integer pixels per side; update rate accepts 0–1000 Hz. A lost or resized texture needs fresh content at the next successful draw_begin(). Alternatively, set_draw_callback() enables automatic drawing; successful manual drawing replaces that callback. Do not nest drawing blocks. JOLT_DEBUG_SURFACES shows edges and front direction, including hidden valid displays.

API reference#

Public function and method signatures. Call methods on the returned instance; parameters with defaults are optional.

Related guides#

• Migrating existing code›
• Surface input›
• Ragdolls›

Verified operation contracts#

These contracts distinguish units, return values, errors and lifetime according to the current implementation. Check results: false, 0 and undefined can mean different things for different methods.