# Cyclops Level Builder trades version compatibility for collision on every block > Cyclops Level Builder is an MIT licensed Godot addon that builds blockout levels by clicking and dragging in the viewport, with collision on every block and a material editor. The cost is that its versions are pinned to Godot releases, and upgrading can break scenes you already built. **blackears/cyclopsLevelBuilder** — A Godot plugin to let you block in levels inside the Godot editor. - Repository: https://github.com/blackears/cyclopsLevelBuilder - Stars: 1,647 · Forks: 66 - Language: GDScript - License: MIT - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/blackears-cyclopslevelbuilder ## Click, drag, done: what the addon actually adds to the editor Cyclops Level Builder works inside the Godot viewport rather than as a separate modelling tool. You click and drag to create and edit blocks, the material editor assigns materials, and every block carries collision so you can interact with it immediately after placing it. That last point is the design decision worth naming. Most blockout workflows produce geometry you then have to collision-wrap, one body at a time. Shipping collision as inherent to the block trades authoring speed against flexibility, and for a blockout stage where you want to walk the level the same day it is laid out, that is usually the right trade. The code is GDScript, the repository carries a VERSION.txt and an art/ directory, and the documentation is built with mkdocs given the mkdocs.yml at the top level. A create_addon_archive.py script in the root suggests releases are packaged from the repository rather than built by hand each time, and subprojects/ plus godot/ directories point at the addon being assembled out of more than one Godot project. The editor experience is shown rather than described in the README, which embeds a short demo video instead of a manual. The prose documentation lives at a separate GitHub Pages site. ## Version to Godot mapping is the compatibility contract The addon is tied to engine versions, and the README states the mapping plainly. Cyclops Level Builder 1.5.0 works with Godot 4.7 and later. Version 1.0.2 works with Godot 4.2 and later. Versions 1.0.1 and earlier work with Godot 4.0. Read that as a floor statement with an upper edge. The 1.5.0 line is the one to use on a current engine, and 1.0.2 is the fallback if you are pinned to a 4.2 era project. There is no claim that 1.5.0 works on 4.2, and assuming forward compatibility is how you end up with a broken scene file. The release history is quick and recent: v1.5.1 on 2026-10-13 fixing tool gizmos and single window mode, v1.5.0 on 2026-09-17 which added the UV editor, and a v1.5.0_dev_3 from 2026-08-26 that fixed the root folder in the distributable. The repository is not archived and the last push was on 2026-10-15, one day after the latest release, so development is still moving and version numbers will keep climbing. ## Installing from the releases archive, then enabling the autoload Installation is a manual copy, not a package manager step. Download the latest release, unzip it to a temporary directory, then copy the `/addons/cyclops_level_builder` folder and everything inside it into the `/addons` folder of the target project. In the editor, open Project Settings, go to the Plugins tab and tick Enable next to the Cyclops Level Builder entry. Then go to the Globals tab and confirm an entry called `CyclopsAutoload` exists, points at `res://addons/cyclops_level_builder/cyclops_autoload.tscn`, and is enabled. That second step is the one people miss. From version 1.5.0 it should be created automatically, but earlier versions need it added by hand, and it can also be left disabled if you are upgrading from an earlier release. The project name it registers matters: `CyclopsAutoload`. If you clone instead of downloading the release, the repository uses LFS for large files, so your git client must support it. The README calls out Mint Linux by name as a system where LFS support may need enabling separately. ## Upgrading can invalidate scenes, and there is a migration button The README puts a warning at the top of the upgrade section: back up your project before upgrading, because some updates may break previously built scenes. That is unusual honesty for a plugin readme and it shapes how you should work with this addon. There is a recovery path. The import and export features migrate level assets between incompatible versions, and if you use version control such as GitHub you can restore previously trashed assets and then export them. So the migration story is migrate forward, or roll back in git and re-export, rather than patch by hand. One concrete example is spelled out. Upgrading from v1.0.0, v1.0.1 or an earlier development build of 1.0.2 requires upgrading the CyclopsBlocks object. Select it in the Scene outliner and click the Upgrade button that appears in the toolbar. That creates a new subtree where the old CyclopsConvexBlock objects are replaced by the new CyclopsBlock object, while the original CyclopsBlocks object stays in the scene with its visibility turned off and can be deleted once you no longer need it. Note what this migration leaves behind: a hidden legacy subtree you have to remember to remove. ## What it will not do for you It is a blockout tool, not a modelling tool. The blocks exist to be arranged at the greybox stage. The README describes no UV workflow for shipping assets, only that 1.5.0 added a UV editor, and it says nothing about mesh deformation, boolean operations, or any way to convert a built level into production geometry. It is also single user and local. There is no collaboration story, no scene merging for two people working on the same level, and no headless or command line mode in the repository layout. If your pipeline needs level geometry generated from a script, this addon is not in that pipeline. The documentation is external to the repository. The README points at a GitHub Pages site for usage documentation and contains a demo video rather than a manual, so the details of the material editor and the UV editor are not in the project you are reading. Judge the feature depth from the docs site, not from the README. ## Against building greyboxes by hand and against a generic editor addon The honest alternative is primitive boxes. The cost of that approach is repetition. Manual blockout can require repeated mesh and collision setup. An addon that makes one block one object is removing a factor of two or three from the node count and making the level readable in the outliner. That wins on ergonomics for pure layout and loses on the fact that you leave the engine, import, and then cannot push a change back without re-exporting. What Cyclops adds that neither has is editing in the live engine viewport with collision already present. That is why the version coupling is tolerable for new work and painful for an existing project. ## Conclusion Adopt Cyclops Level Builder if you block out Godot levels by hand in the viewport rather than importing greybox geometry, and if you can start a project on Godot 4.7 to match version 1.5.0. Do not adopt it mid project if you are on an older Godot, because the addon is version specific and an upgrade can break existing scenes. Verify first that the release you download matches your engine version, that the CyclopsAutoload global is enabled at the documented scene path, and that your git client resolves LFS, since the repository stores large files that way and a partial clone gives you an addon with missing files. ## FAQ ### Which Godot version does Cyclops Level Builder need? Version 1.5.0 works with Godot 4.7 and later, version 1.0.2 works with Godot 4.2 and later, and versions 1.0.1 and earlier work with Godot 4.0. ### How do I install Cyclops Level Builder in a Godot project? Download the latest release, unzip it, and copy the /addons/cyclops_level_builder folder into your project's /addons folder. Then enable it on the Plugins tab of Project Settings and confirm the CyclopsAutoload global is enabled at res://addons/cyclops_level_builder/cyclops_autoload.tscn. ### Do the blocks created by Cyclops Level Builder have collision? Yes. Every block has collision, so you can interact with a block as soon as you place it rather than adding collision separately. ### What happens to my scenes when I upgrade Cyclops Level Builder? Some updates may break previously built scenes, so the README advises backing up the project first. You can migrate level assets with the import and export features, or restore trashed assets from version control and export them again. ## Sources - [blackears/cyclopsLevelBuilder on GitHub](https://github.com/blackears/cyclopsLevelBuilder) - [Issues](https://github.com/blackears/cyclopsLevelBuilder/issues) - [License: MIT](https://github.com/blackears/cyclopsLevelBuilder/blob/master/LICENSE) - [README](https://github.com/blackears/cyclopsLevelBuilder/blob/master/README.md) - [Releases](https://github.com/blackears/cyclopsLevelBuilder/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/blackears-cyclopslevelbuilder