{"id":13525896,"url":"https://github.com/Relintai/voxelman","last_synced_at":"2025-04-01T06:30:39.845Z","repository":{"id":62058148,"uuid":"189623566","full_name":"Relintai/voxelman","owner":"Relintai","description":"A voxel engine for godot. I'ts a c++ engine module.","archived":false,"fork":false,"pushed_at":"2023-01-09T20:17:49.000Z","size":1133,"stargazers_count":102,"open_issues_count":1,"forks_count":8,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-24T08:47:13.145Z","etag":null,"topics":["engine-module","game","godot","lights","meshes","procedural-generation","terrarin-generation","voxel-engine"],"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":"2019-05-31T16:12:26.000Z","updated_at":"2025-02-24T06:21:06.000Z","dependencies_parsed_at":"2023-02-08T14:01:35.182Z","dependency_job_id":null,"html_url":"https://github.com/Relintai/voxelman","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%2Fvoxelman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Relintai%2Fvoxelman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Relintai%2Fvoxelman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Relintai%2Fvoxelman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Relintai","download_url":"https://codeload.github.com/Relintai/voxelman/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246596553,"owners_count":20802844,"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":["engine-module","game","godot","lights","meshes","procedural-generation","terrarin-generation","voxel-engine"],"created_at":"2024-08-01T06:01:23.263Z","updated_at":"2025-04-01T06:30:39.293Z","avatar_url":"https://github.com/Relintai.png","language":"C++","funding_links":[],"categories":["Modules"],"sub_categories":["3D"],"readme":"# Voxelman\n\nA voxel engine for godot, focusing more on editor integration, gameplay-related features, and extendability (even from gdscript), without sacrificing too much speed.\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 find a demonstration project (with pre-built binaries) here: https://github.com/Relintai/the_tower\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 Voxelman is single threaded! \\\n`https://github.com/Relintai/texture_packer`: You get access to [VoxelLibraryMerger](#voxellibrarymerger) and [VoxelLibraryMergerPCM](#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 VoxelWorldBlocky / VoxelWorldMarchingCubes node into it. Create a VoxelLibrary, and assign it to the Library property.\nAlso, add a VoxelSurface 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## VoxelLibrary\n\nThis class stores the materials, and the VoxelSurfaces.\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### VoxelLibrarySimple\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### VoxelLibraryMerger\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### VoxelLibraryMergerPCM\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\nVoxelWorld: Basic world, does not do anything until you implemnent the required virtual methods!\\\nVoxelWorldDefault: This adds threading, and LoD storage support to VoxelWorld. Will not create meshes for you!\n\n### VoxelWorldBlocky\n\nThe most basic world. It is the Minecraft-style world.\n\n### VoxelWorldMarchingCubes\n\nA marching cubes based Voxel World. Actually it uses a modified version of the Transvoxel tables, because it is UV mapped.\n\n### VoxelWorldCubic\n\nThis is my own meshing algorithm, it's basicly a Minecraft style mesher that can take isolevel into account.\n\nIt's kind of a pain to use, it might get removed.\n\n### Level generation\n\nAssign a VoxelManLevelGenerator to the `World`'s `Level Generator` property.\n\nYou can write your own algorithm by implementing the ``` void _generate_chunk(chunk: VoxelChunk) virtual ``` method.\n\n`VoxelManLevelGeneratorFlat` is also available, it will generate a floor for you, if you use it.\n\n## VoxelJobs\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\nVoxelJobs are meant to solve the issue with less complexity.\n\nThey also provide a way to easily modularize mesh and lod generation.\n\n### VoxelJob\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### VoxelLightJob\n\nThis is the job that will generate vertex light based ao, random ao, and will bake your `VoxelLight`s.\n\n### VoxelTerrainJob\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 [VoxelMesherJobSteps](https://github.com/Relintai/voxelman/blob/master/world/jobs/voxel_mesher_job_step.h). The setup happens in your selected world's `_create_chunk` method.\n\n### VoxelPropJob\n\nThis will generate your prop meshes (with lods).\n\nAlso supports [VoxelMesherJobSteps](https://github.com/Relintai/voxelman/blob/master/world/jobs/voxel_mesher_job_step.h).\n\n### Internal workings\n\n#### VoxelWorld\n\nWhenever you want to spawn a chunk your World will create it using the ``` VoxelChunk _create_chunk(x: int, y: int, z: int, chunk: VoxelChunk) 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 `VoxelWorld`.\n\n``` \n    func _create_chunk(x : int, y : int, z : int, chunk : VoxelChunk) -\u003e VoxelChunk:\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 : VoxelTerrainJob = VoxelTerrainJob.new()\n\n            var s : VoxelMesherJobStep = VoxelMesherJobStep.new()\n            s.job_type = VoxelMesherJobStep.TYPE_NORMAL\n            tj.add_jobs_step(s)\n\n            tj.add_mesher(VoxelMesherBlocky.new())\n            tj.add_liquid_mesher(VoxelMesherLiquidBlocky.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: [VoxelWorldBlocky](https://github.com/Relintai/voxelman/blob/master/world/blocky/voxel_world_blocky.cpp), [VoxelWorldMarchingCubes](https://github.com/Relintai/voxelman/blob/master/world/marching_cubes/voxel_world_marching_cubes.cpp).\n\n#### VoxelChunk\n\nStores terrain data, prop data. And mesh data (VoxelChunkDefault), 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#### VoxelMesher\n\nIf you want to implement your own meshing algorithm you can do so by overriding ``` void _add_chunk(chunk: VoxelChunk) virtual ```.\n\nVoxelMesher 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/voxelman.git voxelman```\n\n(the folder needs to be named voxelman!)\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%2Fvoxelman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRelintai%2Fvoxelman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRelintai%2Fvoxelman/lists"}