Poly Skeleton Mesh

Overview

Poly Skeleton Mesh builds low-poly meshes from a tree of skeleton nodes. You shape the silhouette by placing nodes and setting their radius and cross-section, and the tool generates the hull between them. Skeleton meshes can be spliced together (a limb into a body, a branch into a trunk), subdivided, deformed by bone controllers, and exported as a self-contained prefab with a regular MeshRenderer or a rigged SkinnedMeshRenderer.

• Node-tree modeling with scene-view handles: move, rotate, scale, change parents, insert, split and merge.
• Quadrangle and octagon cross-sections with per-corner offset, sharpness and color.
• Symmetric editing along X, Y or Z with a configurable mirror center.
• Mesh splicing — ports connect automatically and the hull bridges both meshes.
• Subdivision levels 0–3 with per-corner creases, smooth or flat shading and flipped faces.
• Bone controllers and skinned export including mesh, bone hierarchy and bind poses.
• Prefab export with the mesh embedded as a sub-asset and optional lightmap UVs.
• GPU (compute shader) render path at runtime with an automatic CPU fallback.
• Runtime API to build, edit, connect, deform and export skeletons from code.

Engine

Unity 6+

Assemblies

Runtime + Editor

Rendering

GPU, CPU fallback

Samples

5 scenes

Requirements

Installation

Copy the Assets/PolySkeletonMesh folder into your project, or import the package. Nothing has to be configured.

Assets/PolySkeletonMesh/
  Runtime/       # SkeletonMesh component, data model, mesh generators
  Editor/        # inspector, scene tools, exporter, benchmark
  Samples/       # sample scenes (optional)
  Documentation/ # this manual and its media (optional)

• Runtime/PolySkeletonMesh.Runtime.asmdef contains the component, the data model and the mesh generators.
• Editor/PolySkeletonMesh.Editor.asmdef contains the inspector, scene tools, exporter and benchmark.
• Samples and Documentation are optional and can be deleted.

Core concepts

Positions and radii are in the transform space of the SkeletonMesh component, so scaling or rotating the component moves the whole skeleton.

Quick start

1. Create the component with GameObject ▸ Poly Skeleton Mesh (shortcut Ctrl+Shift+D).
2. In the inspector toolbar, switch to Skeleton mode.
3. Select the root node and hold Shift while dragging the Position handle to create child nodes.
4. Adjust Radius, Shape and Color in the node inspector; repeat until the silhouette is right.
5. Switch to Mesh mode and assign a Material — the component draws nothing without one.
6. Optionally set Subdivision, Is Smooth and Is Flipped.
7. Open Unity Mesh Exporter and press Export to write a prefab.

Editor guide

The inspector toolbar has two modes. Skeleton mode gives you node and control point handles, symmetry and bone controllers: Unity's built-in move, rotate and scale tools are replaced by the tool's own handles while that mode is active on a valid, unlocked scene mesh. Mesh mode holds material, subdivision, flip and smooth, locking, mirror and normalize buttons, splicing ports and export.

Creating a skeleton mesh

Use GameObject ▸ Poly Skeleton Mesh or the shortcut Ctrl+Shift+D. The new mesh starts with a root node plus one child. When a node is selected in Skeleton mode, the new mesh inherits that node's material, subdivision and orientation, and starts from its shape and radius — handy for continuing an existing limb with a separate mesh.

Creating nodes

Select a node, make sure the Move tool is active (W), then hold Shift and drag the Position handle. A child node is created on mouse down and follows the drag; releasing the mouse commits it. With symmetry enabled, the matching symmetric node is created as well.

Editing nodes

• Ctrl + click another node to make the previously selected node a child of it. Cycles are rejected automatically.
• Use the Move, Rotate and Scale tools (W, E, R) to transform the selected node. Transform Mode in the settings decides whether the subtree follows.
• The node inspector gives numeric control over shape, position, radius, angle, color, ports and bones.

Editing control points

Every cross-section corner can be edited individually. Hold Ctrl to add control points to the multi-selection, or press Edit Point in the node inspector to jump to the first one. The control point inspector exposes Offset, Sharpness, Color and Color Mix; scene handles move the points directly, and symmetric points follow automatically.

