Use#

Module: plupy · obtained from scene.objects[...], scene.objects.add(obj), use.children[...]

A placed object: an object datablock's use in a scene (a root) or under another use (a child), with its own name, transform and input values. An edit to its object changes every use of that object; inputs and the transform are this use's own.

class Use(Handle)

Inherits Handle: its members are documented there.

Usage and examples

Members: local_reference · name · object · owner · parent · scene · active · children · inputs · evaluated · transform · world_transform · transform_2d · world_transform_2d · bounds · remove · duplicate · make_unique

local_reference#

local_reference(root: 'Use')

Return a target relative to root, using stable child-use IDs. This use must be root or its descendant in the same scene. Assign the result to a SceneReference field, custom-data property or exposed input; each consuming runtime object resolves it within its own copy with Entity.Find. The returned value can be read and reassigned unchanged.

name#

name   # read/write

Use label.

object#

object -> Object   # read-only

Referenced definition.

owner#

owner -> DataBlock   # read-only

Scene or shared object storing the use.

parent#

parent -> Use | None   # read-only

Parent occurrence; None at root.

scene#

scene -> Scene   # read-only

Resolving scene.

active#

active -> bool   # read/write

Stored starting activation for this use, defaulting to True. Assigning changes the saved scene through Undo. A resolved inactive use and its descendants stop rendering and gameplay.

A root edit affects that placement; a child edit affects the parent's shared composition everywhere. An optional-child input can override this flag in either direction; parents and collections also gate activation. Read use.evaluated.active for the resolved result. Editing this source leaves its wires connected.

children#

children -> Uses   # read-only

Direct child occurrences.

inputs#

inputs -> Inputs   # read-only

Editable declared use values.

evaluated#

evaluated -> EvaluatedUse   # read-only

Read-only scene values after inputs and wiring; never a destination for authored writes.

transform#

transform -> Transform   # read-only

Writable 3D channels.

world_transform#

world_transform -> Transform   # read-only

Writable 3D channels.

transform_2d#

transform_2d -> Transform   # read-only

Writable 2D channels.

world_transform_2d#

world_transform_2d -> Transform   # read-only

Writable 2D channels.

bounds#

bounds() -> dict

The world-space box around every mesh this use draws (its children's too): a dict of min, max, size and center, each (x, y, z) in metres. A use that draws no mesh raises PlupyError.

The world-space box around every mesh this use draws, its children's included: a dict of min, max, size and center, each (x, y, z) in metres, plus meshes (how many were measured). Scale and parent transforms are applied; a rotated mesh's box encloses its rotated corners. It reads the current state, including changes made earlier in the same edit. A use that draws no mesh raises PlupyError; read its position from use.world_transform.position.

with plupy.edit("Crate on the table"):
    scene = plupy.data.scenes["Main"]
    table = scene.objects["Table"].bounds()
    crate = scene.objects["Crate"]
    size = crate.bounds()["size"]
    crate.world_transform.position = (table["center"][0], table["max"][1] + size[1] / 2, table["center"][2])

The last line assumes the crate's mesh is centred on its origin, as primitives and generated meshes are.

remove#

remove()

Removes the stored use; returns None. Object data remains. Removing a nested use changes its shared owner everywhere. Connected child wires must be disconnected first. Removed selection identities are reconciled; no other selection is made.

duplicate#

duplicate(unique=False)

A new sibling use right after this one, sharing the same object (linked) or, with unique=True, placing a new object whose nested objects are copied too (the editor's Shift+D). One undo step.

Returns a new sibling Use right after this one, copying placement and input values. By default it shares the same object (a linked duplicate, the editor's Cmd/Ctrl+D); with unique=True it places a new object instead, a copy whose nested objects are copied too (the editor's Shift+D), in one undo step. It does not select the duplicate.

make_unique#

make_unique()

Returns the resulting Object after copying the selected definition and any required ancestors for this occurrence. Referenced dependencies remain shared. This is an explicit data copy; accessing a nested child does not otherwise make it unique.

DataBlock · EvaluatedUse · Handle · Inputs · Object · PlupyError · Scene · Transform · Uses · edit

Source#

_live.py:1041