Blender Addon

The Plume3D Blender addon lets you attach references to a Wren class and TOML config on objects or collections. Config and scripts live in your project (source control); the .blend file stores only the references (config path, script path, class name).

Prerequisites

Download and install Blender 5.0 (or the version matching the addon build) from the official Blender release index:

Blender releases → Blender 5.0

Pick the installer for your OS (Windows, macOS, Linux). The addon is built for Blender 5.0; other versions may not be compatible.

Download the Plume3D addon after Blender is installed, then follow the installation steps below.

Pipeline: config and scripts outside .blend

In the project (source control)

• TOML config files (e.g. radio.toml) — Define [Radio] and properties. The addon stores the path, not the file contents.
• Wren scripts (e.g. main.wren or scripts/radio.wren) — Define one or more classes. The addon stores the script path and class name so the engine knows which file to load and which class to use for the object/collection.

In the .blend (addon UI)

• Config path (e.g. radio.toml) — Path to the TOML file in the project. Not embedded; the engine loads this from the project when loading the .blend.
• Script path (e.g. scripts/radio.wren) — Path to the Wren script in the project. Not embedded; the engine loads it at runtime.
• Class name (e.g. Radio) — Which class in that script to use. Required because a script can define multiple classes.
• Node Id — Stable identifier for this node within an instantiated hierarchy. The root instance exposes .nodes[node_id] so script code can use .nodes[node_id] to access child nodes.
• Tags (named layers) — Layer names are defined in your app’s game.toml [Physics] section as tag_layers. Set Game Config Path (on the root collection) to that game.toml so the addon shows these names as checkboxes. Used for raycast and gameplay filtering.
• Collision Layers (named layers) — Layer names are defined in game.toml [Physics] as collision_layers. Same as Tags: set Game Config Path so the addon shows the names. Used for physics collisions and raycast inclusion/exclusion. See Configuration (game.toml) for the full Physics section and collision matrix.

Root-only (paths): Only the root of an instantiation gets Class Name, Config Path, and Class Path. If any ancestor (object parent or collection hierarchy) has a class configured, the addon shows only Node Id and Tags / Collision Layers for the child; the Paths section is hidden and paths are inherited from the parent.

When loading a .blend, the engine:

1. Reads references from the .blend (config path, script path, class name per object/collection).
2. Validates that the config path and script path exist in the project and that the class exists in the script. Raises a runtime exception if not found.
3. Loads the TOML from the project (e.g. Config.load("radio.toml")).
4. Loads the script (if not already loaded) and hooks the object/collection to the specified class. Lifecycle: engine calls init() on create, update(dt) each frame, destroy() on remove (no-op if the method is not defined).

Install

1. In Blender: Edit → Preferences → Add-ons → Install…
2. Option A — single file: Select plume3d_wren.py (from the extractedplume3d_blender_5_0.zip).
3. Option B — zip: Use the plume3d_blender_5_0.zip from the Downloads page then select that zip.
4. In the addon list, set the category to Development or search for Plume3D, then enable the addon.
5. If it doesn’t appear: use Option A (install only plume3d_wren.py), restart Blender, and search again for “Plume3D”.

Tag and Collision layer names are defined in your app’s game.toml in the optional [Physics] section (tag_layers and collision_layers). Set Game Config Path on the root collection to your game.toml so the addon can show those names in the UI. See Configuration (game.toml) for how to set up Physics.

Save required for the engine

The engine reads class names and node IDs from custom properties (ID properties) in the .blend file. The addon writes your Wren Script Config into these custom properties when you save (and when you open a file).

After configuring Plume3D on objects/collections, save the .blend (File → Save or Ctrl+S / Cmd+S). Until you save, the engine will not see classes (e.g. Radio) and instantiate("Radio", ...) will return null.

1. Open your .blend in Blender with the Plume3D addon enabled.
2. Configure Wren Script Config on the root collection and objects as needed.
3. Save the file (File → Save). The addon writes config to custom properties on save.

Use

1. In Blender, open the 3D Viewport and press N to open the sidebar (or use the arrow tab on the right).
2. Click the Plume3D tab. The panel is context-sensitive: it shows the Wren config for whatever you have selected in the Outliner.
3. Object: Select an object in the Outliner or viewport. The panel shows Object: [name] and its config. Enable Enable Wren Script Config, then set Config Path, Class Path (script file), and Class Name. Use the folder/file icons to browse or create files.
4. Collection: Select a collection in the Outliner (click the collection name). The panel shows Collection: [name] and its config. Edit Config Path, Class Path, and Class Name the same way.
5. Class Path is the path to the .wren script that contains the class. Class Name (e.g. Radio) is the class the engine will use. The engine validates that the class exists in the script at load; runtime exception if not found.
6. Node Id / Tags / Collision Layers: Set Node Id so the instantiated root can look up this node via .nodes[node_id]. Tags and Collision Layers appear as named checkboxes; the layer names come from your game.toml [Physics] section (tag_layers and collision_layers). Set Game Config Path on the root collection to your game.toml so the addon shows these names. See Configuration (game.toml).

Engine side

• Load .blend: The engine reads from the .blend config_path, script_path, and class_name per object/collection (references only).
• Validation: When loading a .blend, the engine checks that each referenced config path and script path exist in the project and that class name exists in the script. Raises a runtime exception if not found.
• Load config: The engine loads the TOML from the project using config_path — the file is the source of truth.
• Load script / class: The engine loads the script from the project using script_path and uses class_name to select which class to instantiate.
• Lifecycle: The engine tries to call init() on create, update(dt) each frame, destroy() on remove; no-op if the method is not defined.

For loading blends in code, see Resource.loadBlend and BlendResult.instantiate.