Script Properties¶

Script properties are designer-tunable values stored on each ScriptEntry and edited in the Properties window. They serialize with the scene and sync into runtime script instances on play and export.

Overview¶

At runtime, ScriptProperty::syncToMember() (C++) or direct field injection (Lua) applies Properties values before init() runs.

C++ DPROPERTY macro¶

Defined in engine/core/script/ScriptProperty.h:

#define DPROPERTY_1(DisplayName) public:
#define DPROPERTY_2(DisplayName, Type) public: /* @DPROPERTY_TYPE: Type */
#define DPROPERTY(...) GET_DPROPERTY_MACRO(__VA_ARGS__, DPROPERTY_2, DPROPERTY_1)(__VA_ARGS__)

The macro expands to public: plus an optional /* @DPROPERTY_TYPE: ... */ comment for the editor parser. Place it immediately before the member variable — no other declarations between the macro and the member.

Basic examples¶

DPROPERTY("Speed")
float speed = 5.0f;

DPROPERTY("Target Position")
doriax::Vector3 targetPosition = doriax::Vector3(0, 0, 0);

DPROPERTY("Mesh Color", Color4)
doriax::Vector4 meshColor = doriax::Vector4(1, 1, 1, 1);

DPROPERTY("Follow Target")
doriax::Object* followTarget = nullptr;

Syntax forms¶

The editor regex expects this pattern:

DPROPERTY("Label")
Type memberName = defaultValue;

Type inference priority¶

1. Explicit second argument: DPROPERTY("X", Color4)
2. Comment annotation: /* @DPROPERTY_TYPE: Color4 */
3. C++ type inference (see table below)

Supported C++ property types¶

Entity reference pointers¶

Pointer properties store an EntityReference { entity, sceneId } in serialized data, not a raw C++ pointer. At runtime:

• C++ — resolved when the script instance is created.
• Lua — Pass 2 of initializeLuaScripts resolves to a Lua script instance (if the target has a matching enabled script) or a typed wrapper (Object, Mesh, etc.).

Supported pointer types for entity references include all gameplay wrappers listed in LuaBinding::pushEntityHandleByType (Object, Mesh, Camera, Light, Sprite, Body2D, Action, etc.).

Supported default values¶

DPROPERTY("Enabled")
bool enabled = true;

DPROPERTY("Lives")
int lives = 3;

DPROPERTY("Speed")
float speed = 5.0f;

DPROPERTY("Name")
std::string name = "Player";

DPROPERTY("Offset")
doriax::Vector2 offset = doriax::Vector2(1, 2);

DPROPERTY("Target")
doriax::Vector3 target = doriax::Vector3(0, 3, 0);

DPROPERTY("Tint", Color4)
doriax::Vector4 tint = doriax::Vector4(1, 1, 1, 1);

Non-null pointer defaults are not supported. Use nullptr and assign the target in the Properties.

Lua script properties¶

Declare properties in the table returned by your Lua module:

local Door = {
    properties = {
        { name = "openSpeed", displayName = "Open Speed", type = "float", default = 2.5 },
        { name = "startsOpen", displayName = "Starts Open", type = "bool", default = false },
        { name = "linkedDoor", displayName = "Linked Door", type = "entity", default = nil }
    }
}

function Door:init()
    print(self.openSpeed, self.startsOpen)
end

return Door

Lua property fields¶

Supported Lua type strings¶

For entity references, the code editor picks the property type from the referenced entity: it prefers an enabled Lua script class name when present, otherwise the wrapper type detected from components (Object, Mesh, Camera, etc.).

Insert entity references by drag and drop¶

The fastest way to declare an entity reference property is to drag the entity from the Structure panel into the script file open in the Code Editor. This works for both Lua files and C++ headers, and does three things at once:

1. Inserts the declaration at the right place — a new entry in the Lua properties table, or a DPROPERTY line plus pointer member after the last existing DPROPERTY in the C++ header.
2. Picks the type from the dropped entity — the entity's script class name if it has an enabled script of the matching language, otherwise the wrapper type detected from its components (Object, Mesh, Camera, etc.). For C++ subclass types the editor also adds the missing #include.
3. Assigns the value — every entity already using this script gets the dropped entity linked as the property value, so it shows up wired in the Properties window immediately.

The property name is derived from the entity name (camelCase), with a numeric suffix if the name is already taken.

{
    name = "mainCamera",
    displayName = "Main Camera",
    type = "Camera",
    default = nil
}

DPROPERTY("Main Camera")
doriax::Camera* mainCamera = nullptr;

Runtime sync¶

ScriptProperty (engine/core/script/ScriptProperty.cpp):

C++ scripts store memberPtr during parsing. Lua scripts store luaRef to the instance table field.

Properties behavior¶

1. Editor parses script headers / Lua modules when a ScriptEntry is added or the file changes.
2. New properties are appended; existing properties with the same name and type keep their edited values.
3. Property edits go through undoable PropertyCmd commands.
4. Values serialize into scene YAML with the entity's ScriptComponent.

The integrated code editor can insert DPROPERTY blocks (C++) or properties entries (Lua) from templates.

ScriptPropertyType enum¶

enum class ScriptPropertyType {
    Bool, Int, Float, String,
    Vector2, Vector3, Vector4,
    Color3, Color4,
    EntityReference
};

Values are stored in a std::variant (ScriptPropertyValue).

Common mistakes¶

Editor tooling reference¶

Next steps¶

• Creating Scripts — attach scripts and understand lifecycle
• Events — react to input and gameplay with event handlers
• ScriptBase — C++ script base class