Creating Entities

To place a custom entity in Blender, you first need to define and export it from your Godot project. This page covers both authoring paths and all the property and gizmo features available.

Two Authoring Paths

There are two ways to expose an entity to Blender. Both produce identical output.

Code-path entities still appear in the wizard sidebar, but as read-only entries. To edit them, open the source script.

Entity Wizard

The Entity Wizard lives in the Entities tab of the Godot main screen. It controls which properties an entity exposes to Blender and which gizmos are drawn for each instance in the viewport.

Step 1 - Pick a Source

Click New Definition in the toolbar and choose where to save the new EntityDefinition .tres.

Then pick one of three source modes:

• BuiltIn - select a class from Godot's ClassDB (e.g. OmniLight3D, Area3D). All editor-visible properties are scanned.
• Script - pick a .gd file. Only @export properties are scanned.
• Scene - pick a .tscn file. The wizard scans @export properties on the root node's script.

Script and Scene modes store a UID reference internally, so the .tres stays valid even if the script or scene is moved.

Step 2 - Select Properties

The wizard lists every property found on the source. Check the ones to expose in Blender. Checked properties sort to the top of the list automatically, so frequently used props are always visible without scrolling.

Step 3 - Apply

Click Apply. The resource is saved and the manifest can be regenerated.

Property Types

All basic property types are supported. Blender's property inspector picks an appropriate widget for each.

Source and Destination

source and destination are special string types that link entities together.

• A source property is the entity's name. Other entities address this entity by typing its source value into their destination field.
• A destination property points to another entity by name.

When a destination property is set, Liminal draws a 3D arrow in the viewport from the source entity to the destination entity. This visualises the logic graph and keeps wiring legible at a glance.

The Pick button next to a destination field opens a dropdown listing every source name currently in the scene.

Example. A lever entity with a destination property pointing at a door entity. Pulling the lever in the game opens the door.

Choices

A choices property shows a dropdown in Blender populated at export time. The dropdown is most useful for enums, but you can drive it with any provider that returns a list of label/value pairs.

When the .lm file is imported, Liminal resolves the stored label back to its Godot-native value using a snapshot baked into entities.json - no provider code runs at import time.

Built-in Providers

Example. An ambient sound entity exposes a clip property as choices. The provider scans an audio assets directory for .ogg and .wav files. Level designers pick a clip from the dropdown in Blender.

Custom Providers

Subclass LMChoicesProvider and override get_choices() to return an array of { "label": String, "value": Variant } dictionaries. Save as a .tres file and assign it to any choices property.

class_name MyCustomProvider extends LMChoicesProvider

func get_choices() -> Array[Dictionary]:
    var result: Array[Dictionary] = []
    for f in DirAccess.get_files_at("res://assets/sfx/"):
        result.append({ "label": f.get_basename(), "value": "res://assets/sfx/" + f })
    return result

Gizmos

Gizmos are visual shapes drawn in the Blender viewport to represent an entity's spatial influence, range, or orientation. They are purely cosmetic - they help the level designer see what an entity does without cluttering the scene with real geometry.

Typical uses: a light's radius, a trigger zone's volume, a camera's frustum, a turret's aim cone, a label showing a live property value.

Gizmos live in the entity definition, not in the scene. Adding or changing a gizmo declaration and reloading the manifest in Blender updates every instance at once.

Defining Gizmos

In the wizard's right column, click + Add Gizmo to append a row. Each row has:

• Type dropdown - the shape to draw (see Gizmo Types)
• Style dropdown - wire (default) or solid. solid adds a translucent filled body beneath the wire outline
• Color field - a hex tint. Click to open a color picker, or bind it to a property
• Fill α field - fill opacity (0–1) for solid style and the volume type. Defaults to 0.25
• Type-specific parameter fields - depend on the gizmo type
• Offset X›Y›Z - translation in entity-local Godot space
• Euler° X›Y›Z - rotation offset in entity-local Godot space (XYZ order, degrees)

An entity can have any number of gizmos. They are drawn independently, each with its own type, size, color, and offset.

Gizmo Types

sphere

A wireframe sphere centred on the entity origin.

arrow

A line with an arrowhead pointing along the entity's forward direction (-Z in Godot / +Y in Blender). Use this for facing, aim direction, or signal targets.

cone

A cone opening along the entity's forward direction. Useful for spotlights, view cones, and detection angles.

box

A wireframe axis-aligned box centred on the entity origin (in local space).

frustum

A camera-style frustum: near and far planes connected by four corner rays. Useful for cameras and projectors. Assumes a 16:9 aspect ratio.

