simvx.core.properties

Typed Property subclasses for editor-visible values.

These subclasses extend :class:simvx.core.descriptors.Property with type-specific metadata so the editor can dispatch the correct widget without relying on name heuristics or tuple-shape guessing. Stored values remain primitive (str, int, tuple) so scene serialisation is unaffected.

The five subclasses are:

• class:

  Colour – RGB/RGBA tuple with optional alpha channel. Also carries a palette of named colour constants (Colour.RED etc.) and factory helpers (Colour.hex, Colour.rgba, Colour.from_255).

• class:

  FilePath – File / resource path with filter and relative base.

• class:

  Multiline – Multi-line string with optional syntax hint.

• class:

  Bitmask – N-bit integer with optional per-bit names.

• class:

  NodePath – Scene-relative node path with optional type filter.

All five accept the existing hint=, group=, on_change=, link=, propagate= kwargs exactly like :class:Property.

Module Contents

Classes

Colour	RGB or RGBA colour property (tuple of floats in [0, 1]).
FilePath	File / resource path property.
Multiline	Multi-line string property with optional syntax hint.
Bitmask	Bit flag integer property with optional per-bit names.
NodePath	Scene-relative node path property.

Data

__all__

API

class simvx.core.properties.Colour(default: tuple = (1.0, 1.0, 1.0, 1.0), *, has_alpha: bool = True, **kwargs)

Bases: simvx.core.descriptors.Property

RGB or RGBA colour property (tuple of floats in [0, 1]).

Also exposes a palette of common colour constants and hex/rgba factory helpers for use anywhere an RGBA tuple is expected.

Example as a Property::

class Light(Node3D):
    tint = Colour((1.0, 0.5, 0.0, 1.0))
    ambient = Colour((0.1, 0.1, 0.15), has_alpha=False)

Example as a palette::

panel.bg_colour = Colour.RED
label.text_colour = Colour.hex("#FF6600")
button.bg_colour = Colour.rgba(0.2, 0.4, 0.8)

Initialization

Create an editor-visible property descriptor.

Args: default: Default value for the property. Mutually exclusive with default_factory. Mutable containers (list, dict, set, bytearray) are rejected here because a single shared instance would alias across every owning object — pass default_factory instead. default_factory: Zero-arg callable invoked the first time each instance reads the property. The result is cached on the instance, matching functools.cached_property and dataclasses.field(default_factory=...) semantics. range: Optional (min, max) tuple for numeric clamping. enum: Optional list of allowed values. hint: Description shown in the editor inspector. link: When True, child values are offset from the parent’s value. propagate: When True, bool/enum Settings inherit disabling values from parents. group: Inspector section name for grouping. Empty string = default “Properties” section. on_change: Name of a bound method to invoke on the owning instance after a successful value change (i.e. when the new value differs from the old). Hooks may fire during __init__ if the Property is passed as a kwarg, so they must be robust to partially-initialised state. Hooks must be O(1) and must not write to other Properties (no recursion guard is enforced). persist: When True, the value is included in SaveManager snapshots. save_version: Optional integer schema version recorded alongside the persisted value.

WHITE

(1.0, 1.0, 1.0, 1.0)

BLACK

(0.0, 0.0, 0.0, 1.0)

RED

(1.0, 0.0, 0.0, 1.0)

GREEN

(0.0, 1.0, 0.0, 1.0)

BLUE

(0.0, 0.0, 1.0, 1.0)

YELLOW

(1.0, 1.0, 0.0, 1.0)

CYAN

(0.0, 1.0, 1.0, 1.0)

MAGENTA

(1.0, 0.0, 1.0, 1.0)

TRANSPARENT

(0.0, 0.0, 0.0, 0.0)

GRAY

(0.5, 0.5, 0.5, 1.0)

DARK_GRAY

(0.2, 0.2, 0.2, 1.0)

LIGHT_GRAY

(0.75, 0.75, 0.75, 1.0)

ORANGE

(1.0, 0.6, 0.0, 1.0)

PURPLE

(0.6, 0.2, 0.8, 1.0)

PINK

(1.0, 0.4, 0.7, 1.0)

__slots__

(‘has_alpha’,)

__set__(obj, value)

static hex(h: str) → tuple[float, float, float, float]

Parse hex colour string '#RRGGBB' / '#RRGGBBAA' into RGBA tuple.

static rgba(r: float, g: float, b: float, a: float = 1.0) → tuple[float, float, float, float]

Create colour from float components (0.0-1.0).

static from_255(r: int, g: int, b: int, a: int = 255) → tuple[float, float, float, float]

Create colour from 0-255 integer components.

__set_name__(owner, name)

__get__(obj, objtype=None)

__repr__()

class simvx.core.properties.FilePath(default: str = '', *, filter: str = '*.*', relative_to: str | None = None, **kwargs)

Bases: simvx.core.descriptors.Property

File / resource path property.

Example::

icon = FilePath("", filter="*.png;*.jpg")

Initialization

Create an editor-visible property descriptor.

Args: default: Default value for the property. Mutually exclusive with default_factory. Mutable containers (list, dict, set, bytearray) are rejected here because a single shared instance would alias across every owning object — pass default_factory instead. default_factory: Zero-arg callable invoked the first time each instance reads the property. The result is cached on the instance, matching functools.cached_property and dataclasses.field(default_factory=...) semantics. range: Optional (min, max) tuple for numeric clamping. enum: Optional list of allowed values. hint: Description shown in the editor inspector. link: When True, child values are offset from the parent’s value. propagate: When True, bool/enum Settings inherit disabling values from parents. group: Inspector section name for grouping. Empty string = default “Properties” section. on_change: Name of a bound method to invoke on the owning instance after a successful value change (i.e. when the new value differs from the old). Hooks may fire during __init__ if the Property is passed as a kwarg, so they must be robust to partially-initialised state. Hooks must be O(1) and must not write to other Properties (no recursion guard is enforced). persist: When True, the value is included in SaveManager snapshots. save_version: Optional integer schema version recorded alongside the persisted value.

