{"id":15722571,"url":"https://github.com/astrochili/defold-trenchfold","last_synced_at":"2025-04-08T04:18:31.662Z","repository":{"id":46374315,"uuid":"497611702","full_name":"astrochili/defold-trenchfold","owner":"astrochili","description":"A toolkit to design a level in TrenchBroom and export it to Defold","archived":false,"fork":false,"pushed_at":"2025-01-01T20:44:03.000Z","size":523,"stargazers_count":58,"open_issues_count":6,"forks_count":7,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-01T16:21:42.499Z","etag":null,"topics":["3d","defold","leveldesign","trenchbroom"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/astrochili.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-29T14:17:21.000Z","updated_at":"2025-02-20T14:19:20.000Z","dependencies_parsed_at":"2024-01-21T13:22:39.552Z","dependency_job_id":"96835279-78bd-4281-ab11-e8311902ddb5","html_url":"https://github.com/astrochili/defold-trenchfold","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrochili%2Fdefold-trenchfold","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrochili%2Fdefold-trenchfold/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrochili%2Fdefold-trenchfold/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrochili%2Fdefold-trenchfold/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/astrochili","download_url":"https://codeload.github.com/astrochili/defold-trenchfold/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247773721,"owners_count":20993639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","defold","leveldesign","trenchbroom"],"created_at":"2024-10-03T22:08:26.126Z","updated_at":"2025-04-08T04:18:31.640Z","avatar_url":"https://github.com/astrochili.png","language":"Lua","funding_links":["https://buymeacoffee.com/astrochili"],"categories":["Libraries"],"sub_categories":["Programming Language"],"readme":"![logo](https://user-images.githubusercontent.com/4752473/179576684-bea03ccb-0b52-4346-819a-927e4d5d3c0e.jpg)\n\n# TrenchFold\n\n[![Release](https://img.shields.io/github/v/release/astrochili/defold-trenchfold.svg?include_prereleases=\u0026sort=semver\u0026color=blue)](https://github.com/astrochili/defold-trenchfold/releases)\n[![License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/astrochili/defold-trenchfold/blob/master/LICENSE)\n[![Website](https://img.shields.io/badge/website-gray.svg?\u0026logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxOCIgaGVpZ2h0PSIxNiIgZmlsbD0ibm9uZSIgdmlld0JveD0iMCAwIDE4IDE2Ij48Y2lyY2xlIGN4PSIzLjY2IiBjeT0iMTQuNzUiIHI9IjEuMjUiIGZpbGw9InVybCgjYSkiLz48Y2lyY2xlIGN4PSI4LjY2IiBjeT0iMTQuNzUiIHI9IjEuMjUiIGZpbGw9InVybCgjYikiLz48Y2lyY2xlIGN4PSIxMy42NSIgY3k9IjE0Ljc1IiByPSIxLjI1IiBmaWxsPSJ1cmwoI2MpIi8+PHBhdGggZmlsbD0idXJsKCNkKSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNNy42MyAxLjQ4Yy41LS43IDEuNTUtLjcgMi4wNSAwbDYuMjIgOC44MWMuNTguODMtLjAxIDEuOTctMS4wMyAxLjk3SDIuNDRhMS4yNSAxLjI1IDAgMCAxLTEuMDItMS45N2w2LjIxLTguODFaIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiLz48ZGVmcz48bGluZWFyR3JhZGllbnQgaWQ9ImEiIHgxPSIyLjQxIiB4Mj0iMi40MSIgeTE9IjEzLjUiIHkyPSIxNiIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIHN0b3AtY29sb3I9IiNGRDhENDIiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNGOTU0MUYiLz48L2xpbmVhckdyYWRpZW50PjxsaW5lYXJHcmFkaWVudCBpZD0iYiIgeDE9IjcuNDEiIHgyPSI3LjQxIiB5MT0iMTMuNSIgeTI9IjE2IiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+PHN0b3Agc3RvcC1jb2xvcj0iI0ZEOEQ0MiIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iI0Y5NTQxRiIvPjwvbGluZWFyR3JhZGllbnQ+PGxpbmVhckdyYWRpZW50IGlkPSJjIiB4MT0iMTIuNCIgeDI9IjEyLjQiIHkxPSIxMy41IiB5Mj0iMTYiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj48c3RvcCBzdG9wLWNvbG9yPSIjRkQ4RDQyIi8+PHN0b3Agb2Zmc2V0PSIxIiBzdG9wLWNvbG9yPSIjRjk1NDFGIi8+PC9saW5lYXJHcmFkaWVudD48bGluZWFyR3JhZGllbnQgaWQ9ImQiIHgxPSIuMDMiIHgyPSIuMDMiIHkxPSIuMDMiIHkyPSIxMi4yNiIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIHN0b3AtY29sb3I9IiNGRkU2NUUiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNGRkM4MzAiLz48L2xpbmVhckdyYWRpZW50PjwvZGVmcz48L3N2Zz4=)](https://astronachos.com/)\n[![Mastodon](https://img.shields.io/badge/mastodon-gray?\u0026logo=mastodon)](https://mastodon.gamedev.place/@astronachos)\n[![Twitter](https://img.shields.io/badge/twitter-gray?\u0026logo=twitter)](https://twitter.com/astronachos)\n[![Telegram](https://img.shields.io/badge/telegram-gray?\u0026logo=telegram)](https://t.me/astronachos)\n[![Buy me a coffee](https://img.shields.io/badge/buy_me_a_coffee-gray?\u0026logo=buy%20me%20a%20coffee)](https://buymeacoffee.com/astrochili)\n\n📼 Also in this series:\n- 👖 [Kinematic Walker](https://github.com/astrochili/defold-kinematic-walker)\n- 🎥 [Operator](https://github.com/astrochili/defold-operator)\n- 🎄 [Illumination](https://github.com/astrochili/defold-illumination)\n- 🚧 [Blockout Textures](https://github.com/astrochili/blockout-textures)\n\n## Overview\n\nThis is a kit of game configuration files and importing scripts to design your level with [TrenchBroom](https://trenchbroom.github.io/) and export it to [Defold](https://defold.com/) as the collection.\n\nTrenchBroom 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](https://trenchbroom.github.io/manual/latest/) and usability.\n\n🎮 [Play HTML5 demo](https://astronachos.com/defold/trenchbroom).\n\n💬 [Discuss on the forum](https://forum.defold.com/t/trenchfold-trenchbroom-extension-for-defold/71284).\n\n🧪 Look at [Retro Texture Pack](https://little-martian.itch.io/retro-texture-pack) by [Little Martian](https://little-martian.dev/) used in the demo.\n\n## Features\n\n- [x] Convert level geometry to meshes and collision objects.\n- [x] Use flag textures and checkboxes to define faces behavior.\n- [x] Place triggers, kinematic or dynamic bodies.\n- [x] Convert entities to game objects.\n- [x] Attach file components to your entities.\n- [x] Set custom entity properties and read them from the game logic.\n- [x] Define areas and handle their coordinates in scripts.\n- [x] Run importing with the editor script or the standalone lua module.\n- [x] Expand the game configuration file with your own classes.\n- [ ] Request by [adding an issue or contribute](https://github.com/astrochili/defold-trenchfold/issues).\n\n## Running the Example\n\nTo run the example project, you first need to import the example map.\n\nWith the project open in Defold, right click on the [level.map](https://github.com/astrochili/defold-trenchfold/blob/master/example/maps/level/level.map) file then click on `Convert Map to Collection`. This will create a variety of folders and files next to the `.map` file. You can now build and run the example.\n\n## Install\n\n1. Add link to the zip-archive of the latest version of [defold-trenchfold](https://github.com/astrochili/defold-trenchfold/releases) to your Defold project as [dependency](http://www.defold.com/manuals/libraries/).\n2. Copy the `trenchfold/assets/trenchbroom/games/Defold` folder according [this instruction](https://trenchbroom.github.io/manual/latest/#game_configuration_files) to TrenchBroom user data folder.\n3. Set your game project path as the game path in TrenchBroom preferences when creating the first map.\n4. Setup `textel_size` and `material` in the [worldspawn](#worldspawn) entity.\n\n## Import\n\n### Editor Script\n\nFind your `.map` file in the resources pane of the editor and right click on it and select the `Convert Map to Collection` action. It does the magic and creates the collection file and all the components files: buffers, meshes, convexshapes, collisionobjects and some scripts.\n\n### Lua Module\n\nThere is also the `trenchfold/cli.lua` module to run the import script outside the editor. Just pass it two arguments - `relative/map_folder` and `map_name`.\n\n### VS Code\n\nThere is a working example of launch configuration in [`.vscode/launch.json`](.vscode/launch.json). It launches `trenchfold/cli.lua` with the `/example/maps/level` map by using [local-lua-debugger](https://marketplace.visualstudio.com/items?itemName=tomblind.local-lua-debugger-vscode). Requires Lua or LuaJIT to be installed on your computer.\n\n### TrenchBroom\n\nYou can create a [compilation profile](https://iroom.github.io/manual/latest/#compiling_maps) inside TrenchBroom with the `Run Tool` step to run [cli.lua](#lua-module). Requires Lua or LuaJIT to be installed on your computer.\n\n## Textures\n\n![](https://user-images.githubusercontent.com/4752473/179556704-78346b90-569b-419d-a5b1-e3ed35555ab4.png)\n\nThe game configuration includes marking textures at `flags/textures`. They are handled by the exporting script to provide specific behaviour to the faces without normal textures.\n\n### unused\n\nThis face will be skipped when exporting.\n\nUse it to remove useless faces from the geometry.\n\n### clip\n\nCreates a collision object without texture.\n\nUse it to create invisible walls and useful collision geometry.\n\n### trigger\n\nCreates a trigger collision object.\n\n### area\n\nDoesn't create collision objects but its vertices positions will be sent to the object with the `init_area` message.\n\nUse it to process the area programmaticaly.\n\n## Flags\n\nThere are few content flags in the face properties.\n\n### ghost\n\nThe face isn't solid and doesn't generate a collision object vertices.\n\nUse it on objects that can be passed through or that the player will never reach.\n\n### separated\n\nThe face generates a separate plane collision object.\n\nA rare use case is when you have a wall corner with two solid faces and you don't want to create a triangular prism collision shape on its vertices.\n\n## Entities\n\n![](https://user-images.githubusercontent.com/4752473/179557292-05914789-7700-4f4b-931c-51fd5961bf98.png)\n\nThere are brush entities and point entities. The difference is that a brush entity contains geometry brushes, while the point entity has only an origin position and rotation.\n\n### worldspawn\n\nThe default entity for all the geometry outside of the other entities. Also has some general settings of exporting.\n\n- `textel_size` — how much Trenchbroom grid units are equal to one unit in Defold metrics.\n- `material` — the relative path to the material that will be used for generated meshes by default.\n- `textureN` — path to the texture where `N` is number from `1` to `7`. See [texture path patterns](#texture-path-patterns).\n- `physics_*` — collision object properties used by default.\n\n### static*\n\nA brush entity with the static collision type. The only reason to use it is to attach components and set properties because the `worldspawn` is static by default. To use [areas](#area) or destroy parts of the level, e.g.\n\n- `id` — the identifier of the game object.\n- `#component_id` — the relative path to the file component that will be attached to this game object as `component_id`.\n- `#component_id.property` — the script component property override.\n- `material` — the relative path to the material that will be set in generated meshes.\n- `textureN` — path to the texture where `N` is number from `1` to `7`. See [texture path patterns](#texture-path-patterns).\n- `physics_*` — collision object properties related to static collision type.\n\n### trigger*\n\nTo be fair, triggers are created by the [trigger](#trigger) texture, not the entity. But you also need to put scripts and parameters on this trigger, so which is what this entity is for.\n\nIf you place brushes with normal textures to this entity they also become triggers.\n\n- `id` — the identifier of the game object.\n- `#component_id` — the relative path to the file component that will be attached to this game object as `component_id`.\n- `#component_id.property` — the script component property override.\n- `physics_*` — collision object properties related to trigger collision type.\n\n### kinematic*\n\nA brush entity with the kinematic collision type. Use it for moving platforms or sliding doors, for example.\n\n- `id` — the identifier of the game object.\n- `#component_id` — the relative path to the file component that will be attached to this game object as `component_id`.\n- `#component_id.property` — the script component property override.\n- `material` — the relative path to the material that will be set in generated meshes.\n- `textureN` — path to the texture where `N` is number from `1` to `7`. See [texture path patterns](#texture-path-patterns).\n- `physics_*` — collision object properties related to kinematic collision type.\n\n### dynamic*\n\nA brush entity with dthe ynamic collision type. This could be, for example, a crate that the player can move.\n\n- `id` — the identifier of the game object.\n- `#component_id` — the relative path to the file component that will be attached to this game object as `component_id`.\n- `#component_id.property` — the script component property override.\n- `material` — the relative path to the material that will be set in generated meshes.\n- `textureN` — path to the texture where `N` is number from `1` to `7`. See [texture path patterns](#texture-path-patterns).\n- `physics_*` — collision object properties related to dynamic collision type.\n\n### go\n\nThis is a point entity to add a game object without meshes and collision objects. You can attach any file components to it or replace it with you `.go` file.\n\n- `origin` — the position of the game object that defined automatically when you place it.\n- `angle` — the Y-axis rotation of the game object that defined automatically when you rotate it.\n- `rotation` — X, Y and Z-axis rotation of the game object. Y-axis will be ignored if the `angle` property exists.\n- `id` — the identifier of the game object.\n- `go` — the relative path to the `.go` file that should replace the entity.\n- `#component_id` — the relative path to the file component that will be attached to this game object as `component_id`. Ignored if the `go` property exists.\n- `#component_id.property` — the script component property override.\n\n### illumination, light_point, light_spot\n\nThese are helpers for placing 💡 [Illumination](https://github.com/astrochili/defold-illumination) objects on the map. Don't forget to fill the `go` property with default value.\n\n## Texture Path Patterns\n\nThe `textureN` property allows to set additional material textures 1-7. The next patterns are available:\n\n- `/path/to/texture.png` — a specific texture.\n- `/path/to/prefix_*_suffix.png` — a specific path where * is texture0 original name.\n- `/path/to/alternative/*` — a specific folder with the same texture file name.\n- `prefix_*_suffix.png` — the same folder.\n- `prefix_*_suffix` — the same folder and extension.\n\n## Custom Properties\n\nAll the custom properties will be a part of the script component with the `properties` identifier that attached to the game object. These properties can be accessed in runtime by calling `go.get()`.\n\n```lua\ngo.get('#properties', 'property')\n```\n\n### bool\n\nThe values `true` and `false` are converted to boolean.\n\n### number\n\nThe value which can be handled with `tonumber()` is converted to number.\n\nIf the number is flags value then you can parse it with `utils.flags_from_integer(value)` from the `trenchfold/utils/utils.lua` module.\n\n### vectors\n\n- Value `x y` is converted to `math.vector3(x, y, 0)`.\n- Value `x y z` is converted to `math.vector3(x, y, w)`.\n- Value `x y z w` is converted to `math.vector4(x, y, z, w)`.\n\n### *url\n\nProperty ending with `url` is converted to `msg.url('value')`.\n\n### hash\n\nAny other string property is converted to `hash 'value'`.\n\n# Credits\n\n- [TrenchBroom](https://trenchbroom.github.io/) by [Kristian Duske](https://twitter.com/kristianduske).\n- [Retro Texture Pack](https://little-martian.itch.io/retro-texture-pack) by [Little Martian](https://little-martian.dev/).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastrochili%2Fdefold-trenchfold","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fastrochili%2Fdefold-trenchfold","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastrochili%2Fdefold-trenchfold/lists"}