plupy API reference#

User manual · API home · All types · Operations · Python guides

Python API for editing Plush project data. Run scripts in the editor's Code tab or with Plush --run-python <project> <script.py>. Both use bundled Python. Exported games do not use Python.

Run your first script · Examples · Workspace and imports

Entry points#

Entry point	Type	Purpose
`plupy.data`	Data	Find, create and edit project datablocks without a selection or visible scene
`plupy.context`	Context	Supply temporary targets or use an editor area's captured selection
`plupy.ops.object`	ObjectOps	Move scene uses through an editing operation
`plupy.edit(label)`	edit	Commit a group of edits as one Undo step
`plupy.scripts`	Scripts	Create a C# script file and attach it to an object
`plupy.Project`, `plupy.inspect_scene`	Project, inspect_scene	Read immutable snapshots from an external Python process
`plupy.PlupyError`, `plupy.AmbiguousError`	PlupyError, AmbiguousError	Lookup, validation and session errors

Types by area#

One page per type, generated from the wrapper's docstrings (tools/python/plupy_docs.py), with a heading per member, its signature and how it behaves. Live handles come from the API; do not construct them or import private _live classes. Operations maps every editor operation name (uses.add, the names the editor's assistant uses) to the member that documents it.

Area	Types	Guide
Data	Data, DataCollection, DataBlock, Properties, Mesh, the import collections	Project data
Scenes and uses	Scene, Uses, Use, Transform, SceneCollection, Object	Objects, scenes and uses · Transforms
Components and inputs	Components, Component, ComponentProperties, Pins, Inputs, EvaluatedUse	Components, pins and inputs · Evaluated values
Audio	Sound, SoundSequence, EffectChain, ModulationChain and their collections	Project data
Library	Library, LibraryFolder	Library and model files
Context and operations	Context, ObjectOps, the selection handles	Context and selection · Object operations
Session	edit, PlupyError, Handle	Edit groups · Errors and handle lifetime
Snapshots	Project, inspect_scene	External snapshots

Create and place an object#

import plupy

with plupy.edit("Create crate"):
    scene = plupy.data.scenes.new("Crate scene")
    crate = plupy.data.objects.new("Crate")
    mesh = plupy.data.meshes.new("Crate mesh", primitive="cube")
    crate.components.add("mesh", mesh=mesh)
    placed = scene.objects.add(crate)
    placed.transform.position = (2, 0, 0)

Open Crate scene to inspect the result. One Undo removes this group. No context or selection setup is required. Each run creates new data.

Common rules#

new creates a datablock or organizational folder/collection; add adds an existing object/member.
Removing a scene use or Library entry retains its datablock. delete removes unreferenced data.
IDs identify data; exact names are convenient only when unambiguous.
Direct edits preserve the current scene, selection and Inspector, except removal reconciles deleted targets.
Handles survive Code runs until deleted or the workspace resets/closes. Vectors are immutable tuples; assign a complete property to write it. See edit groups and workspace lifetime.

This reference documents callable APIs only. Missing features and proposals are tracked in Linear, outside the reference.