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 4.2 or newer (Blender 5.0 recommended) from the official Blender release index:

Blender releases → Blender 5.0

Pick the installer for your OS (Windows, macOS, Linux). The addon requires Blender 4.2+ and also ships an extension manifest for the Blender Extensions platform.

Email hello@wyldmagic.gg to request 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. The search button next to the field lists the classes declared in the referenced script.
• 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. Node ids must be unique — the panel’s Validate button checks this.
• Shader Name — Optional Slang shader module key for the object (resolution order: material shader > object shader > default).
• 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. When no game.toml is configured, fallback names come from the addon preferences.
• 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. The default mask is 1 (the engine’s “Default” layer), so untouched objects keep colliding. 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, collection hierarchy, or a collection-instance Empty) has Enable Wren Script Config set, the addon shows only Node Id, Shader Name, and Tags / Collision Layers for the child; the Paths section is hidden and inherited from the ancestor. If a child still carries old root config, the panel offers a one-click Clear Overridden Config.

Paths are project-relative (forward slashes on every OS) and must live inside the .blend’s project — the directory tree containing game.toml. Picking a file from another project is rejected, and creating a new file never overwrites an existing one.

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 extracted addon zip).
3. Option B — zip: Select the addon zip directly. The zip must contain the addon folder (holding __init__.py, plume3d_wren.py, and blender_manifest.toml) at its root, not loose files.
4. Option C — extension (Blender 4.2+): Edit → Preferences → Get Extensions → Install from Disk → select the zip (the addon ships a blender_manifest.toml).
5. In the addon list, set the category to Development or search for Plume3D, then enable the addon.

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 — only on objects/collections that actually carry config; everything else is left untouched. The panel also has a Write Config to .blend button to sync on demand.

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. Press Validate Plume3D Config to catch problems (missing files, bad TOML, class not in script, duplicate node ids) before saving.
4. 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).
7. Multi-select: select several objects/collections in the Outliner to batch-toggle tag/collision layers across the whole selection (a dash icon marks a mixed bit).

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.