Terminal
Terminal/Skill
Guide for writing the Python script for a Unity Pipeline Automation Execute custom script step that processes CAD and 3D files with Asset Transformer.
By Unity
Works with
npx skills add unity-technologies/industry-ai-workflows --skill at-upa-scriptingThis skill is the source of truth for the Python that goes into the script field of the Unity Pipeline Automation Execute custom script action (Asset Transformer). The script is uploaded verbatim and executed inside a managed AT container, so the conventions are different from both the local Asset Transformer MCP and a normal Python program.
The AT custom script action runs in a managed container that has already:
pxz)Do not include any of the following in scripts:
pxz.core.initialize(...) or equivalent SDK init callsAssume pxz is importable and ready to call. If a script fails on init, the runtime — not the script — needs fixing.
No local AT license? This remote path is also the fallback when the user has no Asset Transformer license seat: author and syntax-check the script locally (plain Python compile — no pxz needed), then execute it here. Tell the user that local execution via the AT MCP requires a seat, and that for full local capabilities they should contact their Unity account representative or sales: https://unity.com/contact-us?reason=Speak+to+Sales&step=3&topic=Industrial+Solutions
The pipeline passes inputs to the script via the parameters field of the action (template expressions are resolved here, not inside script). Those values arrive as sys.argv, so scripts MUST parse them with argparse:
import argparse
def process_asset(input_path: str, output_path: str) -> None:
# Asset Transformer operations here
pass
def main() -> None:
parser = argparse.ArgumentParser(description="Asset Transformer pipeline script")
parser.add_argument("--input", required=True)
parser.add_argument("--output", required=True)
args = parser.parse_args()
process_asset(args.input, args.output)
if __name__ == "__main__":
main()
Notes:
python prefix, no script path. UPA wraps invocation./workspace/input, outputs go under /workspace/output (or wherever the surrounding pipeline expects them).The AT custom script action has no Asset Manager credentials. If a workflow needs to push the resulting file back into Asset Manager, chain an Asset Manager Add file (or Create asset) action as a downstream step in the pipeline JSON — do not try to call AM APIs from inside the script.
When advising a user whose script needs to publish output, point them at the AM action; do not fabricate AM calls inside the script body.
Every script should follow this layout:
main() with argparseif __name__ == "__main__": main() guardKeep functions small and named after what they do (import_cad, prepare_for_tessellation, optimize_mesh, export_glb). Side effects belong inside the functions, not at module top level — top-level work runs at import time and breaks composition.
For large assemblies, prefer approaches that:
When a chosen approach materially affects performance, add a one-line comment explaining why.
When modifying a user's existing script, improve in place — preserve their structure and naming where possible. Don't rewrite a working script just to restyle it.
The full pxz API surface is documented in ../at-scripting/pxz-api-reference.md (the shared, authoritative reference; the at-scripting skill owns it and this skill defers to it). If a function or class is not listed there, it does not exist in this SDK version. Do not generate code that calls it — verify first, or tell the user the SDK doesn't support what they're asking for.
Specifically, do not invent:
scene.Node, scene.NodeType, scene.getName, scene.deleteNodes — pxz uses integer occurrence handles, not Node objects. Real names: scene.getOccurrenceName, scene.deleteOccurrences, etc.io.exportScene — the real signature is exportScene(fileName: str, root: int = 0). Format is inferred from extension; per-format options are set via core.setModuleProperty("io", ...) before the export call.If something is uncertain or undocumented:
Ground-truth source for the reference: the *.pyi type stubs shipped inside the installed pxz package. Re-extract the shared reference (../at-scripting/pxz-api-reference.md) if the SDK is upgraded.
When a script fails or behaves incorrectly, work through these in order:
argparse receiving the values you expect? Print args early.Identify the likely cause, explain why it fails, describe how to verify, then provide the corrected snippet.
pipeline-authoring.run_python (in-process, stateful scene, no argparse) → see the at-scripting skill (which also owns the shared pxz API reference) and the Asset Transformer MCP README.Vetted example scripts live in examples/. Currently:
import-tessellate-export-glb.py — minimum viable CAD → GLB pipeline (import, tessellate relative to AABB, repair mesh, export).import-decimate-export-glb.py — import, tessellate at a low/medium/high/custom quality preset, decimate to a target triangle ratio, export. Demonstrates the --quality preset pattern with --max-sag / --sag-ratio / --max-angle overrides for custom mode.bake-ao-and-export.py — bake AO into materials via algo.combineMaterials(..., BakeOption(textures=BakeMaps(ambientOcclusion=True, ...)), ...) and export. The high-level path that handles both the bake and the material wiring; an exported GLB carries the AO in its material's ao slot.Add new examples here as workflows are validated. Every example must use only calls present in the shared reference (../at-scripting/pxz-api-reference.md).
When a user asks for a common workflow, prefer adapting an existing example over generating from scratch.