Spline Generators Overview

With a spline generator you draw a spline, and PolyBash builds stairs, paths, corridors or a whole building along it. The result is a set of normal GameObjects with meshes, materials and colliders, so it works with every other tool in your project.

PolyBash has two generators that share one build process. This page explains the shared parts, and the next two pages document each generator in detail.

Requirements

PolyBash needs Unity 2022.3 or Unity 6, a supported render pipeline and four Unity packages. The section Requirements on the start page of this manual lists them.

Each generator needs a Spline Container component on the same GameObject, and Unity adds that component for you. A build needs a spline with two knots or more. With fewer knots, the generator produces nothing, and the Info section reports "No build yet. Add a spline with at least two knots."

Add a generator to a scene

1. Select GameObject → Create Empty.
2. Select Add Component, and type the name of the generator into the search field.
3. Select Spline Stair Path Generator or Spline Building Generator.
4. Draw the spline with the spline tools of Unity, and add at least two knots.
5. Assign a material to Default Material, at the top of the inspector.
6. Adjust the sections of the inspector. The generator rebuilds after each change.

The generator writes its output into child GameObjects. Both generators work in the Unity Editor and at run time, although you normally build only in the editor.

Build cycle

PolyBash always rebuilds the whole result, and no incremental update exists. Every rebuild destroys the previous output first, and then creates it again. A rebuild starts in these cases:

• You enable the component, or Unity loads the scene.
• You edit the spline of this generator.
• You change a field in the inspector.
• A generator that this generator reads rebuilds itself. The section Developer view describes the only stage that reads another generator.
• You select Regenerate.

Some changes do not pass through the inspector, such as a field that a script changes directly. After such a change, select Regenerate.

A generator that is stored on disk as part of a prefab asset never builds, because Unity forbids an edit of the hierarchy there. Prefab Mode is a normal edit context, so the preview builds inside it. PolyBash deletes the generated objects before it saves the prefab, and it builds them again afterward.

Inspector anatomy

Both inspectors use the same order, and only the middle part differs per generator.

1. Default Material — the material of every generated part whose own material field is empty.
2. The settings sections of the generator, such as Levels or Shape.
3. One section per optional stage, such as Roof or Railings.
4. Pipeline Stages — the developer view of the build pipeline, hidden by default.
5. Scene Gizmos — one visibility toggle per group of scene handles.
6. Regenerate — the button that forces a rebuild.
7. Save to Prefab — the section that saves a copy of the generated objects as a prefab asset.
8. Info — the report of the last build.

Sections remember their expanded state per session. A section with a checkbox in its header controls one stage, and the section Stages describes that behavior.

Sections of the Spline Stair Path Generator

The generator creates its pieces procedurally from the Pieces section, and it needs no further asset.

The field Physics Material needs Unity 6 or newer, because Unity renamed that class, so on Unity 2022.3 the field does not appear.

Sections of the Spline Building Generator

The Roof stage produces nothing until you set Roof Type to Gable.

Stages

A generator builds through a list of stages, and each stage performs one part of the work, such as the walls or the roof. The stages run in a fixed order of phases.

Most stages are mandatory, and the generator adds them for you. The optional stages appear as their own inspector sections, and each one has a checkbox in its section header. A new generator contains every optional stage, so each of these checkboxes starts selected.

• A section with a selected checkbox shows the settings of the stage. Clear the checkbox to disable the stage. A disabled stage keeps its settings, which appear dimmed, and the build skips it.
• After you remove a stage in Pipeline Stages, its section keeps a cleared checkbox. The section then reports "Off — select the checkbox to add this stage."

Developer view

The section Pipeline Stages lists every stage as a card, grouped by phase. To display the section, right-click the header of a stage section, such as Railings or Roof, and then select Show Developer Stages. This option is an editor preference, and it applies to every generator.

Inside that section you drag a card by its grip to reorder it within its phase. Add Stage adds a stage type, and the remove button deletes one. When a later stage reads what the removed stage produces, the removal breaks the pipeline, and PolyBash asks for a confirmation.

Each card shows these elements, from left to right:

• The grip "≡", which reorders the card.
• The arrow "▸" and the class name of the stage. Select either one to expand the card, which then shows the help text and the settings of the stage.
• The tag "required" on a stage that a later stage needs.
• The badge "⚠" on a stage that failed in the last build. Its tooltip shows the error message.
• The checkbox, which enables or disables the stage.
• The button "✕", which removes the stage.

A card that reports "Missing stage type" holds a stage whose class no longer exists in the project, so remove that card.

The Add Stage menu, the cards and the lines of Info name each stage by its class name. The Add Stage menu has one submenu per phase. It also lists stages for diagnosis, which carry the suffix "(dev)" and which this manual does not describe.

The stair path generator uses the stages below, in the order of its default list. The last two stages are not part of the default list.

The source of StairFootprintUnionStage is a building generator, or a stair path generator that carries StairFootprintStage. No stage builds geometry from a footprint, so the only visible effect is a rebuild of this generator after each rebuild of the source. Without a source, the stage reports the warning "Footprint union: no source generator assigned."

The building generator uses the stages below, and its default list contains all of them.

