Unibuilder Manual
Everything the plugin does, and the keys that do it. Covers Unibuilder 1.0 on Godot 4.7+.
Getting started
Installation
- Copy the
addons/unibuilder/folder from your purchase into your project'saddons/folder. - Open Project → Project Settings → Plugins and enable Unibuilder.
- The Unibuilder toolbar appears above the 3D viewport. You're ready.
Requirements: Godot 4.7 or later, any platform. The plugin is pure GDScript, so the standard Godot build works. No .NET, no native libraries.
Your first mesh
- Open the Add menu on the toolbar and pick Cube.
- Press and drag in the viewport to draw the base rectangle on the grid, release, then move the mouse to pull out the height.
- Click to commit. The new object is selected and ready to edit, and drawing another shape chains straight on.
Press 4 to enter Face mode, click a face, then hold Shift and drag the move gizmo. That's an extrude, and it is the single gesture you will use most.
What a Unibuilder mesh is
Every Unibuilder object is a UBMeshInstance3D, which extends the ordinary MeshInstance3D. The editable model (n-gon faces, materials, UV settings, colors) lives in its mesh_data resource, and the plugin compiles it to a normal ArrayMesh whenever it changes. Because the compiled mesh is stored with the scene:
- the mesh renders, lightmaps, and occludes like any other mesh;
- scenes open fine, and games run fine, on machines without the plugin;
- exported games include collision, because the node script ships with the addon.
The grid and snapping
Unibuilder draws its own reference grid, independent of Godot's. One value drives both the visual density and the snap step, so what you see is what you snap to. The grid shows whenever a Unibuilder mesh is being edited, and its state is saved per project, never in your scenes.
Controls
| Control | What it does |
|---|---|
| Plane selector (X / Y / Z) | Which axis plane the grid lies on. Draw on walls by switching to X or Z. |
| Grid toggle | Show or hide the grid. Snapping still works with it hidden. |
| Step spinbox, ÷2 / ×2 | The snap increment. Accepts values like 0.125. |
| [ / ] | Halve / double the step from the keyboard. |
| , / . | Nudge the grid plane along its axis by one step (for working at different floor heights). |
| 0 | Reset the plane offset. |
| Snap toggle | Snap transforms to the grid. Hold Ctrl during a drag to temporarily invert it. |
Per-element snap
By default a dragged selection snaps as one rigid block, keeping its shape. Turn on Per-Element Snap in the Tools menu and each vertex quantizes to the grid individually instead. The shape may distort; that's the point. Use it to conform loose geometry to the grid.
Vertex snapping
Hold V during any move drag. When the cursor comes near another vertex, an amber ring and crosshair mark it, and the dragged selection jumps so its grabbed vertex lands exactly on the target. No gap, mathematically exact.
- The anchor is the dragged vertex nearest your cursor when the drag started, so grab the gizmo near the corner you want to place.
- Targets include the rest of the current mesh and every vertex of every other Unibuilder mesh in the scene. Dragging a wall corner onto a floor corner is the intended use.
- In Object mode the whole node snaps by whichever of its vertices is nearest the cursor.
- Release V and the drag goes back to normal grid behavior.
Drawing shapes
Everything in the Add menu draws directly in the viewport and lands snapped to the grid, on the active grid plane. The general gesture: press and drag the base, release, move to pull the height, click to commit. Esc cancels at any point. A dimensions label follows the cursor while you draw.
Plane and Sphere commit as soon as you release the base drag (they have no height pull). Stairs get one step per snap increment automatically.
The shapes
| Shape | Notes and parameters |
|---|---|
| Cube | The basic blockout unit. |
| Plane | Divisions U / V. |
| Cylinder / Cone | Sides. |
| Prism | Triangular wedge. |
| Stairs | Steps. Solid and watertight, rising toward local +Z. |
| Curved Stairs | Steps, Arc (degrees), Inner Radius. Stairs sweeping around an arc. |
| Arch | Radius, arc segments, Smooth (round-shades the curved underside). |
| Door | A doorway frame: pediment band and side posts. Pediment / Side sizes are fractions by default; the Absolute toggle switches them to world units. Arched swaps the flat lintel for an arc. Smooth round-shades the arc. |
| Sphere | Subdivs. Built from quads with no pole fans, shades smooth. |
| Torus | Tube Radius, Ring Segs, Tube Segs. Base drag sets the outer diameter, height pull sets the tube. |
| Pipe | Thickness, Sides. A tube with real inner walls. |
| Poly Shape | Click points to outline any polygon (Backspace removes the last point), close it by clicking the first point or pressing Enter, then pull the height and click. |
All primitives are watertight, which matters later: booleans require it.
Editing parameters after committing
After you commit a parametric shape, its parameters appear in the adjust panel on the right and stay live: change the step count of stairs or the arc segments of an arch and watch it rebuild. The shape stays adjustable until you move on to something else, which commits it as one undo entry. After that, its geometry is ordinary editable mesh like everything else.
Selection
Modes
1 Object, 2 Vertex, 3 Edge, 4 Face. Esc returns to Object mode. The toolbar buttons mirror the keys.
Switching modes converts your selection instead of dropping it: a selected face becomes its four edges in Edge mode, its four vertices in Vertex mode, and going back up keeps only elements that are fully covered (two vertices of a quad are not enough to reselect the quad).
Picking
- Click selects, Shift+click adds or removes. As you move the mouse, the element a click would pick lights up.
- Drag in empty space for a marquee. The X-Ray toggle makes the marquee select through geometry instead of visible-only.
- Picking works against Unibuilder's own data, so you never need collision shapes for editing.
Loops and rings
- Double-click an edge: edge loop. Alt+double-click: edge ring.
- Double-click a face: face loop, steered by the nearest edge under the cursor.
Selection tools
| Tool | What it does |
|---|---|
| Grow / Shrink | Expand the selection to adjacent elements, or contract it from its boundary. Face-mode Grow can be angle-limited in Preferences, so growth stops at hard corners. |
| Select All Ctrl+A | Every element of the current mode. |
| Invert Ctrl+I | Selected becomes unselected and vice versa. |
| Select Similar (Face mode) | Every face sharing material, smoothing group, and color with the selection. |
| Select Holes (Edge mode) | Every boundary edge in the mesh. Works from an empty selection; run Fill Hole afterwards. |
Transforms
The gizmos
W Move, E Rotate, R Scale. The same gizmos drive element selections and, when a Unibuilder node is the only thing selected, the whole object in Object mode, so object transforms snap to the same grid as everything else. Multi-object selections keep Godot's native gizmo.
- Move: axis arrows plus a view-plane center square.
- Rotate: three axis circles with a live degree readout. Snapping is 15° steps; drags past 180° keep counting.
- Scale: axis handles plus a uniform center. The readout shows the live factor, and snapping quantizes factors to the grid step (×0.5, ×1.25 and so on).
- Esc cancels any drag in progress. Ctrl inverts snapping while dragging.
Orientation
The toolbar dropdown switches gizmo orientation between Global (world axes), Local (the node's basis), and Normal (the blue axis points out of the selected faces). Normal is the one to use for pushing a slanted face straight out along its own direction.
Shift-drag extrude
In Face mode with the Move gizmo, hold Shift and drag: the selection extrudes and the new geometry follows the drag. This is the fastest way to rough out volumes.
Pivot tools
| Tool (Tools menu) | What it does |
|---|---|
| Center Pivot | Moves the node origin to the center of the mesh bounds. The mesh does not move in the world. |
| Set Pivot to Selection | Moves the origin to the current element selection, e.g. a door's hinge corner. |
| Freeze Transform | Bakes the node's transform into the vertices and resets it to identity. The mesh stays exactly where it is. |
Editing operations
The toolbar shows the operations valid for the current mode. Anything with parameters opens in the adjust panel after it runs.
The adjust panel
After a parameterised operation runs, its parameters appear in the panel on the right and edit live: the mesh re-applies the operation as you change values. Click Apply, run something else, or change the selection and the result commits as one undo entry. Esc in the viewport or Cancel reverts it entirely.
There is also a modal version: select edges and press Ctrl+B to drive a bevel's width with the mouse (the wheel changes segment count); in Face mode the same key drives Inset. Click commits, Esc cancels.
Vertex mode
| Op | What it does |
|---|---|
| Weld | Merges vertices closer than a threshold (adjustable afterwards). |
| Collapse | Merges the selected vertices to their center. |
| Split | Un-shares a vertex so each face gets its own copy. |
| Connect | Inserts edges between selected vertices on a shared face. Three or more vertices on one face carve it repeatedly. |
| Fill | Select the rim vertices of a hole and it closes. |
| Position panel | With exactly one vertex selected, a small X/Y/Z panel appears for typing exact world coordinates. |
Edge mode
| Op | What it does |
|---|---|
| Extrude | Pulls new geometry out of boundary edges, in the surface plane. |
| Bridge | Connects two edges with a face. Understands crossings, fills openings with correct winding. |
| Bevel | Chamfers edges. The Segments parameter (1–8) rounds the chamfer into an arc; Smooth gives the new faces their own smoothing group. Works on interior and boundary edges. |
| Connect | Splits faces that have exactly two selected edges through their midpoints, a partial loop insert. |
| Insert Loop | Inserts a loop along the ring of the selected edge. The Cuts parameter spaces several evenly. |
| Subdivide | Splits selected edges into N equal segments. |
| Fill Hole | Select any edge of a hole's rim and it closes. |
| Insert Vertex | A click tool: click along any edge to splice a vertex at that spot, snapped along the edge. Esc ends it. |
Face mode
| Op | What it does |
|---|---|
| Extrude | Pushes faces out along the group normal, building side walls. Shift-drag the gizmo for the freeform version. |
| Inset | Shrinks a copy of each face inward, ready to extrude. The Equal toggle keeps the rim width uniform on non-square faces. |
| Subdivide | Splits faces into a grid; the Segments parameter controls density. |
| Merge | Joins selected faces into one n-gon. Refuses regions with holes or bow-ties rather than making bad geometry. |
| Detach | Moves the selected faces into a new object. |
| Duplicate | Copies faces in place and selects the copies, ready to drag away. |
| Delete Del | Removes faces, leaving a hole. |
| Flip | Reverses the winding, turning a face inside out. |
| Flip Face Edge | Rotates the internal diagonal of a non-planar quad, changing how it bends. |
The Cut tool
Cut draws a new sub-face directly onto an existing face. Activate it, click a face, click points (they snap to a grid in the face's own plane; Ctrl frees them), and close via the first point or Enter. The face re-triangulates cleanly around your polygon, concave faces included, and the new sub-face is selected, ready for an extrude or inset. Cutting a doorway into a wall is the canonical use.
Materials and face properties
Materials
In Face mode, the panel on the right edge manages material slots. Pick or create a slot, then Apply assigns it to the selected faces. One mesh can carry any number of materials; the compiler emits one surface per used slot.
Faster: drag a material from the FileSystem dock straight onto a face. If the face is part of the selection, the whole selection takes it.
Auto-UV settings
Every face starts with automatic planar UVs, projected along its dominant axis. The face panel adjusts them live per face: offset U/V, rotation, tiling U/V, and a world-space anchor toggle.
- Local (default): the texture follows the face as the object moves.
- World: the texture stays put in world space while the face slides through it. Handy for continuous brick or tile across separate objects.
Smoothing groups
Each face carries a smoothing group number. Faces in the same group shade smoothly across their shared edges; group 0 means hard. The spinner is in the face panel. Curved primitives (spheres, cylinder walls, smooth arches) set theirs automatically.
The UV editor
Open the UV Editor bottom panel with a Unibuilder mesh selected. It shows the UV layout of your 3D face selection, or the whole mesh when nothing is selected, over the material's texture. Auto faces draw dimmed; manual faces draw bright.
Navigation and selection
| Input | What it does |
|---|---|
| Middle-drag / wheel | Pan / zoom (cursor-anchored). Frame recenters on the 0–1 square. |
| Verts / Faces toggles | Whether clicks pick UV corners or whole UV faces. |
| Click, Shift+click, drag | Select, toggle, marquee. A vertex click grabs every corner stacked at that point. |
| Double-click | Selects the whole UV island. Shift adds another island. |
| Tile toggle | Repeats the texture across the view; the 0–1 square stays outlined. |
Moving, scaling, rotating
- Drag moves the selection, snapped to the UV grid step. Editing an auto face quietly bakes it to manual first, so nothing visibly jumps.
- Ctrl+drag scales about the selection center, with a live ×factor readout. Shift while dragging switches to per-axis.
- Alt+drag rotates about the selection center with a degree readout, in 15° detents when Snap is on.
Tools
| Button | What it does |
|---|---|
| Manual / Auto | Bake the current projection into editable per-corner UVs, or return faces to automatic projection. |
| Planar / Box | Project the faces as one island along their average normal, or per-face along dominant axes. |
| Flip U / Flip V / Rot 90 / Fit | Mirror, quarter-turn, or fit the selection into the 0–1 square. |
| Sew | Welds selected corners that share a 3D vertex, stitching islands together. |
| Split | A picking toggle: vertex clicks grab one corner instead of the whole stack, so dragging tears a seam open. |
| Copy / Paste | Copies the first selected face's layout and pastes it onto faces with the same corner count. |
| Texel | Rescales every island touching the selection so texture density matches the first selected face. Check it with a checker texture: the squares end up the same size everywhere. |
Vertex painting
The paint toggle on the toolbar enters paint mode and docks a palette panel on the right. Vertex colors are stored on the mesh and survive baking.
The brush
- In Vertex mode you get a real brush: a sphere reticle sits on the surface under the cursor, and press-drag blends color in with radius, strength, and falloff from the panel.
- Holding still doesn't compound: one stroke applies at most one full dab anywhere.
- In Face mode, clicks hard-fill whole faces. Use it for color-coding blockouts.
- Shift+click eyedrops the color under the cursor. One stroke is one undo entry. Esc cancels a live stroke, then exits paint.
- Swatches: click applies, Ctrl+click stores the current color. They persist between sessions.
The two-texture blend workflow
The panel's channel mode separates color from alpha so they never fight: Color+Alpha, Color only, or Alpha only. New Blend Material assigns a shader material whose albedo mixes texture A into texture B by painted alpha, and tints by painted color. Set the mode to Alpha only, pick two textures in the material, and paint dirt, moss, or wear exactly where you want it.
Booleans
Tools menu: Boolean Union / Subtract / Intersect. Edit mesh A, then Ctrl+click mesh B in the scene tree so both are selected, and run the operation. B is consumed, A becomes the result, and the result is ordinary editable geometry. One undo restores both.
Both meshes must be watertight (every edge shared by exactly two faces). If the edited mesh isn't, the operation refuses and selects the offending edges for you, switched into Edge mode. Usually a Fill Hole or Conform Normals fixes it, then run the boolean again.
- Materials survive: result surfaces keep the operand they came from.
- An intersect of two meshes that don't overlap warns and changes nothing.
- Marked experimental: the underlying kernel (Godot's Manifold CSG) is robust, but re-building clean editable n-gons from its output is best-effort on complex results.
Object tools
Whole-object operations (Tools menu)
| Tool | What it does |
|---|---|
| Merge Objects | Every other selected Unibuilder node merges into the edited one, transforms baked, materials preserved. One undo restores all the original nodes. |
| Mirror X / Y / Z | Duplicates the mesh reflected across the node's local axis plane and welds the seam. Model half a thing, delete the faces on the mirror plane, mirror, done: the result is watertight. |
| Triangulate Object | Converts every face to triangles. |
| Subdivide Object | Splits every face in four. |
| Conform Normals | Fixes inside-out faces by flooding a consistent winding across the mesh, majority wins. |
| Convert to Unibuilder | Turns any selected plain triangle mesh (imports, CSG bakes) into an editable Unibuilder mesh: welds vertices, merges coplanar regions back into n-gons, and reconstructs smoothing from face angles. |
Collision
The collision_mode property on the node maintains an automatic collision body that regenerates on every edit and exists in exported games:
| Mode | Use for |
|---|---|
| Convex | Simple solid props. Fastest at runtime. |
| Trimesh | Exact static level geometry, including concave shapes. |
| Ramp | Stairs. A smooth wedge over the bounds so characters glide up instead of bumping each tread. |
Collider and Trigger volumes
Set Collider and Set Trigger in the Tools menu mark a mesh as invisible helper geometry: tinted in the editor (orange for colliders, blue for triggers), hidden when the game runs, physics child left behind. A Collider keeps a StaticBody3D for invisible walls; a Trigger swaps it for an Area3D ready to fire body_entered. Running the same item again returns the mesh to normal.
Baking and exporting
| Tool | What it does |
|---|---|
| Bake to MeshInstance3D | Replaces the node with a plain MeshInstance3D carrying the compiled mesh, with lightmap UV2s generated so LightmapGI works out of the box. The texel size lives in Preferences; 0 skips it. |
| Export OBJ… | Writes an OBJ with n-gons preserved plus an MTL sidecar with base colors and texture references. Blender opens it correctly oriented. |
| Export glTF… | Writes .glb or .gltf of the compiled mesh with materials. |
Preferences
Tools → Preferences: overlay colors, vertex handle size, the face-mode Grow angle limit (180 disables it), and the bake lightmap texel size. Settings persist per project.
Keyboard reference
| Key | Action |
|---|---|
| 1 2 3 4 | Object / Vertex / Edge / Face mode |
| Esc | Back to Object mode; cancels any drag, modal tool, or adjust session first |
| W / E / R | Move / Rotate / Scale gizmo |
| Shift+drag (Face mode, Move) | Extrude the selected faces |
| V (hold, while move-dragging) | Vertex snapping |
| Ctrl (hold, while dragging) | Invert grid snapping |
| Ctrl+A / Ctrl+I | Select all / invert selection |
| Double-click edge / Alt+double-click | Edge loop / edge ring |
| Double-click face | Face loop |
| Del (Face mode) | Delete faces |
| Ctrl+B | Modal bevel (Edge mode) / inset (Face mode) drag |
| [ / ] | Halve / double the grid step |
| , / . / 0 | Nudge grid plane down / up / reset |
| Backspace (Poly Shape / Cut) | Remove the last placed point |
| Enter (Poly Shape / Cut) | Close the outline |
| Shift+click (Paint) | Eyedrop |
| UV editor: Ctrl+drag / Alt+drag | Scale / rotate the UV selection |
| UV editor: double-click | Select UV island |
Performance and limits
- Editing cost scales linearly with face count. Typical blockout objects (up to roughly 1,000 faces) edit at full interactivity; at 5,000+ faces drags update at a few frames per second. Split very large levels across several objects, which you'd want anyway for undo granularity and occlusion.
- Paint strokes never trigger a recompile, so painting stays fast even on dense meshes.
- The mesh is recompiled whole on every change. This is deliberate: it keeps every operation robust and every undo exact.
- The benchmark script that produced the published numbers ships in the repository; methodology is in the README.
Troubleshooting
| Symptom | Likely cause and fix |
|---|---|
| A face looks like a hole from one side | It's inside out. Select it and Flip, or run Conform Normals on the object. |
| Boolean refuses to run | A mesh isn't watertight. The offending edges are already selected; Fill Hole usually fixes it. |
| Painted color doesn't show | The material needs Vertex Color → Use As Albedo, or use the blend material. |
| Texture crawls when the object moves | Those faces are world-anchored. Switch the anchor back to local in the face panel. |
| UVs went back to automatic after editing | A topology op changed the face's corner count, so stale manual UVs fell back. Re-bake with Manual. |
| The editor gizmo is gone in Object mode | A Unibuilder node was the sole selection, so Unibuilder's gizmo (grid-snapped) replaced it. Select multiple nodes to get the native one back. |
License, in short
Per-seat: one license per person using the plugin in the editor, on as many of their machines as they like. Unlimited projects, commercial included, no royalties. Games you ship may embed the plugin's runtime files. You may not redistribute the plugin itself, publicly or privately, modified or not. The full EULA ships with your purchase and is the binding text.