Duckboard _{for Godot 4.7+}

Note

Duckboard is in early development (0.x). It is already a capable brush editor, but the API and file layout may still change before 1.0. Back up your scenes.

Duckboard is a Godot editor plugin that brings TrenchBroom-style brush editing straight into the 3D viewport - grid-snapped convex brushes with vertex, edge, and face editing, clip and CSG tools, world-projected per-face textures, and a two-way .map clipboard so you can paste geometry to and from TrenchBroom itself. If you know TrenchBroom, your hands already know Duckboard: the tools, shortcuts, and grid model are deliberately the same.

Why Duckboard

Blocking out levels for a Godot game usually means one of two things: fighting CSG nodes and gizmos that were never built for level design, or working in an external editor (TrenchBroom, Hammer) and living with an export/import round-trip every time you want to see the level with your actual lighting, materials, and gameplay.

Duckboard removes the round-trip. Brushes are real nodes in your scene tree - they render with your materials and lights, they save in your .tscn, they undo with Ctrl+Z, and you can attach gameplay to them by extending the Brush class. The editor is the game engine.

Features

Brush editing

• Convex brushes, TrenchBroom-style - drag out cuboids, stairs, cylinders, and cones with a live ghost preview. Drawing needs no tool: with nothing selected, a drag just draws.
• Vertex, edge, and face tools - reshaping a shared corner or edge moves it on every selected brush, so seams between abutting brushes never tear open.
• Face gestures - Shift+drag pushes a face's plane along its normal; Ctrl+Shift+drag extrudes a new brush outward or splits the brush inward. Hovering a selected brush's outline grabs the face hidden behind it, so the far side is reachable without orbiting round.
• Clip tool - place points, cycle keep-front/keep-back/keep-both with Ctrl+Enter, apply with Enter.
• Scale, shear, rotate - Alt anchors scale to the centre, Shift scales proportionally, Alt shears vertically; numeric toolbars for exact sizes, factors, and angles.
• CSG - Convex Merge, Subtract, Intersect, Hollow, and a two-face bridge.
• Brush groups - several brushes that read as one unit and collapse to a single merged mesh at rest, so the map is always already baked, group by group. Faces buried between touching members are dropped from that mesh. Double-click a group to edit its members individually, with the rest of the map washed back for context.
• Collision, with nothing to set up - every brush and group has a Collision section: Type, Layer and Mask, in the same place and under the same names as any other physics node. Static by default, None for trim and decoration, Moving Platform for lifts, Rigid Body for props that fall, Trigger Volume for the brush entity every Quake map is full of — water, lava, ladders, damage zones, level exits — which builds an Area3D your game can query and walk straight through; the Physics menu sets it on a whole selection at once. A brush is a convex hull already, so it collides as its exact shape, and a group collides as one convex piece per member - no approximation, no bake step, and nothing added to your scene tree. Reshape, move, group, duplicate or delete the geometry and the collision follows.
• Occlusion for free - brushes also generate an occluder, so level geometry hides what is behind it. A brush is closed, convex and low-polygon, which is exactly what an occluder wants, so there is nothing to bake or simplify. Switch it off per solid for glass and railings. (Occlusion culling has to be enabled in Project Settings to take effect.)
• Lightmap UV2, no bake step - switch it on per solid and the second UV set LightmapGI needs is packed with the mesh, at whatever texel density you set. A brush's faces are already flat, so there is nothing to unwrap and no xatlas pass - which also means it works in an exported game, where Godot's own Unwrap UV2 does not exist at all. Deterministic, so anything you keep in that UV space stays put across loads.
• Multi-brush everything - every tool acts on the whole selection.

Textures & UVs

• World-projected per-face textures using TrenchBroom's Valve-220 parallel UV system, with texture lock and UV lock so geometry edits don't smear your alignment. Textures arrive at their own size - a 64x128 image covers 64x128 map units, TrenchBroom's scale 1 - and Fit solves scale and offset so a face holds whole repeats with nothing cut off at the edges.
• Transparent pixels are cut out, not blended, so brushes stay in the opaque pass and keep their shadows and sorting. Faces left untextured are dropped from the mesh in the running game, which gives you nodraw with no bake step.
• Texture dock - a searchable thumbnail browser of your project's textures and materials; click to assign to the selection.
• Drag & drop - drop a texture or material from the FileSystem dock onto a face, or hold Shift for the whole brush.
• UV canvas - drag, rotate, and scale a face's UVs visually, on its actual material.
• Face selection - Shift+click selects a face, Ctrl+Shift+click adds more; the dock edits any mix of faces and brushes as one set.

