Assembly Workflow

The assembly workflow is how foliage, canopies, and other collections of branches are placed onto trees in Natsura. It is the default tool for foliage placement, replacing the cluster decoration for most production cases. It's the workflow that realizes the Leaves, Foliage & Canopies concept.

Visual pending.

The workflow has two main parts: the Assembly Resource, which prepares a library of rigged assemblies for use, and the Assembly Decoration, which places those assemblies onto a tree with full shaping and selection control. The design goal of the workflow is to extract maximum variation from a predefined library of assets while keeping placement and shaping fast enough to iterate on in close to real time in the viewport.

The assembly decoration is the most mature of Natsura's decoration nodes, and indicates the direction the rest of the decoration system is heading. The design history behind the move from the cluster decoration to the assembly decoration is documented separately in From the Cluster Decoration to the Assembly Decoration. For the broader decoration system context, see Decorations.

Two routes through the workflow

Like Natsura's other major workflows, the assembly workflow supports both a high-level wrapper route and a granular step-by-step route.

High-level route: Assembly Resource + Assembly Decoration. The Assembly Resource wraps the internal toolchain (import, pivot editing, rigging, packing, edit-after-rig, visualisation) into a single node that takes one of several input formats (a simulated Natsura tree, a USD or BGEO file, raw SOPs geometry) and produces a ready-to-use library. The Assembly Decoration then plugs the library onto a tree with placement, trait-based selection, rig-level effectors, and density-based removal. This is the recommended starting point, and the route most productions stay on.

