ObjectOps#

Module: plupy · obtained from plupy.ops.object

plupy.ops.object: operations on scene uses (move).

Parameter	Type	Default	Meaning
`delta`	Tuple of 3 or 2 finite numbers	Required	Displacement in world units or local coordinates
`space`	`"world"` or `"local"`	`"world"`	Coordinate space
`targets`	Iterable of `Use`, or `None`	`None`	Explicit targets, otherwise context selection

Tuple of the affected input use handles. Selection and Inspector stay unchanged. One call is one Undo step, or participates in the enclosing plupy.edit. A zero displacement produces no Undo entry when no authored value changes.

World movement skips selected descendants of selected ancestors so displacement is applied once. Local movement edits each selected local position. Shared storage writes are deduplicated; conflicting desired positions fail atomically (squared-distance tolerance 1e-8). Operations edit authored poses. They never redirect a masked channel to its driver; use.evaluated reports the displayed result.

PlupyError for empty targets, mixed/unsupported target kinds, incompatible dimensions, invalid coordinates, stale handles, unrepresentable transforms or conflicting shared writes. Collections and folders are not expanded. A failed call does not silently move only some selected targets.

class ObjectOps

Usage and examples

Members: move · move_2d · settle · bake_wire · drop_to_floor

move#

move(delta, *, space='world', targets=None) -> tuple[Use, ...]

Translate 3D authored placements by an XYZ displacement.

move_2d#

move_2d(delta, *, space='world', targets=None) -> tuple[Use, ...]

Translate 2D authored placements by an XY displacement.

settle#

settle(targets=None, *, seconds=3.0) -> dict

Let placements fall and come to rest with physics, then keep where they landed (Object → Settle physics).

Parameter	Type	Meaning
`targets`	list of Use, optional	Placements to settle; default the context selection. Each is one rigid body around everything it draws.
`seconds`	float	Longest time to simulate (up to 60); it stops sooner once everything is still.

The rest of the scene stays put and is solid where its meshes are drawn. A Rigid Body's mass and friction are used when the placement has one. No scripts run. One Undo step. Returns moved (the uses), seconds simulated, and rested (False if something was still moving when time ran out).

scene = plupy.data.scenes["Main"]
cartons = [u for u in scene.objects if u.name.startswith("Carton")]
plupy.ops.object.settle(cartons, seconds=4)

bake_wire#

bake_wire(start, end, *, slack=0.15, radius=0.012, sides=8, align_ends=True, material=None, name='Wire', scene=None) -> Use

Hang a wire or cable between two points, let it settle over the scene's meshes and bake it into a placed mesh.

Parameter	Type	Meaning
`start`, `end`	(x, y, z) or a `scene.raycast` hit	The ends. A hit dict also gives the surface normal the end leaves along.
`slack`	float	Extra length as a fraction of the straight span: 0 taut, 0.15 a gentle sag, 1 twice as long.
`radius`	float	Tube radius in metres.
`sides`	int	Sides around the tube (3 or more).
`align_ends`	bool	Ends leave along their surface normals (needs hit dicts); off, they hang freely from the points.
`material`	Material, optional	Default: the project's "Wire" material, created dark rubber if missing.

The tube is written to Assets/Models and placed in the scene (default: the context scene) as one Undo step; the wire itself drapes over pipes, ducts and props it meets. Same as the Scene View's Wire tool without the dragging.

scene = plupy.data.scenes["Main"]
a = scene.raycast((0, 3, -2), (0, 0, -1))   # a point on the wall
b = scene.raycast((6, 3, -2), (0, 0, -1))
plupy.ops.object.bake_wire(a, b, slack=0.25, scene=scene)

drop_to_floor#

drop_to_floor(targets=None, *, align=False, max_distance=100.0) -> tuple[Use, ...]

Move placements straight down until what they draw rests on the first surface below, as Scene View End does.

Parameter	Type	Meaning
`targets`	list of Use, optional	Placements to drop; default the context selection. A selected child of a selected parent moves with it.
`align`	bool	Also turn each object's up axis to the surface normal (Alt+End).
`max_distance`	float	How far below to look, in metres (2D: world units).

Surfaces are the drawn meshes (3D) or sprites and text (2D), as click-picking sees them; the dropped placements are ignored. Returns the placements that moved, as one Undo step; those with nothing below keep their pose.

scene = plupy.data.scenes["Main"]
cartons = [u for u in scene.objects if u.name.startswith("Carton")]
plupy.ops.object.drop_to_floor(cartons, align=True)

Object · PlupyError · Scene · Use · edit

Source#

_live.py:2116