TrenchBroom interop

• Two-way .map clipboard - Ctrl+C copies the selection as Valve-220 .map text; Ctrl+V pastes TrenchBroom's clipboard as real brushes, framed in front of the camera. Unit scale (32 TB units = 1 m), Z-up↔Y-up, and UV axes are converted for you.
• Groups cross too - a copied group arrives in TrenchBroom as a group, and a TrenchBroom object (a group, a func_detail, a door, a trigger) arrives here as one. TrenchBroom's nested groups flatten into one, since Duckboard's groups are a single level.
• The same muscle memory - TrenchBroom's tool shortcuts, selection modifiers, and grid behaviour (only the element you edit snaps; untouched geometry keeps its exact coordinates).

A native Godot citizen

• Per-scene toggle - a duck button in the 3D toolbar turns map-editing mode on per scene, remembered across sessions. Off means off: every shortcut and gizmo returns to stock Godot.
• One undo step per gesture - every draw, drag, clip, paste, and texture assignment is a single, cleanly named entry in Godot's undo history.
• Extensible brushes - attach behaviour with extends Brush (call super() in _ready); all tools recognise subclasses.
• A way out - Convert to Mesh replaces a brush or group with the plain engine nodes it was already deriving - mesh, body, collision shapes, occluder - owned, saved, and working with the addon deleted. One-way (the editable geometry goes), undoable until you save, and the honest answer to what happens to your level if this project stops.
• Responsive tool palette - Blender-style: drag it wider for two columns or full labels.

Installation

Duckboard is not on the Asset Library yet. Until then:

1. Copy addons/duckboard into your project's addons/ folder.
2. Enable Duckboard in Project → Project Settings → Plugins.
3. Open a 3D scene and press the duck button in the 3D viewport toolbar.

Requires Godot 4.7 or newer - the version Duckboard is developed and tested on.

This repository is the full development project (test scenes, textures). The addon itself is entirely contained in addons/duckboard.

Shortcuts

Active only while map-editing mode is on - with the duck off, Godot's own bindings return.

Tool	Key		Action	Key
Brush (hull)	B		Duplicate	Ctrl+D (or Ctrl+drag)
Clip	C		Flip horizontally	Ctrl+F
Vertex	V		Flip vertically	Ctrl+Alt+F
Edge	E		Group / ungroup	Ctrl+G / Shift+Ctrl+G
Face	F		Copy / paste .map	Ctrl+C / Ctrl+V
Rotate	R		Delete selection	Delete
Scale	T		Nudge selection	arrows, PgUp / PgDn
Shear	G		Grid size up / down	+ / -
UV lock	U		Grid size 1 - 256 units	1 ... 9
			Commit hull / apply clip	Enter
			Cancel / deselect / leave tool	Escape

Drawing - the Simple Shape tool has no button and no shortcut, matching TrenchBroom: with nothing selected and no tool active, just drag in the viewport. B is the Brush tool, which builds a brush from the convex hull of points placed on existing faces. Selection - click selects a brush, Ctrl+click toggles it in the selection, Shift+click selects a face, Ctrl+Shift+click adds a face. Face gestures - Shift+drag pushes a face's plane; Ctrl+Shift+drag extrudes outward or splits inward. Groups - double-click a group to open it, Escape or a click outside to close. Nudging - the arrow keys move the selection one grid cell in the direction they point on screen, PgUp / PgDn move it up and down; hold a key to keep going.

Deliberate divergences from TrenchBroom

Duckboard follows TrenchBroom where it can and diverges only on purpose - each of these is a considered decision, not a gap:

• Rotation transforms the geometry, not the node - planes are rotated in place, so textures and UVs survive untouched and node transforms stay identity.
• Materials, not just textures - a face can wear a full Godot Material, shown as a sphere in the browser. That's a Godot-native superpower the .map format can't express.

Roadmap

• Settings panel for grid, colours, and keybindings.
• Godot grid sync - drive the orthographic view grids from the plugin's grid size.

Credits

• TrenchBroom by Kristian Duske and contributors - the design north star for the whole plugin.
• The example scene is dressed with Retro Textures Fantasy and Skyboxes by Kenney - released under CC0, and a genuine pleasure to build a demo level with. The test map is modelled on the sample render that ships with Retro Textures Fantasy, rebuilt as brushes in Duckboard. Thank you, Kenney. These assets live in tests/ and are part of the development project only; the addon itself ships no third-party assets.
• The example scene's fish is Fish by Quaternius - also CC0, and likewise part of the development project only.
• Made by Diogo Gomes as tooling for his future game, Rune Thief.

Duckboard is released under the MIT license.