TrenchFold — TrenchBroom extension for Defold

As promised, I’m sharing something very special. I’m sure those who are nostalgic for the old level editors are going to get excited… :nerd_face:


This is a kit of game configuration files and importing scripts to design your level with TrenchBroom and export it to Defold as the collection.

TrenchBroom was originally created to design Quake-format levels, but thanks to its flexible game configurations it’s suitable for any other game with low-polygon level geometry. It’s cross-platform, has a great manual and usability.

:video_game: Play HTML5 demo level made in TrenchBroom with Retro Texture Pack, Operator and Kinematic Walker.

What does the export look like?


  • Convert level geometry to meshes and collision objects.
  • Use flag textures and checkboxes to define faces behavior.
  • Place triggers, kinematic or dynamic bodies.
  • Convert entities to game objects.
  • Attach file components to your entities.
  • Set custom entity properties and read them from the game logic.
  • Define areas and handle their coordinates in scripts.
  • Run importing with the editor script or the standalone lua module.
  • Expand the game configuration file with your own classes.


Full documentation is available in the GitHub repository.


What’s next?

First of all, I wanted to remember the level design. What is level design today? There’s so much stuff in there, as much as geometry. I can’t do it all by myself and that’s why I wanted something simple that didn’t require a lot of time and skills. Go back to 2000’s mapmaking, back to old CS and UT games. That’s why I found the TrenchBroom level editor.

Subsequently, all these extensions were created, with the goal of starting to walking with first-person look on the TrenchBroom-created maps in the Defold game engine. And there it is, yay! :tada:

To be honest, I burned out while doing all this stuff. And unfortunately I don’t have time to finish the lighting. I wanted to implement dynamic cluster lighting (sounds like that!).

Well, I’m going to take a few months break and do more balance in my life. Will also think about what kind of game I want to make with these extensions. :thinking:


I’m not sure is it OK with path handling on Windows. So, please, check the demo level export on Windows and let me know in PM if there are any problems :smiling_face_with_three_hearts:


No way! This is so amazingly cool!

You have done an amazing job creating these extensions. On behalf of the whole Defold community I thank you! :tada: :heart: :+1:

I hope someone else from the community is up for the challenge!


Wow! Another amazing extension! :heart_eyes: Thank you so much for this @astrochili ! :heart:


This is amazing! Great work!

Are you talking about clustered forward lighting? I’ve been interested in attempting something like that for a while. Would be a good use case for a compute shader experiment :slight_smile: But maybe start with something simpler like good old deferred shading, which should be doable with what we have now. Not sure I have a ton of time to do it, but I would be glad to help out at least if someone else wants to do it and has the time for it.


Are you talking about clustered forward lighting?

I may be confusing terms, but I was inspired by this article. Although I still don’t understand how and why to use viewport matrix here, I came up with the following idea.

The information about all the lights can be stored in a small texture, which would be referenced by all the materials that would want to use it to calculate shading. Inside the texture I would organise information about all the light sources and level clusters they affect with their range. For each source I would store the position, colour, brightness and the cluster index.

In the fragment shader, I would read that texture, figure out which light sources I want to use from the current cluster based on the current vertex position, and use them to calculate the rendering color.

In this way, you can allow many light sources to be placed on the map, but use in calculations only those that actually affect the colour of the current texture. To become dynamic, light sources can change this texture at runtime while moving or animating their parameters.

At least that was the idea, inspired by the article and @nikolay.armonik.


Anyway, I’d be happy to see any of the solutions that will allow us to place and adjust the lighting sources on the map :smiling_face_with_three_hearts:.

Static lighting with the whole level lightmap is still possible. Right now it is possible if you export the level from the TrenchBroom into Blender, merge all the textures, arrange the lighting, bake the lightmap and export new uv coordinates into Defold.

This doesn’t solve the dynamic lighting issue, but it can at least create a very nice static picture. Theoretically, you could even automate this by running Blender without UI using a python script. Run it as part of the extension export process with arranging the lighting in Blender based on the light entities placed in Trendbroom.


By the way, I shared all the blockout textures that I made and use in development. The pack is available on github and, feel free to use it :ok_hand:.


This is really cool!

Please everyone share some financial support with @astrochili for giving to the Defold community so much!

Match me!


Are you kidding me? And with collisions and everything?! This is amazing!

I started tinkering with Defold with hopes to potentially make a low poly FPS in the future, you saved me a massive amount of work, THANK YOU!


