{"id":18048301,"url":"https://github.com/relintai/terraman","last_synced_at":"2025-04-10T09:50:44.122Z","repository":{"id":64560633,"uuid":"358203259","full_name":"Relintai/terraman","owner":"Relintai","description":"A terrain engine module for godot. It's a c++ engine module, based on voxelman.","archived":false,"fork":false,"pushed_at":"2023-01-09T20:12:09.000Z","size":391,"stargazers_count":15,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-24T08:46:57.129Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","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/Relintai.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}},"created_at":"2021-04-15T09:33:27.000Z","updated_at":"2023-08-08T11:06:12.000Z","dependencies_parsed_at":"2023-02-08T14:01:00.345Z","dependency_job_id":null,"html_url":"https://github.com/Relintai/terraman","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Relintai%2Fterraman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Relintai%2Fterraman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Relintai%2Fterraman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Relintai%2Fterraman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Relintai","download_url":"https://codeload.github.com/Relintai/terraman/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248197662,"owners_count":21063620,"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":[],"created_at":"2024-10-30T20:12:21.638Z","updated_at":"2025-04-10T09:50:44.100Z","avatar_url":"https://github.com/Relintai.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Terraman\n\nA terrain engine for godot, focusing more on editor integration, gameplay-related features, and extendability (even from gdscript), without sacrificing too much speed.\n\nIt is a spinoff of [Voxelman](https://github.com/Relintai/voxelman). I started working on it when I realized that not only a full 3d voxel engine is too hard for me to use properly for an rpg (just think about how hard it is to do smooth zone - zone and dungeon transitions with the proper fidelity for an rpg), it's also unnecessary.\n\nI could have technically implemented all of this into voxelman, as having only have one row of chunks, and then setting chunk height to 1, and creating a mesher that reads isolevel values as a normal height map will achieve the same effect. However as voxelman has lots of features with noises, lights and vertices, adding this on top of that module would have ended up being messy just for this reason alone (and also let's not forget the 3d apis).\n\nSo I ended up creating this. Everything works the same as in voxelman, but the apis have been simplified to make UX a bit better.\n\nThis is an engine module! Which means that you will need to compile it into Godot! [See the compiling section here.](#compiling)\n\nYou can grab pre-built binaries (even editor + export templates) from the [Broken Seals](https://github.com/Relintai/broken_seals/releases) repo.\n\n## Godot Version Support\n\nThis branch tries to follow godot's master branch (as much as I have time).\n\nFor different godot versions look at the other branches.\n\nStatus for this branch: Update for 4.0 is work in progress.\n\n## Optional Dependencies\n\n`https://github.com/Relintai/thread_pool`: Threaded chunk generation. Without this terraman is single threaded! \\\n`https://github.com/Relintai/texture_packer`: You get access to [TerraLibraryMerger](#voxellibrarymerger) and [TerraLibraryMergerPCM](#voxellibrarymergerpcm). \\\n`https://github.com/Relintai/mesh_data_resource`: You get access to a bunch of properties, and methods that can manipulate meshes.\\\n`https://github.com/Relintai/props`: You get access to a bunch of properties, and methods that can manipulate, and use props.\\\n`https://github.com/Relintai/mesh_utils`: Lets you use lod levels higher than 4 by default.\n\n## Usage\n\nFirst create a scene, and add a TerraWorldBlocky node into it. Create a TerraLibrary, and assign it to the Library property.\nAlso, add a TerraSurface into your library.\n\nTick the editable property, deselect, then select the world again, and click the insert button at the top toolbar, or press B to insert a\nvoxel at the inspector's camera's location.\n\nSelect the add button, and now you can just add voxels with the mouse, by clicking on the newly added voxel.\n\n## TerraLibrary\n\nThis class stores the materials, and the TerraSurfaces.\n\nLod levels will automatically try to use materials of their own index.\\\nFor example lod level 1 will try to use material index 1, lod level 2 will try to use material index 2, etc.\\\nIf a material index is not available, they'll use the highest that is.\\\nFor example lod level 5 will try to get material index 5, but if you only have 3 materials it will use the 3rd.\n\n### TerraLibrarySimple\n\nThe simplest library, just assign a material with a texture, and using the atlas_rows and atlas_culomns properties to tell the system\nhow the UVs should be divided.\n\nThis is the basic Minecraft-style lib rary. Use this if you just have one texture atlas. \n\n### TerraLibraryMerger\n\nYou will only have this if your godot also contains https://github.com/Relintai/texture_packer\n\nYou can assign any texture to your surfaces with this, and it will merge them together.\n\n### TerraLibraryMergerPCM\n\n(PCM = Per Chunk Material)\n\nYou will only have this if your godot also contains https://github.com/Relintai/texture_packer\n\nYou can assign any texture to your surfaces with this, and it will merge them together, but it will do it for every required chunk/voxel combination.\n\nFor example if you have a chunk with voxel Grass, and voxel Stone used in it, this library will create a material with a merged texture for Stone and Grass.\nIf you have an anouther chunk which only has Grass and Stone in it, this material will be reused.\nAnd if you have a third chunk which only has a Grass voxel used in it, it will get a new merged material and texture only containing Grass voxel.\n\n## Worlds\n\nThe 2 base classes. These won't do meshing on their own:\n\nTerraWorld: Basic world, does not do anything until you implemnent the required virtual methods!\\\nTerraWorldDefault: This adds threading, and LoD storage support to TerraWorld. Will not create meshes for you!\n\n### TerraWorldBlocky\n\nIt generated UV mapped standard simple terrain meshes.\nThe default algorithm can also generate normal lods.\n\n### Level generation\n\nAssign a TerraManLevelGenerator to the `World`'s `Level Generator` property.\n\nYou can write your own algorithm by implementing the ``` void _generate_chunk(chunk: TerraChunk) virtual ``` method.\n\n`TerraManLevelGeneratorFlat` is also available, it will generate a floor for you, if you use it.\n\n## TerraJobs\n\nProducing just a terrain mesh for a chunk is not that hard by itself. However when you start adding layers/features\nlike lod generation, collision meshes (especially since manipulating the physics server is not threadsafe), \nvertex lights, props, snapping props, props with vertex lights, etc\nchunk mesh generation can quicly become a serious mess.\n\nTerraJobs are meant to solve the issue with less complexity.\n\nThey also provide a way to easily modularize mesh and lod generation.\n\n### TerraJob\n\nBase class for jobs.\n\nIf the [thread pool](https://github.com/Relintai/thread_pool) module is present, this is inherited from `ThreadPoolJob`,\nelse it implements the same api as `ThreadPoolJob`, but it's not going to use threading.\n\nA job has a reference to it's owner chunk.\n\nIf you implement your own jobs, when your job finishes call `next_job()`.\n\n### TerraLightJob\n\nThis is the job that will generate vertex light based ao, random ao, and will bake your `TerraLight`s.\n\n### TerraTerrainJob\n\nThis will generate your terrain collider and mesh (with lods) for you, using the meshers that you add into it.\n\nYour lod setup is easily customizable with [TerraMesherJobSteps](https://github.com/Relintai/terraman/blob/master/world/jobs/voxel_mesher_job_step.h). The setup happens in your selected world's `_create_chunk` method.\n\n### TerraPropJob\n\nThis will generate your prop meshes (with lods).\n\nAlso supports [TerraMesherJobSteps](https://github.com/Relintai/terraman/blob/master/world/jobs/voxel_mesher_job_step.h).\n\n### Internal workings\n\n#### TerraWorld\n\nWhenever you want to spawn a chunk your World will create it using the ``` TerraChunk _create_chunk(x: int, y: int, z: int, chunk: TerraChunk) virtual ``` method.\n\nSince properly initializing a chunk usually takes quite a few steps that you probably don't want to repeat everywhere the `chunk`\nparameter was added. This means you can just call the super `_create_chunk` methods, and you won't need to worry about your chunk\ngetting overridden. Like:\n\nNote that `_create_chunk` is also responsible for initializing chunks if you have them stored inside a scene. \nThis is done by `setup_chunk(shunk)` in `TerraWorld`.\n\n``` \n    func _create_chunk(x : int, y : int, z : int, chunk : TerraChunk) -\u003e TerraChunk:\n        if !chunk:\n            chunk = MyChunk.new()\n\n        # We need to check whether or not we need to initialize jobs\n        if chunk.job_get_count() == 0:\n            # Setup a blocky (minecratf like) mesher job\n            var tj : TerraTerrainJob = TerraTerrainJob.new()\n\n            var s : TerraMesherJobStep = TerraMesherJobStep.new()\n            s.job_type = TerraMesherJobStep.TYPE_NORMAL\n            tj.add_jobs_step(s)\n\n            tj.add_mesher(TerraMesherBlocky.new())\n            tj.add_liquid_mesher(TerraMesherLiquidBlocky.new())\n\n            chunk.job_add(tj);\n\n        #setup your chunk here\n\n        return ._create_chunk(x, y, z, chunk)\n```\n\nYou can look at the world implementations for more examples: [TerraWorldBlocky](https://github.com/Relintai/terraman/blob/master/world/blocky/voxel_world_blocky.cpp).\n\n#### TerraChunk\n\nStores terrain data, prop data. And mesh data (TerraChunkDefault), and the mesh generation jobs.\n\nWhen it starts building meshes it will start submitting jobs to thread_pool (if present) one by one.\n\n#### TerraMesher\n\nIf you want to implement your own meshing algorithm you can do so by overriding ``` void _add_chunk(chunk: TerraChunk) virtual ```.\n\nTerraMesher works similarly to SurfaceTool, so first you need to set colors, uvs, etc and then call add_vertex.\nThey won't get reset, so for exaple if you want all your vertices to have a certain color, you can get away with setting it only once.\n\n## Compiling\n\nFirst make sure that you can compile godot. See the official docs: https://docs.godotengine.org/en/3.x/development/compiling/index.html\n\n1. Clone the engine if you haven't already:\n\nIf you want Godot 3.x:\n```git clone -b 3.x https://github.com/godotengine/godot.git godot```\n\nIf you want Godot 4.0:\n```git clone https://github.com/godotengine/godot.git godot```\n\n\n2. go into the modules folder inside the engine's directory:\n\n```cd godot``` \\\n```cd modules```\n\n3. clone this repository\n\n```git clone https://github.com/Relintai/terraman.git terraman```\n\n(the folder needs to be named terraman!)\n\n4. If you want the optional dependencies run these commands aswell:\n\n```git clone https://github.com/Relintai/texture_packer.git texture_packer``` \\\n```git clone https://github.com/Relintai/mesh_data_resource.git mesh_data_resource```\n\n5. Go up one folder\n\n```cd ..```\n\n6. Compile godot.\n\nFor example:\n\n```scons p=x11 t=release_debug tools=yes```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frelintai%2Fterraman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frelintai%2Fterraman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frelintai%2Fterraman/lists"}