Scene view shortcuts

Symmetry

Symmetry is configured in the settings panel (Symmetric Space, Symmetric Axis):

• Symmetric Space — Self mirrors around the edited mesh transform, Root around the root mesh transform, and Custom around the transform assigned to Symmetric Center.
• Symmetric Axis — X, Y, Z or None.
• Symmetric nodes are highlighted with their own color; editing a node or control point also edits its symmetric counterpart, and Mirror Flip creates a mirrored copy of the mesh across the axis.
• Set To Symmetric Center stores the current mesh as the custom center.
• Mirror Flip requires a symmetric axis other than None; Normalize Scale is independent of symmetry.

Color brush

Click the small brush icon next to a Color field to activate the brush, then click nodes or control points in the scene to paint them. Right-click to leave the brush. Painting writes the color (and color mix) of the painted element and of its symmetric counterpart.

Splitting and merging meshes

• Split (node inspector) moves the selected node and its subtree into a new SkeletonMesh parented under the current one. Use it to break one mesh into several parts, for example to give a limb its own bones or subdivision. It requires a node that is neither the root nor an end node.
• Merge (node inspector) merges the selected node into its parent node. For a connected root node the merge goes into the connected mesh; the editor then re-parents the remaining child meshes and removes the old mesh.
• Both operations are undoable.

Splicing skeleton meshes

Splicing is spatial and automatic:

1. Save the mesh you want to attach as a prefab, or keep another mesh in the scene.
2. Put a SkeletonMesh port on both sides: tick Is Port on a node and set Connection Radius large enough to reach the other port. Port nodes need a cross-section, so their shape cannot be None.
3. Parent the child mesh under the target mesh in the hierarchy and move it so the two ports come close. The nearest matching ports connect automatically and the hull bridges them; the port colors show unconnected, connected and selected states.
4. While dragging a prefab from the Project window, hold Alt to rotate it and Ctrl to change the target port.
5. When symmetry is active the preview also shows a mirrored copy of the dragged mesh, and the drop creates that copy too. A mesh whose Is Flipped state differs from the target is spliced in the opposite direction so both hulls meet correctly.

The component lists FromConnections and ToConnections expose the result, which is useful for debugging.

Bone controllers

To animate a generated mesh:

1. Tick Is Bone on a node (or call SetBone("Name") from code) and set a Bone Name if you need one.
2. Press New next to Bone Controller to create a Transform for the node, or assign an existing transform. Update re-applies the rest pose to the existing controller.
3. Tick Is Skeleton Locked in Mesh mode. While locked the skeleton cannot be edited, but the bone controllers deform the mesh like a SkinnedMeshRenderer driven by a rig.

Bone controller handles are drawn in the scene view and can be selected directly.

Exporting a prefab

In Mesh mode, on the root mesh, open Unity Mesh Exporter:

Details worth knowing:

• The generated mesh is stored as a sub-asset of the prefab.
• Export uses the root mesh and includes all child meshes in the hierarchy, including spliced ones.
• Export does not add colliders, scripts or LOD groups; add those to the exported prefab if needed.
• The last used folder is remembered in the editor settings.
• Exported prefabs get a generated thumbnail in the Project window, and selecting the prefab asset shows an interactive preview in the inspector (drag to rotate, scroll to zoom, drag the splitter to resize).

Inspector reference

The mesh inspector in Mesh mode contains:

In Skeleton mode the inspector shows the node or control point editor instead (see below).

Editor settings panel

The settings asset is created automatically at Assets/Settings/SkeletonMeshEditorSettings.asset on first use; it is found by type if it lives elsewhere. It stores view and handle preferences and the last export folder. Its content depends on the current mode and on whether the selected mesh is locked.

Symmetry settings

Skeleton editor settings

Mesh editor settings

Bone controller settings

Node & control point reference

Node inspector

Control point inspector

Runtime guide

Add using PolySkeletonMesh.Runtime; to your script.

Build a skeleton from code