Yes, this is a very suitable utility for this purpose :wink:

By the way, in case you faced with problems with too much complex collision objects. Don’t forget about the possibility to separate collisions from the visual geometry with the clip texture.

For example, you can separately design the whole level with details and mark it with the ghost flag. Then, in a separate layer create primitive collision brushes with the clip and unused textures. This is a bit more manual than using the level geometry as collision objects, but the physics engine will thank you for it.


This looks great. Thank you for making it :+1:

Unfortunately, I’m having a little problem. I followed the required steps, but when I right click on the .map file and press “Prepare Map Components Folders”, it gives me this error:

ERROR:EXT: Prepare Map Components Folders's "run" in /trenchbroom/trenchbroom.editor_script failed:
ERROR:EXT: /trenchbroom/trenchbroom.editor_script:45 attempt to index ? (a nil value)

Any idea where my mistake is?
Thank you again

1 Like

I think you are on Windows, right?

1 Like

Yes, right

I was sure there would be something wrong with paths on Windows. Could you help me to figure out?

  1. Turn off the extension from the dependencies and download the trenchbroom folder directly into the your project folder.

  2. Add print() commands in the trenchbroom.editor_script like in the screenshot, reload the editor extension and run it again.

  1. Can you share the output?
1 Like
ERROR:EXT: Prepare Map Components Folders's "run" in /trenchbroom/trenchbroom.editor_script failed:
ERROR:EXT: /trenchbroom/trenchbroom.editor_script:51 attempt to index ? (a nil value)

Hope this helps

1 Like

Thank you, now I understand the bug. Can you replace some files in the trenchbroom folder with these? (1.7 KB)

This should work, but the next thing I’m worried about is the shell scripts :thinking:.

The first time it gave a warning about the shell script, I ignored it.
When I press “Prepare Map Components Folders”, This happens:

# Cleaning up
Clean up 'assets/maps/buffer'
Clean up 'assets/maps/mesh'
Clean up 'assets/maps/convexshape'
Clean up 'assets/maps/collisionobject'
Clean up 'assets/maps/script'
ERROR:EXT: Prepare Map Components Folders's "run" in /trenchbroom/trenchbroom.editor_script failed:
ERROR:EXT: Cannot run program "sh" (in directory "D:\AllProjects\Defold\ProjectLambda"): CreateProcess error=2, The system cannot find the file specified

When I press “Convert Map to Collection”, This happens:

# TrenchBroom to Defold
Starting with map 'assets/maps\'

# Parsing
Parsing 'assets\maps\'
Parsing 'assets\maps\Level_00.obj'
Parsing 'assets\maps\Level_00.mtl'

# Building
Putting all the data together
ERROR:EXT: Convert Map to Collection's "run" in /trenchbroom/trenchbroom.editor_script failed:
ERROR:EXT: @trenchbroom/builders/level.lua:117 Can't find the brush 'entity0_brush0' in .obj file. Looks like the file is outdated. Try to export .obj from TrenchBroom again to get updated geometry.

.obj is not outdated though, I exported it again, and I don’t know what entity0_brush0 is

Oh, I definitely need to find a Windows machine or someone with Windows who helps us to fix it.

ERROR:EXT: Cannot run program “sh” (in directory “D:\AllProjects\Defold\ProjectLambda”): CreateProcess error=2, The system cannot find the file specified

As I understand Defold runs shell scripts using the system shell app that is not presented in Windows. But because the only thing which this shell script doing is deleting and creating folders so you can do it manual. Just create empty folders:

  • ‘assets/maps/buffer’,
  • ‘assets/maps/mesh’,
  • ‘assets/maps/convexshape’,
  • ‘assets/maps/collisionobject’,
  • ‘assets/maps/script’

It’s looks like an another reason to solve #6810 to avoid using shell scripts because it doesn’t work on Windows without additional preparing.

ERROR:EXT: @trenchbroom/builders/level.lua:117 Can’t find the brush ‘entity0_brush0’ in .obj file. Looks like the file is outdated. Try to export .obj from TrenchBroom again to get updated geometry.

So far, it looks exactly as written. Could you share the project archive where I can see what’s wrong?


Btw, if you have a way to run lua outside the Editor then just run something like this:

$ lua.exe trenchbroom/cli.lua /assets/maps Level_00`

It does all the work without editor and shell scripts.