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.).

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