billboard

A square at the entity origin that always faces the viewport camera, whichever way you orbit. Use it for point lights, audio sources, spawn points and other entities with no direction of their own, where a sphere would swallow the space around them.

Give it a Texture and the image is the gizmo: it fills the square and no outline is drawn around it, so a spawn point can carry a spawn icon and an ambient sound a speaker. Color tints the image, so a greyscale icon takes the class colour. Without a texture you get the plain square — wire, or translucent under Style solid.

The square keeps a fixed size in world units, so it shrinks with distance like every other gizmo.

volume

A translucent fill of the entity's own mesh body — not a procedural shape. It follows the actual geometry you author (including modifiers and edit-mode changes), so it's the right choice for trigger zones, ambient regions, and other brush-shaped volumes where you need to see the exact extent. Only renders for volume entities; on a non-volume entity it draws nothing. The wire outline comes from the object's own wireframe display.

Volume textures. Pick any texture from your project and the fill carries it as a tiling label instead of a flat tint, so the volume announces what it is at a glance — a trigger brush reads TRIGGER from across the level. This belongs to the entity type, set once here: every volume of that class shows it, and level designers never assign anything.

The texture is projected from the volume's own object space and blended across all three axes, so it lands evenly on walls, floors and caps whatever shape the brush is, and stays locked to the brush when you rotate it.

Texels/m sets density in texels per metre rather than repeats, so the label comes out the same physical size on a doorway-sized trigger and a hangar-sized one. Lower the value to make the lettering larger.

The tint from color multiplies the texture, so per-class colour coding still works, and a greyscale tile takes the class colour cleanly. A volume with no texture set is unchanged.

Sync copies each texture a definition references into the Blender workspace, so any texture in your project works — including ones you keep with your own art.

Making your own labels. The plugin ships a set of ready volume textures (TRIGGER, CLIP, HURT, WATER, LADDER, SOUND, NAV BLOCK) under addons/liminal_editor/gizmo_textures/. For a label of your own, create a new LMIconTexture resource anywhere in your project and set its label — it generates the tile for you, so no image editor is involved:

Keep your own resources outside addons/ — plugin folders are replaced when you update Liminal Editor.

text

A screen-space label drawn at the entity's location (offset by offset if set), in the gizmo's color.

path

A polyline connecting the entity's child objects with line segments. Use it for patrol routes, waypoint chains, and any ordered sequence of points authored as children of the entity. Needs at least two children to draw anything; unlike the other gizmos it ignores offset/euler and instead reads each child's world position.

Gizmo Bindings

Numeric and color gizmo fields can be bound to a checked entity property so the gizmo reflects the value set on each instance rather than a fixed literal.

Binding via Drag-and-Drop

Each gizmo property has a small white dot beside it.

When a binding is active, the field's input control is replaced by a green → prop_name label. Click the × button to clear the binding and return to a literal value.

If the bound property does not exist on the object, or its value cannot be converted to the expected type, the field falls back to its default.

Text Template Tokens

The text gizmo's Text field uses {{prop_name}} template syntax instead of dot bindings. Any number of tokens can appear in the same string:

"Range: {{range}} m"          → "Range: 5.0 m"
"{{name}} ({{state}})"        → "door_01 (OPEN)"

If a referenced property does not exist on the object, the token is left as-is.

Code Path

For entities that manage their own exports in script, override _export_entity_props() and optionally _export_entity_gizmos():

func _export_entity_props() -> Array[Dictionary]:
    var ret = super()
    ret.append_array([
        { "name": "delay" },
        { "name": "target",     "type": "destination" },
        { "name": "targetname", "type": "source" },
        { "name": "sound_cue",  "choices": preload("res://my_sound_provider.tres") },
    ])
    return ret

func _export_entity_gizmos() -> Array:
    return [
        {"type": "sphere", "bindings": {"radius": "detection_range"}, "color": "#FF4400"},
        {"type": "arrow",  "length": "2.0"},
        {"type": "text",   "text": "Range: {{detection_range}}"},
    ]

Rules for _export_entity_props():

• Every entry must have a "name" key matching a property on this node.
• "type" overrides the inferred type. Valid values: "source", "destination", "choices", or any Godot type name string.
• "choices" takes an LMChoicesProvider instance (preloaded .tres or constructed inline).
• Omit both "type" and "choices" to use the property's inferred Godot type.
• For Object-typed properties (e.g. @export var preset: SoundPreset), a "choices" entry is required.

Applying Changes

Any change to an entity definition - via the wizard or in code - requires regenerating the manifest before Blender sees it.