Granular route: the constituent utilities at the top level. The internal toolchain (Import Assembly, Pivot Edit, Build Assembly Rig, Assembly Pack, Assembly Edit, Visualize) can be placed as individual nodes outside the Assembly Resource wrapper. Use this route when the wrapper isn't the right shape: when rigging defaults need tuning that the wrapper doesn't expose, when intermediate output of one step feeds something other than the next step, or when authoring a custom library-build pipeline. Classify can also be used standalone (rather than embedded in the decoration's classification gizmo) to split a library into sub-libraries or to apply different trait assignments for different parts of a tree.

Why assemblies

The unit you're working with matters. The cluster decoration's primitive was "deform a mesh to follow a curve", which implies a flat mesh as the input and gives you a deformed clone at every placement. The assembly decoration's primitive is "place a pre-rigged assembly at a point", which preserves instancing across the placement and gives you assemblies that already animate and deform together as a unit.

The shift unlocks:

• Pre-rigged hierarchies as first-class inputs. Branches with leaves that can sway, sub-clusters that rotate as a group, assemblies that carry their own pose and behaviour into the placement.
• Real variation from real difference. Twenty-five distinct assemblies in a library produce twenty-five visibly distinct placements; twenty-five deformed clones of five inputs do not.
• Iteration without re-running the simulation. All shaping lives on the decoration; finishing foliage doesn't trigger a simulation rebuild.

Anatomy of an assembly

An assembly is a hierarchy of packed instances. The expected input shape is a set of branches: collections of instances whose pivots are placed at the base of where each instance attaches to its parent branch or trunk. This applies to buds and leaves too: their pivots should be at the base where they connect to their stem.

The Assembly Resource attempts to automatically generate Natsura's specific assembly rig from the input geometry. Auto-rigging succeeds for most well-formed input setups, provided the geometry is at an appropriate scale.

The assembly workflow

1. Build or import parts

Use the Assembly Resource to prepare a library of rigged assemblies. The resource accepts several input formats:

• The output of another simulate (a Natsura simulated tree).
• A USD file.
• A BGEO file.
• A direct SOPs input.

The resource attempts to auto-rig the input. When auto-rigging fails (most often because pivots are not at the base of branches), the resource exposes an interactive edit pivots state. Press Enter on the node to enter the state, then manually correct pivot positions. Once pivots are correct, auto-rigging succeeds on the next cook.

The resource also has an edit assembly state: a second interactive mode for rotating and deforming assemblies after rigging, and for fixing minor connectivity issues between sub-parts.

When the input is the output of another simulate, a separate suite of controls handles converting a simulated Natsura model into valid assembly geometry.

Building a library from a simulate. Where the Assembly Resource prepares a library from imported geometry, Rig to Assembly takes a simulated Natsura module, a branch cluster grown and decorated in its own Simulate, and breaks it down into rigged instances. This is the bridge that lets you build a branch module once (procedural growth plus prefab instances) and then reuse it as a single decoration part across a larger tree. Wire both of the source Simulate's outputs (geometry and rig) into Rig to Assembly, optionally use its Carve and Fuse Threshold controls to build larger composite modules, then feed the result into the library input of an Assembly Decoration on the destination tree. The same step appears on screen in Your First Tree §9.

2. Place with Assembly Decoration

Plug the Assembly Resource into the library input of an Assembly Decoration. The decoration spawns assemblies at points on the tree's geometry:

• Tips. End points of branches.
• Intersections. Where branches meet.
• Internodes. Along the length of branches.
• Custom groups. Any point group defined upstream.

Density is configurable: the core skeleton can be resampled to spawn at higher or lower frequencies. Masking is supported via mapping, so the spawn distribution can be driven by any attribute on the tree.

All parameters on the assembly decoration are mappable, just like parameters in the core system. The shaping interface is the same one artists already know from the grow.

3. Select with the trait system

The trait system decides which assembly from the library goes where on the tree. A trait is an attribute that lives on both sides of the workflow: on the tree's geometry where assemblies will spawn, and on each assembly in the library. At placement time, the decoration matches assemblies to spawn points by comparing trait values. If both the tree and an assembly carry a height attribute, the assembly will spawn at the heights on the tree that match its trait value. Same for angle: an assembly tagged with a high angle value will spawn on the upward-pointing parts of the tree.

Traits are not limited to geometric attributes. Any attribute can be a trait: age, health, project-specific concepts. As many traits as the project needs can be defined.

The classify tool is an interactive viewport gizmo embedded directly in the assembly decoration: press Enter on the decoration to enter its classification state while the tree is displayed. The viewport shows the tree alongside a graph where each assembly in the library appears as a draggable point. Dragging an assembly toward a higher value on a trait axis causes it to spawn more on the parts of the tree where that trait is high. Updates are close to real-time, so the tree visibly redistributes as parts are dragged.

Trait-based classification can also be exposed as a standalone Classify node placed between the Assembly Resource and the Assembly Decoration. Use a standalone classify node to split a large library into sub-libraries that flow into different assembly decorations, or to apply different trait assignments for different parts of a tree.

4. Add rig-level effectors

Effectors on the assembly decoration modify the placement and pose of assemblies on the tree. Because deformation is applied through the assembly's rig (rigid rotation of rig joints, not per-vertex deform), instancing is preserved across the modification.

The amount of usable variation depends on the rig. A small or simple rig produces stiff-looking deformation. A larger assembly with a more developed rig can produce a wide range of variation from a single source asset: the same assembly can point upward at the top of the tree, level toward the sky, lean toward a magnet, all from one library entry.

5. Final density and removal

Removal is a density-based pruning pass that runs after placement. It looks at the local density of placed assemblies and removes individual sub-components from over-dense regions, producing additional visual variation in the final result. If a single placed assembly contains many sub-parts, removal reaches into the assembly and prunes sub-parts in dense areas rather than discarding the assembly as a whole.

6. Rig (when needed) and export

Use Build Assembly Rig when an assembly hierarchy needs to be rigged for animation or wind. Export proceeds through the standard pipeline (Nanite Skeletal Assembly for Unreal, USD output, etc.), with instance relationships preserved through the chain.

The toolchain

The Assembly Resource is a wrapper that contains a set of utilities. Diving into the resource exposes the internal toolchain:

• Import Assembly. Brings the source geometry into the workflow.
• Pivot Edit. Hosts the edit-pivots interactive state.
• Build Assembly Rig. Performs the auto-rigging. Has settings; defaults are appropriate for most cases.
• Assembly Pack. Packs the rigged assemblies in the form downstream nodes consume.
• Assembly Edit. Hosts the edit-assembly interactive state.
• Visualize. A visualisation node that shows the animated assemblies.

The utilities can also be used at the top level, outside the assembly resource wrapper, for a more granular step-by-step approach. Place Import Assembly, Pivot Edit, Build Assembly Rig, and Assembly Edit as separate top-level nodes if the wrapper is too coarse for the work at hand. The Build Assembly Rig node has internal settings that can be tuned when the default rigging behaviour is not quite right; these are not exposed on the top-level assembly resource.

Mental model

Assemblies are many cached pieces plus the relationships that survive through meshing, rigging, and export. The decoration places them at points on the tree; the trait system decides which goes where; rig-level effectors produce per-position variation without breaking instancing; density-based removal handles the final layer of variation.

Related

For the broader decoration system this workflow sits inside, see Decorations; for the design history behind the move from the cluster decoration to the assembly decoration, see the cluster-to-assembly article. The constituent nodes have their own pages: Assembly Decoration, Assembly Resource, Classify, and Build Assembly Rig. For the workflow on screen, watch Nanite Assemblies; for the export path, see Export Unreal Nanite Assembly.