ComponentProperties#

Module: plupy · obtained from component.props

A component's fields as a mapping (component.props): read, write and reset the stored values, including script fields and datablock references.

Expression	Result
`props[key]`	Stored value, or known default/inherited value when unset; `None` when unknown/unset
`props[key] = value`	Validate and store a value through an undoable authoring command
`for key in props`, `len(props)`	Supported property keys and count
`props.reset(key)`	Remove the stored field, restoring default/inheritance; returns `None`
`props.pin(key)`	Compatibility accessor for `component.pins.pin(key)`

Built-in keys retain their registered spelling, such as "render2D.tint"; a write or reset may drop the component prefix ("tint") when that names exactly one property. Script keys are their C# field/property names, such as "Speed". Integer fields require whole numbers within their CLR range; enum fields accept exact declared names. Colors use "#RRGGBB". Unknown read keys raise KeyError; invalid writes/reset raise PlupyError. A field without a pin raises KeyError through pin(). Resetting "mesh.asset" is rejected; remove the Mesh Renderer component instead.

An assignment equal to the default remains an authored value. Reset removes that value; it does not copy the current default into storage. None is not a clearing command: use reset(). Constructors, getters and other gameplay code are never executed to discover defaults. A known default comes from a constant script initializer, DefaultValue attribute or registered field metadata; it is not a prediction of the value after gameplay starts.

Assign typed datablock handles, not IDs, names or storage dictionaries. Reads return datablock handles for existing targets. Supported script reference types include AssemblyReference (object), SceneAssetReference (scene), EffectReference (effect), SoundReference (sound), SequenceReference (soundSequence) and CollisionLayerReference (collisionLayer). Wrong types, deleted handles and handles from another session are rejected.

# Requires an existing C# component with an AssemblyReference field named Template.
component.props["Template"] = plupy.data.objects["Crate"]
component.props.reset("Template")

class ComponentProperties(Mapping)

A read-only mapping protocol (x[key], for key in x, len(x), key in x, .get, .keys(), .items()); writes are listed below when supported.

Usage and examples

Members: in_scene · schema · Iteration · Length · Indexing · Assignment · reset · pin

in_scene#

in_scene(scene: Scene) -> ComponentProperties

Resolve scene-relative references in an explicit scene; no editor context changes.

Returns another property mapping that resolves scene-relative references in the supplied scene. It does not select a window, set plupy.context, move the Inspector or modify data.

SceneReference stores an occurrence ID relative to the scene in which gameplay runs. Assign a Use handle; its scene validates the target and is recorded with it, so the assignment reads back anywhere. An older reference stored without a scene needs in_scene() to read, because a shared definition can be used in several scenes. With a bound mapping, assignments must also belong to that scene. The same stored ID may resolve differently in different scenes. Missing targets raise PlupyError on mapping reads; schema() instead reports readable=False and an error. An unset reference reads as None.

# Requires a script component named Mover with a SceneReference field named Target.
import plupy

scene = plupy.data.scenes["Main"]
component = plupy.data.objects["Platform"].components["Mover"]
props = component.props.in_scene(scene)
props["Target"] = scene.objects["Destination"]
print(props["Target"].world_transform.position)

Scene references are also Nodes pins (wireable). Per-use differences still require the engine's declared input model where supported; assigning this field edits the shared component definition.

schema#

schema() -> tuple[dict, ...]

Returns current property descriptions, including staged edits.

Field	Meaning
`key`, `name`, `label`	Exact mapping key (`name` repeats it for compatibility) and display label
`kind`	`Number`, `Text`, `Boolean`, `Color` or `Reference`
`value_type`	C# script value type name, such as `Int32` or `SceneReference`; `None` for registered built-ins
`target_type`	Datablock type, `"use"` for a scene occurrence, `"animationSlot"` for a clip slot, or `None`
`value`	Same source value as mapping access, when `readable` is true
`is_set`	Field exists in authored storage, independently of its value
`has_default`, `default`	Whether a default is known, and its value; a known default may itself be `None`
`readable`, `error`	Whether the value resolves; an unresolved scene reference supplies an explanation
`default_error`	Explanation if a scene-relative default cannot resolve
`choices`	Enum choices (`value`, `name`), or clip choices with `binding` and `controller` datablock handles
`min`, `max`, `whole`	Declared numeric constraints; absent bounds are `None`
`wireable`, `pin`	Whether the graph currently provides a pin, and that handle or `None`

An empty choices tuple does not mean read-only. Datablock references use target_type and the matching data collection. Clip choices come from the owner's binding first, then scene-reference targets, then descendants when an explicit scene is supplied. A clip value is a nonempty slot ID string; the API does not guarantee that gameplay will play that slot on the same object. Use the choice's controller/binding to inspect where it is declared. Imported clip labels are not slot IDs.

Iteration#

for item in x

The supported property keys.

Length#

len(x)

How many properties the component supports.

Indexing#

x[key]

The stored value, or the known default or inherited value when unset (None when unknown). KeyError for an unknown key; PlupyError for a scene reference that does not resolve.

Assignment#

x[key] = value

Validate and store a value through an undoable edit; an invalid value raises PlupyError. Every use of the owning object sees it.

reset#

reset(key)

Remove the stored field so the default or inherited value applies again. None is not a clearing value; use this.

pin#

pin(key)

Wiring accessor retained for scripts that used props.pin().

Datablock · Mesh · PlupyError · Scene · Use · edit

Source#

_live.py:1665