using PolySkeletonMesh.Runtime;
using UnityEngine;

[RequireComponent(typeof(SkeletonMesh))]
public class RuntimeSkeleton : MonoBehaviour
{
    private SkeletonMesh _mesh;

    private void Awake()
    {
        _mesh = GetComponent<SkeletonMesh>();
    }

    private void Start()
    {
        // A material is required; pick a shader from your render pipeline.
        _mesh.Material = new Material(Resources.Load<Shader>("Wireframe Vertex Color"));
        _mesh.Subdivision = 1;

        // Node positions are local to the SkeletonMesh transform.
        var chest = _mesh.RootNode.AddChild(new Vector3(0f, 0f, 1f), new Vector2(0.5f, 0.5f));
        var head = chest.AddChild(new Vector3(0f, 0f, 2f), new Vector2(0.4f, 0.4f));
        head.SetColor(Color.yellow, 0.5f);

        // The readable CPU mesh (colliders, export, custom renderers).
        var mesh = _mesh.GeneratedMesh;
        Debug.Log($"{mesh.vertexCount} vertices in {mesh.subMeshCount} submesh(es)");
    }
}

Convenience overloads exist for the common cases: AddChild(position, radius), AddChild(position, shape), AddChild(radius) and AddChild(shape). SetPosition, SetRadius, SetColor, SetBone and friends return the node for chaining.

The example above creates a mesh like this:

Mesh data

The component renders itself with Graphics.DrawMesh in LateUpdate; it does not create a MeshRenderer, so renderer-based features such as light probes through a renderer or static batching do not apply to it. Export a prefab if you need a regular renderer.

Lock and deform with bone controllers

var boneNode = _mesh.GetNode(1).SetBone("Chest");

// Creates a "<name> (Controller)" Transform in the mesh hierarchy and binds it to the node.
// Use boneNode.SetBoneController(existingTransform) to bind your own instead.
var controller = boneNode.CreateBoneController();

// While locked, node edits are rejected and the controller drives the mesh.
_mesh.IsSkeletonLocked = true;

// Then animate the controller from your own script, a Timeline or an Animator:
controller.localRotation = Quaternion.Euler(0f, 30f, 0f);

ResetBoneController() restores the rest pose of a controller. While the skeleton is locked, any node or control point edit throws InvalidOperationException("skeleton is locked, can not edit.").

Splice at runtime

Splicing needs two meshes in a parent/child transform hierarchy, each with a port node close enough to the other:

var body = _mesh;                                   // existing mesh
var socket = body.GetNode(1);
socket.SetIsPort(true).SetConnectionRadius(0.6f);   // socket node needs a shape

var limbGo = new GameObject("Limb");
limbGo.transform.SetParent(body.transform, false);
limbGo.transform.localPosition = socket.Position;
var limb = limbGo.AddComponent<SkeletonMesh>();
limb.Material = body.Material;
limb.RootNode.SetShape(NodeShape.Quadrangle).SetRadius(0.4f);
limb.RootNode.AddChild(new Vector3(0f, 0f, 0.6f), new Vector2(0.4f, 0.4f))
    .SetIsPort(true)
    .SetConnectionRadius(0.6f);

// Connections are rebuilt on demand; inspect the result.
foreach (var connection in body.FromConnections)
{
    Debug.Log($"{connection.FromNode.Index} -> {connection.ToNode.Index}");
}

Export from code

// A GameObject with MeshFilter + MeshRenderer, or SkinnedMeshRenderer + bones when isGenerateBone is true.
var exported = _mesh.GenerateUnityMeshObject(isGenerateBone: true, isIncludingChildren: true);

// Or the raw data: mesh + one material per submesh + the bone transforms.
var mesh = _mesh.ToUnityMesh(out var materials, out var bones, isIncludingChildren: true);

ToUnityMesh(out materials, out bones) always generates bone data; the overload without bones only generates it for a locked skeleton. The exported objects are plain scene objects — in the editor, save them with PrefabUtility.SaveAsPrefabAsset, which is what the Export button does, including embedding the mesh as a sub-asset.