Use the developer view for diagnosis, because the normal workflow needs only the stage sections.

Per-knot and per-section values

Some values exist once per spline knot, or once per section between two knots. PolyBash resizes these arrays after each change of the knot count, and each value keeps its index in the array. So after you insert or delete a knot inside the spline, each later knot receives the values of another knot. Verify the values of the foldouts after such an edit.

The wall section of the stair path generator adds Section Wall Left and Section Wall Right. These arrays enable or disable a wall per section, so you can open one side of the corridor.

The rows of these foldouts and the knot labels of the scene handles count from 0, such as "Knot 0", "Section 0" and "K0". The generated nodes count from 01, so the row "Section 0" belongs to the node Section-01. The cards and the opening labels of the stair path generator also count from 0, such as "Opening 0". The cards and the opening labels of the building generator count from 1, such as "Door 1".

Scene handles

Some stages draw handles in the Scene view, and the section Scene Gizmos lists one toggle per group of handles. A toggle appears after the stage that draws the handles exists on the generator. Each toggle is a user preference for one stage type, so it applies to every generator with that stage, in every project.

While you hold Ctrl (Cmd on macOS), some handles move in steps of the move increment of the Unity snap settings. These are the corridor offset handles, the wall-floor base handles and the sill cube of a window.

The section also has a checkbox to Hide Collider Gizmos, which is present on both generators. The checkbox disables the Scene view gizmo of every collider type, so the wireframes of the generated colliders disappear. To restore the collider gizmos that were visible before, clear the checkbox. Unity stores the gizmo state per project, and not per scene, so the checkbox keeps its state after a restart of the editor. As a result, the collider gizmos stay hidden after you open a scene without a generator. To restore them, clear the checkbox on any generator, or use the Gizmos menu of the Scene view.

Hide Handle Labels, in the same section, removes the text labels from every scene handle, such as the knot offsets and the opening names. The handles stay visible and keep working. The setting is a user preference, so it applies to every project.

Info section

The Info section reports the last build:

• A summary line, such as "Build ran in 12.4 ms — 14 stage(s)".
• One line per stage, with its class name, its phase, its duration and its status: Ran, Failed or Disabled.
• Validation errors in a red box. The build refuses to run while an error exists, and the summary line reports "Build did not run — see the validation errors above."
• Warnings in a yellow box.

A failed stage appears in red, and its tooltip carries the error message. The rest of the pipeline continues after a failure, so a partial result is normal in that case. A disabled stage appears dimmed at the start of the list, without a phase and with a duration of 0 ms.

Generated output

Both generators create child GameObjects with the marker component Generated Output, and the names describe the content.

Do not edit the generated objects, because every build destroys them and creates them again. Objects that you add outside the generated nodes survive a build. An object that you place under a generated node disappears with that node at the next build.

Materials

Each generated part carries its own material field, such as Stair Material or Outer Wall Material, and an empty field falls back to another material.

The stair path generator resolves a material in this order:

1. The material of the part.
2. Default Material.

The generated pieces carry no material of their own, so Default Material is the fallback for every part whose own field stays empty.

The building generator resolves a material in this order:

1. The material of the part.
2. The wall material of the matching side. The floor and the ceiling follow Outer Wall Material, and the top cap and the roof follow Inner Wall Material.
3. Default Material.

The page Texture Generation explains how PolyBash produces the textures of those materials, and the page Surface Variants explains the surface variants.

Appliers

An applier is a component that connects a material source to a generator. It creates the material and its textures when they are missing, and it assigns that material to the material fields that you select. Two appliers exist:

• The Texture Definition Applier drives a texture definition, which captures block prefabs into a texture. Use it when a part needs a captured surface, such as a brick wall.
• The Surface Variant Applier drives one surface variant, which it bakes into a texture pair and a material. Use it when a part needs one recolored surface without a capture.

Both appliers share the Material Slots section, which the section Material Slots describes. Both work only in the Unity Editor, and not in Play Mode.

Output folder

Both appliers carry an Output Folder field, which locates the assets that the applier writes. The field accepts two forms of path.

A path that starts with ./ or with ../ is relative to the folder that holds the scene of the component. In Prefab Mode that path is relative to the folder that holds the prefab. Every other path is relative to the Assets folder. The button ... opens a folder browser, and it stores the selected folder in the form that the field already uses.

A path relative to the scene needs a saved scene, because an unsaved scene has no folder. The inspector warns you while the scene has no folder. Until you save the scene, the applier resolves the path against the Assets folder, so ./Textures becomes Assets/Textures.

The applier creates the output folder when the folder is missing, so you can type the name of a folder that does not exist yet. Verify the spelling of the path, because a typing error creates a second folder instead of an error message.

An applier on a prefab resolves a path relative to the scene once per scene. The same prefab in three scenes writes three sets of assets, one beside each scene file. Use a path relative to the Assets folder when every scene must share one set of assets.

Texture Definition Applier

The Texture Definition Applier captures its texture definition when the images are missing. It then assigns the material of the texture definition to the fields that you select. Use the component instead of an assignment by hand, because the component also creates the textures that the material needs.

