Brush-based level editor for Godot 4.7+
Requires Godot 4.7+ (tested on 4.7.stable). Works in both editor and exported games via HFIORuntime.
Draw rooms, carve doors, paint terrain, and bake to optimized meshes — all inside the Godot editor.
81 brushes. Every column, wall bay and gallery drawn with the tools below, textured with the built-in prototype materials.
Fair warning: This is a solo hobby project in early alpha. I built it to support another project and it grew from there. It's buggy, rough around the edges, and a bit directionless. If any of this looks useful to you, I'd genuinely appreciate help testing and filing issues. Contributions welcome -- just know you're signing up for an adventure, not a polished product.
Four steps, each a real screenshot of the editor. The dock tab on the left is the one you would actually be using at that point.
| 1. Draw a floor | 2. Raise the walls |
|---|---|
 |  |
| Drag a base, click to set height. One brush, one shape. | Add walls and leave a gap for the door. Still two clicks each. |
| 3. Add detail and materials | 4. Test it |
|---|---|
 |  |
| Platform, ramp, pillars, and prototype textures from the Paint tab. | The Console checks the level, then Test Level bakes and plays it. |
HammerForge runs inside the Godot editor -- its own dock, main-screen entry, and viewport tools.
Level editors like Hammer and TrenchBroom proved that brush-based workflows are the fastest way to block out 3D spaces. HammerForge brings that paradigm into Godot so you never have to leave the editor:
- No full-scene live CSG -- brushes are lightweight preview nodes; full CSG runs only at bake time. An optional, capped subtract overlay computes only nearby cut previews.
- Two-click geometry -- drag a base rectangle, click to set height. Extrude faces to extend rooms. Type exact numbers any time.
- Paint floors and terrain -- grid-based floor paint with heightmaps, multi-material blending, auto-connectors (ramps/stairs), and foliage scatter.
- Bake when ready -- one click produces merged meshes, collision shapes (trimesh, per-brush convex, or per-visgroup partitioned), lightmap UVs, navmeshes, and LODs.
HammerForge is a single addons/ folder. No external tools, no custom builds, no export plugins. Drop it in, enable, draw.
| Subsystem-based coordinator architecture | 2,200 unit + integration tests with CI on every push |
| 15 brush shapes (box through dodecahedron) | 150 built-in prototype textures for instant greyboxing |
Quake .map + glTF .glb export | .hflevel native format with threaded I/O |
| Customizable keymaps (JSON) | Plugin API for custom tools |
| Dark/light theme sync across all custom UI | Performance health monitor with recommendations |
| HammerForge Console -- RAG status board, every toggle, live log | Main-screen entry -- the mark beside 2D, 3D and Script |
1. Copy addons/hammerforge into your project
2. Enable the plugin: Project -> Project Settings -> Plugins -> HammerForge
3. Open a 3D scene and use Create Starter in the empty-state banner
4. Verify: the dock shows Build, Paint, Objects, and Test; the primary toolbar shows Draw, Select, Paint, More, and Help
Create Starter adds LevelRoot, a floor, sunlight, and a player spawn. Create Empty adds only LevelRoot. An intentional Draw-tool left-click can also create an empty root; navigation, selection, and other passive input never modify the scene.
Upgrading? See Install + Upgrade for upgrade steps and cache reset.
This repository also vendors a project-scoped Godot MCP server in addons/godot_mcp. Each contributor creates an ignored, machine-local .codex/config.toml; authentication comes from the user-scoped HAMMERFORGE_GODOT_MCP_TOKEN environment variable. Codex configuration, tokens, and Godot user:// MCP state must never be committed. See Install + Upgrade for the configuration and verification steps.
| Step | Action |
|---|---|
| 1. Create | In a 3D scene, click Create Starter. Choose Create Empty only when you do not want the floor, sunlight, and spawn. |
| 2. Draw | In Build, choose Draw + Solid + Box, drag the base in the viewport, then click to set height. |
| 3. Test | Click Test Level (Bake + Play) in Test, or press Ctrl+Enter. HammerForge checks, bakes, validates the spawn, and runs the scene. |
| Optional: Cut | Press Q to switch Solid/Cutout, draw through existing geometry, then apply or commit cuts. |
| Optional: Material | Open Paint → Materials, select faces, and assign a prototype or project material. |
| Optional: Floor paint | Press Shift+P, choose Paint/Erase/Rect/Line/Bucket/Blend, and paint cells or surfaces. |
| Document | Description |
|---|---|
| User Guide | Complete usage documentation |
| MVP Guide | Architecture and contributor reference |
| Install + Upgrade | Setup, upgrade, and cache reset |
| Design Constraints | Explicit tradeoffs and limits |
| Data Portability | .hflevel / .map / .glb workflow |
| Texture + Materials | Face materials, UVs, and surface paint |
| Prototype Textures | Built-in 150 SVG textures |
| Floor Paint Design | Grid paint system design |
| Editor Smoke Checklist | Repeatable live-editor verification flow |
| Development + Testing | Local setup, architecture, test checklist |
| Spec | Technical specification |
| Changelog | Version history |
| Roadmap | Planned features and priorities |
| Brand | The mark, palette, and asset generators |
| Contributing | How to contribute |
| Code of Conduct | Expected behavior and how to report a problem |
| Security Policy | What counts as a vulnerability and how to report one privately |
| Demo Clips | Clip list and naming scheme |
| Sample Levels | Minimal and stress test scenes |
This is a one-person project and there's more here than one person can properly test. If you try HammerForge and something breaks, please open an issue -- even a one-liner like "Hollow crashed on a cylinder" is helpful. Specific areas where help would make a real difference:
- Bug reports -- the test suite covers a lot, but editor-context bugs are hard to catch headless
- Playtesting -- try the workflows (draw, bake, quick play) and report what feels broken or confusing
- Edge cases -- large levels, unusual brush shapes, rapid undo/redo, plugin reload cycles
- Documentation -- if something in the user guide doesn't match reality, flag it
- Good first issues — scoped small, no deep architecture knowledge needed
- Help wanted — things I can't get to alone
- Browse by area —
area:labels map to the dock tabs: Build, Paint, Objects, Test - Milestones — what the open work is grouped under
- Discussions — for questions that aren't bug reports
See CONTRIBUTING.md for local setup and the check commands, and CODE_OF_CONDUCT.md for how we treat each other here.
The Console's Controls tab collects every HammerForge setting in one place, grouped by what it affects — Viewport (what you see while building, none of it changes the level), Bake (how drafts become the meshes that ship), and Safety net (autosave, backups, logging). Each switch carries a one-line reason, not just a label.
The complete feature reference, architecture notes, keyboard shortcuts, testing guide, roadmap and troubleshooting now live in the documentation site:
- Features and Reference -- every workflow in detail
- User Guide
- Install and Upgrade
- Regenerating the screenshots