__slots__

(‘filter’, ‘relative_to’)

__set__(obj, value)

__set_name__(owner, name)

__get__(obj, objtype=None)

__repr__()

class simvx.core.properties.Multiline(default: str = '', *, min_lines: int = 3, syntax: str | None = None, **kwargs)

Bases: simvx.core.descriptors.Property

Multi-line string property with optional syntax hint.

When syntax='python' the editor uses its code editor widget; otherwise it uses the plain multi-line text editor.

Example::

description = Multiline("", min_lines=4)
script_body = Multiline("", syntax="python")

Initialization

Create an editor-visible property descriptor.

Args: default: Default value for the property. Mutually exclusive with default_factory. Mutable containers (list, dict, set, bytearray) are rejected here because a single shared instance would alias across every owning object — pass default_factory instead. default_factory: Zero-arg callable invoked the first time each instance reads the property. The result is cached on the instance, matching functools.cached_property and dataclasses.field(default_factory=...) semantics. range: Optional (min, max) tuple for numeric clamping. enum: Optional list of allowed values. hint: Description shown in the editor inspector. link: When True, child values are offset from the parent’s value. propagate: When True, bool/enum Settings inherit disabling values from parents. group: Inspector section name for grouping. Empty string = default “Properties” section. on_change: Name of a bound method to invoke on the owning instance after a successful value change (i.e. when the new value differs from the old). Hooks may fire during __init__ if the Property is passed as a kwarg, so they must be robust to partially-initialised state. Hooks must be O(1) and must not write to other Properties (no recursion guard is enforced). persist: When True, the value is included in SaveManager snapshots. save_version: Optional integer schema version recorded alongside the persisted value.

__slots__

(‘min_lines’, ‘syntax’)

__set__(obj, value)

__set_name__(owner, name)

__get__(obj, objtype=None)

__repr__()

class simvx.core.properties.Bitmask(default: int = 0, *, bits: int = 32, names: list[str] | None = None, **kwargs)

Bases: simvx.core.descriptors.Property

Bit flag integer property with optional per-bit names.

Stores an ordinary int. The editor renders a grid of bits toggles arranged as bits // 8 rows of 8.

Example::

collision_layer = Bitmask(1, bits=32, group="Collision")

Initialization

Create an editor-visible property descriptor.

Args: default: Default value for the property. Mutually exclusive with default_factory. Mutable containers (list, dict, set, bytearray) are rejected here because a single shared instance would alias across every owning object — pass default_factory instead. default_factory: Zero-arg callable invoked the first time each instance reads the property. The result is cached on the instance, matching functools.cached_property and dataclasses.field(default_factory=...) semantics. range: Optional (min, max) tuple for numeric clamping. enum: Optional list of allowed values. hint: Description shown in the editor inspector. link: When True, child values are offset from the parent’s value. propagate: When True, bool/enum Settings inherit disabling values from parents. group: Inspector section name for grouping. Empty string = default “Properties” section. on_change: Name of a bound method to invoke on the owning instance after a successful value change (i.e. when the new value differs from the old). Hooks may fire during __init__ if the Property is passed as a kwarg, so they must be robust to partially-initialised state. Hooks must be O(1) and must not write to other Properties (no recursion guard is enforced). persist: When True, the value is included in SaveManager snapshots. save_version: Optional integer schema version recorded alongside the persisted value.

__slots__

(‘bits’, ‘names’)

__set__(obj, value)

__set_name__(owner, name)

__get__(obj, objtype=None)

__repr__()

class simvx.core.properties.NodePath(default: str = '', *, type_filter: type | None = None, **kwargs)

Bases: simvx.core.descriptors.Property

Scene-relative node path property.

Stores a path string (e.g. "../Camera2D"). type_filter is an optional Node subclass used by the editor picker to grey out nodes that would be invalid targets.

Example::

remote_path = NodePath("", type_filter=Node2D)

Initialization

Create an editor-visible property descriptor.

Args: default: Default value for the property. Mutually exclusive with default_factory. Mutable containers (list, dict, set, bytearray) are rejected here because a single shared instance would alias across every owning object — pass default_factory instead. default_factory: Zero-arg callable invoked the first time each instance reads the property. The result is cached on the instance, matching functools.cached_property and dataclasses.field(default_factory=...) semantics. range: Optional (min, max) tuple for numeric clamping. enum: Optional list of allowed values. hint: Description shown in the editor inspector. link: When True, child values are offset from the parent’s value. propagate: When True, bool/enum Settings inherit disabling values from parents. group: Inspector section name for grouping. Empty string = default “Properties” section. on_change: Name of a bound method to invoke on the owning instance after a successful value change (i.e. when the new value differs from the old). Hooks may fire during __init__ if the Property is passed as a kwarg, so they must be robust to partially-initialised state. Hooks must be O(1) and must not write to other Properties (no recursion guard is enforced). persist: When True, the value is included in SaveManager snapshots. save_version: Optional integer schema version recorded alongside the persisted value.

__slots__

(‘type_filter’,)

__set__(obj, value)

__set_name__(owner, name)

__get__(obj, objtype=None)

__repr__()

simvx.core.properties.__all__

[‘Bitmask’, ‘Colour’, ‘FilePath’, ‘Multiline’, ‘NodePath’]