1. Select the GameObject that carries a Spline Stair Path Generator or a Spline Building Generator.
2. Select Add Component → Snowtop → PolyBash → Texture Definition Applier.
3. Assign your texture definition to the Definition field.
4. In the Material Slots section, select each material field that the texture definition drives.

The check for missing images runs when you open the scene, when you add the component, and when you add a prefab that carries it. The check also runs after each change to a field of the component, and after each script reload. Clear Capture When Missing to disable that automatic capture.

The button Capture Now captures the missing images and creates a missing material, even when Capture When Missing is cleared. The button Recapture captures the images again, and the button Apply To Slots writes the material into every selected field again, without a capture. A status line above the buttons names the material and the output folder, and it reports whether the captured images exist.

Leave Output Folder empty, and the applier writes into the output folder of the texture definition. It then assigns the shared material of that texture definition. Enter a folder, and the applier writes its own copy of the images and of the material into that folder. The shared material of the texture definition then stays unchanged. The section Output folder describes the two forms that the field accepts.

Add one component for each texture definition that the GameObject needs. So a building that uses a wall texture and a roof texture carries two components.

Surface Variant Applier

The Surface Variant Applier bakes one surface variant into two textures plus a material, and it assigns that material to the fields that you select. The page Surface Variants describes the surface variant asset.

1. Select the GameObject that carries a Spline Stair Path Generator or a Spline Building Generator.
2. Select Add Component → Snowtop → PolyBash → Surface Variant Applier.
3. Assign your surface variant to the Variant field.
4. Set Gradient Interpolation, which blends between gradient A and gradient B of the surface variant.
5. Set Detail Preservation, which controls how much per-pixel detail the bake keeps, from 0 (pure gradient colors) to 1 (full detail).
6. Set Output Folder and File Name, which locate the baked assets. The section Output folder describes the folder, and an empty file name means the name of the surface variant.
7. In the Material Slots section, select each material field that the surface variant drives.

The bake produces three assets in the output folder, and the name of each one starts with the value of File Name.

The bake applies the surface transform of the surface variant, so the result is the patch that one block covers. As a result, a surface variant that keeps the default tiling of 0.5 bakes one quarter of the target texture. To bake the whole texture, set Surface Tiling to 1 on the surface variant.

The component bakes when the textures are missing, when a setting of the component changes, and when you edit the surface variant. Clear Auto Bake to disable the automatic bake. The button Bake Now runs the same check, and the button Rebake bakes the assets again. The button Apply To Slots writes the material into every selected field again, without a bake.

A status line names the material and the path of the baked albedo texture, and it reports whether the baked textures exist. A thumbnail below it shows the baked albedo texture.

An existing material at the output path keeps its GUID across a rebake, so every reference to it survives. The component adopts that material, and it never replaces it. The adopted material also keeps its shader, even after a change of render pipeline.

Material Slots

The Material Slots section lists every material field of the generator. The group "Generator" holds the fields of the generator itself and of its configuration groups. Each enabled stage with a material field adds one group, which carries the class name of the stage, such as BuildingRoofStage. A field of a disabled stage does not appear in the list.

Each row holds a checkbox, the name of the field, and a read-only field that shows the current material. The applier searches for the generator only on its own GameObject. Without a generator, the component still creates its material, but it assigns the material to no field.

The component records the material that a field held before you selected it. The field returns to that material when you clear the field, or when you remove the component.

After you disable the owning stage, the field returns to that material when the applier runs again, such as after Apply To Slots. The applier then removes the field from its selection, so select the field again after you enable the stage.

When two appliers drive the same field, the applier that runs last wins, and the inspector reports the conflict. The report covers every combination, so it also names a conflict between a surface variant applier and a texture definition applier.

Prefabs

A generator works inside a prefab, with two restrictions:

• On a prefab instance, you cannot add, remove or reorder stages. Open the prefab for those operations. A field edit stays possible, and it becomes an instance override.
• The inspector edits the stages of one generator at a time. With several generators selected, the stage sections report "Select a single generator to edit its stages."

Save to Prefab

The section Save to Prefab saves a copy of the generated objects as a new prefab asset. The prefab holds no generator, so a later rebuild of the generator does not change it.

1. Expand the section Save to Prefab, below the button Regenerate.
2. To copy the position, the rotation and the scale of the generator to the root of the prefab, select Keep Transform.
3. Select Save to Prefab….
4. In the save dialog, select a folder, enter a file name, and save the prefab.

Keep Transform is cleared by default, so the root of the prefab keeps the default position, rotation and scale. After the save, Unity highlights the new prefab in the Project window.

The prefab contains a copy of each generated node, without the Generated Output marker component. The prefab file stores the generated meshes, and it also stores each material that exists only in the scene. A material that is a project asset stays a reference to that asset.

When the file already exists, PolyBash replaces its content, and it deletes the meshes and the materials that the file stored before. With several generators selected, PolyBash opens one save dialog per generator.

A generator without generated output, such as a generator with a spline of one knot, cannot save a prefab. In that case, a dialog reports that the generator "has no generated output to save. Regenerate the generator, then save again."

Troubleshooting