Mesh generation details

• Hull — every node contributes its cross-section to the hull of its parent–child segment. End nodes and N-joint roots get a cap; internal nodes are bridged smoothly.
• Connections — a spliced port pair creates an extra hull segment between the two meshes, so the surface is continuous across the splice, including flipped and same-direction connections.
• Subdivision (0–3) — one Catmull-Clark-like pass per level; each quadrangle becomes four. Per-control-point Sharpness blends the smoothed position with the original corner, which is how creases are kept.
• Normals — flat shading derives one normal per face; Is Smooth averages the face normals around each vertex (flipped faces contribute negated normals).
• Colors — vertex colors come from node colors blended by Color Mix and from control point colors.
• Submeshes — meshes with different materials produce one submesh per material; the hull is split accordingly.
• Bounds — the CPU mesh recalculates bounds exactly; the GPU path uses a conservative bound derived from the bone matrices so animated parts are not culled.
• UVs — the generated mesh has no authored UVs. Use Is Generate UV on export to create a lightmap UV layout, or generate UVs with your own tooling.

Performance

SkeletonMesh generates the render mesh on the GPU (compute shader) at runtime and only falls back to the CPU path when compute shaders are unavailable. The CPU path is used for GeneratedMesh (export, colliders, editor preview) and for skinned bone updates.

Measured on an i7-10700K / RTX 3080 at subdivision 3 (Unity 6.3, editor build):

Guidelines:

• Runtime rendering is cheap; the CPU path is the expensive one. Avoid reading GeneratedMesh every frame, for example to rebuild colliders — it is meant for export and editor tooling.
• Subdivision grows the face and vertex count by about 4× per level. A 200-node chain at subdivision 3 already produces ~205k vertices; keep the level low for large skeletons and let the GPU path draw the render mesh.
• A locked skeleton is only rebuilt when a bone controller actually moved, so idle animated meshes cost almost nothing.
• Locking applies the bone pose before subdivision, so the first build of a skinned mesh costs the same single pipeline pass as an unskinned build.

Benchmark tool

A baseline benchmark lives in Editor/Diagnostics/SkeletonMeshBenchmark.cs. Define POLY_SKELETON_MESH_DEV (Project Settings ▸ Player ▸ Scripting Define Symbols) to compile it, then run Tools ▸ Poly Skeleton Mesh ▸ Run Benchmark. The report is written to Temp/Benchmark/polyskeletonmesh-benchmark.md and covers first build, dirty rebuild, half-mesh generation, skinned build, incremental bone update, export and JSON serialization, including managed allocations per operation.

Samples

Samples/Default/Defalt Samples.unity is a showcase scene with several prepared skeletons (basic shapes and hollow shells) to explore the tool without building anything. The three feature samples below live next to it.

Tree Generator

A procedural tree generator that builds a low-poly tree from a handful of parameters; the whole tree is a single SkeletonMesh component.

Clicking with the mouse plants a randomly generated tree that grows from small to large.

Monster Simulator

Pieces different body parts into a monster, generates its rig and adds procedural animation with the Animation Rigging package. Monsters can be archived as json.

Wireframe Mesh Generator

Converts an existing mesh into a wireframe skeleton: every vertex becomes a SkeletonMesh and every edge becomes a node chain, so the wireframe thickness and color can be edited like any other skeleton.

Sample scenes

Troubleshooting

Known limitations

• The data model is a tree: a node has exactly one parent and any number of children.
• Ports are matched spatially; there is no explicit "connect these two nodes" API. Overlapping ports resolve to the nearest valid pair.
• Connection rebuilding walks the mesh hierarchy on the main thread; avoid moving or re-parenting many spliced meshes every frame.
• The component renders through Graphics.DrawMesh, so it does not appear as a renderer in the hierarchy and does not participate in renderer-based batching or GPU instancing.
• Colliders are not generated; bake a MeshCollider from GeneratedMesh or add primitive colliders to the exported prefab instead.
• Skeleton data is serialized as JSON inside the component. Do not hand-edit it; corrupt data blocks loading by design.