# Table of Contents - [Blocky terrains - Voxel Tools documentation](#blocky-terrains-voxel-tools-documentation) - [ - Voxel Tools documentation](#-voxel-tools-documentation) - [Changelog - Voxel Tools documentation](#changelog-voxel-tools-documentation) - [Development - Voxel Tools documentation](#development-voxel-tools-documentation) - [Editor - Voxel Tools documentation](#editor-voxel-tools-documentation) - [Getting Voxel Tools - Voxel Tools documentation](#getting-voxel-tools-voxel-tools-documentation) - [Generators - Voxel Tools documentation](#generators-voxel-tools-documentation) - [VoxelGeneratorGraph nodes - Voxel Tools documentation](#voxelgeneratorgraph-nodes-voxel-tools-documentation) - [Navigation - Voxel Tools documentation](#navigation-voxel-tools-documentation) - [Multiplayer - Voxel Tools documentation](#multiplayer-voxel-tools-documentation) - [Overview - Voxel Tools documentation](#overview-voxel-tools-documentation) - [Procedural generation - Voxel Tools documentation](#procedural-generation-voxel-tools-documentation) - [Performance - Voxel Tools documentation](#performance-voxel-tools-documentation) - [Instancing - Voxel Tools documentation](#instancing-voxel-tools-documentation) - [Quick start - Voxel Tools documentation](#quick-start-voxel-tools-documentation) - [Scripting - Voxel Tools documentation](#scripting-voxel-tools-documentation) - [Streams - Voxel Tools documentation](#streams-voxel-tools-documentation) - [VoxelAStarGrid3D - Voxel Tools documentation](#voxelastargrid3d-voxel-tools-documentation) - [FastNoise2 - Voxel Tools documentation](#fastnoise2-voxel-tools-documentation) - [Smooth terrains - Voxel Tools documentation](#smooth-terrains-voxel-tools-documentation) - [VoxelBlockyAttribute - Voxel Tools documentation](#voxelblockyattribute-voxel-tools-documentation) - [VoxelBlockyAttributeAxis - Voxel Tools documentation](#voxelblockyattributeaxis-voxel-tools-documentation) - [VoxelBlockSerializer - Voxel Tools documentation](#voxelblockserializer-voxel-tools-documentation) - [VoxelBlockyAttributeCustom - Voxel Tools documentation](#voxelblockyattributecustom-voxel-tools-documentation) - [VoxelBlockyAttributeDirection - Voxel Tools documentation](#voxelblockyattributedirection-voxel-tools-documentation) - [VoxelBlockyAttributeRotation - Voxel Tools documentation](#voxelblockyattributerotation-voxel-tools-documentation) - [VoxelBlockyFluid - Voxel Tools documentation](#voxelblockyfluid-voxel-tools-documentation) - [VoxelBlockyLibraryBase - Voxel Tools documentation](#voxelblockylibrarybase-voxel-tools-documentation) - [VoxelBlockyLibrary - Voxel Tools documentation](#voxelblockylibrary-voxel-tools-documentation) - [VoxelBlockyModelCube - Voxel Tools documentation](#voxelblockymodelcube-voxel-tools-documentation) - [VoxelBlockyModelFluid - Voxel Tools documentation](#voxelblockymodelfluid-voxel-tools-documentation) - [VoxelBlockyModelEmpty - Voxel Tools documentation](#voxelblockymodelempty-voxel-tools-documentation) - [VoxelGenerator - Voxel Tools documentation](#voxelgenerator-voxel-tools-documentation) - [VoxelBlockyType - Voxel Tools documentation](#voxelblockytype-voxel-tools-documentation) - [VoxelGeneratorWaves - Voxel Tools documentation](#voxelgeneratorwaves-voxel-tools-documentation) - [VoxelGeneratorFlat - Voxel Tools documentation](#voxelgeneratorflat-voxel-tools-documentation) - [VoxelInstanceComponent - Voxel Tools documentation](#voxelinstancecomponent-voxel-tools-documentation) - [VoxelInstanceLibrarySceneItem - Voxel Tools documentation](#voxelinstancelibrarysceneitem-voxel-tools-documentation) - [VoxelModifierSphere - Voxel Tools documentation](#voxelmodifiersphere-voxel-tools-documentation) - [VoxelModifierMesh - Voxel Tools documentation](#voxelmodifiermesh-voxel-tools-documentation) - [VoxelSaveCompletionTracker - Voxel Tools documentation](#voxelsavecompletiontracker-voxel-tools-documentation) - [VoxelStreamMemory - Voxel Tools documentation](#voxelstreammemory-voxel-tools-documentation) - [VoxelDataBlockEnterInfo - Voxel Tools documentation](#voxeldatablockenterinfo-voxel-tools-documentation) - [VoxelBlockyModel - Voxel Tools documentation](#voxelblockymodel-voxel-tools-documentation) - [VoxelBoxMover - Voxel Tools documentation](#voxelboxmover-voxel-tools-documentation) - [VoxelEngine - Voxel Tools documentation](#voxelengine-voxel-tools-documentation) - [VoxelGeneratorHeightmap - Voxel Tools documentation](#voxelgeneratorheightmap-voxel-tools-documentation) - [VoxelGeneratorImage - Voxel Tools documentation](#voxelgeneratorimage-voxel-tools-documentation) - [VoxelGeneratorNoise - Voxel Tools documentation](#voxelgeneratornoise-voxel-tools-documentation) - [VoxelGeneratorScript - Voxel Tools documentation](#voxelgeneratorscript-voxel-tools-documentation) - [VoxelInstanceLibrary - Voxel Tools documentation](#voxelinstancelibrary-voxel-tools-documentation) - [VoxelInstanceLibraryItem - Voxel Tools documentation](#voxelinstancelibraryitem-voxel-tools-documentation) - [VoxelMesher - Voxel Tools documentation](#voxelmesher-voxel-tools-documentation) - [VoxelModifier - Voxel Tools documentation](#voxelmodifier-voxel-tools-documentation) - [VoxelMesherCubes - Voxel Tools documentation](#voxelmeshercubes-voxel-tools-documentation) - [VoxelInstancerRigidBody - Voxel Tools documentation](#voxelinstancerrigidbody-voxel-tools-documentation) - [All classes - Voxel Tools documentation](#all-classes-voxel-tools-documentation) - [VoxelBlockyModelMesh - Voxel Tools documentation](#voxelblockymodelmesh-voxel-tools-documentation) - [ZN_ThreadedTask - Voxel Tools documentation](#zn-threadedtask-voxel-tools-documentation) - [Compressed data format - Voxel Tools documentation](#compressed-data-format-voxel-tools-documentation) - [VoxelTerrainMultiplayerSynchronizer - Voxel Tools documentation](#voxelterrainmultiplayersynchronizer-voxel-tools-documentation) - [VoxelStreamScript - Voxel Tools documentation](#voxelstreamscript-voxel-tools-documentation) - [VoxelToolBuffer - Voxel Tools documentation](#voxeltoolbuffer-voxel-tools-documentation) - [VoxelColorPalette - Voxel Tools documentation](#voxelcolorpalette-voxel-tools-documentation) - [VoxelBlockyTypeLibrary - Voxel Tools documentation](#voxelblockytypelibrary-voxel-tools-documentation) - [VoxelMesherBlocky - Voxel Tools documentation](#voxelmesherblocky-voxel-tools-documentation) - [VoxelToolMultipassGenerator - Voxel Tools documentation](#voxeltoolmultipassgenerator-voxel-tools-documentation) - [VoxelMesherTransvoxel - Voxel Tools documentation](#voxelmeshertransvoxel-voxel-tools-documentation) - [VoxelVoxLoader - Voxel Tools documentation](#voxelvoxloader-voxel-tools-documentation) - [Instance block format v1 - Voxel Tools documentation](#instance-block-format-v1-voxel-tools-documentation) - [ZN_FastNoiseLiteGradient - Voxel Tools documentation](#zn-fastnoiselitegradient-voxel-tools-documentation) - [VoxelToolTerrain - Voxel Tools documentation](#voxeltoolterrain-voxel-tools-documentation) - [SQLite format v1 - Voxel Tools documentation](#sqlite-format-v1-voxel-tools-documentation) - [SQLite format v0 - Voxel Tools documentation](#sqlite-format-v0-voxel-tools-documentation) - [VoxelStreamRegionFiles - Voxel Tools documentation](#voxelstreamregionfiles-voxel-tools-documentation) - [VoxelRaycastResult - Voxel Tools documentation](#voxelraycastresult-voxel-tools-documentation) - [VoxelStreamSQLite - Voxel Tools documentation](#voxelstreamsqlite-voxel-tools-documentation) - [ZN_SpotNoise - Voxel Tools documentation](#zn-spotnoise-voxel-tools-documentation) - [VoxelGeneratorNoise2D - Voxel Tools documentation](#voxelgeneratornoise2d-voxel-tools-documentation) - [VoxelGeneratorMultipassCB - Voxel Tools documentation](#voxelgeneratormultipasscb-voxel-tools-documentation) - [VoxelInstancer - Voxel Tools documentation](#voxelinstancer-voxel-tools-documentation) - [VoxelNode - Voxel Tools documentation](#voxelnode-voxel-tools-documentation) - [Voxel block format v2 - Voxel Tools documentation](#voxel-block-format-v2-voxel-tools-documentation) - [Region format v2 - Voxel Tools documentation](#region-format-v2-voxel-tools-documentation) - [Instance block format v0 - Voxel Tools documentation](#instance-block-format-v0-voxel-tools-documentation) - [Voxel block format v3 - Voxel Tools documentation](#voxel-block-format-v3-voxel-tools-documentation) - [VoxelFormat - Voxel Tools documentation](#voxelformat-voxel-tools-documentation) - [VoxelStream - Voxel Tools documentation](#voxelstream-voxel-tools-documentation) - [VoxelGeneratorGraph - Voxel Tools documentation](#voxelgeneratorgraph-voxel-tools-documentation) - [Voxel block format v4 - Voxel Tools documentation](#voxel-block-format-v4-voxel-tools-documentation) - [VoxelInstanceLibraryMultiMeshItem - Voxel Tools documentation](#voxelinstancelibrarymultimeshitem-voxel-tools-documentation) - [Voxel block format v1 - Voxel Tools documentation](#voxel-block-format-v1-voxel-tools-documentation) - [Voxel Tools documentation](#voxel-tools-documentation) - [VoxelInstanceGenerator - Voxel Tools documentation](#voxelinstancegenerator-voxel-tools-documentation) - [VoxelToolLodTerrain - Voxel Tools documentation](#voxeltoollodterrain-voxel-tools-documentation) - [ZN_FastNoiseLite - Voxel Tools documentation](#zn-fastnoiselite-voxel-tools-documentation) - [Region format v3 - Voxel Tools documentation](#region-format-v3-voxel-tools-documentation) - [VoxelTerrain - Voxel Tools documentation](#voxelterrain-voxel-tools-documentation) - [VoxelMeshSDF - Voxel Tools documentation](#voxelmeshsdf-voxel-tools-documentation) - [VoxelViewer - Voxel Tools documentation](#voxelviewer-voxel-tools-documentation) - [VoxelTool - Voxel Tools documentation](#voxeltool-voxel-tools-documentation) - [VoxelGraphFunction - Voxel Tools documentation](#voxelgraphfunction-voxel-tools-documentation) - [VoxelLodTerrain - Voxel Tools documentation](#voxellodterrain-voxel-tools-documentation) - [VoxelBuffer - Voxel Tools documentation](#voxelbuffer-voxel-tools-documentation) --- # Blocky terrains - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Blocky terrains * * * Blocky terrains[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#blocky-terrains "Permanent link") ================================================================================================================== This page focuses more in detail on blocky terrains, Minecraft-like, or made of cubes. `VoxelMesherBlocky` with models[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#voxelmesherblocky-with-models "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------ This mesher combines small meshes corresponding to model IDs into chunks. It culls faces occluding each other, but doesn't do greedy meshing. This is a similar technique used in Minecraft. Voxel data used by this mesher may be stored in the following channel: `VoxelBuffer.CHANNEL_TYPE` ### Creating voxel models[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#creating-voxel-models "Permanent link") The mesher has a `library` property of type `VoxelBlockyLibraryBase`. This is a resource containing a list of all the models you want to use in order to build a voxel mesh: grass, dirt, wood, leaves, water, shrubs, stairs, door parts etc. You can create a new library in place, or make one saved to a file if you want to re-use it in several places. You can also create it from code. There are two kinds of libraries that can be used: * `VoxelBlockyLibrary`: a simple list of models, where the index in the list corresponds to the ID to use in voxel data. * `VoxelBlockyTypeLibrary`: a higher-level library storing a list of `VoxelBlockyType`. This is an experimental workflow similar to how Minecraft works, which will be explained later. It is easier to get started with `VoxelBlockyLibrary`. ![Screenshot of the list of voxels in VoxelBlockyLibrary](https://voxel-tools.readthedocs.io/en/latest/images/voxel_library_voxels_list.webp) Each slot can contain a `VoxelBlockyModel` resource. The index shown on their left will be the ID they use in voxel data. Voxel `0` is a special case: by convention, it may be used as the default "air" voxel. You may assign a new `VoxelBlockyModel` resource to each slot, and fill in their properties. With default 16-bit voxel data, you can create up to 65,536 models. Warning To allow conversion from older versions of the module, `VoxelBlockyModel` can be instanced, which means the inspector and scripts can create it. However, it is not actually expected. You should not create instances of `VoxelBlockyModel`, instead you should use its derived classes. ### Cubes[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#cubes "Permanent link") There are several kinds of models. A simple one is `VoxelBlockyModelCube`, which renders a cube with specific textures on its sides. With `VoxelMesherBlocky`, using texture atlases is recommended to allow re-using materials and reduce the number of draw calls. You can create a texture containing all the tiles your voxels can use. For example, here is one from the [blocky game](https://github.com/Zylann/voxelgame/tree/master/project/blocky_game) demo: ![Atlas used in the blocky game demo](https://voxel-tools.readthedocs.io/en/latest/images/blocky_game_atlas.webp) This atlas is a square texture and can contain up to 16x16 tiles. This number is important and needs to be set on the `VoxelBlockyModelCube` `atlas_size_in_tiles` property, so texture coordinates can be generated properly. Cube models can have different tiles on each of their faces. You can decide which one to use by assigning properties of `Voxel`, under the `Cube tiles` category. Coordinates here are in tiles, not pixels. ![Voxel cube tile properties screenshot](https://voxel-tools.readthedocs.io/en/latest/images/voxel_cube_tiles_properties.webp) For example, if you want to use the "planks" tile, you may use x=3 and y=1: ![Tile coordinates](https://voxel-tools.readthedocs.io/en/latest/images/cube_tile_coordinates.webp) So far we defined a cubic voxel with specific texture coordinates on its faces, but we still have to actually assign the texture and material used to render it. This can be done in the `Material overrides` section, in which you can assign a material with the texture in it. Make sure to assign its `albedo_texture` to your texture. You may also check the `Vertex Color/Use as albedo` property, because this will allow the mesher to bake ambient occlusion on the edge of cubes. ![Material for blocky terrain](https://voxel-tools.readthedocs.io/en/latest/images/material_blocky_game.webp) Each model can use different materials with different textures, but keep in mind the more you re-use materials, the better. It reduces the number of draw calls and makes rendering faster. Note, there are several levels at which materials get applied, each one overriding the other: - Materials present on meshes are the default (if you use meshes explicitely) - Materials specified on `VoxelBlockyModel` will override mesh materials - The material specified on `VoxelTerrain` will override all library materials ### Meshes[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#meshes "Permanent link") Creating voxel types with the `Cube` geometry is a shortcut that can be used for simple voxels, but the most versatile workflow is to use actual meshes. If you use `VoxelBlockyModelMesh`, you are allowed to assign a mesh resource instead. The `Cube tiles` properties are not available, because you will have to assign texture coordinates of the mesh within a 3D modeler like Blender. ![Blender screenshot for UV editing a block](https://voxel-tools.readthedocs.io/en/latest/images/blender_block_uv_mapping.webp) Meshes can have any shape you want, however there are a few constraints to respect: * The origin of the mesh should be its lower corner. * Blender's coordinate system is Z-up, but Godot is Y-up. Make sure the meshes you export don't go into negative coordinates once imported in Godot. * Vertices should preferably be located within the 0..1 range, in all directions * Keep it low-poly. The mesher can deal with large models, but performance can decrease very quickly if a complex model appears a lot of times. * Faces lying on the sides of the 1x1x1 unit cube will be the only faces that can be culled by the mesher. Make sure they are perfectly lining up. If they don't, it can cause dramatic slowdowns due to the amount of generated geometry not getting culled. ![Blender screenshot for face lining up with cube side](https://voxel-tools.readthedocs.io/en/latest/images/blender_face_cube_side.webp) The best format to use to export your meshes is OBJ. Godot imports this format by default as a mesh resource. Other formats are not suitable because Godot imports them as scenes, and `VoxelBlockyModelMesh` resources require meshes, not scenes. You can choose to export materials from here too, but it is recommended to do it in Godot because it allows you to re-use them. Note A second material can be used in each model. This is useful if a given mesh needs both transparent and opaque parts. This works as usual, by having a mesh with two surfaces. However, face culling will still use properties of the model regardless. For example, if a model has opaque sides and is transparent in the middle, it may be defined as a non-transparent block, so when placed next to other opaque blocks, geometry of its sides will be culled. See [Transparency](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#transparency) section for more info. Warning If your voxels use mesh-based physics (GodotPhysics, Jolt...) and you export your game with "Export as dedicated server" in the resources tab of an export preset, make sure meshes you used in `VoxelBlockyModelMesh` are **not** stripped. Mesh data is required at runtime to generate colliders. If you don't do this, models using a mesh will not generate any mesh-based collision. ### Fluids[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#fluids "Permanent link") If you need to make flowing water with different levels and a similar style as Minecraft, [VoxelBlockyModelFluid](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelFluid/) is available. Top corners of fluid voxels will be raised to match the highest neighbor fluid of the same type. This is a procedural model, so less data is precomputed and is instead calculated by the mesher on every block update. This is because when fluids have more than a few levels, precomputed models would require so many variations that it wouldn't be worth it. Note Like the rest of models, fluids won't simulate behavior on their own. That part is for you to implement. #### Library setup[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#library-setup "Permanent link") Fluid models works a bit differently than regular models. First you have to create a [VoxelBlockyFluid](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyFluid/) resource, and save it as a `.tres` file. Then, in your library, create a [VoxelBlockyModelFluid](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelFluid/) for every level your fluid has, setting their `fluid` and `level` properties accordingly. It may be convenient for each level to have consecutive IDs, but it is not required. It is important that you share the same fluid on the `fluid` property (which is easier if the fluid resource is a file). This way, the mesher will recognize each model as part of the same fluid. To avoid issues with side culling, make sure fluid models also have a `transparency_index` higher than solid blocks. #### Material setup[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#material-setup "Permanent link") [VoxelBlockyFluid](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyFluid/) has a `material` property, which will be used for every model part of that fluid. In order to flow in the right direction and animate, you have to use a `ShaderMaterial` with a special shader. Instead of filling `UV` with texture coordinates, the mesher will store flowing information: * `UV.x` = which axis to project textures on. 0=x, 1=y, 2=z (this could also be deduced from the vertex normal). * `UV.y` = flowing state. Tells which direction the flow is going, or if it's not moving. | Flow state | Value | | --- | --- | | Straight +X | 0 | | Diagonal +X -Z | 1 | | Straight -Z | 2 | | Diagonal -X -Z | 3 | | Straight -X | 4 | | Diagonal -X +Z | 5 | | Straight +Z | 6 | | Diagonal +X +Z | 7 | | Idle | 8 | Values are chosen such that they are proportional to an angle. ![Screenshot of 3x3 water voxels flowing outwards from the center, and flowing state numbers laid out on top. OpenGL axes are indicated too, with X going right and Z going down. Flowing states start at 0 on the right, and increment counter-clockwise, where 8 is at the center.](https://voxel-tools.readthedocs.io/en/latest/images/blocky_fluid_flowing_states.webp) Based on this, it is possible to orient and animate a water texture, using local vertex coordinates instead to sample pixels (similar to triplanar mapping). This mostly matters for the top side of fluid voxels. Lateral sides will always flow down, and the bottom side will always be idle. It is up to you to tweak the shader if you want the result to look different, for example if you want flowing textures to be different than the idle texture. TODO Example scene #### Limitations[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#limitations "Permanent link") * The maximum number of levels is limited (see [VoxelBlockyModelFluid](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelFluid/) API) * The maximum number of fluids is limited (see [VoxelBlockyLibraryBase](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/) API) * Normals of the top side of fluid voxels remain the same as if it was flat. Only corner positions are displaced. As a result, shading of the top won't change with slope. This is currently not implemented for performance reasons, until a fast method is found (note: Minecraft seems to have done the same choice). * Currently no backfaces are generated. In Minecraft, water actually has both backfaces and front faces, which are culled differently in certain edge cases. Currently the engine doesn't differenciate the two. A workaround people often try is to disable backface culling entirely in the water material, but that might lead to other issues. For more details, see [issue 621](https://github.com/Zylann/godot_voxel/issues/621) ### Usage of voxel model IDs[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#usage-of-voxel-model-ids "Permanent link") Voxel IDs defined in a `VoxelBlockyLibrary` are like tiles in a tilemap: for simple games, they can directly correspond to a type of block. However, you may want to avoid treating them directly this way over time. Instead, you may define your own list of block types, and each type can correspond to one, or multiple `VoxelBlockyModel` IDs. Examples from Minecraft: * Stairs can be placed at different orientations, and sometimes have different appearance. These are actually multiple voxel IDs. * Crops can have several growth stages. Each stage is a different voxel ID, for the same type of block. * One door is actually made of 2 voxels. Its top, and bottom. There could be even more if we consider opened and closed doors. * One rail can correspond to many different voxels: straight rails, slopes, and turns. They are all rails, but in different sub-configurations. Managing the correspondance between your "game's block" IDs and voxel IDs is up to you. ### Rotating models[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#rotating-models "Permanent link") At the moment, rotating or flipping voxels automatically is not supported, so you have to create each rotated version you may need for a type of voxel. However it is possible to create these model variants in the editor, by using the rotation buttons in the inspector: ![Model preview in inspector with rotation buttons](https://voxel-tools.readthedocs.io/en/latest/images/model_preview_with_rotation_buttons.webp) These buttons are not for previewing, they actually rotate the model and it will appear in that rotation when placed in game. ### Transparency[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#transparency "Permanent link") You may want some of your voxel types to be transparent. There is in fact two main ways to achieve this: * Using alpha clip: transparent pixels are discarded, allowing rendering through the opaque pass, which avoids some typical issues with transparent surfaces. * Alpha blend: actual transparency, which has a few limitations when multiple transparent surfaces are rendered behind each other Both require to use a different material from the default one you may have used. Note if you use a texture atlas, a typical setup only needs 3 materials using the same atlas: opaque, alpha clip and transparent. `VoxelBlockyModel` resources also have a `transparency_index` property. This property allows to tune how two voxels occlude their faces. For example, let's say you have two transparent voxels, glass and leaves. By default, if you put them next to each other, the face they share will be culled, allowing you to see through the leaves from the glass block: ![Screenshot of transparency index not being exploited](https://voxel-tools.readthedocs.io/en/latest/images/transparency_index_example1.webp) If two faces touch each other, if they have the same transparency index, they can get culled. But if their transparency index is different, they may not. This allows to see the leaves directly behind glass, instead of seeing the insides. Here, glass has `transparency_index=2`, and leaves have `transparency_index=1`: ![Screenshot of transparency index being exploited](https://voxel-tools.readthedocs.io/en/latest/images/transparency_index_example2.webp) `VoxelBlockyModel` also has a `culls_neighbors` property. This is enabled by default and prevents unnecessary rendering of neighboring voxel sides. However, for some transparent voxels it may be more desirable to always render neighboring voxel sides. For example, foliage can be made to look denser if all of the inner voxel sides are visible. Here is a group of leaves with `culls_neighbors=true` (the default): ![Screenshot of leaves with culls_neighbors set to true](https://voxel-tools.readthedocs.io/en/latest/images/culls_neighbors_enabled.webp) Here is that same group of leaves with `culls_neighbors=false`. The sides in-between the voxels are rendered, making the group of leaves look less hollow. ![Screenshot of leaves with culls_neighbors set to false](https://voxel-tools.readthedocs.io/en/latest/images/culls_neighbors_disabled.webp) ### Culling limitations[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#culling-limitations "Permanent link") While the blocky mesher will attempt to cull neighbor faces when they cover each other, it won't actually cut them out perfectly like CSG nodes. If you have two slabs touching each other on the side, both sides will be removed. ![Screenshot of several models touching each other sharing a side with the same shape](https://voxel-tools.readthedocs.io/en/latest/images/matching_model_sides.webp) But if you have a cube touching a slab, the slab will be covered and its side will be culled, but the cube's side will still be half-visible. In this case the engine leaves triangles of the whole side visible. In other words, sides are either fully culled, or not culled (this also happens in Minecraft). ![Screenshot of two models touching each other sharing a side with different shapes](https://voxel-tools.readthedocs.io/en/latest/images/mismatching_model_sides.webp) This is mainly because the engine doesn't have time to do full "CSG" on every possible combination of sides there can be when it meshes models into a chunk. Instead, it uses a matrix of precomputed bitmasks, so that telling if a face covers another is very fast. This is also one reason why models rotation or flipping is precomputed per model, because it eliminates a lot of work that boils down to simple lookups. This can be problematic if models need transparency because it exposes the underlying geometry. There is currently no way to avoid it, other than not having this situation in the game. For example, in Minecraft, there are no glass slabs or staircases, and water flows such that model sides always match. Another more minor detail is how matching faces are detected. During baking of the library, the engine uses rasterization to check if two sides have the same shape, so it can gather all shapes of the whole library and compare them all against each other quickly, generating a "culling" matrix that the mesher will be able to use. If you rely on very small triangles or very detailed faces, the result might not work out perfectly in certain cases. ### Random tick[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#random-tick "Permanent link") `VoxelBlockyModel` has a property named `random_tickable`. This is for use with a very specific function of `VoxelToolTerrain`: [run\_blocky\_random\_tick](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/) `VoxelMesherBlocky` with types[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#voxelmesherblocky-with-types "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------- Warning This feature is experimental, may have bugs, missing parts and may change over time. It proposes a way to organize models for a game and automates a few things, but you may still use `VoxelBlockyLibrary` if you want to handle this in your own way. See also the [corresponding issue on Github](https://github.com/Zylann/godot_voxel/issues/506) . An alternative library type exists, `VoxelBlockyTypeLibrary`. Instead of directly containing a list of models, it contains a list of `VoxelBlockyType`. A type is closer to what you would call a "block type" in a game, and this system was designed to be very similar to how blocks are defined in Minecraft (inspiration from https://docs.minecraftforge.net/en/1.19.2/blocks/states/). ### Attributes[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#attributes "Permanent link") A type can have a few `VoxelBlockyAttribute`. Each attribute is like a variable representing a state of the type. They could be the orientation of a log, a button being pressed or not, a block being the top or bottom part of a door, connections with neighbors, or the growth level of crops. Types should usually have very few attributes, and each attribute can take only a few values as well (between 0 and 255). This limitation relates to the lightweight nature of voxels, you can't store too much into a single voxel otherwise it looses its ability to be part of a terrain with millions of them. If you need a block to have much more complex states, such as objects and lists of things, this system may not work for your case and you will have to fallback on using voxel metadata and actual nodes (like entities in Minecraft). ### Variant models[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#variant-models "Permanent link") After you assigned attributes to a type, the inspector will show you a list of models for every combination of states: ![Variant models list](https://voxel-tools.readthedocs.io/en/latest/images/type_variant_models.webp) You can also preview combinations by using the side panel next to the type's 3D preview on top of the inspector. If you have many attributes or many states, it is possible that this list becomes very large. In Minecraft, redstone dust technically has [1,296 model variants](https://minecraftitemids.com/item/redstone-dust) . It is therefore not made using a list of variants, but a conditional combination of models. In the future a similar feature may be implemented. ### Rotations[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#rotations "Permanent link") A very common use for attributes are rotations. It is so common that `VoxelBlockyType` automates the generation of rotated models, if you use a built-in rotation attribute: * `VoxelBlockyAttributeAxis` * `VoxelBlockyAttributeDirection` * `VoxelBlockyAttributeRotation` Each rotation attribute comes with a default rotation, and you may design your models as if they had that rotation, so that every other rotation can be generated properly. Because these variants are generated automatically, they won't be displayed in the inspector, but they are internally stored like other variants. Note It can be tempting to use `VoxelBlockyAttributeRotation` for everything, but it has the highest number of variants. The engine has to generate pre-rotated models for every combinations, so it has a cost in memory. Similarly, if you don't need certain rotations, consider changing properties of these attributes (you can exclude vertical rotations). ### Model names and numerical IDs[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#model-names-and-numerical-ids "Permanent link") The name of types and attributes matter. They are used to uniquely identify models, in the following form: [attribute1=value,attribute2=value,...] For example, a particular voxel could be identified as `button[direction=up,pressed=yes]`. If you rename, remove or add an attribute causing this identifier to change, it will effectively become a different voxel, and may be given a different ID. That means if you have a saved world with the old names, those won't appear after you change the type. A type can correspond to one, or multiple models with different numerical IDs. Contrary to `VoxelBlockyLibrary`, you don't choose those IDs. They are automatically generated based on all the combinations of all attributes you gave to each type. The more attributes and states a type has, the more model IDs will be reserved for it. Once a particular model is baked, its name and attribute states will be associated to a specific numerical ID. One reason numerical IDs are not manually assigned, is first because it's tedious to do without mistakes when you have many types, but also because of modding. In Minecraft, each world may have different numerical IDs for each voxel compared to other worlds, because of resource packs and mods that could be adding different models. Adding or removing mods should not make IDs clash with each other. In the end, it is not the numerical IDs that uniquely identify a model. Instead, types and attribute names are used. Type names may even be namespaced with a syntax like `minecraft:flower` and `mymod:thingy`. Numerical IDs are only unique within a specific world. They are used to store voxel data and send it across network, which is more efficient, but not portable across different worlds. Numerical IDs and names are mapped with what we could call an "ID map". You can see a list of generated IDs by clicking on the `Inspect model IDs` at the very bottom of a `VoxelBlockyTypeLibrary` in the inspector. ### Usage in scripts[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#usage-in-scripts "Permanent link") When dealing with voxel data, you still need to get and set model IDs with `VoxelTool`, because that's what voxels actually store. If a voxel from a given type needs to change state, that means it will change value to another model ID, like you would do in a game based on the classic `VoxelBlockyLibrary`. `VoxelBlockyTypeLibrary` has functions to obtain a model ID from a type name and the value of each of its attributes, and inversely. If you need specific IDs a large number of times, consider caching them in a local variable for performance. Type names and attribute names use `StringName` instead of `String`, which is a little bit more efficient to compare against other names. So you will need to use a specific syntax using `&`: var model_id := library.get_model_index_with_attributes(&"button", # Note that dictionary keys don't use `&`, because Godot converts StringName keys into String. { "direction": VoxelBlockyAttributeDirection.DIR_POSITIVE_X, "active": 1, "powered": 0 }) If the type only has one attribute, you can use a faster shortcut: var model_id := library.get_model_index_single_attribute(&"log", VoxelBlockyAttributeAxis.AXIS_Z) And if the type has no attribute, or you just want its default state: var model_id := library.get_model_index_default(&"leaves") `VoxelMesherCubes`[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#voxelmeshercubes "Permanent link") ---------------------------------------------------------------------------------------------------------------------- This mesher exclusively generates cubes with specific colors. TODO Fast collisions alternative[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#fast-collisions-alternative "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------ ### Move and slide[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#move-and-slide "Permanent link") Mesh-based collisions are quite accurate and feature-rich in Godot, however it has some drawbacks: * Trimesh collision shapes have to be built each time the terrain is modified, which is [very slow](https://github.com/Zylann/godot_voxel/issues/54) . * The physics engine has to process arbitrary triangles near the player, which can't take advantage of particular situations, such as everything being cubes * Sometimes you may also want a simpler, more game-oriented collision system The `VoxelBoxMover` class provides a Minecraft-like collision system, which can be used in a similar way to `move_and_slide()`. It is more limited, but is extremely fast and is not affected by tunnelling. The code below shows how to use it, but see the [blocky demo](https://github.com/Zylann/voxelgame/tree/master/project/blocky_terrain) for the full code. var box_mover = VoxelBoxMover.new() var character_box = AABB(Vector3(-0.4, -0.9, -0.4), Vector3(0.8, 1.8, 0.8)) var terrain = get_node("VoxelTerrain") func _physics_process(delta): # ... Input commands that set velocity go here ... # Apply terrain collision var motion : Vector3 = velocity * delta motion = box_mover.get_motion(get_translation(), motion, character_box, terrain) global_translate(motion) velocity = motion / delta This technique mainly works if you use `VoxelMesherBlocky`, because it gets information about which block is collidable from the `VoxelBlockyLibrary` used with it. It might have some limited support in other meshers though. If you use `VoxelMesherBlocky`, it will use the list of AABBs specified in `VoxelBlockyModel` resources. If the list is empty, the voxel won't have collisions. You can also filter out some collisions by assigning the `collision mask` property of `VoxelBoxMover`. This will be matched against the `collision mask` property found on `VoxelBlockyModel` resources. ### Raycast[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#raycast "Permanent link") An alternative raycast function exists as well, which returns voxel-specific results. It may be useful if you turned off classic collisions as well. This is accessible with the `VoxelTool` class. An instance of it bound to the terrain can be obtained with `get_voxel_tool()`. var terrain : VoxelTerrain = get_node("VoxelTerrain") var vt : VoxelTool = terrain.get_voxel_tool() var hit = vt.raycast(origin, direction, 10) if hit != null: # The returned position is in voxel coordinates, # and can be used to access the value of the voxel with other functions of `VoxelTool` print("Hit voxel ", hit.position) If you use `VoxelMesherBlocky`, it is possible to filter out some voxel types by specifying the `collision mask` argument. This will be matched against the `collision mask` property found on `VoxelBlockyModel` resources. Custom meshing[¶](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#custom-meshing "Permanent link") ---------------------------------------------------------------------------------------------------------------- Games with blocky voxels often have a custom way to interpret voxel data and converting it into geometry, for a variety of reasons: * Using more than just an ID in voxel data to affect results * Handling rotations and transformations at meshing time instead of precomputing them * Separating shape, texture, colors or other properties from voxel data instead of mapping one ID to one model * Procedural shapes half-way between cubic voxels and smooth voxels, depending on special rules with neighbors * Packing vertex data to be used in custom shaders * Etc... There are mainly two ways this can go: * Write your own custom mesher that does exactly what your game needs. This however requires that you implement that logic in C++, because meshing is a resource-intensive process. This would be ideal because it allows to make all assumptions you want with your game's logic and the way you want to interpret voxel data. It is one big reason so many voxel games use their own code instead of a library doing it for them. But it obviously means the engine cannot provide such mesher for you, it would otherwise be a big maintainance burden and having a mesher for every game would bloat the engine. * Write a generic mesher relying on baked assets and settings that work in a mostly unified way. This changes the problem to be an asset management issue, which can be easier to solve than having to code a mesher. One voxel = one model. Models that need to be rotated are just variants. Different states or textures are more variants too. This is the approach used in the engine. The downside is that you have to bend your needs to fit this pipeline. The burden of generating variants is on you, and might not work out in some extreme cases. If you still want to use a custom mesher, the only current ways are: * Create your own [C++ module](https://docs.godotengine.org/en/stable/engine_details/architecture/custom_modules_in_cpp.html) to create your own mesher: no need to modify the voxel module, but you will have to compile Godot, inherit the base class `VoxelMesher` and implement its virtual methods (check how the engine's own meshers are implemented for examples). * Modify an existing mesher in the module itself, or start from a copy of one. While in theory we could expose a way for GDScript to inherit `VoxelMesher`, scripts are too slow to take on the task of individually polygonize each voxel, and it's not yet clear what form the API would take. A development branch [mesher\_script](https://github.com/Zylann/godot_voxel/tree/mesher_script) attempts to implement that, but isn't ready to use. --- # - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * * * Nothing to see here. Have a Capybara. ![Capybara image](https://github.com/Zylann/godot_voxel/assets/1311555/39c3e7b5-fa03-4eb9-b18d-9e69e6fc3300) _Photo by [Wilfredo Rafael Rodriguez Hernandez](https://www.wikidata.org/wiki/Q115464159) - WTF Public License_ --- # Changelog - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Changelog * * * Changelog[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#changelog "Permanent link") ================================================================================================= This is a high-level list of features, changes and fixes that have been made over time. At the moment, this module doesn't have a distinct release schedule, so this changelog follows Godot's version numbers and binary releases. Almost each version mentionned here should have an associated Git branch (for THIS repo, not Godot's) containing features at the time of the version. Backports aren't done so far. I try to minimize breaking changes, but there are usually a few in each release which I list in detail, so watch out for that section. 1.7.1 dev - master branch[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#171-dev-master-branch "Permanent link") ----------------------------------------------------------------------------------------------------------------------------- * Improvements * `VoxelGeneratorGraph`: Editor: added `Select` menu listing all named nodes * Fixes * `VoxelBlockyTypeLibrary`: fixed new types sometimes not getting registered in the ID list, if vacant entries already existed (#891) 1.7 - 20/08/2026 - tag `v1.7`[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#17-20082026-tag-v17 "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- * Improvements * Added compute shader caching (thanks to chalecampb #866) * `VoxelNode`: exposes `get_voxel_tool` instead of it being repeated in its child classes. * `ZN_FastNoiseLite`: Editor: added support for noise analysis window, formerly present only on `FastNoise2` (This is mainly a debug tool for internal development of graph generators). * Editor: range analysis debugging now also shows actual min/max on outputs connected to `SdfPreview` nodes. This is mainly to investigate internal bugs. * Fixes * Extension: fixed crash when expanding plugin resources in the inspector and other similar actions involving previews (see https://github.com/godotengine/godot-cpp/pull/1928) * Extension: fixed .vox importer options (#882) * Noises: editor: allow to set `period` larger than what inspector sliders allow, by typing the value. * `VoxelBlockSerializer`: fixed incorrect serialization when using a compression mode. LZ4 mode was incorrectly writing the LZ4\_BE header, which couldn't be deserialized (and still can't without manually replacing the header with LZ4), and ZSTD mode was producing LZ4 instead. * `VoxelBlockyModelFluid`: fixed fluid voxels below another fluid voxel were producing mesh collisions. They should never do because mesh collisions are for solid stuff. * `VoxelBoxMover`: fixed some cases where step climbing didn't trigger or made player intersect with blocks (thanks to help from NuclearPhoenixx #813) * `VoxelGeneratorGraph`: fixed FastNoiseLite cellular noise range wasn't properly estimated when a fractal was used, leading to disappearing chunks at close range * `VoxelInstanceLibraryMultimeshItem`: fixed mesh LOD distances did not scale properly with `lod_index` when using `VoxelLodTerrain` with the `Octree` streaming system * `VoxelLodTerrain`: added option to set each LOD distances manually (#379) * `VoxelStreamSQLite`: fixed some hangs and failures when using functions of the stream on the main thread while the terrain's threaded tasks are still using it (#881) * `VoxelTool`: fixed `do_path` was sometimes generating `is_valid_block_position` errors * `VoxelToolBuffer`: `paste_masked_writable_list` is now implemented * Breaking changes * `VoxelTerrain` and `VoxelLodTerrain`: removed `run_stream_in_editor`. Streams and generators will always run in editor, unless they use a script that is not in tool mode. 1.6 - 04/02/2026 - tag `v1.6`[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#16-04022026-tag-v16 "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- * Improvements * `VoxelBlockyModel`: added `tags_mask` property. Initially, it can be used to filter selected voxels when using `VoxelToolTerrain.run_blocky_random_tick`. * `VoxelBoxMover`: * Added support for `VoxelLodTerrain`. * Added `intersects` method to check if an AABB overlaps with blocky voxels. * `VoxelGeneratorGraph`: * Editor: added `Add Node` item to the context menu * Added support for domain warp on `FastNoiseLite` and `ZN_FastNoiseLite` resources when using GPU (previously required to prepend `FastNoiseLiteGradient` noise) * Added methods to get the index of node inputs and output by their name * Added `generate_image_from_sdf` * Added `raycast_sdf_approx` to find where surface is from a ray * `VoxelLodTerrain`: added debug flag to draw locations of voxel metadatas * `VoxelNode`: added `convert_to_nodes` method, which creates a snapshot of the terrain using vanilla Godot nodes. * `VoxelStream`: added option to compress saves using ZSTD instead of LZ4 * `VoxelToolLodTerrain`: * implemented `get/set_voxel_metadata` methods. Warning: caching is off by default, so getting metadata in non-edited areas will invoke the generator, like `get_voxel`. * implemented `do_path` * Fixes * `VoxelAStarGrid3D`: fixed crash after calling `set_region` with negative size * `VoxelBlockyModelFluid`: fixed collision boxes were ignored by library baking * `VoxelBuffer`: fixed `get_channel_as_byte_array` was crashing when used on non-uniform buffers * `VoxelGeneratorGraph`: * fixed `FastNoiseGradient` was incorrect when fractal type isn't `None` and using GPU * fixed `auto_connect_default_inputs` was not saved and reverted to its default value * `VoxelGraphFunction`: fixed `set_node_default_input_by_name` would match parameters but it should have been inputs * `VoxelLodTerrain`: * fixed potential mesh fading error when Clipbox is used and a viewer moves away from a block while another non-visual viewer still keeps its physics loaded. * fixed some cases in LOD update and non-cached blocks that would potentially ignore the `VoxelFormat` override * `VoxelTool`: * `run_blocky_random_tick`: fixed uniform blocks were not picked up (PR #794) * `run_blocky_random_tick`: will now run over the remainder if voxel count is not divisible by batch size * Terrains: fixed `set_voxel_f` which wasn't scaling SDF properly * Breaking changes * `VoxelStreamRegionFiles`: removed `lod_count` property. Any LOD can be saved without the need to preconfigure it. 1.5 - 16/09/2025 - tag `v1.5`[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#15-16092025-tag-v15 "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- * Improvements * `VoxelBuffer`: added functions to rotate/mirror contents * `VoxelEngine`: added function to manually change thread count (thanks to wildlachs) * `VoxelGeneratorGraph`: * Editor: selected nodes and connections can be removed using a right-click context menu (may be long-press on Android) * implemented constant reduction, which slightly optimizes graphs running on CPU if they contain constant branches * `VoxelGeneratorHeightmap`: added `offset` property * `VoxelGraphFunction`: Editor: preview nodes should now work * `VoxelInstanceLibraryItem`: Exposed `floating_sdf_*` parameters to tune how floating instances are detected after digging ground around them. * `VoxelInstanceLibraryMultiMeshItem`: * Added `removal_behavior` property to trigger something when instances get removed * Added `collision_distance` to only create colliders when below a certain distance to chunks * `VoxelInstanceGenerator`: * Added an option to snap instances based on the voxel generator SDF (only available with `VoxelGeneratorGraph`). * Exposed threshold for voxel texture filtering * Added falloff settings for height, slope and noise filtering, so density can fade progressively (issue 784). * Added noise threshold to expand or shrink areas filtered by noise. * `VoxelInstancer`: * Added `remove_instances_in_sphere` * Added fading system so a shader can be used to fade instances as they load in and out * Slightly improved random spread of instances over triangles * `VoxelMesherBlocky`: added tint mode to modulate voxel colors using the `COLOR` channel. * `VoxelMesherTransvoxel`: added `Single` texturing mode, which uses only one byte per voxel to store a texture index. `VoxelGeneratorGraph` was also updated to include this mode. * `VoxelTool`: * added `do_mesh` to replace `stamp_sdf`. Supported on terrains only. * The `channels_mask` parameter of `copy` and `paste` functions is now optional, defaulting to all channels * `VoxelTerrain`: added debug flag to draw locations of voxel metadatas * `FastNoise2`: * Exposed `CELLULAR_VALUE` noise type * Exposed properties to choose cell indices used in distance/value calculations * Build system: added options to turn off features when doing custom builds * Introduced `VoxelFormat` to allow overriding default channel depths (was required to use the new `Single` voxel textures mode) * Fixes * `VoxelBlockyType`: fixed models added using `set_variant_model` were not always returned by `_variant_models_data` (however it can still happen for different reasons, check the documentation of `set_variant_model`) * `VoxelBlockyTypeLibrary`: * fixed crash when setting `types` to empty array * fixed incorrect loading of the ID map when a type has more than two attributes * `VoxelBuffer`: fixed `copy_voxel_metadata_in_area` could crash in some cases with the error `Assertion failed: "is_position_valid(dst_pos)" is false.` * `VoxelInstancer`: * Fixed instance removal failing randomly after at least one chunk gets unloaded * Fixed instances getting generated when digging down or building up in _already meshed_ chunks that had no geometry before, when using `VoxelLodTerrain` * Fixed transition meshes should not be used as spawning surfaces, they caused density bias and position bias at chunk borders * Fixed error when loading a scene with an instancer set with `up_mode = SPHERE` (issue 786; `voxel_instancer.cpp:906 - Condition "_parent == nullptr" is true`) * Fixed some potential issues occurring after `mesh_block_size` gets modified while the terrain is already in the scene tree, where the instancer would not use the right block size (leading to `ERROR: Condition "render_to_data_factor <= 0 || render_to_data_factor > 2" is true`) * `VoxelGeneratorGraph`: * Editor: fixed error sometimes printing after closing the graph editor * Editor: fixed error spam `Invalid param name` after editing a graph (in some yet unknown situations) * Editor: fixed node dialog didn't auto-select the first item when searching * Editor: decimal numbers that have no exact float representation are now displayed rounded instead of widening nodes excessively. Instead, the exact value is shown with a tooltip. * Editor: fixed node names were incorrectly translated * Fixed incorrect texture painting leading to black triangles when using Mixel4 with OutputSingleTexture and GPU generation * Fixed crash with specific setups where equivalent nodes are connected multiple times to equivalent ancestors (issue 783; `FATAL: Assertion failed: "p != equivalence" is false`) * Fixed error when creating multiple nodes referring to a common resource (`ERROR: Signal 'changed' is already connected to given callable 'VoxelGraphFunction::_on_subresource_changed'`) * Fixed incorrect "walls" showing up in areas that are assumed uniform by range analysis, when GPU generation is enabled (For example, when using a Select node to output SDF=1.0 in an area; commit: 350d3897dcec7e37016e4fb95851cd389947371b) * `VoxelMesherBlocky`: Fixed crash when invalid model IDs are present at chunk borders with `VoxelLodTerrain` * `VoxelMeshSDF`: Fixed error when baking from a non-indexed mesh (which is exceptionally the case with Godot's CSG nodes) * `VoxelMesherTransvoxel`: Fixed some incorrect geometry changes near positive LOD borders, notably when voxel textures are used. Edge cases remain but can be fixed with a shader hack for now. * `VoxelStreamRegionFiles`: GDExtension: fixed error creating directories * `VoxelStreamSQLite`: * `preferred_coordinate_format` was incorrectly exposed (fixed thanks to @beicause) * Replaced error spam with a single warning when the stream has no path configured, notably when assigning a new stream in the editor * `VoxelTool`: * `is_area_editable` was off by one in size, and was always returning `true` if the size of the AABB had any component smaller than 1 * `paste_masked` didn't check the right coordinates to clear metadata in destinations containing at least one. It also caused a spam of `get_voxel` being at invalid position * `paste_masked_writable_list` caused an index out of bounds error (spotted thanks to @HiperSlug) * `set_voxel_metadata`: terrains: fixed passing `null` wasn't erasing metadata like with `VoxelBuffers`. * `copy`: fixed voxel metadata was not copied when the source is a terrain * `VoxelToolLodTerrain`: fixed `do_graph` tended to produce boxes when the transform was scaled and `sdf_strength` was not 1 * `VoxelViewer`: reparenting (`remove_child` followed by `add_child`) should no longer reload terrain around the viewer * `VoxelAStarGrid3D`: fixed crash if `find_path` is called without setting a terrain first * `ZN_SpotNoise`: fixed `get_spot_positions_in_area` functions were not working outside of the (0,0) cell * Breaking changes * `VoxelGeneratorGraph`: `SdfSphere` node: `radius` is now an input instead of a parameter (compat breakage only occurs if you used a script to set it: replace `set_node_param(id, 0, radius)` with `set_node_default_input(id, 3, radius)`) * `VoxelTool.set_voxel_metadata`: on terrains, passing `null` now erases metadata, instead of creating a metadata with the value `null`, to be consistent with `VoxelBuffer` and fix issue 773. 1.4.1 - 29/03/2025 - tag `v1.4.1`[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#141-29032025-tag-v141 "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------- * `VoxelToolMultipassGenerator`: implemented `get/set_voxel_metadata` * Fixes * Fixed leak when GPU is enabled for voxel generation or detail normalmap rendering, which could lead to a crash after a while * Terrains no longer interpolate unnecessarily when physics interpolation is enabled (terrain is static so it is not supported for now). * `VoxelGeneratorGraph`: * Fixed `Curve` node was incorrect when used on the GPU. * Fixed single-voxel queries not working with blocky voxels (notably fixes raycast in VoxelLodTerrain) * Editor: auto-connects stopped working when copying a node having some (like noise; workaround was to reload the graph) * `VoxelGeneratorMultipassCB`: Fixed voxel metadata wasn't preserved when outputting final blocks 1.4 - 03/03/2025 - tag `v1.4`[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#14-03032025-tag-v14 "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- Primarily developped with Godot 4.4. * `VoxelBlockyModel`: Added option to turn off "LOD skirts" when used with `VoxelLodTerrain`, which may be useful with transparent models * `VoxelBlockyModelCube`: Added support for mesh rotation like `VoxelBlockyMesh` (prior to that, rotation buttons in the editor only swapped tiles around) * `VoxelEngine`: Added the `tasks.gpu` entry to the dictionary returned by `get_stats`, which is useful for loading screens when GPU features are used (notably asynchronous compiling of compute shaders, which can delay generation) * `VoxelBuffer`: * Added functions to create/update a `Texture3D` from the SDF channel * Added functions to get/set a whole channel as a raw `PackedByteArray` * `VoxelInstanceGenerator`: * Added `OnePerTriangle` emission mode * Added ability to filter spawning by voxel texture indices, when using `VoxelMesherTransvoxel` with `texturing_mode` set to `4-blend over 16 textures` * `VoxelTool`: `raycast` also returns a `normal` based on voxel data (it may be different from a physics raycast in some cases) * `VoxelToolLodTerrain`: Implemented raycast when the mesher is `VoxelMesherBlocky` or `VoxelMesherCubes` * `VoxelMesherBlocky`: Added basic support for fluid models * Fixes * Fixed potential deadlock when using detail rendering and various editing features (thanks to lenesxy, issue #693) * `VoxelInstanceLibrary`: Editor: reworked the way items are exposed as a Blender-style list. Now removing an item while the library is open as a sub-inspector is no longer problematic * `VoxelInstancer`: * Fixed persistent instances reloading with wrong positions (in the air, underground...) when mesh block size is set to 32 * Editor: fixed `!is_inside_world()` errors when editing a `VoxelBlockyLibrary` after deleting a `VoxelInstancer` that was using it * `VoxelLodTerrain`: * Fixed potential crash when when using the Clipbox streaming system with threaded update (thanks to lenesxy, issue #692) * Fixed blocks were saved with incorrect LOD index when they get unloaded using Clipbox, leading to holes and mismatched terrain (#691) * Fixed incorrect loading of chunks near terrain borders when viewers are far away from bounds, when using the Clipbox streaming system * `VoxelStreamSQLite`: fixed connection leaks (thanks to lenesxy, issue #713) * `VoxelTerrain`: * Edits and copies across fixed bounds no longer behave as if terrain generates beyond (was causing "walls" to appear). * Viewers with collision-only should no longer cause visual meshes to appear * `VoxelGeneratorGraph`: * Fixed wrong values when using `OutputWeight` with optimized execution map enabled, when weights are determined to be locally constant * Fixed occasional holes in terrain when using `FastNoise3D` nodes with the `OpenSimplex2S` noise type * Fixed shader generation error when using the `Distance3D` node (vec2 instead of vec3, thanks to scwich) * Fixed crash when assigning an empty image to the `Image` node * `VoxelMesherTransvoxel`: revert texturing logic that attempted to prevent air voxels from contributing, but was lowering quality. It is now optional as an experimental property. * `VoxelStreamSQLite`: Fixed "empty size" errors when loading areas with edited `VoxelInstancer` data * `VoxelTool`: `raycast`: when using blocky voxels, the returned `distance_along_ray` now accounts for non-cube voxels * `VoxelVoxLoader`: Fixed loading `.vox` files saved with versions of MagicaVoxel following 0.99.7 * `.vox` scene importer: disabled threaded import to workaround the editor freezing when saving meshes * Breaking changes * `VoxelInstanceLibrary`: Items should no longer be accessed using generated properties (`item1`, `item2` etc). Use `get_item` instead. * `VoxelMesherTransvoxel`: Removed `deep_sampling` experimental option * `VoxelTool`: The `flat_direction` of `do_hemisphere` now points away from the flat side of the hemisphere (like its normal), instead of pointing towards it * `VoxelToolLodTerrain`: `raycast` used to take coordinates in terrain space. It is now in world space, for consistency with `VoxelToolTerrain`. 1.3 - 17/08/2024 - branch `1.3` - tag `v1.3.0`[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#13-17082024-branch-13-tag-v130 "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------- Primarily developped with Godot 4.3. * Added project setting `voxel/ownership_checks` to turn off sanity checks done by certain virtual functions that pass an object (such as `_generate_block`). Relevant for C#, where the garbage collection model prevents such checks from working properly. * `VoxelBuffer`: Added several functions to do arithmetic operations on all voxels * `VoxelInstanceGenerator`: allow to set density beyond 1, up to 10, by typing it in the field * `VoxelMesherBlocky`: * Can be used with `VoxelLodTerrain`. Basic support: meshes scale with LOD and LOD>1 chunks have extra geometry to reduce cracks between LODs * Added experimental "shadow occluders": generates quads on chunk sides if they are covered by opaque voxels, to force shadows to project in caves when there is no surface for DirectionalLight to project from (see #622). * `VoxelMesherTransvoxel`: * added `edge_clamp_margin` property to prevent triangles from becoming too small, at the cost of slightly lower fidelity * reverted removal of degenerate triangles * `VoxelStreamSQLite`: Added option to change the coordinate format, now defaulting to a format allowing larger coordinates. Existing saves keep their original format. * `VoxelToolLodTerrain`: added `run_blocky_random_tick` * `VoxelViewer`: added `view_distance_vertical_ratio` to use different vertical view distance proportionally to the horizontal distance * Fixes * `VoxelBlockyModelMesh`: Fixed materials present directly in the mesh resource were not applied (only overrides in the model or on the terrain were applied) * `VoxelBlockyType`: Fixed configuration warning about missing variants when there is a base model specified * `VoxelGeneratorGraph`: Fixed crash when using the `Image` node with a non-square image * `VoxelStreamSQLite`: * Fixed `set_key_cache_enabled(true)` caused nothing to load * Fixed slow loading when the database path contains `res://` or `user://` * Fixed crash if the database has an invalid path and `flush()` is called after `set_key_cache_enabled(true)` * `VoxelInstancer`: * Fixed instances with LOD > 0 were generated on `VoxelTerrain` even though LOD isn't supported (ending up in weird positions). No instances should generate. * Fixed error spam in the editor when instancing the node without a terrain parent * `VoxelInstanceLibrary`: Fixed `Assertion failed: "p_id < 0 || p_id >= MAX_ID" is false` when removing items from a VoxelInstanceLibrary * `VoxelMeshSDF`: Fixed error in the editor when trying to visualize the last slice (which turns out to be off by 1) * `VoxelModifierMesh`: * Fixed setting `isolevel` had no effect * Fixed missing configuration warning when parenting under `VoxelTerrain` (only `VoxelLodTerrain` is supported) * Breaking changes * `VoxelBlockyLibrary`: removed deprecated method `get_voxel_index_from_name`, use `get_model_index_from_resource_name` instead * `VoxelBlockyModel`: removed `transparent` deprecated property, use `transparency_index` instead * `VoxelBuffer`: removed `optimize` deprecated method, use `compress_uniform_channels` instead * `VoxelRaycastResult`: position properties are now `Vector3i` instead of `Vector3` (they were always integer but forgot to change them when Godot introduced `Vector3i`) * `VoxelStream`: * removed `emerge_block` deprecated method, use `load_voxel_block` instead * removed `immerge_block` deprecated method, use `save_voxel_block` instead * `VoxelVoxLoader`: methods are now static, so no instance of the class need to be created * Removed `VoxelMesherDMC` 1.2 - 20/04/2024 - branch `1.2` - tag `v1.2.0`[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#12-20042024-branch-12-tag-v120 "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------- Primarily developped with Godot 4.2. * Added `ZN_SpotNoise`, exposing the same algorithm as the `SpotNoise2D` and `SpotNoise3D` nodes of graph generators * Saving with `save_all_modified_blocks` now automatically flushes eventual caches implemented by `VoxelStream` upon completion * Added `VoxelStreamMemory`, which stores in memory instead of the filesystem. This is mainly for testing purposes. * More memory allocations are now tracked by Godot (you might notice `OS.get_static_memory_usage()` returns slightly more) * `VoxelBlockyModelMesh`: exposed `side_vertex_tolerance` to tune when geometry is considered on sides of the voxel * `VoxelBuffer`: exposed `fill_area_f` * `VoxelEngine`: added methods to get the version of the voxel engine * `VoxelGeneratorGraph`: Added GPU support for the `Select` node * `VoxelLodTerrain`: * `save_all_modified_blocks` now returns a completion tracker similar to `VoxelTerrain` * Added new optional LOD streaming system `Clipbox` (advanced settings): * Uses concentric boxes instead of octree traversal, although some logic remains similar to what an octree does * Uses less CPU * Supports multiple viewers * Supports collision-only viewers * Adds secondary LOD distance parameter controlling the extents of LOD1 and beyond, separately from LOD0 (unused in the legacy system) * Has its own limitations and pending improvements, may be addressed over time * The original system is now referenced as "Legacy Octree". * Debug drawing is now exposed as properties. Editor checkboxes were removed from the terrain menu * `VoxelMesherTransvoxel`: textures from air voxels (SDF>0) no longer contribute to the mesh * `VoxelStream`: * Added `flush` method to force writing to the filesystem in case the stream's implementation uses caching * `VoxelStreamSQLite`: Added support for `user://` paths (via internal call to `ProjectSettings.globalize_path()`) * `VoxelTool`: * Added `grow_sphere` as alternate way to progressively grow or shrink matter in a spherical region with smooth voxels (thanks to Piratux) * `do_box` with smooth voxels now uses a proper box SDF, to improve quality. Before it was a solid fill, which could cause artifacts * Added `paste_masked_writable_list`, which also determines what is copied based the destination voxels * `VoxelToolBuffer`: edits are now allowed even if the affected area is partially out of bounds of the target buffer. Results will be clipped. * `VoxelToolLodTerrain`: * Improved quality of `separate_floating_chunks` on smooth terrains by expanding cutting-off area to include more gradients * Fixes * Fixed chunk loading was prioritized incorrectly around the player in specific game start conditions * Fixed `"plugins_list.has(p_plugin)" is true` errors in the editor, at the cost of slight behavior changes. This was caused by existing workarounds to prevent UIs from hiding unexpectedly, which were modified to avoid the error, but are still needed unfortunately. * Fixed error `Unimplemented _get_import_order in add-on` when importing `.vox` files * Fixed some corner cases where quickly leaving and coming back to an edited area would revert edits to their previous state, due to chunks reloading before those edits got saved asynchronously * Fixed possible artifacts near terrain borders when using generators that sometimes avoid filling the output buffer, assuming they are initialized to defaults (issue #603) * `VoxelBlockyModel`: Fixed `material_override_*` properties all acting like the same material * `VoxelBlockyTypeLibrary`: Fixed a crash when saving a library with a null type entry (thanks to ArchLinus) * `VoxelBoxMover`: Fixed performance slowdown when `VoxelBlockyLibrary` contains a lot of models. * `VoxelGeneratorGraph`: * Fixed ambiguous voxel texture indices produced by `OutputSingleTexture` caused painting to fail in some situations * Fixed default input values of output nodes were always 0 when using GPU generation * Fixed crash when using 16 weight output nodes (which is the maximum) * Fixed error when using more than 12 weight output nodes * Fixed using a graph as brush wasn't working with some transforms * Fixed wrapping error with the `Image` node in negative coordinates * Fixed wrong behavior and crashes when generating chunks large enough to trigger the "subdivision" feature * `VoxelInstanceLibraryMultimeshItem`: fixed error when using "Update From Scene" and trying to undo/redo it * `VoxelStreamSQLite`: fixed crash when using `set_key_cache_enabled(true)` * `VoxelTool`: fixed `paste` wrongly printing an error despite working fine * `VoxelToolLodTerrain`: * `do_point` and `set_voxel` were not always updating meshes near chunk borders, leaving holes * `get_voxel` would always return 0 in indices and weight channels if the area was never edited, data streaming is on and the generator is a `VoxelGeneratorGraph` producing single-texture information * `copy` would return incorrect buffers when used on non-edited areas when data streaming is on and a generator is assigned * Fixed errors printed when moving away from edited chunks while no stream is assigned * Fixed `separate_floating_chunks` was spawning chunks not exactly at the same place * Fixed `stamp_sdf` was randomly not working correctly * Breaking changes * `VoxelBuffer`: * `get_voxel_f` and `set_voxel_f` now automatically rescale quantized values. They are no longer normalized in -1..1 and may represent signed distances, so no need to scale manually (imprecisions caused by fixed-point encoding still applies). * `debug_print_sdf_y_slices` now returns a typed array instead of untyped array * `VoxelGeneratorGraph`: the fix to `Image` coordinate wrapping means results will be different than the previous broken version (the broken version was partially offsetting the image in negative coordinates) * `VoxelGraphFunction`: some members of the `NodeTypeID` enum have changed value. However, this enum's values shouldn't be used raw, and shouldn't be used in saves. * `VoxelStream`: save and load methods for voxels now take a position in blocks instead of a position in voxels * `VoxelTool`: due to the automatic internal SDF rescaling, if you modify `sdf_scale`, you may have to adjust it (or remove it if you set it to 0.002). * `VoxelToolMultipassGenerator`: changed `get_editable_area_max` to return an exclusive position instead of inclusive 1.1 - 29/12/2023 - branch `1.1` - tag `v1.1.0`[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#11-29122023-branch-11-tag-v110 "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------- Primarily developped with Godot 4.1 * General * Added shadow casting setting to both terrain types * Added editor shortcut to re-generate the selected terrain * Added support for block generation on the GPU (only available with generators that support both CPU and GPU, for now `VoxelGeneratorGraph` only). * Updated FastNoise2 to 0.10.0-alpha * Started an experimental type system for the blocky voxels workflow. However it is not fully functional, its API may change in the future or have parts removed. * Added experimental `VoxelAStarGrid3D` for grid-based pathfinding on blocky voxels * Added experimental `VoxelGeneratorMultipassCB` to implement column-based generation in multiple passes that works across chunks * Added `render_layers_mask` property to `VoxelTerrain` and `VoxelLodTerrain` * Voxel engine processing no longer stops when the SceneTree is paused * `VoxelGeneratorGraph`: * Added `Spots2D` and `Spots3D` nodes, optimized for generating "ore patches" * Added shader support for `FastNoiseGradient2D` and `FastNoiseGradient3D` nodes * Added bilinear filter option to the `Image` node * Editor: reworked context menu to add nodes, similar to VisualShader. Now has search bar, tree view and node descriptions. * Editor: added copy/paste with Ctrl+C/Ctrl+V shortcuts * `VoxelGraphFunction`: * Editor: the graph will now get compiled while editing, which provides some checks * Editor: I/Os are setup automatically when the graph is compiled by default. Manual setup might be exposed in the future if necessary. * `VoxelTerrain`: * Added `VoxelTerrainMultiplayerSynchronizer`, which simplifies replication using Godot's high-level multiplayer API * Added `is_area_meshed` as an alternative to `VoxelTool.is_area_editable` for games using mesh colliders * Added `do_path` to build or carve "worms" of varying radius * Editor: added warning when bounds are empty * `VoxelTool`: * Added `smooth_sphere`, which smoothens terrain in a spherical area using box blur. Smooth/SDF terrain only. (Thanks to Piratux for the idea and initial implementation) * Separated `paste` into `paste` and `paste_masked` functions. The latter performs masking using a specific channel and value. * `VoxelToolTerrain`: * Raycasting a terrain using `VoxelMesherBlocky` now takes collision boxes into account (thanks to Lry722) * `VoxelToolLodTerrain`: * Added support for `paste` * `VoxelMesherCubes`: * Added helper function to convert an image into a 1-voxel thick "sprite mesh" * `VoxelInstancer`: * Added `get_library_item_id` on multimesh instances with physics body nodes, so raycasts hitting them can tell which item they are * `VoxelInstanceGenerator`: * Added noise graph property, so instances can also be filtered with a custom VoxelGraphFunction * `VoxelInstanceLibrary`: * Added `get_all_item_ids()` to allow iterating over all items of a library * `VoxelLibraryMultiMeshItem`: * Added `render_layer` property (thanks to m4nu3lf) * Added `gi_mode` property * Exposed custom distance ratios for the secondary distance-based LOD system * Added option to hide instances when beyond their max distance-based LOD (only relevant for terrains with no LOD, or on the last LOD of `VoxelLodTerrain`) * Node groups on the template scene are now added to instance colliders if present * `VoxelLodTerrain`: * Added debug drawing for modifier bounds * Added `is_area_meshed` as an alternative to `VoxelTool.is_area_editable` for games using mesh colliders * Terrain now updates when the `material` property is assigned in the editor * Editor: added warning when bounds are empty * `VoxelVoxLoader`: * Added parameter to allow loading data in a custom channel (instead of the color channel) * `VoxelBlockyModel`: * Added 3D preview in editor * Added ability to rotate the model in editor (not just for preview, actually rotate the baked model) * Changed names to be handled with `Resource.name`, so it also shows them in the list of models in the editor * Added `culls_neighbors` property to control whether the sides of a model can cull sides of other models (thanks to spazzylemons) * Fixes * Fixed editor not shrinking properly on narrow screens with a terrain selected. Stats appearing in bottom panel will use a scrollbar if the area is too small. * `VoxelBoxMover`: Workaround floating point error with stair climbing, which could cause characters to fall through the step (depends on gameplay code inducing errors when converting the returned motion) * `VoxelGeneratorGraph`: * Fixed crash if a graph contains a node with both used and unused outputs, and gets compiled with `debug=false` * Fixed error when adding Constant nodes * Fixed graph not always saving when saving the scene * Fixed shader generator crash when a node has an unconnected input * Fixed cellular noise when used on GPU * Fixed Image node issues when sampling at negative coordinates * `VoxelGraphFunction`: * Fixed default input values were not properly loaded * Fixed unexpected "missing node" error when more than one custom inputs are used * `VoxelInstancer`: * Fixed crash when hiding the node in the editor * Fixed crash when closing the scene while an instancer node is selected * Fixed instances were not cleared when using the "Re-generate" menu in the editor when terrain shape changed * `VoxelInstanceLibrary`: * Fixed `find_item_by_name` was not finding items * Fixed newly added items in the editor rendering badly by default when the terrain doesn't have LOD. For now they always default to LOD 0 instead of LOD 2. * `VoxelTerrain`: Fixed crash when the terrain tries to update while it has no mesher assigned * `VoxelLodTerrain`: Fixed error spam when re-generating or destroying the terrain * `VoxelMesherBlocky`: Fixed materials "wrapping around" when more than 256 are used. Raised limit to 65536. * `VoxelMesherTransvoxel`: Removed rare degenerate/microscopic triangles, which caused errors with Jolt Physics. However, doing those checks makes meshing about 15% slower (untextured). * `VoxelStreamRegionFiles`: Fixed `block_size_po2` wasn't working correctly * `VoxelToolTerrain`: Fixed terrain was not marked as modified when setting voxel metadata * `VoxelToolLodTerrain`: * Fixed `stamp_sdf` wasn't working due to an error when providing a baked mesh * Fixed `set_voxel` was creating artifacts * Fixed `separate_floating_chunks` was creating artifacts * `VoxelMeshSDF`: fixed saved resource was not loading properly * Breaking changes * `VoxelBlockyLibrary`: * Changed the list of models to be handled by a typed array instead of individual properties. When opened in the editor, old resources will get converted. Re-save them to make the conversion persist. * `VoxelBlockyModel`: * The class was split into several subclasses for each type of geometry. When opened in the editor, old resources will get converted, but only if they are part of a `VoxelBlockyLibaray`. They won't work if they are individual resource files. * `VoxelNode`: * Removed `GIMode` enum, replaced with `GeometryInstance3D.GIMode` 1.0 - 12/03/2023 - `godot4.0`[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#10-12032023-godot40 "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- Godot 4 is required from this version. * General * Added `gi_mode` to terrain nodes to choose how they behave with Godot's global illumination * Added `FastNoise2` for faster SIMD noise * Added experimental support functions to help setting up basic multiplayer with `VoxelTerrain` (might change in the future) * Improved support for 64-bit floats * Added `ZN_ThreadedTask` to allow running custom tasks using the thread pool system * Added `VoxelMeshSDF` to bake SDF from meshes, which can be used in voxel sculpting. * Mesh resources are now fully built on threads with the Godot Vulkan renderer * Editor: terrain bounds are now shown in the inspector as min/max instead of position/size * Added `do_hemisphere` to `VoxelToolTerrain` and `VoxelToolLodTerrain`, which can be used as flattening brush * `VoxelGeneratorGraph`: * added support for outputting to the TYPE channel, allowing use with `VoxelMesherBlocky` * editor: unconnected inputs show their default value directly on the node * editor: allow to change the axes on preview nodes 3D slices * editor: replace existing connection if dragging from/to an input port having one already * editor: creating noise and curve nodes now auto-create their resource instead of coming up null * editor: added pin button to keep the graph editor shown even after deselecting the terrain. * editor: added popout button to open the graph editor in a separate window * added comment nodes * added relay nodes * added custom functions with the new `VoxelGraphFunction` resource (initial implementation, has limitations) * added `OutputSingleTexture` node for outputting a single texture index per voxel, as an alternative to weights. This is specific to smooth voxels. * added math expression node * added Pow and Powi nodes * Clamp now accepts min and max as inputs. For the version with constant parameters, use ClampC (might be faster in the current state of things). * Added per-node profiling detail to see which ones take most of the time * Added "live update" option, to automatically re-generate the terrain when the graph is modified * Some nodes have default input connections, so it's no longer required to connect them manually to (X,Y,Z) inputs * Added minor optimization to share branches of nodes doing the same calculations * `VoxelInstancer`: * Added support for `VoxelTerrain`. This means only LOD0 works, but mesh-LODs should work. * Editor: added basic UI to see how many instances exist * Allow to dump VoxelInstancer as scene for debug inspection * Editor: instance chunks are shown when the node is selected * Changing mesh block size should no longer make saved instances invalid if they were saved with a different mesh block size * `VoxelInstanceLibraryMultiMeshItem`: * Support setting up mesh LODs from a scene with name `LODx` suffixes * Support setting a scene directly, which is converted to multimesh at runtime (fixes a few workflow issues: updates automatically when scene changes, doesn't create mesh and texture copies in the `.tres` file when using imported scenes) * `VoxelLodTerrain`: exposed debug drawing options for development versions * Smooth voxels * SDF data is now encoded with `inorm8` and `inorm16`, instead of an arbitrary version of `unorm8` and `unorm16`. Migration code is in place to load old save files, but _do a backup before running your project with the new version_. * `VoxelTool`: Added `set_sdf_strength()` to control brush strength when sculpting smooth voxels (previously acted as if it was 1.0) * `VoxelLodTerrain`: added _experimental_ `full_load_mode`, in which all edited data is loaded at once, allowing any area to be edited anytime. Useful for some fixed-size volumes. * `VoxelLodTerrain`: Added optional calculation of distant normalmaps to improve LOD quality. It can also run on the GPU for faster execution (`VoxelGeneratorGraph` only). * `VoxelLodTerrain`: * Editor: added option to show octree nodes in editor * Editor: added option to show octree grid in editor, now off by default * Added option to run a major part of the process logic into another thread * added debug gizmos to see mesh updates * `VoxelToolLodTerrain`: * added _experimental_ `do_sphere_async`, an alternative version of `do_sphere` which defers the task on threads to reduce stutter if the affected area is big. * added `stamp_sdf` function to place a baked mesh SDF on the terrain * added `do_graph` to run a custom brush based on `VoxelGeneratorGraph` in a specific area. An `InputSDF` node was added in order to support SDF modifications. * `VoxelMesherTransvoxel`: * initial support for deep SDF sampling, to affine vertex positions at low levels of details (slow and limited proof of concept for now). * Variable LOD: regular and transition meshes are now combined in one single mesh per chunk. A shader is required to render it, but creates far less mesh resources and reduces the amount of draw calls. * Blocky voxels * `VoxelMesherBlocky`: * materials are now unlimited and specified in each model, either as overrides or directly from mesh (You still need to consider draw calls when using many materials) * each model can have up to 2 materials (aka surfaces) * mesh collisions: added support for specifying which surfaces have collision * `VoxelBoxMover`: added basic support for stair climbing * Fixes * `VoxelBlockyLibrary`: the editor no longer crashes some time after having null model entries. * `VoxelBlockyModel`: properties of the inspector were not refreshed when changing `geometry_type` * `VoxelBuffer`: frequently creating buffers with always different sizes no longer wastes memory * `VoxelGeneratorGraph`: * editor: fix inspector starting to throw errors after deleting a node, as it is still inspecting it * editor: fixed crash when connecting an SdfPreview node to an input. However this is not supported yet. * editor: fixed wrong position of context menu in some dual monitor configurations * editor: fixed an occasional random crash happening when nodes UI layouts are updated * fixed Image2D node not accepting image formats L8 and LA8 * fixed memory leaks when the graph contains resources * some specific node graphs were not ordered properly * SmoothUnion and SmoothSubtract were causing branches to be incorrectly skipped by runtime optimization, leading to empty blocks * `VoxelGeneratorFlat`: fixed underground SDF values being 0 instead of negative * `VoxelInstancer`: * fix instances not refreshing when an item is modified and the mesh block size is 32 * fix crash when removing an item from the library while an instancer node is using it * fix errors when removing scene instances * fix position issues when scene instances are saved * fix position issues when instances are saved while mesh block size is set to 32 * `VoxelLodTerrain`: * fix `lod_fade_duration` property was not accepting decimal numbers * Cracks no longer appear at seams when LOD fading is enabled * `VoxelMesherCubes`: * editor: color mode is now a proper dropdown * fixed raw color mode not working properly * wrong alpha check between transparent and solid cubes * `VoxelMesherTransvoxel`: * fixed surface not appearing if it lines up exactly at integer coordinates * fixed occasional holes and "spikes" in geometry in some specific configurations * `VoxelStreamScript`: fix voxel data not getting retrieved when `BLOCK_FOUND` is returned * `VoxelTerrain`: * fixed `Condition "mesh_block == nullptr" is true` which could happen in some conditions * changing a material now updates existing meshes instead of only new ones * `VoxelTool`: `raycast` locking up if you send a Vector3 containing NaN * `VoxelToolLodTerrain`: fix inconsistent result with integer `do_sphere` radius * `VoxelToolTerrain`: `run_blocky_random_tick` no longer snaps area borders to chunk borders in unintuitive ways * Breaking changes * Some functions now take `Vector3i` instead of `Vector3`. If you used to send `Vector3` without `floor()` or `round()`, it can have side-effects in negative coordinates. * `VoxelTerrain`: the main way to specify materials is no longer here, but in meshers instead. * `VoxelLodTerrain`: `set_process_mode` and `get_process_mode` were renamed `set_process_callback` and `get_process_callback` (due to a name conflict) * `VoxelLodTerrain`: `has_block` was renamed `has_data_block` * `VoxelMesherTransvoxel`: Shader API: The data in `COLOR` and `UV` was moved respectively to `CUSTOM0` and `CUSTOM1` (old attributes no longer work for this use case) * `VoxelMesherTransvoxel`: Variable LOD: a shader is now required to properly render transitions * `Voxel` was renamed `VoxelBlockyModel` * `VoxelLibrary` was renamed `VoxelBlockyLibrary` * `VoxelVoxImporter` was renamed `VoxelVoxSceneImporter` * `VoxelInstanceLibraryItem` was renamed `VoxelInstanceLibraryMultiMeshItem` * `VoxelInstanceLibraryItemBase` was renamed `VoxelInstanceLibraryItem` * `VoxelServer`: renamed `VoxelEngine` * `VoxelStream`: * renamed `emerge_block` => `load_voxel_block` * renamed `immerge_block` => `save_voxel_block` * `VoxelStreamScript`: * renamed `_emerge_block` => `_load_voxel_block` * renamed `_immerge_block` => `_save_voxel_block` * `VoxelGeneratorGraph`: the `Select` node's `threshold` port is now a parameter instead. * `FastNoiseLite` was renamed `ZN_FastNoiseLite`, as now Godot 4 comes with its own implementation, with a few differences. * Removed `VoxelStreamBlockFiles` * Known issues * Some nodes and resources no longer start with predefined properties due to a warning introduced in Godot4 when properties are resources. * SDFGI does not work all the time and can only be forced to update by moving away and coming back, pre-generating the terrain, or toggling it off and on. This is a limitation of Godot not supporting well meshes created dynamically. 0.5.x - Legacy Godot 3 branch - `godot3.x`[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#05x-legacy-godot-3-branch-godot3x "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------------------- This branch is the last supporting Godot 3 * Smooth voxels * `VoxelLodTerrain`: added _experimental_ `full_load_mode`, in which all edited data is loaded at once, allowing any area to be edited anytime. Useful for some fixed-size volumes. * `VoxelToolLodTerrain`: added _experimental_ `do_sphere_async`, an alternative version of `do_sphere` which defers the task on threads to reduce stutter if the affected area is big. * `VoxelInstanceLibraryItem`: Support setting up mesh LODs from a scene with name `LODx` suffixes * Fixes * `VoxelBuffer`: frequently creating buffers with always different sizes no longer wastes memory * `Voxel`: properties were not refreshed when changing `geometry_type` * `VoxelGeneratorGraph`: * fixed Image2D node not accepting image formats L8 and LA8 * editor: fixed crash when connecting an SdfPreview node to an input. However this is not supported yet. * fixed memory leaks when the graph contains resources * `VoxelTerrain`: fixed `Condition "mesh_block == nullptr" is true` which could happen in some conditions * `VoxelTool`: `raycast` locking up if you send a Vector3 containing NaN * `VoxelToolLodTerrain`: fix inconsistent result with integer `do_sphere` radius * `VoxelInstancer`: * fix instances not refreshing when an item is modified and the mesh block size is 32 * fix crash when removing an item from the library while an instancer node is using it * fix errors when removing scene instances * `VoxelStreamScript`: fix voxel data not getting retrieved when `BLOCK_FOUND` is returned * Terrain was not visible if a room/portals system was used. For now it is not culled by rooms. 0.5 - 06/11/2021 - `godot3.4`[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#05-06112021-godot34 "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- * General * `VoxelTerrain`: added `get_data_block_size()` * `VoxelToolTerrain`: added `for_each_voxel_metadata_in_area()` to quickly find all metadata in a box * `FastNoiseLiteGradient`: exposed missing warp functions * Added property to terrain nodes to configure collision margin * Thread count is automatically determined from the number of concurrent threads the CPU supports * Added project settings to configure thread count * Added third-party licenses to the About Window in the editor * Blocky voxels * Added \*.vox importers to import MagicaVoxel files as scenes or meshes * Smooth voxels * `VoxelMesherTransvoxel`: * Initial support for texturing data in voxels, using 4-bit indices and weights * `VoxelMesherTransvoxel`: * optimized hot path, making it about 20% faster * added option to simplify meshes using MeshOptimizer * `VoxelToolLodTerrain`: * added `copy` function * added `get_voxel_f_interpolated` function, useful to obtain interpolated SDF * added a function to separate floating chunks as rigid-bodies in a specified region * `VoxelInstanceGenerator`: added extra option to emit from faces more precisely, especially when meshes got simplified (slower than the other options) * `VoxelInstancer`: * added menu to setup a multimesh item from a scene (similarly to GridMap), which also allows to set up colliders * added initial support for instancing regular scenes (slower than multimeshes) * added option to turn off random rotation * `VoxelInstanceLibrary`: moved menu to add/remove/update items to the inspector, instead of the 3D editor toolbar * Breaking changes * `VoxelBuffer`: channels `DATA3` and `DATA4` were renamed `INDICES` and `WEIGHTS` * `VoxelInstanceGenerator`: `EMIT_FROM_FACES` got renamed `EMIT_FROM_FACES_FAST`. `EMIT_FROM_FACES` still exists but is a different algorithm. * `VoxelServer`: `get_stats()` format has changed, check documentation * `VoxelLodTerrain`: `get_statistics()` format has changed: `time_process_update_responses` and `remaining_main_thread_blocks` are no longer available * `VoxelLodTerrain`: Maximum LOD count was decreased to 24, which is still largely enough. Higher maximums were likely to cause integer overflows. * `VoxelTerrain`: `get_statistics()` format has changed: `time_process_update_responses` and `remaining_main_thread_blocks` are no longer available * `VoxelViewer`: `requires_collisions` is now `true` by default * Fixes * `VoxelGeneratorGraph`: * changes to node properties are now saved properly * fix some per-thread memory not freed on exit * `debug_analyze_range` was crashing when given a negative-size area * `VoxelBuffer`: * `copy_voxel_metadata_in_area` was checking the source box incorrectly * multiple calls to `create()` with different sizes could lead to heap corruption if a channel was not uniform * `copy_channel_from_area` could lead to heap corruption if the source and destination had the same size and were copied entirely * `VoxelMesherTransvoxel`: no longer crashes when the input buffer is not cubic * `VoxelLodTerrain`: * fixed errors and crashes when editing voxels near loading borders * fixed crash occurring after a few edits when LOD count is set to 1 * fixed crash when `run stream in editor` is turned off while the terrain is loading in editor * `VoxelTool` channel no longer defaults to 7 when using `get_voxel_tool` from a terrain with a stream assigned. Instead it picks first used channel of the mesher (fallback order is mesher, then generator, then stream). * `VoxelInstancer`: * fixed error when node visibility changes * fixed no instances generated when density is 1 in vertex emission mode * `VoxelInstanceLibraryItem`: fixed collision shapes setup in editor not being saved * `VoxelInstanceLibrarySceneItem`: fixed associated scene not being saved * `VoxelTerrain`: fixed materials shown under the wrong inspector category * `VoxelStreamRegionFiles`: fixed errors caused by meta file being sometimes written with wrong depth values * `VoxelStreamBlockFiles`: fixed warning about channels always shown in the scene tree * `VoxelStreamSQLite`: fixed blocks above LOD0 being saved at wrong locations, causing them to be reloaded often floating in the air * Fix some crashes occurring when all PoolVector allocs are in use (Godot 3.x limitation). It will print errors instead, but crashes can still occur inside Godot's code as it's not often checking for this * Fix some crashes occurring when negative sizes are sent to AABB function parameters 0.4 - 09/05/2021 - `godot3.3`[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#04-09052021-godot33 "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- * General * Introduction of `VoxelServer`, which shares threaded tasks among all voxel nodes * Voxel data is no longer copied when sent to processing threads, reducing high memory spikes in some scenarios * Added a utility class to load `.vox` files created with MagicaVoxel (scripts only) * Voxel nodes can be moved, scaled and rotated * Voxel nodes can be limited to specific bounds, rather than being infinitely paging volumes (multiples of block size). * Meshers are now resources so you can choose and configure them per terrain * Added [FastNoiseLite](https://github.com/Auburn/FastNoise) for a wider variety of noises * Generators are no longer limited to a single background thread * Added `VoxelStreamSQLite`, allowing to save volumes as a single SQLite database * Implemented `copy` and `paste` for `VoxelToolTerrain` * Added ability to double block size used for meshes and instancing, improving rendering speed at the cost of slower modification * Added collision layer and mask properties * Editor * Streaming/LOD can be set to follow the editor camera instead of being centered on world origin. Use with caution, fast big movements and zooms can cause lag * The amount of pending background tasks is now indicated when the node is selected * Added About window * Smooth voxels * Shaders now have access to the transform of each block, useful for triplanar mapping on moving volumes * Transvoxel runs faster (almost x2 speedup) * The SDF channel is now 16-bit by default instead of 8-bit, which reduces terracing in big terrains * Optimized `VoxelGeneratorGraph` by making it detect empty blocks more accurately and process by buffers * `VoxelGeneratorGraph` now exposes performance tuning parameters * Added `SdfSphereHeightmap` and `Normalize` nodes to voxel graph, which can help making planets * Added `SdfSmoothUnion` and `SdfSmoothSubtract` nodes to voxel graph * Added `VoxelInstancer` to instantiate items on top of `VoxelLodTerrain`, aimed at spawning natural elements such as rocks and foliage * Implemented `VoxelToolLodterrain.raycast()` * Added experimental API for LOD fading, with some limitations. * Blocky voxels * Introduced a second blocky mesher dedicated to colored cubes, with greedy meshing and palette support * Replaced `transparent` property with `transparency_index` for more control on the culling of transparent faces * The TYPE channel is now 16-bit by default instead of 8-bit, allowing to store up to 65,536 types (part of this channel might actually be used to store rotation in the future) * Added normalmaps support * `VoxelRaycastResult` now also contains hit distance, so it is possible to determine the exact hit position * `VoxelBoxMover` supports scaled/translated terrains and `VoxelMesherCubes` (limited to non-zero color voxels) * `VoxelColorPalette` colors can be edited in the inspector * `VoxelToolTerrain.raycast` accounts for scale and rotation, and supports VoxelMesherCubes (non-zero values) * Breaking changes * `VoxelViewer` now replaces the `viewer_path` property on `VoxelTerrain`, and allows multiple loading points * Defined `COLOR` channel in `VoxelBuffer`, previously known as `DATA2` * `VoxelGenerator` is no longer the base for script-based generators, use `VoxelGeneratorScript` instead * `VoxelGenerator` no longer inherits `VoxelStream` * `VoxelStream` is no longer the base for script-based streams, use `VoxelStreamScript` instead * Generators and streams have been split. Streams are more dedicated to files and use a single background thread. Generators are dedicated to generation and can be used by more than one background thread. Terrains have one property for each. * The meshing system no longer "guesses" how voxels will look like. Instead it uses the mesher assigned to the terrain. * SDF and TYPE channels have different default depth, so if you relied on 8-bit depth, you may have to explicitely set that format in your generator, to avoid mismatch with existing savegames * The block serialization format has changed, and migration is not implemented, so old saves using it cannot be used. See documentation for more information. * Terrains no longer auto-save when they are destroyed while having a `stream` assigned. You have to call `save_modified_blocks()` explicitely before doing that. * `VoxelLodTerrain.lod_split_scale` has been replaced with `lod_distance` for clarity. It is the distance from the viewer where the first LOD level may extend. * Fixes * C# should be able to properly implement generator/stream functions * Known issues * `VoxelLodTerrain` does not entirely support `VoxelViewer`, but a refactoring pass is planned for it. 0.3 - 08/09/2020 - `godot3.2.3`[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#03-08092020-godot323 "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------- * General * Added per-voxel and per-block metadata, which are saved by file streams along with voxel data * `StringName` is now used when possible to call script functions, to reduce overhead * Exposed block serializer to allow encoding voxels for network or files from script * Added terrain methods to trigger saves explicitely * The module only prints debug logs if the engine is in verbose mode * `VoxelTerrain` now emit signals when blocks are loaded and unloaded * Editor * Terrain nodes now render in the editor, unless scripts are involved (can be changed with an option) * Blocky voxels * Added collision masks to blocky voxels, which takes effect with `VoxelBoxMover` and voxel raycasts * Added random tick API for blocky terrains * Blocky mesh collision shapes now take all surfaces into account * Smooth voxels * Added a graph-based generator, dedicated to SDF data for now * Fixes * Fixed crash when `VoxelTerrain` is used without a stream * Fixed `Voxel.duplicate()` not implemented properly * Fixed collision shapes only being generated for the first mesh surface * Fixed `VoxelTool` truncating 64-bit values 0.2 - 27/03/2020 - (no branch) - Tokisan Games binary version[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#02-27032020-no-branch-tokisan-games-binary-version "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * General * Optimized `VoxelBuffer` memory allocation with a pool (best when sizes are often the same) * Optimized block visibility by removing meshes from the world rather than setting the `visible` property * Added customizable bit depth to `VoxelBuffer` (8, 16, 32 and 64 bits) * Added node configuration warnings in case terrain nodes are wrongly setup * Implemented VoxelTool for VoxelBuffers * Added `VoxelStreamNoise2D` * Added blur option in `VoxelGeneratorImage` * Generators now all inherit `VoxelGenerator` * Blocky voxels * Blocky voxels can be defined with a custom mesh, sides get culled automatically even when not a cube * Blocky voxels can have custom collision AABBs for use with `VoxelBoxMover` * The 3D noise generator now works in blocky mode with `VoxelTerrain` * Blocky voxels support 8 bit and 16 bit depths * Smooth voxels * Implemented Transvoxel mesher, supporting transition meshes for seamless LOD. It now replaces DMC by default. * Heightmap generators now have an `iso_scale` tuning property which helps reducing terracing * Fixes * Fixed dark normals occasionally appearing on smooth terrains * Fixed Transvoxel mesher being offset compared to other meshers * Fixed stuttering caused by `ShaderMaterial` creation, now they are pooled * Fixed cases where `VoxelLodTerrain` was getting stuck when teleporting far away * Fixed a few bugs with `VoxelStreamBlockFiles` and `VoxelStreamRegionFiles` * Breaking changes * Removed channel enum from `Voxel`, it was redundant with `VoxelBuffer` * Renamed `VoxelBuffer.CHANNEL_ISOLEVEL` => `CHANNEL_SDF` * Removed `VoxelIsoSurfaceTool`, superseded by `VoxelTool` * Removed `VoxelMesherMC`, superseded by `VoxelMesherTransvoxel` * Replaced `VoxelGeneratorTest` by `VoxelGeneratorWaves` and `VoxelGeneratorFlat` 0.1 - 03/10/2019 - `godot3.1`[¶](https://voxel-tools.readthedocs.io/en/latest/changelog/#01-03102019-godot31 "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- Initial reference version. * Support for blocky, dual marching cubes and simple marching cubes meshers * Terrain with constant LOD paging, or variable LOD (smooth voxels only) * Voxels editable in game (limited to LOD0) * Various simple streams to generate, save and load voxel terrain data * Meshers and storage primitives available to use by scripts ... * 01/05/2016 - Creation of the module, using Godot 3.0 beta --- # Development - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Development * * * Development[¶](https://voxel-tools.readthedocs.io/en/latest/development/#development "Permanent link") ======================================================================================================= This page will give some info about the project's internals and how to compile it. It may be useful if you want to contribute, or write custom C++ code for your game in order to get better performance. The source code can be found on [Github](https://github.com/Zylann/godot_voxel) . Note While this project can compile both as a module or an extension, this documentation mainly refers to module development. The project is primarily worked on as a module, and GDExtension is a more recent addition. It may have some specific differences, but overall most things work the same. Building[¶](https://voxel-tools.readthedocs.io/en/latest/development/#building "Permanent link") ------------------------------------------------------------------------------------------------- ### Build as a module[¶](https://voxel-tools.readthedocs.io/en/latest/development/#build-as-a-module "Permanent link") #### Build Godot[¶](https://voxel-tools.readthedocs.io/en/latest/development/#build-godot "Permanent link") 1. Download and compile the [Godot source](https://github.com/godotengine/godot) by following [the official guide](https://docs.godotengine.org/en/latest/development/compiling/index.html) . If you want to regularly update your build (recommended), clone the repository with Git instead of downloading a zip file. 2. Make sure to select the appropriate branches. If you want the very latest development version, use the `master` branch of Godot. If you want a more stable build following the latest stable release, use the branch of that version (for example `4.0`) or a specific version tag (like `4.0.2-stable`). If you want Godot 3, use Godot's `3.x` branch, and the module's `godot3.x` branch (but is no longer maintained). 3. Build Godot before adding any other modules and make sure it produces an executable. 4. Run the newly built executable found in `godot/bin`. Look under Help/About and confirm that the version string indicates you are running the version you want (e.g. `3.2dev.custom_build.ee5ba3e`). #### Add Voxel Tools[¶](https://voxel-tools.readthedocs.io/en/latest/development/#add-voxel-tools "Permanent link") 1. Download or clone the repository for [Voxel Tools](https://github.com/Zylann/godot_voxel) . Use Git to clone the repository if you want to make it easy to update your builds (recommended). 2. By default, the `master` branch of the module should work with the latest stable branch of Godot. There are "snapshot" branches of the module, which were created at the time specific Godot versions were released (such as `godot4.0`), but they are not updated. 3. Place the Voxel Tools directory inside your Godot source tree, in the `godot/modules` directory. 4. Rename the Voxel Tools folder to `voxel`. When correct, the files (e.g. README.md) will be located in `godot/modules/voxel`. **This is important!** 5. Rebuild Godot and make sure it produces an executable. 6. Test that your build has Voxel support: 1. Run your new Godot build. 2. Create a new project. 3. Create a new 3D scene. 4. Add a new node, search for "Voxel" and see if "VoxelTerrain" appears. If so, you have a successful build. If not, review these instructions and your build logs to see if you missed a step or something failed along the way. #### Updating Your Build[¶](https://voxel-tools.readthedocs.io/en/latest/development/#updating-your-build "Permanent link") If you cloned Godot and Voxel Tools, you can use git to update your local code. 1. Go to your local Godot source directory `godot` and run `git pull`. It will download all updates from the repository and merge them into your local source. 2. Go to `godot/modules/voxel` and run `git pull`. Git will update Voxel Tools. 3. Rebuild Godot. Note Since you are pulling from two projects developped by different people, it's probable that on occasion your build won't compile, your project won't open, or your Voxel Tools won't work properly or even crash Godot. To minimize downtime, save your successful builds. Move them out of the build folder and rename them with the version number (e.g. godot-3.2+ee5ba3e.exe). This way, you can continue to use previously working builds until the Godot or Voxel developers fix whatever is broken. It is generally desired by all that code published to repositories will at least build, but stuff happens. ### Build as a GDExtension[¶](https://voxel-tools.readthedocs.io/en/latest/development/#build-as-a-gdextension "Permanent link") Warning This feature is under development and is not ready for production. It has bugs and can crash the engine. Check the [issue tracker](https://github.com/Zylann/godot_voxel/issues/333) for work in progress. This module can compile as a GDExtension library. This allows to distribute it as a library file (`.dll`, `.so`...) without having to recompile Godot Engine. You should read Godot's documentation about GDExtension: * [On Godot Docs](https://docs.godotengine.org/en/stable/tutorials/scripting/gdextension/index.html) * [GodotCpp Repository](https://github.com/godotengine/godot-cpp) To compile the library: * Download a copy of [GodotCpp](https://github.com/godotengine/godot-cpp) * In the voxel's root directory, write the path to GodotCpp at the beginning of the `SConstruct` script, or set the environment variable `GODOT_CPP_PATH` from command line. * Open the same kind of console you would use to compile Godot, change directory to voxel's root folder, and run `scons` there. It will use the `SConstruct` file instead of `SCsub`. Example of build command on Windows (unoptimized debug build for use in editor): scons platform=windows target=debug -j4 The built library will be placed inside the `project/addons/zylann.voxel/bin/` folder. `project/` contains a Godot 4 project. It is then possible to open it to test the extension. By default, the GDExtension config file of this project is setup for debug builds. You may want to modify `voxel.gdextension` for your needs. When doing release packages, the config file is replaced with `voxel.gdextension-release` instead, which is pre-configured with non-dev version of the library for all platforms. There are known issues with GDExtension, check the [issue tracker](https://github.com/Zylann/godot_voxel/issues/333) . #### Web builds[¶](https://voxel-tools.readthedocs.io/en/latest/development/#web-builds "Permanent link") Building for the web requires a WebAssembly compiler, [Emscripten](https://emscripten.org/) . Then you would use the corresponding platform in the SCons command line: scons platform=web [etc...] Important: you need to use the same Emscripten version that was used by Godot's export template for the web. TODO: where can we get which exact version of Emscripten to use when using official export templates? This doesn't seem to be documented. Current guessses: * 4.0.11 ([according to Github Actions](https://github.com/godotengine/godot/blob/bf95b62586e31b8a3503f5903d7764d7c52bf2ab/.github/workflows/web_builds.yml#L12) ) * 4.0.20 (in Godot 4.6, [according to this post](https://github.com/godotengine/godot-cpp/issues/1907#issuecomment-3790865190) ) * It is printed in Godot's editor console if you debug a web build (i.e you would have to first make a basic game without extensions to try this) * 5.0.0 doesn't work as of 2026/02/14 Alternatively, you could [build your own Godot export template](https://docs.godotengine.org/en/stable/engine_details/development/compiling/compiling_for_web.html#compiling-for-the-web) using the version of Emscripten of your choice. There might be some other caveats: [https://github.com/Zylann/godot\_voxel/issues/745](https://github.com/Zylann/godot_voxel/issues/745) Contributing[¶](https://voxel-tools.readthedocs.io/en/latest/development/#contributing "Permanent link") --------------------------------------------------------------------------------------------------------- To contribute to the project, you need to clone the repo using [Git](https://git-scm.com/) , and create your branch on Github so you'll be able to make Pull Requests. ### C++ code[¶](https://voxel-tools.readthedocs.io/en/latest/development/#c-code "Permanent link") It is recommended to read the **Engine Development** section on the official [Godot Documentation](https://docs.godotengine.org/en/stable/) . It explains how to compile the engine, setup an IDE and how custom modules are made. For code guidelines related to Voxel Tools, see [Code Guidelines](https://voxel-tools.readthedocs.io/en/latest/development/#code-guidelines) ### Main documentation[¶](https://voxel-tools.readthedocs.io/en/latest/development/#main-documentation "Permanent link") The documentation is written using Markdown, formatted using [Mkdocs](https://www.mkdocs.org/) and made available as a website on [ReadTheDocs](https://readthedocs.org/) . To contribute to the main pages, make your change to `.md` files located under the `doc/docs` folder, and post a PR on Github. ### API documentation[¶](https://voxel-tools.readthedocs.io/en/latest/development/#api-documentation "Permanent link") To contribute to the class reference (API), you may edit XML files under `doc/classes` instead, similarly to how it's done for regular Godot modules or core classes. After an XML file has been changed, it can be converted into its Markdown counterpart by using the `build.py` script in `doc/tools`, using this command: python build.py -a `build.py` has other arguments to do other things. If you run it without arguments, help will be printed. ### Graph nodes documentation[¶](https://voxel-tools.readthedocs.io/en/latest/development/#graph-nodes-documentation "Permanent link") Graph nodes of \[VoxelGeneratorGraph\] are currently not represented with Godot classes. Therefore they use their own documentation in an XML file, using a workflow similar to classes. The XML file is the single souce of truth for node descriptions and categories shown in the editor, as well as the online documentation. The XML file can be generated or updated from nodes present in the engine by running Godot with the following argument: `--voxel_doc_tool src dst` Where `src` is a path to the original XML, and `dst` is a path to write the updated XML. Both paths can be the same. This XML file should be already versionned under `doc/graph_nodes.xml`. The XML file can then be used to generate several documentations: * The Markdown documentation, appearing on the website * The C++ documentation, appearing in the editor Both are generated by running the script `graph_nodes_doc.py` from inside `doc/tools/`. Layers[¶](https://voxel-tools.readthedocs.io/en/latest/development/#layers "Permanent link") --------------------------------------------------------------------------------------------- ### Main layers[¶](https://voxel-tools.readthedocs.io/en/latest/development/#main-layers "Permanent link") This module has 3 main layers: * Voxel: the voxel engine. Wrapped into `zylann::voxel::` namespace. * Util: library of functions, helpers and data structures, which does not depend on Voxel. Wrapped into `zylann::` namespace. * Thirdparty: third-party libraries. ### Folders[¶](https://voxel-tools.readthedocs.io/en/latest/development/#folders "Permanent link") The module is divided in several folders, each with different dependencies. Because of this, it is possible to use `VoxelMesher`, `VoxelGenerator` or `VoxelStream` standalone, without needing to use a `VoxelTerrain` node for example. | Directory | Description | | --- | --- | | constants/ | Constants and lookup tables used throughout the engine. | | doc/ | Contains documentation | | edition/ | High-level utilities to access and modify voxels. May depend on voxel nodes. | | editor/ | Editor-specific code. May also depend on voxel nodes. | | engine/ | Contains global stuff with the VoxelEngine singleton. Depends on meshers, streams, storage but not directly on nodes. | | generators/ | Procedural generators. They only depend on voxel storage and math. | | meshers/ | Only depends on voxel storage, math and some Godot graphics APIs. | | misc/ | Various scripts and configuration files, stored here to avoid cluttering the main folder. | | modifiers/ | Files related to the modifiers feature. | | shaders/ | Shaders used internally by the engine, both in text form and formatted C++ form. | | storage/ | Storage and memory data structures. | | streams/ | File storage handling code. Only depends on filesystem and storage. | | terrain/ | Contains all the nodes. Depends on the rest of the module, except editor-only parts. | | tests/ | Contains tests. These run when Godot starts if enabled in the build script and specified by command line. | | thirdparty/ | Third-party libraries, in source code form. They are compiled statically so Godot remains a single executable. | | util/ | Generic utility functions and data structures. They don't depend on voxel stuff. | ### Code[¶](https://voxel-tools.readthedocs.io/en/latest/development/#code "Permanent link") In addition to layers reflected by the folder structure, there is an implicit distinction between Godot and this module: if a piece of code does not need to depend on Godot, then it will tend to not depend on Godot. For example, the _implementation_ of Transvoxel has very little dependencies on Godot. Indeed, it doesn't care what a resource is, doesn't need Variant, doesnt need bindings, doesn't need to use OOP etc. That's why the _mesher resource_ does not contain the _logic_, but instead acts as a "bridge" between the algorithm and its usage within Godot. Same for `VoxelBuffer`: this class is actually not a full-fledged Godot object. It is much lighter than that, because it can have thousands of instances, or even supports being allocated on the stack and moved. It is exposed as a wrapper object instead for the few cases where scripters have to interact with it. ### Namespaces[¶](https://voxel-tools.readthedocs.io/en/latest/development/#namespaces "Permanent link") | Namespace | Description | | --- | --- | | `zylann` | General-purpose, not necessarily related to Godot | | `zylann::math` | Math utilities | | `zylann::godot` | General-purpose Godot utilities | | `zylann::voxel` | Voxel engine | | `zylann::voxel::ops` | Voxel editing utilities | | `zylann::voxel::godot` | Some classes have Godot-specific wrappers in order to be exposed to scripting APIs, which are in this namespace to allow using the same name as in `zylann::voxel` | | `zylann::voxel::magica` | MagicaVoxel functions | | `zylann::voxel::pg` | Graph processing functionality | There might be more smaller namespaces that can be documented in code. Tests[¶](https://voxel-tools.readthedocs.io/en/latest/development/#tests "Permanent link") ------------------------------------------------------------------------------------------- Tests are not mandatory, but if there is time to make new ones, it's good to have. Full coverage isn't really a goal, but it's useful when troubleshooting some bugs and ensuring they don't come back. ### Internal tests[¶](https://voxel-tools.readthedocs.io/en/latest/development/#internal-tests "Permanent link") The module contains internal tests in the `tests/` folder. No test framework is used at the moment, instead they just run by either printing an error when they fail or not. Tests will only be compiled if `voxel_tests=yes` is passed as parameter to the SCons command line. Tests will run on startup if `--run_voxel_tests` is passed as command line parameter when launching Godot. Threads[¶](https://voxel-tools.readthedocs.io/en/latest/development/#threads "Permanent link") ----------------------------------------------------------------------------------------------- The module uses several background threads to process voxels. The number of threads can be adjusted in Project Settings. ![Schema of threads](https://voxel-tools.readthedocs.io/en/latest/images/threads_schema.webp) There is one pool of threads. This pool can be given many tasks and distributes them to all its threads. So the more threads are available, the quicker large amounts of tasks get done. Tasks are also sorted by priority, so for example updating a mesh near a player will run before generating a voxel block 300 meters away. Some tasks are scheduled in a "serial" group, which means only one of them will run at a time (although any thread can run them). This is to avoid clogging up all the threads with waiting tasks if they all lock a shared resource. This is used for I/O such as loading and saving to disk. The thread pool is in [VoxelEngine](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/) . Note: this task system does not account for "frames". Tasks can run at any time for less or more than one frame of the main thread. Code guidelines[¶](https://voxel-tools.readthedocs.io/en/latest/development/#code-guidelines "Permanent link") --------------------------------------------------------------------------------------------------------------- ### Syntax[¶](https://voxel-tools.readthedocs.io/en/latest/development/#syntax "Permanent link") For the most part, use `clang-format` and follow most of Godot conventions. * Class and struct names `PascalCase` * Constants, enums and macros `CAPSLOCK_CASE` * Other names `snake_case` * Globals prefixed with `g_` * Statics prefixed with `s_` * Thread-locals prefixed with `tls_` * Parameters prefixed with `p_` in case of ambiguity, recommended for large functions. * Private and protected fields prefixed with `_` * Generally functions shouldn't start with `_`, except for API reasons or another special rule. * Signal handler functions are prefixed with `on_` and should preferably not be called manually * Enums preferably prefixed by their name. Example: `enum Type { TYPE_ONE, TYPE_TWO }`. Mandatory for enums exposed to Godot. * Open braces at the end of line, close them next line * Never omit braces * Space between binary operators and control flow: `if (a + b == 42)` * Indent with tabs * Private wrapper functions can be used to adapt to the Godot script API and are prefixed with `_b_`. * Use Clang-format to automate most of these rules (there should be a file included at the root of the C++ project) * Prefer comments with `//` only * Some virtual functions from wrapper classes are prefixed with `_zn_` to encapsulate signature differences when compiling as a module or as a GDExtension. ### File structure[¶](https://voxel-tools.readthedocs.io/en/latest/development/#file-structure "Permanent link") * Use `.h` for headers and `.cpp` for implementation files. * File names use `snake_case`. * Constructors and destructors go on top * Public API goes on top, private stuff goes below * Bindings go at the bottom. * Avoid long lines. Preferred maximum line length is 120 characters. Don't fit too many operations on the same line, use locals. * Defining types or functions in `.cpp` may be better for compilation times than in header if they are internal. * When a line is too long to fit a function signature, function call or list, write elements in column. ### C++ features[¶](https://voxel-tools.readthedocs.io/en/latest/development/#c-features "Permanent link") * Don't use `auto` unless the type is impossible to express or a long template (like STL ones). IDEs aren't granted (Github reviews and diffs) * Moderate use of lambdas and functors are fine. Not `std::function`. * Lambda captures should be defined explicitely (try to reduce usage of `[=]` or `[&]`) * STL is ok if it measurably performs better than Godot alternatives. * Initialize variables next to declaration * Avoid using macros to define logic or constants. Prefer `static const`, `constexpr` and `inline` functions. * Prefer adding `const` to variables that won't change after being initialized * Don't exploit booleanization when an explicit alternative exists. Example: use `if (a == nullptr)` instead of `if (!a)` * If possible, avoid plain arrays like `int a[42]`. Debuggers don't catch overruns on them. Prefer using wrappers such as `std::array`, `FixedArray` and `Span`. * Use `uint32_t`, `uint16_t`, `uint8_t` in case integer size matters. * If possible, use forward declarations in headers instead of including files * `#include` what you use, don't assume a header transitively includes things. This has been broadly ignored for a while, but new code should attempt to follow it. `util/godot` micro-headers are an exception. * Don't do `using namespace` in headers (Except with `godot::`, but that's only to help supporting GDExtension using the same codebase, since Godot core does not have this namespace). * `mutable` must ONLY be used for thread synchronization primitives. Do not use it with "cache data" to make getters `const`, as it can be misleading in a multi-threaded context. * Use `ZN_NEW` and `ZN_DELETE` instead of `new` and `delete` on types that don't derive from Godot `Object`. This is intented for code that may be independent from Godot, yet be tracked in Godot's default allocator when used. * Use `ZN_ALLOC` and `ZN_FREE` instead of `malloc` and `free`. This is intented for code that may be independent from Godot, yet be tracked in Godot's default allocator when used. * When using standard library containers, prefer aliases from `util/containers/` such as `StdVector`. These are using Godot's allocation functions so memory will be tracked. ### Error handling[¶](https://voxel-tools.readthedocs.io/en/latest/development/#error-handling "Permanent link") * Exceptions are not used. * Check invariants, fail early. Use `CRASH_COND` or `ZN_ASSERT` in debug mode to make sure states are as expected even if they don't cause immediate harm. * Crashes aren't nice to users, so in user-facing code (scripting) use `ERR_FAIL_COND` or `ZN_ASSERT_RETURN` macros for code that can recover from error, or to prevent hitting internal assertions * Macros prefixed with `ZN_` are Godot-agnostic and may be used for portability in areas that don't depend on Godot too much. ### Performance[¶](https://voxel-tools.readthedocs.io/en/latest/development/#performance "Permanent link") In performance-critical areas which run a lot: * Avoid allocations. Re-use memory with memory pools, `ObjectPool`, fixed-size arrays or use `std::vector` capacity. * Avoid `virtual`, `Ref`, `String` * Don't resize `PoolVectors` or `Vector`, or do it in one go if needed * Careful about what is thread-safe and what isn't. Some major areas of this module work within threads. * Reduce mutex locking to a minimum, and avoid locking for long periods. * Use data structures that are fit to the most frequent use over time (will often be either array, vector or hash map). * Consider tracking debug stats if their impact is negligible. It helps users to monitor how well the module performs even in release builds. * Profile your code, in release mode. This module is Tracy-friendly, see `util/profiling.hpp`. * Care about alignment when making data structures. For exmaple, pack fields smaller than 4 bytes so they use space better ### Godot API[¶](https://voxel-tools.readthedocs.io/en/latest/development/#godot-api "Permanent link") * In areas where performance matters, use the most direct APIs for the job. Especially, don't use nodes. See `RenderingServer` and `PhysicsServer`. * Only expose a function to the script API if it is safe to use and guaranteed to remain present for a while * Use `memnew` and `memdelete` instead of `new` and `delete` on types derived from Godot `Object` * Don't leave random prints. For verbose mode you may also use `ZN_PRINT_VERBOSE()` instead of `print_verbose()`. * Use `int` as argument for functions exposed to scripts if they don't need to exceed 2^31, even if they are never negative, so errors are clearer if the user makes a mistake * If possible, keep Godot usage to a minimum, to make the code more portable, and sometimes faster for GDExtension builds. Some areas use custom equivalents defined in `util/`. Compiling as a module or an extension is both supported, so it involves some restrictions: * Don't include Godot headers directly. Use headers from `util/godot`. * Only use APIs that are available to GDExtensions (or the script API). If they exist in both but are different, use wrappers defined in `util/godot`. ### Namespaces[¶](https://voxel-tools.readthedocs.io/en/latest/development/#namespaces_1 "Permanent link") The intented namespaces are `zylann::` as main, and `zylann::voxel::` for voxel-related stuff. There may be others for different parts of the module. Registered classes are also namespaced to prevent conflicts. Namespaces do not appear in Godot's ClassDB, so voxel-related classes are also prefixed `Voxel`. Other more generic classes are prefixed `ZN_`. If a registered class needs the same name as an internal one, it can be placed into a `::godot` sub-namespace. On the other hand, internal classes can also be suffixed `Internal`. ### Version control[¶](https://voxel-tools.readthedocs.io/en/latest/development/#version-control "Permanent link") * Prefer separating commits with logic changes and commits with code formatting * When doing a PR, prefer to squash WIP commits Debugging[¶](https://voxel-tools.readthedocs.io/en/latest/development/#debugging "Permanent link") --------------------------------------------------------------------------------------------------- ### Command line arguments[¶](https://voxel-tools.readthedocs.io/en/latest/development/#command-line-arguments "Permanent link") When you start Godot, by default it starts the project manager. When you choose a project from there, it will relaunch itself, but that breaks the debugger's connection. So it is recommended to use command line arguments to directly start Godot in the project and mode you want. First, make sure Godot is launched within the working directory of your project. * To debug the game, launch Godot with no argument, and it will start from the main scene. * To debug a specific scene of the project, launch Godot with the relative path to the scene as command line argument * To debug the editor, add the `-e` argument. Example of options setup in in VSCode `launch.json` on Windows: { "version": "0.2.0", "configurations": [\ {\ "name": "(Windows) Launch",\ "type": "cppvsdbg", // For MSVC\ //"type": "cppdbg", // For GDB\ "request": "launch",\ "program": "${workspaceFolder}/bin/godot.windows.editor.dev.x86_64.exe", // Dev build (old target=debug)\ //"program": "${workspaceFolder}/bin/godot.windows.editor.x86_64.exe", // Non-dev build (old target=release_debug)\ "args": [\ "-v", // Verbose output\ \ //"-e", // Editor mode\ \ //"--debug-collisions",\ \ // Run a specific scene\ //"local_tests/sqlite/test_sqlite.tscn",\ //"local_tests/texturing/test_textured_terrain.tscn"\ //"local_tests/texturing/test_texturing.tscn"\ ],\ "stopAtEntry": false,\ "cwd": "D:/PROJETS/INFO/GODOT/Games/SolarSystem/Project",\ "environment": [],\ "visualizerFile": "${workspaceFolder}/modules/voxel/misc/voxel.natvis"\ }\ ] } ### Breakpoint on error[¶](https://voxel-tools.readthedocs.io/en/latest/development/#breakpoint-on-error "Permanent link") It is recommended to use a debugger to have better information when errors or crashes occur. It may be useful to open `core/error/error_macros.cpp` (in Godot 4.x) and leave a breakpoint in `_err_print_error`, so that every time an error occurs, the debugger will break in there, providing you with the live call stack and variable states to inspect. If you debug the editor, Godot tends to print a lot more errors for things that aren't critical, such as making temporary mistakes in the script editor, or trying to index a resource file in the explorer dock and failing for whatever reason. In this case you may either need clean dedicated test projects, or place breakpoints after launch. ### Debug print[¶](https://voxel-tools.readthedocs.io/en/latest/development/#debug-print "Permanent link") Godot: #include print_line(String("Hello {0}, my age is {1}").format(varray(name, age))); Non-Godot: #include "util/io/log.h" #include "util/string/format.h" println(format("Hello {}, my age is {}", name, age)); ### Pretty printing[¶](https://voxel-tools.readthedocs.io/en/latest/development/#pretty-printing "Permanent link") Godot and the voxel module both use their own container types, in addition to STL's ones. Debuggers often aren't able to inspect them. For example, Godot's `Vector` class is similar to `std::vector` but debuggers are unable to let you inspect what's in them. To fix this, it is usually possible to provide your debugger a file listing special patterns to inspect these types in a more user-friendly way. In VSCode, the cpp-tools extension supports Natvis files. Godot comes with such a file in `platform/windows/godot.natvis`. To get pretty printing for Godot types, in your `launch.json` file, add the following line: "visualizerFile": "${workspaceFolder}/platform/windows/godot.natvis" Unfortunately, only one file can be provided at the moment. [An issue is open](https://github.com/Microsoft/vscode-cpptools/issues/925) to request support for multiple files. That means if you also want pretty-printing for structures of the voxel module, you have to replace the natvis path with the following: "visualizerFile": "${workspaceFolder}/modules/voxel/misc/voxel.natvis" Profile with Tracy[¶](https://voxel-tools.readthedocs.io/en/latest/development/#profile-with-tracy "Permanent link") --------------------------------------------------------------------------------------------------------------------- This module contains macros to profile specific code sections. By default, these macros expand to [Tracy Profiler](https://github.com/wolfpld/tracy) zones. It allows to check how long code takes to run, and displays it in a timeline. It was tested with [Tracy 0.10](https://github.com/wolfpld/tracy/releases/tag/v0.10) , but later versions probably work too. ![Tracy screenshot](https://voxel-tools.readthedocs.io/en/latest/images/tracy.webp) Alternative profilers are also mentionned in the [Godot docs](https://docs.godotengine.org/en/stable/engine_details/development/debugging/using_cpp_profilers.html#doc-using-cpp-profilers) . They profile everything and appear to be based on CPU sampling, while Tracy is an instrumenting profiler providing specific, live results on a timeline. A typical workflow is to launch Tracy, start a connection, and then launch the game, which will establish a connection and record all events. Tracy can also be launched and connect after the game, in which case the data will accumulate inside the game. ### Tracy-enabled builds[¶](https://voxel-tools.readthedocs.io/en/latest/development/#tracy-enabled-builds "Permanent link") Note These builds are experimental and will be reworked when Godot 4.6 is released with better Tracy support. Builds of Godot with the module and Tracy integrated are available for Windows, on [Github Actions](https://github.com/Zylann/godot_voxel/actions/workflows/windows.yml) . The file to download will have `tracy` in the name. Note, you will need a Github account to download it. Warning These builds start recording data immediately on startup. _That includes the project manager and the editor_. It can use a lot of memory (2 Gb just starting the editor). If you only want to profile the game, [use the command line](https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html#command-line-tutorial) to directly launch that build of Godot with your game, or just drop the executable at the root of your project and launch it. Outside of this case, you have to compile yourself to get Tracy support. Once you are done profiling, don't forget to switch back to a normal build, otherwise profiling data will accumulate in memory without being retrieved. ### Adding Tracy[¶](https://voxel-tools.readthedocs.io/en/latest/development/#adding-tracy "Permanent link") #### In Godot 4.6 and later[¶](https://voxel-tools.readthedocs.io/en/latest/development/#in-godot-46-and-later "Permanent link") Since Godot 4.6, Tracy is natively supported as an option of Godot's build system. You need to recompile the engine with additional SCons options: `profiler=tracy profiler_path=`. #### in Godot 4.5 and older[¶](https://voxel-tools.readthedocs.io/en/latest/development/#in-godot-45-and-older "Permanent link") To add Tracy support, clone it under `thirdparty/tracy` (Godot's `thirdparty` folder, not the module). Then compile the engine by including `tracy=yes` in the SCons command line. This way so internally some of the work is actually done in the voxel module's build script. Note Tracy has a concept of frame mark, which is usually provided by the application, to tell the profiler when each frame begins. Godot doesn't have a hook for us to insert that call at the right time, so the frame mark was hacked into `VoxelEngine` process function. This allows to see frames of the main thread in the timeline, but they might be offset from their real beginning. #### In GDExtension build[¶](https://voxel-tools.readthedocs.io/en/latest/development/#in-gdextension-build "Permanent link") Not supported at the moment, but with a few tweaks of the build system it could be made to work. ### How to add profiler scopes[¶](https://voxel-tools.readthedocs.io/en/latest/development/#how-to-add-profiler-scopes "Permanent link") If existing instrumentation isn't enough, you can add more by editing the code. A profiling scope bounds a section of code. It takes the time before, the time after, and records it into a timeline. In C++ we can use RAII to automatically close a section when we exit a function or block, so usually a single macro is needed at the beginning of the profiled zone. The module already have plenty of them, but you can add yours if you need more insight. The macros are profiler-agnostic, so if you want to use another profiler it is possible to change them. You need to include `util/profiling.h` to access the macros. To profile a whole function: void some_function() { ZN_PROFILE_SCOPE(); //... } To profile part of a function: void some_function() { // Some code... // Could be an `if`, `for`, `while`, or a simple block as here { ZN_PROFILE_SCOPE(); // Profiled code... } //... } By default scopes take the name of the function, or file and a line number, but you can give a name explicitely using `ZN_PROFILE_SCOPE_NAMED("Hello")`. Only compile-time strings are supported, don't use `String` or `std::string`. It is also possible to plot numeric values so they are displayed in the timeline too: void process_every_frame() { // Some code... ZN_PROFILE_PLOT("Bunnies", bunnies.size()); } Compilation flags and macros[¶](https://voxel-tools.readthedocs.io/en/latest/development/#compilation-flags-and-macros "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------- The module has a few preprocessor macros that can be defined in order to turn off parts of the code getting compiled. Some can be specified through SCons command line parameters. ### Features[¶](https://voxel-tools.readthedocs.io/en/latest/development/#features "Permanent link") By default, features are all enabled, unless specified otherwise. To turn off a feature, specify `flag_name=no` in the SCons command line. | SCons flag | C++ Macro | Description | | --- | --- | --- | | `voxel_fast_noise_2` | `VOXEL_ENABLE_FAST_NOISE_2` | Integrated support for SIMD CPU noise using FastNoise2. It is optional in case it causes problem on some compilers or platforms. **Not available in GDExtension builds**. | | `voxel_tests` | `VOXEL_TESTS` | Unit tests. They will run on startup if the `--run_voxel_tests` command line argument is passed, or if `VoxelEngine.run_tests()` is called. | | `voxel_smooth_meshing` | `VOXEL_ENABLE_SMOOTH_MESHING` | Smooth voxel meshers and some associated features. Turning this off also turns off modifiers, which depend on it. | | `voxel_modifiers` | `VOXEL_ENABLE_MODIFIERS` | `VoxelModifier` experimental feature support. | | `voxel_sqlite` | `VOXEL_ENABLE_SQLITE` | `VoxelStreamSQLite`, which also bundles the SQLite3 library. | | `voxel_instancer` | `VOXEL_ENABLE_INSTANCER` | `VoxelInstancer` support | | `voxel_gpu` | `VOXEL_ENABLE_GPU` | GPU compute support (the GPU is still used when this option is off, just not using compute shaders) | | `voxel_basic_generators` | `VOXEL_ENABLE_BASIC_GENERATORS` | Includes basic generators that could be used for testing. | | `voxel_mesh_sdf` | `VOXEL_ENABLE_MESH_SDF` | Support for voxelized meshes with `VoxelMeshSDF`. Turning this off also turns off modifiers, which depend on it. | | `voxel_vox` | `VOXEL_ENABLE_VOX` | Ability to load `.vox` MagicaVoxel files. | Warning Testing combinations of these flags over time is very time-consuming, and most people don't compile custom builds to turn them off. So it is possible that the project doesn't compile with a specific subset. You may signal it and/or open a PR if you want to fix it. ### Other macros[¶](https://voxel-tools.readthedocs.io/en/latest/development/#other-macros "Permanent link") * `MESHOPTIMIZER_ZYLANN_WRAP_LIBRARY_IN_NAMESPACE`: this one must be defined to prevent conflict with Godot's own version of MeshOptimizer. See [https://github.com/zeux/meshoptimizer/issues/311#issuecomment-955750624](https://github.com/zeux/meshoptimizer/issues/311#issuecomment-955750624) * `ZN_GODOT`: must be defined when compiling this project as a module. * `ZN_GODOT_EXTENSION`: must be defined when compiling this project as a GDExtension. Shaders[¶](https://voxel-tools.readthedocs.io/en/latest/development/#shaders "Permanent link") ----------------------------------------------------------------------------------------------- The module contains shaders for some of its features, mainly compute shaders. They are found under the `shaders/dev/` folder. `shaders/dev` contains a Godot project. The purpose of this project is mainly to quickly test if shaders compile properly, and eventually test them with simple scenes and GDScript code. There are several ways shaders are written: * Plain: regular shaders, which will be used as-is. * Templates: these contain `` sections, which the engine will replace with generated code. Code inside those sections will be replaced and is only present to make the shader compile in the test project. * Snippets: these contain `` sections, which will be inserted into templates or other generated code. Code outside those sections will not be used and is only present to make the shader compile in the test project. Shipping external files when compiling as a module is inconvenient, so instead they are embedded in C++ directly, similarly to how Godot does. A script can be executed to update those generated files. You must open a command line inside the `shaders/` folder and run `python text2cpp.py`. Currently, C++ code generating shaders is intertwined with the contents of those shaders. For example, C++ strings in code generation can contain variable names found in GLSL files, so you should have both open to understand the context. Using the module from another module[¶](https://voxel-tools.readthedocs.io/en/latest/development/#using-the-module-from-another-module "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------------------- Writing a custom C++ module directly in Godot is the easiest way to access features of Godot and the voxel engine directly, which can be better for performance and more stable than a GDExtension. You can do this too if you want to create a custom generator, mesher, stream, or just use components of the module, without having to modify the module directly. You can include files from the voxel module by using `modules/voxel/` in your includes: #include You will also need to define preprocessor macros in your `SCsub` file: env_yourmodule.Append(CPPDEFINES = [\ 'ZN_GODOT'\ ]) TODO: since the implementation of [compiling-out features](https://github.com/Zylann/godot_voxel/issues/746) , you will have a lot more of preprocessor symbols to define, since you may want to `#include` headers of the voxel engine that expect them to be defined or not. There is currently no helper to do this, so you have to add them manually in your `CPPDEFINES` array. See the [list of macros](https://voxel-tools.readthedocs.io/en/latest/development/#features) . Note While API docs cover functions you will also find in C++, internals sometimes only have comments. They are not documented outside, and there is no plan to do so. It is recommended to inspect the headers to find what is exposed, what namespaces to use etc. You may also read existing code in `.cpp` files to see how some things are used. --- # Editor - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Editor * * * Editor[¶](https://voxel-tools.readthedocs.io/en/latest/editor/#editor "Permanent link") ======================================================================================== Previewing in the editor[¶](https://voxel-tools.readthedocs.io/en/latest/editor/#previewing-in-the-editor "Permanent link") ---------------------------------------------------------------------------------------------------------------------------- ![Screenshot of the editor](https://voxel-tools.readthedocs.io/en/latest/images/editor_preview_smooth_2d_noise_terrain.webp) ### Preview options[¶](https://voxel-tools.readthedocs.io/en/latest/editor/#preview-options "Permanent link") Terrains with a generator or valid stream assigned to them are able to show up in the editor by default. If the generator or stream is providing a type of voxel data which is not supported by the mesher, nothing will show up. This is usually fixed by changing the mesher or its channel option, when available. The whole terrain can be told to re-mesh or re-load by using one of the options in the `Terrain` menu: ![Re-generate menu](https://voxel-tools.readthedocs.io/en/latest/images/menu_regenerate.webp) #### Tool scripts[¶](https://voxel-tools.readthedocs.io/en/latest/editor/#tool-scripts "Permanent link") Warning Take extra caution with tool scripts on generators and streams. If you use a script on either [VoxelGeneratorScript](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorScript/) or [VoxelStreamScript](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamScript/) , they will be executed in the editor if they are declared with tool mode (`@tool` in GDScript). However, alongside risks of tool mode, there is extra danger: if the script gets modified while it is still being run by a background thread in the editor, unpredictable bugs can happen. You have to make sure the script doesn't change while previewing this way, or that terrain finished loading (can be forced to a degree by closing the scene). Therefore tool mode should only be used temporarily during development. You can always test by running your game instead, with or without tool mode. This limitation is tracked in [issue177](https://github.com/Zylann/godot_voxel/issues/177) . ### Camera options[¶](https://voxel-tools.readthedocs.io/en/latest/editor/#camera-options "Permanent link") In the editor, blocks will only load around the node's origin by default. If the volume is very big or uses LOD, it will not load further and concentrate detail at its center. You can override this by going in the `Terrain` menu and enabling `Stream follow camera`. This will make the terrain adapt its level of detail and blocks to be around the editor's camera, and will update as the camera moves. Turning off the option will freeze the terrain. ![Stream follow camera menu](https://voxel-tools.readthedocs.io/en/latest/images/menu_stream_follow_camera.webp) This option exists for large volumes because they need to stream blocks in and out as you move around. While this is often done in a controlled manner in a game, in the editor the camera could be moving very fast without any restriction, which can demand much more work for the CPU. You can monitor the amount of ongoing tasks in the bottom panel, while the node is selected. The terrain also needs to be selected, partially because of [this](https://github.com/godotengine/godot-proposals/issues/1302) ). Terrains can be very big, and sometimes Godot might prevent you from zooming out further. You can workaround this by increasing the editor's Camera `far` clip in the `View -> Settings` menu. That might slightly degrade visual quality if set too high, so you can also increase `near` clip to keep it balanced. These two numbers cannot be too far apart due to 32-bit float precision. Editing[¶](https://voxel-tools.readthedocs.io/en/latest/editor/#editing "Permanent link") ------------------------------------------------------------------------------------------ There are no tools to edit voxel volumes destructively in the Godot Editor yet. This feature might be implemented in the future. It is possible to use non-destructive [modifiers](https://voxel-tools.readthedocs.io/en/latest/generators/#modifiers) , but they are limited. Terrains can be fully edited in-game using scripts and [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/scripting/) . It is also possible to create a script editor plugin to implement edition in a similar manner. --- # Getting Voxel Tools - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Getting Voxel Tools * * * Getting Voxel Tools[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#getting-voxel-tools "Permanent link") ============================================================================================================================== This project exists in two editions: * [Module](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#module) : bundled as a custom build of Godot Engine and custom export templates. This is the primary way it was developped for a long time. * [GDExtension](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#gdextension) : a native add-on that can be added to your project, and will work with an official build of Godot (4.4.1 or later). This is more recent so it had less testing so far. Each one comes with its own advantages and drawbacks, but generally offer the same functionality. Module[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#module "Permanent link") ---------------------------------------------------------------------------------------------------- The following section applies if you use the Module edition of Voxel Tools. ### Precompiled builds[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#precompiled-builds "Permanent link") #### Release builds[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#release-builds "Permanent link") Builds are provided at [https://github.com/Zylann/godot\_voxel/releases](https://github.com/Zylann/godot_voxel/releases) . Module builds are usually prefixed as `Godot 4.x.x + Voxel Tools 1.x.x`. The project follows a continuous development cycle, so "releases" are merely snapshots of development versions. Because Github requires an account to download latest development versions from Github Actions, releases are published for convenience. The engine is massive and targets a lot of platforms, while our module is small in comparison and we don't have dedicated build containers, so not all combinations of editors and export templates are available. You can develop your game and test it with the editor on main desktop platforms, but if a combination of platforms/options isn't provided, you will have to build them yourself. #### Development builds[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#development-builds "Permanent link") Development builds contain the very latest features and bug fixes (although they can also contain unknown bugs). They are available on Github Actions. Note You need a Github account to download artifacts from Github Actions. Otherwise, links will not work. Pick your platform: * [Windows builds](https://github.com/Zylann/godot_voxel/actions/workflows/windows.yml) * [Linux builds](https://github.com/Zylann/godot_voxel/actions/workflows/linux.yml) * [MacOS builds](https://github.com/Zylann/godot_voxel/actions/workflows/macos.yml) Then click on the latest successful build, with a green checkmark: ![Screenshot of a list of builds, with the latest successful one circled in green](https://voxel-tools.readthedocs.io/en/latest/images/ci_builds_latest_link.webp) Then scroll to the bottom, you should see download links: ![Github actions screenshot](https://voxel-tools.readthedocs.io/en/latest/images/github_actions_windows_artifacts.webp) In case there are multiple downloadable artifacts, the editor build will be the one with `editor` in the name. These builds correspond to the `master` version depicted in the [changelog](https://github.com/Zylann/godot_voxel/blob/master/CHANGELOG.md) . They are built using Godot's latest stable version branch (for example, `4.2` at time of writing), instead of `master`, unless indicated otherwise. A new build is made each time commits are pushed to the main branch, but also when other developers make Pull Requests, so careful about which one you pick. Note Mono builds (C# support) [are also done](https://github.com/Zylann/godot_voxel/actions/workflows/mono.yml) , however they no longer work out of the box. For more information, see [C# support](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#c-suppport) . ### Building yourself[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#building-yourself "Permanent link") See [Building as a module](https://voxel-tools.readthedocs.io/en/latest/development/#building) ### Exporting[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#exporting "Permanent link") Note You will need this section if you want to export your game into an executable. #### Supported platforms[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#supported-platforms "Permanent link") This module supports all platforms Godot supports, on which threads are available. Some features might not always be available: * SIMD noise with FastNoise2 0.10 can only benefit from an x86 CPU and falls back to scalar otherwise, which is slower * GPU features require support for compute shaders (Forward+ renderer) * Threads might not work on all browsers with the web export #### Getting a template[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#getting-a-template "Permanent link") In Godot Engine, exporting your game as an executable for a target platform requires a "template". A template is an optimized build of Godot Engine without the editor stuff. Godot combines your project files with that template and makes the final executable. If you only download the Godot Editor with the module, it will allow you to develop and test your game, but if you export without any other setup, Godot will attempt to use a vanilla template, which won't have the module. Therefore, it will fail to open some scenes. As mentionned in earlier sections, you can get pre-built templates for some platforms and configurations. If there is no pre-built template available for your platform, you may build it yourself. This is the same as building Godot with the module, only with different options. See the [Godot Documentation](https://docs.godotengine.org/en/latest/development/compiling/index.html) for more details, under the "building export templates" category of the platform you target. #### Using a template[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#using-a-template "Permanent link") Once you have a template build, tell Godot to use it in the Export configurations. Fill in the path to a custom template in the "Custom Template" section: ![Screenshot of Godot export configuration window with a custom template assigned for Windows](https://voxel-tools.readthedocs.io/en/latest/images/export_template_window.webp) GDExtension[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#gdextension "Permanent link") -------------------------------------------------------------------------------------------------------------- Godot 4 introduced [GDExtension](https://docs.godotengine.org/en/stable/tutorials/scripting/gdextension/what_is_gdextension.html) , a native API allowing C++ plugins to be added to a project without requiring a custom build of the engine. Voxel Tools can also compile as a GDExtension, although it is a recent addition, and has gone through less testing, so it might have bugs that are not present in the Module edition. ### Differences[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#differences "Permanent link") Module and GDExtension editions aim to be compatible. However, there are a few important differences (list non exhaustive): * `FastNoise2` is not included * There are some technical drawbacks, some of which [are listed here](https://github.com/Zylann/godot_voxel/issues/442) ### Release builds[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#release-builds_1 "Permanent link") Plugin packages can be found in Releases: [https://github.com/Zylann/godot\_voxel/releases](https://github.com/Zylann/godot_voxel/releases) . They usually contain the word `GDExtension` in the title. The project follows a continuous development cycle, so "releases" are merely snapshots of development versions. Because Github requires an account to download latest development versions from Github Actions, releases are published for convenience. ### Development builds[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#development-builds_1 "Permanent link") There are development builds of the GDExtension available on [Github Actions](https://github.com/Zylann/godot_voxel/actions/workflows/extension_ci.yml) as we try to keep the module compiling with GodotCpp, however they lack testing and might crash. Use at your own risk. ### Building yourself[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#building-yourself_1 "Permanent link") If the provided binaries don't include the platform or options you need, or if you need customizations, you can still make your own build. See [Development](https://voxel-tools.readthedocs.io/en/latest/development/#gdextension) ### Exporting[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#exporting_1 "Permanent link") Exporting your game with Godot's regular templates should work out of the box. You can check which platforms are provided by the extension in the config file at `addons/zylann.voxel/voxel.gdextension`: * Windows x86\_64 * Linux x86\_64 * Mac OS x86\_64 (universal) * Mac OS arm64 (universal) * iOS arm64 * Android x86\_64 * Android arm64 If what you need is not in this list, you may try [Building yourself](https://voxel-tools.readthedocs.io/en/latest/development/#gdextension) . #### Stripping out icons[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#stripping-out-icons "Permanent link") Currently, editor icons have to be registered in the GDExtension config file and cannot be excluded with a `.gdignore` file. That means when you export your game, those icons will be needlessly included in your game. You can exclude the contents of the `addons/zylann.voxel/editor` folder in your export configurations. Switching between Module and GDExtension[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#switching-between-module-and-gdextension "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ If you start using GDExtension in a project that was using the Module edition, you should use an official version of Godot Engine, or one that does not include the module, otherwise classes will conflict. If you want to switch back to using the Module edition, you can remove all files related to GDExtension in `addons/zylann.voxel/` and then start the editor. Alternatively, you can also change the file extension of `addons/zylann.voxel/voxel.gdextension` so that Godot no longer detects it. C# support[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#c-support "Permanent link") ----------------------------------------------------------------------------------------------------------- C# is a bit of a special case in Godot, especially when it comes to plugins. It requires extra work to setup. ### Module[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#module_1 "Permanent link") Working builds used to be available on Github Actions (as "Mono Builds"). Unfortunately, Godot 4 changed the way C# integrates by using the Nuget package manager. This made it harder for module developers to provide ready-to-use executables, and hard for users too: * When you make a project in Godot C#, it fetches the "vanilla" Godot SDK from Nuget, but it is only available for official stable versions, so you can't use CI builds of the engine that use the latest development version of Godot. * Modules add new classes to the API which are not present in the official SDK. It would require to create SDKs for every combination of modules you want to use and upload them to Nuget, which isn't practical. * You could revert to the latest official SDK available on Nuget, but to access module APIs you would have to use workarounds such as `obj.Get(string)`, `Set(string)` and `Call(string, args)` in code, which is hard to use, inefficient and terrible to maintain. To obtain a working version, you have to generate the SDK yourself and use a local Nuget repository instead of the official one. Follow the steps described in the [Godot Documentation for C#](https://docs.godotengine.org/en/stable/engine_details/development/compiling/compiling_with_dotnet.html) . ### Ownership checks[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#ownership-checks "Permanent link") Voxel Tools does some sanity checks when running some virtual methods, such as custom generators. These checks involve reference counting. However, that doesn't work in C# because it is a garbage-collected language: `RefCounted` objects going out of scope are not actually freed until the garbage collector runs. This can cause false-positive errors. You may turn off those checks in Project Settings: `voxel/ownership_checks` ### GDExtension and `C#`[¶](https://voxel-tools.readthedocs.io/en/latest/getting_the_module/#gdextension-and-c "Permanent link") C# support of extensions implemented in C++ is not well defined at the moment. The issue is that the Godot API C# can use (nicknamed the "glue") is generated when Godot itself is built, so it only contains core vanilla classes. Everything else (extensions, GDScript) is missing from it, so it requires to use Godot's reflection methods. In theory, C++ extensions could provide a strongly-typed API since they have function pointers that could be bound to C#, but this has not been implemented by Godot so far. So the only way to interact from C# with classes defined by an extension is to use the following: * Calling methods: [call](https://docs.godotengine.org/en/stable/classes/class_object.html#class-object-method-call) * Getting or setting properties: [get](https://docs.godotengine.org/en/stable/classes/class_object.html#class-object-method-get) and [set](https://docs.godotengine.org/en/stable/classes/class_object.html#class-object-method-set) * Creating new instances: [ClassDB.instantiate](https://docs.godotengine.org/en/stable/classes/class_classdb.html#class-classdb-method-instantiate) . // /!\ Pseudo-code, untested GodotObject model = Godot.ClassDB.Instantiate("VoxelBlockyModelCube"); model.Call("set_tile", Godot.ClassDB.ClassGetIntegerConstant("VoxelBlockyModel", "SIDE_NEGATIVE_X"), new Vector2I(1, 1)) model.Set("atlas_size_in_tiles", new Vector2I(8, 8)); This approach however carries a lot of overhead, impacts performance, and is tedious to use. Similar situations are presented in Godot's documentation about [Cross-Language Scripting](https://docs.godotengine.org/en/stable/tutorials/scripting/cross_language_scripting.html) --- # Generators - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Generators * * * Generators[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#generators "Permanent link") ==================================================================================================== `VoxelGenerator` allows to generate voxels given a specific area in space, or from a single position. They can serve as a base to automate the creation of large landscapes, or can be used in a game to generate worlds. They have an important place because storing voxel data is expensive, while procedural sources are lightweight. How generators work[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#how-generators-work "Permanent link") ---------------------------------------------------------------------------------------------------------------------- Generators currently run on the CPU and primarily work on blocks of voxels. For example, given a `VoxelBuffer` of 16x16x16 voxels, they decide what value each one will take. Using blocks makes it easier to split the work across multiple threads, and focus only on the area the player is located, especially if the world is infinite. Voxel data is split into various channels, so depending on the kind of volume to generate, one or more different channels will be used. For example, a Minecraft generator will likely use the `TYPE` channel for voxel types, while a smooth terrain generator will use the `SDF` channel to fill in distance field values. Generators have a thread-safe API. The same generator `generate_block` method may be used by multiple threads at once. However, depending on the class, some parameters might only be modifiable from the main thread, so check the documentation to be sure. If a volume is not given a generator, blocks will be filled with air by default. ### Series generation[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#series-generation "Permanent link") Some generators support "series generation": in addition to being able to fill 3D grids of voxels ("chunks"), they can also work when given a list of arbitrary floating-point positions (or "point cloud"). This is used by some features like detail rendering (CPU only) and `VoxelInstanceGenerator` snapping to SDF. Not all generators can do this, and this feature is not required for the terrain system to work. There is also no scripting API to implement this currently. `VoxelGeneratorGraph` supports it, and some of the basic generators too. Basic generators[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#basic-generators "Permanent link") ---------------------------------------------------------------------------------------------------------------- The module provides several built-in generators. They are simple examples to get a quick result, and showing how the base API can be implemented (see source code). Some of these generators have an option to choose which channel they will work on. If you use a smooth mesher, use the `SDF` channel (1), otherwise use the `TYPE` channel (0). The following screenshots use a smooth `VoxelLodTerrain`. ### [Flat](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorFlat/) [¶](https://voxel-tools.readthedocs.io/en/latest/generators/#flat "Permanent link") Generates a flat ground. ![Screenshot of flat generator](https://voxel-tools.readthedocs.io/en/latest/images/generator_flat.webp) ### [Waves](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorWaves/) [¶](https://voxel-tools.readthedocs.io/en/latest/generators/#waves "Permanent link") Generates waves. ![Screenshot of waves generator](https://voxel-tools.readthedocs.io/en/latest/images/generator_waves.webp) ### [Image](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorImage/) [¶](https://voxel-tools.readthedocs.io/en/latest/generators/#image "Permanent link") Generates a heightmap based on an image, repeated infinitely. ![Screenshot of image generator](https://voxel-tools.readthedocs.io/en/latest/images/generator_image.webp) Note With this generator, an `Image` resource is required. By default, Godot imports image files as `StreamTexture`. You may change this in the Import dock. At time of writing, in Godot 3, this requires an editor restart. ### [Noise2D](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise2D/) [¶](https://voxel-tools.readthedocs.io/en/latest/generators/#noise2d "Permanent link") Generates a heightmap based on fractal noise. ![Screenshot of 2D noise generator](https://voxel-tools.readthedocs.io/en/latest/images/generator_noise2d.webp) ### [Noise (3D)](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise/) [¶](https://voxel-tools.readthedocs.io/en/latest/generators/#noise-3d "Permanent link") Generates a blobby terrain with overhangs using 3D fractal noise. A gradient is applied along height so the volume becomes air when going up, and closes down into matter when going down. ![Screenshot of 3D noise generator](https://voxel-tools.readthedocs.io/en/latest/images/generator_noise3d.webp) Node-graph generators with `VoxelGeneratorGraph`[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#node-graph-generators-with-voxelgeneratorgraph "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Basic generators may often not be suited to make a whole game from, but you don't necessarily need to program one. C++ is a very fast language to program a generator but it can be a tedious workflow, especially when prototyping. If you need smooth terrain, a graph-based generator is available, which offers a very customizable approach to make procedural volumes. Warning This generator was originally made for smooth terrain, but works with blocky too, to some extent. ### Concept[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#concept "Permanent link") Voxel graphs allow to represent a 3D density by connecting operation nodes together. It takes 3D coordinates (X, Y, Z), and computes the value of every voxel from them. For example it can do a simple 2D or 3D noise, which can be scaled, deformed, masked using other noises, curves or even images. An inspiration of this approach comes again from sculpting of signed-distance-fields (every voxel stores the distance to the nearest surface), which is why the main output node is usually an `SdfOutput`. A bunch of nodes are meant to work on SDF as well. However, it is not strictly necessary to respect perfect distances, as long as the result looks correct for a game, so most of the time it's easier to work with approximations. Note Voxel graphs are half-way between programming 3D shaders and procedural design. It has similar speed to C++ generators but has only basic instructions, so there are some maths involved. This might get eased a bit in the future when more high-level nodes are added. ### Examples[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#examples "Permanent link") #### Flat plane[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#flat-plane "Permanent link") The simplest possible graph with a visible output is a flat plane. The SDF of a flat plane is the distance to sea-level (0), which is `sdf = y`. In other words, the surface appears where voxel values are crossing zero. Right-click the background of the graph, choose the nodes `InputY` and `SdfOutput`, then connect them together by dragging their ports together. ![Plane voxel graph screenshot](https://voxel-tools.readthedocs.io/en/latest/images/voxel_graph_flat.webp) It is possible to decide the height of the plane by subtracting a constant (`sdf = y - height`), so that `sdf == 0` will occur at a higher coordinate. To do this, an extra node must be added: ![Offset plane voxel graph screenshot](https://voxel-tools.readthedocs.io/en/latest/images/voxel_graph_flat_offset.webp) By default, the `Add` node does nothing because its `b` port is not connected to anything. It is possible to give a default value to such port. You can set it by clicking on the node and changing it in the inspector. (note: I used `Add` with a negative value for `b`, but you can also use a `Subtract` node to get the same result). Making a flat plane also has a shortcut node, `SdfPlane`, which outputs the SDF of a flat plane in one go (equivalent to `y - height`). #### Noise[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#noise "Permanent link") A flat plane is simple but a bit boring, so one typical way to generate a terrain is adding good old fractal noise. You can do this in 2D (heightmap) or 3D (volumetric). The 2D approach is simpler, as we only need to take our previous setup, and add 2D noise to the result. Also, since noise is generated in the range \[-1 to 1\], we also need a multiplier to make it larger (`sdf = y - height + noise2d(x, y) * noise_multiplier`). There are several types of noise available, each with their own parameters. At time of writing, `FastNoise2D` noise is the best option. `Noise2D` works too but it is slightly slower (in particular when using Voxel Tools as a GDExtension). After you create this node, a new `FastNoiseLite` resource must be created in its parameters. ![Voxel graph 2D noise](https://voxel-tools.readthedocs.io/en/latest/images/voxel_graph_noise2d.webp) 3D noise is more expensive to compute, but is interesting because it actually produces overhangs or even small caves. It is possible to replace 2D noise with 3D noise in the previous setup: ![Voxel graph 3D noise](https://voxel-tools.readthedocs.io/en/latest/images/voxel_graph_noise3d_not_expanded.webp) You might notice that despite it being 3D, it still appears to produce a heightmap. That's because the addition of `Y` in the graph is gradually offsetting noise values towards higher and higher values when going towards the sky, which makes the surface fade away quickly. We can either multiply `Y` with a value smaller than 1, or we can increase the amplitude of the noise (`sdf = y - height + amplitude * noise3d(x, y, z)`): ![Voxel graph 3D noise expanded](https://voxel-tools.readthedocs.io/en/latest/images/voxel_graph_noise3d_expanded.webp) Note Some nodes have default connections. For example, with 3D noise, if you don't connect inputs, they will automatically assume (X,Y,Z) voxel position by default (see "Auto" labels). If you need a constant in an input, this behavior can be opted out by turning off `autoconnect_default_inputs` in the inspector, or connecting another node. #### Planet[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#planet "Permanent link") We are not actually forced to keep generating the world like a plane. We can go even crazier, and do planets. A good way to begin a planet is to make a sphere with the `SdfSphere` node: ![Voxel graph sdf sphere node](https://voxel-tools.readthedocs.io/en/latest/images/voxel_graph_sphere.webp) We cannot really use 2D noise here, so we can add 3D noise as well: ![Voxel graph sdf sphere with noise](https://voxel-tools.readthedocs.io/en/latest/images/voxel_graph_sphere_with_noise.webp) If you increase 3D noise amplitude like before, you might notice floating chunks. You should be able to tune the right amount to make them less likely. Another way is to use a height-based approach: project coordinates on the sphere, instead of global 3D coordinates. Then treat the output of noise as a height. Picking a ridged fractal can also give an eroded look, although it requires to negate the noise to invert its distance field (if we leave it positive it will look puffed instead of eroded). ![Voxel graph sdf sphere with height noise](https://voxel-tools.readthedocs.io/en/latest/images/voxel_graph_sphere_with_noise2.webp) Note You can obtain a donut-shaped planet if you replace the `SdfSphere` node with a `SdfTorus` node. ![Torus voxel graph](https://voxel-tools.readthedocs.io/en/latest/images/voxel_graph_torus.webp) More techniques can be found in the [Procedural Generation](https://voxel-tools.readthedocs.io/en/latest/procedural_generation/) section. ### Usage with blocky voxels[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#usage-with-blocky-voxels "Permanent link") It is possible to use this generator with `VoxelMesherBlocky` by using an `OutputType` node instead of `OutputSDF`. However, `VoxelMesherBlocky` expects voxels to be IDs, not SDF values. The simplest example is to pick any existing SDF generator, and replace `OutputSDF` with a `Select` node connected to an `OutputType`. The idea is to choose between the ID of two different voxel types (like air or stone) if the SDF value is above or below a threshold. ![Example screenshot of a basic blocky heightmap made with a graph generator](https://voxel-tools.readthedocs.io/en/latest/images/voxel_graph_blocky_basic_heightmap.webp) If more variety is needed, `Select` nodes can be chained to combine multiple layers, using different thresholds and sources. ![Example screenshot of a blocky heightmap with two biomes made with a graph generator](https://voxel-tools.readthedocs.io/en/latest/images/voxel_graph_blocky_biome.webp) `Select` creates a "cut" between the two possible values, and it may be desirable to have some sort of transition. While this isn't possible with `VoxelMesherBlocky` without a lot of different types for each value of the gradient (usually done with a shader), it is however easy to add a bit of noise to the threshold. This reproduces a similar "dithered" transition, as can be seen in Minecraft between sand and dirt. ![Example screenshot of a blocky heightmap with two biomes and dithering](https://voxel-tools.readthedocs.io/en/latest/images/voxel_graph_blocky_biome_dithering.webp) Currently, graph generators only work per voxel. That makes them good to generate base ground and biomes, but it isn't practical to generate structures like trees or villages with it. This may be easier to accomplish using a second pass on the whole block instead, using a custom generator. ### Relays[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#relays "Permanent link") A special `Relay` node exists to organize long connections between nodes. They do nothing on their own, they just redirect a connection. It also remains possible for a relay to have multiple destinations. ![Screenshot of a relay node](https://voxel-tools.readthedocs.io/en/latest/images/relay_node.webp) ### Preview nodes[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#preview-nodes "Permanent link") It is possible to preview the output of nodes with the `SdfPreview` node. This node will display a slice of the 3D data as a greyscale image, or a colored image depending on its settings. This is useful to check if a branch is outputting expected values. Note * Preview nodes will only work if the output they are connected to is also connected to an actual output of the graph. ![Screenshot of a preview node showing the output of a plane node](https://voxel-tools.readthedocs.io/en/latest/images/graph_preview_node_plane.webp) In the example above, the preview shows the output of a `SdfPlane` node. Values are negative below the surface, positive above the surface, and increase gradually along the Y axis. As a result, previews show white above, and black below. By default, the node shows a slice along the XY plane, but you can change it to the XZ plane in case you need a top-down view, in the `Debug -> Preview Axes` menu on top of the editor. Here is the output for a sphere of radius 50: ![Screenshot of a preview node showing the output of a sphere node](https://voxel-tools.readthedocs.io/en/latest/images/graph_preview_node_sphere.webp) By default, each pixel of the preview corresponds to 1 unit of space. You can zoom by holding the `CTRL` key and using the mouse wheel on top of the preview. You can also move around by holding `CTRL` and dragging the preview's viewport holding the middle mouse button. Pan & zoom locations can be reset to defaults by using the menu `Debug -> Preview Axes -> Reset Location`. ![Screenshot of a preview node showing the output of a sphere node, zoomed in](https://voxel-tools.readthedocs.io/en/latest/images/graph_preview_node_sphere_pan_and_zoom.webp) Previews show black and white based on a specific range defined in their properties. By default, -1 is black, 1 is white (so 0 is actually grey). You can change that range by selecting the preview node and using the inspector. ![Screenshot of a selected preview node and its min/max properties in the inspector](https://voxel-tools.readthedocs.io/en/latest/images/graph_preview_node_min_max_inspector.webp) When working with signed distance fields (SDF), preview nodes can also display values in a more specialized way. In the inspector, you can change the `mode` to `SDF`: ![Screenshot of a preview node in SDF mode](https://voxel-tools.readthedocs.io/en/latest/images/graph_preview_node_sdf_inspector.webp) This mode shows negative values as blue (inside shape) and positive values as yellow (outside shape). It also renders "bands" of repeating gradients to better visualize how they propagate away from the surface. The length of those bands is controlled by `fraction period`. ![Screenshot of a preview node in SDF mode showing sphere gradient fractions](https://voxel-tools.readthedocs.io/en/latest/images/graph_preview_node_sphere_gradients.webp) With a sphere, gradients are quite regular, which is usually best. But when using noise as signed distance field, you can notice how gradients actually evolve below and above the surface: ![Screenshot of a preview node in SDF mode showing noise gradients](https://voxel-tools.readthedocs.io/en/latest/images/graph_preview_node_noise_sdf.webp) Noise is a lot more inconsistent. However, most of the time, this isn't a big deal. It depends on what operations you do with the terrain. If the "speed" of gradients varies too sharply, especially near the surface, it can be the cause of precision loss or blockyness in generated meshes. It can also be a problem when approximating the surface solely from SDF voxels or using sphere tracing. ### Scripting[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#scripting "Permanent link") Graph generators can be modified from a script using the [VoxelGraphFunction](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/) API. This is useful for example if you design a base graph, and want to randomize noise seeds or adjust some constants. `VoxelGeneratorGraph` contains an instance of it as their "main" function. You can access the graph by calling `get_main_function()` on the generator. Nodes are identified by an ID, so you should give a name to nodes that you want to access so you can get their ID with `find_node_by_name`. Example in the Solar System demo: [https://github.com/Zylann/solar\_system\_demo/blob/1ec891db22b41a842d48ca0c0b1c4c7c9157f6bc/solar\_system/solar\_system\_setup.gd#L306](https://github.com/Zylann/solar_system_demo/blob/1ec891db22b41a842d48ca0c0b1c4c7c9157f6bc/solar_system/solar_system_setup.gd#L306) Custom generator[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#custom-generator "Permanent link") ---------------------------------------------------------------------------------------------------------------- See [Scripting](https://voxel-tools.readthedocs.io/en/latest/scripting/) Using `VoxelGeneratorGraph` as a brush[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#using-voxelgeneratorgraph-as-a-brush "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------------------- This feature is currently only supported in `VoxelLodTerrain` and smooth voxels. `VoxelTool` offers simple functions to modify smooth terrain with `do_sphere` for example, but it is also possible to define procedural custom brushes using `VoxelGeneratorGraph`. The same workflow applies to making such a graph, except it can accept an `InputSDF` node, so the signed distance field can be modified, not just generated. Example of additive `do_sphere` recreated with a graph: ![Additive sphere brush graph](https://voxel-tools.readthedocs.io/en/latest/images/graph_sphere_brush.webp) A more complex flattening brush, which both subtracts matter in a sphere and adds matter in a hemisphere to form a ledge (here defaulting to a radius of 30 for better preview, but making unit-sized brushes may be easier to re-use): ![Dual flattening brush](https://voxel-tools.readthedocs.io/en/latest/images/graph_flatten_brush.webp) One more detail to consider, is how big the original brush is. Usually voxel generators have no particular bounds, but it matters here because it will be used locally. For example if your make a spherical brush, you might use a `SdfSphere` node with radius `1`. Then, your original size will be `(2,2,2)`. You can then transform that brush (scale, rotate...) when using `do_graph` at the desired position. Re-usable graphs with `VoxelGraphFunction`[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#re-usable-graphs-with-voxelgraphfunction "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ `VoxelGraphFunction` allows to create graphs that can be used inside other graphs. This is a convenient way to re-use and share graphs. ### Creating a function[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#creating-a-function "Permanent link") A `VoxelGraphFunction` can be created in the inspector and edited just like a `VoxelGeneratorGraph`, except it will lack some features only found on the latter. It is recommended to save functions as their own `.tres` files, because this is what allows to pick them up in other graphs. Note A `VoxelGraphFunction` cannot contain itself, directly or indirectly. Doing this will result in Godot failing to load it. ### Exposing inputs and outputs[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#exposing-inputs-and-outputs "Permanent link") To be usable in other graphs, functions should have inputs and outputs. Inputs can be added to the function by creating nodes `InputX`, `InputY`, `InputZ`, `InputSDF` or `CustomInput`. Outputs can be added by creating nodes `OutputX`, `OutputY`, `OutputZ`, `CustomOutput` etc. Non-custom inputs and outputs such as `InputX` or `OutputX` are _special_ nodes, and are identified by their type. They are recognized by the engine for specific purposes. You can have multiple nodes with the same type, but they will always refer to the same input of the function. Custom inputs and outputs _are identified by their name_. If you add 2 `CustomInput` nodes and give them the same name, they will get their data from the same input. It is recommended to give a name to custom input and output nodes. Empty names still count as a name (so multiple `CustomInput` without names will refer to the same unnamed input). ### Exposing parameters[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#exposing-parameters "Permanent link") Currently parameters cannot be exposed, but it is planned. ### Handling changes[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#handling-changes "Permanent link") When an existing function changes (new/removed inputs/outputs for example), it is possible that other graphs using it will break. If you try to open them, some of the nodes and connections could be missing. Currently, you are expected to fix these graphs, and save them. You can also change the offending function so that its inputs, outputs and parameters are what you expect. However if you save a broken graph, you might loose some connections or nodes. ### Debugging[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#debugging "Permanent link") Editor tools such as profiling, output previews or range analysis are currently unsupported inside a `VoxelGraphFunction`. It is also not possible to inspect internal nodes of a function when editing a `VoxelGeneratorGraph`. It is planned to have these tools available when editing a standalone `VoxelGraphFunction` in the future. This will be done by moving features out of `VoxelGeneratorGraph` so they become more generic. Inspecting a function "instance" (and sub-instances...) may be desirable, but it is tricky to implement. It could be done as an "Open Inside" feature, to inspect data within the context of the "containing graph". However because functions are fully unpacked and optimized out internally, the engine has to trace back the information to original nodes. Tracing is already present to some degree, but only maps the "top-level" graph to fully-expanded/optimized graph, with no in-between information. This might be worked on further in the future. ### VoxelGeneratorGraph nodes[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#voxelgeneratorgraph-nodes "Permanent link") A complete list of nodes [can be found here](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/) . Multi-pass generation with `VoxelGeneratorMultipassCB`[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#multi-pass-generation-with-voxelgeneratormultipasscb "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Sometimes you need to write a custom generator that needs to produce structures _made of voxels in the terrain itself_ overlapping neighbor chunks, such as trees. While it is possible to make trees with a [deterministic approach](https://voxel-tools.readthedocs.io/en/latest/procedural_generation/#deterministic-approach) , it has limitations and is a bit harder to understand. Also, you might want to have access to an entire vertical section of the world while generating it, instead of just a 16x16x16 chunk. Contrary to other generators, `VoxelGeneratorMultipassCB` allows you to structure generation in several passes, where you can access neighbor chunks. It also works in columns, so you have access to a full vertical section of the world. Things like placing a structure across chunk borders just works. You may find early design information [in this issue](https://github.com/Zylann/godot_voxel/issues/545) . ### World model[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#world-model "Permanent link") ![Schema of a terrain composed of columns, with one column and its neighbors highlighted as the "extent" of generation passes](https://voxel-tools.readthedocs.io/en/latest/images/multipass_columns.webp) This generator is suffixed "CB" for "Column-Based". The world this generator works on is "flat". Similar to Minecraft, generation occurs within a fixed region going from minimum to maximum altitude (specified with properties), in columns of 16x16 voxels. Then everything above is air, and everything below is either bedrock or just air too. The amount of neighbor columns a pass can access is called the "extent" of the pass. While the multipass column logic only works within the fixed vertical range, it will be possible to define what's outside of that range, but it has to be single pass. In sections below, "column" will refer to a stack of blocks within the fixed region. Note Fixed column height is a design choice to make the generator simpler to implement, and should cover the majority of terrains. However, this is only a limitation of the generator. `VoxelTerrain` remains unlimited vertically, so players can still build higher than the area handled by the terrain generator. ### API[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#api "Permanent link") This generator is implemented using a script, similar to `VoxelGeneratorScript`. The difference is this function: extends VoxelGeneratorMultipassCB func _generate_pass(voxel_tool: VoxelToolMultipassGenerator, pass_index: int): var min_pos := voxel_tool.get_main_area_min() var max_pos := voxel_tool.get_main_area_max() if pass_index == 0: # Base terrain for gz in range(min_pos.z, max_pos.z): for gx in range(min_pos.x, max_pos.x): # Do things with `voxel_tool` # ... elif pass_index == 1: # Trees # ... Unlike `VoxelGeneratorScript` where `_generate_block` is called once for every 16x16x16 block of the terrain, `_generate_pass` is called multiple times _for every column of blocks_, once for every pass. Subsequent calls can access and modify voxels left by previous passes. Columns may be designated in two different ways in this process: * "Main" column: this is the column being processed by `_generate_pass`. The available area passed with `voxel_tool` will be centered on that column. Usually, if you plant trees, their trunk should only be planted in the main column, to keep results consistent. * "Neighbor" columns: these are around the main column, which also means they will be "seen" by more than one column processing during the same pass. Note Accessing neighbors doesn't mean this generator has access to _voxels of the terrain players have access to_. Internally, the generator has its own separate representation of the world, and only stores blocks that are generating. Columns don't interact with the game, and the game can't interact with them. Note Generator scripts can run directly in the editor with tool mode, **but need extra caution**. For more info, see [tool scripts](https://voxel-tools.readthedocs.io/en/latest/editor/#tool-scripts) . ### Column inter-dependencies[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#column-inter-dependencies "Permanent link") Inter-dependency is a core concept that makes this generator different from the others. It is a direct result of the fact each column can access its neighbors while generating. It is intuitive to do so, but it creates side-effects. #### "Completing" a pass[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#completing-a-pass "Permanent link") Let's say we define 2 passes: * Pass 1: base terrain. Just combinations of Perlin noise and shapes, where it is not necessary to access neighbors. * Pass 2: trees. They could have various shapes and overlap across chunks, and could check if they fit or if they have access to sunlight. That pass will access up to 1 chunk away. With just these two passes, generating one _final_ column requires to process a bunch of other columns: a a a a a a = pass 1 partially affected by b a b b b a b = pass 2 incomplete, partially affected by itself a b B b a B = pass 2 complete a b b b a a a a a a The reason is that in order to _completely finish_ Pass 2 on a specific column, we can't just run it once on that column. We must also do it _on all neighbors that can reach that column_. ![Schema showing a 3x3 grid of chunks. Each chunk gets processed, bringing more trees overlapping other chunks. Once all chunks have generated trees, the middle one can be considered complete.](https://voxel-tools.readthedocs.io/en/latest/images/multipass_tree_inter_dependency.webp) With 3 passes, even more columns have to be partially generated: a a a a a a a a a a = pass 1 partially affected by b a b b b b b b b a b = pass 2 incomplete, partially affected by itself a b B B B B B b a B = pass 2 complete, partially affected by c a b B c c c B b a c = pass 3 incomplete, partially affected by itself a b B c C c B b a C = pass 3 complete a b B c c c B b a a b B B B B B b a a b b b b b b b a a a a a a a a a a The generator does not do all this work from scratch everytime it needs to generate a column. Since columns will have to be re-accessed many times, they are cached in an internal map. Columns get unloaded when far enough from any viewer. This map can be previewed in the editor, when the terrain is present in the edited scene: ![Screenshot of the inspector showing the generator, in which the cache of columns is shown](https://voxel-tools.readthedocs.io/en/latest/images/multipass_cache_viewer.webp) Each pass can be seen as concentric rectangular areas extending _beyond the view distance of the viewer_ (note, you won't see a preview of these passes if your script is not in tool mode. If it is however, take extra caution, see [Editor preview](https://voxel-tools.readthedocs.io/en/latest/editor/#tool-scripts) ). Passes that can access neighbors use two shades of color, where the brighter shade means all neighbors have run the same pass. #### Determinism[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#determinism "Permanent link") A key feature of generators is to be deterministic. Generating the same column again must always give the same result, as long as parameters are the same (position, seed...). However, with multipass, a few factors can break determinism. Column passes are executed in parallel, using multiple threads. Also, players can cause columns to generate from any direction. That means _the order in which columns generate is unpredictable_. Consider neighbor columns `A` and `B`. `A` could generate a tree overlapping into `B`. But `B` can also generate a tree overlapping into `A`. As a result, if the neighbor tree has already been planted, you have to make sure not to erase parts of its trunk, or even leaves if they are different. In this case: * The result might no longer be deterministic, although you could decide it's ok if the differences are acceptable. In some cases results could be the same regardless of order. * Structure generation can be bothered a bit, notably placement checks or trees growing through other structures. You might have to place voxels by choosing which voxel types or areas you can overwrite yourself. ### Limitations[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#limitations "Permanent link") * This kind of generator only works with `VoxelTerrain`, because it is very data-heavy: it is too expensive to run on the fly and directly produce LODs, like simpler single-pass generators can. If LOD has to be supported with a terrain using this generator, it will likely have to work differently and update slower, because it is required to generate the highest level of detail everywhere (i.e Distant Horizons mod in Minecraft). * It is generally more expensive than single-pass generators, and consumes more memory because it needs to cache partially-generated columns in a radius around every player, _beyond their view distances_. It does this to improve performance (which otherwise would be orders of magnitude worse). With a lot of passes or high extents, the amount of memory consumed by this cache could even exceed visible chunks. * Column height is limited for practical reasons. Multipass cubic chunks were experimented with during development of `VoxelGeneratorMultipassCB`, and they were significantly more expensive, and harder to work with in some cases, because of the inability to access a full vertical section (which would have to be infinite). * The reachable distance outside the main column is limited. It can be increased, but it gets expensive quickly. If you need to reach further to place very big structures spanning dozens of chunks across, you might have to think of a different approach. For example, generating a "blueprint" up-front (or deterministically), and rasterizing parts of it progressively when they intersect the column. * The same instance of generator cannot be shared between multiple terrains. If you need the same generator on two terrains, make a copy. * Implementation isn't ideal. `VoxelTerrain` is very generic and works with infinite cubic chunks, while this generator needed different constraints to work well. As a result, there is some overhead that could be avoided if the terrain was entirely rewritten and dedicated to this kind of column structure. It wasn't done because it would become less configurable, break compatibility and take time to develop. * Currently, the column cache isn't saved, contrary to what was described in [issue 545](https://github.com/Zylann/godot_voxel/issues/545) . So if the game restarts, some columns and their neighbors can be asked to generate again if blocks weren't saved in a `VoxelStream`. This can be mitigated by saving generated blocks with `VoxelStream.save_generator_output`. In general, don't expect `VoxelGenerator` to be called only once for a given chunk, because it might be called again in corner cases. Generators should be deterministic and not have race conditions. Modifiers[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#modifiers "Permanent link") -------------------------------------------------------------------------------------------------- Modifiers are generators that affect a limited region of the volume. They can stack on top of base generated voxels or other modifiers, and affect the final result. This is a workflow that mostly serves if your world has a finite size, and you want to set up specific shapes of the landscape in a non-destructive way from the editor. Note This feature is only implemented with `VoxelLodTerrain` at the moment, and only works to sculpt smooth voxels. It is in early stages so it is quite limited. Modifiers can be added with nodes as child of the terrain. `VoxelModifierSphere` adds or subtracts a sphere, while `VoxelModifierMesh` adds or subtracts a mesh. For the latter, the mesh must be baked into an SDF volume first, using the `VoxelMeshSDF` resource. Because modifiers are part of the procedural generation stack, destructive edits will always override them. If a block is edited, modifiers cannot affect it. It is then assumed that such edits would come from players at runtime, and that modifiers don't change. Caching[¶](https://voxel-tools.readthedocs.io/en/latest/generators/#caching "Permanent link") ---------------------------------------------------------------------------------------------- Generators are designed to be deterministic: if the same area is generated twice, the result must be the same. This means, ultimately, we only need to store edited voxels (aka "destructive" editing), while non-edited regions can be recomputed on the fly. Even if you want to access one voxel and it happens to be in a non-edited location, then the generator will be called just to obtain that voxel. However, if a generator is too expensive or not expected to run this way, it may be desirable to store the output in memory so that querying the same area again picks up the cached data. By default, `VoxelTerrain` caches blocks in memory until they get far from any viewer. `VoxelLodTerrain` does not cache blocks by default. There is no option yet to change that behavior. It is also possible to tell a `VoxelGenerator` to save its outputs to the current `VoxelStream`, if any is setup. However, these blocks will act as edited ones, so they will behave as if it was changes done destructively. --- # VoxelGeneratorGraph nodes - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * VoxelGeneratorGraph nodes * * * VoxelGeneratorGraph nodes[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#voxelgeneratorgraph-nodes "Permanent link") =================================================================================================================================== This page lists all nodes that can be used in [VoxelGeneratorGraph](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/) and [VoxelGraphFunction](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/) . Input[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#input "Permanent link") ------------------------------------------------------------------------------------------- ### CustomInput[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#custominput "Permanent link") Outputs: `value` Outputs values from the custom input having the same name as the node. May be used in [VoxelGraphFunction](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/) . It won't be used in [VoxelGeneratorGraph](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/) . ### InputSDF[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#inputsdf "Permanent link") Outputs: `sdf` Outputs the existing signed distance at the current voxel. This may only be used in specific situations, such as using the graph as a procedural brush. ### InputX[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#inputx "Permanent link") Outputs: `x` Outputs the X coordinate of the current voxel. ### InputY[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#inputy "Permanent link") Outputs: `y` Outputs the Y coordinate of the current voxel. ### InputZ[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#inputz "Permanent link") Outputs: `z` Outputs the Z coordinate of the current voxel. Mapping[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#mapping "Permanent link") ----------------------------------------------------------------------------------------------- ### Curve[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#curve "Permanent link") Inputs: `x` Outputs: `out` Parameters: `curve` Returns the value of a custom `curve` at coordinate `x`, where `x` is in the range `[0..1]`. The `curve` is specified with a [Curve](https://docs.godotengine.org/en/stable/classes/class_curve.html) resource. ### Image[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#image "Permanent link") Inputs: `x`, `y` Outputs: `out` Parameters: `image` Returns the value of the red channel of an image at coordinates `(x, y)`, where `x` and `y` are in pixels and the return value is in the range `[0..1]` (or more if the image has an HDR format). If coordinates are outside the image, they will be wrapped around. No filtering is performed. The image must have an uncompressed format. Math[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#math "Permanent link") ----------------------------------------------------------------------------------------- ### Abs[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#abs "Permanent link") Inputs: `x` Outputs: `out` If `x` is negative, returns `x` as a positive number. Otherwise, returns `x`. ### Clamp[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#clamp "Permanent link") Inputs: `x`, `min`, `max` Outputs: `out` If `x` is lower than `min`, returns `min`. If `x` is higher than `max`, returns `max`. Otherwise, returns `x`. ### ClampC[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#clampc "Permanent link") Inputs: `x` Outputs: `out` Parameters: `min`, `max` If `x` is lower than `min`, returns `min`. If `x` is higher than `max`, returns `max`. Otherwise, returns `x`. This node is an alternative to `Clamp`, used internally as an optimization if `min` and `max` are constant. ### Expression[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#expression "Permanent link") Outputs: `out` Parameters: `expression` Evaluates a math expression. Variable names can be written as inputs of the node. Some functions can be used, but they must be supported graph nodes in the first place, as the expression will be converted to nodes internally. Available functions: sin(x) floor(x) abs(x) sqrt(x) fract(x) stepify(x, step) wrap(x, length) min(a, b) max(a, b) clamp(x, min, max) lerp(a, b, ratio) ### Floor[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#floor "Permanent link") Inputs: `x` Outputs: `out` Returns the result of `floor(x)`, the nearest integer that is equal or lower to `x`. ### Fract[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#fract "Permanent link") Inputs: `x` Outputs: `out` Returns the decimal part of `x`. The result is always positive regardless of sign. ### Max[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#max "Permanent link") Inputs: `a`, `b` Outputs: `out` Returns the highest value between `a` and `b`. ### Min[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#min "Permanent link") Inputs: `a`, `b` Outputs: `out` Returns the lowest value between `a` and `b`. ### Mix[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#mix "Permanent link") Inputs: `a`, `b`, `ratio` Outputs: `out` Interpolates between `a` and `b`, using parameter value `t`. If `t` is `0`, `a` will be returned. If `t` is `1`, `b` will be returned. If `t` is beyond the `[0..1]` range, the returned value will be an extrapolation. ### Pow[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#pow "Permanent link") Inputs: `x`, `p` Outputs: `out` Returns the result of the power function (`x ^ power`). It can be relatively slow. ### Powi[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#powi "Permanent link") Inputs: `x` Outputs: `out` Parameters: `power` Returns the result of the power function (`x ^ power`), where the exponent is a constant positive integer. May be faster than `Pow`. ### Remap[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#remap "Permanent link") Inputs: `x` Outputs: `out` Parameters: `min0`, `max0`, `min1`, `max1` For an input value `x` in the range `[min0, max0]`, converts linearly into the `[min1, max1]` range. For example, if `x` is `min0`, then `min1` will be returned. If `x` is `max0`, then `max1` will be returned. If `x` is beyond the `[min0, max0]` range, the result will be an extrapolation. ### Select[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#select "Permanent link") Inputs: `a`, `b`, `t` Outputs: `out` Parameters: `threshold` If `t` is lower than `threshold`, returns `a`. Otherwise, returns `b`. ### Sin[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#sin "Permanent link") Inputs: `x` Outputs: `out` Returns the result of `sin(x)` ### Smoothstep[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#smoothstep "Permanent link") Inputs: `x` Outputs: `out` Parameters: `edge0`, `edge1` Returns the result of smoothly interpolating the value of `x` between `0` and `1`, based on the where `x` lies with respect to the edges `egde0` and `edge1`. The return value is `0` if `x <= edge0`, and `1` if `x >= edge1`. If `x` lies between `edge0` and `edge1`, the returned value follows an S-shaped curve that maps `x` between `0` and `1`. This S-shaped curve is the cubic Hermite interpolator, given by `f(y) = 3*y^2 - 2*y^3` where `y = (x-edge0) / (edge1-edge0)`. ### Sqrt[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#sqrt "Permanent link") Inputs: `x` Outputs: `out` Returns the square root of `x`. Note: unlike classic square root, if `x` is negative, this function returns `0` instead of `NaN`. ### Stepify[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#stepify "Permanent link") Inputs: `x`, `step` Outputs: `out` Snaps `x` to a given step, similar to GDScript's function `stepify`. ### Wrap[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#wrap "Permanent link") Inputs: `x`, `length` Outputs: `out` Wraps `x` between `0` and `length`, similar to GDScript's function `wrapf(x, 0, max)`. Note: if `length` is 0, this node will return `NaN`. If it happens, it should not crash, but results will be messed up. Misc[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#misc "Permanent link") ----------------------------------------------------------------------------------------- ### Comment[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#comment "Permanent link") Parameters: `text` A rectangular area with a description, to help organizing a graph. ### Constant[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#constant "Permanent link") Outputs: `value` Parameters: `value` Outputs a constant number. ### Function[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#function "Permanent link") Parameters: `_function` Runs a custom function, like a re-usable sub-graph. The first parameter (parameter 0) of this node is a reference to a [VoxelGraphFunction](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/) . Further parameters (starting from 1) are those exposed by the function. ### Relay[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#relay "Permanent link") Inputs: `in` Outputs: `out` Pass-through node, allowing to better organize the path of long connections. Noise[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#noise "Permanent link") ------------------------------------------------------------------------------------------- ### FastNoise2D[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#fastnoise2d "Permanent link") Inputs: `x`, `y` Outputs: `out` Parameters: `noise` Returns computation of 2D noise at coordinates `(x, y)` using the FastNoiseLite library. The `noise` parameter is specified with an instance of the [ZN\_FastNoiseLite](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/) resource. Note: this node might be a little faster than `Noise2D`. ### FastNoise2\_2D[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#fastnoise2_2d "Permanent link") Inputs: `x`, `y` Outputs: `out` Parameters: `noise` Returns computation of 2D SIMD noise at coordinates `(x, y)` using the FastNoise2 library. The `noise` parameter is specified with an instance of the [FastNoise2](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/) resource. This is the fastest noise currently supported. ### FastNoise2\_3D[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#fastnoise2_3d "Permanent link") Inputs: `x`, `y`, `z` Outputs: `out` Parameters: `noise` Returns computation of 3D SIMD noise at coordinates `(x, y, z)` using the FastNoise2 library. The `noise` parameter is specified with an instance of the [FastNoise2](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/) resource. This is the fastest noise currently supported. ### FastNoise3D[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#fastnoise3d "Permanent link") Inputs: `x`, `y`, `z` Outputs: `out` Parameters: `noise` Returns computation of 3D noise at coordinates `(x, y, z)` using the FastNoiseLite library. The `noise` parameter is specified with an instance of the [ZN\_FastNoiseLite](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/) resource. Note: this node might be a little faster than `Noise3D`. ### FastNoiseGradient2D[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#fastnoisegradient2d "Permanent link") Inputs: `x`, `y` Outputs: `out_x`, `out_y` Parameters: `noise` Warps 2D coordinates `(x, y)` using a noise gradient from the FastNoiseLite library. The `noise` parameter is specified with an instance of the [FastNoiseLiteGradient](https://docs.godotengine.org/en/stable/classes/class_fastnoiselitegradient.html) resource. ### FastNoiseGradient3D[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#fastnoisegradient3d "Permanent link") Inputs: `x`, `y`, `z` Outputs: `out_x`, `out_y`, `out_z` Parameters: `noise` Warps 3D coordinates `(x, y, z)` using a noise gradient from the FastNoiseLite library. The `noise` parameter is specified with an instance of the [FastNoiseLiteGradient](https://docs.godotengine.org/en/stable/classes/class_fastnoiselitegradient.html) resource. ### Noise2D[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#noise2d "Permanent link") Inputs: `x`, `y` Outputs: `out` Parameters: `noise` Returns 2D noise at coordinates `(x, y)` using one of the [Noise](https://docs.godotengine.org/en/stable/classes/class_noise.html) subclasses provided by Godot. ### Noise3D[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#noise3d "Permanent link") Inputs: `x`, `y`, `z` Outputs: `out` Parameters: `noise` Returns 3D noise at coordinates `(x, y, z)` using one of the [Noise](https://docs.godotengine.org/en/stable/classes/class_noise.html) subclasses provided by Godot. ### Spots2D[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#spots2d "Permanent link") Inputs: `x`, `y`, `spot_radius` Outputs: `out` Parameters: `seed`, `cell_size`, `jitter` Cellular noise optimized for "ore patch" generation: divides space into a 2D grid where each cell contains a circular "spot". Returns 1 when the position is inside the spot, 0 otherwise. `jitter` more or less randomizes the position of the spot inside each cell. Limitation: high jitter can make spots clip with cell borders. This is intentional. If you need more generic cellular noise, use another node. ### Spots3D[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#spots3d "Permanent link") Inputs: `x`, `y`, `z`, `spot_radius` Outputs: `out` Parameters: `seed`, `cell_size`, `jitter` Cellular noise optimized for "ore patch" generation: divides space into a 3D grid where each cell contains a circular "spot". Returns 1 when the position is inside the spot, 0 otherwise. `jitter` more or less randomizes the position of the spot inside each cell. Limitation: high jitter can make spots clip with cell borders. This is intentional. If you need more generic cellular noise, use another node. Ops[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#ops "Permanent link") --------------------------------------------------------------------------------------- ### Add[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#add "Permanent link") Inputs: `a`, `b` Outputs: `out` Returns the sum of `a` and `b` ### Divide[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#divide "Permanent link") Inputs: `a`, `b` Outputs: `out` Returns the result of `a / b`. Note: dividing by zero outputs NaN. It should not cause crashes, but will likely mess up results. Consider using Multiply when possible. ### Multiply[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#multiply "Permanent link") Inputs: `a`, `b` Outputs: `out` Returns the result of `a * b`. ### Subtract[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#subtract "Permanent link") Inputs: `a`, `b` Outputs: `out` Returns the result of `a - b` Output[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#output "Permanent link") --------------------------------------------------------------------------------------------- ### CustomOutput[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#customoutput "Permanent link") Inputs: `value` Sets the value of the custom output having the same name as the node. May be used in [VoxelGraphFunction](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/) . It won't be used in [VoxelGeneratorGraph](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/) . ### OutputSDF[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#outputsdf "Permanent link") Inputs: `sdf` Sets the Signed Distance Field value of the current voxel. ### OutputSingleTexture[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#outputsingletexture "Permanent link") Inputs: `index` Sets the texture index of the current voxel. This is an alternative to using `OutputWeight` nodes, if your voxels only have one texture. This is easier to use but does not allow for long gradients. Using this node in combination with `OutputWeight` is not supported. ### OutputType[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#outputtype "Permanent link") Inputs: `type` Sets the TYPE index of the current voxel. This is for use with [VoxelMesherBlocky](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/) . If you use this output, you don't need to use `OutputSDF`. ### OutputWeight[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#outputweight "Permanent link") Inputs: `weight` Parameters: `layer` Sets the value of a specific texture weight for the current voxel. The texture is specified as an index with the `layer` parameter. There can only be one output using a given layer index. SDF[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#sdf "Permanent link") --------------------------------------------------------------------------------------- ### SdfBox[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#sdfbox "Permanent link") Inputs: `x`, `y`, `z` Outputs: `sdf` Parameters: `size_x`, `size_y`, `size_z` Returns the signed distance field of an axis-aligned box centered at the origin, of size `(size_x, size_y, size_z)`, at coordinates `(x, y, z)`. ### SdfPlane[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#sdfplane "Permanent link") Inputs: `y`, `height` Outputs: `sdf` Returns the signed distance field of a plane facing the Y axis located at a given `height`, at coordinate `y`. ### SdfPreview[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#sdfpreview "Permanent link") Inputs: `value` Parameters: `min_value`, `max_value`, `fraction_period`, `mode` Debug node, not used in the final result. In the editor, shows a slice of the values emitted from the output it is connected to, according to boundary `[min_value, max_value]`. The slice will be either along the XY plane or the XZ plane, depending on current settings. ### SdfSmoothSubtract[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#sdfsmoothsubtract "Permanent link") Inputs: `a`, `b` Outputs: `sdf` Parameters: `smoothness` Subtracts signed distance field `b` from `a`, using the same smoothing as with the `SdfSmoothUnion` node. ### SdfSmoothUnion[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#sdfsmoothunion "Permanent link") Inputs: `a`, `b` Outputs: `sdf` Parameters: `smoothness` Returns the smooth union of two signed distance field values `a` and `b`. Smoothness is controlled with the `smoothness` parameter. Higher smoothness will create a larger "weld" between the shapes formed by the two inputs. ### SdfSphere[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#sdfsphere "Permanent link") Inputs: `x`, `y`, `z` Outputs: `sdf` Parameters: `radius` Returns the signed distance field of a sphere centered at the origin, of given `radius`, at coordinates `(x, y, z)`. ### SdfSphereHeightmap[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#sdfsphereheightmap "Permanent link") Inputs: `x`, `y`, `z` Outputs: `sdf` Parameters: `image`, `radius`, `factor` Returns an approximation of the signed distance field of a spherical heightmap, at coordinates `(x, y, z)`. The heightmap is an `image` using panoramic projection, similar to those used for environment sky in Godot. The radius of the sphere is specified with `radius`. The heights from the heightmap can be scaled using the `factor` parameter. The image must use an uncompressed format. ### SdfTorus[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#sdftorus "Permanent link") Inputs: `x`, `y`, `z` Outputs: `sdf` Parameters: `radius1`, `radius2` Returns the signed distance field of a torus centered at the origin, facing the Y axis, at coordinates `(x, y, z)`. The radius of the ring is `radius1`, and its thickness is `radius2`. Vector[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#vector "Permanent link") --------------------------------------------------------------------------------------------- ### Distance2D[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#distance2d "Permanent link") Inputs: `x0`, `y0`, `x1`, `y1` Outputs: `out` Returns the distance between two 2D points `(x0, y0)` and `(x1, y1)`. ### Distance3D[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#distance3d "Permanent link") Inputs: `x0`, `y0`, `z0`, `x1`, `y1`, `z1` Outputs: `out` Returns the distance between two 3D points `(x0, y0, z0)` and `(x1, y1, z1)`. ### Normalize[¶](https://voxel-tools.readthedocs.io/en/latest/graph_nodes/#normalize "Permanent link") Inputs: `x`, `y`, `z` Outputs: `nx`, `ny`, `nz`, `len` Returns the normalized coordinates of the given `(x, y, z)` 3D vector, such that the length of the output vector is 1. --- # Navigation - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Navigation * * * Navigation[¶](https://voxel-tools.readthedocs.io/en/latest/navigation/#navigation "Permanent link") ==================================================================================================== AI navigation can be implemented in different ways, but currently there is no general solution for dynamic voxel terrain. Warning Most of what is described on this page is experimental. You may either try one of the approaches described, modify it, or roll your own. Grid-based pathfinding[¶](https://voxel-tools.readthedocs.io/en/latest/navigation/#grid-based-pathfinding "Permanent link") ---------------------------------------------------------------------------------------------------------------------------- Voxels can be interpreted as a grid to do pathfinding on directly. This may be suitable for blocky voxels. You can implement your own logic this way, or you can use [VoxelAStarGrid3D](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/) . This has a relatively limited range and only works well with "character" agents that are 1x2 voxels in size. Waypoint-based pathfinding[¶](https://voxel-tools.readthedocs.io/en/latest/navigation/#waypoint-based-pathfinding "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ You can use Godot's `AStar3D` class to dyamically/progressively scatter loose waypoints through the world using a script, and connect them up. Doing raycasts or shape casts can help determining if a location is walkable or not. Agents may then complete this information by steering based on their immediate surroundings. This might be one of the cheapest options, though it is probably less accurate depending on how it's implemented. Navmesh-based navigation[¶](https://voxel-tools.readthedocs.io/en/latest/navigation/#navmesh-based-navigation "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- Godot's general-purpose 3D [navigation system](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_introduction_3d.html) requires the use of `NavigationMesh` and `NavigationRegion3D`. However, there is currently no support for it out of the box. A particular challenge in building navmeshes for voxel terrain, is the fact it can't be tweaked and baked perfectly like most terrains that are created by developers in the editor. Navmeshes are sensitive to the source geometry thrown at them. Voxel terrain is streamed, can be modified by players, and could have the most unforgiving variations of shapes in any direction, so it is a hard requirement for navigation to not break in-game. Even just the most basic noise-based terrain [can raise errors in Godot's baking process](https://github.com/godotengine/godot/issues/85548#issuecomment-2021774612) , and produce navmeshes that can be expensive to traverse. In addition, any edit or streaming event requires to constantly re-bake navmeshes to match the areas players are in. Obstacles on top of the terrain must also be taken into account, as well as the fact agents have a size that could cross chunks. Multiple agent sizes also require multiple navmeshes. ![Screenshot of blobby smooth voxel terrain on top of which a complex navmesh has been generated](https://voxel-tools.readthedocs.io/en/latest/images/navmesh_bumpy_noise_terrain.webp) On top of this, Godot's navigation system has limitations that make it difficult to bake navmeshes at runtime while avoiding CPU stutters. The baking process can be threaded relatively easily by conforming to strict scene parsing rules (the scene tree is not thread-safe). However, Godot still runs a lot of logic after that _on the main thread_, and that logic can badly affect framerate on a large scale. It is also hard to support planets because it assumes the world is flat. The `navigation` branch of the module attempts to implement a dynamic navmesh system, however it has performance issues and isn't ready for production. At time of writing, it is not actively developped (subject to change, eventually). You may check it out and tweak it for your needs if you want to use it. See also [issue 610](https://github.com/Zylann/godot_voxel/issues/610) . --- # Multiplayer - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Multiplayer * * * Multiplayer[¶](https://voxel-tools.readthedocs.io/en/latest/multiplayer/#multiplayer "Permanent link") ======================================================================================================= Multiplayer in a voxel game can be implemented with lots of different details. Not all the features of the engine are supported, it is still very experimental and might change in the future. So how to setup multiplayer is explained in sections with a date, based on last experiments. The most recent one will often relate to a new/better/simpler way, and old ones might eventually be removed. Note This page assumes you already have knowledge in general multiplayer programming. It is strongly recommended you learn it beforehand. You can have a look at [Godot's documentation page about networking](https://docs.godotengine.org/en/stable/tutorials/networking/index.html) . 2023/04/13 - Server-side viewer with `VoxelTerrain` and `VoxelNetworkTerrain*` nodes[¶](https://voxel-tools.readthedocs.io/en/latest/multiplayer/#20230413-server-side-viewer-with-voxelterrain-and-voxelnetworkterrain-nodes "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ This is a new iteration over the previous method, based on the same principle, but integrating it to the engine with some speed improvements. The server will be authoritative, and the client just receives information from it. Client and server will need a different setup. This will rely on Godot's high-level multiplayer API, using RPCs. It is important for a client or server to be setup before the terrain starts processing. This can be done before adding the game world to the tree, or initializing multiplayer in `_ready`. ### On the server[¶](https://voxel-tools.readthedocs.io/en/latest/multiplayer/#on-the-server "Permanent link") * Add `VoxelTerrain` to your scene. * Add a `VoxelTerrainMultiplayerSynchronizer` node as child of your `VoxelTerrain`. * When a player joins, make sure a `VoxelViewer` is created for it. Assign its `network_peer_id` and enable `requires_data_block_notifications`. You may also want to turn off `require_visuals` on viewers representing remote players, since it's normally not necessary to render their surroundings. ### On the client[¶](https://voxel-tools.readthedocs.io/en/latest/multiplayer/#on-the-client "Permanent link") * Add `VoxelTerrain` to your scene. * Add `VoxelTerrainMultiplayerSynchronizer` node as child of the `VoxelTerrain`. Make sure it has the same name as its server equivalent. * The client will still need a `VoxelViewer`, which will allow the terrain to detect when it can unload voxel data (the server does not send that information). To reduce the likelihood of "holes" in the terrain if blocks get unloaded too soon, you may give the `VoxelViewer` a slightly larger view distance than the server. * The client can have remote players synchronized so the player can see them, but you should not add a `VoxelViewer` to them (only the server does). The client should not have to stream terrain for remote players, it only has one for the local player. 2022/01/31 - Server-side viewer with `VoxelTerrain` and some scripting[¶](https://voxel-tools.readthedocs.io/en/latest/multiplayer/#20220131-server-side-viewer-with-voxelterrain-and-some-scripting "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This was the first iteration of support function allowing to implement multiplayer. The idea is for the server to be authoritative, and the client just receives information from it. `VoxelTerrain` has a `Networking` category in the inspector. These properties are not necessarily specific to multiplayer, but were actually added to experiment with it, so they are grouped together. Client and server will need a different setup. ### On the server[¶](https://voxel-tools.readthedocs.io/en/latest/multiplayer/#on-the-server_1 "Permanent link") * Configure `VoxelTerrain` as normal, with a generator and maybe a stream. * On `VoxelTerrain`, Enable `block_enter_notification_enabled` * Add a script to `VoxelTerrain` implementing `func _on_data_block_entered(info)`. This function will be called each time a new voxel block enters a remote player's area. This will be a place where you may send the block to the client. You can use `VoxelBlockSerializer` to pack voxel data into bytes. The `info.are_voxels_edited()` boolean can tell if the block was ever edited: if it wasn't, you can avoid sending the whole data and just tell the client to generate the block locally. * When a player joins, make sure a `VoxelViewer` is created for it, assign its `network_peer_id` and enable `requires_data_block_notifications`. This will make the terrain load blocks around it and notify when blocks need to be sent to the peer. * On `VoxelTerrain`, enable `area_edit_notification_enabled` * In your `VoxelTerrain` script, implement `func _on_area_edited(origin, size)`. This function will be called each time voxels are edited within a bounding box. Voxels inside may have to be sent to all players close enough. You can get a list of network peer IDs by calling `get_viewer_network_peer_ids_in_area(origin, size)`. ### On the client[¶](https://voxel-tools.readthedocs.io/en/latest/multiplayer/#on-the-client_1 "Permanent link") * Configure `VoxelTerrain` with a mesher and maybe a generator, and turn off `automatic_loading_enabled`. Voxels will only load based on what the server sends. * Add a script handling network messages. When a block is received from the server, store it inside `VoxelTerrain` by using the `try_set_block_data` function. * When a box of edited voxels is received from the server, you may use a `VoxelTool` and the `paste` function to replace the edited voxels. If you want the client to generate the block locally, you could use the generator to make one with `generate_block_async()`. If you use asynchronous generation, note that blocks written with `try_set_block_data` will cancel blocks that are loading. That means if a client receives an edited block in the meantime, the generating block won't overwrite it. * The client will still need a `VoxelViewer`, which will allow the terrain to detect when it can unload voxel data (the server does not send that information). To reduce the likelihood of "holes" in the terrain if blocks get unloaded too soon, you may give the `VoxelViewer` a larger view distance than the server. * The client can have remote players synchronized so the player can see them, but you should not add a `VoxelViewer` to them (only the server does). The client should not have to stream terrain for remote players, it only has one for the local player. With `VoxelLodTerrain`[¶](https://voxel-tools.readthedocs.io/en/latest/multiplayer/#with-voxellodterrain "Permanent link") --------------------------------------------------------------------------------------------------------------------------- There is no support for now, but it is planned. Protocol notes[¶](https://voxel-tools.readthedocs.io/en/latest/multiplayer/#protocol-notes "Permanent link") ------------------------------------------------------------------------------------------------------------- RPCs in Godot use UDP (reliable or unreliable), so sending large amounts of voxels to clients could have limited speed. Instead, it would be an option to use TCP to send blocks instead, as well as large edits. Small edits or deterministic edits with ligthweight info could keep using reliable UDP. Problem: you would have to use two ports, one for UDP, one for TCP. So maybe it is a better idea to keep using reliable UDP. Note: Minecraft's network protocol is entirely built on top of TCP. Other points to explore[¶](https://voxel-tools.readthedocs.io/en/latest/multiplayer/#other-points-to-explore "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- * Block caching and versionning: save blocks client-side so the server doesn't have to send them again next time if they didn't change * Client-requesting alternative model: having the client actively request blocks with custom code instead of passively receiving them from the server * Block diffing: if it is acceptable for clients to know the world seed, instead of expecting clients to cache data (which requires the server to know what the client knows), store a diff map in voxel data server-side, 1-bit per voxel. Then if less than 30% of a block has changed, send only the difference and let the client fill the gaps. --- # Overview - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Overview * * * Overview[¶](https://voxel-tools.readthedocs.io/en/latest/overview/#overview "Permanent link") ============================================================================================== This section explains the main concepts used in this voxel engine and which parts implement them. What voxels are[¶](https://voxel-tools.readthedocs.io/en/latest/overview/#what-voxels-are "Permanent link") ------------------------------------------------------------------------------------------------------------ ![Cubes and marching cubes](https://voxel-tools.readthedocs.io/en/latest/images/cubes_and_marching_cubes.webp) "Voxel" is short for "volumetric picture element", similar to "pixel" which means "picture element". They compose volumes, as opposed to simple 2D images, which allows to make 3D terrains or models in 3 dimensions. Instead of representing solely the surface of objects like classic polygon-based models do, they also represent the insides as well, in every point of space. In this engine, a voxel is a specific point in space holding some values. Those values can be: * The type of the voxel * Its density (or Signed Distance) * Its color * Its material * Etc... Voxels can be obtained by either deciding their values manually on a grid, or by defining procedural rules to generate them from anywhere, like fractal noise or Signed-Distance-Field formulas. Note Although this engine started as a way to generate terrains, it is not the only thing you can do with it. Because of this, you will often find the word "volume" instead of "terrain" in this documentation, to designate objects composed of voxels. Generating voxels[¶](https://voxel-tools.readthedocs.io/en/latest/overview/#generating-voxels "Permanent link") ---------------------------------------------------------------------------------------------------------------- Voxels span 3 dimensions, so contrary to images, storing them can take up way more memory as volumes get bigger. This is why it important to think about procedural sources of voxels, because they don't cost any memory and can be accessed at any resolution. This task is implemented by resources deriving [VoxelGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/) . Their goal is to generate voxel data, either at a specific point in space, or in a whole defined volume. There are endless possible recipes to generate models, terrains or planets, which we won't detail in this section. Types of generators include: * [VoxelGeneratorNoise2D](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise2D/) : generates a heightmap using 2D fractal noise * [VoxelGeneratorNoise](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise/) : generates a "spongy" world using 3D noise to form large caves and overhangs, modified so that most of the terrain is downwards and becomes only air above some altitude * [VoxelGeneratorFlat](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorFlat/) : generates a simple flat plane. * [VoxelGeneratorGraph](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/) : allows to combine all sorts of operations using a graph (like a 3D VisualShader) to produce the volume with more flexibility than the other simple generators * [VoxelGeneratorScript](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorScript/) : allows to implement the generation logic with a script. Will likely be slower than the other options, unless you use C# or GDExtension. * And some others Storing voxels[¶](https://voxel-tools.readthedocs.io/en/latest/overview/#storing-voxels "Permanent link") ---------------------------------------------------------------------------------------------------------- ![Block map storage schema](https://voxel-tools.readthedocs.io/en/latest/images/block_map_storage.webp) Even if it needs lots of memory, we still have to store voxel data at some point. This is important for passing voxels around, storing player edits which cannot be reproduced with a generator, or saving terrains to disk. The core class for doing this is [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) . This is a simple grid data structure with configurable format. You might not have to use this class often, but its storage concept is useful to know in order to use other APIs like [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) . Voxels can hold various kinds of values, so this object uses multiple channels, each of them being one type of information: * `TYPE`: The type of voxel, mainly used to associate the voxel with a type of model like in Minecraft. This is very similar to tile IDs seen in tilemaps or gridmaps. * `SDF`: The Signed Distance Field value, used for smooth voxels. It tells how far from the surface the voxel is. This can be understood like a density of matter, where negative values mean "matter" (distance below surface), and positive values mean "air" (distance above surface). * `COLOR`: Color information. It can either be compressed RGBA, or an index into a palette of colors. * And others. The engine uses the first channels, while others are unused for now. Each channel can also use a configurable bit depth: 8, 16, 32 or 64 bits. This allows to tune quality and memory usage depending on your needs. Finally, a simple optimization is applied so that if a channel is filled with the same value, it won't allocate memory and instead store just that value. This way, areas such as the sky don't take up memory. Saving voxels to disk[¶](https://voxel-tools.readthedocs.io/en/latest/overview/#saving-voxels-to-disk "Permanent link") ------------------------------------------------------------------------------------------------------------------------ ![Raw region file seen as an image](https://voxel-tools.readthedocs.io/en/latest/images/region_file_seen_as_image.png) When players make edits to the world or when you want to sculpt a terrain in the editor and keep your changes saved, it becomes necessary to save voxels to disk. This module implements this functionality with [VoxelStream](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/) . Similarly to generators, a stream allows to request blocks of voxels so that it's not necessary to load the entire thing at once. But also, it allows to send back blocks of voxels to save them. This block-based approach is especially useful if the world is very large. In contrast, smaller volumes might just be loaded all at once. Subclasses may implement it in various ways, often using compressed files. Turning voxels into meshes[¶](https://voxel-tools.readthedocs.io/en/latest/overview/#turning-voxels-into-meshes "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------- ![Cubes and wireframe](https://voxel-tools.readthedocs.io/en/latest/images/cubes_and_wireframe.webp) Today's graphics cards are getting more and more powerful, but in average, polygons (meshes) remain the fastest way to render 3D models. So we are not really going to directly draw voxels. Instead, we have to convert them into polygons, which will then be rendered. To do this, this engine uses a resource called [VoxelMesher](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/) . There are several ways to produce polygons from voxel data, and the engine provides types of meshers to do it: * [VoxelMesherCubes](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/) : the color of voxels is used to produce colored cubes. This is the simplest way to polygonize voxels. * [VoxelMesherBlocky](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/) : the type of voxels is used to batch together meshes corresponding to that type. This can also use cubes, but any shape will do if custom meshes are provided. This is a similar technique as the one used in Minecraft, and has a wide range of options. * [VoxelMesherTransvoxel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/) : instead of making cubes, this one uses the SDF value to produce a smooth surface, based on the [Transvoxel](https://transvoxel.org/) algorithm. It can also produce transition meshes, which is useful to stitch together two meshes of different level of detail. Putting it together with nodes[¶](https://voxel-tools.readthedocs.io/en/latest/overview/#putting-it-together-with-nodes "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------ ![Game screenshots](https://voxel-tools.readthedocs.io/en/latest/images/game_examples.webp) So far, we could consider that there are enough tools to use voxels within games. It's a bit more work to take it from there, though. Turning a bunch of voxels into a mesh is ok for a model or a small piece of land, however it won't scale well with large editable terrains. It gets more tricky if that terrain needs to have a large view distance. Very often, the proposed solution is to split it into chunks, eventually using variable level of detail, and properly update parts of that terrain when they are modified by players. This is what the `VoxelTerrain*` nodes do, by putting together the tools seen before, and using threads to run heavy operations in the background. Note In this engine, "Chunks" are actually called "Blocks". They typically represent cubes of 16x16x16 voxels. Some options are specified in blocks, rather than spatial units. ### Terrain types[¶](https://voxel-tools.readthedocs.io/en/latest/overview/#terrain-types "Permanent link") There are two main types of terrains supported by the engine. They have a lot in common, but also handle blocks in a very different way. * [VoxelTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/) : this one uses a simple grid of blocks, and takes care of loading and unloading blocks as the viewer moves around. Its view distance is limited in similar ways to Minecraft, so it is better used with blocky voxels or moderate-size smooth volumes. * [VoxelLodTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/) : this one uses an octree of blocks. Contrary to a simple grid, this allows to store voxels at multiple levels of detail, allowing to render much larger distances. It currently works a bit differently compared to the other. Both kinds of terrains can be edited in real time, and only the edited parts will be re-meshed dynamically. A helper class [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) is exposed to the script API to simplify the process of editing voxels, which can be obtained by using `get_voxel_tool()` methods. It allows to set single voxels, dig around or blend simple shapes such as spheres or boxes. The same concept of channels seen earlier is available on this API, so depending on the type of mesher you are using, you may want to edit either `TYPE`, `SDF` or `COLOR` channels. Finally, for these terrains to load, it is required to place at least one [VoxelViewer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/) node in the world. These may be placed typically as child of the player, or the main `Camera3D`. They tell the voxel engine where to load voxels, how far, and give priority to mesh updates happening near them. ### Common properties[¶](https://voxel-tools.readthedocs.io/en/latest/overview/#common-properties "Permanent link") #### Voxel properties[¶](https://voxel-tools.readthedocs.io/en/latest/overview/#voxel-properties "Permanent link") Each voxel node inherits `VoxelNode`, which defines properties they all have in common. * `stream`: a `VoxelStream` resource, which allows to load and save voxels. See [Voxel Streams](https://voxel-tools.readthedocs.io/en/latest/streams/) * `generator`: a `VoxelGenerator` resource, which allows to populate the volume with generated voxels. See [Generators](https://voxel-tools.readthedocs.io/en/latest/generators/) * `mesher`: a `VoxelMesher` resource, which defines how the voxels will look like. It also defines collision meshes if enabled. #### Collisions[¶](https://voxel-tools.readthedocs.io/en/latest/overview/#collisions "Permanent link") Physics based collisions are enabled by default, and behave like a static body. It provides both raycasting and collision detection. You can turn it on or off by setting the `generate_collisions` option on any of the terrain nodes. Or you can enable or disable it in code. The collision is built along with the mesh. So any blocks that have already been built will not be affected by this setting unless they are regenerated. You can also turn on the collision wire mesh for debugging. In the editor, look under the Debug menu for `Visible Collision Shapes`. ![Collision shapes](https://voxel-tools.readthedocs.io/en/latest/images/debug-collision-shapes.gif) --- # Procedural generation - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Procedural generation * * * Procedural generation[¶](https://voxel-tools.readthedocs.io/en/latest/procedural_generation/#procedural-generation "Permanent link") ===================================================================================================================================== This section describes techniques involved in procedural generation of terrains. Some are experimental and may be adjusted. Articles will either use graphs or scripts, and can be more advanced than other sections of the documentation, so you should first get familiar with the API. Caves with graph generator[¶](https://voxel-tools.readthedocs.io/en/latest/procedural_generation/#caves-with-graph-generator "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------- It is possible to generate caves by subtracting noise "worms" from a base SDF terrain. To simplify the approach, let's first look at what 2D noise looks like, with a few octaves: ![Noise](https://voxel-tools.readthedocs.io/en/latest/images/noise.webp) If we multiply that noise by itself (i.e square it), we obtain this: ![Squared noise](https://voxel-tools.readthedocs.io/en/latest/images/squared_noise.webp) And if we clamp it to highlight values below a threshold close to zero, we can notice a path-like pattern going on: ![Squared noise path highlight](https://voxel-tools.readthedocs.io/en/latest/images/squared_noise_with_highlight.webp) In 2D (or in 3D when using normalized coordinates) this is the key to produce rivers, or ravines. But the problem with caves is to obtain 3D, round-shaped "worms", not just 2D shapes. So we can cheat a little, by still using 2D noise, but instead we modulate the threshold along the Y axis. We need a parabola-shaped curve for this, which can be obtained with a second-degree polynome like `y^2 - 1`: ![Cave threshold modulation](https://voxel-tools.readthedocs.io/en/latest/images/cave_threshold_modulation.webp) Back to the voxel graph, we may connect directly the cave generation nodes to the output just to preview what they look like, without the rest of the terrain: ![Cave voxel graph](https://voxel-tools.readthedocs.io/en/latest/images/caves_flat.webp) After tweaking noise and other values, we obtain those famous worms, but there are two problems: * The caves are still flat, they don't go up or down * They go on endlessly, there are no dead-ends We can fix the first problem by adding an extra layer of 2D noise to the Y coordinate so it can perturb the caves vertically. Re-using the ground surface noise with an extra multiplier can prove effective sometimes, so we avoid computing extra noise. ![Caves perturb](https://voxel-tools.readthedocs.io/en/latest/images/caves_perturb.webp) The second problem can also be fixed with yet another layer of low-frequency noise, which can be added to the cave threshold so caves will shrink to become dead-ends on some regions. Again, adding multipliers may change how sharply that transition occurs. ![Cave voxel graph perturb and modulated](https://voxel-tools.readthedocs.io/en/latest/images/caves_perturb_modulated.webp) Finally, we can blend our terrain with caves by subtracting them. This can be done with the `SdfSmoothSubtract` node, essentially doing `terrain - caves`. ![Cave voxel graph terrain subtract](https://voxel-tools.readthedocs.io/en/latest/images/caves_composed.webp) There are likely variants of this to obtain different results. Handling block boundaries with voxel structures[¶](https://voxel-tools.readthedocs.io/en/latest/procedural_generation/#handling-block-boundaries-with-voxel-structures "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In Minecraft-style terrain, a very common problem that arises once base terrain is generated, is how to plant trees in it, because such structures would be voxels too. In that specific case, there are a number of caveats when doing that with generators, which mainly revolve about the fact they process chunks one by one, and not the entire world at once. There are several ways to deal with this: * Exploit procedural determinism to "guess" where trees would grow in neighbor chunks, without having to generate entire neighbor chunks * Split generation in multiple passes and provide access to neighbor chunks that have gone through previous passes The following describes the first method, which does not involve accessing neighbors at all, and allows to generate trees in a terrain where the base height is both deterministic and easy to compute (2D noise heightmap for example). If you want to use the second method, you may check [multipass generators](https://voxel-tools.readthedocs.io/en/latest/generators/#multi-pass-generation-with-voxelgeneratormultipasscb) . ### Deterministic approach[¶](https://voxel-tools.readthedocs.io/en/latest/procedural_generation/#deterministic-approach "Permanent link") #### Finding where trees should grow in (X, Z)[¶](https://voxel-tools.readthedocs.io/en/latest/procedural_generation/#finding-where-trees-should-grow-in-x-z "Permanent link") The first thing to do is to figure out, in the current block, where should trees grow. For simplicity, we will consider it as a 2D problem, where trees can grow at specific (X, Z) positions (since Y is up). For that, we need to find positions of voxels just above ground, and do so in a deterministic manner, so that the same seed will produce the same results. But how to make it deterministic? We can use the seed of a `RandomNumberGenerator` instance. But if we give it the seed of the world, every block will have trees at the same position in them. What we really need, is a seed that is unique per block. We can achieve that by using a hash of the 2D coordinates of the block: var block_position := Vector3i( origin_in_voxels.x >> 4, origin_in_voxels.y >> 4, origin_in_voxels.z >> 4) # floored division by 16 var rng := RandomNumberGenerator.new() rng.seed = global_seed + hash(Vector2i(block_position.x, block_position.z)) And now we can generate how many trees are in the block, and where: var block_size := out_buffer.get_size() var tree_count := rng.randi_range(0, 2) var tree_positions := [] tree_positions.resize(tree_count) for i in tree_count: var tree_pos := Vector3i( rng.randi_range(0, block_size.x), 0, # We leave Y for later rng.randi_range(0, block_size.z)) # Note, those positions are local to the block tree_positions[i] = tree_pos #### Finding the altitude (Y)[¶](https://voxel-tools.readthedocs.io/en/latest/procedural_generation/#finding-the-altitude-y "Permanent link") But we still need to calculate the altitude from which the tree will grow (the Y coordinate). One issue is that the engine generates cubic blocks, so when generating a given 16x16x16 voxel, you can't access what's below, you only know what's inside the area of the block. However, if base terrain is generated using 2D heightmap noise, then we can calculate how high terrain is at any (x, z) coordinate by computing the height function again, wherever we need. Assuming we already have such function as `func get_height(x: float, y: float) -> float`, we can complete the Y coordinate like so: for i in len(tree_positions): var tree_pos_local : Vector3i = tree_positions[i] # Use world coordinates for this var tree_pos_global := tree_pos_local + origin_in_voxels tree_pos_global.y := get_height(tree_pos_global.x, tree_pos_global.z) # And bring back to local tree_pos_local = tree_pos_global - origin_in_voxels # And store back into the array tree_positions[i] = tree_pos_local #### Placing the tree[¶](https://voxel-tools.readthedocs.io/en/latest/procedural_generation/#placing-the-tree "Permanent link") Now we should be able to place the tree, but what if positions we found are outside the block? We can't set voxels at these positions. What we can do, is to first determine how big the tree will be. Once we know its bounding box, we can place voxels, but only those intersecting our block. To determine how big the tree is, it sounds like we have to generate the tree first, and then determine its bounding box in voxels. We can do that in a separate blank buffer with large enough size, or using a `Dictionary` of `Vector3i` keys and `int` values. But at the end, it is preferable to store the result in an optimized `VoxelBuffer` of the right size. We won't describe how to generate the tree itself here, it's not really the point of this article and can be different with plenty of factors. But it could just be a vertical bar of trunk voxels, with a sphere of leaves on top. It is possible to optimize this step by pre-generating (or making by hand) a bunch of trees ahead of time and store them in a list, so all tree bounds are known and no need to spend time generating them in detail. We can pack tree data into a class: class TreeInfo: # Position of the tree relative to our current block var instance_position := Vector3i() # Buffer storing only the tree, like a model, so it can later be pasted in the world var voxels : VoxelBuffer # Position of the base of the tree, within the VoxelBuffer containing the model of the tree var trunk_base_position := Vector3i() So we can have a list of trees instead of just their positions: var trees : Array[TreeInfo] = [] for tree_pos in tree_positions: var tree : TreeInfo = generate_tree(rng) tree.position = tree_pos trees.append(tree) We may wrap this logic in a function `func generate_trees_for_block(block_position: Vector3i) -> Array[TreeInfo]`, because it may be useful later. Once we know the bounds of each tree, we can check if they intersect with the current block. If they do, we can use the `paste_masked` method to plant just the tree, without replacing solid voxels with empty ones from the tree's `VoxelBuffer`: # AABB of our current block, in local coordinates var block_aabb := AABB(Vector3(), block_size.get_size() + Vector3i(1, 1, 1)) var voxel_tool := out_buffer.get_voxel_tool() # Paste intersecting trees for tree in trees: var lower_corner_pos := tree.instance_position - tree.trunk_base_position var tree_aabb := AABB(lower_corner_pos, tree.voxels.get_size() + Vector3(1,1,1)) if tree_aabb.intersects(block_aabb): voxel_tool.paste_masked(lower_corner_pos, tree.voxels, # Which channel we want to paste 1 << VoxelBuffer.CHANNEL_TYPE, # Masking 0, since 0 is considered air VoxelBuffer.CHANNEL_TYPE, 0) #### Fixing overlaps[¶](https://voxel-tools.readthedocs.io/en/latest/procedural_generation/#fixing-overlaps "Permanent link") Now trees should appear in the world, but when they overlap block borders, they will be cutoff. The reason is that each block is unaware of its neighbors, they generate only trees that originate inside them in the X and Z axes, and only affect voxels in themselves, since they can't modify their neighbors. ![Schema of individual blocks generating cutoff trees](https://voxel-tools.readthedocs.io/en/latest/images/tree_generation_cutoff_schema.webp) We could decide to clamp their position so that they never overlap, but that might not be acceptable, given how "aligned" they will look in the game. We can workaround this by applying the same reasoning we did to obtain their altitude. Instead of just considering trees in the current block, we can also check trees that would generate in neighbor blocks, since we can re-run the function to get them deterministically from a given block position. Then all we have to do is keep only those intersecting our block. Each block will then generate with neighbor trees in the right locations. ![Schema of neighbor trees being generated to take into account overlaps with the current block](https://voxel-tools.readthedocs.io/en/latest/images/tree_generation_neighbor_fix_schema.webp) Note that it means each block will recalculate the locations of its own trees and neighbor trees, so trees in a given block will be calculated more than once during generation of the world. That also means `generate_tree` will be called more than once too. But if we cache generated tree models ahead of time (before the game starts), this process will be a lot cheaper. var trees : Array[TreeInfo] = [] # Get trees that originate from the current block and its neighbors for nz in range(-1, 2): for nx in range(-1, 2): var trees_in_block := generate_trees_for_block(block_position + Vector3i(nx, 0, nz)) trees.append_array(trees_in_block) # Paste intersecting trees for tree in trees: # Earlier code for pasting trees # ... This method has been implemented [in this demo](https://github.com/Zylann/voxelgame/blob/2fa552abfdf52c688bbec27edd676018a31373e0/project/blocky_game/generator/generator.gd#L144) , although the code is a bit different. This approach is also used in Voronoi noise (also known as cellular noise in FastNoiseLite) to produce seamless cells. #### Limitations[¶](https://voxel-tools.readthedocs.io/en/latest/procedural_generation/#limitations "Permanent link") Of course this method has its limitations: if our terrain is more than just a heightmap, includes floating islands, complex carvings or 3D noise structures, it can make the process of finding altitude more complicated. At worse, generating neighbor columns of voxels or entire blocks would become necessary just to find the highest voxel, which would make it too slow. To counter this, you can check [multipass generators](https://voxel-tools.readthedocs.io/en/latest/generators/#multi-pass-generation-with-voxelgeneratormultipasscb) . --- # Performance - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Performance * * * Performance[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#performance "Permanent link") ======================================================================================================= This section discusses performance-related topics, such as making the voxel engine run fast. It can be more technical than the other sections. Threads[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#threads "Permanent link") ----------------------------------------------------------------------------------------------- ### Thread count[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#thread-count "Permanent link") This module uses threads to speed up heavy operations and avoid stalls. Depending on how many threads your CPU can run at the same time, the optimal number of threads can vary. This may also differ for players running your game. The module automatically determines the number of threads to use at runtime, based on how many concurrent threads the CPU supports. You can change how many threads are allocated in your Project Settings, in the `Voxel` section (if you don't see it, try checking "Advanced Settings"). The automatic calculation will be based on the following properties: | Parameter name | Type | Description | | --- | --- | --- | | `voxel/threads/count/minimum` | `int` | Minimum amount of threads | | `voxel/threads/count/margin_below_maximum` | `int` | How many threads below max concurrent count should be considered maximum. `0` means the maximum concurrent count will be the maximum. `1` means the maximum concurrent count minus 1 will be the maximum. | | `voxel/threads/count/ratio_over_maximum` | `float` | Portion of max concurrent threads to attempt using, between 0 and 1. For example, `0.5` will attempt to use half of them. The result will be clamped using the other options. | Several notes: * It is recommended to not use all available threads for voxel stuff. Games use more for other things, and players may even do something else in background (such as music, YouTube playlist or voice chat). * It is not possible to use zero threads. The module is designed to use threads at the moment. * You can check at runtime how many theads are allocated with a script and using `VoxelEngine.get_stats()`. It is also printed if `debug/settings/stdout/verbose_stdout` is enabled in project settings (or `-v` in command line). * Changing these settings requires an editor restart (or game restart) to take effect. ### Main thread timeout[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#main-thread-timeout "Permanent link") Some tasks still have to run on the main thread, and sometimes their total time can exceed the duration of a frame, if we were to add all the remaining things that have to be processed. To mitigate this, the module has an option to stop processing these tasks beyond a certain amount of milliseconds, and continue them over next frames. In `ProjectSettings`, look for `voxel/threads/main/time_budget_ms`. Rendering[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#rendering "Permanent link") --------------------------------------------------------------------------------------------------- Terrains are rendered with many unique meshes. That can amount for a lot of draw calls and work for the engine to cull. It is possible to reduce the number of blocks in several ways: * Reduce view distance * Reduce LOD distance, if you use `VoxelLodTerrain` * Increase mesh block size: they default to 16, but it can be set to 32 instead. This reduces the number of draw calls, but may increase the time it takes to modify voxels. ### Slow mesh updates issue with OpenGL[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#slow-mesh-updates-issue-with-opengl "Permanent link") #### Issue[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#issue "Permanent link") Godot 3.x is using OpenGL, and there is an issue which currently degrades performance of this voxel engine a lot. Framerate is not necessarily bad, but the speed at which voxel terrain updates is very low, compared to what it should be. So far the issue has been seen on Windows, on both Intel or nVidia cards. Note: Godot 4.x will have an OpenGL renderer, but this issue has not been tested here yet. #### Workarounds[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#workarounds "Permanent link") Note: you don't have to do them all at once, picking just one of them can improve the situation. * Increase `voxel/threads/main/time_budget_ms` to a value higher than frame time (by default it is about 8 ms, which is half of a frame). However this can slowdown FPS while meshes are updated. * Or turn on `debug/settings/stdout/verbose_stdout` in project settings. This internally enables an OpenGL debugging extension, which for some reason fixes the expected timing of OpenGL calls. It's the most effective fix regarding framerate, but has drawbacks because it prints a lot, and was intented as a debugging feature. * Or turn off `display/window/vsync/use_vsync` in project settings. Not as effective and eats more resources, but improves performance. * Or turn on `display/window/vsync/vsync_via_compositor` in project settings. Not as effective but can improve performance in windowed mode. #### Explanation[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#explanation "Permanent link") The engine relies a lot on uploading many meshes at runtime, and this cannot be threaded efficiently in Godot 3.x so far. So instead, meshes are uploaded in the main thread, until part of the frame time elapsed. Beyond that time, the engine stops and continues next frame. This is intented to smooth out the load and avoid stutters _caused by the task CPU-side_. Other tasks that cannot be threaded are also put into the same queue, like creating colliders. Unfortunately, the first call to OpenGL during the frame appears to take a whopping 15 milliseconds _on the CPU_. This happens no matter how heavy the call is. The voxel engine detects that, and immediately stops uploading meshes, thinking it has done too much. As a result, typically only one mesh ends up being uploaded each frame, which is ridiculously low. We could lift the time limit, but if it were to continue running tasks, it would start stuttering due to overshooting the 16ms limit of the frame. When one workaround is used, like enabling `verbose_stdout`, this slowdown completely disappears. Instead, the "delay" moves at the end of the frame. This has been linked to a debugging OpenGL extension getting turned on. For more information, see [Godot issue #52801](https://github.com/godotengine/godot/issues/52801) . ### Slowdown when moving fast with Vulkan[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#slowdown-when-moving-fast-with-vulkan "Permanent link") #### Issue[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#issue_1 "Permanent link") If you move fast while near a terrain with a lot of chunks (mesh size 16 and high LOD detail), the renderer can cause noticeable slowdowns. This is because Godot4's Vulkan allocator is much slower to destroy mesh buffers than Godot 3 was, and it does that on the main thread. When you move fast, a lot of meshes get created in front of the camera, and a lot get destroyed behind the camera at the same time. Creation is cheap, destruction is expensive. This was observed by profiling with Tracy in a `release_debug` build (typical mode used for official optimized builds): ![Screenshot of Tracy profiler showing slow buffer deallocation](https://voxel-tools.readthedocs.io/en/latest/images/tracy_profile_slow_vulkan_dealloc.webp) Lots of buffers get freed on the main thread at the end of the frame, and it can take a while, causing a CPU spike. On the other hand, there is no such issue when the same amount of meshes is allocated. This issue also was not noticeable in Godot 3. This problem reproduces specifically when a lot of small meshes are destroyed (small as in 16x16 pieces of terrain, variable size), while a lot of them (thousands) already exist at the same time. Note, some of them are not necessarily visible. #### Workarounds[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#workarounds_1 "Permanent link") It is not possible for the module to just "pool the meshes", because when new meshes need to be created, the API requires to create new buffers anyways and drops the old ones (AFAIK). It is also not possible to use a thread on our side because the work is deferred to the end of the frame, not on the call site. A mitigation is in place to smooth the spikes by spreading the amount of destroyed meshes over time, but the slowdown is still noticeable. The only workarounds involve limiting the game: * Increase mesh block size to 32 to reduce their number, at the expense of edition cost * Limit the speed at which the player can move when close to voxels * Reduce LOD distance so less blocks have to be destroyed, at the expense of quality Physics[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#physics "Permanent link") ----------------------------------------------------------------------------------------------- The voxel engine offers two different approaches to physics: - Standard Physics: the official API Godot exposes through `PhysicsServer3D` (Godot Physics, Godot Jolt...). - Box Physics: a small specialized API that only works with axis-aligned boxes on blocky terrain, exposed with `VoxelBoxMover` and voxel raycasts. It is much more limited and requires some setup, but performs faster. ### Standard Physics[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#standard-physics "Permanent link") #### Mesh colliders simulation[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#mesh-colliders-simulation "Permanent link") Similar to rendering 16x16x16 or 32x32x32 blocks, the voxel engine uses "mesh" colliders for every terrain block (or "chunk"). These colliders are static and can be concave. Therefore, any terrain shape should be supported, but depends a lot on how performant these colliders are in the underlying physics engine. Moving terrain remains possible, but do not expect physics to work correctly on the surface while moving it. #### Tunnelling[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#tunnelling "Permanent link") Mesh colliders used by terrain have no "thickness". An object can sit undisturbed outside or inside of it, contrary to convex colliders which usually have a "depenetration force" pushing objects away from their inside. This makes mesh colliders more prone to "tunneling": if an object goes too fast, or is too small relative to its velocity, it can pass through the ground. * Limit speed of your objects * For fast-moving objects (projectiles?), use elongated shapes, or just raycasts, making sure that the "trail" of the shape "connects" between each physics frame * Enable Continuous Collision Detection, if the physics engine supports it * Check voxel data to find out if a point is underground and move up the object #### Shape creation is very slow[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#shape-creation-is-very-slow "Permanent link") Similar to rendering, the voxel engine has to convert voxels into meshes ("meshing"), and does this with our own prioritised pool of threads. It will use those meshes as colliders. Creating a collider from a mesh is actually much more expensive than meshing itself (about 3 to 5 times), because it involves creating an acceleration structure to speed up collision detection (BVH, octree...). Unfortunately, Godot does not offer a reliable way to safely create these shapes _including their acceleration structure_ from within out meshing threads. So instead, we had to defer it all to the main thread, and spread it over multiple frames. This slows down terrain loading tremendously (compared to disabling collisions). * A [proposal](https://github.com/godotengine/godot-proposals/issues/483) has been opened to expose this issue, still not addressed * [Godot Jolt](https://github.com/godotengine/godot/pull/99895) also has this issue, exacerbated by the fact it was implemented to defer shape setup to the very last moment, when entering the scene tree. So even if we were allowed to create mesh colliders from our threads, it still defers all the hard work to the main thread. Voxel Iteration order[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#voxel-iteration-order "Permanent link") --------------------------------------------------------------------------------------------------------------------------- In this engine, voxels are stored in flat arrays indexed in ZXY order. Y is the "deepest" coordinate: when iterating a `VoxelBuffer` of dimensions `(size.x, size.y, size.z)`, adding 1 to the Y coordinate is equivalent to advancing by 1 element in memory. Conversely, adding 1 to the X coordinate advances by `size.y` elements, and adding 1 to the Z coordinate advances by `(size.x * size.y)` elements. Therefore, for cache locality, iterating voxels is best done in this order: for z in size.z: for x in size.x: for y in size.y: var v := buffer.get_voxel(x, y, z, channel) # ... The only reason for this particular choice was that most games use Y as the vertical coordinate, so some operations can be done quickly alongside the vertical axis. It was decided in early days of the project and was kept for consistency. But generally, this convention should only matter if you are working on low-level code. GDScript[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#gdscript "Permanent link") ------------------------------------------------------------------------------------------------- GDScript is already quite slow to perform intensive operations such as doing 3D for loops to process voxel buffers with complex conditions. You may use it that way for prototyping, but it is not scalable. Another approach is to use it as a "logic glue" to compose lower-level functions together that do the expensive work, such as `VoxelTool` or `VoxelBuffer` methods, or delegating to graphs. It also suffers from a significant performance penalty when used inside multiple threads in editor tests. This is especially relevant when implementing `VoxelGeneratorScript` for example. When run from the editor, Godot uses debug synchronization primitives that hugely slow down function calls, to the point using less threads could make your code faster. This issue is not present in exported builds. Access to voxels from different threads[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#access-to-voxels-from-different-threads "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------------------------- This section explains in more detail how multithreading is implemented with voxel storage, and what are the implications when you access and modify voxels. ### The problem[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#the-problem "Permanent link") Up to version `godot3.2.3` of the module, reading and writing to voxels did not care about multithreading. It was possible to access them without locking, because all the threaded operations using them (saving and meshing) were given copies of the voxels, made on the main thread. This made things simple, however it causes several issues. * If threads are unable to consume tasks faster than they are issued, copies of voxel data will keep accumulating rapidly and make the game run out of memory. * Copying blocks and their neighbors takes time and is potentially wasteful because it's not guaranteed to be used. * It assumes the threaded task will only need to access a specific block at a fixed LOD, which is not always the case in other voxel engines (such as UE4 Voxel Plugin by Phyronnaz). For example, Transvoxel running on a big block may attempt to access higher-resolution blocks to better approximate the isosurface, which is not possible with the current approach. ### Internal changes[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#internal-changes "Permanent link") The old design starts to change in version `godot3.2.4`. Copies aren't made preemptively on the main thread anymore, and are done in the actual threaded task instead. This means accessing voxels now require to lock the data during each transaction, to make sure each thread gets consistent data. Locking is required **if you access voxels which are part of a multithreaded volume**, like a terrain present in the scene tree. You don't need to if you know the data is not used by any other thread, like inside generators, custom streams, known copies or other storage not owned by an active component of the voxel engine. #### RWLocks per VoxelBuffer[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#rwlocks-per-voxelbuffer "Permanent link") The locking strategy was initially implemented by adding an `RWLock` on every `VoxelBuffer`. Such locks are read-write-locks, also known as shared mutexes. While simple, this method meant that if you had a 16x16x16 loaded terrain area containing voxels, you'd have to allocate 4,096 `RWLocks` from the system, and lock them all if a region needed to be accessed. For example, updating a mesh means accessing a block and its 26 neighbors, so 27 locks. They also had to be locked in a specific order, because two threads trying to lock multiple blocks in different order would lead to a dead-lock, freezing the game. `RWLock` is also quite heavy on Windows, taking 244 bytes (half of the base data structure for data blocks). Besides, certain platforms (such as consoles or mobile systems) might not allow creating that many locks. #### Spatial lock (17/06/2023)[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#spatial-lock-17062023 "Permanent link") Later on, `RWLocks` were removed from `VoxelBuffer`. They were replaced with `SpatialLock3D`. A spatial lock is just a list of boxes protected by a mutex. If you want to read voxels in a specific area, try adding that box to the list, and remove it once you're done. If you want to also write voxels, tag that box as "write mode". The spatial lock will block locking attempts if an existing box in "write mode" is intersecting yours, while allowing multiple "read mode" boxes to overlap. It essentially acts the same as `RWLock`, except only one short-duration mutex is used to protect the list, and there is no need for thousands of them to exist. This approach requires the same amount of locks regardless of the size of the box. #### Read and write[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#read-and-write "Permanent link") Multiple threads can read the same block, but only one can modify it at once. If a thread wants to modify the block while it is already locked for _read_, the thread will be blocked until all other threads finished reading it. This can cause stutter if done too often on the main thread, so if it becomes a problem, a possible solution is to lock for _read_, copy the block and then modify it (Copy-on-Write). Another solution is to run expensive modifications in a thread and use "try lock" instead of "lock", delaying the task instead of blocking the thread. ### Editing voxels efficiently[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#editing-voxels-efficiently "Permanent link") This matters for scripters. If you use `VoxelTool`, all locking mechanisms are handled for you automatically. However, you must be aware that it doesn't come for free: if you want to access voxels randomly and modify them randomly, you will pretty much get the worst overhead. If you want to access a well-defined region and you know where to read, and where to write ahead of time, then optimizing becomes possible. For example, _on a terrain node_, `VoxelTool.get_voxel` or `set_voxel` are the simplest, yet the slowest way to modify voxels. This is not only because of locking, but also because the engine has to go all the way through several data structures to access the voxel. This is perfectly fine for small isolated edits, like the player digging or building piece by piece. This is what happen when you change a single voxel in a terrain (as of 17/06/2023. May also vary depending on the operation and terrain configuration): * Your voxel position is converted into block coordinates * The map containing blocks is locked (so we are sure nothing else modifies it as we access it) * The block is queried. If it isn't loaded, the edit will fail as "area not editable". * If the block is loaded but does not cache voxel data (in some configurations, non-edited blocks do not store data), the whole block will be generated on the spot using `VoxelGenerator` and modifiers and will be inserted in the map. * The map containing blocks is unlocked * The block itself gets locked in Write mode. Nothing else can access it. If something else is already using the block, the current thread will block until it unlocks. * Your voxel position is converted into block-relative voxel position and bound-checked * The voxel channel is accessed: if it contains no voxel data due to the whole block containing the same value (optimization), data will get allocated so that the voxel you are modifying can take a different value. * The channel's format is checked: coming from a script, the value you pass could be a 64-bit integer or a float, but channel data may be 8, 16, 32 or 64 bits with various encodings. By default, it is 16 bits, so the value may get clamped and encoded. * The value actually gets stored * The block is unlocked and marked as modified * The terrain is notified that a change occurred in the block you edited. * If the terrain has a mesher, a re-meshing task will be scheduled (if not already done so far) to update visuals and maybe collisions. * If the terrain has a network synchronizer, it will schedule an "area changed" RPC message. * If the terrain has a VoxelInstancer, it will check if instances lost contact with ground. As you can see, a lot is going on with a single voxel. Repeating this all over for many voxels is not efficient. That's why bulk edits may be preferred, because a lot of these operations will happen only once for the whole edit, an the only thing that will get executed many times is the actual voxel data changes. If you want to excavate whole chunks or generating structures, try to use specialized bulk functions instead, such as `do_sphere()`, `do_box()`, `raycast` or `paste()`. These will be more efficient because they can cache data structures on the way and perform locking in the best way they can. If your changes are very custom or depend on a lot of pre-existing voxels, you can use `copy()` to extract a chunk of voxels into a `VoxelBuffer` so you can read them very fast without locking. You can even choose to do your changes on that same buffer, and finally use `paste()` when you're done. Tuning `VoxelGeneratorGraph`[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#tuning-voxelgeneratorgraph "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------- `VoxelGeneratorGraph` uses a number of optimization strategies to make the calculations faster. You may want to fine-tune them in some cases depending on the kind of volume you want to generate, although it should run ok by default. When you get more familiar with the tool it may be useful to know how it works under the hood, notably to troubleshoot generation issues when they occur. ### Buffer processing (CPU)[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#buffer-processing-cpu "Permanent link") Contrary to many node-based or expression tools existing in Godot so far, voxel graphs are not tailored to run on voxels one by one. The main use case is to process a bunch of them. Indeed, for a 16x16x16 block, there are 4096 voxels to generate. That would mean traversing the entire graph 4096 times, and the cost of doing that individually can exceed the cost of the calculations themselves. Besides, switching constantly between node types to run different operations is not CPU-friendly due to all the jumps required. So instead, outputs of each node are associated small buffers for a subset of the voxels, say, a 16x16 slice. Then, the graph is traversed once ahead-of-time to obtain a simple list of operations. It is guaranteed that if a node depends on another, the other will have run before. ![Graph to operations schema](https://voxel-tools.readthedocs.io/en/latest/images/voxel_graph_operation_list.webp) Finally, the generator executes the list, node by node, and each node computes a bunch of voxels at once instead of just one. This ensures that the CPU is almost exclusively used for the operations themselves, providing performance similar to C++, while graph traversal becomes neglibible. It also offers the opportunity to use [SIMD](https://en.wikipedia.org/wiki/SIMD) very easily, which can be even faster than if the code was written in plain C++. Buffer processing is mostly an internal detail so there are no particular settings on the scripting API. ### Range analysis (CPU)[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#range-analysis-cpu "Permanent link") Before processing voxels in a specific region of space (a box), the generator first runs a [range analysis](https://en.wikipedia.org/wiki/Interval_arithmetic) pass. Each node has an alternative implementation using intervals, with the sole purpose of estimating the range of values it will output in the area. It's like a broad-phase before the heavy work. It is possible to inspect results of this pass in the editor by enabling it with the `Analyse range` button. The analysis will focus on the box specified in the dialog, which will appear as a yellow wireframe in the 3D viewport. ![Analyse range editor screenshot](https://voxel-tools.readthedocs.io/en/latest/images/range_analysis_dialog.webp) You can also hover the output label of any node to see what range was calculated for it: ![Range analysis tooltips](https://voxel-tools.readthedocs.io/en/latest/images/range_analysis_tooltip.webp) Note Noise is typically between -1 and 1, but we take it a step further. Ranges are approximated using maximum derivatives, which is how fast noise can vary along a given distance. Each noise algorithm has its own. We calculate noise at the center of the box, and add half of the maximum derivative, positively and negatively. In other words, in the box, we know noise cannot exceed the central value + the maximum variation along extents of the box. At close range, this can successfully detect valleys and hills, without fully computing them. Results of this pass are used for several optimization techniques described below. ### SDF clipping (CPU)[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#sdf-clipping-cpu "Permanent link") 3D volumes represented with meshes to form a terrain have an interesting property: to generate them, we are mostly interested in the areas where voxel values are crossing the isolevel (zero). That means we could completely discard regions of space that are guaranteed to never get near zero, and simplify them to a single value (like "only matter" or "only air"). Doing that in 3 dimensions has tremendous speed implications so it is a major feature of this generator. Range analysis is used to perform this optimization. In a given area, if the maximum value of SDF is lower than a threshold below zero, then the whole block is skipped and assigned a uniform negative value. The same happens with a threshold above zero. It is possible to choose that threshold with the `sdf_clip_threshold` property in the inspector. If given an extremely large value like `10000`, it will essentially turn off this optimization. It is exposed because in some situations, clipping can cause artifacts when the edge of a block is too close from a clipped one. Indeed, clipping blocks cause discontinuities in the distance field. ![Sdf clipping schema](https://voxel-tools.readthedocs.io/en/latest/images/sdf_clipping.webp) Usually they happen far enough from the surface to be of any concern, but sometimes they can come close if the threshold is too low: ![Sdf clipping artifacts](https://voxel-tools.readthedocs.io/en/latest/images/sdf_clipping_artifacts.webp) So by default the threshold is above zero and should cover most cases. It is also possible to instruct the generator to invert clipped blocks, which will make them stand out: ![Sdf clipping debug](https://voxel-tools.readthedocs.io/en/latest/images/sdf_clip_debug.webp) ### Local optimization (CPU)[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#local-optimization-cpu "Permanent link") Conditionals (`if/else`) are not supported by this voxel graph implementation. The main reason is because of the buffer processing approach. The CPU can churn through buffers very fast, but branching on a per-voxel basis would disrupt it. Besides, range analysis might get a lot more complicated if branching was added. They can exist within nodes, but cannot exist as a graph-level primitive. So the usual approach is to blend things by mixing, adding, subtracting parts of the graph. But when a graph becomes big, even with SDF clipping, performance could be better. Conditionals are often used to optimize locally, so how can we do this without? Let's consider an example world made of two biomes, each generated with a big node setup, and blended together across the world's X axis. ![Two biomes](https://voxel-tools.readthedocs.io/en/latest/images/biomes.webp) If we don't optimize this, both biomes will constantly get calculated at every point of space close enough to the surface. But if we look at the range analysis we performed earlier, and focus on one of the biomes, we notice that the range of values received by the `Mix` node are such that only one biome is blended. In other words, one of the inputs of `Mix` has no effect on its result, and is therefore ignored there. ![Ignored input](https://voxel-tools.readthedocs.io/en/latest/images/range_of_ignored_input.webp) So each biome then only computes its own branch when far away enough from the blending area: ![Ignored biome range debug](https://voxel-tools.readthedocs.io/en/latest/images/biomes_optimization.png) Thanks again to range analysis, the generator is able to detect this locally, and _dynamically skips whole branches of nodes_ if they are found to not affect the final result. Therefore, it is not required to add conditionals for this use case, it's done automatically. You can visualize this by turning on the analysis tool, which will grey out nodes that are ignored in the specified area. Internally, the generator parses the graph locally (using a faster data structure since the graph is compiled) to obtain an alternative list of operations. This list is currently nicknamed an `execution map`, because it maps the full list of operations to a reduced one. ![Execution map schema](https://voxel-tools.readthedocs.io/en/latest/images/voxel_graph_operation_list_optimized.webp) This setting can be toggled in the inspector. Note This feature may be more or less precise depending on the range of values parts of the graph are producing. So it is possible that two different graphs providing the same result can run at different speeds. For this reason, analysing ranges can prove useful to understand why parts of the graph are still computed. ### Subdivision (CPU)[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#subdivision-cpu "Permanent link") Previous optimizations are tied to the size of the considered area. The bigger the area, the less precise they will be. For example, with a larger box, it is more likely to find a place where voxels produce a surface. It is also more likely for more biomes or other shapes to appear and blend together. Besides, changing the size of our world chunks isn't a light decision. So a simple improvement is to tell the generator to further subdivide itself the region of space it works on. Usually a subdivision size of 16x16x16 is ok. 8x8x8 is even more precise, but below that size the cost of iteration will eventually exceed the cost of computations again (see Buffer processing). Subdivision sizes must also divide volume block sizes without remainder. This is mostly to avoid having to deal with buffers of different sizes. ### XZ caching (CPU)[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#xz-caching-cpu "Permanent link") When generating voxel-based terrains, despite the attractiveness of overhangs, there can be a large part of your generator only relying on the X and Z coordinates. Typically, generating from 2D noise as a base layer is one of these situations. When the generator is done with a slice along X and Z, it increases Y and does the slice above. But since 2D noise only depends on X and Z, it would get recomputed again. And noise is expensive. This situation is similar to the following pseudocode: for z in size_z: for x in size_x: for y in size_y: set_voxel(x, y, z, noise2d(x, z) + y) Typically, to optimize this, you would move out the `noise2d` call into the outer loop, like so: for z in size_z: for x in size_x: n = noise2d(x, z) for y in size_y: set_voxel(x, y, z, n + y) This way, the 2D noise is only computed once for each column of voxels along Y, which speeds up generation a lot. In Voxel Graphs, the same optimization occurs. When the list of operations is computed, they are put in two groups: `XZ` and `XZY`. All operations that only depend on X and Z are put into the `XZ` group, and others go into the `XZY` group. When generating a block of voxels, the `XZ` group is executed once for the first slice of voxels, and the `XZY` group is executed for every slice, re-using results from the `XZ` group. This optimization only applies on both X and Z axes. It can be toggled in the inspector. ### Buffer reduction (CPU)[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#buffer-reduction-cpu "Permanent link") The graph attempts to use as few temporary buffers as possible. For example, if you have 10 nodes processing before the output, it won't necessarily allocate 10 unique buffers to store intermediary outputs. Instead, buffers will be re-used for multiple nodes, if that doesn't change the result. Buffers are assigned ahead-of-time, when the graph is compiled. It saves memory, and might improve performance because less data has to be loaded into CPU cache. This feature is disabled when the graph is compiled in debug mode, as it allows inspecting the state of each output. ### GPU[¶](https://voxel-tools.readthedocs.io/en/latest/performance/#gpu "Permanent link") Earlier sections were related to the CPU backend of `VoxelGeneratorGraph`. There is a GPU backend, which runs very differently. None of the CPU optimization settings apply to that backend. The GPU backend will generate a compute shader for each kind of usage (at time of writing: chunk generation, and detail texture rendering). These compute shaders are dispatched from a separate `RenderingDevice`, in a background thread, so while they use the graphics card, they usually don't lead to framerate drops. You can see the generated code using the `Generate Shader` menu in the graph editor. Shader compilation is done on a separate thread as well, and can take a while depending on the complexity of your graph. It can be noticed if the first chunk takes an unusual amount of time to generate. If you notice this but still want to use the GPU backend, you may simplify your graph: - Reduce the number of noise nodes, in particular `FastNoiseLite`. While this node gets the same results as the CPU version, it's a huge library in regard to shaders, and the more calls there are, the more complex compilation will get (either from GLSL to SPIRV, but also from SPIRV to GPU-specific format). - Use less complex noise types. Cellular kinds are more costly. - Replace noise nodes with image nodes that seamlessly repeat, i.e bake noise up-front. This is also faster to execute, at the cost of eventual repetition. Combining them at different rates can make it less obvious. --- # Instancing - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Instancing * * * Instancing[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#instancing "Permanent link") ==================================================================================================== The module provides an instancing system with the [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) node. This node must be added as child of a voxel terrain. It supports spawning 3D models on top of the terrain's surface, which can later be removed when modified. It can spawn two different kinds of objects: * **Multimesh instances**. They can be extremely numerous, and can optionally have collision. * **Scene instances**. They use regular scenes, however it is much slower so should be tuned to low numbers. This system is primarily intended at natural spawning: grass, rocks, trees and other kinds of semi-random foliage. It is not suited for complex man-made structures like houses or villages, although scene instances can be used in some cases, if the available features suit your game. VoxelInstanceLibrary[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#voxelinstancelibrary "Permanent link") ------------------------------------------------------------------------------------------------------------------------ ### Library setup[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#library-setup "Permanent link") In order to spawn items, `VoxelInstancer` needs a [VoxelInstanceLibrary](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/) resource. This resource contains a list of all the items that can be spawned, and how they will be placed. Select a `VoxelInstancer`. In the inspector, assign a library to the `library` property, or create a new embedded one. Then click on the library resource. Buttons appear at the top of the inspector: ![Screenshot of the VoxelInstanceLibrary menu](https://voxel-tools.readthedocs.io/en/latest/images/instance_library_menu.webp) You can add items to the library by clicking the "+" icon, and choose `Add Multimesh item`. Items created this way come with a default setup, so you should be able to see something appear on top of the voxel surface. Note If you are making a planet, you may want to set the `up_mode` of `VoxelInstancer` to `Sphere` mode. This will tell the instancer where the upward direction is, and will align the items according to the local origin of the terrain. ### Block LOD[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#block-lod "Permanent link") The range at which items spawn is based on the LOD system of the voxel terrain itself, either on high-resolution chunks, or low-resolution ones. This is configured in the `lod_index` property of [VoxelInstanceLibraryItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/) . For example, choosing `0` will make the item spawn on chunks of LOD0 at closest range, and fade quickly in the distance. Higher indexes will spawn on bigger chunks covering a larger range. ![Screenshot showing the effect of lod_index on the range of instances](https://voxel-tools.readthedocs.io/en/latest/images/instances_lod_index.webp) Usually landscapes may be composed of multiple layers so that the closer you get, the more details come in. Bigger items use high lod indexes to be seen from far away, while smaller items may use lower indexes. ![Screenshot of landscape using layers of instances](https://voxel-tools.readthedocs.io/en/latest/images/landscape_with_instances.webp) Note When making grass or other items, it may be a good idea to fade meshes based on distance from the camera using a custom shader, so they won't disappear abruptly. Using a ground texture of similar colors also helps to make it blend. ### Placement precision[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#placement-precision "Permanent link") There is a balance to consider when choosing the appropriate `lod_index`: currently, larger indexes are _much more imprecise_, because they work on top of a lower-resolution mesh. This allows to generate instances much quicker at larger distances, without having to calculate full-precision LODs. The downside is, as getting closer and terrain calculates higher-resolution LODs, it's possible that such instances are seen floating above ground, or sinking into it. This mostly happens in areas with sharp changes such as ridges, crevices or caves: ![Screenshot of misaligned instances](https://voxel-tools.readthedocs.io/en/latest/images/misaligned_instances.webp) #### Offset along normal[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#offset-along-normal "Permanent link") A first option to adjust placement, is to adjust the `offset_along_normal` parameter in the `generator` associated to the item. This depends on the asset, so designing them such that they can have part of their bottom sunk into the ground can give some margin of error. #### Snapping from generator SDF[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#snapping-from-generator-sdf "Permanent link") Another option is to enable `snap_to_generator_sdf_enabled`, at the cost of slower instance generation. This is preferably used when `lod_index` > 0, as LOD0 already has maximum precision. Without snapping: ![Screenshot of instances spawned from LOD2 an viewed at LOD0, without snapping. Many are not properly on ground](https://voxel-tools.readthedocs.io/en/latest/images/instance_gen_sdf_affining_off.webp) With snapping: ![Screenshot of instances spawned from LOD2 an viewed at LOD0, with snapping on, resulting in better positionning](https://voxel-tools.readthedocs.io/en/latest/images/instance_gen_sdf_affining_on.webp) This option queries the `VoxelGenerator` at floating point positions to approximate where the surface is, assuming the mesh-based position was a good starting point. The generator can only return SDF values, which roughly tells how "close" each 3D point is from the surface. With at least 2 nearby samples or more, we can interpolate to snap positions closer to that surface. So this is not an accurate snapping, but it can improve positionning significantly. Limitations: * Requires a generator that supports series generation (i.e query arbitrary floating point positions to get voxel data from, instead of voxel chunks). At time of writing, only `VoxelGeneratorGraph` supports this. * Doesn't work if the terrain is modified: if a player comes back to the edited area and instances have to re-generate on top, estimations from the generator will not account for edited areas. To workaround this, instances could be set as `persistent`, so editing terrain marks them as modified and saves their positions onwards instead of re-generating. * Tends to "bury" or "float" instances far away when their low-resolution mesh is active, since they get moved closer to the high-resolution one. This should however not be as noticeable as before, when that was happening at close range. #### Research[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#research "Permanent link") More options may be researched in the future in case the current workarounds aren't enough: * Gradually snap instances as higher-resolution meshes become available. Requires fast mesh raycast, if possible doable from threads (that unfortunately excludes Godot physics). ### Mesh LOD[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#mesh-lod "Permanent link") A secondary LOD system is included, which applies to meshes themselves, to some limited extent. It allows to reduce vertex count over distance from within a set of visible meshes. It only applies to `VoxelInstanceLibraryMultiMeshItem`. Note This LOD system exists because Godot 3 didn't have one. Godot 4 added [automatic mesh LOD](https://docs.godotengine.org/en/stable/tutorials/3d/mesh_lod.html) , which you might be able to use instead of this system. If you want to control the mesh and material used for each LOD, you may use this system. While [Visibility Ranges](https://docs.godotengine.org/en/stable/tutorials/3d/visibility_ranges.html#doc-visibility-ranges) is presented as the alternative, when using `MultiMesh` it requires to unnecessarily duplicate the data and increase the number of scene objects to process. To use this, you have to fill the 3 mesh LOD properties on your `VoxelInstanceLibraryMultiMeshItem`: ![Screenshot of mesh LOD properties](https://voxel-tools.readthedocs.io/en/latest/images/mesh_lod_properties.webp) If only the `mesh` property is set, no LOD will be used. ![Screenshot of mesh LODs with colors](https://voxel-tools.readthedocs.io/en/latest/images/mesh_lods.webp) If you need fewer LODs, you can assign twice the same mesh. Note Impostor meshes are simple quads that can fake the presence of the real model over far distances. For example, this is a really fast way to render forests from afar, while being able to use detailed trees when coming closer. It is possible to customize the distances at which mesh LODs switch, under the `Mesh LOD settings` property group. They are defined as ratios (usually between 0 and 1) relative to the view distance of the corresponding terrain LOD (defined by `lod_index`). It is also possible to hide instances that fall beyond the maximum distance of the last LOD. This is mainly useful if the terrain has no LOD, however keep in mind that instances will still be generated, they will just not be rendered. Warning There is currently a performance issue occurring when `MultiMesh.mesh` is changed to a different LOD. It should be easier to fix once [this PR](https://github.com/godotengine/godot/pull/79833) is merged into Godot. ### Edition[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#edition "Permanent link") Editing instances manually in the editor is not supported yet. It is only possible to define where instances spawn by using procedural generation. It is however possible to remove them from within the game, when digging the ground they spawned on. ### Persistence[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#persistence "Permanent link") It is possible for some items to be persistent. This option can be enabled with the `persistent` property of [VoxelInstanceLibraryItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/) . If the parent terrain has a `VoxelStream` supporting it, then instances from edited blocks will be saved into the stream, and won't respawn next time the player gets close to the area. Non-persistent instances will always respawn on each surface where procedural conditions are fulfilled. The ID of persistent items is important, because it will be used in saved data. If you delete an item and try to load instances from a stream that still contains them, warnings will occur. At time of writing, only [VoxelStreamSQLite](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/) supports saving instances. The save format is described in [this document](https://voxel-tools.readthedocs.io/en/latest/instancing/specs/instances_format.md) . ### Setting up a Multimesh item from a scene[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#setting-up-a-multimesh-item-from-a-scene "Permanent link") It is possible to setup a Multimesh Item from an existing scene, as an alternative to setting it up in the inspector. The scene will be converted to fit multimesh rendering. One reason you could need this is to setup colliders, because although they are supported, it is not possible to set them in the inspector at the moment. It is also more convenient to design instances in the 3D editor using nodes. There are two ways of setting up from a scene: * Assign the `scene` property. This will convert the scene at runtime. The scene will be linked to the item, so it will stay updated if the scene changes. * Use the `Setup from scene` button on top of the inspector. This does not link the scene, and rather assigns manual properties doing the conversion in the editor. The item will not update if the scene change. If the scene embeds meshes, materials or textures, they might end up being copied into the item's resource file. The conversion process expects your scene to follow a specific structure: - PhysicsBody (StaticBody, RigidBody...) - MeshInstance_LOD0 <-- "LOD" suffixes are optional but allow to specify the 4 LODs if needed - MeshInstance_LOD1 - MeshInstance_LOD2 - MeshInstance_LOD3 - CollisionShape1 - CollisionShape2 - ... Materials can be setup in two ways: * `material_override` on the MeshInstance * Materials on the mesh resource directly Surface material properties on the `MeshInstance` node are not supported. ### Scene instances[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#scene-instances "Permanent link") Multimesh items are fast and efficient, but have limitations. Instancing scenes is supported by adding items of type `VoxelInstanceLibrarySceneItem`. Instead of spawning multimeshes, regular scene instances will be created as child of `VoxelInstancer`. The advantage is the ability to put much more varied behavior on them, such as scripts, sounds, animations, or even further spawning logic or interaction. The only constraint is, the root of the scene must be `Node3D` or derive from it. This freedom has a high price compared to multimesh instances. Adding many instances can become slow quickly, so the default density of these items is lower when you create them from the editor. It is strongly recommended to not use too complex scenes, because depending on the settings, it can lead to a freeze or crash of Godot if your computer cannot handle too many instances. Warning If you add a scene to the library and then try to load that library from that same scene, Godot will crash. This is a cyclic reference and is hard to detect in all cases at the moment. Procedural generation[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#procedural-generation "Permanent link") -------------------------------------------------------------------------------------------------------------------------- ### Built-in generator[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#built-in-generator "Permanent link") ![Screenshot of a layer of instances using noise](https://voxel-tools.readthedocs.io/en/latest/images/instances_procgen.webp) Items are added with a default built-in generator, so they will already spawn based on procedural rules rather than being painted manually. You can tweak the generator by inspecting the `generator` property of [VoxelInstanceLibraryItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/) . Persistent instances located in a block that was edited in the game will no longer regenerate. ### Custom instance generator[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#custom-instance-generator "Permanent link") The feature is recent and the API may still change, so this is not available to scripts at the moment. Streaming events (advanced)[¶](https://voxel-tools.readthedocs.io/en/latest/instancing/#streaming-events-advanced "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ `VoxelInstancer` knows when to spawn things by registering itself to its parent's block events. This is currently not available to the script API of `VoxelLodTerrain`, but may be added in the future. --- # Quick start - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Quick start * * * Quick start[¶](https://voxel-tools.readthedocs.io/en/latest/quick_start/#quick-start "Permanent link") ======================================================================================================= Demo projects[¶](https://voxel-tools.readthedocs.io/en/latest/quick_start/#demo-projects "Permanent link") ----------------------------------------------------------------------------------------------------------- Now that your Godot Engine has voxel support built in, you can either download one of the demos and start playing around with them: * [Zylann's basic demos](https://github.com/Zylann/voxelgame) * [Zylann's solar system demo](https://github.com/Zylann/solar_system_demo) * [TinmanJuggernaut's fps\_demo](https://github.com/tinmanjuggernaut/voxelgame) Videos[¶](https://voxel-tools.readthedocs.io/en/latest/quick_start/#videos "Permanent link") --------------------------------------------------------------------------------------------- You can watch some of the video tutorials available (they might come out of date!): * [Voxel Terrain Tutorial with Godot's voxel tools module using the Smooth Transvoxel method (by Aknakos)](https://www.youtube.com/watch?v=YDHkTJ6Na9U) (17 Jun 2021) * [How To Make Voxel Terrains In Godot (by Tokisan Games)](https://www.youtube.com/watch?v=zfzmcbR1H_0) (4 Nov 2019) * [Godot Voxel Tools (by Gamesfromscratch)](https://www.youtube.com/watch?v=WxZK_Yg5kU0) (25 Jul 2020) Short recipes[¶](https://voxel-tools.readthedocs.io/en/latest/quick_start/#short-recipes "Permanent link") ----------------------------------------------------------------------------------------------------------- The following sections contain basic quick start instructions to get voxel terrains running. For more in-depth information, see the rest of the documentation. Before each example, you may do the following: * Create a new project and a new 3D scene. Give it some light by adding a `DirectionalLight` node, and orientate it so it shines approximately downwards. You can enable `Shadows` too. ### Blocky heightmap terrain using `VoxelTerrain`[¶](https://voxel-tools.readthedocs.io/en/latest/quick_start/#blocky-heightmap-terrain-using-voxelterrain "Permanent link") 1) Add a `VoxelTerrain` node, and adjust the following settings in the inspector: 1.1) Under the `materials` section, create a new `StandardMaterial3D` in the first slot. Click that material, and in the "Vertex Color" category, enable "Use as Albedo" (`vertex_color_as_albedo`). This will give the blocks better shading. 1.2) Click on the `Generator` property: create a new `VoxelGeneratorNoise2D`. Then click on it and set its `Channel` parameter to `TYPE`. Also make sure the `noise` property is assigned to a noise resource. 1.3) Click on the `Mesher` property: create a new `VoxelMesherBlocky`. In the `library` property, create a new `VoxelBlockyLibrary`. In the `models` property, create a new item of type `VoxelBlockyModelEmpty` (this will be "air"). Create another item of type `VoxelBlockyModelCube` (this will be a solid cube). 1.4) Select the terrain node again, and in the `Terrain` menu on top of the viewport, click `Re-generate`. At this point you should start to see a terrain made of cubes appear in the editor viewport. 2) The terrain is not setup to appear in-game yet. Add a `Camera3D` node, and elevate it so it's above the terrain. You may also want to angle it a bit downward to see more of the landscape. 3) Add a `VoxelViewer` node under the camera. When the game runs, this node will tell the voxel engine where to generate voxels, as the camera moves around. 4) Make sure your scene contains an environment and a light, so you can see the terrain in-game (by default the default lighting you see in editor will not apply in game, leaving everything unlit and grey). ![Screenshot of the preview environment menu](https://voxel-tools.readthedocs.io/en/latest/images/add_environment_to_scene.webp) 5) Play the scene: you should see the terrain appear! ![Screenshot of blocky terrain from the quick start guide](https://voxel-tools.readthedocs.io/en/latest/images/quickstart_blocky_terrain_result.webp) You can modify the shape of the terrain by changing noise parameters under the generator. `VoxelMesherBlocky` allows to specify way more than just white cubes: you can define multiple models, with varying textures, materials and shapes, in order to compose a world like you would see in Minecraft for example. ### Large smooth heightmap with overhangs using `VoxelLODTerrain`[¶](https://voxel-tools.readthedocs.io/en/latest/quick_start/#large-smooth-heightmap-with-overhangs-using-voxellodterrain "Permanent link") 1) Add a `VoxelLodTerrain` node, and adjust the following settings in the inspector: 1.1) `Generator`: create a new `VoxelGeneratorNoise`. Then click on it and set its `Channel` parameter to `SDF`. Also make sure the `noise` property is assigned to a noise resource. 1.2) `Mesher`: create a new `VoxelMesherTransvoxel`. 2) At this point you should start to see a smooth, spongy terrain appear in the editor viewport. You might need to look around and zoom out a bit. If you can't see anything, you can force a reload by reopening the scene, or using the menu `Terrain -> Re-generate`. 3) The terrain is not setup to appear in-game yet. Add a `Camera3D` node, and elevate it so it's above the terrain. You may also want to angle it a bit downward to see more of the landscape. 4) Add a `VoxelViewer` node under the camera. When the game runs, this node will tell the voxel engine where to generate voxels, as the camera moves around. 5) Make sure your scene contains an environment and a light, so you can see the terrain in-game (by default the default lighting you see in editor will not apply in game, leaving everything unlit and grey). 6) Play the scene: you should see the terrain appear! ![Screenshot of smooth terrain from the quick start guide](https://voxel-tools.readthedocs.io/en/latest/images/quickstart_smooth_lod_terrain_result.webp) You can modify the shape of the terrain by changing noise parameters under the generator. Painting textures from voxel data is possible, but it's also common to use procedural texturing using a shader. Is Voxel tools for you?[¶](https://voxel-tools.readthedocs.io/en/latest/quick_start/#is-voxel-tools-for-you "Permanent link") ------------------------------------------------------------------------------------------------------------------------------ It's easy to think a project needs voxels, but they are less needed than it sounds. Also, just because there is a 3D grid somewhere in a game doesn't necessarily mean this module is appropriate. This module is more fit to certain cases than others, and will not necessarily focus on every kind of technology or feature using voxels. Here are some reasons why you might not need it: * "I need a procedurally generated world": if you don't need overhangs you can go with a heightmap approach. Heightmaps are faster and easier to work with. * "I need destructible models": voxels in this module are "blobby" or "blocky", they can't represent every possible shape. If you need something precise, you could try more specialized alternatives like CSG nodes or precomputed destruction. * "I need a terrain with overhangs and caves": do you need it to be editable by players? If not, then you can model the terrain in any 3D modeller and optimize it up-front. You can mix heightmaps + 3D models. You might rely on voxels to make the authoring process easier, but in the exported game you will only need the meshes and static colliders. * "I need to make a planet": you can make more efficient planets by stitching 6 spherified heightmaps together. Take a cube where each face is a heightmap, then puff that cube to turn it into a sphere. * "I want to make Minecraft but different and with my own blocks": Minecraft is a lot more than voxels. While the module can replicate basic functionalities, it is more general/low-level than this at the moment, so it doesn't provide a lot of features found in Minecraft out of the box. Alternatively, you could create a mod with [Minetest](https://www.minetest.net/) , which is a more specialized engine. * "I want super small voxels like Teardown or John Lin's sandbox": these games use a very different tech than this module uses. They raytrace voxels in real-time. This module instead uses a classic polygon-based approach. While you could in theory make terrain that looks like that, it won't perform well. * "GridMap sucks": how large do you want your grid to be? How complex are your models? This module's blocky mesher is geared towards very large grids with simple geometry, so it has its own restrictions. --- # Scripting - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting * * * Scripting[¶](https://voxel-tools.readthedocs.io/en/latest/scripting/#scripting "Permanent link") ================================================================================================= This page shows some examples in how to use the scripting API. Editing the terrain[¶](https://voxel-tools.readthedocs.io/en/latest/scripting/#editing-the-terrain "Permanent link") --------------------------------------------------------------------------------------------------------------------- ### Using [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) [¶](https://voxel-tools.readthedocs.io/en/latest/scripting/#using-voxeltool "Permanent link") `VoxelTool` is a simplified API to access and modify voxel data. It is possible to obtain one from any class storing voxels, using the `get_voxel_tool()` function. That function will return a `VoxelTool` tied to the volume you got it from. See [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) for available functions. Note, depending on which class you get it from, subclasses of `VoxelTool` may have more specialized functions. It is possible to store a reference to `VoxelTool` in a member variable, in case you want to access voxels from the same volume many times. It is more efficient, because every call to `get_voxel_tool()` creates a new instance of it. Before you start modifying voxels, make sure you access the right channel. # If you use VoxelMesherBlocky voxel_tool.channel = VoxelBuffer.CHANNEL_TYPE # If you use VoxelMesherTransvoxel voxel_tool.channel = VoxelBuffer.CHANNEL_SDF # If you use VoxelMesherCubes voxel_tool.channel = VoxelBuffer.CHANNEL_COLOR ### Boundary limitation[¶](https://voxel-tools.readthedocs.io/en/latest/scripting/#boundary-limitation "Permanent link") When a terrain is streaming blocks in and out, it is not possible to edit past loaded borders. Either you will get an error, or nothing will happen. You can test if the area you want to access or edit is available by calling `VoxelTool.is_area_editable()`. ### LOD limitation[¶](https://voxel-tools.readthedocs.io/en/latest/scripting/#lod-limitation "Permanent link") Similarly to bounds limitation, when you use LOD with `VoxelLodTerrain`, it is not possible to access or edit voxels beyond the first LOD level. Past this level, voxel data is no longer available at full resolution. ### Editing performance[¶](https://voxel-tools.readthedocs.io/en/latest/scripting/#editing-performance "Permanent link") In general, editing voxels one by one is the slowest. It is ok for actually getting only a few, but if you plan to modify larger areas at once, you may prefer functions that do this in bulk, or copy/paste buffers. See [Access to voxels and multithreading](https://voxel-tools.readthedocs.io/en/latest/performance/) Custom generator[¶](https://voxel-tools.readthedocs.io/en/latest/scripting/#custom-generator "Permanent link") --------------------------------------------------------------------------------------------------------------- You can provide your own voxel generator by extending `VoxelGeneratorScript` in either GDScript, C# or C++. Note custom generators can also be created without scripts, using [VoxelGeneratorGraph](https://voxel-tools.readthedocs.io/en/latest/generators/) ### Example[¶](https://voxel-tools.readthedocs.io/en/latest/scripting/#example "Permanent link") #### With blocky voxels[¶](https://voxel-tools.readthedocs.io/en/latest/scripting/#with-blocky-voxels "Permanent link") Here is how to make a bare bones generator usable with a blocky terrain. Make sure you use `VoxelMesherBlocky` as mesher. Create a standalone script `my_generator.gd` with the following contents: @tool extends VoxelGeneratorScript const channel : int = VoxelBuffer.CHANNEL_TYPE func _get_used_channels_mask() -> int: return 1 << channel func _generate_block(buffer : VoxelBuffer, origin : Vector3i, lod : int) -> void: if lod != 0: return if origin.y < 0: buffer.fill(1, channel) if origin.x == origin.z and origin.y < 1: buffer.fill(1, channel) Note Generator scripts can run directly in the editor with tool mode, **but need extra caution**. For more info, see [tool scripts](https://voxel-tools.readthedocs.io/en/latest/editor/#tool-scripts) . In your terrain scene, add another script to a node, which will setup your generator when the game starts. Code might differ a bit depending on how you structure your scene. extends Node # Or whatever your root node is const MyGenerator = preload("my_generator.gd") # Get the terrain @onready var terrain = $VoxelTerrain func _ready(): terrain.generator = MyGenerator.new() Make sure to have a `VoxelViewer` node in the scene under the camera. You may also want to move it up, look down, and add a `DirectionalLight3D` and `WorldEnvironment` (otherwise everything will look grey). ![Custom stream](https://voxel-tools.readthedocs.io/en/latest/images/custom-stream.jpg) Though `VoxelBuffer.fill()` is probably not what you want to use, the above is a quick example. Generate\_block generally gives you a block of 16x16x16 cubes to fill all at once, so you may also use `VoxelBuffer.set_voxel()` to specify each one individually. #### With smooth voxels[¶](https://voxel-tools.readthedocs.io/en/latest/scripting/#with-smooth-voxels "Permanent link") Getting a similar result with smooth voxels like in the previous example is more tricky, so we'll switch to a different one. First you have to change your mesher to `VoxelMesherTranvoxel`. Next, here is how you could generate ground with varying height: @tool extends VoxelGeneratorScript # Change channel to SDF const channel : int = VoxelBuffer.CHANNEL_SDF func _generate_block(out_buffer : VoxelBuffer, origin_in_voxels : Vector3i, lod : int) -> void: # We'll have to iterate every 3D voxel in the block this time for rz in out_buffer.get_size().z: for rx in out_buffer.get_size().x: # The following part only depends on `x` and `z`, # so moving it out of the innermost loop optimizes things a little. # Get voxel world position. # To account for LOD we multiply local coordinates by 2^lod. # This can be done faster than `pow()` by using binary left-shift. # Y is left out because we'll compute it in the inner loop. var pos_world := Vector3(origin_in_voxels) + Vector3(rx << lod, 0, rz << lod) # Generates infinite "wavy" hills. var height := 10.0 * (sin(pos_world.x * 0.1) + cos(pos_world.z * 0.1)) # Innermost loop for ry in out_buffer.get_size().y: pos_world.y = origin_in_voxels.y + (ry << lod) # This is a cheap approximation for the signed distance of a heightfield var signed_distance := pos_world.y - height # When outputting signed distances, use `set_voxel_f` instead of `set_voxel` out_buffer.set_voxel_f(signed_distance, rx, ry, rz, channel) With signed distance fields, negative values mean "inside" while positive values mean "outside". It is also important to output _gradients_, instead of just setting voxels to either 1 or 0. This is why we can't use `fill` here. In practice you 'll also want to use noise and actual SDF functions. See [Signed Distance Fields](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#signed-distance-fields) . Further optimizations are also possible, for example if you know that the passed block is far enough to intersect any area where land features occur, you could do an early-return that outputs `fill_f(100.0)`. It's as a way to say "there is only air here and it's far from everything". Similarly, you can do `fill_f(-100.0)` to mean "there is only matter in this block and it's far from any surface". ### Thread-safety[¶](https://voxel-tools.readthedocs.io/en/latest/scripting/#thread-safety "Permanent link") Generators are invoked from multiple threads. Make sure your code is thread-safe. If your generator uses resources or exports parameters that you want to change while it might be running, you should make sure they are read-only or copied per thread, so if the resource is modified from outside or another thread it won't disrupt the generator. You can use `Mutex` to enforce single-thread access to variables that can be modified: var _dictionary := {} var _dictionary_mutex := Mutex.new() func _generate_block(...): # ... _dictionary_mutex.lock() var x := 0 if not _dictionary.has(key): _dictionary[key] = x else: x = _dictionary[key] _dictionary_mutex.unlock() # ... However, mutexes must be used with a lot of care: if they are locked a lot of times or remain locked for too long, you could end up limiting performance to one thread (while the other waits for the lock to be released). If you use more than one and lock them in different orders, that can also lead to [deadlocks](https://en.wikipedia.org/wiki/Deadlock) . Using Read-Write locks and thread-locals are good options depending on the situation, unfortunately the Godot script API does not provide this. Careful about lazy-initialization, it can cause crashes if two threads run it at the same time. `Curve` is one of the resources doing that: if you call `interpolate_baked()` and it wasn't baked yet, it will be baked at the very last moment. That involves modifying internal states which might overlap with other threads doing the same thing. Here is an example of working around this: const MountainsCurve : Curve = preload("moutains_curve.tres") # This is called when the generator is created func _init(): # Call `bake()` to be sure it doesn't happen later inside `generate_block()`. MountainsCurve.bake() # ... Custom stream[¶](https://voxel-tools.readthedocs.io/en/latest/scripting/#custom-stream "Permanent link") --------------------------------------------------------------------------------------------------------- Making a custom stream works similarly to a custom generator. You have to extend the class `VoxelStreamScript` and override the methods `_load_block` and `_save_block`. See TODO Script example of a custom stream --- # Streams - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Streams * * * Streams[¶](https://voxel-tools.readthedocs.io/en/latest/streams/#streams "Permanent link") =========================================================================================== `VoxelStream` allows to save and load voxel data to a file or a directory structure, using various kinds of implementations. They don't hold voxel data in memory, they are just an access point to different file formats. Stream types[¶](https://voxel-tools.readthedocs.io/en/latest/streams/#stream-types "Permanent link") ----------------------------------------------------------------------------------------------------- A few different types are available, each with slightly different features. * [VoxelStreamSQLite](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/) is the most featured one, and uses a single SQLite database file. It can save both voxel data and [instancing](https://voxel-tools.readthedocs.io/en/latest/instancing/) data. * [VoxelStreamRegionFiles](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/) is an older one, which works similarly to Minecraft's region system. It saves under multiple files in a folder. It only supports voxel data. * [VoxelStreamScript](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamScript/) is a custom stream that may be implemented using a script. See [Scripting](https://voxel-tools.readthedocs.io/en/latest/scripting/#custom-stream) . There is currently no stream implementation using an existing file format (like `.vox` for example), mainly because the current API expects the ability to load data in chunks compatible with the engine's format. Using streams for savegames[¶](https://voxel-tools.readthedocs.io/en/latest/streams/#using-streams-for-savegames "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------- Streams were created initially to serve as a database for saves. Games using voxel technology for terrain are often persistent, so there has to be a place on disk where to save the changes, and reload them back. The engine can handle near-unlimited terrain size, so there are often situations where loading the entire world in memory is not possible. For that reason, streams are built in such a way they provide data block by block (or "chunks"). Only blocks within the player's view distance will be loaded in memory. When the player moves, blocks far away will get unloaded/saved, while blocks getting closer will be loaded. By default, only modified blocks are saved. However, if the generator you use is too expensive to re-run on demand, or if your world is primarily edited, it can be configured such that every new block will always get saved. This is the case in Minecraft. When voxels are edited, modified blocks are not saved immediately. This is because many edits could keep happening, and trying to save too often could be wasteful. Saving only occurs under the following conditions: * The block gets unloaded when too far away * [save\_modified\_blocks()](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_save_modified_blocks) is called on the terrain node (you may want to call this when the player saves, on a timer, or when quitting the game) You can add minimal saving with this script: extends VoxelTerrain func _ready(): stream = VoxelStreamSQLite.new() stream.database_path = "path/to/save.file" # Note, the directory must exist func _on_tree_exited(): save_modified_blocks() It can get more complex as development progresses. See following sections for details. See also this demo game, which includes one save: [https://github.com/Zylann/voxelgame/tree/master/project/blocky\_game](https://github.com/Zylann/voxelgame/tree/master/project/blocky_game) TODO: Demo handling multiple saves Asynchronous saving[¶](https://voxel-tools.readthedocs.io/en/latest/streams/#asynchronous-saving "Permanent link") ------------------------------------------------------------------------------------------------------------------- While streams have synchronous save/load methods and don't actually depend on terrains, terrains use them _asynchronously_. Loading is performed on different threads, similarly to how procedural generation works in chunks. Saving is also asynchronous, and doesn't block the main thread so the game will not stutter. However, this approach has consequences you usually don't encounter in more "classic" scene loading/saving, and need to be accounted for. ### Knowing when saving is complete[¶](https://voxel-tools.readthedocs.io/en/latest/streams/#knowing-when-saving-is-complete "Permanent link") If you save and quit a "world" for example, saving will remain happening in the background for a little while, even after you destroy the terrain node. The file won't contain the changes for a moment. To handle this, you may wait for all tasks to finish, maybe displaying a waiting screen in the meantime. Check the documentation of [save\_modified\_blocks()](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_save_modified_blocks) for more details. ### Switching saves[¶](https://voxel-tools.readthedocs.io/en/latest/streams/#switching-saves "Permanent link") Another caveat is that changes you do to a stream resource at runtime can be potentially mistaken. For example, let's say you play on a terrain, you save, and want to load another terrain. You could change the path property of your stream to point to another save file/directory, and start a new session. But because saving is asynchronous, saving/loading tasks could still be pending in different threads while you do this. That can cause saves meant for the previous file to end up in the next one. A simple solution to avoid this, is to create a different stream instance, and let the old one finish off as all its asynchronous tasks complete. This guarantees that a new session can't possibly be bothered by asynchronous tasks of the previous. You should also consider _NOT embedding a stream resource inside your scene (like `world.tscn`)_. If saves are dynamically created in game, this is not a good approach, because even if you destroy the nodes from that scene and then re-instantiate it for another session, Godot keeps the resources cached, including the stream, which means you'll end up modifying the same stream as the previous session. So creating and assigning a new stream at runtime is a better option. ### File locking[¶](https://voxel-tools.readthedocs.io/en/latest/streams/#file-locking "Permanent link") Streams remain open, in order to continuously save and load blocks of terrain. Closing and re-opening to save each block would be much slower due to system API calls, and some platforms have to do a lot of filesystem work under the hood. The consequence is that save files will often be locked while they are in use. Notably, they can't be deleted. First, you could wait when saves complete before taking action, or just expect that your file(s) will be locked for a little while after leaving a "world". Second, make sure your stream actually closes. Some approaches are: * 1) Ideally, just let Godot's resource system destroy the stream _once nothing in the game references it_. This is another reason why you should preferably not embed a stream resource in your scenes, because even if there are no instances of that scene in the tree, a variable containing the [PackedScene](https://docs.godotengine.org/en/latest/classes/class_packedscene.html) still references that resource, preventing it from being unloaded. Once all references are gone from your side, the only ones left will be eventual background tasks, that should complete soon after. * 2) Manually modify properties of the stream to make it "close". For example, with [VoxelStreamSQLite](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/) , you can set `database_path` to an empty string (`""`), which will force it to close. However, this will cause pending saves and loads to fail, so you should make sure to do that when saving has completed first (TODO: at the moment, [loads will cause errors too](https://github.com/Zylann/godot_voxel/issues/620#issuecomment-2040255061) but there is no way to "wait" for them. This might be addressed in the future if you want to use method 2, but for now try using method 1) Using streams in the Godot Editor[¶](https://voxel-tools.readthedocs.io/en/latest/streams/#using-streams-in-the-godot-editor "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------- ### Overlap between editor and game[¶](https://voxel-tools.readthedocs.io/en/latest/streams/#overlap-between-editor-and-game "Permanent link") At the moment, streams can run in the editor, but they behave the same as if the game was running. If you modify anything, blocks will eventually get saved under the same conditions as seen earlier. If you want to preserve your game saves, either leave the `stream` property unassigned, or you can assign a "development save" on the stream in the editor. Then, assign a different path from within your game to the real save (using script). If you use the same save files between game and editor, there is a risk of conflict when you run the game: it will try to open files which are already opened and locked by the editor. To workaround this, either use different files, or close the scene before running the game. See [issue 283](https://github.com/Zylann/godot_voxel/issues/283) . ### Closing the game[¶](https://voxel-tools.readthedocs.io/en/latest/streams/#closing-the-game "Permanent link") When you test your game and expect proper saving, prefer closing it normally, instead of using Godot's `Stop` button: ![Screenshot of the Stop button in the Godot Editor](https://voxel-tools.readthedocs.io/en/latest/images/godot_editor_stop_button.webp) This button will [kill the game's process](https://github.com/godotengine/godot/blob/b4e2a24c1f62088b3f7ce0197afc90832fc25009/editor/editor_run.cpp#L358) , without leaving a chance for cleanup (SIGKILL on Linux). That means any pending save tasks will be lost, and caches won't be flushed. If files are in the middle of being written, it can also cause them to get corrupted. Save format specifications[¶](https://voxel-tools.readthedocs.io/en/latest/streams/#save-format-specifications "Permanent link") --------------------------------------------------------------------------------------------------------------------------------- * [Region format](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/) * [Block format](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v4/) * [Instance format](https://voxel-tools.readthedocs.io/en/latest/specs/instances_format_v1/) * [SQLite format](https://voxel-tools.readthedocs.io/en/latest/specs/sqlite_format_v1/) --- # VoxelAStarGrid3D - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelAStarGrid3D * * * VoxelAStarGrid3D[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#voxelastargrid3d "Permanent link") ========================================================================================================================== Inherits: [RefCounted](https://docs.godotengine.org/en/stable/classes/class_refcounted.html) Warning This class is marked as experimental. It is subject to likely change or possible removal in future versions. Use at your own discretion. Grid-based A\* pathfinding algorithm adapted to blocky voxel terrain. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#description "Permanent link") ----------------------------------------------------------------------------------------------------------------- This can be used to find paths between two voxel positions on blocky terrain. It is tuned for agents 2 voxels tall and 1 voxel wide, which must stand on solid voxels and can jump 1 voxel high. No navmesh is required, it uses voxels directly with no baking. However, search radius is limited by an area (50 voxels and above starts to be relatively expensive). At the moment, this pathfinder only considers voxels with ID 0 to be air, and the rest is considered solid. Note: "positions" in this class are expected to be in voxels. If your terrain is offset or if voxels are smaller or bigger than world units, you may have to convert coordinates. Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#methods "Permanent link") --------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [Vector3i\[\]](https://docs.godotengine.org/en/stable/classes/class_vector3i[].html) | [debug\_get\_visited\_positions](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#i_debug_get_visited_positions)
( ) const | | [Vector3i\[\]](https://docs.godotengine.org/en/stable/classes/class_vector3i[].html) | [find\_path](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#i_find_path)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
from\_position, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
to\_position ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#) | [find\_path\_async](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#i_find_path_async)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
from\_position, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
to\_position ) | | [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) | [get\_region](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#i_get_region)
( ) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [is\_running\_async](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#i_is_running_async)
( ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#) | [set\_region](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#i_set_region)
( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html)
box ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#) | [set\_terrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#i_set_terrain)
( [VoxelTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/)
terrain ) | Signals:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#signals "Permanent link") --------------------------------------------------------------------------------------------------------- ### async\_search\_completed( [Vector3i\[\]](https://docs.godotengine.org/en/stable/classes/class_vector3i[].html) path )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#async_search_completed-vector3i-path "Permanent link") Emitted when searches triggered with [find\_path\_async](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#i_find_path_async) are complete. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#method-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- ### [Vector3i\[\]](https://docs.godotengine.org/en/stable/classes/class_vector3i[].html) **debug\_get\_visited\_positions**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#vector3i-debug_get_visited_positions "Permanent link") Gets the list of voxel positions that were visited by the last pathfinding request (relates to how A\* works under the hood). This is for debugging. ### [Vector3i\[\]](https://docs.godotengine.org/en/stable/classes/class_vector3i[].html) **find\_path**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) from\_position, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) to\_position )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#vector3i-find_path-vector3i-from_position-vector3i-to_position "Permanent link") Calculates a path starting from a voxel position to a target voxel position. Those positions should be air voxels just above ground with enough room for agents to fit in. The returned path will be a series of contiguous voxel positions to walk through in order to get to the destination. If no path is found, or if either start or destination position is outside of the search area, an empty array will be returned. You may also use [set\_region](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#i_set_region) to specify the search area. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#) **find\_path\_async**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) from\_position, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) to\_position )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#void-find_path_async-vector3i-from_position-vector3i-to_position "Permanent link") Same as [find\_path](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#i_find_path) , but performs the calculation on a separate thread. The result will be emitted with the [VoxelAStarGrid3D.async\_search\_completed](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#signals) signal. Only one asynchronous search can be active at a given time. Use [is\_running\_async](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#i_is_running_async) to check this. ### [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) **get\_region**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#aabb-get_region "Permanent link") Gets the maximum region limit that will be considered for pathfinding, in voxels. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **is\_running\_async**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#bool-is_running_async "Permanent link") Returns true if a path is currently being calculated asynchronously. See [find\_path\_async](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#i_find_path_async) . ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#) **set\_region**( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) box )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#void-set_region-aabb-box "Permanent link") Sets the maximum region limit that will be considered for pathfinding, in voxels. You should usually set this before calling [find\_path](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#i_find_path) . The larger the region, the more expensive the search can get. Keep in mind voxel volumes scale cubically, so don't use this on large areas (for example 50 voxels is quite big). ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#) **set\_terrain**( [VoxelTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/) terrain )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/#void-set_terrain-voxelterrain-terrain "Permanent link") Sets the terrain that will be used to do searches in. _Generated on Aug 20, 2026_ --- # FastNoise2 - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * FastNoise2 * * * FastNoise2[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#fastnoise2 "Permanent link") ======================================================================================================== Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Wrapper for the [FastNoise2](https://github.com/Auburn/FastNoise2) library. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#description "Permanent link") ----------------------------------------------------------------------------------------------------------- Generates coherent noise with support for SIMD processing, which can speed up generation significantly compared to scalar implementations like [FastNoiseLite](https://docs.godotengine.org/en/stable/classes/class_fastnoiselite.html) . It uses a node-based structure internally for configuration, which is however not editable from within Godot at the moment. Instead, simplified properties are exposed. It possible to edit noise graphs with an external Noise Tool, which can export an encoded node tree as a base64 string. The current integration uses FastNoise2 version 0.10.0-alpha. If you use encoded node trees made with the Noise Tool, it must match that version. After changing properties, you must call [update\_generator](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_update_generator) for the internal graph to be rebuilt and changes to take effect. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#properties "Permanent link") --------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [CellularDistanceFunction](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#enumerations) | [cellular\_distance\_function](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_cellular_distance_function) | CELLULAR\_DISTANCE\_EUCLIDEAN (0) | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [cellular\_index0](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_cellular_index0) | 0 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [cellular\_index1](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_cellular_index1) | 1 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [cellular\_jitter](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_cellular_jitter) | 1.0 | | [CellularReturnType](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#enumerations) | [cellular\_return\_type](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_cellular_return_type) | CELLULAR\_RETURN\_INDEX\_0 (0) | | [String](https://docs.godotengine.org/en/stable/classes/class_string.html) | [encoded\_node\_tree](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_encoded_node_tree) | "" | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [fractal\_gain](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_fractal_gain) | 0.5 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [fractal\_lacunarity](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_fractal_lacunarity) | 2.0 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [fractal\_octaves](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_fractal_octaves) | 3 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [fractal\_ping\_pong\_strength](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_fractal_ping_pong_strength) | 2.0 | | [FractalType](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#enumerations) | [fractal\_type](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_fractal_type) | FRACTAL\_NONE (0) | | [NoiseType](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#enumerations) | [noise\_type](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_noise_type) | TYPE\_OPEN\_SIMPLEX\_2 (0) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [period](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_period) | 64.0 | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [remap\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_remap_enabled) | false | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [remap\_input\_max](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_remap_input_max) | 1.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [remap\_input\_min](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_remap_input_min) | \-1.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [remap\_output\_max](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_remap_output_max) | 1.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [remap\_output\_min](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_remap_output_min) | \-1.0 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [seed](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_seed) | 1337 | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [terrace\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_terrace_enabled) | false | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [terrace\_multiplier](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_terrace_multiplier) | 1.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [terrace\_smoothness](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_terrace_smoothness) | 0.0 | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#methods "Permanent link") --------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#) | [generate\_image](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_generate_image)
( [Image](https://docs.godotengine.org/en/stable/classes/class_image.html)
image, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
tileable ) const | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [get\_noise\_2d\_single](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_get_noise_2d_single)
( [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html)
pos ) const | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [get\_noise\_3d\_single](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_get_noise_3d_single)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
pos ) const | | [SIMDLevel](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#enumerations) | [get\_simd\_level](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_get_simd_level)
( ) const | | [String](https://docs.godotengine.org/en/stable/classes/class_string.html) | [get\_simd\_level\_name](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_get_simd_level_name)
( [SIMDLevel](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#enumerations)
level ) static | | [void](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#) | [update\_generator](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#i_update_generator)
( ) | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#enumerations "Permanent link") ------------------------------------------------------------------------------------------------------------- enum **NoiseType**: * **TYPE\_OPEN\_SIMPLEX\_2** = **0** * **TYPE\_SIMPLEX** = **1** * **TYPE\_PERLIN** = **2** * **TYPE\_VALUE** = **3** * **TYPE\_CELLULAR** = **4** * **TYPE\_ENCODED\_NODE\_TREE** = **5** * **TYPE\_CELLULAR\_VALUE** = **6** enum **FractalType**: * **FRACTAL\_NONE** = **0** * **FRACTAL\_FBM** = **1** * **FRACTAL\_RIDGED** = **2** * **FRACTAL\_PING\_PONG** = **3** enum **CellularDistanceFunction**: * **CELLULAR\_DISTANCE\_EUCLIDEAN** = **0** * **CELLULAR\_DISTANCE\_EUCLIDEAN\_SQ** = **1** * **CELLULAR\_DISTANCE\_MANHATTAN** = **2** * **CELLULAR\_DISTANCE\_HYBRID** = **3** * **CELLULAR\_DISTANCE\_MAX\_AXIS** = **4** enum **CellularReturnType**: * **CELLULAR\_RETURN\_INDEX\_0** = **0** * **CELLULAR\_RETURN\_INDEX\_0\_ADD\_1** = **1** * **CELLULAR\_RETURN\_INDEX\_0\_SUB\_1** = **2** * **CELLULAR\_RETURN\_INDEX\_0\_MUL\_1** = **3** * **CELLULAR\_RETURN\_INDEX\_0\_DIV\_1** = **4** enum **SIMDLevel**: * **SIMD\_NULL** = **0** --- Undefined level. * **SIMD\_SCALAR** = **1** --- Single numbers. Slowest level. * **SIMD\_SSE** = **2** --- x86 CPU processing 4 floats in one instruction. * **SIMD\_SSE2** = **4** --- x86 CPU Processing 4 floats in one instruction, with more instructions supported than SSE. * **SIMD\_SSE3** = **8** --- x86 CPU Processing 4 floats in one instruction, with more instructions supported than SSE3. * **SIMD\_SSSE3** = **16** --- x86 CPU Processing 4 floats in one instruction, with more instructions supported than SSE4. * **SIMD\_SSE41** = **32** --- x86 CPU Processing 4 floats in one instruction, with more instructions supported than SSE41. * **SIMD\_SSE42** = **64** --- x86 CPU Processing 4 floats in one instruction, with more instructions supported than SSE42. * **SIMD\_AVX** = **128** --- x86 CPU Processing 8 floats in one instruction. * **SIMD\_AVX2** = **256** --- x86 CPU Processing 8 floats in one instruction, with more instructions supported than AVX. * **SIMD\_AVX512** = **512** --- x86 CPU Processing 16 floats in one instruction. * **SIMD\_NEON** = **65536** --- ARM CPU processing 4 floats in one instruction. Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------ ### [CellularDistanceFunction](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#enumerations) **cellular\_distance\_function** = CELLULAR\_DISTANCE\_EUCLIDEAN (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#cellulardistancefunction-cellular_distance_function-cellular_distance_euclidean-0 "Permanent link") _(This property has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **cellular\_index0** = 0[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#int-cellular_index0-0 "Permanent link") N-th closest cell used in cellular distance or value calculations. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **cellular\_index1** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#int-cellular_index1-1 "Permanent link") N-th closest cell used as second component in some cellular distance calculations. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **cellular\_jitter** = 1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#float-cellular_jitter-10 "Permanent link") _(This property has no documentation)_ ### [CellularReturnType](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#enumerations) **cellular\_return\_type** = CELLULAR\_RETURN\_INDEX\_0 (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#cellularreturntype-cellular_return_type-cellular_return_index_0-0 "Permanent link") _(This property has no documentation)_ ### [String](https://docs.godotengine.org/en/stable/classes/class_string.html) **encoded\_node\_tree** = ""[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#string-encoded_node_tree "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **fractal\_gain** = 0.5[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#float-fractal_gain-05 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **fractal\_lacunarity** = 2.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#float-fractal_lacunarity-20 "Permanent link") _(This property has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **fractal\_octaves** = 3[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#int-fractal_octaves-3 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **fractal\_ping\_pong\_strength** = 2.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#float-fractal_ping_pong_strength-20 "Permanent link") _(This property has no documentation)_ ### [FractalType](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#enumerations) **fractal\_type** = FRACTAL\_NONE (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#fractaltype-fractal_type-fractal_none-0 "Permanent link") _(This property has no documentation)_ ### [NoiseType](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#enumerations) **noise\_type** = TYPE\_OPEN\_SIMPLEX\_2 (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#noisetype-noise_type-type_open_simplex_2-0 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **period** = 64.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#float-period-640 "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **remap\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#bool-remap_enabled-false "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **remap\_input\_max** = 1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#float-remap_input_max-10 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **remap\_input\_min** = -1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#float-remap_input_min-10 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **remap\_output\_max** = 1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#float-remap_output_max-10 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **remap\_output\_min** = -1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#float-remap_output_min-10 "Permanent link") _(This property has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **seed** = 1337[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#int-seed-1337 "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **terrace\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#bool-terrace_enabled-false "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **terrace\_multiplier** = 1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#float-terrace_multiplier-10 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **terrace\_smoothness** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#float-terrace_smoothness-00 "Permanent link") _(This property has no documentation)_ Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#method-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------- ### [void](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#) **generate\_image**( [Image](https://docs.godotengine.org/en/stable/classes/class_image.html) image, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) tileable )[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#void-generate_image-image-image-bool-tileable "Permanent link") Fills a greyscale image with noise values. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **get\_noise\_2d\_single**( [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) pos )[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#float-get_noise_2d_single-vector2-pos "Permanent link") Generates a single value of 2D noise. Note that generating values one by one will not benefit from SIMD performance as much as generating multiple values at once. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **get\_noise\_3d\_single**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) pos )[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#float-get_noise_3d_single-vector3-pos "Permanent link") Generates a single value of 3D noise. Note that generating values one by one will not benefit from SIMD performance as much as generating multiple values at once. ### [SIMDLevel](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#enumerations) **get\_simd\_level**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#simdlevel-get_simd_level "Permanent link") Gets which SIMD level was detected by the library. This gives an indication of performance on the current CPU, as different models can have different SIMD instructions available. ### [String](https://docs.godotengine.org/en/stable/classes/class_string.html) **get\_simd\_level\_name**( [SIMDLevel](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#enumerations) level )[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#string-get_simd_level_name-simdlevel-level "Permanent link") Gets the name of SIMD level. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#) **update\_generator**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/#void-update_generator "Permanent link") This method must be called after you change properties, so they can take effect. _Generated on Aug 20, 2026_ --- # Smooth terrains - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Smooth terrains * * * Smooth terrains[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#smooth-terrains "Permanent link") ================================================================================================================== It is possible to work with smooth-looking terrains, using signed distance fields and `VoxelMesherTransvoxel`. Signed distance fields[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#signed-distance-fields "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- ### Concept[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#concept "Permanent link") In order to represent smooth terrain, using a grid with points being either 0 or 1 is not enough. Such a grid is good for polygonizing blocky surfaces, but not curves. It could be averaged or blurred somehow, but this would be expensive. For any point in space, a signed distance field (SDF) is a distance to the closest surface. It is "signed" because if the point is below a surface ("inside of something"), that distance becomes negative. That means the surface is defined by all the points for which the SDF is 0. That `0` is usually called the `isolevel`. For example, `1` means we are 1 unit away from the shape. `-1` means we are 1 unit inside the shape. `0` means we are exactly on the shape's surface. SDF is commonly used in raymarching shaders as a way to define volumes. It is also used in the Transvoxel algorithm (a variant of Marching Cubes), which is implemented by this engine. So instead of discrete values, voxels store a sort of smooth "gradient" of distances. ### Technical explanation[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#technical-explanation "Permanent link") Voxels use SDF in 3D, so to help visualizing it, we'll have a look at 2D examples. If we were to represent a sphere with blocky voxels, we would apply the following pseudo-code to every voxel: if distance(center, position) < radius: voxel = 1 else: voxel = 0 Which gives the following: ![Blocky SDF](https://voxel-tools.readthedocs.io/en/latest/images/sdf_example_blocky.webp) Each voxel has binary values, either 1 or 0. But that gives no information about how the transition occurs between "matter" and "air", so if we were to render this using Transvoxel, the result would be: ![SDF sphere blocky](https://voxel-tools.readthedocs.io/en/latest/images/sdf_sphere_blocky.webp) It is kinda blocky. Now, we might indeed want this result (see section about shaders). But if we dont, we will need to change the code. In fact, if we walk back one step, the answer is already there: voxel = distance(origin, position) - radius This is the signed distance of a sphere. Here shown normalized, so voxels close to `0` are grey: ![True SDF](https://voxel-tools.readthedocs.io/en/latest/images/sdf_example_true.webp) Every voxel now contains a slowly changing gradient, so when Transvoxel marches through all cells to find the surface, it will see much more precise variations than just `0` or `1`, which allows it to produce smooth polygons. ![SDF sphere blocky](https://voxel-tools.readthedocs.io/en/latest/images/sdf_sphere_smooth.webp) ### SDF encoding[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#sdf-encoding "Permanent link") #### Clamping[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#clamping "Permanent link") This engine allows to edit voxels and save them. Storing true SDF can be expensive for games. For example, because it is a _distance_, if a player builds a small tower on the ground, we would have to keep voxels up to date far away in the sky, just because the tower made the ground slightly closer to them. So in practice, it is not required to deal with exact SDF. We only need something that's good enough, so the gradients can vary at different speeds and modifications can stay "local". Voxels far away in the sky are actually not interesting for us. The surface is what we really need. So we can clamp distances, such that voxels far enough from the surface will have the same value. And if a whole chunk has the same value, it can be optimized out as "uniform". So the sphere SDF we've seen earlier would actually look like this in the data: ![Clamped SDF](https://voxel-tools.readthedocs.io/en/latest/images/sdf_example_clamped.webp) Over multiple chunks, all regions without a gradient will take very little space in memory. #### Quantization[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#quantization "Permanent link") To save further memory, this engine does not store SDF using 32-bit `float` numbers (not by default). Instead, it uses either 8-bit or 16-bit integers, which are interpreted as fixed-point decimal numbers. Internally, a practical range of value is chosen to distribute a more limited amount of decimal values. By default, the engine uses 16-bit. | Depth | Minimum | Maximum | Step | | --- | --- | --- | --- | | 8-bit | \-10.0 | 10.0 | ~0.078 | | 16-bit | \-500.0 | 500.0 | ~0.015 | When set to 32-bit, buffers will use `float` numbers directly. In practice, it means that when you store signed distances into a `VoxelBuffer`, there will be a bit of imprecision when getting the values back. When using LOD, 16-bit ranges that can extend relatively far is useful to keep gradients going as chunks become larger and larger. With 8-bit, gradients would become so relatively small that the results would start to get clamped, resulting in blocky appearance. #### Links[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#links "Permanent link") For more information about SDF and other domains where they are used, you can check out some of these videos: * [Glyphs, shapes, fonts, signed distance fields. (Martin Donald)](https://www.youtube.com/watch?v=1b5hIMqz_wM) * [Coding Adventure: Marching Cubes (Sebastian Lague)](https://www.youtube.com/watch?v=M3iI2l0ltbE) * [Painting a Cartoon Girl using Mathematics (Inigo Quilez)](https://www.youtube.com/watch?v=8--5LwHRhjk) * [Code for a bunch of SDF functions and operations (Inigo Quilez)](https://iquilezles.org/articles/distfunctions/) Transvoxel[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#transvoxel "Permanent link") -------------------------------------------------------------------------------------------------------- ### Definition[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#definition "Permanent link") Transvoxel is an extension of Marching Cubes that can be used to create smooth meshes from voxel data. The advantage of this algorithm is to integrate stitching of different levels of details without causing cracks, so it can be used to render very large landscapes. For more information, visit [https://transvoxel.org/](https://transvoxel.org/) . ### Smooth stitches in vertex shader[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#smooth-stitches-in-vertex-shader "Permanent link") Transvoxel uses special meshes to stitch blocks of different level of detail. However the seams may still be visible as occasional sharp little steps. To smooth this out a bit, meshes produced by `VoxelMesherTransvoxel` contain extra information in their `CUSTOM0` attribute, telling how to move vertices to smooth those steps, and make room for them in the regular part of the mesh. Create and setup a `ShaderMaterial` on your terrain, and integrate this snippet to it: // This uniform is assigned internally by the voxel engine. // Layout: 00000000 00000000 0000000 00xxyyzz // Where: // - xx are respectively -x and x transitions, // - yy are respectively -y and y transitions, // - zz are respectively -z and z transitions, uniform int u_transition_mask; float get_transvoxel_secondary_factor(int idata) { int transition_mask = u_transition_mask & 0xff; int cell_border_mask = (idata >> 0) & 63; // Which sides the cell is touching int vertex_border_mask = (idata >> 8) & 63; // Which sides the vertex is touching // If the vertex is near a side where there is a low-resolution neighbor, // move it to secondary position int m = transition_mask & cell_border_mask; float t = float(m != 0); // If the vertex lies on one or more sides, and at least one side has no low-resolution neighbor, // don't move the vertex. t *= float((vertex_border_mask & ~transition_mask) == 0); return t; } vec3 get_transvoxel_position(vec3 vertex_pos, vec4 fdata) { int idata = floatBitsToInt(fdata.a); // Move vertices to smooth transitions float secondary_factor = get_transvoxel_secondary_factor(idata); vec3 secondary_position = fdata.xyz; vec3 pos = mix(vertex_pos, secondary_position, secondary_factor); // If the mesh combines transitions and the vertex belongs to a transition, // when that transition isn't active we change the position of the vertices so // all triangles will be degenerate and won't be visible. // This is an alternative to rendering them separately, // which has less draw calls and less mesh resources to create in Godot. // Ideally I would tweak the index buffer like LOD does but Godot does not // expose anything to use it that way. int itransition = (idata >> 16) & 0xff; // Is the vertex on a transition mesh? float transition_cull = float(itransition == 0 || (itransition & u_transition_mask) != 0); pos *= transition_cull; return pos; } void vertex() { VERTEX = get_transvoxel_position(VERTEX, CUSTOM0); //... } Research issue which led to this code: [Issue #2](https://github.com/Zylann/godot_voxel/issues/2) Texturing[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#texturing "Permanent link") ------------------------------------------------------------------------------------------------------ Texturing a voxel surface can be more difficult than classic 3D meshes, because the geometry isn't known in advance, and can have almost any shape. So in this section we'll review ways to solve UV-mapping, procedural techniques and blending textures from voxel data. ### Triplanar mapping[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#triplanar-mapping "Permanent link") Classic UV-mapping cannot be used on smooth voxel surfaces, because of the arbitrary shapes it can contain. In fact, smooth meshers don't provide any proper UV. So instead, we can use triplanar mapping. The method involves projecting the texture on to the part of object that directly faces the X-axis. Then projecting it on the sides that directly face the Y-axis. Then again for the Z-axis. The edges of these projections are then blended together with a specified sharpness. Look at how the brick textures are blended together on the top right sphere. ![Triplanar mapping image](https://voxel-tools.readthedocs.io/en/latest/images/triplanar_example.webp) Read about [triplanar mapping in Godot](https://docs.godotengine.org/en/latest/tutorials/3d/standard_material_3d.html#triplanar-mapping) . It is also possible to choose a different texture for the 3 axes. Here's a shader that supports two materials, such as grass on the top and rock on the sides, each with triplanar mapped albedo, normal and AO maps, then blended together based on if their normal faces the upward direction or the sides. You can find a working example in the [demo](https://github.com/Zylann/voxelgame) , or see the [shader](https://github.com/Zylann/voxelgame/blob/godot4/project/smooth_terrain/transvoxel_terrain.gdshader) itself (triplanar functions defined here https://github.com/Zylann/voxelgame/blob/godot4/project/smooth\_terrain/shaders/triplanar.gdshaderinc). In the shader parameters, add your two albedo maps, and optionally normal, and AO maps. Then play with the `AB Mix 1` and `AB Mix 2` sliders to adjust how the top and sides blend together. The other settings should be self explanatory. The screenshot below also has a little bit of fog and far DOF added. ![Textured terrain](https://voxel-tools.readthedocs.io/en/latest/images/textured-terrain.jpg) ### Procedural texturing[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#procedural-texturing "Permanent link") Voxel data is heavy, so if texturing rules of your game are simple enough to be determined from a shader and don't impact gameplay, you won't need to define any extra data in the voxels. For example, you can check the normal of a terrain surface to blend between a grass and rock texture, and use snow above a certain height. ### Voxel texturing[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#voxel-texturing "Permanent link") If on the other hand you really need texturing to be a property of voxels themselves, it would be necessary to store that information in them somehow. This means voxel data will take more space, and more volumetric processing has to occur accounting for that. Voxel texturing can be split in 2 parts: * The voxel format: what voxels actually contain. * The vertex format: what is used in meshes built from voxel data, so that shaders can render it. ### Voxel texture formats[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#voxel-texture-formats "Permanent link") #### Single[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#single "Permanent link") The simplest format is to give every voxel an 8-bit index that indicates what texture it has. This allows you to choose from a pool of 256 possible textures. This is usually way more than enough for smooth terrains. This format cannot represent gradients, so painting has no falloff. This data is stored in the [INDICES](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_INDICES) channel, using a depth of 8-bits. Note This mode is the easiest, but wasn't the first to be implemented. So the default voxel format isn't suitable for it. To fix this, assign a new [VoxelFormat](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/) resource to your terrain, and change its `indices_depth` to `8-bit`. Then make sure your mesher has its texture mode set to `Single`. In some cases, you may also configure your generator to output that format as well (notably [VoxelGeneratorGraph](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/) ). Editing voxel textures with that format is as simple as editing "blocky voxels". So editing functions can be used with the [SET](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_MODE_SET) mode. # Paints texture 2 in a sphere area (does not create matter) voxel_tool.mode = VoxelTool.MODE_SET voxel_tool.channel = VoxelBuffer.CHANNEL_INDICES voxel_tool.value = 2 voxel_tool.do_sphere(hit_position, radius) Note `VoxelTool` has a `TEXTURE` mode and as `texture_index` property, but these are currently only used with `Mixel4`. You should not use them when editing `Single` texture data. #### Mixel4[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#mixel4 "Permanent link") Another approach consists in storing multiple indices in every voxel, and how much of each of those it has, using weights. This allows to define gradients since a stretch of land can then gradually transition between voxels having little to more of a certain texture, while other textures decrease. The implementation can store up to 4 different textures per voxel. This format however has a lot of drawbacks: it is much heavier and complicated to manipulate. The implementation also limits texture count to 16. The data for the 4 textures (`a`, `b`, `c`, `d`) is encoded over two channels, [INDICES](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_INDICES) and [WEIGHTS](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_WEIGHTS) , both using a depth of 16 bits. So each texture only has 4 bits of precision. 1st byte 2nd byte INDICES: aaaa bbbb cccc dddd WEIGHTS: aaaa bbbb cccc dddd By default, these channels default to indices `(0,1,2,3)` and weights `(1,0,0,0)`, meaning voxels always start with texture `0`. Another rule is that indices must not appear twice (for example, indices `(0,1,1,1)` are invalid). If an index appears twice, in particular with different weights, it can cause ambiguous calculations. To edit such format, you have to use the [TEXTURE\_PAINT](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_MODE_TEXTURE_PAINT) mode. # Paints texture 2 in a sphere area (does not create matter) voxel_tool.mode = VoxelTool.MODE_TEXTURE_PAINT voxel_tool.texture_index = 2 voxel_tool.set_texture_opacity = 1.0 voxel_tool.do_sphere(hit_position, radius) It is possible to set mixel values directly with `VoxelTool.set_voxel` but it is up to you to pack them properly. You may use `VoxelTool` helper functions to encode/decode these values: * [vec4i\_to\_u16\_indices](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_vec4i_to_u16_indices) * [color\_to\_u16\_weights](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_color_to_u16_weights) * [u16\_indices\_to\_vec4i](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_u16_indices_to_vec4i) * [u16\_weights\_to\_color](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_u16_weights_to_color) It is also possible to generate this in `VoxelGeneratorGraph` using special outputs, but it still requires a bit of math to produce valid data. See also this [painting demo](https://github.com/Zylann/voxelgame/tree/master/project/smooth_materials) . ### Mesh data[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#mesh-data "Permanent link") Currently, all voxel texture formats are combined into the same vertex format: when calculating every marching cube cell, the mesher gathers the most-represented textures over the corresponding voxels, and stores the result in vertex data. This format is referred to as `S4` in `VoxelMesherTransvoxel`, as it gathers groups of 4 textures. The mesher will include texturing information in the `CUSTOM1` attribute of vertices. Contrary to voxel values, the packed information will have 8 bits of precision: * `CUSTOM1.x` will contain 4 indices, encoded as 4 bytes, which can be obtained by reinterpreting the float number as an integer and using bit-shifting operators. * `CUSTOM1.y` will contain 4 weights, again encoded as 4 bytes. Each index tells which texture needs to be used, and each weight respectively tells how much of that texture should be blended. It is essentially the same as a classic color splatmap, except textures can vary, which allows for more than 4 possible textures. One minor downside is that you cannot blend more than 4 textures per voxel, so if this happens, it might cause artifacts. But in practice, it is assumed this case is so infrequent it can be ignored. #### Shader[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#shader "Permanent link") A shader is necessary to render voxel textures using the data encoded in vertices. If you can have more than 4 different textures, it is also preferable for your textures to be in a [Texture2DArray](https://docs.godotengine.org/en/stable/classes/class_texture2darray.html) . Here is the shader code you will need: shader_type spatial; // Textures should preferably be in a Texture2DArray, so looking them up is cheap uniform sampler2DArray u_texture_array : source_color; // We'll need to pass data from the vertex shader to the fragment shader varying vec4 v_indices; varying vec4 v_weights; varying vec3 v_normal; varying vec3 v_pos; // We'll use a utility function to decode components. // It returns 4 values in the range [0..255]. vec4 decode_8bit_vec4(float v) { uint i = floatBitsToUint(v); return vec4( float(i & uint(0xff)), float((i >> uint(8)) & uint(0xff)), float((i >> uint(16)) & uint(0xff)), float((i >> uint(24)) & uint(0xff))); } // A voxel mesh can have overhangs in any direction, // so we may have to use triplanar mapping functions. vec3 get_triplanar_blend(vec3 world_normal) { vec3 blending = abs(world_normal); blending = normalize(max(blending, vec3(0.00001))); // Force weights to sum to 1.0 float b = blending.x + blending.y + blending.z; return blending / vec3(b, b, b); } vec4 texture_array_triplanar(sampler2DArray tex, vec3 world_pos, vec3 blend, float i) { vec4 xaxis = texture(tex, vec3(world_pos.yz, i)); vec4 yaxis = texture(tex, vec3(world_pos.xz, i)); vec4 zaxis = texture(tex, vec3(world_pos.xy, i)); // blend the results of the 3 planar projections. return xaxis * blend.x + yaxis * blend.y + zaxis * blend.z; } void vertex() { // Indices are integer values so we can decode them as-is v_indices = decode_8bit_vec4(CUSTOM1.x); // Weights must be in [0..1] so we divide them v_weights = decode_8bit_vec4(CUSTOM1.y) / 255.0; v_pos = VERTEX; v_normal = NORMAL; //... } void fragment() { // Define a texture scale for convenience. // We can use an array instead if different scales per index is needed. float uv_scale = 0.5; // Sample the 4 blending textures, all with triplanar mapping. // We can re-use the same triplanar blending factors for all of them so separating that part // of the function improves performance a little. vec3 blending = get_triplanar_blend(v_normal); vec3 col0 = texture_array_triplanar(u_texture_array, v_pos * uv_scale, blending, v_indices.x).rgb; vec3 col1 = texture_array_triplanar(u_texture_array, v_pos * uv_scale, blending, v_indices.y).rgb; vec3 col2 = texture_array_triplanar(u_texture_array, v_pos * uv_scale, blending, v_indices.z).rgb; vec3 col3 = texture_array_triplanar(u_texture_array, v_pos * uv_scale, blending, v_indices.w).rgb; // Get weights and make sure they are normalized. // We may add a tiny safety margin so we can afford some degree of error. vec4 weights = v_weights; weights /= (weights.x + weights.y + weights.z + weights.w + 0.00001); // Calculate albedo vec3 col = col0 * weights.r + col1 * weights.g + col2 * weights.b + col3 * weights.a; ALBEDO = col; //... } ![Smooth voxel painting prototype](https://voxel-tools.readthedocs.io/en/latest/images/smooth_voxel_painting_on_plane.webp) Note If you want to use `Mixel4` but only need 4 textures, then you can leave indices to their default values (which contains `0,1,2,3`) and only use weights. When using `VoxelTool`, you may only use texture indices 0, 1, 2 or 3. Texture arrays are less relevant in this case. ### Recommended Reading[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#recommended-reading "Permanent link") * [Shading Index](https://docs.godotengine.org/en/stable/tutorials/shading/index.html) - tutorials and the shader language API * Shader API Reference - some of the most frequently accessed references * [Shading Language](https://docs.godotengine.org/en/stable/tutorials/shading/shading_reference/shading_language.html) * [SpatialShader](https://docs.godotengine.org/en/stable/tutorials/shading/shading_reference/spatial_shader.html) Shading[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#shading "Permanent link") -------------------------------------------------------------------------------------------------- By default smooth voxels also produce smooth meshes by sharing vertices. This also contributes to meshes being smaller in memory. ### Low-poly / flat-shaded look[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#low-poly-flat-shaded-look "Permanent link") It is currently not possible to make the mesher produce vertices with split flat triangles, but you can use this in your fragment shader. When using Vulkan: NORMAL = normalize(cross(dFdy(VERTEX), dFdx(VERTEX))); When using OpenGL: NORMAL = normalize(cross(dFdx(VERTEX), dFdy(VERTEX))); ![Flat shading](https://voxel-tools.readthedocs.io/en/latest/images/flat_shading.webp) ### Blocky look[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#blocky-look "Permanent link") It is also possible to give a "blocky" look to "smooth" voxels: ![Flat shading](https://voxel-tools.readthedocs.io/en/latest/images/blocky_sdf.webp) This can be done by saturating SDF values in the voxel generator: they have to be always -1 or 1, without transition values. Since values are clamped when using `set_voxel_f`, multiplying by a large number also works. Built-in basic generators might not have this option, but you can do it if you use your own generator script or `VoxelGeneratorGraph`. You may also make shading hard-edged in your shader for better results. Shader API reference[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#shader-api-reference "Permanent link") ---------------------------------------------------------------------------------------------------------------------------- If you use a `ShaderMaterial` on a voxel node, the module will recognize some uniform names (shader parameters) to provide extra information. Some are necessary for features to work. | Parameter name | Type | Description | | --- | --- | --- | | `u_lod_fade` | `vec2` | Information for progressive fading between levels of detail. `x` is fading progress: it will go from 0.0 to 1.0 during the transition. `y` is fading direction: `1.0` means fade in, `0.0` means fade out. Only available with `VoxelLodTerrain`. See [Lod fading](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#lod-fading) | | `u_block_local_transform` | `mat4` | Transform of the rendered block, local to the whole volume, as they may be rendered with multiple meshes. Useful if the volume is moving, to fix triplanar mapping. Only available with `VoxelLodTerrain` at the moment. | | `u_voxel_cell_lookup` | `usampler2D` | 3D `RG8` texture where each pixel contains a cell index packed in bytes of `R` and part of `G` (`r + ((g & 0x3f) << 8)`), and an axis index in 2 bits of `G` (`g >> 6`). The position to use for indexing this texture is relative to the origin of the mesh. The texture is 2D and square, so coordinates may be computed knowing the size of the mesh in voxels. Will only be assigned in meshes using detail texturing of [normalmaps](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#detail-rendering)
. | | `u_voxel_normalmap_atlas` | `sampler2D` | Texture atlas where each tile contains a model-space normalmap (it is not relative to surface, unlike common normalmaps). Coordinates may be computed from `u_voxel_cell_lookup` and `u_voxel_virtual_texture_tile_size`. UV orientation is similar to triplanar mapping, but the axes are known from the information in `u_voxel_cell_lookup`. Will only be assigned in meshes using detail texturing of [normalmaps](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#detail-rendering)
. | | `u_voxel_virtual_texture_tile_size` | `int` | Resolution in pixels of each tile in `u_voxel_normalmap_atlas`. | | `u_voxel_cell_size` | `float` | Size of one cubic cell in the mesh, in model space units. Will be > 0 in voxel meshes having [normalmaps](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#detail-rendering)
. | | `u_voxel_block_size` | `int` | Size of the cubic block of voxels that the mesh represents, in voxels. | | `u_voxel_virtual_texture_fade` | `float` | When LOD fading is enabled, this will be a value between 0 and 1 for how much to mix in detail textures such as `u_voxel_normalmap_atlas`. They take time to update so this allows them to appear smoothly. The value is 1 if fading is not enabled, or 0 if the mesh has no detail textures. | | `u_voxel_virtual_texture_offset_scale` | `vec4` | Used in LOD terrains where normalmaps are enabled. Contains a transformation to apply when sampling `u_voxel_cell_lookup` and `u_voxel_normalmap_atlas`. `x`, `y` and `z` contain an offset, and `w` contain a scale. This is relevant when textures for the current mesh aren't ready yet, so it falls back on a parent LOD: parent meshes are larger, so we need to sample a sub-region. | | `u_transition_mask` | `int` | When using `VoxelMesherTransvoxel`, this is a bitmask storing informations about neighboring meshes of different levels of detail. If one of the 6 sides of the mesh has a lower-resolution neighbor, the corresponding bit will be `1`. Side indices are in order `-X`, `X`, `-Y`, `Y`, `-Z`, `Z` and are stored in the first byte. Layout: `00000000 00000000 00000000 00xxyyzz`. See [smooth stitches in vertex shaders](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#smooth-stitches-in-vertex-shader)
. | | `u_voxel_lod_info` | `int` | Will be assigned to a combination of the LOD index of the block and the total number of LODs. Layout: `000000 000000 cccccccc iiiiiiii` where `c` is LOD count and `i` is LOD index. Mainly intented for debugging. | Level of detail (LOD)[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#level-of-detail-lod "Permanent link") ---------------------------------------------------------------------------------------------------------------------------- `VoxelLodTerrain` implements dynamic level of detail for smooth terrain. ### Description[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#description "Permanent link") LOD (Level Of Detail) is a technique used to change the amount of geometry dymamically, such that meshes close to the viewer have high definition, while meshes far from the viewer are simplified down. This aims at improving performance. ![LOD example](https://voxel-tools.readthedocs.io/en/latest/images/lod_example.webp) Note Careful: in this engine, `LOD` _levels_ are frequently represented with numbers from `0` to `N-1`, where `N` is the number of LODs. `0` is the _highest level of detail_, while LOD `1`, `2` etc up to `N-1` are _lower levels of detail_. ![Illustration of level of detail with a grid of voxels](https://voxel-tools.readthedocs.io/en/latest/images/lod_density_schema.webp) When going from LOD `i` to `i+1`, voxels and blocks double in size, covering more space. However resolution of blocks doesn't change, so detail density is lower and consumes less resources. ### Octrees[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#octrees "Permanent link") LOD is implemented using multiple parented grids, each with blocks twice the size of their children. Blocks of the root grid (lowest LOD) can be thought of an octree: it may be subdivided into 8 smaller blocks in the child grid, which themselves can be subdivided in 8 more etc, until reaching LOD0, maximum level of detail. Subdivision occurs as the viewer gets closer. The threshold upon which it happens is controlled with the `lod_distance` property. It represents how far LOD0 will spread around the viewer. It may also affect how far other LODs will go, so it controls quality overall. Similarly to `VoxelTerrain`, as the viewer moves around, blocks of every grid are loaded in front and those getting too far are unloaded. This allows to keep support for "infinite" terrain, without having to setup a single octree with unnecessary depth levels. So in a sense, there are multiple "octrees". The size of the largest grid around the viewer depends on two factors: * The `view_distance` parameter of `VoxelLodTerrain` * The `view_distance` parameter on `VoxelViewer`. The final view distance is calculated as the minimum of both, clipped with bounds of the terrain. #### Streaming systems[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#streaming-systems "Permanent link") There are currently multiple systems handling how LOD blocks are loaded around viewers. This is the case for legacy reasons. Each has different behavior and features. It can be selected under the Advanced category of `VoxelLodTerrain`, as `streaming_system`. * `Octree`: original system. Uses explicit octree data structures which are traversed regularly, loading blocks in a spherical pattern. Has got more testing. However, it only supports one viewer. If multiple viewers are in the scene, it will pick one but there is no guarantee which. Due to regular traversal, it might not be well-suited for large amount of blocks (large `lod_distance`). * `Clipbox`: Loads blocks in concentric boxes and updates only differences as viewers move, similarly to `VoxelTerrain`. It was added to bring support for multiple viewers and address some shortcomings of the Octree system, in regards to multiplayer. It might load blocks in a less precise pattern than octrees, due to having to conform to boxes. The name is made up, and was chosen in reference to "clipmaps" from heightmap terrains, which look similar. In the editor, debug drawing "gizmos" can be shown in the `Terrain` menu. Some will only show anything depending on the selected streaming system. ### Number of LODs[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#number-of-lods "Permanent link") Increasing the number of LODs allows the terrain to have larger blocks, which in turns allows to increase view distance. It does not actually make `LOD0` sharper, it goes the other way around, adding terrain further away (if you expected otherwise, maybe you need to tweak your generator to produce larger shapes, reduce voxel size or change the scales of your game which might be too small). You might notice the grid changes size if you change LOD count: this is because it rounds to the current `view_distance`. Reducing the number of LODs reduces the size of the biggest blocks, however it also means there will be much more of them to fill the grid up to `view_distance`. Make sure to keep a good sweetspot between LOD count and `view_distance` so that the density of blocks is not too high. If you are not making an infinite terrain, you may give it fixed bounds with the `bounds` property, as well as a very large view distance so it stays in view. `bounds` will be rounded to octree size: for example, with 4 LODs and mesh block size of 16, LOD0 blocks will be 16, LOD1 will be 32, LOD2 will be 64... and LOD3 (the biggest) will be 128. Since the current implementation keeps at minimum 8 blocks around the origin, optimal bounds for this setup would be 256. ![Screenshot of fixed bounds LOD terrain](https://voxel-tools.readthedocs.io/en/latest/images/fixed_bounds_octrees.webp) Following the same logic, fixed bounds of 512 is optimal with 5 LODs, 1024 is optimal with 6 LODs and so on. This is based on mesh block size of `16`, so if you set it to `32`, you may set one less LOD since meshes are twice as big. For information about LOD behavior in the editor, see [Camera options in editor](https://voxel-tools.readthedocs.io/en/latest/editor/#camera-options) . ### Voxel size[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#voxel-size "Permanent link") Currently, the size of voxels is fixed to 1 space unit. It might be possible in a future version to change it. For now, a workaround is to scale down the node. However, make sure it is a uniform scale, and careful not to scale too low otherwise it might blow up. `scale` from Node3D must not be confused with the concept of _size_. If you change `scale`, _it will also scale the voxel grid_, view distances, all the dimensions you might have set in generators, and of course it will apply to child nodes as well. The result will _look the same_, just bigger, no more details. So if you want something larger _with more details as a result_, it is recommended to change these sizes instead of scaling everything. For example, if your generator contains a sphere and Perlin noise, you may change the radius of the sphere and the frequency/period of the noise instead of scaling the node. Doing it this way preserve the size of voxels and so it preserves accuracy. Godot also allows you to scale non-uniformly, but it's not recommended (might cause collision issues too). ### Full load mode (aka turning off data streaming)[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#full-load-mode-aka-turning-off-data-streaming "Permanent link") LOD applies both to meshes and to voxel data, keeping memory usage relatively constant. Depending on your settings, distant voxels will not load full-resolution data. Only full-resolution voxels can be edited, so that means you can only modify terrain in a limited distance around the viewer. If this limitation isn't suitable for your game, a workaround is to enable `full_load_mode`. This will load all edited chunks present in the `stream` (if any), such that all the data is available and can be edited anywhere without wait. Non-edited chunks will cause the generator to be queried on the fly instead of being cached. Because data streaming won't take place, keep in mind more memory will be used the more edited chunks the terrain contains. ### LOD fading[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#lod-fading "Permanent link") LOD changes can introduce some mild "popping" in the landscape, which might be a bit disturbing. One way to attenuate this problem is to fade meshes when they switch from two different levels of details. When a "parent" mesh subdivides into higher-resolution "child" meshes, they can be both rendered at the same time for a brief period of time, while the parent fades out and the children fade in, and vice-versa. This trick requires you to use a `ShaderMaterial` on `VoxelLodTerrain`, as the rendering part needs an extra bit of code inside the fragment shader. `VoxelLodTerrain` has a property `lod_fade_duration`, expressed in seconds. By default it is `0`, which makes it inactive. Setting it to a small value like `0.25` will enable it. In your shader, add the following uniform: // This is recognized and assigned automatically by the voxel node uniform vec2 u_lod_fade; Add also this function (unless you have it already): float get_hash(vec2 c) { return fract(sin(dot(c.xy, vec2(12.9898,78.233))) * 43758.5453); } And _at the end_ of `fragment()`, add this: // Discard pixels progressively. // It has to be last to workaround https://github.com/godotengine/godot/issues/34966 float h = get_hash(SCREEN_UV); if (u_lod_fade.y > 0.5) { // Fade in if (u_lod_fade.x < h) { discard; } } else { // Fade out if (u_lod_fade.x > h) { discard; } } Note: this is an example of implementation. There might be more optimized ways to do it. This will discard such that pixels of the two meshes will be complementary without overlap. `discard` is used so the mesh can remain rendered in the same pass (usually the opaque pass). This technique has some limitations: * Shadow maps still create self-shadowing in cases the faded meshes are far enough from each other. While both meshes are rendered to cross-fade, one of them will eventually project shadows on the other. This creates a lot of noisy patches. Turning off shadows from one of them does not fix the other, and turning shadows off will make them pop. I haven't found a solution yet. See [comment on Godot proposal #692](https://github.com/godotengine/godot-proposals/issues/692#issuecomment-782331429) ### Detail rendering[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#detail-rendering "Permanent link") LOD decimates geometric details quite fast in the distance. It can be tuned up, but it quickly gets very expensive to generate and render a lot of polygons. An alternative is to generate normalmaps instead for medium/far meshes, to give the illusion of detail on otherwise flat polygons. This engine contains an implementation of such a technique adapted to voxel meshes (thanks to [Victor Careil](https://twitter.com/phyronnaz/status/1544005424495607809) for the insight!), so it can work even with overhangs. Here is a landscape without the feature: ![Landscape without detailed normals](https://voxel-tools.readthedocs.io/en/latest/images/distance_normals_off.webp) With the feature: ![Landscape with detailed normals](https://voxel-tools.readthedocs.io/en/latest/images/distance_normals_on.webp) The number of polygons is the same: ![Landscape wireframe](https://voxel-tools.readthedocs.io/en/latest/images/distance_normals_wireframe.webp) This can be turned on in the inspector when using `VoxelLodTerrain`. The cost is slower mesh generation and more memory usage to store normalmap textures. This feature is only available in `VoxelLodTerrain`. It also works best with data streaming turned off (`full_load_mode_enabled`), because being able to see all details from far away requires to not unload edited blocks. It will still use the generator if data streaming is on, but you won't see edited regions. Despite improving detail at lower cost than geometry, detail rendering is significantly more expensive than generating regular blocks. Several ways to optimize it are: * Tweak tile sizes and LOD levels. The bigger tiles are, the higher the quality, but the more expensive it gets. Also the feature is usually not doing much if used at LODs 0 and 1, so usually a good default is to begin at LOD 2, with minimum tile size 4 and maximum 16. * Use a simplified version of the `VoxelGenerator`. It is possible to override the generator that will be used to compute normalmaps, with `VoxelLodTerrain.set_normalmap_generator_override`. A typical use case is when the generator can produce caves. Caves don't have enough impact on surface visuals, so they could be ignored beyond a certain LOD level. * Use SIMD noise. Noise is often the biggest bottleneck. In general, SIMD noise such as `FastNoise2` will perform better. #### Shader[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#shader_1 "Permanent link") Rendering these normals requires special shader code in your terrain material. // NOTE: this is not a full shader code, just the part of it required for this feature // TODO Godot is not binding integer samplers properly. // See https://github.com/godotengine/godot/issues/57841 // TODO Workaround using float texelFetch doesnt't work either... // See https://github.com/godotengine/godot/issues/31732 //uniform usampler2D u_voxel_cell_lookup; uniform sampler2D u_voxel_cell_lookup : filter_nearest; uniform sampler2D u_voxel_normalmap_atlas; uniform int u_voxel_virtual_texture_tile_size; uniform float u_voxel_cell_size; uniform int u_voxel_block_size; // This is used when falling back on a detail texture from a parent mesh. // The texture will cover a larger cube, so we use this information // to query only inside a sub-region. // (x, y, z) is offset, (w) is scale. uniform vec4 u_voxel_virtual_texture_offset_scale; varying vec3 v_vertex_pos_model; vec2 pad_uv(vec2 uv, float amount) { return uv * (1.0 - 2.0 * amount) + vec2(amount); } // https://knarkowicz.wordpress.com/2014/04/16/octahedron-normal-vector-encoding/ vec3 octahedron_decode(vec2 f) { f = f * 2.0 - 1.0; // https://twitter.com/Stubbesaurus/status/937994790553227264 vec3 n = vec3(f.x, f.y, 1.0 - abs(f.x) - abs(f.y)); float t = clamp(-n.z, 0.0, 1.0); // GLSL didn't accept the vector version of this. Any impact? n.x += n.x >= 0.0 ? -t : t; n.y += n.y >= 0.0 ? -t : t; return /*f == vec2(0.0) ? vec3(0.0) : */normalize(n); } vec3 get_voxel_normal_model() { float cell_size = u_voxel_cell_size; int block_size = u_voxel_block_size; int normalmap_tile_size = u_voxel_virtual_texture_tile_size; vec3 cell_posf = v_vertex_pos_model / cell_size; cell_posf = cell_posf * u_voxel_virtual_texture_offset_scale.w + u_voxel_virtual_texture_offset_scale.xyz; ivec3 cell_pos = ivec3(floor(cell_posf)); vec3 cell_fract = fract(cell_posf); int cell_index = cell_pos.x + cell_pos.y * block_size + cell_pos.z * block_size * block_size; int lookup_sqri = int(ceil(sqrt(float(block_size * block_size * block_size)))); ivec2 lookup_pos = ivec2(cell_index % lookup_sqri, cell_index / lookup_sqri); //uvec3 lookup_value = texelFetch(u_voxel_cell_lookup, lookup_pos, 0).rgb; //vec3 lookup_valuef = texelFetch(u_voxel_cell_lookup, lookup_pos, 0).rgb; vec2 lookup_valuef = texture(u_voxel_cell_lookup, (vec2(lookup_pos) + vec2(0.5)) / float(lookup_sqri)).rg; ivec2 lookup_value = ivec2(round(lookup_valuef * 255.0)); int tile_index = lookup_value.r | ((lookup_value.g & 0x3f) << 8); int tile_direction = lookup_value.g >> 6; vec2 tile_texcoord = vec2(0.0); // TODO Could do it non-branching with weighted addition switch(tile_direction) { case 0: tile_texcoord = cell_fract.zy; break; case 1: tile_texcoord = cell_fract.xz; break; case 2: tile_texcoord = cell_fract.xy; break; } float padding = 0.5 / float(normalmap_tile_size); tile_texcoord = pad_uv(tile_texcoord, padding); ivec2 atlas_size = textureSize(u_voxel_normalmap_atlas, 0); int tiles_per_row = atlas_size.x / normalmap_tile_size; ivec2 tile_pos_pixels = ivec2(tile_index % tiles_per_row, tile_index / tiles_per_row) * normalmap_tile_size; vec2 atlas_texcoord = (vec2(tile_pos_pixels) + float(normalmap_tile_size) * tile_texcoord) / vec2(atlas_size); vec3 encoded_normal = texture(u_voxel_normalmap_atlas, atlas_texcoord).rgb; // You may switch between these two snippets depending on if you use octahedral compression or not // 1) XYZ vec3 tile_normal_model = 2.0 * encoded_normal - vec3(1.0); // 2) Octahedral // vec3 tile_normal_model = octahedron_decode(encoded_normal.rg); return tile_normal_model; } vec3 get_voxel_normal_view(vec3 geometry_normal_view, mat4 model_to_view) { if (u_voxel_cell_size == 0.0) { // Detail texture not available in this mesh return geometry_normal_view; } vec3 tile_normal_model = get_voxel_normal_model(); vec3 tile_normal_view = (model_to_view * vec4(tile_normal_model, 0.0)).xyz; // In some edge cases the normal can be invalid (length close to zero), causing black artifacts. // Workaround this by falling back on the geometry normal. vec3 normal = mix(geometry_normal_view, tile_normal_view, dot(tile_normal_view, tile_normal_view)); return normal; } void vertex() { // [...] // Note, if you use Transvoxel, this may be placed after modifications to `VERTEX` v_vertex_pos_model = VERTEX; // [...] } void fragment() { // [...] NORMAL = get_voxel_normal_view(NORMAL, VIEW_MATRIX * MODEL_MATRIX); // [...] } #### Details on the technique[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#details-on-the-technique "Permanent link") Normal-mapping usually requires texture coordinates (UVs). However, smooth voxel meshes aren't trivial to UV-map at runtime. Some methods exist to generate UV-maps on completely arbitrary meshes, but they are too expensive for realtime, or inappropriate for seamless chunked terrain. So instead, we can use something similar to "virtual texturing". The mesh is first subdivided into a grid of cells (we can use Transvoxel cells, which are ready to use). In each cell, we pick an axis-aligned projection working best with triangles of the cell using the average of their normals. A tile can then be generated by projecting its pixels on triangles, evaluating a normal from voxel data, and storing it in an atlas (a TextureArray could be used, but it has more limited number of layers). A shader can then read the atlas using a lookup texture to find the tile. The lookup texture is a 3D texture that tells for each "cell" where is the tile in the atlas (but it can be stored as a 2D texture). ![Image of an atlas of voxel normals](https://voxel-tools.readthedocs.io/en/latest/images/virtual_normalmap.webp) To generate pixels of each tile, we need to access SDF data from two sources: * The procedural generator * Edited voxels at LOD 0 A classic method is used to obtain normals: on the desired position, we take 4 samples offset by a small step, compute their difference, and normalize the result. It's known as "forward differences" (see [Inigo Quilez's article about SDF normals](https://iquilezles.org/articles/normalsSDF/) ). Since every mesh will have its own textures, another technique that comes in handy is [Octahedral Compression](https://knarkowicz.wordpress.com/2014/04/16/octahedron-normal-vector-encoding/) . These normals are world-space, and encoding them in a texture naively would require 3 bytes per pixel (for X, Y, Z). With octahedral compression, we trade off a bit of quality for a much smaller size of 2 bytes per pixels. #### Rendering on the GPU[¶](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#rendering-on-the-gpu "Permanent link") This feature is very expensive, so it is possible to run it on the graphics card if it supports Vulkan. This is enabled by checking `run on GPU` in the terrain's inspector. Limitations: * GPU normalmaps currently don't support edited voxels. Edited areas will fallback using the CPU. * The generator you're using must support a shader variant using GLSL. `VoxelGeneratorGraph` is the only one supporting it at the moment. Some of its nodes don't have support for it. --- # VoxelBlockyAttribute - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockyAttribute * * * VoxelBlockyAttribute[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/#voxelblockyattribute "Permanent link") ====================================================================================================================================== Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Inherited by: [VoxelBlockyAttributeAxis](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeAxis/) , [VoxelBlockyAttributeCustom](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/) , [VoxelBlockyAttributeDirection](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeDirection/) , [VoxelBlockyAttributeRotation](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeRotation/) Warning This class is marked as experimental. It is subject to likely change or possible removal in future versions. Use at your own discretion. Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/#methods "Permanent link") ------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html) | [get\_attribute\_name](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/#i_get_attribute_name)
( ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_default\_value](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/#i_get_default_value)
( ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_value\_count](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/#i_get_value_count)
( ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [is\_rotation](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/#i_is_rotation)
( ) const | Constants:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/#constants "Permanent link") ----------------------------------------------------------------------------------------------------------------- * **MAX\_VALUES** = **256** Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ ### [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html) **get\_attribute\_name**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/#stringname-get_attribute_name "Permanent link") _(This method has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_default\_value**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/#int-get_default_value "Permanent link") _(This method has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_value\_count**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/#int-get_value_count "Permanent link") _(This method has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **is\_rotation**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/#bool-is_rotation "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelBlockyAttributeAxis - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockyAttributeAxis * * * VoxelBlockyAttributeAxis[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeAxis/#voxelblockyattributeaxis "Permanent link") ================================================================================================================================================== Inherits: [VoxelBlockyAttribute](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/) Warning This class is marked as experimental. It is subject to likely change or possible removal in future versions. Use at your own discretion. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeAxis/#properties "Permanent link") ----------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [horizontal\_only](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeAxis/#i_horizontal_only) | false | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeAxis/#methods "Permanent link") ----------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [from\_vec3](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeAxis/#i_from_vec3)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
v ) const | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeAxis/#enumerations "Permanent link") --------------------------------------------------------------------------------------------------------------------------- enum **Axis**: * **AXIS\_X** = **0** * **AXIS\_Y** = **1** * **AXIS\_Z** = **2** * **AXIS\_COUNT** = **3** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeAxis/#property-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------------- ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **horizontal\_only** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeAxis/#bool-horizontal_only-false "Permanent link") _(This property has no documentation)_ Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeAxis/#method-descriptions "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------- ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **from\_vec3**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) v )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeAxis/#int-from_vec3-vector3-v "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelBlockSerializer - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockSerializer * * * VoxelBlockSerializer[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#voxelblockserializer "Permanent link") ====================================================================================================================================== Inherits: [RefCounted](https://docs.godotengine.org/en/stable/classes/class_refcounted.html) Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#description "Permanent link") --------------------------------------------------------------------------------------------------------------------- Low-level utility to save and load the data within a [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) . This can be useful to send data over the network, or to store it in a file. To store into a file allocating a PackedByteArray: # `voxels` is an existing `VoxelBuffer` var data := VoxelBlockSerializer.serialize_to_byte_array(voxels, true) file.store_32(len(data)) file.store_buffer(data) To read it back: var size := file.get_32() var data := file.get_buffer(size) VoxelBlockSerializer.deserialize_from_byte_array(data, voxels, true) To store into a file by re-using a StreamPeerBuffer: # Note, buffer can be re-used if you do this often var stream_peer_buffer := StreamPeerBuffer.new() var written_size = VoxelBlockSerializer.serialize_to_stream_peer(stream_peer_buffer, voxels, true) file.store_32(written_size) file.store_buffer(stream_peer_buffer.data_array) To read it back: var size := file.get_32() var stream_peer_buffer := StreamPeerBuffer.new() # Unfortunately Godot will always allocate memory with this API, can't avoid that stream_peer_buffer.data_array = file.get_buffer(size) VoxelBlockSerializer.deserialize_from_stream_peer(stream_peer_buffer, voxels, size, true) Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#methods "Permanent link") ------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#) | [deserialize\_from\_byte\_array](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#i_deserialize_from_byte_array)
( [PackedByteArray](https://docs.godotengine.org/en/stable/classes/class_packedbytearray.html)
bytes, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
voxel\_buffer, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
decompress ) static | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#) | [deserialize\_from\_stream\_peer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#i_deserialize_from_stream_peer)
( [StreamPeer](https://docs.godotengine.org/en/stable/classes/class_streampeer.html)
peer, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
voxel\_buffer, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
size, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
decompress ) static | | [PackedByteArray](https://docs.godotengine.org/en/stable/classes/class_packedbytearray.html) | [serialize\_to\_byte\_array](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#i_serialize_to_byte_array)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
voxel\_buffer, [Compression](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#enumerations)
compress ) static | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [serialize\_to\_stream\_peer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#i_serialize_to_stream_peer)
( [StreamPeer](https://docs.godotengine.org/en/stable/classes/class_streampeer.html)
peer, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
voxel\_buffer, [Compression](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#enumerations)
compress ) static | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#enumerations "Permanent link") ----------------------------------------------------------------------------------------------------------------------- enum **Compression**: * **COMPRESSION\_NONE** = **0** --- Don't compress the data. * **COMPRESSION\_LZ4** = **1** --- Use the LZ4 default compression algorithm. Fast, but lower compression ratio. * **COMPRESSION\_ZSTD** = **2** --- Use the Zstandard default compression algorithm. Good compression ratio but slower. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#) **deserialize\_from\_byte\_array**( [PackedByteArray](https://docs.godotengine.org/en/stable/classes/class_packedbytearray.html) bytes, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) voxel\_buffer, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) decompress )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#void-deserialize_from_byte_array-packedbytearray-bytes-voxelbuffer-voxel_buffer-bool-decompress "Permanent link") Reads the data of a [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) from a [PackedByteArray](https://docs.godotengine.org/en/stable/classes/class_packedbytearray.html) . ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#) **deserialize\_from\_stream\_peer**( [StreamPeer](https://docs.godotengine.org/en/stable/classes/class_streampeer.html) peer, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) voxel\_buffer, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) size, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) decompress )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#void-deserialize_from_stream_peer-streampeer-peer-voxelbuffer-voxel_buffer-int-size-bool-decompress "Permanent link") Reads the data of a [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) from a [StreamPeer](https://docs.godotengine.org/en/stable/classes/class_streampeer.html) . You must provide the number of bytes to read. ### [PackedByteArray](https://docs.godotengine.org/en/stable/classes/class_packedbytearray.html) **serialize\_to\_byte\_array**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) voxel\_buffer, [Compression](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#enumerations) compress )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#packedbytearray-serialize_to_byte_array-voxelbuffer-voxel_buffer-compression-compress "Permanent link") Stores the data of a [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) into a [PackedByteArray](https://docs.godotengine.org/en/stable/classes/class_packedbytearray.html) . ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **serialize\_to\_stream\_peer**( [StreamPeer](https://docs.godotengine.org/en/stable/classes/class_streampeer.html) peer, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) voxel\_buffer, [Compression](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#enumerations) compress )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#int-serialize_to_stream_peer-streampeer-peer-voxelbuffer-voxel_buffer-compression-compress "Permanent link") Stores the data of a [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) into a [StreamPeer](https://docs.godotengine.org/en/stable/classes/class_streampeer.html) . Returns the number of written bytes. _Generated on Aug 20, 2026_ --- # VoxelBlockyAttributeCustom - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockyAttributeCustom * * * VoxelBlockyAttributeCustom[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/#voxelblockyattributecustom "Permanent link") ======================================================================================================================================================== Inherits: [VoxelBlockyAttribute](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/) Warning This class is marked as experimental. It is subject to likely change or possible removal in future versions. Use at your own discretion. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/#properties "Permanent link") ------------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html) | [attribute\_name](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/#i_attribute_name) | &"" | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [default\_value](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/#i_default_value) | 0 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [value\_count](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/#i_value_count) | 2 | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/#methods "Permanent link") ------------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/#) | [set\_value\_name](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/#i_set_value_name)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
value, [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html)
value\_name ) | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/#property-descriptions "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------- ### [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html) **attribute\_name** = &""[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/#stringname-attribute_name "Permanent link") _(This property has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **default\_value** = 0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/#int-default_value-0 "Permanent link") _(This property has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **value\_count** = 2[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/#int-value_count-2 "Permanent link") _(This property has no documentation)_ Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/#) **set\_value\_name**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) value, [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html) value\_name )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/#void-set_value_name-int-value-stringname-value_name "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelBlockyAttributeDirection - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockyAttributeDirection * * * VoxelBlockyAttributeDirection[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeDirection/#voxelblockyattributedirection "Permanent link") ================================================================================================================================================================= Inherits: [VoxelBlockyAttribute](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/) Warning This class is marked as experimental. It is subject to likely change or possible removal in future versions. Use at your own discretion. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeDirection/#properties "Permanent link") ---------------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [horizontal\_only](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeDirection/#i_horizontal_only) | false | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeDirection/#methods "Permanent link") ---------------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [from\_vec3](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeDirection/#i_from_vec3)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
v ) const | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeDirection/#enumerations "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- enum **Direction**: * **DIR\_NEGATIVE\_X** = **0** * **DIR\_POSITIVE\_X** = **1** * **DIR\_NEGATIVE\_Y** = **2** * **DIR\_POSITIVE\_Y** = **3** * **DIR\_NEGATIVE\_Z** = **4** * **DIR\_POSITIVE\_Z** = **5** * **DIR\_COUNT** = **6** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeDirection/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------- ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **horizontal\_only** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeDirection/#bool-horizontal_only-false "Permanent link") _(This property has no documentation)_ Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeDirection/#method-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------- ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **from\_vec3**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) v )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeDirection/#int-from_vec3-vector3-v "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelBlockyAttributeRotation - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockyAttributeRotation * * * VoxelBlockyAttributeRotation[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeRotation/#voxelblockyattributerotation "Permanent link") ============================================================================================================================================================== Inherits: [VoxelBlockyAttribute](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/) Warning This class is marked as experimental. It is subject to likely change or possible removal in future versions. Use at your own discretion. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeRotation/#properties "Permanent link") --------------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [horizontal\_only](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeRotation/#i_horizontal_only) | false | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeRotation/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **horizontal\_only** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeRotation/#bool-horizontal_only-false "Permanent link") _(This property has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelBlockyFluid - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockyFluid * * * VoxelBlockyFluid[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyFluid/#voxelblockyfluid "Permanent link") ========================================================================================================================== Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Properties of a blocky fluid. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyFluid/#description "Permanent link") ----------------------------------------------------------------------------------------------------------------- Common properties of a specific fluid. It may be shared between multiple blocky models, each representing a level/state of the fluid. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyFluid/#properties "Permanent link") --------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [dip\_when\_flowing\_down](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyFluid/#i_dip_when_flowing_down) | false | | [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) | [material](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyFluid/#i_material) | | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyFluid/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **dip\_when\_flowing\_down** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyFluid/#bool-dip_when_flowing_down-false "Permanent link") When enabled, if all following conditions are met for a given fluid voxel: * It doesn't have maximum level * It isn't covered by another voxel of the same fluid type * It can flow downwards (below is air or fluid of the same type) Then the shape of the voxel will change to be "pushed" downwards, creating steeper slopes. Note, this also means the voxel will look as if it has minimum level in some situations. However, in practice these cases don't occur often. You may decide whether to use this option depending on how your fluid simulates. ### [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) **material**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyFluid/#material-material "Permanent link") Material used by all states of the fluid. Note that UVs of a fluid are different than a regular model, so you may need a [ShaderMaterial](https://docs.godotengine.org/en/stable/classes/class_shadermaterial.html) to handle flowing animation. See [https://voxel-tools.readthedocs.io/en/latest/blocky\_terrain/#fluids](https://voxel-tools.readthedocs.io/en/latest/blocky_terrain/#fluids) _Generated on Aug 20, 2026_ --- # VoxelBlockyLibraryBase - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockyLibraryBase * * * VoxelBlockyLibraryBase[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#voxelblockylibrarybase "Permanent link") ============================================================================================================================================ Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Inherited by: [VoxelBlockyLibrary](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/) , [VoxelBlockyTypeLibrary](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/) Contains a list of models that can be used by [VoxelMesherBlocky](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/) . Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#description "Permanent link") ----------------------------------------------------------------------------------------------------------------------- Models used by [VoxelMesherBlocky](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/) must be baked before they can be used efficiently at runtime. The way this process happens depends on the implementation of this class. It can be a simple list of models, or a list of high-level types generating variant models. Check child classes for more information. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#properties "Permanent link") --------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [bake\_tangents](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#i_bake_tangents) | true | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#methods "Permanent link") --------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#) | [bake](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#i_bake)
( ) | | [Material\[\]](https://docs.godotengine.org/en/stable/classes/class_material[].html) | [get\_materials](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#i_get_materials)
( ) const | Constants:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#constants "Permanent link") ------------------------------------------------------------------------------------------------------------------- * **MAX\_MODELS** = **65536** * **MAX\_MATERIALS** = **65536** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **bake\_tangents** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#bool-bake_tangents-true "Permanent link") Enable this option if you need normal mapping on your voxels. If you don't need it, disabling can reduce memory usage and give a small speed boost. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#method-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------- ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#) **bake**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#void-bake "Permanent link") Bakes the library. The data of models is optimized in order to combine them more efficiently when generating voxel meshes. ### [Material\[\]](https://docs.godotengine.org/en/stable/classes/class_material[].html) **get\_materials**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#material-get_materials "Permanent link") Gets a list of all distinct materials found in all models of the library. Note, if at least one non-empty model has no material, there will be one `null` entry in this list to represent "The default material". _Generated on Aug 20, 2026_ --- # VoxelBlockyLibrary - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockyLibrary * * * VoxelBlockyLibrary[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/#voxelblockylibrary "Permanent link") ================================================================================================================================ Inherits: [VoxelBlockyLibraryBase](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/) Contains a list of models that can be used by [VoxelMesherBlocky](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/) . Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/#description "Permanent link") ------------------------------------------------------------------------------------------------------------------- Provides a list of models that can be used by [VoxelMesherBlocky](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/) . Each model corresponds to an ID in voxel data, and is generally defined from a mesh. Some extra properties can also be defined, such as how sides get culled by neighbor voxels, or how it is treated by some functionality of the voxel engine. If you create this library from code, it needs to be baked at the end using the [VoxelBlockyLibraryBase.bake](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#i_bake) function. The first model (at index 0) is conventionally used for "air" or "empty". Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/#properties "Permanent link") ----------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [VoxelBlockyModel\[\]](https://docs.godotengine.org/en/stable/classes/class_voxelblockymodel[].html) | [models](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/#i_models) | \[\] | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/#methods "Permanent link") ----------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [add\_model](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/#i_add_model)
( [VoxelBlockyModel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/)
model ) | | [VoxelBlockyModel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/) | [get\_model](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/#i_get_model)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
index ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_model\_index\_from\_resource\_name](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/#i_get_model_index_from_resource_name)
( [String](https://docs.godotengine.org/en/stable/classes/class_string.html)
name ) const | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/#property-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------- ### [VoxelBlockyModel\[\]](https://docs.godotengine.org/en/stable/classes/class_voxelblockymodel[].html) **models** = \[\][¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/#voxelblockymodel-models "Permanent link") Array of all the models. The index of each model corresponds to the value representing them in voxel data's TYPE channel. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/#method-descriptions "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------- ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **add\_model**( [VoxelBlockyModel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/) model )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/#int-add_model-voxelblockymodel-model "Permanent link") Adds a model to the library. Returns its index, which will be the value of voxels representing it. ### [VoxelBlockyModel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/) **get\_model**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/#voxelblockymodel-get_model-int-index "Permanent link") Gets a model from its index. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_model\_index\_from\_resource\_name**( [String](https://docs.godotengine.org/en/stable/classes/class_string.html) name )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/#int-get_model_index_from_resource_name-string-name "Permanent link") Finds the index of the first model having the specified resource name. If not found, returns `null`. _Generated on Aug 20, 2026_ --- # VoxelBlockyModelCube - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockyModelCube * * * VoxelBlockyModelCube[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#voxelblockymodelcube "Permanent link") ====================================================================================================================================== Inherits: [VoxelBlockyModel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/) Generates a cube model with specific tiles on its sides. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#properties "Permanent link") ------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [Vector2i](https://docs.godotengine.org/en/stable/classes/class_vector2i.html) | [atlas\_size\_in\_tiles](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#i_atlas_size_in_tiles) | Vector2i(16, 16) | | [AABB\[\]](https://docs.godotengine.org/en/stable/classes/class_aabb[].html) | [collision\_aabbs](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#i_collision_aabbs) | \[AABB(0, 0, 0, 1, 1, 1)\] | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [height](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#i_height) | 1.0 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [mesh\_ortho\_rotation\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#i_mesh_ortho_rotation_index) | 0 | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#methods "Permanent link") ------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [Vector2i](https://docs.godotengine.org/en/stable/classes/class_vector2i.html) | [get\_tile](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#i_get_tile)
( [Side](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#enumerations)
side ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#) | [set\_tile](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#i_set_tile)
( [Side](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#enumerations)
side, [Vector2i](https://docs.godotengine.org/en/stable/classes/class_vector2i.html)
position ) | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#property-descriptions "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------- ### [Vector2i](https://docs.godotengine.org/en/stable/classes/class_vector2i.html) **atlas\_size\_in\_tiles** = Vector2i(16, 16)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#vector2i-atlas_size_in_tiles-vector2i16-16 "Permanent link") Sets a reference size of texture atlas, in tiles. It must be set so the model generates correct texture coordinates from specified tile positions. If you are not using an atlas and every side uses the same full texture, use (1,1). ### [AABB\[\]](https://docs.godotengine.org/en/stable/classes/class_aabb[].html) **collision\_aabbs** = \[AABB(0, 0, 0, 1, 1, 1)\][¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#aabb-collision_aabbs-aabb0-0-0-1-1-1 "Permanent link") ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **height** = 1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#float-height-10 "Permanent link") _(This property has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **mesh\_ortho\_rotation\_index** = 0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#int-mesh_ortho_rotation_index-0 "Permanent link") _(This property has no documentation)_ Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ ### [Vector2i](https://docs.godotengine.org/en/stable/classes/class_vector2i.html) **get\_tile**( [Side](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#enumerations) side )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#vector2i-get_tile-side-side "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#) **set\_tile**( [Side](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#enumerations) side, [Vector2i](https://docs.godotengine.org/en/stable/classes/class_vector2i.html) position )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/#void-set_tile-side-side-vector2i-position "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelBlockyModelFluid - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockyModelFluid * * * VoxelBlockyModelFluid[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelFluid/#voxelblockymodelfluid "Permanent link") ========================================================================================================================================= Inherits: [VoxelBlockyModel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/) Model representing a specific state of a fluid. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelFluid/#properties "Permanent link") -------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [VoxelBlockyFluid](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyFluid/) | [fluid](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelFluid/#i_fluid) | | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [level](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelFluid/#i_level) | 0 | Constants:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelFluid/#constants "Permanent link") ------------------------------------------------------------------------------------------------------------------ * **MAX\_LEVELS** = **256** --- Maximum amount of supported fluid levels. Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelFluid/#property-descriptions "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------- ### [VoxelBlockyFluid](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyFluid/) **fluid**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelFluid/#voxelblockyfluid-fluid "Permanent link") Which fluid this model is part of. Note, fluid resources are supposed to be shared between multiple models, in order to make those models recognized as states of that fluid. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **level** = 0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelFluid/#int-level-0 "Permanent link") Fluid level, usually representing how much fluid the model contains. Levels should start from 0, and must be lower than 256. Fluids can have multiple models with the same level. It is also preferable to define at least one model per level (avoid missing levels). It is also recommended to assign models with consecutive levels to consecutive library IDs, however this is not required. _Generated on Aug 20, 2026_ --- # VoxelBlockyModelEmpty - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockyModelEmpty * * * VoxelBlockyModelEmpty[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelEmpty/#voxelblockymodelempty "Permanent link") ========================================================================================================================================= Inherits: [VoxelBlockyModel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/) Explicitely represents an empty model. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelEmpty/#description "Permanent link") ---------------------------------------------------------------------------------------------------------------------- This can be used for the default air model (at index 0), but may also be useful if you want to define a model that has no visuals, but still has collision or other attributes different than air. _Generated on Aug 20, 2026_ --- # VoxelGenerator - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelGenerator * * * VoxelGenerator[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/#voxelgenerator "Permanent link") ==================================================================================================================== Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Inherited by: [VoxelGeneratorFlat](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorFlat/) , [VoxelGeneratorGraph](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/) , [VoxelGeneratorHeightmap](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/) , [VoxelGeneratorMultipassCB](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/) , [VoxelGeneratorNoise](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise/) , [VoxelGeneratorScript](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorScript/) Base class to all voxel procedural generators. Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/#methods "Permanent link") ------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/#) | [generate\_block](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/#i_generate_block)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
out\_buffer, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
origin\_in\_voxels, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
lod ) | Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/#) **generate\_block**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) out\_buffer, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) origin\_in\_voxels, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) lod )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/#void-generate_block-voxelbuffer-out_buffer-vector3-origin_in_voxels-int-lod "Permanent link") Generates a block of voxels within the specified world area. `out_buffer`: Buffer in which voxel data will be generated. It must not be `null` and must have a non-empty size. `origin_in_voxels`: Coordinates of the lower corner of the box to generate, relative to LOD0. `lod`: Level of detail index to use for this block. Some generators might not support LOD, in which case it can be left 0. At LOD 0, each cell of the passed buffer spans 1 space unit. At LOD 1, 2 units. At LOD 2, 4 units, and so on. _Generated on Aug 20, 2026_ --- # VoxelBlockyType - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockyType * * * VoxelBlockyType[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#voxelblockytype "Permanent link") ======================================================================================================================= Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Warning This class is marked as experimental. It is subject to likely change or possible removal in future versions. Use at your own discretion. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#properties "Permanent link") -------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) | [\_variant\_models\_data](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#i__variant_models_data) | \[\] | | [VoxelBlockyAttribute\[\]](https://docs.godotengine.org/en/stable/classes/class_voxelblockyattribute[].html) | [attributes](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#i_attributes) | \[\] | | [VoxelBlockyModel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/) | [base\_model](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#i_base_model) | | | [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html) | [unique\_name](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#i_unique_name) | &"unnamed" | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#methods "Permanent link") -------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [VoxelBlockyAttribute](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/) | [get\_rotation\_attribute](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#i_get_rotation_attribute)
( ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#) | [set\_variant\_model](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#i_set_variant_model)
( [Array](https://docs.godotengine.org/en/stable/classes/class_array.html)
key, [VoxelBlockyModel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/)
model ) | Constants:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#constants "Permanent link") ------------------------------------------------------------------------------------------------------------ * **MAX\_ATTRIBUTES** = **4** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#property-descriptions "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------- ### [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) **\_variant\_models\_data** = \[\][¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#array-_variant_models_data "Permanent link") _(This property has no documentation)_ ### [VoxelBlockyAttribute\[\]](https://docs.godotengine.org/en/stable/classes/class_voxelblockyattribute[].html) **attributes** = \[\][¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#voxelblockyattribute-attributes "Permanent link") _(This property has no documentation)_ ### [VoxelBlockyModel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/) **base\_model**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#voxelblockymodel-base_model "Permanent link") _(This property has no documentation)_ ### [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html) **unique\_name** = &"unnamed"[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#stringname-unique_name-unnamed "Permanent link") _(This property has no documentation)_ Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- ### [VoxelBlockyAttribute](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/) **get\_rotation\_attribute**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#voxelblockyattribute-get_rotation_attribute "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#) **set\_variant\_model**( [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) key, [VoxelBlockyModel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/) model )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/#void-set_variant_model-array-key-voxelblockymodel-model "Permanent link") Explicitely sets which model to use for a given combination of attributes (key). If you have attributes that automatically generate variants (such as rotations), you are expected to only set models for the default value of such attributes. Other models will not be preserved. This is because the default value will be used as a reference to generate the other models. _Generated on Aug 20, 2026_ --- # VoxelGeneratorWaves - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelGeneratorWaves * * * VoxelGeneratorWaves[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorWaves/#voxelgeneratorwaves "Permanent link") =================================================================================================================================== Inherits: [VoxelGeneratorHeightmap](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/) Voxel generator producing a wavy terrain pattern. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorWaves/#properties "Permanent link") ------------------------------------------------------------------------------------------------------------------ | Type | Name | Default | | --- | --- | --- | | [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) | [pattern\_offset](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorWaves/#i_pattern_offset) | Vector2(0, 0) | | [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) | [pattern\_size](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorWaves/#i_pattern_size) | Vector2(30, 30) | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorWaves/#property-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------- ### [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) **pattern\_offset** = Vector2(0, 0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorWaves/#vector2-pattern_offset-vector20-0 "Permanent link") Offset (or phase) of the waves. ### [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) **pattern\_size** = Vector2(30, 30)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorWaves/#vector2-pattern_size-vector230-30 "Permanent link") Length of the waves. Note that this only controls length across the X and Z axes. Height is controlled by [VoxelGeneratorHeightmap.height\_start](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#i_height_start) and [VoxelGeneratorHeightmap.height\_range](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#i_height_range) . _Generated on Aug 20, 2026_ --- # VoxelGeneratorFlat - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelGeneratorFlat * * * VoxelGeneratorFlat[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorFlat/#voxelgeneratorflat "Permanent link") ================================================================================================================================ Inherits: [VoxelGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/) Voxel generator producing an infinite flat ground. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorFlat/#properties "Permanent link") ----------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) | [channel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorFlat/#i_channel) | CHANNEL\_SDF (1) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [height](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorFlat/#i_height) | 0.0 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [voxel\_type](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorFlat/#i_voxel_type) | 1 | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorFlat/#property-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------- ### [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) **channel** = CHANNEL\_SDF (1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorFlat/#channelid-channel-channel_sdf-1 "Permanent link") Channel that will be used to generate the ground. Use [VoxelBuffer.CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) for smooth terrain, other channels for blocky. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **height** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorFlat/#float-height-00 "Permanent link") Altitude of the ground. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **voxel\_type** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorFlat/#int-voxel_type-1 "Permanent link") If [channel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorFlat/#i_channel) is set to any channel other than [VoxelBuffer.CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) , this value will be used to fill ground voxels, while air voxels will be set to 0. _Generated on Aug 20, 2026_ --- # VoxelInstanceComponent - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelInstanceComponent * * * VoxelInstanceComponent[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceComponent/#voxelinstancecomponent "Permanent link") ============================================================================================================================================ Inherits: [Node](https://docs.godotengine.org/en/stable/classes/class_node.html) This node gets attached to scene items instanced by [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) . Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceComponent/#description "Permanent link") ----------------------------------------------------------------------------------------------------------------------- [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) internally adds this node to instanced scenes, so it can track when they get destroyed or removed from the scene tree. _Generated on Aug 20, 2026_ --- # VoxelInstanceLibrarySceneItem - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelInstanceLibrarySceneItem * * * VoxelInstanceLibrarySceneItem[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrarySceneItem/#voxelinstancelibrarysceneitem "Permanent link") ================================================================================================================================================================= Inherits: [VoxelInstanceLibraryItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/) Instancer model using scenes. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrarySceneItem/#description "Permanent link") ------------------------------------------------------------------------------------------------------------------------------ This model will spawn scene instances, which may be suited for sparse and complex elements. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrarySceneItem/#properties "Permanent link") ---------------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [PackedScene](https://docs.godotengine.org/en/stable/classes/class_packedscene.html) | [scene](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrarySceneItem/#i_scene) | | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrarySceneItem/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------- ### [PackedScene](https://docs.godotengine.org/en/stable/classes/class_packedscene.html) **scene**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrarySceneItem/#packedscene-scene "Permanent link") _(This property has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelModifierSphere - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelModifierSphere * * * VoxelModifierSphere[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierSphere/#voxelmodifiersphere "Permanent link") =================================================================================================================================== Inherits: [VoxelModifier](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifier/) Voxel modifier that uses sphere shape. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierSphere/#properties "Permanent link") ------------------------------------------------------------------------------------------------------------------ | Type | Name | Default | | --- | --- | --- | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [radius](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierSphere/#i_radius) | 10.0 | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierSphere/#property-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------- ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **radius** = 10.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierSphere/#float-radius-100 "Permanent link") Radius of the sphere. _Generated on Aug 20, 2026_ --- # VoxelModifierMesh - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelModifierMesh * * * VoxelModifierMesh[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierMesh/#voxelmodifiermesh "Permanent link") ============================================================================================================================= Inherits: [VoxelModifier](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifier/) Voxel modifier that uses [VoxelMeshSDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/) . Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierMesh/#properties "Permanent link") ---------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [isolevel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierMesh/#i_isolevel) | 0.0 | | [VoxelMeshSDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/) | [mesh\_sdf](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierMesh/#i_mesh_sdf) | | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierMesh/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------- ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **isolevel** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierMesh/#float-isolevel-00 "Permanent link") Offsets isolevel of SDF mesh. Positive value makes object appear thicker as well as smoother and negative value - thinner. ### [VoxelMeshSDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/) **mesh\_sdf**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierMesh/#voxelmeshsdf-mesh_sdf "Permanent link") SDF mesh that is used for modifier. _Generated on Aug 20, 2026_ --- # VoxelSaveCompletionTracker - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelSaveCompletionTracker * * * VoxelSaveCompletionTracker[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/#voxelsavecompletiontracker "Permanent link") ======================================================================================================================================================== Inherits: [RefCounted](https://docs.godotengine.org/en/stable/classes/class_refcounted.html) Object returned by some asynchronous functions to track progress and completion. Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/#methods "Permanent link") ------------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_remaining\_tasks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/#i_get_remaining_tasks)
( ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_total\_tasks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/#i_get_total_tasks)
( ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [is\_aborted](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/#i_is_aborted)
( ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [is\_complete](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/#i_is_complete)
( ) const | Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_remaining\_tasks**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/#int-get_remaining_tasks "Permanent link") _(This method has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_total\_tasks**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/#int-get_total_tasks "Permanent link") _(This method has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **is\_aborted**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/#bool-is_aborted "Permanent link") _(This method has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **is\_complete**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/#bool-is_complete "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelStreamMemory - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelStreamMemory * * * VoxelStreamMemory[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamMemory/#voxelstreammemory "Permanent link") ============================================================================================================================= Inherits: [VoxelStream](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/) Keeps data into memory rather than writing it on disk. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamMemory/#description "Permanent link") ------------------------------------------------------------------------------------------------------------------ This stream is mainly intented for testing purposes. It shouldn't be used as a proper saving system. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamMemory/#properties "Permanent link") ---------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [artificial\_save\_latency\_usec](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamMemory/#i_artificial_save_latency_usec) | 0 | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamMemory/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------- ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **artificial\_save\_latency\_usec** = 0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamMemory/#int-artificial_save_latency_usec-0 "Permanent link") Fakes long saving by making the calling thread sleep for some amount of time. _Generated on Aug 20, 2026_ --- # VoxelDataBlockEnterInfo - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelDataBlockEnterInfo * * * VoxelDataBlockEnterInfo[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/#voxeldatablockenterinfo "Permanent link") =============================================================================================================================================== Inherits: [Object](https://docs.godotengine.org/en/stable/classes/class_object.html) Information sent by a terrain when one of its data blocks enters the area of a [VoxelViewer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/) . Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/#description "Permanent link") ------------------------------------------------------------------------------------------------------------------------ Information sent by a terrain when one of its data blocks enters the area of a [VoxelViewer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/) . See [VoxelTerrain.\_on\_data\_block\_entered](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i__on_data_block_entered) . Instances of this class must not be stored, as they will become invalid after the call they come from. Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/#methods "Permanent link") ---------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [are\_voxels\_edited](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/#i_are_voxels_edited)
( ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_lod\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/#i_get_lod_index)
( ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_network\_peer\_id](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/#i_get_network_peer_id)
( ) const | | [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) | [get\_position](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/#i_get_position)
( ) const | | [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) | [get\_voxels](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/#i_get_voxels)
( ) const | Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/#method-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------- ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **are\_voxels\_edited**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/#bool-are_voxels_edited "Permanent link") Tells if voxels in the block have ever been edited. If not, it means the same data can be obtained by running the generator. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_lod\_index**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/#int-get_lod_index "Permanent link") Gets which LOD index the data block is in. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_network\_peer\_id**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/#int-get_network_peer_id "Permanent link") Gets the network peer ID of the [VoxelViewer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/) who caused the block to be referenced. ### [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) **get\_position**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/#vector3i-get_position "Permanent link") Gets the position of the data block, in data block coordinates (voxel coordinates are obtained by multiplying these coordinates with data block size). ### [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) **get\_voxels**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/#voxelbuffer-get_voxels "Permanent link") Gets access to the voxels in the block. _Generated on Aug 20, 2026_ --- # VoxelBlockyModel - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockyModel * * * VoxelBlockyModel[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#voxelblockymodel "Permanent link") ========================================================================================================================== Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Inherited by: [VoxelBlockyModelCube](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/) , [VoxelBlockyModelEmpty](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelEmpty/) , [VoxelBlockyModelFluid](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelFluid/) , [VoxelBlockyModelMesh](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelMesh/) Model stored in [VoxelBlockyLibrary](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/) and used by [VoxelMesherBlocky](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/) . Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#description "Permanent link") ----------------------------------------------------------------------------------------------------------------- Represents a model to be used for voxels of a specific TYPE value. Such models must be contained within a [VoxelBlockyLibrary](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/) to be used with [VoxelTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/) or directly with a [VoxelMesherBlocky](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/) . A model can be setup in various ways, see child classes. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#properties "Permanent link") --------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [AABB\[\]](https://docs.godotengine.org/en/stable/classes/class_aabb[].html) | [collision\_aabbs](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_collision_aabbs) | \[\] | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [collision\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_collision_mask) | 1 | | [Color](https://docs.godotengine.org/en/stable/classes/class_color.html) | [color](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_color) | Color(1, 1, 1, 1) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [culls\_neighbors](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_culls_neighbors) | true | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [lod\_skirts\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_lod_skirts_enabled) | true | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [random\_tickable](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_random_tickable) | false | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [tags\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_tags_mask) | 1 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [transparency\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_transparency_index) | 0 | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#methods "Permanent link") --------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) | [get\_material\_override](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_get_material_override)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
index ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_mesh\_ortho\_rotation\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_get_mesh_ortho_rotation_index)
( ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [is\_mesh\_collision\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_is_mesh_collision_enabled)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
surface\_index ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#) | [rotate\_90](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_rotate_90)
( [Axis](https://docs.godotengine.org/en/stable/classes/class_vector3i.html#enum-vector3i-axis)
axis, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
clockwise ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#) | [set\_material\_override](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_set_material_override)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
index, [Material](https://docs.godotengine.org/en/stable/classes/class_material.html)
material ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#) | [set\_mesh\_collision\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_set_mesh_collision_enabled)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
surface\_index, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
enabled ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#) | [set\_mesh\_ortho\_rotation\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_set_mesh_ortho_rotation_index)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
i ) | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#enumerations "Permanent link") ------------------------------------------------------------------------------------------------------------------- enum **Side**: * **SIDE\_NEGATIVE\_X** = **1** * **SIDE\_POSITIVE\_X** = **0** * **SIDE\_NEGATIVE\_Y** = **2** * **SIDE\_POSITIVE\_Y** = **3** * **SIDE\_NEGATIVE\_Z** = **4** * **SIDE\_POSITIVE\_Z** = **5** * **SIDE\_COUNT** = **6** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ ### [AABB\[\]](https://docs.godotengine.org/en/stable/classes/class_aabb[].html) **collision\_aabbs** = \[\][¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#aabb-collision_aabbs "Permanent link") List of bounding boxes relative to the model. They are used for box-based collision, using [VoxelBoxMover](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/) . They are not used with mesh-based collision. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **collision\_mask** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#int-collision_mask-1 "Permanent link") Collision mask used for box-based collision [VoxelBoxMover](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/) and voxel raycasts ([VoxelToolTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/) ). It is not used for mesh-based collisions. ### [Color](https://docs.godotengine.org/en/stable/classes/class_color.html) **color** = Color(1, 1, 1, 1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#color-color-color1-1-1-1 "Permanent link") Color of the model. It will be used to modulate its color when built into a voxel mesh. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **culls\_neighbors** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#bool-culls_neighbors-true "Permanent link") If enabled, this voxel culls the faces of its neighbors. Disabling can be useful for denser transparent voxels, such as foliage. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **lod\_skirts\_enabled** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#bool-lod_skirts_enabled-true "Permanent link") If enabled and the terrain has LODs, this model will produce skirts when located at the edge of a chunk. This is intented to hide "cracks" between chunks of different LOD. You may turn this off if the model is transparent, as the skirt would become visible from behind other surfaces. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **random\_tickable** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#bool-random_tickable-false "Permanent link") If enabled, voxels having this ID in the TYPE channel will be used by [VoxelToolTerrain.run\_blocky\_random\_tick](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#i_run_blocky_random_tick) . ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **tags\_mask** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#int-tags_mask-1 "Permanent link") Bitmask used to filter this model in some operations. For example, see [VoxelToolTerrain.run\_blocky\_random\_tick](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#i_run_blocky_random_tick) . ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **transparency\_index** = 0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#int-transparency_index-0 "Permanent link") Determines how transparency is handled when the sides of the model are culled by neighbor voxels. If the neighbor voxel at a given side has a transparency index lower or equal to the current voxel, the side will be culled. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#method-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- ### [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) **get\_material\_override**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#material-get_material_override-int-index "Permanent link") Gets the material override for a specific surface of the model. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_mesh\_ortho\_rotation\_index**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#int-get_mesh_ortho_rotation_index "Permanent link") Gets the 90-degree rotation ID that will be applied to the model when the library is baked. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **is\_mesh\_collision\_enabled**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) surface\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#bool-is_mesh_collision_enabled-int-surface_index "Permanent link") Tells if a specific surface produces mesh-based collisions. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#) **rotate\_90**( [Axis](https://docs.godotengine.org/en/stable/classes/class_vector3i.html#enum-vector3i-axis) axis, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) clockwise )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#void-rotate_90-axis-axis-bool-clockwise "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#) **set\_material\_override**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) index, [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) material )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#void-set_material_override-int-index-material-material "Permanent link") Sets a material override for a specific surface of the model. It allows to use the same mesh on multiple models, but using different materials on each. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#) **set\_mesh\_collision\_enabled**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) surface\_index, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) enabled )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#void-set_mesh_collision_enabled-int-surface_index-bool-enabled "Permanent link") Enables or disables mesh-based collision on a specific surface. It allows a model to have solid parts and others where players can pass through. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#) **set\_mesh\_ortho\_rotation\_index**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) i )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#void-set_mesh_ortho_rotation_index-int-i "Permanent link") Gets the 90-degree rotation ID that will be applied to the model when the library is baked. This is a number representing one of 24 possible 90-degree rotations. You can also use [rotate\_90](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_rotate_90) . _Generated on Aug 20, 2026_ --- # VoxelBoxMover - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBoxMover * * * VoxelBoxMover[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#voxelboxmover "Permanent link") ================================================================================================================= Inherits: [RefCounted](https://docs.godotengine.org/en/stable/classes/class_refcounted.html) Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#description "Permanent link") -------------------------------------------------------------------------------------------------------------- Utility class allowing to reproduce simple move-and-slide logic using only voxel AABBs, similar to Minecraft physics. This class may only be used with blocky voxels. Store an instance of it within a member variable of your script, and use it within [Node.\_process](https://docs.godotengine.org/en/stable/classes/class_node.html#class-node-method-process) or [Node.\_physics\_process](https://docs.godotengine.org/en/stable/classes/class_node.html#class-node-method-physics-process) (it works wherever you like). var motion = Vector3(0, 0, -10 * delta) # Move forward motion = _box_mover.get_motion(get_translation(), motion, aabb, terrain_node) global_translate(motion) Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#methods "Permanent link") ------------------------------------------------------------------------------------------------------ | Return | Signature | | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_collision\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#i_get_collision_mask)
( ) const | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [get\_max\_step\_height](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#i_get_max_step_height)
( ) const | | [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) | [get\_motion](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#i_get_motion)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
pos, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
motion, [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html)
aabb, [Node](https://docs.godotengine.org/en/stable/classes/class_node.html)
terrain ) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [has\_stepped\_up](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#i_has_stepped_up)
( ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [intersects](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#i_intersects)
( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html)
aabb, [Object](https://docs.godotengine.org/en/stable/classes/class_object.html)
terrain ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [is\_step\_climbing\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#i_is_step_climbing_enabled)
( ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#) | [set\_collision\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#i_set_collision_mask)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
mask ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#) | [set\_max\_step\_height](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#i_set_max_step_height)
( [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
height ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#) | [set\_step\_climbing\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#i_set_step_climbing_enabled)
( [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
enabled ) | Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#method-descriptions "Permanent link") ----------------------------------------------------------------------------------------------------------------------------- ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_collision\_mask**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#int-get_collision_mask "Permanent link") Gets the collision mask used to detect collidable voxels. This collision mask is specific to this collision system, and is defined in [VoxelBlockyModel.collision\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_collision_mask) . ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **get\_max\_step\_height**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#float-get_max_step_height "Permanent link") _(This method has no documentation)_ ### [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) **get\_motion**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) pos, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) motion, [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) aabb, [Node](https://docs.godotengine.org/en/stable/classes/class_node.html) terrain )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#vector3-get_motion-vector3-pos-vector3-motion-aabb-aabb-node-terrain "Permanent link") Given a motion vector, returns a modified vector telling you by how much to move your character. This is similar to [KinematicBody.move\_and\_slide](https://docs.godotengine.org/en/stable/classes/class_kinematicbody.html#class-kinematicbody-method-move-and-slide) , except you have to apply the movement. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **has\_stepped\_up**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#bool-has_stepped_up "Permanent link") When step climbing is enabled, tells when the last call to [get\_motion](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#i_get_motion) caused climbing to occur. Climbing modifies the motion vector upwards so that the body is snapped on top of the step. This can have implications in character controller code, such as considering the character to be on the floor instead of having jumped. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **intersects**( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) aabb, [Object](https://docs.godotengine.org/en/stable/classes/class_object.html) terrain )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#bool-intersects-aabb-aabb-object-terrain "Permanent link") Tests if an axis-aligned box intersects with any voxel collision box. Note: due to floating point precision, you might get false positives when testing against boxes that are touching voxels bounds. If this is undesired, you might want to shrink your AABB slightly. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **is\_step\_climbing\_enabled**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#bool-is_step_climbing_enabled "Permanent link") Tells if step climbing is enabled. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#) **set\_collision\_mask**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) mask )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#void-set_collision_mask-int-mask "Permanent link") Sets the collision mask used to detect collidable voxels. Only voxels sharing at least one bit between the masks will be detected. This collision mask is specific to this collision system, and is defined in [VoxelBlockyModel.collision\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_collision_mask) . ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#) **set\_max\_step\_height**( [float](https://docs.godotengine.org/en/stable/classes/class_float.html) height )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#void-set_max_step_height-float-height "Permanent link") Sets the maximum height that can be climbed like "stairs". ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#) **set\_step\_climbing\_enabled**( [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) enabled )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#void-set_step_climbing_enabled-bool-enabled "Permanent link") When enabled, [get\_motion](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/#i_get_motion) will attempt to climb up small steps. This allows to implement Minecraft-like stairs. _Generated on Aug 20, 2026_ --- # VoxelEngine - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelEngine * * * VoxelEngine[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#voxelengine "Permanent link") =========================================================================================================== Inherits: [Object](https://docs.godotengine.org/en/stable/classes/class_object.html) Singleton holding common settings and handling voxel processing tasks in background threads. Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#methods "Permanent link") ---------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) | [get\_stats](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#i_get_stats)
( ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_thread\_count](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#i_get_thread_count)
( ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [get\_threaded\_graphics\_resource\_building\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#i_get_threaded_graphics_resource_building_enabled)
( ) const | | [String](https://docs.godotengine.org/en/stable/classes/class_string.html) | [get\_version\_edition](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#i_get_version_edition)
( ) const | | [String](https://docs.godotengine.org/en/stable/classes/class_string.html) | [get\_version\_git\_hash](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#i_get_version_git_hash)
( ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_version\_major](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#i_get_version_major)
( ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_version\_minor](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#i_get_version_minor)
( ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_version\_patch](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#i_get_version_patch)
( ) const | | [String](https://docs.godotengine.org/en/stable/classes/class_string.html) | [get\_version\_status](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#i_get_version_status)
( ) const | | [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) | [get\_version\_v](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#i_get_version_v)
( ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#) | [run\_tests](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#i_run_tests)
( [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html)
options ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#) | [set\_thread\_count](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#i_set_thread_count)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
count ) | Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#method-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------- ### [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) **get\_stats**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#dictionary-get_stats "Permanent link") Gets debug information about shared voxel processing. The returned dictionary has the following structure: { "thread_pools": { "general": { "tasks": int, "active_threads": int, "thread_count": int, "task_names": PackedStringArray } }, "tasks": { "streaming": int, "meshing": int, "generation": int, "main_thread": int, "gpu": int }, "memory_pools": { "voxel_used": int, "voxel_total": int, "block_count": int, "std_allocated": int, "std_deallocated": int, "std_current": int } } ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_thread\_count**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#int-get_thread_count "Permanent link") Returns the number of threads currently used internally by the `ThreadedTaskRunner`. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **get\_threaded\_graphics\_resource\_building\_enabled**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#bool-get_threaded_graphics_resource_building_enabled "Permanent link") Tells if the voxel engine is able to create graphics resources from different threads. This will usually be true if the current renderer's thread model is safe or multi-threaded, but might also be false if the renderer would poorly benefit from this (such as legacy OpenGL). ### [String](https://docs.godotengine.org/en/stable/classes/class_string.html) **get\_version\_edition**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#string-get_version_edition "Permanent link") Tells the edition of the voxel engine, which is either of the following: `module`, `extension` ### [String](https://docs.godotengine.org/en/stable/classes/class_string.html) **get\_version\_git\_hash**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#string-get_version_git_hash "Permanent link") Gets the Git hash that was used to compile the voxel engine. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_version\_major**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#int-get_version_major "Permanent link") Gets the major version number of the voxel engine. For example, in `1.2.0`, `1` is the major version. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_version\_minor**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#int-get_version_minor "Permanent link") Gets the minor version number of the voxel engine. For example, in `1.2.0`, `2` is the minor version. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_version\_patch**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#int-get_version_patch "Permanent link") Gets the patch version number of the voxel engine. For example, in `1.2.0`, `0` is the patch version. ### [String](https://docs.godotengine.org/en/stable/classes/class_string.html) **get\_version\_status**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#string-get_version_status "Permanent link") Gets the version status, which may be one of the following: `dev`, `release` ### [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) **get\_version\_v**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#vector3i-get_version_v "Permanent link") Gets the major (x), minor (y) and patch (z) version numbers of the voxel engine as a single vector. May be useful for comparisons. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#) **run\_tests**( [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) options )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#void-run_tests-dictionary-options "Permanent link") Runs internal unit tests. This function is only available if the voxel engine is compiled with `voxel_tests=true`. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#) **set\_thread\_count**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) count )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/#void-set_thread_count-int-count "Permanent link") Sets the number of threads to be used internally by the `ThreadedTaskRunner`. Setting this can cause lagging, and it might take some time until the number of threads actually matches the given value. _Generated on Aug 20, 2026_ --- # VoxelGeneratorHeightmap - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelGeneratorHeightmap * * * VoxelGeneratorHeightmap[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#voxelgeneratorheightmap "Permanent link") =============================================================================================================================================== Inherits: [VoxelGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/) Inherited by: [VoxelGeneratorImage](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorImage/) , [VoxelGeneratorNoise2D](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise2D/) , [VoxelGeneratorWaves](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorWaves/) Base class for several basic height-based generators. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#properties "Permanent link") ---------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) | [channel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#i_channel) | CHANNEL\_SDF (1) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [height\_range](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#i_height_range) | 30.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [height\_start](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#i_height_start) | \-50.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [iso\_scale](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#i_iso_scale) | 1.0 | | [Vector2i](https://docs.godotengine.org/en/stable/classes/class_vector2i.html) | [offset](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#i_offset) | Vector2i(0, 0) | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------- ### [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) **channel** = CHANNEL\_SDF (1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#channelid-channel-channel_sdf-1 "Permanent link") Channel where voxels will be generated. If set to [VoxelBuffer.CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) , voxels will be a signed distance field usable by smooth meshers. Otherwise, the value 1 will be set below ground, and the value 0 will be set above ground (blocky). ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **height\_range** = 30.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#float-height_range-300 "Permanent link") Maximum distance between the lowest and highest surface points that can generate. NOTE: due to a bug in Godot's documentation tool, the default value shown here is not 30.0, but 200.0. This seems to be because one of the subclasses, `VoxelGeneratorWaves`, has a different default value, chosen for better practical results. This property also appears in some subclasses now, despite being defined in the base class. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **height\_start** = -50.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#float-height_start-500 "Permanent link") Minimum height where the surface will generate. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **iso\_scale** = 1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#float-iso_scale-10 "Permanent link") Scale applied to the signed distance field when using a smooth terrain configuration. ### [Vector2i](https://docs.godotengine.org/en/stable/classes/class_vector2i.html) **offset** = Vector2i(0, 0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#vector2i-offset-vector2i0-0 "Permanent link") Offsets height generation along the X and Z axes. _Generated on Aug 20, 2026_ --- # VoxelGeneratorImage - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelGeneratorImage * * * VoxelGeneratorImage[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorImage/#voxelgeneratorimage "Permanent link") =================================================================================================================================== Inherits: [VoxelGeneratorHeightmap](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/) Voxel generator producing a heightmap-based shape using an image. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorImage/#description "Permanent link") -------------------------------------------------------------------------------------------------------------------- Uses the red channel of an image to generate a heightmap, such that the top left corner is centered on the world origin. The image will repeat if terrain generates beyond its size. Note: values in the image are read using `get_pixel` and are assumed to be between 0 and 1 (normalized). These values will be transformed by [VoxelGeneratorHeightmap.height\_start](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#i_height_start) and [VoxelGeneratorHeightmap.height\_range](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/#i_height_range) . Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorImage/#properties "Permanent link") ------------------------------------------------------------------------------------------------------------------ | Type | Name | Default | | --- | --- | --- | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [blur\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorImage/#i_blur_enabled) | false | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [height\_range](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorImage/#i_height_range) | 200.0 | | [Image](https://docs.godotengine.org/en/stable/classes/class_image.html) | [image](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorImage/#i_image) | | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorImage/#property-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------- ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **blur\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorImage/#bool-blur_enabled-false "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **height\_range** = 200.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorImage/#float-height_range-2000 "Permanent link") ### [Image](https://docs.godotengine.org/en/stable/classes/class_image.html) **image**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorImage/#image-image "Permanent link") Sets the image that will be used as a heightmap. Only the red channel will be used. It is preferable to use an image using the `RF` or `RH` format, which contain higher resolution heights. Common images only have 8-bit depth and will appear blocky. _Generated on Aug 20, 2026_ --- # VoxelGeneratorNoise - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelGeneratorNoise * * * VoxelGeneratorNoise[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise/#voxelgeneratornoise "Permanent link") =================================================================================================================================== Inherits: [VoxelGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/) Voxel generator producing overhanging shapes using 3D noise. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise/#properties "Permanent link") ------------------------------------------------------------------------------------------------------------------ | Type | Name | Default | | --- | --- | --- | | [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) | [channel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise/#i_channel) | CHANNEL\_SDF (1) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [height\_range](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise/#i_height_range) | 200.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [height\_start](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise/#i_height_start) | \-100.0 | | [FastNoiseLite](https://docs.godotengine.org/en/stable/classes/class_fastnoiselite.html) | [noise](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise/#i_noise) | | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise/#property-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------- ### [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) **channel** = CHANNEL\_SDF (1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise/#channelid-channel-channel_sdf-1 "Permanent link") Channel into which the generator will produce voxel data. This depends on the type of meshing you need. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **height\_range** = 200.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise/#float-height_range-2000 "Permanent link") Range of altitudes within which the shape variations will be found. The higher this range, the more overhangs there will be. Shapes will start at maximum density near the base of the shape (low probability to find air), and progressively loose density until it reaches maximum height. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **height\_start** = -100.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise/#float-height_start-1000 "Permanent link") Base of the shape. Everything below it will be filled with ground. ### [FastNoiseLite](https://docs.godotengine.org/en/stable/classes/class_fastnoiselite.html) **noise**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise/#fastnoiselite-noise "Permanent link") Noise used as density function. It is required for the generator to work. _Generated on Aug 20, 2026_ --- # VoxelGeneratorScript - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelGeneratorScript * * * VoxelGeneratorScript[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorScript/#voxelgeneratorscript "Permanent link") ====================================================================================================================================== Inherits: [VoxelGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/) Base class for custom generators defined with a script. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorScript/#description "Permanent link") --------------------------------------------------------------------------------------------------------------------- Important: this engine makes heavy use of threads. Generators will run in one of them, so make sure you don't access the scene tree or other unsafe APIs from within a generator. Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorScript/#methods "Permanent link") ------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorScript/#) | [\_generate\_block](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorScript/#i__generate_block)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
out\_buffer, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
origin\_in\_voxels, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
lod ) virtual | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [\_get\_used\_channels\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorScript/#i__get_used_channels_mask)
( ) virtual const | Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorScript/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorScript/#) **\_generate\_block**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) out\_buffer, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) origin\_in\_voxels, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) lod )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorScript/#void-_generate_block-voxelbuffer-out_buffer-vector3i-origin_in_voxels-int-lod "Permanent link") `out_buffer`: Buffer in which to populate voxel data. It will never be `null` and will have the requested size. It is only valid for this function, do not store it anywhere after the end. Note: this buffer can have any non-empty size, but some assumptions can be made depending on which terrain node you're using. [VoxelTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/) will always request blocks of size 16x16x16, but [VoxelLodTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/) can request blocks of different sizes. `origin_in_voxels`: Coordinates of the lower corner of the box to generate, relative to LOD0. The size of the box is known from `out_buffer`. `lod`: Level of detail index to use for this block. It can be ignored if you don't use LOD. This may be used as a power of two, telling how big is one voxel. For example, if you use a loop to fill the buffer using noise, you should sample that noise at steps of 2^lod, starting from `origin_in_voxels` (in code you can use `1 << lod` for fast computation, instead of `pow(2, lod)`). You may want to separate variables that iterate the coordinates in `out_buffer` and variables used to generate voxel values in space. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **\_get\_used\_channels\_mask**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorScript/#int-_get_used_channels_mask "Permanent link") Use this to indicate which channels your generator will use. It returns a bitmask, so for example you may provide information like this: `(1 << channel1) | (1 << channel2)` _Generated on Aug 20, 2026_ --- # VoxelInstanceLibrary - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelInstanceLibrary * * * VoxelInstanceLibrary[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#voxelinstancelibrary "Permanent link") ====================================================================================================================================== Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Contains a list of models that can be used by [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) , associated with a unique ID. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#properties "Permanent link") ------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) | [\_data](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#i__data) | \[0\] | | [VoxelInstanceLibraryItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/) | [\_selected\_item](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#i__selected_item) | | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#methods "Permanent link") ------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#) | [add\_item](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#i_add_item)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
id, [VoxelInstanceLibraryItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/)
item ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#) | [clear](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#i_clear)
( ) | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [find\_item\_by\_name](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#i_find_item_by_name)
( [String](https://docs.godotengine.org/en/stable/classes/class_string.html)
name ) const | | [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html) | [get\_all\_item\_ids](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#i_get_all_item_ids)
( ) const | | [VoxelInstanceLibraryItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/) | [get\_item](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#i_get_item)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
id ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#) | [remove\_item](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#i_remove_item)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
id ) | Constants:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#constants "Permanent link") ----------------------------------------------------------------------------------------------------------------- * **MAX\_ID** = **65535** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#property-descriptions "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------- ### [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) **\_data** = \[0\][¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#array-_data-0 "Permanent link") _(This property has no documentation)_ ### [VoxelInstanceLibraryItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/) **\_selected\_item**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#voxelinstancelibraryitem-_selected_item "Permanent link") _(This property has no documentation)_ Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#) **add\_item**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) id, [VoxelInstanceLibraryItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/) item )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#void-add_item-int-id-voxelinstancelibraryitem-item "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#) **clear**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#void-clear "Permanent link") _(This method has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **find\_item\_by\_name**( [String](https://docs.godotengine.org/en/stable/classes/class_string.html) name )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#int-find_item_by_name-string-name "Permanent link") _(This method has no documentation)_ ### [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html) **get\_all\_item\_ids**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#packedint32array-get_all_item_ids "Permanent link") _(This method has no documentation)_ ### [VoxelInstanceLibraryItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/) **get\_item**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) id )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#voxelinstancelibraryitem-get_item-int-id "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#) **remove\_item**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) id )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/#void-remove_item-int-id "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelInstanceLibraryItem - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelInstanceLibraryItem * * * VoxelInstanceLibraryItem[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#voxelinstancelibraryitem "Permanent link") ================================================================================================================================================== Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Inherited by: [VoxelInstanceLibraryMultiMeshItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/) , [VoxelInstanceLibrarySceneItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrarySceneItem/) Settings for a model that can be used by [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#properties "Permanent link") ----------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [floating\_sdf\_offset\_along\_normal](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#i_floating_sdf_offset_along_normal) | \-0.1 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [floating\_sdf\_threshold](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#i_floating_sdf_threshold) | 0.0 | | [VoxelInstanceGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/) | [generator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#i_generator) | | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [lod\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#i_lod_index) | 0 | | [String](https://docs.godotengine.org/en/stable/classes/class_string.html) | [name](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#i_name) | "" | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [persistent](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#i_persistent) | false | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#property-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------------- ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **floating\_sdf\_offset\_along\_normal** = -0.1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#float-floating_sdf_offset_along_normal-01 "Permanent link") Offset along instances upward axis to apply when the object is tested for being floating or not. An instance is determined to be floating if the SDF at its origin is greater than 0. However, in practice, SDF can be imprecise, and the way instances spawn on triangles of meshes means SDF at their position will always fluctuate a bit around 0. This can lead instances to be overly removed after digging around them, or not enough. You can attempt to fix this by increasing this offset to very small values, so SDF slightly below instances (usually underground) is tested instead. Negative values will check below, positive will check above. Make sure to test resulting behaviors. WARNING: changing this too high can break automatic removal entirely, but is relatively safer than [floating\_sdf\_threshold](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#i_floating_sdf_threshold) . ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **floating\_sdf\_threshold** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#float-floating_sdf_threshold-00 "Permanent link") Threshold used to find if SDF is air. If the SDF at the sampled location is greater, the instance is considered floating. See also [floating\_sdf\_offset\_along\_normal](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#i_floating_sdf_offset_along_normal) for more info. WARNING: changing this too high can break automatic removal entirely. While this can "turn off" removal after digging ground, it is not recommended to do this when instances have no collider, because then it leaves no way of removing them. ### [VoxelInstanceGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/) **generator**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#voxelinstancegenerator-generator "Permanent link") Generator that will be used to pick points where the item will spawn. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **lod\_index** = 0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#int-lod_index-0 "Permanent link") LOD index of chunks of the terrain where this item will spawn. The higher it is, the broader the range it will spawn at around viewers, however it will have lower precision because it uses meshes of a lower level of detail. Prefer spawning larger objects on higher LOD indexes (large trees, boulders), and small objects on lower LOD indexes (grass, small rocks) ### [String](https://docs.godotengine.org/en/stable/classes/class_string.html) **name** = ""[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#string-name "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **persistent** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/#bool-persistent-false "Permanent link") If not enabled, items will always spawn if generator conditions are met: for example, if you dig a hole, it will remove grass in the surface, but if you leave the area and come back, grass will spawn inside the hole. If enabled, and if the terrain has a [VoxelStream](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/) supporting instances, this item will be saved in chunks where instances of it got modified (following the same events as voxel modifications), so if you leave and come back, instances of the item will remain in the same state as you left them. Only the transform of items is saved. Note: saving relies on identifying the item in save files with the same number given in the [VoxelInstanceLibrary](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/) . Removing the item or changing its ID can lead saves to load the item incorrectly. See also [https://voxel-tools.readthedocs.io/en/latest/instancing/#persistence](https://voxel-tools.readthedocs.io/en/latest/instancing/#persistence) _Generated on Aug 20, 2026_ --- # VoxelMesher - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelMesher * * * VoxelMesher[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/#voxelmesher "Permanent link") =========================================================================================================== Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Inherited by: [VoxelMesherBlocky](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/) , [VoxelMesherCubes](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/) , [VoxelMesherTransvoxel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/) Base class for all meshing algorithms. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/#description "Permanent link") ------------------------------------------------------------------------------------------------------------ In order to be rendered by Godot, voxels can be transformed into a mesh. There are various ways to do this, that's why this class is only a base for other, specialized ones. Voxel nodes automatically make use of meshers, but you can also produce meshes manually. For this, you may use one of the derived classes. Meshers can be re-used, which often yields better performance by reducing memory allocations. Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/#methods "Permanent link") ---------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) | [build\_mesh](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/#i_build_mesh)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
voxel\_buffer, [Material\[\]](https://docs.godotengine.org/en/stable/classes/class_material[].html)
materials, [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html)
additional\_data={} ) | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_maximum\_padding](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/#i_get_maximum_padding)
( ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_minimum\_padding](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/#i_get_minimum_padding)
( ) const | Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/#method-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------- ### [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) **build\_mesh**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) voxel\_buffer, [Material\[\]](https://docs.godotengine.org/en/stable/classes/class_material[].html) materials, [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) additional\_data={} )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/#mesh-build_mesh-voxelbuffer-voxel_buffer-material-materials-dictionary-additional_data "Permanent link") Builds a mesh from the provided voxels. Materials will be attached to each surface based on the provided array. The way materials are used can depend on the type of mesher. Meshers are initially meant to work on chunks, so voxels within an outer margin of the buffer will not be part of the result. They are considered "neighbors" and may eventually affect face culling. If you want to use a mesher to make a standalone voxel mesh, make sure it is padded by air. The size of that margin is determined by [get\_minimum\_padding](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/#i_get_minimum_padding) and [get\_maximum\_padding](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/#i_get_maximum_padding) . ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_maximum\_padding**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/#int-get_maximum_padding "Permanent link") Gets by how much voxels must be padded before their lower corner in order for the mesher to work. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_minimum\_padding**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/#int-get_minimum_padding "Permanent link") Gets by how much voxels must be padded after their upper corner in order for the mesher to work. _Generated on Aug 20, 2026_ --- # VoxelModifier - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelModifier * * * VoxelModifier[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifier/#voxelmodifier "Permanent link") ================================================================================================================= Inherits: [Node3D](https://docs.godotengine.org/en/stable/classes/class_node3d.html) Inherited by: [VoxelModifierMesh](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierMesh/) , [VoxelModifierSphere](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierSphere/) Base class for voxel modifiers. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifier/#description "Permanent link") -------------------------------------------------------------------------------------------------------------- Modifiers are meant to be as an extension to terrain's generator that non-destructively affect limited volume. Stacks with other modifiers. Runtime edits from [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) override modifier values. Note 1: Only works with [VoxelLodTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/) . Note 2: Only works with smooth terrain (SDF). Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifier/#properties "Permanent link") ------------------------------------------------------------------------------------------------------------ | Type | Name | Default | | --- | --- | --- | | [Operation](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifier/#enumerations) | [operation](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifier/#i_operation) | OPERATION\_ADD (0) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [smoothness](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifier/#i_smoothness) | 0.0 | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifier/#enumerations "Permanent link") ---------------------------------------------------------------------------------------------------------------- enum **Operation**: * **OPERATION\_ADD** = **0** --- Performs SDF union. * **OPERATION\_REMOVE** = **1** --- Performs SDF subtraction. Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifier/#property-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------------- ### [Operation](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifier/#enumerations) **operation** = OPERATION\_ADD (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifier/#operation-operation-operation_add-0 "Permanent link") An operation that the modifier performs on the terrain or on the other modifiers. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **smoothness** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifier/#float-smoothness-00 "Permanent link") Increasing this value makes the shape "merge" with its surroundings across a more or less large distance. Note, it assumes the base generator produces consistent gradients. This is not always the case. Notably, it is a common optimization for generators to avoid calculating gradients beyond a certain distance from surfaces. If smoothness is too large, or if the generator's cutoff distance is too low, it can lead to gaps in the resulting mesh, usually at chunk boundaries. _Generated on Aug 20, 2026_ --- # VoxelMesherCubes - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelMesherCubes * * * VoxelMesherCubes[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#voxelmeshercubes "Permanent link") ========================================================================================================================== Inherits: [VoxelMesher](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/) Generates a cubic voxels mesh from colors. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#description "Permanent link") ----------------------------------------------------------------------------------------------------------------- Builds meshes representing cubic voxels, based on color values stored in the [VoxelBuffer.CHANNEL\_COLOR](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_COLOR) channel. Colors will usually be stored in the `COLOR` vertex attribute and may require a material with vertex colors enabled, or a custom shader. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#properties "Permanent link") --------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [ColorMode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#enumerations) | [color\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#i_color_mode) | COLOR\_RAW (0) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [greedy\_meshing\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#i_greedy_meshing_enabled) | true | | [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) | [opaque\_material](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#i_opaque_material) | | | [VoxelColorPalette](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/) | [palette](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#i_palette) | | | [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) | [transparent\_material](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#i_transparent_material) | | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#methods "Permanent link") --------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) | [generate\_mesh\_from\_image](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#i_generate_mesh_from_image)
( [Image](https://docs.godotengine.org/en/stable/classes/class_image.html)
image, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
voxel\_size ) static | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#) | [set\_material\_by\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#i_set_material_by_index)
( [Materials](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#enumerations)
id, [Material](https://docs.godotengine.org/en/stable/classes/class_material.html)
material ) | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#enumerations "Permanent link") ------------------------------------------------------------------------------------------------------------------- enum **Materials**: * **MATERIAL\_OPAQUE** = **0** --- Index of the opaque material. * **MATERIAL\_TRANSPARENT** = **1** --- Index of the transparent material. * **MATERIAL\_COUNT** = **2** --- Maximum number of materials. enum **ColorMode**: * **COLOR\_RAW** = **0** --- Voxel values will be directly interpreted as colors. 8-bit voxels are interpreted as `rrggbbaa` (2 bits per component) where the range per component is converted from 0..3 to 0..255. 16-bit voxels are interpreted as `rrrrgggg bbbbaaaa` (4 bits per component) where the range per component is converted from 0..15 to 0..255. 32-bit voxels are interpreted as `rrrrrrrr gggggggg bbbbbbbb aaaaaaaa` (8 bits per component) where each component is in 0..255. * **COLOR\_MESHER\_PALETTE** = **1** --- Voxel values will be interpreted as indices within the color palette assigned in the [palette](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#i_palette) property. * **COLOR\_SHADER\_PALETTE** = **2** --- Voxel values will be directly written as such in the mesh, instead of colors. They are written in the red component of the `COLOR`, leaving red and blue to zero. Note, it will be normalized to 0..1 in shader, so if you need the integer value back you may use `int(COLOR.r * 255.0)`. The alpha component will be set to the transparency of the corresponding color in [palette](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#i_palette) (a palette resource is still needed to differenciate transparent parts; RGB values are not used). You are expected to use a [ShaderMaterial](https://docs.godotengine.org/en/stable/classes/class_shadermaterial.html) to read vertex data and choose the actual color with a custom shader. [StandardMaterial](https://docs.godotengine.org/en/stable/classes/class_standardmaterial.html) will not work with this mode. Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ ### [ColorMode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#enumerations) **color\_mode** = COLOR\_RAW (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#colormode-color_mode-color_raw-0 "Permanent link") Sets how voxel color is determined when building the mesh. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **greedy\_meshing\_enabled** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#bool-greedy_meshing_enabled-true "Permanent link") Enables greedy meshing: the mesher will attempt to merge contiguous faces having the same color to reduce the number of polygons. ### [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) **opaque\_material**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#material-opaque_material "Permanent link") Material that will be used for opaque parts of the mesh. ### [VoxelColorPalette](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/) **palette**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#voxelcolorpalette-palette "Permanent link") Palette that will be used when using the [COLOR\_MESHER\_PALETTE](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#i_COLOR_MESHER_PALETTE) color mode. ### [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) **transparent\_material**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#material-transparent_material "Permanent link") Material that will be used for transparent parts of the mesh (colors where alpha is not set to max). Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#method-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- ### [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) **generate\_mesh\_from\_image**( [Image](https://docs.godotengine.org/en/stable/classes/class_image.html) image, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) voxel\_size )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#mesh-generate_mesh_from_image-image-image-float-voxel_size "Permanent link") Generates a 1-voxel thick greedy mesh from pixels of an image. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#) **set\_material\_by\_index**( [Materials](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#enumerations) id, [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) material )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#void-set_material_by_index-materials-id-material-material "Permanent link") Sets one of the materials that will be used when building meshes. This is equivalent to using either [opaque\_material](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#i_opaque_material) or [transparent\_material](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/#i_transparent_material) . _Generated on Aug 20, 2026_ --- # VoxelInstancerRigidBody - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelInstancerRigidBody * * * VoxelInstancerRigidBody[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancerRigidBody/#voxelinstancerrigidbody "Permanent link") =============================================================================================================================================== Inherits: [RigidBody3D](https://docs.godotengine.org/en/stable/classes/class_rigidbody3d.html) Collision node generated for every collidable multimesh instance created by [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) . Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancerRigidBody/#description "Permanent link") ------------------------------------------------------------------------------------------------------------------------ Instances generated from [VoxelInstanceLibraryMultiMeshItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/) don't use nodes to render. However, they can be given collision, in the form of body nodes using this class. Calling `queue_free()` on an instance of this node will also unregister the instance from [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) . Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancerRigidBody/#methods "Permanent link") ---------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_library\_item\_id](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancerRigidBody/#i_get_library_item_id)
( ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancerRigidBody/#) | [queue\_free\_and\_notify\_instancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancerRigidBody/#i_queue_free_and_notify_instancer)
( ) | Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancerRigidBody/#method-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------- ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_library\_item\_id**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancerRigidBody/#int-get_library_item_id "Permanent link") Gets the ID of the item in the instancer's [VoxelInstanceLibrary](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/) that was used to create the instance having this collider. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancerRigidBody/#) **queue\_free\_and\_notify\_instancer**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancerRigidBody/#void-queue_free_and_notify_instancer "Permanent link") Alternative to `queue_free` in case you don't want to use `call_deferred` to add nodes under [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) from [VoxelInstanceLibraryMultiMeshItem.\_on\_instance\_removed](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i__on_instance_removed) . _Generated on Aug 20, 2026_ --- # All classes - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * All classes * * * All classes[¶](https://voxel-tools.readthedocs.io/en/latest/api/all_classes/#all-classes "Permanent link") =========================================================================================================== * Object * Node * Node3D * RigidBody3D * [VoxelInstancerRigidBody](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancerRigidBody/) * [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) * [VoxelModifier](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifier/) * [VoxelModifierMesh](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierMesh/) * [VoxelModifierSphere](https://voxel-tools.readthedocs.io/en/latest/api/VoxelModifierSphere/) * [VoxelNode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/) * [VoxelLodTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/) * [VoxelTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/) * [VoxelViewer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/) * [VoxelInstanceComponent](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceComponent/) * [VoxelTerrainMultiplayerSynchronizer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrainMultiplayerSynchronizer/) * RefCounted * Resource * [FastNoise2](https://voxel-tools.readthedocs.io/en/latest/api/FastNoise2/) * [VoxelBlockyAttribute](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttribute/) * [VoxelBlockyAttributeAxis](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeAxis/) * [VoxelBlockyAttributeCustom](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeCustom/) * [VoxelBlockyAttributeDirection](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeDirection/) * [VoxelBlockyAttributeRotation](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyAttributeRotation/) * [VoxelBlockyFluid](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyFluid/) * [VoxelBlockyLibraryBase](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/) * [VoxelBlockyLibrary](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/) * [VoxelBlockyTypeLibrary](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/) * [VoxelBlockyModel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/) * [VoxelBlockyModelCube](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelCube/) * [VoxelBlockyModelEmpty](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelEmpty/) * [VoxelBlockyModelFluid](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelFluid/) * [VoxelBlockyModelMesh](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelMesh/) * [VoxelBlockyType](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/) * [VoxelColorPalette](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/) * [VoxelFormat](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/) * [VoxelGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/) * [VoxelGeneratorFlat](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorFlat/) * [VoxelGeneratorGraph](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/) * [VoxelGeneratorHeightmap](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/) * [VoxelGeneratorImage](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorImage/) * [VoxelGeneratorNoise2D](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise2D/) * [VoxelGeneratorWaves](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorWaves/) * [VoxelGeneratorMultipassCB](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/) * [VoxelGeneratorNoise](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise/) * [VoxelGeneratorScript](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorScript/) * [VoxelGraphFunction](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/) * [VoxelInstanceGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/) * [VoxelInstanceLibrary](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/) * [VoxelInstanceLibraryItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/) * [VoxelInstanceLibraryMultiMeshItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/) * [VoxelInstanceLibrarySceneItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrarySceneItem/) * [VoxelMeshSDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/) * [VoxelMesher](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/) * [VoxelMesherBlocky](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/) * [VoxelMesherCubes](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/) * [VoxelMesherTransvoxel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/) * [VoxelStream](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/) * [VoxelStreamMemory](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamMemory/) * [VoxelStreamRegionFiles](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/) * [VoxelStreamSQLite](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/) * [VoxelStreamScript](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamScript/) * [ZN\_FastNoiseLite](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/) * [ZN\_FastNoiseLiteGradient](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/) * [ZN\_SpotNoise](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/) * [VoxelAStarGrid3D](https://voxel-tools.readthedocs.io/en/latest/api/VoxelAStarGrid3D/) * [VoxelBlockSerializer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/) * [VoxelBoxMover](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/) * [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) * [VoxelRaycastResult](https://voxel-tools.readthedocs.io/en/latest/api/VoxelRaycastResult/) * [VoxelSaveCompletionTracker](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/) * [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) * [VoxelToolBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolBuffer/) * [VoxelToolLodTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/) * [VoxelToolMultipassGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/) * [VoxelToolTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/) * [VoxelVoxLoader](https://voxel-tools.readthedocs.io/en/latest/api/VoxelVoxLoader/) * [ZN\_ThreadedTask](https://voxel-tools.readthedocs.io/en/latest/api/ZN_ThreadedTask/) * [VoxelDataBlockEnterInfo](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/) * [VoxelEngine](https://voxel-tools.readthedocs.io/en/latest/api/VoxelEngine/) --- # VoxelBlockyModelMesh - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockyModelMesh * * * VoxelBlockyModelMesh[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelMesh/#voxelblockymodelmesh "Permanent link") ====================================================================================================================================== Inherits: [VoxelBlockyModel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/) Generates a model based on a custom mesh. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelMesh/#description "Permanent link") --------------------------------------------------------------------------------------------------------------------- [VoxelMesherBlocky](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/) does not require models to be cubes. Ultimately, model visuals are all meshes. This is the most versatile option to make a model. The workflow is to make these models in a 3D editor such as Blender, making sure they are confined in a box going from (0,0) to (1,1). Textures are assigned with classic UV-mapping. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelMesh/#properties "Permanent link") ------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) | [mesh](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelMesh/#i_mesh) | | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [mesh\_ortho\_rotation\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelMesh/#i_mesh_ortho_rotation_index) | 0 | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [side\_cutout\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelMesh/#i_side_cutout_enabled) | false | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [side\_vertex\_tolerance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelMesh/#i_side_vertex_tolerance) | 0.001 | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelMesh/#property-descriptions "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------- ### [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) **mesh**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelMesh/#mesh-mesh "Permanent link") Mesh that will be used for this model. Must not be empty (if you want an empty model, use [VoxelBlockyModelEmpty](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelEmpty/) ). If it has more than 2 surfaces (2 materials) the next surfaces will be ignored. Surfaces must be made of triangles. Must be indexed (if you generate meshes with [SurfaceTool](https://docs.godotengine.org/en/stable/classes/class_surfacetool.html) , use [SurfaceTool.index](https://docs.godotengine.org/en/stable/classes/class_surfacetool.html#class-surfacetool-method-index) ). Should ideally contain geometry within a 0..1 area. Only triangles located on the sides of that cubic area will be considered for neighbor side culling (see also [side\_vertex\_tolerance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelMesh/#i_side_vertex_tolerance) ). ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **mesh\_ortho\_rotation\_index** = 0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelMesh/#int-mesh_ortho_rotation_index-0 "Permanent link") Orthogonal rotation applied to the mesh when baking. Values are taken from the same convention as [GridMap](https://docs.godotengine.org/en/stable/classes/class_gridmap.html) tiles. ([GridMap](https://docs.godotengine.org/en/stable/classes/class_gridmap.html) provides a conversion method from [Basis](https://docs.godotengine.org/en/stable/classes/class_basis.html) , unfortunately it is not a static method so it requires a [GridMap](https://docs.godotengine.org/en/stable/classes/class_gridmap.html) instance to exist. A helper method could be added in the future if requested) ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **side\_cutout\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelMesh/#bool-side_cutout_enabled-false "Permanent link") When a neighbor voxel partially covers a side of this voxel, the occluded geometry of the side will be cut away. This only works if the shape of both sides is a rectangle. Note, enabling this option can actually produce more triangles than when it is enabled. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **side\_vertex\_tolerance** = 0.001[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModelMesh/#float-side_vertex_tolerance-0001 "Permanent link") Margin below which triangles located near one of the 6 sides of the voxel will be considered on that side. Sides get culled or not by comparing between triangles of neighbor sides. _Generated on Aug 20, 2026_ --- # ZN_ThreadedTask - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * ZN\_ThreadedTask * * * ZN\_ThreadedTask[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_ThreadedTask/#zn_threadedtask "Permanent link") ======================================================================================================================== Inherits: [RefCounted](https://docs.godotengine.org/en/stable/classes/class_refcounted.html) Warning This class is marked as experimental. It is subject to likely change or possible removal in future versions. Use at your own discretion. Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_ThreadedTask/#methods "Permanent link") -------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [\_get\_priority](https://voxel-tools.readthedocs.io/en/latest/api/ZN_ThreadedTask/#i__get_priority)
( ) virtual | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [\_is\_cancelled](https://voxel-tools.readthedocs.io/en/latest/api/ZN_ThreadedTask/#i__is_cancelled)
( ) virtual | | [void](https://voxel-tools.readthedocs.io/en/latest/api/ZN_ThreadedTask/#) | [\_run](https://voxel-tools.readthedocs.io/en/latest/api/ZN_ThreadedTask/#i__run)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
thread\_index ) virtual | Signals:[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_ThreadedTask/#signals "Permanent link") -------------------------------------------------------------------------------------------------------- ### completed( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_ThreadedTask/#completed "Permanent link") _(This signal has no documentation)_ Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_ThreadedTask/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **\_get\_priority**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_ThreadedTask/#int-_get_priority "Permanent link") _(This method has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **\_is\_cancelled**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_ThreadedTask/#bool-_is_cancelled "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/ZN_ThreadedTask/#) **\_run**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) thread\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_ThreadedTask/#void-_run-int-thread_index "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # Compressed data format - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Serialization formats * Compressed data format * * * Compressed data format[¶](https://voxel-tools.readthedocs.io/en/latest/specs/compressed_container/#compressed-data-format "Permanent link") ============================================================================================================================================ Some custom formats used in this engine can be wrapped in a compressed container. Specification[¶](https://voxel-tools.readthedocs.io/en/latest/specs/compressed_container/#specification "Permanent link") -------------------------------------------------------------------------------------------------------------------------- ### Endianness[¶](https://voxel-tools.readthedocs.io/en/latest/specs/compressed_container/#endianness "Permanent link") By default, little-endian. ### Compressed container[¶](https://voxel-tools.readthedocs.io/en/latest/specs/compressed_container/#compressed-container "Permanent link") CompressedData - uint8_t format - data Compressed data starts with one byte. Depending on its value, what follows is different. * `0`: no compression. Following bytes can be read directly. This is rarely used and could be for debugging. * `1`: LZ4\_BE compression, _deprecated_. The next big-endian 32-bit unsigned integer is the size of the decompressed data, and following bytes are compressed data using LZ4 default parameters. * `2`: LZ4 compression, The next little-endian 32-bit unsigned integer is the size of the decompressed data, and following bytes are compressed data using LZ4 default parameters. This is the default mode. * `3`: Zstandard compression. The next little-endian 32-bit unsigned integer is the size of the decompressed data, and the following bytes are compressed data using Zstandard default parameters. Note Depending on the type of data, knowing its decompressed size may be important when parsing it later. --- # VoxelTerrainMultiplayerSynchronizer - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelTerrainMultiplayerSynchronizer * * * VoxelTerrainMultiplayerSynchronizer[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrainMultiplayerSynchronizer/#voxelterrainmultiplayersynchronizer "Permanent link") =================================================================================================================================================================================== Inherits: [Node](https://docs.godotengine.org/en/stable/classes/class_node.html) _Generated on Aug 20, 2026_ --- # VoxelStreamScript - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelStreamScript * * * VoxelStreamScript[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamScript/#voxelstreamscript "Permanent link") ============================================================================================================================= Inherits: [VoxelStream](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/) Base class for custom streams defined with a script. Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamScript/#methods "Permanent link") ---------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [\_get\_used\_channels\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamScript/#i__get_used_channels_mask)
( ) virtual const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [\_load\_voxel\_block](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamScript/#i__load_voxel_block)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
out\_buffer, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
position\_in\_blocks, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
lod ) virtual | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamScript/#) | [\_save\_voxel\_block](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamScript/#i__save_voxel_block)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
buffer, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
position\_in\_blocks, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
lod ) virtual | Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamScript/#method-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------------- ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **\_get\_used\_channels\_mask**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamScript/#int-_get_used_channels_mask "Permanent link") Tells which channels in [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) are supported to save voxel data, in case the stream only saves specific ones. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **\_load\_voxel\_block**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) out\_buffer, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) position\_in\_blocks, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) lod )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamScript/#int-_load_voxel_block-voxelbuffer-out_buffer-vector3i-position_in_blocks-int-lod "Permanent link") Called when a block of voxels needs to be loaded. Assumes `out_buffer` always has the same size. Returns [ResultCode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#enumerations) . ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamScript/#) **\_save\_voxel\_block**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) buffer, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) position\_in\_blocks, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) lod )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamScript/#void-_save_voxel_block-voxelbuffer-buffer-vector3i-position_in_blocks-int-lod "Permanent link") Called when a block of voxels needs to be saved. Assumes `out_buffer` always has the same size. _Generated on Aug 20, 2026_ --- # VoxelToolBuffer - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelToolBuffer * * * VoxelToolBuffer[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolBuffer/#voxeltoolbuffer "Permanent link") ======================================================================================================================= Inherits: [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) Implementation of the [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) API for [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) . Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolBuffer/#description "Permanent link") ---------------------------------------------------------------------------------------------------------------- There are no functions specific to [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) . You may check generic ones in [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) . Note: contrary to other implementations, this one allows editing even if the area is partially out of bounds. _Generated on Aug 20, 2026_ --- # VoxelColorPalette - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelColorPalette * * * VoxelColorPalette[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#voxelcolorpalette "Permanent link") ============================================================================================================================= Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Limited list of 256 colors in 8-bit format that can be indexed quickly. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#description "Permanent link") ------------------------------------------------------------------------------------------------------------------ Contains a list of colors that can be accessed quickly by their index. This is useful to store colored voxels with small memory footprint. It can be used with [VoxelMesherCubes](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/) . Note: colors are internally stored with 8-bit components, so floats used by [Color](https://docs.godotengine.org/en/stable/classes/class_color.html) will be rounded to the nearest value. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#properties "Permanent link") ---------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [PackedColorArray](https://docs.godotengine.org/en/stable/classes/class_packedcolorarray.html) | [colors](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#i_colors) | PackedColorArray(0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1) | | [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html) | [data](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#i_data) | PackedInt32Array(0, -1, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255) | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#methods "Permanent link") ---------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [Color](https://docs.godotengine.org/en/stable/classes/class_color.html) | [get\_color](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#i_get_color)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
index ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#) | [set\_color](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#i_set_color)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
index, [Color](https://docs.godotengine.org/en/stable/classes/class_color.html)
color ) | Constants:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#constants "Permanent link") -------------------------------------------------------------------------------------------------------------- * **MAX\_COLORS** = **256** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------- ### [PackedColorArray](https://docs.godotengine.org/en/stable/classes/class_packedcolorarray.html) **colors** = PackedColorArray(0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#packedcolorarray-colors-packedcolorarray0-0-0-0-1-1-1-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1-0-0-0-1 "Permanent link") Array of all the colors in the palette. It must have 256 elements. You may use this if you want to get or set all colors at once. Otherwise, prefer using [get\_color](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#i_get_color) and [set\_color](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#i_set_color) . ### [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html) **data** = PackedInt32Array(0, -1, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#packedint32array-data-packedint32array0-1-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255-255 "Permanent link") Array used to store colors as 8-bit binary components in the resource file. It must have 256 elements. To access colors with a script, prefer using [get\_color](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#i_get_color) and [set\_color](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#i_set_color) . Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#method-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------------- ### [Color](https://docs.godotengine.org/en/stable/classes/class_color.html) **get\_color**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#color-get_color-int-index "Permanent link") Gets the color at the given index. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#) **set\_color**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) index, [Color](https://docs.godotengine.org/en/stable/classes/class_color.html) color )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/#void-set_color-int-index-color-color "Permanent link") Sets the color at the given index. _Generated on Aug 20, 2026_ --- # VoxelBlockyTypeLibrary - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBlockyTypeLibrary * * * VoxelBlockyTypeLibrary[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#voxelblockytypelibrary "Permanent link") ============================================================================================================================================ Inherits: [VoxelBlockyLibraryBase](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/) Warning This class is marked as experimental. It is subject to likely change or possible removal in future versions. Use at your own discretion. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#properties "Permanent link") --------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [PackedStringArray](https://docs.godotengine.org/en/stable/classes/class_packedstringarray.html) | [\_id\_map\_data](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#i__id_map_data) | PackedStringArray() | | [VoxelBlockyType\[\]](https://docs.godotengine.org/en/stable/classes/class_voxelblockytype[].html) | [types](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#i_types) | \[\] | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#methods "Permanent link") --------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_model\_index\_default](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#i_get_model_index_default)
( [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html)
type\_name ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_model\_index\_single\_attribute](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#i_get_model_index_single_attribute)
( [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html)
type\_name, [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html)
attrib\_value ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_model\_index\_with\_attributes](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#i_get_model_index_with_attributes)
( [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html)
type\_name, [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html)
attribs\_dict ) const | | [VoxelBlockyType](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/) | [get\_type\_from\_name](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#i_get_type_from_name)
( [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html)
type\_name ) const | | [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) | [get\_type\_name\_and\_attributes\_from\_model\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#i_get_type_name_and_attributes_from_model_index)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
model\_index ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [load\_id\_map\_from\_json](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#i_load_id_map_from_json)
( [String](https://docs.godotengine.org/en/stable/classes/class_string.html)
json ) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [load\_id\_map\_from\_string\_array](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#i_load_id_map_from_string_array)
( [PackedStringArray](https://docs.godotengine.org/en/stable/classes/class_packedstringarray.html)
str\_array ) | | [String](https://docs.godotengine.org/en/stable/classes/class_string.html) | [serialize\_id\_map\_to\_json](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#i_serialize_id_map_to_json)
( ) const | | [PackedStringArray](https://docs.godotengine.org/en/stable/classes/class_packedstringarray.html) | [serialize\_id\_map\_to\_string\_array](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#i_serialize_id_map_to_string_array)
( ) const | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------ ### [PackedStringArray](https://docs.godotengine.org/en/stable/classes/class_packedstringarray.html) **\_id\_map\_data** = PackedStringArray()[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#packedstringarray-_id_map_data-packedstringarray "Permanent link") _(This property has no documentation)_ ### [VoxelBlockyType\[\]](https://docs.godotengine.org/en/stable/classes/class_voxelblockytype[].html) **types** = \[\][¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#voxelblockytype-types "Permanent link") _(This property has no documentation)_ Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#method-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------- ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_model\_index\_default**( [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html) type\_name )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#int-get_model_index_default-stringname-type_name "Permanent link") _(This method has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_model\_index\_single\_attribute**( [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html) type\_name, [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) attrib\_value )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#int-get_model_index_single_attribute-stringname-type_name-variant-attrib_value "Permanent link") _(This method has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_model\_index\_with\_attributes**( [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html) type\_name, [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) attribs\_dict )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#int-get_model_index_with_attributes-stringname-type_name-dictionary-attribs_dict "Permanent link") _(This method has no documentation)_ ### [VoxelBlockyType](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyType/) **get\_type\_from\_name**( [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html) type\_name )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#voxelblockytype-get_type_from_name-stringname-type_name "Permanent link") _(This method has no documentation)_ ### [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) **get\_type\_name\_and\_attributes\_from\_model\_index**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) model\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#array-get_type_name_and_attributes_from_model_index-int-model_index "Permanent link") _(This method has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **load\_id\_map\_from\_json**( [String](https://docs.godotengine.org/en/stable/classes/class_string.html) json )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#bool-load_id_map_from_json-string-json "Permanent link") _(This method has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **load\_id\_map\_from\_string\_array**( [PackedStringArray](https://docs.godotengine.org/en/stable/classes/class_packedstringarray.html) str\_array )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#bool-load_id_map_from_string_array-packedstringarray-str_array "Permanent link") _(This method has no documentation)_ ### [String](https://docs.godotengine.org/en/stable/classes/class_string.html) **serialize\_id\_map\_to\_json**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#string-serialize_id_map_to_json "Permanent link") _(This method has no documentation)_ ### [PackedStringArray](https://docs.godotengine.org/en/stable/classes/class_packedstringarray.html) **serialize\_id\_map\_to\_string\_array**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyTypeLibrary/#packedstringarray-serialize_id_map_to_string_array "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelMesherBlocky - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelMesherBlocky * * * VoxelMesherBlocky[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#voxelmesherblocky "Permanent link") ============================================================================================================================= Inherits: [VoxelMesher](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/) Produces a mesh by batching models corresponding to each voxel value, similar to games like Minecraft or StarMade. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#description "Permanent link") ------------------------------------------------------------------------------------------------------------------ Occluded faces are removed from the result, and some degree of ambient occlusion can be baked on the edges. Values are expected to be in the [VoxelBuffer.CHANNEL\_TYPE](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_TYPE) channel. Models are defined with a [VoxelBlockyLibrary](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibrary/) , in which model indices correspond to the voxel values. Models don't have to be cubes. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#properties "Permanent link") ---------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [VoxelBlockyLibraryBase](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/) | [library](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#i_library) | | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [occlusion\_darkness](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#i_occlusion_darkness) | 0.8 | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [occlusion\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#i_occlusion_enabled) | true | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [shadow\_occluder\_negative\_x](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#i_shadow_occluder_negative_x) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [shadow\_occluder\_negative\_y](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#i_shadow_occluder_negative_y) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [shadow\_occluder\_negative\_z](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#i_shadow_occluder_negative_z) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [shadow\_occluder\_positive\_x](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#i_shadow_occluder_positive_x) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [shadow\_occluder\_positive\_y](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#i_shadow_occluder_positive_y) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [shadow\_occluder\_positive\_z](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#i_shadow_occluder_positive_z) | false | | [TintMode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#enumerations) | [tint\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#i_tint_mode) | TINT\_NONE (0) | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#methods "Permanent link") ---------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [get\_shadow\_occluder\_side](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#i_get_shadow_occluder_side)
( [Side](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#enumerations)
side ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#) | [set\_shadow\_occluder\_side](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#i_set_shadow_occluder_side)
( [Side](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#enumerations)
side, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
enabled ) | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#enumerations "Permanent link") -------------------------------------------------------------------------------------------------------------------- enum **Side**: * **SIDE\_NEGATIVE\_X** = **0** * **SIDE\_POSITIVE\_X** = **1** * **SIDE\_NEGATIVE\_Y** = **2** * **SIDE\_POSITIVE\_Y** = **3** * **SIDE\_NEGATIVE\_Z** = **4** * **SIDE\_POSITIVE\_Z** = **5** enum **TintMode**: * **TINT\_NONE** = **0** --- Only use colors from library models. * **TINT\_RAW\_COLOR** = **1** --- Modulate voxel colors based on the [VoxelBuffer.CHANNEL\_COLOR](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_COLOR) channel. Values are interpreted as being raw RGBA color. If the channel is 16-bit, colors are packed with 4 bits per component. If 32-bits, colors are packed with 8 bits per component. Other depths are not supported. See [VoxelTool.color\_to\_u32](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_color_to_u32) for encoding. You may also change the format of the color channel to use this, see [VoxelNode.format](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#i_format) . Alpha will only have an effect if the material supports transparency, but will not affect how faces are culled by the mesher. Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------- ### [VoxelBlockyLibraryBase](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/) **library**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#voxelblockylibrarybase-library "Permanent link") Library of models that will be used by this mesher. If you are using a mesher without a terrain, make sure you call [VoxelBlockyLibraryBase.bake](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyLibraryBase/#i_bake) before building meshes, otherwise results will be empty or out-of-date. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **occlusion\_darkness** = 0.8[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#float-occlusion_darkness-08 "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **occlusion\_enabled** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#bool-occlusion_enabled-true "Permanent link") Enables baked ambient occlusion. To render it, you need a material that applies vertex colors. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **shadow\_occluder\_negative\_x** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#bool-shadow_occluder_negative_x-false "Permanent link") When enabled, generates a quad covering the negative X side of the chunk if it is fully covered by opaque voxels, in order to force directional lights to project a shadow. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **shadow\_occluder\_negative\_y** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#bool-shadow_occluder_negative_y-false "Permanent link") When enabled, generates a quad covering the negative Y side of the chunk if it is fully covered by opaque voxels, in order to force directional lights to project a shadow. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **shadow\_occluder\_negative\_z** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#bool-shadow_occluder_negative_z-false "Permanent link") When enabled, generates a quad covering the negative Z side of the chunk if it is fully covered by opaque voxels, in order to force directional lights to project a shadow. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **shadow\_occluder\_positive\_x** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#bool-shadow_occluder_positive_x-false "Permanent link") When enabled, generates a quad covering the positive X side of the chunk if it is fully covered by opaque voxels, in order to force directional lights to project a shadow. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **shadow\_occluder\_positive\_y** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#bool-shadow_occluder_positive_y-false "Permanent link") When enabled, generates a quad covering the positive Y side of the chunk if it is fully covered by opaque voxels, in order to force directional lights to project a shadow. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **shadow\_occluder\_positive\_z** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#bool-shadow_occluder_positive_z-false "Permanent link") When enabled, generates a quad covering the positive Z side of the chunk if it is fully covered by opaque voxels, in order to force directional lights to project a shadow. ### [TintMode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#enumerations) **tint\_mode** = TINT\_NONE (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#tintmode-tint_mode-tint_none-0 "Permanent link") Configures a way to apply color from voxel data. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#method-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------------- ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **get\_shadow\_occluder\_side**( [Side](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#enumerations) side )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#bool-get_shadow_occluder_side-side-side "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#) **set\_shadow\_occluder\_side**( [Side](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#enumerations) side, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) enabled )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/#void-set_shadow_occluder_side-side-side-bool-enabled "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelToolMultipassGenerator - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelToolMultipassGenerator * * * VoxelToolMultipassGenerator[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/#voxeltoolmultipassgenerator "Permanent link") =========================================================================================================================================================== Inherits: [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) Provided to edit voxels in the context of multipass terrain generation. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/#description "Permanent link") ---------------------------------------------------------------------------------------------------------------------------- This tool allows to edit voxels within a 3D box, centered on a specific area corresponding to the current chunk or column to generate. Depending on context, it is also possible to edit voxels some distance away from the main area. The difference between "main" and "total" areas, is that the "main" area is where you should generate stuff, while the "total area" is only available in case what you generate needs to overlap outside of the main area. Instances of this class are temporary and not thread-safe. They must never be re-used or stored in a member variable. Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/#methods "Permanent link") -------------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) | [get\_editable\_area\_max](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/#i_get_editable_area_max)
( ) const | | [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) | [get\_editable\_area\_min](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/#i_get_editable_area_min)
( ) const | | [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) | [get\_main\_area\_max](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/#i_get_main_area_max)
( ) const | | [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) | [get\_main\_area\_min](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/#i_get_main_area_min)
( ) const | Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------- ### [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) **get\_editable\_area\_max**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/#vector3i-get_editable_area_max "Permanent link") Gets the upper corner of the total editable area, in voxels, exclusive. ### [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) **get\_editable\_area\_min**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/#vector3i-get_editable_area_min "Permanent link") Gets the lower corner of the total editable area, in voxels. ### [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) **get\_main\_area\_max**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/#vector3i-get_main_area_max "Permanent link") Gets the upper corner of the main editable area, in voxels, exclusive. ### [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) **get\_main\_area\_min**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/#vector3i-get_main_area_min "Permanent link") Gets the lower corner of the main editable area, in voxels. _Generated on Aug 20, 2026_ --- # VoxelMesherTransvoxel - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelMesherTransvoxel * * * VoxelMesherTransvoxel[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#voxelmeshertransvoxel "Permanent link") ========================================================================================================================================= Inherits: [VoxelMesher](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/) Implements isosurface generation (smooth voxels) using the [Transvoxel](https://transvoxel.org/) algorithm. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#description "Permanent link") ---------------------------------------------------------------------------------------------------------------------- Uses the [Transvoxel](https://transvoxel.org/) algorithm to polygonize smooth voxels. Note: if you want to use LOD, you will need special vertex shader code to properly render seams (otherwise they will render as thin sheets between chunks). Check [https://voxel-tools.readthedocs.io/en/latest/smooth\_terrain/#transvoxel](https://voxel-tools.readthedocs.io/en/latest/smooth_terrain/#transvoxel) or demos featuring smooth terrain for more information. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#properties "Permanent link") -------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [edge\_clamp\_margin](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#i_edge_clamp_margin) | 0.02 | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [mesh\_optimization\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#i_mesh_optimization_enabled) | false | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [mesh\_optimization\_error\_threshold](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#i_mesh_optimization_error_threshold) | 0.005 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [mesh\_optimization\_target\_ratio](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#i_mesh_optimization_target_ratio) | 0.0 | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [textures\_ignore\_air\_voxels](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#i_textures_ignore_air_voxels) | false | | [TexturingMode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#enumerations) | [texturing\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#i_texturing_mode) | TEXTURES\_NONE (0) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [transitions\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#i_transitions_enabled) | true | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#methods "Permanent link") -------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [ArrayMesh](https://docs.godotengine.org/en/stable/classes/class_arraymesh.html) | [build\_transition\_mesh](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#i_build_transition_mesh)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
voxel\_buffer, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
direction ) | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#enumerations "Permanent link") ------------------------------------------------------------------------------------------------------------------------ enum **TexturingMode**: * **TEXTURES\_NONE** = **0** --- Disables texturing information. This mode is the fastest if you can use a shader to apply textures procedurally. * **TEXTURES\_MIXEL4\_S4** = **1** --- Expects voxels to have 4 4-bit indices packed in 16-bit values in [VoxelBuffer.CHANNEL\_INDICES](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_INDICES) , and 4 4-bit weights in [VoxelBuffer.CHANNEL\_WEIGHTS](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_WEIGHTS) . Adds texturing information as 4 texture indices and 4 weights, encoded in `CUSTOM1.xy` in Godot fragment shaders, where x and y contain 4 packed 8-bit values. In cases where more than 4 textures cross each other in a 2x2x2 voxel area, triangles in that area will only use the 4 indices with the highest weights. A custom shader is required to render this, usually with texture arrays to index textures easily. * **TEXTURES\_SINGLE\_S4** = **2** --- Expects voxels to have a 8-bit texture index in the [VoxelBuffer.CHANNEL\_INDICES](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_INDICES) channel. Adds texturing information as 4 texture indices and 4 weights, encoded in `CUSTOM1.xy` in Godot fragment shaders, where x and y contain 4 packed 8-bit values. In cases where more than 4 textures cross each other in a 2x2x2 voxel area, triangles in that area will only use the 4 indices with the highest weights. A custom shader is required to render this, usually with texture arrays to index textures easily. Constants:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#constants "Permanent link") ------------------------------------------------------------------------------------------------------------------ * **TEXTURES\_BLEND\_4\_OVER\_16** = **1** --- _This constant is deprecated. Use TEXTURES\_MIXEL4\_S4_ Legacy alias for [TEXTURES\_MIXEL4\_S4](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#i_TEXTURES_MIXEL4_S4) . Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#property-descriptions "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------- ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **edge\_clamp\_margin** = 0.02[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#float-edge_clamp_margin-002 "Permanent link") When a marching cube cell is computed, vertices may be placed anywhere on edges of the cell, including very close to corners. This can lead to very thin or small triangles, which can be a problem notably for some physics engines. this margin is the minimum distance from corners, below which vertices will be clamped to it. Increasing this value might reduce quality of the mesh introducing small ridges. This property cannot be lower than 0 (in which case no clamping occurs), and cannot be higher than 0.5 (in which case no interpolation occurs as vertices always get placed in the middle of edges). ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **mesh\_optimization\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#bool-mesh_optimization_enabled-false "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **mesh\_optimization\_error\_threshold** = 0.005[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#float-mesh_optimization_error_threshold-0005 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **mesh\_optimization\_target\_ratio** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#float-mesh_optimization_target_ratio-00 "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **textures\_ignore\_air\_voxels** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#bool-textures_ignore_air_voxels-false "Permanent link") _(This property has no documentation)_ ### [TexturingMode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#enumerations) **texturing\_mode** = TEXTURES\_NONE (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#texturingmode-texturing_mode-textures_none-0 "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **transitions\_enabled** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#bool-transitions_enabled-true "Permanent link") _(This property has no documentation)_ Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------- ### [ArrayMesh](https://docs.godotengine.org/en/stable/classes/class_arraymesh.html) **build\_transition\_mesh**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) voxel\_buffer, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) direction )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#arraymesh-build_transition_mesh-voxelbuffer-voxel_buffer-int-direction "Permanent link") Generates only the part of the mesh that Transvoxel uses to connect surfaces with different level of detail. This method is mainly for testing purposes. _Generated on Aug 20, 2026_ --- # VoxelVoxLoader - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelVoxLoader * * * VoxelVoxLoader[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelVoxLoader/#voxelvoxloader "Permanent link") ==================================================================================================================== Inherits: [RefCounted](https://docs.godotengine.org/en/stable/classes/class_refcounted.html) Utility class to load voxels from MagicaVoxel files Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelVoxLoader/#methods "Permanent link") ------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [load\_from\_file](https://voxel-tools.readthedocs.io/en/latest/api/VoxelVoxLoader/#i_load_from_file)
( [String](https://docs.godotengine.org/en/stable/classes/class_string.html)
fpath, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
voxels, [VoxelColorPalette](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/)
palette, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations)
dst\_channel=CHANNEL\_COLOR (2) ) static | Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelVoxLoader/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **load\_from\_file**( [String](https://docs.godotengine.org/en/stable/classes/class_string.html) fpath, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) voxels, [VoxelColorPalette](https://voxel-tools.readthedocs.io/en/latest/api/VoxelColorPalette/) palette, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) dst\_channel=CHANNEL\_COLOR (2) )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelVoxLoader/#int-load_from_file-string-fpath-voxelbuffer-voxels-voxelcolorpalette-palette-channelid-dst_channelchannel_color-2 "Permanent link") Loads voxels from the first model found in a vox file and stores it in a single [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) . Other models that might be in the file are not loaded. Transform of the model is not considered. Data will be stored in one channel of the provided buffer. 64-bit depth channel is not supported. If palette is provided, it will also load the color palette from the file and voxels will be indices pointing into it. 8-bit channel depth is optimal (as MagicaVoxel voxels use 8-bit indices), but 16-bit and 32-bit are also supported. If palette is not provided (null), the loader will attempt to store colors bit-packed directly into the voxels, according to the depth the provided buffer has (2-bit per component if 8-bit, 4-bit per component if 16-bit, 8-bit per component if 32-bit). Returns an [Error](https://docs.godotengine.org/en/stable/classes/class_error.html) enum code to tell if loading succeeded or not. Note: MagicaVoxel uses a different axis convention than Godot: X is right, Y is forwards and Z is up. Voxel coordinates will be the same when looked up in the buffer, but they mean different location in space. _Generated on Aug 20, 2026_ --- # Instance block format v1 - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Serialization formats * Instance block format v1 * * * Instance block format v1[¶](https://voxel-tools.readthedocs.io/en/latest/specs/instances_format_v1/#instance-block-format-v1 "Permanent link") =============================================================================================================================================== This page describes the binary format used by the module to save instances to files or databases. Changes from version 0[¶](https://voxel-tools.readthedocs.io/en/latest/specs/instances_format_v1/#changes-from-version-0 "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------- * Data is now little-endian instead of big-endian. * No other changes were made, so version 0 is easily convertible. Specification[¶](https://voxel-tools.readthedocs.io/en/latest/specs/instances_format_v1/#specification "Permanent link") ------------------------------------------------------------------------------------------------------------------------- ### Compressed container[¶](https://voxel-tools.readthedocs.io/en/latest/specs/instances_format_v1/#compressed-container "Permanent link") A block is usually serialized as compressed data. See [Compressed container format](https://voxel-tools.readthedocs.io/en/latest/specs/compressed_container/) for specification. ### Binary data[¶](https://voxel-tools.readthedocs.io/en/latest/specs/instances_format_v1/#binary-data "Permanent link") This data is little-endian. In pseudo-code: // Root structure struct InstanceBlockData { // Version tag in case more stuff is added in the future uint8_t version = 1; // There can be up to 256 different layers in one block uint8_t layer_count; // To compress positions we need to know their range. // It's local to the block so we know it starts from zero. float position_range; LayerData layers[layer_count]; // Magic number to signal the end of the data block uint32_t control_end = 0x900df00d; }; struct LayerData { uint16_t id; // Identifies the type of instances (rocks, grass, pebbles, bushes etc) uint16_t count; // To be able to compress scale we must know its range float scale_min; float scale_max; // This tells which format instances of this layer use. For now I always use the same format, // But maybe some types of instances will need more, or less data? uint8_t format = 0; InstanceData data[count]; }; struct InstanceData { // Position is lossy-compressed based on the size of the block uint16_t x; uint16_t y; uint16_t z; // Scale is uniform and is lossy-compressed to 256 values uint8_t scale; // Rotation is a compressed quaternion uint8_t x; uint8_t y; uint8_t z; uint8_t w; }; --- # ZN_FastNoiseLiteGradient - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * ZN\_FastNoiseLiteGradient * * * ZN\_FastNoiseLiteGradient[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#zn_fastnoiselitegradient "Permanent link") =================================================================================================================================================== Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Generates coherent and fractal noise gradients using the [FastNoiseLite](https://github.com/Auburn/FastNoiseLite) library. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#description "Permanent link") ------------------------------------------------------------------------------------------------------------------------- This is an alternate implementation of [FastNoiseLite](https://docs.godotengine.org/en/stable/classes/class_fastnoiselite.html) , because Godot's integration does not expose methods to access gradients directly. These algorithms are specialized to generate vectors to perturb positions, and can be faster than calculating 2 or 3 times a regular noise. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#properties "Permanent link") ----------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [amplitude](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#i_amplitude) | 30.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [fractal\_gain](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#i_fractal_gain) | 0.5 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [fractal\_lacunarity](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#i_fractal_lacunarity) | 2.0 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [fractal\_octaves](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#i_fractal_octaves) | 3 | | [FractalType](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#enumerations) | [fractal\_type](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#i_fractal_type) | FRACTAL\_NONE (0) | | [NoiseType](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#enumerations) | [noise\_type](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#i_noise_type) | TYPE\_VALUE (2) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [period](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#i_period) | 64.0 | | [RotationType3D](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#enumerations) | [rotation\_type\_3d](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#i_rotation_type_3d) | ROTATION\_3D\_NONE (0) | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [seed](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#i_seed) | 0 | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#methods "Permanent link") ----------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) | [warp\_2d](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#i_warp_2d)
( [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html)
position ) | | [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) | [warp\_3d](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#i_warp_3d)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
position ) | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#enumerations "Permanent link") --------------------------------------------------------------------------------------------------------------------------- enum **NoiseType**: * **TYPE\_OPEN\_SIMPLEX\_2** = **0** * **TYPE\_OPEN\_SIMPLEX\_2\_REDUCED** = **1** * **TYPE\_VALUE** = **2** enum **FractalType**: * **FRACTAL\_NONE** = **0** * **FRACTAL\_DOMAIN\_WARP\_PROGRESSIVE** = **1** * **FRACTAL\_DOMAIN\_WARP\_INDEPENDENT** = **2** enum **RotationType3D**: * **ROTATION\_3D\_NONE** = **0** * **ROTATION\_3D\_IMPROVE\_XY\_PLANES** = **1** * **ROTATION\_3D\_IMPROVE\_XZ\_PLANES** = **2** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#property-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------------- ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **amplitude** = 30.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#float-amplitude-300 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **fractal\_gain** = 0.5[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#float-fractal_gain-05 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **fractal\_lacunarity** = 2.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#float-fractal_lacunarity-20 "Permanent link") _(This property has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **fractal\_octaves** = 3[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#int-fractal_octaves-3 "Permanent link") _(This property has no documentation)_ ### [FractalType](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#enumerations) **fractal\_type** = FRACTAL\_NONE (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#fractaltype-fractal_type-fractal_none-0 "Permanent link") _(This property has no documentation)_ ### [NoiseType](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#enumerations) **noise\_type** = TYPE\_VALUE (2)[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#noisetype-noise_type-type_value-2 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **period** = 64.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#float-period-640 "Permanent link") _(This property has no documentation)_ ### [RotationType3D](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#enumerations) **rotation\_type\_3d** = ROTATION\_3D\_NONE (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#rotationtype3d-rotation_type_3d-rotation_3d_none-0 "Permanent link") _(This property has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **seed** = 0[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#int-seed-0 "Permanent link") _(This property has no documentation)_ Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#method-descriptions "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------- ### [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) **warp\_2d**( [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) position )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#vector2-warp_2d-vector2-position "Permanent link") _(This method has no documentation)_ ### [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) **warp\_3d**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) position )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/#vector3-warp_3d-vector3-position "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelToolTerrain - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelToolTerrain * * * VoxelToolTerrain[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#voxeltoolterrain "Permanent link") ========================================================================================================================== Inherits: [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) Implementation of [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) specialized for uses on [VoxelTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/) . Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#description "Permanent link") ----------------------------------------------------------------------------------------------------------------- Functions in this class are specific to [VoxelTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/) . For generic functions, you may also check [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) . It's not a class to instantiate alone, you may get it from [VoxelTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/) using the `get_voxel_tool()` method. Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#methods "Permanent link") --------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#) | [do\_hemisphere](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#i_do_hemisphere)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
center, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
radius, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
flat\_direction, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
smoothness=0.0 ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#) | [for\_each\_voxel\_metadata\_in\_area](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#i_for_each_voxel_metadata_in_area)
( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html)
voxel\_area, [Callable](https://docs.godotengine.org/en/stable/classes/class_callable.html)
callback ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#) | [run\_blocky\_random\_tick](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#i_run_blocky_random_tick)
( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html)
area, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
voxel\_count, [Callable](https://docs.godotengine.org/en/stable/classes/class_callable.html)
callback, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
batch\_count=16, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
tags\_mask=4294967295 ) | Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#method-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#) **do\_hemisphere**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) center, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) radius, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) flat\_direction, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) smoothness=0.0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#void-do_hemisphere-vector3-center-float-radius-vector3-flat_direction-float-smoothness00 "Permanent link") Operates on a hemisphere, where `flat_direction` is pointing away from the flat surface (like a normal). `smoothness` determines how the flat part blends with the rounded part, with higher values producing softer more rounded edge. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#) **for\_each\_voxel\_metadata\_in\_area**( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) voxel\_area, [Callable](https://docs.godotengine.org/en/stable/classes/class_callable.html) callback )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#void-for_each_voxel_metadata_in_area-aabb-voxel_area-callable-callback "Permanent link") Executes a function for each voxel holding metadata in the given area. The given callback takes two arguments: voxel position (Vector3i), voxel metadata (Variant). IMPORTANT: inserting new or removing metadata from inside this function is not allowed. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#) **run\_blocky\_random\_tick**( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) area, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) voxel\_count, [Callable](https://docs.godotengine.org/en/stable/classes/class_callable.html) callback, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) batch\_count=16, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) tags\_mask=4294967295 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/#void-run_blocky_random_tick-aabb-area-int-voxel_count-callable-callback-int-batch_count16-int-tags_mask4294967295 "Permanent link") Picks random voxels within the specified area. If voxel models have [VoxelBlockyModel.random\_tickable](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_random_tickable) set to `true` and [VoxelBlockyModel.tags\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_tags_mask) matches any bit in `tags_mask`, executes a function on them. This only works for terrains using [VoxelMesherBlocky](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/) . The given callback takes two arguments: voxel position (Vector3i), voxel value (int). The purpose of `batch_count` is to optimize the picking process through the internal data structure. The algorithm goes as follows: `voxel_count` is divided in batches of length `batch_count`. For each batch, a random block intersecting `area` is chosen, and `batch_count` voxels are picked at random inside of it. If `voxel_count` is not divisible by `batch_count`, an extra block will be picked to do the remainder. `batch` can bias randomness by concentrating picks in specific blocks, but if this function is used every frame over time, that bias should average out. If you want no bias at all, set `batch_count` to 1. _Generated on Aug 20, 2026_ --- # SQLite format v1 - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Serialization formats * SQLite format v1 * * * SQLite format v1[¶](https://voxel-tools.readthedocs.io/en/latest/specs/sqlite_format_v1/#sqlite-format-v1 "Permanent link") ============================================================================================================================ This page describes the database schema used by `VoxelStreamSQLite`. Changes from version 0[¶](https://voxel-tools.readthedocs.io/en/latest/specs/sqlite_format_v1/#changes-from-version-0 "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------- Added a `coordinate_format` column to the `meta` table, and several ways to represent coordinates in the `blocks` table. Schema[¶](https://voxel-tools.readthedocs.io/en/latest/specs/sqlite_format_v1/#schema "Permanent link") -------------------------------------------------------------------------------------------------------- ### `meta`[¶](https://voxel-tools.readthedocs.io/en/latest/specs/sqlite_format_v1/#meta "Permanent link") meta { - version: INTEGER - block_size_po2: INTEGER - coordinate_format: INTEGER } Contains general info about the volume. There is only one row inside it. * `version` is the version of the schema. Currently `1`. * `block_size_po2` is the size of blocks as a power of two. They are expected to be always the same. By default it is `4` (for blocks of 16x16x16). * `coordinate_format` specifies how block coordinates are stored. Usually, this row should never be modified once the database is setup. If for some reason changes are necessary, they must be done such that the database remains consistent (and may require to re-process all the blocks). Creating a new database and converting over may be preferable than modifying in-place. ### `blocks`[¶](https://voxel-tools.readthedocs.io/en/latest/specs/sqlite_format_v1/#blocks "Permanent link") blocks { if meta.coordinate_format is: 0 or 1 - loc: INT64 PRIMARY KEY 2: - loc: TEXT PRIMARY KEY - vb: BLOB - instances: BLOB } Contains every block of the volume. There can be thousands of them. * `loc` is a key identifying the block, usually made from its coordinates. Its encoding depends on `meta.coordinate_format`. * `vb` contains compressed voxel data using the [Block format](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v4/) . * `instances` contains compressed instance data using the [Instance format](https://voxel-tools.readthedocs.io/en/latest/specs/instances_format_v1/) . #### Coordinate format[¶](https://voxel-tools.readthedocs.io/en/latest/specs/sqlite_format_v1/#coordinate-format "Permanent link") In all cases, coordinates are equal to the origin of the block in voxels, divided by the size of the block + lod index using euclidean division (`coord >> (block_size_po2 + lod_index)`). Depending on `meta.coordinate_format`, that column is interpreted differently: * `0`: 64-bit little-endian integer packing the coordinates and LOD index of the block. XYZ are 16-bit signed integers, and LOD is a 8-bit unsigned integer: `0LXXYYZZ`. This was the default format in v0. * `1`: 64-bit little-endian integer packing the coordinates and LOD index of the block. XYZ are 19-bit signed integers, and LOD is a 7-bit unsigned integer: `lllllllx xxxxxxxx xxxxxxxx xxyyyyyy yyyyyyyy yyyyyzzz zzzzzzzz zzzzzzzz` (where the most significant bits are on the left). * `2`: Comma-separated coordinates in base 10, stored in plain text, without spaces. * `3`: 80-bit blob packing the coordinates and LOD index. XYZ are 25-bit signed integers, and LOD is a 5-bit unsigned integer. Format `3` can be represented this way: Byte | 9 8 7 6 5 4 3 2 1 0 -----|--------|--------|--------|--------|--------|--------|--------|--------|--------|-------- Bits |lllllzzz zzzzzzzz zzzzzzzz zzzzzzyy yyyyyyyy yyyyyyyy yyyyyyyx xxxxxxxx xxxxxxxx xxxxxxxx Where each cluster of bits (for each coordinate) may be read with most significant bit to the left, as when printed out. Note the reverse byte order. ### `channels`[¶](https://voxel-tools.readthedocs.io/en/latest/specs/sqlite_format_v1/#channels "Permanent link") channels { - idx: INTEGER PRIMARY KEY - depth: INTEGER } Contains general info about which channel formats should be expected in the volume. There is one row per used channel. Warning Currently this table is actually not used, because the engine still needs work to manage formats in general. For now the database accepts blocks of any formats since they are standalone since version 3, but ideally they must be consistent. --- # SQLite format v0 - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Serialization formats * SQLite format v0 * * * SQLite format v0[¶](https://voxel-tools.readthedocs.io/en/latest/specs/sqlite_format_v0/#sqlite-format-v0 "Permanent link") ============================================================================================================================ Warning This document is about an old version of the format. You may check the most recent version. This page describes the database schema used by `VoxelStreamSQLite`. Schema[¶](https://voxel-tools.readthedocs.io/en/latest/specs/sqlite_format_v0/#schema "Permanent link") -------------------------------------------------------------------------------------------------------- ### `meta`[¶](https://voxel-tools.readthedocs.io/en/latest/specs/sqlite_format_v0/#meta "Permanent link") meta { - version: INTEGER - block_size_po2: INTEGER } Contains general info about the volume. There is only one row inside it. * `version` is the version of the schema. Currently `0`. * `block_size_po2` is the size of blocks as a power of two. They are expected to be always the same. By default it is `4` (for blocks of 16x16x16). ### `blocks`[¶](https://voxel-tools.readthedocs.io/en/latest/specs/sqlite_format_v0/#blocks "Permanent link") blocks { - loc: INT64 PRIMARY KEY - vb: BLOB - instances: BLOB } Contains every block of the volume. There can be thousands of them. * `loc` is a 64-bit integer packing the coordinates and LOD index of the block using little-endian. Coordinates are equal to the origin of the block in voxels, divided by the size of the block + lod index using euclidean division (`coord >> (block_size_po2 + lod_index)`). XYZ are 16-bit signed integers, and LOD is a 8-bit unsigned integer: `0LXXYYZZ` * `vb` contains compressed voxel data using the [Block format](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v4/) . * `instances` contains compressed instance data using the [Instance format](https://voxel-tools.readthedocs.io/en/latest/specs/instances_format_v0/) . ### `channels`[¶](https://voxel-tools.readthedocs.io/en/latest/specs/sqlite_format_v0/#channels "Permanent link") channels { - idx: INTEGER PRIMARY KEY - depth: INTEGER } Contains general info about which channel formats should be expected in the volume. There is one row per used channel. Warning Currently this table is actually not used, because the engine still needs work to manage formats in general. For now the database accepts blocks of any formats since they are standalone since version 3, but ideally they must be consistent. --- # VoxelStreamRegionFiles - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelStreamRegionFiles * * * VoxelStreamRegionFiles[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#voxelstreamregionfiles "Permanent link") ============================================================================================================================================ Inherits: [VoxelStream](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/) Loads and saves blocks to region files indexed by world position, under a directory. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#description "Permanent link") ----------------------------------------------------------------------------------------------------------------------- Loads and saves blocks to the filesystem, in multiple region files indexed by world position, under a directory. Regions pack many blocks together, so it reduces file switching and improves performance. Inspired by [Seed of Andromeda](https://www.seedofandromeda.com/blogs/1-creating-a-region-file-system-for-a-voxel-game) and Minecraft. Region files are not thread-safe. Because of this, internal mutexing may often constrain the use by one thread only. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#properties "Permanent link") --------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [block\_size\_po2](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#i_block_size_po2) | 4 | | [String](https://docs.godotengine.org/en/stable/classes/class_string.html) | [directory](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#i_directory) | "" | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [region\_size\_po2](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#i_region_size_po2) | 4 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [sector\_size](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#i_sector_size) | 512 | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#methods "Permanent link") --------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#) | [convert\_files](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#i_convert_files)
( [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html)
new\_settings ) | | [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) | [get\_region\_size](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#i_get_region_size)
( ) const | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **block\_size\_po2** = 4[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#int-block_size_po2-4 "Permanent link") _(This property has no documentation)_ ### [String](https://docs.godotengine.org/en/stable/classes/class_string.html) **directory** = ""[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#string-directory "Permanent link") Directory under which the data is saved. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **region\_size\_po2** = 4[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#int-region_size_po2-4 "Permanent link") _(This property has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **sector\_size** = 512[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#int-sector_size-512 "Permanent link") _(This property has no documentation)_ Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#method-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------- ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#) **convert\_files**( [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) new\_settings )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#void-convert_files-dictionary-new_settings "Permanent link") _(This method has no documentation)_ ### [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) **get\_region\_size**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/#vector3-get_region_size "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelRaycastResult - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelRaycastResult * * * VoxelRaycastResult[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelRaycastResult/#voxelraycastresult "Permanent link") ================================================================================================================================ Inherits: [RefCounted](https://docs.godotengine.org/en/stable/classes/class_refcounted.html) Result of a raycast performed with [VoxelTool.raycast](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_raycast) Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelRaycastResult/#properties "Permanent link") ----------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelRaycastResult/#i_distance) | 0.0 | | [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) | [normal](https://voxel-tools.readthedocs.io/en/latest/api/VoxelRaycastResult/#i_normal) | Vector3(0, 0, 0) | | [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) | [position](https://voxel-tools.readthedocs.io/en/latest/api/VoxelRaycastResult/#i_position) | Vector3i(0, 0, 0) | | [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) | [previous\_position](https://voxel-tools.readthedocs.io/en/latest/api/VoxelRaycastResult/#i_previous_position) | Vector3i(0, 0, 0) | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelRaycastResult/#property-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------- ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **distance** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelRaycastResult/#float-distance-00 "Permanent link") Distance between the origin of the ray and the surface of the cube representing the hit voxel. ### [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) **normal** = Vector3(0, 0, 0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelRaycastResult/#vector3-normal-vector30-0-0 "Permanent link") Unit vector pointing away from the surface that was hit. This is only available if [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) was configured to compute normals. See [VoxelTool.set\_raycast\_normal\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_set_raycast_normal_enabled) . With blocky voxels, this normal will be based on collision boxes rather than the mesh. ### [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) **position** = Vector3i(0, 0, 0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelRaycastResult/#vector3i-position-vector3i0-0-0 "Permanent link") Integer position of the voxel that was hit. In a blocky game, this would be the position of the voxel to interact with. ### [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) **previous\_position** = Vector3i(0, 0, 0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelRaycastResult/#vector3i-previous_position-vector3i0-0-0 "Permanent link") Integer position of the previous voxel along the ray before the final hit. In a blocky game, this would be the position of the voxel to place on top of the pointed one. _Generated on Aug 20, 2026_ --- # VoxelStreamSQLite - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelStreamSQLite * * * VoxelStreamSQLite[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#voxelstreamsqlite "Permanent link") ============================================================================================================================= Inherits: [VoxelStream](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/) Saves voxel data into a single SQLite database file. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#properties "Permanent link") ---------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [String](https://docs.godotengine.org/en/stable/classes/class_string.html) | [database\_path](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#i_database_path) | "" | | [CoordinateFormat](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#enumerations) | [preferred\_coordinate\_format](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#i_preferred_coordinate_format) | COORDINATE\_FORMAT\_STRING\_CSD (2) | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#methods "Permanent link") ---------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [is\_key\_cache\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#i_is_key_cache_enabled)
( ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#) | [set\_key\_cache\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#i_set_key_cache_enabled)
( [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
enabled ) | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#enumerations "Permanent link") -------------------------------------------------------------------------------------------------------------------- enum **CoordinateFormat**: * **COORDINATE\_FORMAT\_INT64\_X16\_Y16\_Z16\_L16** = **0** --- Coordinates are stored in a 64-bit integer key, where X, Y, Z and LOD are 16-bit signed integers. * **COORDINATE\_FORMAT\_INT64\_X19\_Y19\_Z19\_L7** = **1** --- Coordinates are stored in a 64-bit integer key, where X, Y and Z are 19-bit signed integers, and LOD is a 7-bit unsigned integer. * **COORDINATE\_FORMAT\_STRING\_CSD** = **2** --- Coordinates are stored in strings of comma-separated base 10 numbers "X,Y,Z,LOD". * **COORDINATE\_FORMAT\_BLOB80\_X25\_Y25\_Z25\_L5** = **3** --- Coordinates are stored in 80-bit blobs, where X, Y and Z are 25-bit signed integers and LOD is a 5-bit unsigned integer. * **COORDINATE\_FORMAT\_COUNT** = **4** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------- ### [String](https://docs.godotengine.org/en/stable/classes/class_string.html) **database\_path** = ""[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#string-database_path "Permanent link") Path to the database file. `res://` and `user://` should work, however `res://` will not work after export (see [why here](https://docs.godotengine.org/en/stable/tutorials/io/data_paths.html#accessing-persistent-user-data-user) ). The path can be relative to the game's executable. Directories in the path must exist. If the file does not exist, it will be created. ### [CoordinateFormat](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#enumerations) **preferred\_coordinate\_format** = COORDINATE\_FORMAT\_STRING\_CSD (2)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#coordinateformat-preferred_coordinate_format-coordinate_format_string_csd-2 "Permanent link") Sets which block coordinate format will be used when creating new databases. This affects the range of supported coordinates and how quickly SQLite can execute queries (to a minor extent). When opening existing databases, this setting will be ignored, and the format of the database will be used instead. Changing the format of an existing database is currently not possible, and may require using a script to load individual blocks from one stream and save them to a new one. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#method-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------------- ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **is\_key\_cache\_enabled**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#bool-is_key_cache_enabled "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#) **set\_key\_cache\_enabled**( [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) enabled )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/#void-set_key_cache_enabled-bool-enabled "Permanent link") Enables caching keys of the database to speed up loading queries in terrains that only save sparse edited blocks. This won't provide any benefit if your terrain saves all its blocks (for example if the output of the generator is saved). This must be called before any call to `load_voxel_block` (before the terrain starts using it), otherwise it won't work properly. You may use a script to do this. _Generated on Aug 20, 2026_ --- # ZN_SpotNoise - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * ZN\_SpotNoise * * * ZN\_SpotNoise[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#zn_spotnoise "Permanent link") =============================================================================================================== Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Specialization of cellular noise intented for cheap "ore patch" generation or deterministic point scattering. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#description "Permanent link") ------------------------------------------------------------------------------------------------------------- Divides space into a grid where each cell contains a circular "spot". Noise evaluation returns 1 when the position is inside a spot, 0 otherwise. Limitation: high jitter can make spots clip with cell borders. This is expected. If you need higher quality (but slower) results, you may use another noise library such as [FastNoiseLite](https://docs.godotengine.org/en/stable/classes/class_fastnoiselite.html) . Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#properties "Permanent link") ----------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [cell\_size](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#i_cell_size) | 32.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [jitter](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#i_jitter) | 0.9 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [seed](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#i_seed) | 1337 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [spot\_radius](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#i_spot_radius) | 3.0 | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#methods "Permanent link") ----------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [get\_noise\_2d](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#i_get_noise_2d)
( [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
x, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
y ) const | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [get\_noise\_2dv](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#i_get_noise_2dv)
( [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html)
pos ) const | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [get\_noise\_3d](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#i_get_noise_3d)
( [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
x, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
y, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
z ) const | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [get\_noise\_3dv](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#i_get_noise_3dv)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
pos ) const | | [PackedVector2Array](https://docs.godotengine.org/en/stable/classes/class_packedvector2array.html) | [get\_spot\_positions\_in\_area\_2d](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#i_get_spot_positions_in_area_2d)
( [Rect2](https://docs.godotengine.org/en/stable/classes/class_rect2.html)
rect ) const | | [PackedVector3Array](https://docs.godotengine.org/en/stable/classes/class_packedvector3array.html) | [get\_spot\_positions\_in\_area\_3d](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#i_get_spot_positions_in_area_3d)
( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html)
aabb ) const | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#property-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **cell\_size** = 32.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#float-cell_size-320 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **jitter** = 0.9[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#float-jitter-09 "Permanent link") _(This property has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **seed** = 1337[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#int-seed-1337 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **spot\_radius** = 3.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#float-spot_radius-30 "Permanent link") _(This property has no documentation)_ Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#method-descriptions "Permanent link") ---------------------------------------------------------------------------------------------------------------------------- ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **get\_noise\_2d**( [float](https://docs.godotengine.org/en/stable/classes/class_float.html) x, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) y )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#float-get_noise_2d-float-x-float-y "Permanent link") _(This method has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **get\_noise\_2dv**( [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) pos )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#float-get_noise_2dv-vector2-pos "Permanent link") _(This method has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **get\_noise\_3d**( [float](https://docs.godotengine.org/en/stable/classes/class_float.html) x, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) y, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) z )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#float-get_noise_3d-float-x-float-y-float-z "Permanent link") _(This method has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **get\_noise\_3dv**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) pos )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#float-get_noise_3dv-vector3-pos "Permanent link") _(This method has no documentation)_ ### [PackedVector2Array](https://docs.godotengine.org/en/stable/classes/class_packedvector2array.html) **get\_spot\_positions\_in\_area\_2d**( [Rect2](https://docs.godotengine.org/en/stable/classes/class_rect2.html) rect )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#packedvector2array-get_spot_positions_in_area_2d-rect2-rect "Permanent link") _(This method has no documentation)_ ### [PackedVector3Array](https://docs.godotengine.org/en/stable/classes/class_packedvector3array.html) **get\_spot\_positions\_in\_area\_3d**( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) aabb )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_SpotNoise/#packedvector3array-get_spot_positions_in_area_3d-aabb-aabb "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelGeneratorNoise2D - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelGeneratorNoise2D * * * VoxelGeneratorNoise2D[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise2D/#voxelgeneratornoise2d "Permanent link") ========================================================================================================================================= Inherits: [VoxelGeneratorHeightmap](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorHeightmap/) Voxel generator producing noise-based heightmap terrain. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise2D/#properties "Permanent link") -------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [Curve](https://docs.godotengine.org/en/stable/classes/class_curve.html) | [curve](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise2D/#i_curve) | | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [height\_range](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise2D/#i_height_range) | 200.0 | | [Noise](https://docs.godotengine.org/en/stable/classes/class_noise.html) | [noise](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise2D/#i_noise) | | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise2D/#property-descriptions "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------- ### [Curve](https://docs.godotengine.org/en/stable/classes/class_curve.html) **curve**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise2D/#curve-curve "Permanent link") When assigned, this curve will alter the distribution of height variations, allowing to give some kind of "profile" to the generated shapes. By default, a linear curve from 0 to 1 is used. It is assumed that the curve's domain goes from 0 to 1. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **height\_range** = 200.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise2D/#float-height_range-2000 "Permanent link") ### [Noise](https://docs.godotengine.org/en/stable/classes/class_noise.html) **noise**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorNoise2D/#noise-noise "Permanent link") Noise used to produce the heightmap. It is required for the generator to work. _Generated on Aug 20, 2026_ --- # VoxelGeneratorMultipassCB - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelGeneratorMultipassCB * * * VoxelGeneratorMultipassCB[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#voxelgeneratormultipasscb "Permanent link") ===================================================================================================================================================== Inherits: [VoxelGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/) Warning This class is marked as experimental. It is subject to likely change or possible removal in future versions. Use at your own discretion. Scriptable generator working on columns of blocks and multiple passes. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#description "Permanent link") -------------------------------------------------------------------------------------------------------------------------- This generator can be implemented with a script to generate terrain in columns of blocks instead of only block by block. It allows to use multiple passes, where every pass can access results of the previous ones, and allowing access to neighbor columns. The height of columns is not infinite, but it is possible to define what generates above and below, using a single-pass per-block fallback. It may only be used with [VoxelTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/) . Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#properties "Permanent link") ------------------------------------------------------------------------------------------------------------------------ | Type | Name | Default | | --- | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [column\_base\_y\_blocks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#i_column_base_y_blocks) | \-4 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [column\_height\_blocks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#i_column_height_blocks) | 8 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [pass\_count](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#i_pass_count) | 1 | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#methods "Permanent link") ------------------------------------------------------------------------------------------------------------------ | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#) | [\_generate\_block\_fallback](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#i__generate_block_fallback)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
out\_buffer, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
origin\_in\_voxels ) virtual | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#) | [\_generate\_pass](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#i__generate_pass)
( [VoxelToolMultipassGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/)
voxel\_tool, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
pass\_index ) virtual | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [\_get\_used\_channels\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#i__get_used_channels_mask)
( ) virtual const | | [VoxelBuffer\[\]](https://docs.godotengine.org/en/stable/classes/class_voxelbuffer[].html) | [debug\_generate\_test\_column](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#i_debug_generate_test_column)
( [Vector2i](https://docs.godotengine.org/en/stable/classes/class_vector2i.html)
column\_position\_blocks ) | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_pass\_extent\_blocks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#i_get_pass_extent_blocks)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
pass\_index ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#) | [set\_pass\_extent\_blocks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#i_set_pass_extent_blocks)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
pass\_index, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
extent ) | Constants:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#constants "Permanent link") ---------------------------------------------------------------------------------------------------------------------- * **MAX\_PASSES** = **4** * **MAX\_PASS\_EXTENT** = **2** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#property-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------- ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **column\_base\_y\_blocks** = -4[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#int-column_base_y_blocks-4 "Permanent link") Lowest altitude of columns, in blocks. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **column\_height\_blocks** = 8[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#int-column_height_blocks-8 "Permanent link") Height of columns, in blocks. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **pass\_count** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#int-pass_count-1 "Permanent link") Number of passes columns will go through before being considered fully generated. More passes increases memory and processing cost. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#method-descriptions "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------- ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#) **\_generate\_block\_fallback**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) out\_buffer, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) origin\_in\_voxels )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#void-_generate_block_fallback-voxelbuffer-out_buffer-vector3i-origin_in_voxels "Permanent link") Called for every block to generate above or below the column-based region. For example you can decide to generate air above, and bedrock below. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#) **\_generate\_pass**( [VoxelToolMultipassGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/) voxel\_tool, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) pass\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#void-_generate_pass-voxeltoolmultipassgenerator-voxel_tool-int-pass_index "Permanent link") Called once per pass for every column of blocks. The passed `voxel_tool` must be used to get information about the area to generate, and fill/edit this area with voxels. Important: do not keep this object in a member variable for later re-use. You can only use it in the current call to this method. You may use `pass_index` to do something different in each pass. For example, 0 could be base ground with Perlin noise, 1 could plant trees and other structures. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **\_get\_used\_channels\_mask**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#int-_get_used_channels_mask "Permanent link") Use this to indicate which channels your generator will use. It returns a bitmask, so for example you may provide information like this: `(1 << channel1) | (1 << channel2)` ### [VoxelBuffer\[\]](https://docs.godotengine.org/en/stable/classes/class_voxelbuffer[].html) **debug\_generate\_test\_column**( [Vector2i](https://docs.godotengine.org/en/stable/classes/class_vector2i.html) column\_position\_blocks )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#voxelbuffer-debug_generate_test_column-vector2i-column_position_blocks "Permanent link") Testing method that will fully generate all blocks of a specific column, and returns them. This function doesn't use any threads and doesn't use the internal cache, so it will be very slow. However, it allows to test or debug your script more easily, using an isolated scene for example. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_pass\_extent\_blocks**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) pass\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#int-get_pass_extent_blocks-int-pass_index "Permanent link") Gets how many blocks a pass can access around it (note: a block is 16x16x16 voxels by default). ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#) **set\_pass\_extent\_blocks**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) pass\_index, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) extent )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorMultipassCB/#void-set_pass_extent_blocks-int-pass_index-int-extent "Permanent link") Sets how many blocks a pass can access around columns when they generate (note: a block is 16x16x16 voxels by default). By design, the first pass is not allowed to access neighbors, so it will remain 0. Following passes are designed to access at least 1 block away. Such passes don't support 0 because it would be the same as simply putting your logic in a previous pass. Increasing extent will also increase the cost of the generator, both in memory and processing time, so it should be balanced with caution. _Generated on Aug 20, 2026_ --- # VoxelInstancer - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelInstancer * * * VoxelInstancer[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#voxelinstancer "Permanent link") ==================================================================================================================== Inherits: [Node3D](https://docs.godotengine.org/en/stable/classes/class_node3d.html) Spawns items on top of voxel surfaces. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#description "Permanent link") --------------------------------------------------------------------------------------------------------------- Add-on to voxel nodes, allowing to spawn static elements on the surface. These elements are rendered with hardware instancing, can have collisions, and also be persistent. It must be child of a voxel node. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#properties "Permanent link") ------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [collision\_update\_budget\_microseconds](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_collision_update_budget_microseconds) | 500 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [fading\_duration](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_fading_duration) | 0.3 | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [fading\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_fading_enabled) | false | | [VoxelInstanceLibrary](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/) | [library](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_library) | | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [mesh\_lod\_update\_budget\_microseconds](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_mesh_lod_update_budget_microseconds) | 500 | | [UpMode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#enumerations) | [up\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_up_mode) | UP\_MODE\_POSITIVE\_Y (0) | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#methods "Permanent link") ------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#) | [debug\_dump\_as\_scene](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_debug_dump_as_scene)
( [String](https://docs.godotengine.org/en/stable/classes/class_string.html)
fpath ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [debug\_get\_block\_count](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_debug_get_block_count)
( ) const | | [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) | [debug\_get\_block\_infos](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_debug_get_block_infos)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
world\_position, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
item\_id ) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_get\_draw\_flag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_debug_get_draw_flag)
( [DebugDrawFlag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#enumerations)
flag ) const | | [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) | [debug\_get\_instance\_counts](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_debug_get_instance_counts)
( ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_is\_draw\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_debug_is_draw_enabled)
( ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#) | [debug\_set\_draw\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_debug_set_draw_enabled)
( [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
enabled ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#) | [debug\_set\_draw\_flag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_debug_set_draw_flag)
( [DebugDrawFlag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#enumerations)
flag, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
enabled ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#) | [remove\_instances\_in\_sphere](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_remove_instances_in_sphere)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
center, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
radius ) | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#enumerations "Permanent link") ----------------------------------------------------------------------------------------------------------------- enum **UpMode**: * **UP\_MODE\_POSITIVE\_Y** = **0** --- Up is towards the positive Y axis. This is the default assumption in Godot. * **UP\_MODE\_SPHERE** = **1** --- Up is opposite from the direction where the terrain's origin is. May be used if your terrain is a planet for example. enum **DebugDrawFlag**: * **DEBUG\_DRAW\_ALL\_BLOCKS** = **0** * **DEBUG\_DRAW\_EDITED\_BLOCKS** = **1** * **DEBUG\_DRAW\_FLAGS\_COUNT** = **2** Constants:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#constants "Permanent link") ----------------------------------------------------------------------------------------------------------- * **MAX\_LOD** = **8** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#property-descriptions "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------- ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **collision\_update\_budget\_microseconds** = 500[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#int-collision_update_budget_microseconds-500 "Permanent link") Hints the maximum time that should be spent updating collisions that are based on distance (see [VoxelInstanceLibraryMultiMeshItem.collision\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_collision_distance) ). This time can still be exceeded if an operation takes longer, but then no further processing will occur until next frame. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **fading\_duration** = 0.3[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#float-fading_duration-03 "Permanent link") How long it takes for fading to complete, in seconds (same for fading in and out). Used when [fading\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_fading_enabled) is active. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **fading\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#bool-fading_enabled-false "Permanent link") When enabled, a per-instance shader parameter will be updated when instances load in and out, so it can be used to apply a fading effect. The material used by instances must have a shader that has a `instance uniform vec2 u_lod_fade;` property. X will animate from 0 to 1 during fade in and fade out. Y will be 1 when fading in, and 0 when fading out. ### [VoxelInstanceLibrary](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibrary/) **library**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#voxelinstancelibrary-library "Permanent link") Library from which instances to spawn will be taken from. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **mesh\_lod\_update\_budget\_microseconds** = 500[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#int-mesh_lod_update_budget_microseconds-500 "Permanent link") Hints the maximum time that should be spent updating mesh LODs (see "mesh LOD" properties on [VoxelInstanceLibraryMultiMeshItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/) ). This time can still be exceeded if an operation takes longer, but then no further processing will occur until next frame. ### [UpMode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#enumerations) **up\_mode** = UP\_MODE\_POSITIVE\_Y (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#upmode-up_mode-up_mode_positive_y-0 "Permanent link") Where to consider the "up" direction is on the terrain when generating instances. See also [VoxelInstanceGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/) . Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#) **debug\_dump\_as\_scene**( [String](https://docs.godotengine.org/en/stable/classes/class_string.html) fpath )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#void-debug_dump_as_scene-string-fpath "Permanent link") _(This method has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **debug\_get\_block\_count**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#int-debug_get_block_count "Permanent link") _(This method has no documentation)_ ### [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) **debug\_get\_block\_infos**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) world\_position, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) item\_id )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#dictionary-debug_get_block_infos-vector3-world_position-int-item_id "Permanent link") _(This method has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_get\_draw\_flag**( [DebugDrawFlag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#enumerations) flag )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#bool-debug_get_draw_flag-debugdrawflag-flag "Permanent link") _(This method has no documentation)_ ### [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) **debug\_get\_instance\_counts**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#dictionary-debug_get_instance_counts "Permanent link") _(This method has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_is\_draw\_enabled**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#bool-debug_is_draw_enabled "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#) **debug\_set\_draw\_enabled**( [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) enabled )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#void-debug_set_draw_enabled-bool-enabled "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#) **debug\_set\_draw\_flag**( [DebugDrawFlag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#enumerations) flag, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) enabled )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#void-debug_set_draw_flag-debugdrawflag-flag-bool-enabled "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#) **remove\_instances\_in\_sphere**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) center, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) radius )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#void-remove_instances_in_sphere-vector3-center-float-radius "Permanent link") Removes all instances having their origin inside the given sphere. Coordinates are local to the instancer. _Generated on Aug 20, 2026_ --- # VoxelNode - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelNode * * * VoxelNode[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#voxelnode "Permanent link") ===================================================================================================== Inherits: [Node3D](https://docs.godotengine.org/en/stable/classes/class_node3d.html) Inherited by: [VoxelLodTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/) , [VoxelTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/) Base class for voxel volumes. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#properties "Permanent link") -------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [ShadowCastingSetting](https://docs.godotengine.org/en/stable/classes/class_geometryinstance3d.html#enum-geometryinstance3d-shadowcastingsetting) | [cast\_shadow](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#i_cast_shadow) | 1 | | [VoxelFormat](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/) | [format](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#i_format) | | | [VoxelGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/) | [generator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#i_generator) | | | [GIMode](https://docs.godotengine.org/en/stable/classes/class_geometryinstance3d.html#enum-geometryinstance3d-gimode) | [gi\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#i_gi_mode) | 0 | | [VoxelMesher](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/) | [mesher](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#i_mesher) | | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [render\_layers\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#i_render_layers_mask) | 1 | | [VoxelStream](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/) | [stream](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#i_stream) | | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#methods "Permanent link") -------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [Node3D](https://docs.godotengine.org/en/stable/classes/class_node3d.html) | [convert\_to\_nodes](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#i_convert_to_nodes)
( [NodeConversionFlags](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#enumerations)
flags ) const | | [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) | [get\_voxel\_tool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#i_get_voxel_tool)
( ) | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#enumerations "Permanent link") ------------------------------------------------------------------------------------------------------------ enum **NodeConversionFlags**: * **NODE\_CONVERSION\_INCLUDE\_INSTANCER** = **1** --- If the terrain has a [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) , instances spawned by it will be included in the result as a [MultiMeshInstance](https://docs.godotengine.org/en/stable/classes/class_multimeshinstance.html) per chunk. * **NODE\_CONVERSION\_INCLUDE\_INVISIBLE\_BLOCKS** = **2** --- Some chunks are internally hidden by the terrain system, notably as part of the LOD system. If this flag is provided, these chunks will be included in the output. * **NODE\_CONVERSION\_INCLUDE\_MATERIAL\_OVERRIDES** = **4** --- Specifies that material overrides present on the terrain should be applied to chunks of the result. Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#property-descriptions "Permanent link") ----------------------------------------------------------------------------------------------------------------------------- ### [ShadowCastingSetting](https://docs.godotengine.org/en/stable/classes/class_geometryinstance3d.html#enum-geometryinstance3d-shadowcastingsetting) **cast\_shadow** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#shadowcastingsetting-cast_shadow-1 "Permanent link") Sets the shadow casting mode that meshes of the terrain will use. ### [VoxelFormat](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/) **format**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#voxelformat-format "Permanent link") Overrides the default format of voxels. WARNING: changing this will reload the terrain. If it has a stream attached with data saved with a different format, it might load improperly. ### [VoxelGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/) **generator**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#voxelgenerator-generator "Permanent link") Procedural generator used to load voxel blocks when not present in the stream. ### [GIMode](https://docs.godotengine.org/en/stable/classes/class_geometryinstance3d.html#enum-geometryinstance3d-gimode) **gi\_mode** = 0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#gimode-gi_mode-0 "Permanent link") Sets the Global Illumination mode meshes of the terrain will use. ### [VoxelMesher](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesher/) **mesher**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#voxelmesher-mesher "Permanent link") Defines how voxels are transformed into visible meshes. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **render\_layers\_mask** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#int-render_layers_mask-1 "Permanent link") Sets the render layers meshes of the terrain will use. ### [VoxelStream](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/) **stream**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#voxelstream-stream "Permanent link") Primary source of persistent voxel data. If left unassigned, the whole volume will use the generator. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------- ### [Node3D](https://docs.godotengine.org/en/stable/classes/class_node3d.html) **convert\_to\_nodes**( [NodeConversionFlags](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#enumerations) flags )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#node3d-convert_to_nodes-nodeconversionflags-flags "Permanent link") Generates a tree representing the terrain at the time of calling, only using Godot vanilla nodes. This method can be used as a way to produce a snapshot of the terrain as a vanilla scene that can be opened with standard Godot versions without plugins. It could also be used for debug purposes, or as a way to workaround Godot features that expect mesh instance nodes (such as some GI baking options, navigation generation or GLTF export). The returned root is not added to the scene tree. It is up to you to decide what to do with it. If you want it to be present in the scene, you should add it as child of an existing node. Otherwise, don't forget to free it. Output structure: every chunk of the terrain will create its own [MeshInstance3D](https://docs.godotengine.org/en/stable/classes/class_meshinstance3d.html) , with a unique [ArrayMesh](https://docs.godotengine.org/en/stable/classes/class_arraymesh.html) resource attached to it. Meshes and/or mesh instances may also have materials attached to them. Depending on how the terrain is configured, these materials can be unique per chunk. If the terrain has LODs, chunks will be stored under a corresponding LOD node. If the terrain has an instancer, multimesh chunks can be included. See [NodeConversionFlags](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#enumerations) for options. Resources: unless specified, resources attached to nodes of the tree will be direct references to those actually used by the terrain system. Careful, depending on configuration, it is possible that they get altered when the terrain runs its next process cycle (for example, materials with per-chunk parameters are pooled, so when chunks get unloaded, those referenced in the nodes might drastically change as new chunks re-use them). Performance: this can be an expensive operation. It might slow down your game. Packing to scene file: it is possible to save the output as a [PackedScene](https://docs.godotengine.org/en/stable/classes/class_packedscene.html) , by assigning [Node.owner](https://docs.godotengine.org/en/stable/classes/class_node.html#class-node-property-owner) (see Godot's documentation). It contains a lot of unique meshes so the saved scenes can be very large. Prefer saving as binary `.scn` if it's a problem. If the terrain uses a [ShaderMaterial](https://docs.godotengine.org/en/stable/classes/class_shadermaterial.html) with detail rendering, chunks will also have unique textures, further increasing size. GLTF: if your terrain uses [ShaderMaterial](https://docs.godotengine.org/en/stable/classes/class_shadermaterial.html) and you want to convert the terrain to a [GLTFDocument](https://docs.godotengine.org/en/stable/classes/class_gltfdocument.html) , these materials won't carry over because GLTF does not support it. That also means if you use [VoxelMesherTransvoxel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/) with LOD, meshes in your GLTF document will have unwanted extra geometry and cracks at the seams (which would normally be handled by shader). LOD: if your terrain has LOD, you will only get a snapshot of which LODs are currently active. Detailed meshes will be centered around viewers, and have less and less details further away. ### [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) **get\_voxel\_tool**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/#voxeltool-get_voxel_tool "Permanent link") Creates an instance of [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) bound to this node, to access voxels and edition methods. You can keep it in a member variable to avoid creating one again, as long as the node still exists. _Generated on Aug 20, 2026_ --- # Voxel block format v2 - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Serialization formats * Voxel block format v2 * * * Voxel block format v2[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v2/#voxel-block-format-v2 "Permanent link") ===================================================================================================================================== Warning This document is about an old version of the format. You may check the most recent version. Version: 2 This page describes the binary format used by default in this module to serialize voxel blocks to files, network or databases. ### Changes from version 1[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v2/#changes-from-version-1 "Permanent link") Overall the format can be more standalone than before, where information had to be known up-front. * Made compressed container a bit more independent with a header * Added version header * Added 3D size * Added depth information on each channel There is no migration available from version 1. Specification[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v2/#specification "Permanent link") --------------------------------------------------------------------------------------------------------------------- ### Compressed container[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v2/#compressed-container "Permanent link") A block is usually serialized as compressed data. This is the format provided by the `VoxelBlockSerializer` utility class. If you don't use compression, the layout will correspond to `BlockData` described in the next listing, and won't have this wrapper. Compressed data starts with one byte. Depending on its value, what follows is different. * 0: no compression. Following bytes can be read as as block format directly. This is rarely used and could be for debugging. * 1: LZ4 compression. The next big-endian 32-bit unsigned integer is the size of the decompressed data, and following bytes are compressed data using LZ4 default parameters. This mode is used by default. Knowing the size of the decompressed data may be important when parsing the block later. ### Block format[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v2/#block-format "Permanent link") The obtained data then contains the actual block. It starts with version number `2` in one byte, then some metadata and the actual voxels. Note The size and formats are present to make the format standalone. When used within a chunked container like region files, it is recommended to check if they match the format expected for the volume as a whole. BlockData - version: uint8_t - size_x: uint16_t - size_y: uint16_t - size_z: uint16_t - channels[8] - metadata* - epilogue ### Channels[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v2/#channels "Permanent link") Block data starts with exactly 8 channels one after the other, each with the following structure: Channel - format: uint8_t (low nibble = compression, high nibble = depth) - data `format` contains both compression and bit depth, respectively known as `VoxelBuffer::Compression` and `VoxelBuffer::Depth` enums. The low nibble contains compression, and the high nibble contains depth. Depending on those values, `data` will be different. Depth can be 0 (8-bit), 1 (16-bit), 2 (32-bit) or 3 (64-bit). If compression is `COMPRESSION_NONE` (0), `data` will be an array of N\*S bytes, where N is the number of voxels inside a block, multiplied by the number of bytes corresponding to the bit depth. For example, a block of size 16x16x16 and a channel of 32-bit depth will have `16*16*16*4` bytes to load from the file into this channel. The 3D indexing of that data is in order `ZXY`. If compression is `COMPRESSION_UNIFORM` (1), the data will be a single voxel value, which means all voxels in the block have that same value. Unused channels will always use this mode. The value spans the same number of bytes defined by the depth. Other compression values are invalid. ### Metadata[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v2/#metadata "Permanent link") After all channels information, block data can contain metadata information. Blocks that don't contain any will only have a fixed amount of bytes left (from the epilogue) before reaching the size of the total data to read. If there is more, the block contains metadata. Metadata - metadata_size: uint32_t - block_metadata - voxel_metadata[*] It starts with one 32-bit unsigned integer representing the total size of all metadata there is to read. That data comes in two groups: one for the whole block, and one per voxel. Block metadata is one Godot `Variant`, encoded using the `encode_variant` method of the engine. Voxel metadata immediately follows. It is a sequence of the following data structures, which must be read until a total of `metadata_size` bytes have been read from the beginning: VoxelMetadata - x: uint16_t - y: uint16_t - z: uint16_t - data `x`, `y` and `z` indicate which voxel the data corresponds. `data` is also a `Variant` encoded the same way as described earlier. This results in an associative collection between voxel positions relative to the block and their corresponding metadata. ### Epilogue[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v2/#epilogue "Permanent link") At the very end, block data finishes with a sequence of 4 bytes, which once read into a `uint32_t` integer must match the value `0x900df00d`. If that condition isn't fulfilled, the block must be assumed corrupted. Note On little-endian architectures (mostly desktop), binary editors will not show the epilogue as `0x900df00d`, but as `0x0df00d90` instead. Current Issues[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v2/#current-issues "Permanent link") ----------------------------------------------------------------------------------------------------------------------- Although this format is currently implemented and usable, it has known issues. ### Endianness[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v2/#endianness "Permanent link") Godot's `encode_variant` doesn't seem to care about endianness across architectures, so it's possible it becomes a problem in the future and gets changed to a custom format. The rest of this spec is not affected by this and assumes we use little-endian, however the implementation of block channels with depth greater than 8-bit currently doesn't consider this either. This might be refined in a later iteration. This will become important to address if voxel games require communication between mobile and desktop. --- # Region format v2 - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Serialization formats * Region format v2 * * * Region format v2[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v2/#region-format-v2 "Permanent link") ============================================================================================================================ Warning This document is about an old version of the format. You may check the most recent version. Version: 2 Regions allows to save large 3D voxel volumes in a format suitable for frequent streaming in all directions. This format is inspired by https://www.seedofandromeda.com/blogs/1-creating-a-region-file-system-for-a-voxel-game It is implemented by `VoxelStreamRegionFiles`, which can be found in https://github.com/Zylann/godot\_voxel/blob/master/streams/voxel\_stream\_region\_files.cpp Coordinate spaces[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v2/#coordinate-spaces "Permanent link") ------------------------------------------------------------------------------------------------------------------------------ This format uses 3 different coordinate spaces. Each one can be converted to another by using a multiplier. * Voxel coordinates: actual position of voxels in space * Block coordinates: position of a block of voxels with a defined size B. For example, common block size is 16x16x16 voxels. Block coordinates can be converted into voxel coordinates by multiplying it by B, giving the origin voxel within that block. * Region coordinates: position of a region of blocks with a defined size R. A region coordinate can be converted into block coordinates by multiplying it by R, giving the origin block within that region. Powers of two may be used as multipliers. File structure[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v2/#file-structure "Permanent link") ------------------------------------------------------------------------------------------------------------------------ A region save is organized in multiple files, and is contained within a root directory containing them. Under that directory, is located two things: * A `meta.vxrm` file * A `regions` directory Under the region directory, there must be a sub-directory, for each layer of level of detail (LOD). Those folders must be named `lodX`, where `X` is the LOD index, starting from `0`. LOD folders then contain region files for that LOD. Each region file is named using the following convention: `r.X.Y.Z.vxr`, where X, Y and Z are coordinates of the region, in the region coordinate space. * `world/` * `meta.vxrm` * `regions/` * `lod0/` * `r.0.0.0.vxr` * `r.1.6.0.vxr` * `r.32.-2.-6.vxr` * ... * `lod1/` * ... * `lod2/` * ... * ... Meta file[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v2/#meta-file "Permanent link") -------------------------------------------------------------------------------------------------------------- The meta file under the root directory contains global information about all voxel data. It is currently using JSON, but may not be edited by hand. It must contain the following fields: * `version`: integer telling the version of that format. It must be `2`. Older versions may be migrated. * `block_size_po2`: size of blocks in voxels, as an integer power of two (4 for 16, 5 for 32 etc). Blocks are always cubic. * `lod_count`: how many LOD levels there are. There will be as many LOD folders. It must be greater than 0. * `region_size_po2`: size of regions in blocks, as an integer power of two (4 for 16, 5 for 32 etc). Regions are always cubic. * `sector_size`: size of a sector within a region file, as a strictly positive integer. See region format for more information. * `channel_depths`: array of 8 integers, representing the bit depth of each voxel channel: * `0`: 8 bits * `1`: 16 bits * `2`: 32 bits * `3`: 64 bits * See block format for more information. Region file[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v2/#region-file "Permanent link") ------------------------------------------------------------------------------------------------------------------ Region files are binary, little-endian. They are composed of a prologue, header, and sector data. Prologue: - "VXR_" - version: uint8_t Header: - blocks: uint32_t[region_size ^ 3] SectorData: - ... ### Prologue[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v2/#prologue "Permanent link") It starts with four 8-bit characters: `VXR_`, followed by one byte representing the version of the format in binary form. The version must be `2`. Version `1` has the same data layout so it can be read the same. Other versions cannot be read. The header is a sequence of 32-bit integers. Each integer represents information about where a block is in the file, and how big it is. The count of that sequence is the number of blocks a region can contain, and is the same in all regions. The index of elements in that sequence is calculated from 3D block positions, in ZXY order. The index for a block can be obtained with the formula `y + block_size * (x + block_size * z)`. Each integer contains two informations: - The first byte is the number of sectors the block is spanning. Obtained as `n & 0xff`. - The 3 other bytes are the index to the first sector. Obtained as `n >> 8`. ### Sectors[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v2/#sectors "Permanent link") The rest of the file is occupied by sectors. Sectors are fixed-size chunks of data. Their size is determined from the meta file described earlier. Blocks are stored in those sectors. A block can span one or more sectors. The file is partitionned in this way to allow frequently writing blocks of variable size without having to often shift consecutive contents. When we need to load a block, the address where block information starts will be the following: header_size + first_sector_index * sector_size Once we have the address of the block, the first 4 bytes at this address will contain the size of the written data. Note those 4 bytes are included in the total block size when the number of occupied sectors is determined. RegionBlockData - buffer_size: uint32_t - buffer The obtained buffer can be read using the block format. Block format[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v2/#block-format "Permanent link") -------------------------------------------------------------------------------------------------------------------- See [Block format](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v1/) Current Issues[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v2/#current-issues "Permanent link") ------------------------------------------------------------------------------------------------------------------------ Although this format is currently implemented and usable, it has known issues. ### Endianness[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v2/#endianness "Permanent link") Godot's `encode_variant` doesn't seem to care about endianness across architectures, so it's possible it becomes a problem in the future and gets changed to a custom format. The rest of this spec is not affected by this and assumes we use little-endian, however the implementation of block channels currently doesn't consider this either. This may be refined in a later iteration. ### Versioning[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v2/#versioning "Permanent link") The region format should be thought of a container for instances of the block format. The former has a version number, but the latter doesn't, which is hard to manage. We may introduce separate versionning, which will cause older saves to become incompatible. User versionning may also be added as a third layer: if the game needs to replace some metadata with new ones, or swap voxel IDs around due to a change in the game, it is desirable to expose a hook to migrate old versions. --- # Instance block format v0 - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Serialization formats * Instance block format v0 * * * Instance block format v0[¶](https://voxel-tools.readthedocs.io/en/latest/specs/instances_format_v0/#instance-block-format-v0 "Permanent link") =============================================================================================================================================== Warning This document is about an old version of the format. You may check the most recent version. This page describes the binary format used by the module to save instances to files or databases. Specification[¶](https://voxel-tools.readthedocs.io/en/latest/specs/instances_format_v0/#specification "Permanent link") ------------------------------------------------------------------------------------------------------------------------- ### Compressed container[¶](https://voxel-tools.readthedocs.io/en/latest/specs/instances_format_v0/#compressed-container "Permanent link") A block is usually serialized as compressed data. See [Compressed container format](https://voxel-tools.readthedocs.io/en/latest/specs/compressed_container/) for specification. ### Binary data[¶](https://voxel-tools.readthedocs.io/en/latest/specs/instances_format_v0/#binary-data "Permanent link") This data uses big-endian. In pseudo-code: // Root structure struct InstanceBlockData { // Version tag in case more stuff is added in the future uint8_t version = 0; // There can be up to 256 different layers in one block uint8_t layer_count; // To compress positions we need to know their range. // It's local to the block so we know it starts from zero. float position_range; LayerData layers[layer_count]; // Magic number to signal the end of the data block uint32_t control_end = 0x900df00d; }; struct LayerData { uint16_t id; // Identifies the type of instances (rocks, grass, pebbles, bushes etc) uint16_t count; // To be able to compress scale we must know its range float scale_min; float scale_max; // This tells which format instances of this layer use. For now I always use the same format, // But maybe some types of instances will need more, or less data? uint8_t format = 0; InstanceData data[count]; }; struct InstanceData { // Position is lossy-compressed based on the size of the block uint16_t x; uint16_t y; uint16_t z; // Scale is uniform and is lossy-compressed to 256 values uint8_t scale; // Rotation is a compressed quaternion uint8_t x; uint8_t y; uint8_t z; uint8_t w; }; --- # Voxel block format v3 - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Serialization formats * Voxel block format v3 * * * Voxel block format v3[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v3/#voxel-block-format-v3 "Permanent link") ===================================================================================================================================== Warning This document is about an old version of the format. You may check the most recent version. Version: 3 This page describes the binary format used by default in this module to serialize voxel blocks to files, network or databases. ### Changes from version 2[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v3/#changes-from-version-2 "Permanent link") * The second channel (at index 1) was used for SDF data but the format didn't dictate anything particular about it. It is now expected to be for SDF. It used to have an arbitrary format for fixed-point encoding. It is now using inorm16. * Compression format `1` is deprecated. * Moved compression wrapper to its own specification. Specification[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v3/#specification "Permanent link") --------------------------------------------------------------------------------------------------------------------- ### Endianness[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v3/#endianness "Permanent link") By default, little-endian. ### Compressed container[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v3/#compressed-container "Permanent link") A block is usually serialized within a compressed data container. This is the format provided by the `VoxelBlockSerializer` utility class. If you don't use compression, the layout will correspond to `BlockData` described in the next listing, and won't have this wrapper. See [Compressed container format](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v3/#compressed-container) for specification. ### Block format[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v3/#block-format "Permanent link") It starts with version number `3` in one byte, then some metadata and the actual voxels. Note The size and formats are present to make the format standalone. When used within a chunked container like region files, it is recommended to check if they match the format expected for the volume as a whole. BlockData - version: uint8_t - size_x: uint16_t - size_y: uint16_t - size_z: uint16_t - channels[8] - metadata* - epilogue ### Channels[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v3/#channels "Permanent link") Block data starts with exactly 8 channels one after the other, each with the following structure: Channel - format: uint8_t (low nibble = compression, high nibble = depth) - data `format` contains both compression and bit depth, respectively known as `VoxelBuffer::Compression` and `VoxelBuffer::Depth` enums. The low nibble contains compression, and the high nibble contains depth. Depending on those values, `data` will be different. Depth can be 0 (8-bit), 1 (16-bit), 2 (32-bit) or 3 (64-bit). If compression is `COMPRESSION_NONE` (0), `data` will be an array of N\*S bytes, where N is the number of voxels inside a block, multiplied by the number of bytes corresponding to the bit depth. For example, a block of size 16x16x16 and a channel of 32-bit depth will have `16*16*16*4` bytes to load from the file into this channel. The 3D indexing of that data is in order `ZXY`. If compression is `COMPRESSION_UNIFORM` (1), the data will be a single voxel value, which means all voxels in the block have that same value. Unused channels will always use this mode. The value spans the same number of bytes defined by the depth. Other compression values are invalid. #### SDF channel[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v3/#sdf-channel "Permanent link") The second channel (at index 1) is used for SDF data. If depth is 8 or 16 bits, it may contain fixed-point values encoded as `inorm8` or `inorm16`. This is numbers in the range \[-1..1\]. To obtain a `float` from an `int8`, use `max(i / 127, -1.f)`. To obtain a `float` from an `int16`, use `max(i / 32767, -1.f)`. For 32-bit depth, regular `float` are used. For 64-bit depth, regular `double` are used. ### Metadata[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v3/#metadata "Permanent link") After all channels information, block data can contain metadata information. Blocks that don't contain any will only have a fixed amount of bytes left (from the epilogue) before reaching the size of the total data to read. If there is more, the block contains metadata. Metadata - metadata_size: uint32_t - block_metadata - voxel_metadata[*] It starts with one 32-bit unsigned integer representing the total size of all metadata there is to read. That data comes in two groups: one for the whole block, and one per voxel. Block metadata is one Godot `Variant`, encoded using the `encode_variant` method of the engine. Voxel metadata immediately follows. It is a sequence of the following data structures, which must be read until a total of `metadata_size` bytes have been read from the beginning: VoxelMetadata - x: uint16_t - y: uint16_t - z: uint16_t - data `x`, `y` and `z` indicate which voxel the data corresponds. `data` is also a `Variant` encoded the same way as described earlier. This results in an associative collection between voxel positions relative to the block and their corresponding metadata. ### Epilogue[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v3/#epilogue "Permanent link") At the very end, block data finishes with a sequence of 4 bytes, which once read into a `uint32_t` integer must match the value `0x900df00d`. If that condition isn't fulfilled, the block must be assumed corrupted. Note On little-endian architectures (like desktop), binary editors will not show the epilogue as `0x900df00d`, but as `0x0df00d90` instead. Current Issues[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v3/#current-issues "Permanent link") ----------------------------------------------------------------------------------------------------------------------- ### Endianness[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v3/#endianness_1 "Permanent link") The format is intented to use little-endian, however the implementation of the engine does not fully guarantee this. Godot's `encode_variant` doesn't seem to care about endianness across architectures, so it's possible it becomes a problem in the future and gets changed to a custom format. The implementation of block channels with depth greater than 8-bit currently doesn't consider this either. This might be refined in a later iteration. This will become important to address if voxel games require communication between mobile and desktop. --- # VoxelFormat - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelFormat * * * VoxelFormat[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#voxelformat "Permanent link") =========================================================================================================== Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Specifies the format of voxels. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#description "Permanent link") ------------------------------------------------------------------------------------------------------------ Specifies the format of voxels. Currently, it only stores how many bytes each channel uses per voxel. Voxels have a default format which is often enough for most use cases, but sometimes it is necessary to change it. In this case, you may create a new [VoxelFormat](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/) resource, do the changes, and assign it to a [VoxelNode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/) . WARNING: it is recommended to choose a format early in development (whether it is the default, or a custom one). If you want to change much later and you have saves in the wild, you will have to figure out how to convert them, otherwise loading them will be problematic. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#properties "Permanent link") ---------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) | [\_data](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#i__data) | \[0, 1, 1, 0, 1, 1, 0, 0, 0\] | | [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) | [color\_depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#i_color_depth) | DEPTH\_8\_BIT (0) | | [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) | [indices\_depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#i_indices_depth) | DEPTH\_16\_BIT (1) | | [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) | [sdf\_depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#i_sdf_depth) | DEPTH\_16\_BIT (1) | | [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) | [type\_depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#i_type_depth) | DEPTH\_16\_BIT (1) | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#methods "Permanent link") ---------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#) | [configure\_buffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#i_configure_buffer)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
buffer ) const | | [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) | [create\_buffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#i_create_buffer)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
size ) const | | [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) | [get\_channel\_depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#i_get_channel_depth)
( [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations)
channel\_index ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#) | [set\_channel\_depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#i_set_channel_depth)
( [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations)
channel\_index, [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations)
depth ) | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- ### [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) **\_data** = \[0, 1, 1, 0, 1, 1, 0, 0, 0\][¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#array-_data-0-1-1-0-1-1-0-0-0 "Permanent link") _(This property has no documentation)_ ### [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) **color\_depth** = DEPTH\_8\_BIT (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#depth-color_depth-depth_8_bit-0 "Permanent link") Depth of [VoxelBuffer.CHANNEL\_COLOR](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_COLOR) . ### [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) **indices\_depth** = DEPTH\_16\_BIT (1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#depth-indices_depth-depth_16_bit-1 "Permanent link") Depth of [VoxelBuffer.CHANNEL\_INDICES](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_INDICES) . Only 8-bit and 16-bit depths are supported. ### [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) **sdf\_depth** = DEPTH\_16\_BIT (1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#depth-sdf_depth-depth_16_bit-1 "Permanent link") Depth of [VoxelBuffer.CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) . ### [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) **type\_depth** = DEPTH\_16\_BIT (1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#depth-type_depth-depth_16_bit-1 "Permanent link") Depth of [VoxelBuffer.CHANNEL\_TYPE](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_TYPE) . Only 8-bit and 16-bit depths are supported. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#method-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------- ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#) **configure\_buffer**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) buffer )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#void-configure_buffer-voxelbuffer-buffer "Permanent link") Clears and formats the [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) using properties from the current format. Should be used on a buffer that hasn't been modified yet. ### [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) **create\_buffer**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) size )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#voxelbuffer-create_buffer-vector3i-size "Permanent link") Creates a new [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) that has the current format. ### [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) **get\_channel\_depth**( [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) channel\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#depth-get_channel_depth-channelid-channel_index "Permanent link") Gets the depth of a specific channel. See [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) for more information. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#) **set\_channel\_depth**( [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) channel\_index, [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) depth )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/#void-set_channel_depth-channelid-channel_index-depth-depth "Permanent link") Sets the depth of a specific channel. See [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) for more information. _Generated on Aug 20, 2026_ --- # VoxelStream - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelStream * * * VoxelStream[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#voxelstream "Permanent link") =========================================================================================================== Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Inherited by: [VoxelStreamMemory](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamMemory/) , [VoxelStreamRegionFiles](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamRegionFiles/) , [VoxelStreamSQLite](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamSQLite/) , [VoxelStreamScript](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStreamScript/) Implements loading and saving voxel blocks, mainly using files. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#properties "Permanent link") ---------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [Compression](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#enumerations) | [compression\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#i_compression_mode) | COMPRESSION\_LZ4 (1) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [save\_generator\_output](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#i_save_generator_output) | false | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#methods "Permanent link") ---------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#) | [flush](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#i_flush)
( ) | | [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) | [get\_block\_size](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#i_get_block_size)
( ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_used\_channels\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#i_get_used_channels_mask)
( ) const | | [ResultCode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#enumerations) | [load\_voxel\_block](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#i_load_voxel_block)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
out\_buffer, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
block\_position, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
lod\_index ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#) | [save\_voxel\_block](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#i_save_voxel_block)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
buffer, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
block\_position, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
lod\_index ) | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#enumerations "Permanent link") -------------------------------------------------------------------------------------------------------------- enum **ResultCode**: * **RESULT\_ERROR** = **0** --- An error occurred when loading the block. The request will be aborted. * **RESULT\_BLOCK\_FOUND** = **2** --- The block was found. * **RESULT\_BLOCK\_NOT\_FOUND** = **1** --- The block was not found. The requester may fallback on using the generator, if any. Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- ### [Compression](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockSerializer/#enumerations) **compression\_mode** = COMPRESSION\_LZ4 (1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#compression-compression_mode-compression_lz4-1 "Permanent link") Specifies which compression algorithm is used when saving blocks. This can reduce the size of save files at the cost of save/load performance. Existing blocks that formerly used a different compression mode can still be loaded, and will use the new mode if saved again. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **save\_generator\_output** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#bool-save_generator_output-false "Permanent link") When this is enabled, if a block cannot be found in the stream and it gets generated, then the generated block will immediately be saved into the stream. This can be used if the generator is too expensive to run on the fly (like Minecraft does), but it will require more disk usage (amount of I/Os and space) and increase network traffic. If this setting is off, only modified blocks will be saved. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#method-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------- ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#) **flush**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#void-flush "Permanent link") Forces cached data to be saved to the filesystem. Some streams might use a cache to improve performance of frequent I/Os. This should not be called frequently if performance is a concern. May be used if you require all data to be written now. Note that implementations should already do this automatically when the resource is destroyed or their configuration changes. Some implementations may do nothing if they have no cache. Note that terrains save asynchronously, so flushing might not always fulfill your goal if saving tasks are still queued and haven't called into [VoxelStream](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/) yet. See [VoxelTerrain.save\_modified\_blocks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_save_modified_blocks) or [VoxelLodTerrain.save\_modified\_blocks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_save_modified_blocks) . ### [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) **get\_block\_size**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#vector3-get_block_size "Permanent link") _(This method has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_used\_channels\_mask**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#int-get_used_channels_mask "Permanent link") _(This method has no documentation)_ ### [ResultCode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#enumerations) **load\_voxel\_block**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) out\_buffer, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) block\_position, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) lod\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#resultcode-load_voxel_block-voxelbuffer-out_buffer-vector3i-block_position-int-lod_index "Permanent link") `out_buffer`: Block of voxels to load. Must be a pre-created instance (not null). `block_position`: Position of the block in block coordinates within the specified LOD. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#) **save\_voxel\_block**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) buffer, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) block\_position, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) lod\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#void-save_voxel_block-voxelbuffer-buffer-vector3i-block_position-int-lod_index "Permanent link") `buffer`: Block of voxels to save. It is strongly recommended to not keep a reference to that data afterward, because streams are allowed to cache it, and saved data must represent either snapshots (copies) or last references to the data after the volume they belonged to is destroyed. `block_position`: Position of the block in block coordinates within the specified LOD. _Generated on Aug 20, 2026_ --- # VoxelGeneratorGraph - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelGeneratorGraph * * * VoxelGeneratorGraph[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#voxelgeneratorgraph "Permanent link") =================================================================================================================================== Inherits: [VoxelGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/) Graph-based voxel generator. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#description "Permanent link") -------------------------------------------------------------------------------------------------------------------- Generates voxel data from a graph of per-voxel operations. The graph must be created, compiled, and only then blocks can be generated. It can be used with SDF-based smooth terrain, and also blocky terrains. Warning: methods to modify the graph should only be called from the main thread. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#properties "Permanent link") ------------------------------------------------------------------------------------------------------------------ | Type | Name | Default | | --- | --- | --- | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_block\_clipping](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_debug_block_clipping) | false | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [sdf\_clip\_threshold](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_sdf_clip_threshold) | 1.5 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [subdivision\_size](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_subdivision_size) | 16 | | [TextureMode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#enumerations) | [texture\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_texture_mode) | TEXTURE\_MODE\_MIXEL4 (0) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [use\_optimized\_execution\_map](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_use_optimized_execution_map) | true | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [use\_subdivision](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_use_subdivision) | true | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [use\_xz\_caching](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_use_xz_caching) | true | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#methods "Permanent link") ------------------------------------------------------------------------------------------------------------ | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#) | [bake\_sphere\_bumpmap](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_bake_sphere_bumpmap)
( [Image](https://docs.godotengine.org/en/stable/classes/class_image.html)
im, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
ref\_radius, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
sdf\_min, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
sdf\_max ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#) | [bake\_sphere\_normalmap](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_bake_sphere_normalmap)
( [Image](https://docs.godotengine.org/en/stable/classes/class_image.html)
im, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
ref\_radius, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
strength ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#) | [clear](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_clear)
( ) | | [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) | [compile](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_compile)
( ) | | [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) | [debug\_analyze\_range](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_debug_analyze_range)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
min\_pos, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
max\_pos ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#) | [debug\_load\_waves\_preset](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_debug_load_waves_preset)
( ) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [debug\_measure\_microseconds\_per\_voxel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_debug_measure_microseconds_per_voxel)
( [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
use\_singular\_queries ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#) | [generate\_image\_from\_sdf](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_generate_image_from_sdf)
( [Image](https://docs.godotengine.org/en/stable/classes/class_image.html)
im, [Transform3D](https://docs.godotengine.org/en/stable/classes/class_transform3d.html)
transform, [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html)
size ) | | [VoxelGraphFunction](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/) | [get\_main\_function](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_get_main_function)
( ) const | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [raycast\_sdf\_approx](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_raycast_sdf_approx)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
ray\_origin, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
ray\_end, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
stride ) const | Signals:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#signals "Permanent link") ------------------------------------------------------------------------------------------------------------ ### node\_name\_changed( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#node_name_changed-int-node_id "Permanent link") _(This signal has no documentation)_ Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#enumerations "Permanent link") ---------------------------------------------------------------------------------------------------------------------- enum **TextureMode**: * **TEXTURE\_MODE\_MIXEL4** = **0** --- Writes texture data into [VoxelBuffer.CHANNEL\_INDICES](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_INDICES) as 4 packed 4-bit indices and into [VoxelBuffer.CHANNEL\_WEIGHTS](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_WEIGHTS) as 4 packed 4-bit weights. See [VoxelMesherTransvoxel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/) and docs about smooth voxels to see how this data is used. * **TEXTURE\_MODE\_SINGLE** = **1** --- Writes texture data into [VoxelBuffer.CHANNEL\_INDICES](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_INDICES) as one 8-bit value per voxel. If you want to use this mode, make sure your voxels have the appropriate format (see [VoxelFormat](https://voxel-tools.readthedocs.io/en/latest/api/VoxelFormat/) ) Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#property-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------- ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_block\_clipping** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#bool-debug_block_clipping-false "Permanent link") When enabled, if the graph outputs SDF data, generated blocks that would otherwise be clipped will be inverted. This has the effect of them showing up as "walls artifacts", which is useful to visualize where the optimization occurs. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **sdf\_clip\_threshold** = 1.5[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#float-sdf_clip_threshold-15 "Permanent link") When generating SDF blocks for a terrain, if the range analysis of a block is beyond this threshold, its SDF data will be considered either fully air, or fully matter (using high constants, positive or negative). This optimizes memory because chunks entirely underground or in the air will have the same value on every voxel. It also saves processing time because SDF calculations (noise etc) are skipped. To turn off this optimization, set it to a high value. Downside: if you use operations to edit the terrain assuming coherent SDF, they might behave incorrectly at boundaries where the clipping starts to occur. This is notably the case of [VoxelTool.grow\_sphere](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_grow_sphere) . ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **subdivision\_size** = 16[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#int-subdivision_size-16 "Permanent link") When generating SDF blocks for a terrain, and if block size is divisible by this value, range analysis will operate on such subdivision. This allows to optimize away more precise areas. However, it may not be set too small otherwise overhead will outweight the benefits. ### [TextureMode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#enumerations) **texture\_mode** = TEXTURE\_MODE\_MIXEL4 (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#texturemode-texture_mode-texture_mode_mixel4-0 "Permanent link") Sets which voxel format will be produced by texture outputs, if present. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **use\_optimized\_execution\_map** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#bool-use_optimized_execution_map-true "Permanent link") If enabled, when generating blocks for a terrain, the generator will attempt to skip specific nodes if they are found to have no importance in specific areas. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **use\_subdivision** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#bool-use_subdivision-true "Permanent link") If enabled, [subdivision\_size](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_subdivision_size) will be used. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **use\_xz\_caching** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#bool-use_xz_caching-true "Permanent link") If enabled, the generator will run only once branches of the graph that only depend on X and Z. This is effective when part of the graph generates a heightmap, as this part is not volumetric. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#method-descriptions "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------- ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#) **bake\_sphere\_bumpmap**( [Image](https://docs.godotengine.org/en/stable/classes/class_image.html) im, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) ref\_radius, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) sdf\_min, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) sdf\_max )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#void-bake_sphere_bumpmap-image-im-float-ref_radius-float-sdf_min-float-sdf_max "Permanent link") Bakes a spherical bumpmap (or heightmap) using SDF output produced by the generator, if any. The bumpmap uses a panorama projection. `ref_radius`: radius of the sphere on which heights will be sampled. `strength`: strength of produced normals, may default to 1.0. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#) **bake\_sphere\_normalmap**( [Image](https://docs.godotengine.org/en/stable/classes/class_image.html) im, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) ref\_radius, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) strength )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#void-bake_sphere_normalmap-image-im-float-ref_radius-float-strength "Permanent link") Bakes a spherical normalmap using SDF output produced by the generator, if any. The normalmap uses a panorama projection. It is assumed the generator produces a spherical shape (like a planet). Such normalmap can be used to add more detail to distant views of a terrain using this generator. `ref_radius`: radius of the sphere on which normals will be sampled. `strength`: strength of produced normals, may default to 1.0. Note: an alternative is to use distance normals feature with [VoxelLodTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/) . ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#) **clear**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#void-clear "Permanent link") Erases all nodes and connections from the graph. ### [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) **compile**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#dictionary-compile "Permanent link") Compiles the graph so it can be used to generate blocks. If it succeeds, the returned result is a dictionary with the following layout: { "success": true } If it fails, the returned result may contain a message and the ID of a graph node that could be the cause: { "success": false, "node_id": int, "message": String } The node ID will be -1 if the error is not about a particular node. ### [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) **debug\_analyze\_range**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) min\_pos, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) max\_pos )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#vector2-debug_analyze_range-vector3-min_pos-vector3-max_pos "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#) **debug\_load\_waves\_preset**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#void-debug_load_waves_preset "Permanent link") _(This method has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **debug\_measure\_microseconds\_per\_voxel**( [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) use\_singular\_queries )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#float-debug_measure_microseconds_per_voxel-bool-use_singular_queries "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#) **generate\_image\_from\_sdf**( [Image](https://docs.godotengine.org/en/stable/classes/class_image.html) im, [Transform3D](https://docs.godotengine.org/en/stable/classes/class_transform3d.html) transform, [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) size )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#void-generate_image_from_sdf-image-im-transform3d-transform-vector2-size "Permanent link") Genereates SDF data within a plane centered on the given transform spanning its X and Y axes, and stores results in pixels of the image. Samples are centered on pixels. The image should preferably have a 32-bit float format, and must not be compressed. ### [VoxelGraphFunction](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/) **get\_main\_function**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#voxelgraphfunction-get_main_function "Permanent link") Gets the graph used for generation. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **raycast\_sdf\_approx**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) ray\_origin, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) ray\_end, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) stride )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#float-raycast_sdf_approx-vector3-ray_origin-vector3-ray_end-float-stride "Permanent link") Generates values along a ray to find the first one where SDF < 0.0, and return distance along the ray. If no hit is found, returns -1.0. This is an approximation: the error margin of the returned value will be up to the given stride. The longer the distance, the more expensive it is. The lower the stride, the more expensive and accurate it is. _Generated on Aug 20, 2026_ --- # Voxel block format v4 - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Serialization formats * Voxel block format v4 * * * Voxel block format v4[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v4/#voxel-block-format-v4 "Permanent link") ===================================================================================================================================== Version: 4 This page describes the binary format used by default in this module to serialize voxel blocks to files, network or databases. ### Changes from version 3[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v4/#changes-from-version-3 "Permanent link") * Metadata uses a new format which no longer has to depend on Godot Engine (can still use `Variant` but other options are available internally). Specification[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v4/#specification "Permanent link") --------------------------------------------------------------------------------------------------------------------- ### Endianness[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v4/#endianness "Permanent link") By default, little-endian. ### Compressed container[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v4/#compressed-container "Permanent link") A block is usually serialized within a compressed data container. This is the format provided by the `VoxelBlockSerializer` utility class. If you don't use compression, the layout will correspond to `BlockData` described in the next listing, and won't have this wrapper. See [Compressed container format](https://voxel-tools.readthedocs.io/en/latest/specs/compressed_container/) for specification. ### Block format[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v4/#block-format "Permanent link") It starts with version number `4` in one byte, then some info and the actual voxels. Optionally, it is followed by custom metadata. Note The size and formats are present to make the format standalone. When used within a chunked container like region files, it is recommended to check if they match the format expected for the volume as a whole. BlockData - version: uint8_t - size_x: uint16_t - size_y: uint16_t - size_z: uint16_t - channels[8] - metadata* - epilogue ### Channels[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v4/#channels "Permanent link") Block data starts with exactly 8 channels one after the other, each with the following structure: Channel - format: uint8_t (low nibble = compression, high nibble = depth) - data `format` contains both compression and bit depth, respectively known as `VoxelBuffer::Compression` and `VoxelBuffer::Depth` enums. The low nibble contains compression, and the high nibble contains depth. Depending on those values, `data` will be different. Depth can be 0 (8-bit), 1 (16-bit), 2 (32-bit) or 3 (64-bit). If compression is `COMPRESSION_NONE` (0), `data` will be an array of N\*S bytes, where N is the number of voxels inside a block, multiplied by the number of bytes corresponding to the bit depth. For example, a block of size 16x16x16 and a channel of 32-bit depth will have `16*16*16*4` bytes to load from the file into this channel. The 3D indexing of that data is in order `ZXY`. If compression is `COMPRESSION_UNIFORM` (1), the data will be a single voxel value, which means all voxels in the block have that same value. Unused channels will always use this mode. The value spans the same number of bytes defined by the depth. Other compression values are invalid. #### SDF channel[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v4/#sdf-channel "Permanent link") The second channel (at index 1) is used for SDF data. If depth is 8 or 16 bits, it may contain fixed-point values encoded as `inorm8` or `inorm16`. This is numbers in the range \[-1..1\]. To obtain a `float` from an `int8`, use `max(i / 127, -1.f)`. To obtain a `float` from an `int16`, use `max(i / 32767, -1.f)`. For 32-bit depth, regular `float` are used. For 64-bit depth, regular `double` are used. ### Metadata[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v4/#metadata "Permanent link") After all channels information, block data can contain metadata information. Blocks that don't contain any will only have a fixed amount of bytes left (from the epilogue) before reaching the size of the total data to read. If there is more, the block contains metadata. Metadata - metadata_size: uint32_t - block_metadata: MetadataItem - voxel_metadata: VoxelMetadataItem[*] VoxelMetadataItem - x: uint16_t - y: uint16_t - z: uint16_t - metadata: MetadataItem It starts with one 32-bit unsigned integer representing the total size of all metadata there is to read. That data comes in two groups: one for the whole block, and a list that associates one per voxel (not all voxels have metadata). Each metadata item uses the following format: MetadataItem - type: uint8_t - data It starts with a `type` header, followed by data depending on that type. * If `type` is `0`, the item is empty and there is no `data` to read. * If `type` is `1`, it is followed by 8 bytes (`uint64_t`). * If `type` is `32`, it is followed by a Godot Engine `Variant`, encoded using the `encode_variant` function. This is only available when using Godot Engine. * If `type` is greater than `32`, the following data is application-defined. The application usually knows which data corresponds to that type and defines how to serialize and deserialize it. The meaning of metadata is application-defined. Two games using different metadata are not expected to be compatible. ### Epilogue[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v4/#epilogue "Permanent link") At the very end, block data finishes with a sequence of 4 bytes, which once read into a `uint32_t` integer must match the value `0x900df00d`. If that condition isn't fulfilled, the block must be assumed corrupted. Note On little-endian architectures (like desktop), binary editors will not show the epilogue as `0x900df00d`, but as `0x0df00d90` instead. Current Issues[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v4/#current-issues "Permanent link") ----------------------------------------------------------------------------------------------------------------------- ### Endianness[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v4/#endianness_1 "Permanent link") The format is intented to use little-endian, however the implementation of the engine does not fully guarantee this. Godot's `encode_variant` doesn't seem to care about endianness across architectures, so it's possible it becomes a problem in the future and gets changed to a custom format. The implementation of block channels with depth greater than 8-bit currently doesn't consider this either. This might be refined in a later iteration. This will become important to address if voxel games require communication between mobile and desktop. --- # VoxelInstanceLibraryMultiMeshItem - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelInstanceLibraryMultiMeshItem * * * VoxelInstanceLibraryMultiMeshItem[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#voxelinstancelibrarymultimeshitem "Permanent link") ============================================================================================================================================================================= Inherits: [VoxelInstanceLibraryItem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryItem/) Instancer model using [MultiMesh](https://docs.godotengine.org/en/stable/classes/class_multimesh.html) to render. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#description "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------- This model is suited for rendering very large amounts of simple instances, such as grass and rocks. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#properties "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [PackedFloat32Array](https://docs.godotengine.org/en/stable/classes/class_packedfloat32array.html) | [\_mesh\_lod\_distance\_ratios](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i__mesh_lod_distance_ratios) | PackedFloat32Array(0.2, 0.35, 0.6, 1) | | [ShadowCastingSetting](https://docs.godotengine.org/en/stable/classes/class_renderingserver.html#enum-renderingserver-shadowcastingsetting) | [cast\_shadow](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_cast_shadow) | 1 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [collision\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_collision_distance) | \-1.0 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [collision\_layer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_collision_layer) | 1 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [collision\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_collision_mask) | 1 | | [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) | [collision\_shapes](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_collision_shapes) | \[\] | | [GIMode](https://docs.godotengine.org/en/stable/classes/class_geometryinstance3d.html#enum-geometryinstance3d-gimode) | [gi\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_gi_mode) | 1 | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [hide\_beyond\_max\_lod](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_hide_beyond_max_lod) | false | | [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) | [material\_override](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_material_override) | | | [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) | [mesh](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_mesh) | | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [mesh\_lod0\_distance\_ratio](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_mesh_lod0_distance_ratio) | 0.2 | | [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) | [mesh\_lod1](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_mesh_lod1) | | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [mesh\_lod1\_distance\_ratio](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_mesh_lod1_distance_ratio) | 0.35 | | [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) | [mesh\_lod2](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_mesh_lod2) | | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [mesh\_lod2\_distance\_ratio](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_mesh_lod2_distance_ratio) | 0.6 | | [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) | [mesh\_lod3](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_mesh_lod3) | | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [mesh\_lod3\_distance\_ratio](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_mesh_lod3_distance_ratio) | 1.0 | | [RemovalBehavior](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#enumerations) | [removal\_behavior](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_removal_behavior) | REMOVAL\_BEHAVIOR\_NONE (0) | | [PackedScene](https://docs.godotengine.org/en/stable/classes/class_packedscene.html) | [removal\_scene](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_removal_scene) | | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [render\_layer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_render_layer) | 1 | | [PackedScene](https://docs.godotengine.org/en/stable/classes/class_packedscene.html) | [scene](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_scene) | | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#methods "Permanent link") -------------------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#) | [\_on\_instance\_removed](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i__on_instance_removed)
( [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/)
instancer, [Transform3D](https://docs.godotengine.org/en/stable/classes/class_transform3d.html)
transform ) virtual | | [StringName\[\]](https://docs.godotengine.org/en/stable/classes/class_stringname[].html) | [get\_collider\_group\_names](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_get_collider_group_names)
( ) const | | [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) | [get\_mesh](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_get_mesh)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
mesh\_lod\_index ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#) | [set\_collider\_group\_names](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_set_collider_group_names)
( [StringName\[\]](https://docs.godotengine.org/en/stable/classes/class_stringname[].html)
names ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#) | [set\_mesh](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_set_mesh)
( [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html)
mesh, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
mesh\_lod\_index ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#) | [setup\_from\_template](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_setup_from_template)
( [Node](https://docs.godotengine.org/en/stable/classes/class_node.html)
node ) | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#enumerations "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ enum **RemovalBehavior**: * **REMOVAL\_BEHAVIOR\_NONE** = **0** --- No extra logic will run when instances are removed. * **REMOVAL\_BEHAVIOR\_INSTANTIATE** = **1** --- Instantiates the [removal\_scene](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_removal_scene) for each instance getting removed. The scene must have a root derived from [Node3D](https://docs.godotengine.org/en/stable/classes/class_node3d.html) , and will be given the same transform as the instance before being added to the scene tree. It will be added under the [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) node. * **REMOVAL\_BEHAVIOR\_CALLBACK** = **2** --- Calls [\_on\_instance\_removed](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i__on_instance_removed) when an instance gets removed. You should attach a script to the item in order to implement this. Note: every resource can have a [Object.script](https://docs.godotengine.org/en/stable/classes/class_object.html#class-object-property-script) . But in the editor, Godot currently doesn't show you that property if the resource appears in a sub-inspector. To workaround that, right-click the property in which the resource is, and choose "Edit". That will open the item in a full inspector. An alternative is to save your item as a file, and then edit it from the file browser. Constants:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#constants "Permanent link") ------------------------------------------------------------------------------------------------------------------------------ * **MAX\_MESH\_LODS** = **4** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#property-descriptions "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------- ### [PackedFloat32Array](https://docs.godotengine.org/en/stable/classes/class_packedfloat32array.html) **\_mesh\_lod\_distance\_ratios** = PackedFloat32Array(0.2, 0.35, 0.6, 1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#packedfloat32array-_mesh_lod_distance_ratios-packedfloat32array02-035-06-1 "Permanent link") _(This property has no documentation)_ ### [ShadowCastingSetting](https://docs.godotengine.org/en/stable/classes/class_renderingserver.html#enum-renderingserver-shadowcastingsetting) **cast\_shadow** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#shadowcastingsetting-cast_shadow-1 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **collision\_distance** = -1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#float-collision_distance-10 "Permanent link") When greater than 0 and colliders are configured, hints the distance below which colliders may be created. This allows to reduce the amount of colliders while keeping a high view distance for visuals. When negative, colliders will be created at all distances. Note: the instancer creates/removes colliders on a per-chunk basis, so this distance is compared against the distance to chunks, and not individual instances. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **collision\_layer** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#int-collision_layer-1 "Permanent link") _(This property has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **collision\_mask** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#int-collision_mask-1 "Permanent link") _(This property has no documentation)_ ### [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) **collision\_shapes** = \[\][¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#array-collision_shapes "Permanent link") Alternating list of [CollisionShape](https://docs.godotengine.org/en/stable/classes/class_collisionshape.html) and [Transform3D](https://docs.godotengine.org/en/stable/classes/class_transform3d.html) . Shape comes first, followed by its local transform relative to the instance. Setting up collision shapes in the editor may require using a scene instead. ### [GIMode](https://docs.godotengine.org/en/stable/classes/class_geometryinstance3d.html#enum-geometryinstance3d-gimode) **gi\_mode** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#gimode-gi_mode-1 "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **hide\_beyond\_max\_lod** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#bool-hide_beyond_max_lod-false "Permanent link") _(This property has no documentation)_ ### [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) **material\_override**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#material-material_override "Permanent link") _(This property has no documentation)_ ### [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) **mesh**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#mesh-mesh "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **mesh\_lod0\_distance\_ratio** = 0.2[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#float-mesh_lod0_distance_ratio-02 "Permanent link") _(This property has no documentation)_ ### [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) **mesh\_lod1**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#mesh-mesh_lod1 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **mesh\_lod1\_distance\_ratio** = 0.35[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#float-mesh_lod1_distance_ratio-035 "Permanent link") _(This property has no documentation)_ ### [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) **mesh\_lod2**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#mesh-mesh_lod2 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **mesh\_lod2\_distance\_ratio** = 0.6[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#float-mesh_lod2_distance_ratio-06 "Permanent link") _(This property has no documentation)_ ### [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) **mesh\_lod3**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#mesh-mesh_lod3 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **mesh\_lod3\_distance\_ratio** = 1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#float-mesh_lod3_distance_ratio-10 "Permanent link") _(This property has no documentation)_ ### [RemovalBehavior](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#enumerations) **removal\_behavior** = REMOVAL\_BEHAVIOR\_NONE (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#removalbehavior-removal_behavior-removal_behavior_none-0 "Permanent link") Specifies what should happen when instances get removed. This is useful if they should turn into more complex objects with animation or logic in them. ### [PackedScene](https://docs.godotengine.org/en/stable/classes/class_packedscene.html) **removal\_scene**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#packedscene-removal_scene "Permanent link") Scene that will be used if [removal\_behavior](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_removal_behavior) is set to [REMOVAL\_BEHAVIOR\_INSTANTIATE](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_REMOVAL_BEHAVIOR_INSTANTIATE) . ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **render\_layer** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#int-render_layer-1 "Permanent link") _(This property has no documentation)_ ### [PackedScene](https://docs.godotengine.org/en/stable/classes/class_packedscene.html) **scene**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#packedscene-scene "Permanent link") Scene that will be used as configuration instead of manual properties. It should have a specific node structure to be supported. See [https://voxel-tools.readthedocs.io/en/latest/instancing/#setting-up-a-multimesh-item-from-a-scene](https://voxel-tools.readthedocs.io/en/latest/instancing/#setting-up-a-multimesh-item-from-a-scene) Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------- ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#) **\_on\_instance\_removed**( [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) instancer, [Transform3D](https://docs.godotengine.org/en/stable/classes/class_transform3d.html) transform )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#void-_on_instance_removed-voxelinstancer-instancer-transform3d-transform "Permanent link") This method will be called if you set [removal\_behavior](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_removal_behavior) to [REMOVAL\_BEHAVIOR\_CALLBACK](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#i_REMOVAL_BEHAVIOR_CALLBACK) . Note: this method can be called from within the removal of a node that is child of [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) . In this context, Godot will prevent you from adding new child nodes. You can workaround that by using [Object.call\_deferred](https://docs.godotengine.org/en/stable/classes/class_object.html#class-object-method-call-deferred) . See also [VoxelInstancerRigidBody.queue\_free\_and\_notify\_instancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancerRigidBody/#i_queue_free_and_notify_instancer) . ### [StringName\[\]](https://docs.godotengine.org/en/stable/classes/class_stringname[].html) **get\_collider\_group\_names**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#stringname-get_collider_group_names "Permanent link") Gets the list of group names that are added to collider nodes. ### [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) **get\_mesh**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) mesh\_lod\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#mesh-get_mesh-int-mesh_lod_index "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#) **set\_collider\_group\_names**( [StringName\[\]](https://docs.godotengine.org/en/stable/classes/class_stringname[].html) names )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#void-set_collider_group_names-stringname-names "Permanent link") Sets the list of group names that will be added to collider nodes generated for each instance. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#) **set\_mesh**( [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) mesh, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) mesh\_lod\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#void-set_mesh-mesh-mesh-int-mesh_lod_index "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#) **setup\_from\_template**( [Node](https://docs.godotengine.org/en/stable/classes/class_node.html) node )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceLibraryMultiMeshItem/#void-setup_from_template-node-node "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # Voxel block format v1 - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Serialization formats * Voxel block format v1 * * * Voxel block format v1[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v1/#voxel-block-format-v1 "Permanent link") ===================================================================================================================================== Warning This document is about an old version of the format. You may check the most recent version. This page describes the binary format used by default in this module to serialize voxel blocks to files, network or databases. This format has no version (version 1 is assumed). Specification[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v1/#specification "Permanent link") --------------------------------------------------------------------------------------------------------------------- ### Top-levels[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v1/#top-levels "Permanent link") A block is serialized as compressed data. This is the format provided by the `VoxelBlockSerializer` utility class. If you don't use compression, the layout will correspond to `BlockData` described in the next listing. CompressedBlockData - decompressed_data_size: uint32_t - compressed_data `compressed_data` must be decompressed using the LZ4 algorithm (without header), into a buffer big enough to contain `decompressed_data_size` bytes. Knowing that size is also important later on. The obtained data then contains the actual block. It is saved as it comes, and doesn't contain metadata about its version, 3D size or the depth of each channel. If you use this for custom block serialization, you must take care of using a format known in advance when encoding and decoding, or prepending it to the data. Region files declare block format globally. BlockData - channels[8] - metadata* - epilogue ### Channels[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v1/#channels "Permanent link") Block data starts with 8 channels one after the other, each with the following structure: Channel - compression: uint8_t - data `compression` is the same as the `VoxelBuffer::Compression` enum. Depending on the value of `compression`, `data` will be different. If compression is `COMPRESSION_NONE` (0), the data will be an array of N bytes, where N is the number of voxels inside a block, multiplied by the number of bytes in the depth setting of the current channel (defined in the meta file seen earlier). For example, a block of size 16 and a channel of 32-bit depth will have `16*16*16*4` bytes to load from the file into this channel. The 3D indexing of that data is also in order `ZXY`. If compression is `COMPRESSION_UNIFORM` (1), the data will be a single voxel value, which means all voxels in the block have that same value. Unused channels will always use this mode. The value can span a variable number of bytes depending on the depth of the current channel: - 1 byte if 8-bit - 2 bytes if 16-bits - 4 bytes if 32-bits - 8 bytes if 64-bits Other compression values are invalid. ### Metadata[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v1/#metadata "Permanent link") After all channels information, block data can contain metadata information. Blocks that don't contain any will only have a fixed amount of bytes left (from the epilogue) before reaching the size of the total data to read. If there is more, the block contains metadata. Metadata - metadata_size: uint32_t - block_metadata - voxel_metadata[*] It starts with one 32-bit unsigned integer representing the total size of all metadata there is to read. That data comes in two groups: one for the whole block, and one per voxel. Block metadata is one Godot `Variant`, encoded using the `encode_variant` method of the engine. Voxel metadata immediately follows. It is a sequence of the following data structures, which must be read until a total of `metadata_size` bytes have been read from the beginning: VoxelMetadata - x: uint16_t - y: uint16_t - z: uint16_t - data `x`, `y` and `z` indicate which voxel the data corresponds. `data` is also a `Variant` encoded the same way as described earlier. This results in an associative collection between voxel positions relative to the block and their corresponding metadata. ### Epilogue[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v1/#epilogue "Permanent link") At the very end, block data finishes with a sequence of 4 bytes, which once read into a `uint32_t` integer must match the value `0x900df00d`. If that condition isn't fulfilled, the block must be assumed corrupted. Current Issues[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v1/#current-issues "Permanent link") ----------------------------------------------------------------------------------------------------------------------- Although this format is currently implemented and usable, it has known issues. ### Endianness[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v1/#endianness "Permanent link") Godot's `encode_variant` doesn't seem to care about endianness across architectures, so it's possible it becomes a problem in the future and gets changed to a custom format. The rest of this spec is not affected by this and assumes we use little-endian, however the implementation of block channels currently doesn't consider this either. This may be refined in a later iteration. ### Absence of metadata[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v1/#absence-of-metadata "Permanent link") A block can't be deserialized without external information, the format must be known in advance. In the future it may be added. ### Versioning[¶](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v1/#versioning "Permanent link") This format doesn't have a header with version tag, which may be problematic if it changes. User versionning might also be considered as a second layer: if the game needs to replace some metadata with new ones, or swap voxel IDs around due to a change in the game, it is desirable to expose a hook to migrate old versions. --- # Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Voxel Tools documentation * * * Voxel Tools documentation[¶](https://voxel-tools.readthedocs.io/en/latest/#voxel-tools-documentation "Permanent link") ======================================================================================================================= Voxel Tools is a C++ module for creating volumetric worlds in [Godot Engine](https://godotengine.org/) . Explore categories on the left to get started! * [Github repository](https://github.com/Zylann/godot_voxel) * [License](https://github.com/Zylann/godot_voxel/blob/master/LICENSE.md) Note Disclaimer: this module is the result of hobbyist experiments around voxel terrains, and is by no means a fits-all solution. A lot of features are available and can be used for games, but some other parts are lacking or can change, so it's possible some information is not well detailed yet. It is also a lot more technical than usual Godot 3D features. You may have to tinker with things or even use C++, so having prior experience in 3D development is preferable. ![Blocky screenshot](https://voxel-tools.readthedocs.io/en/latest/images/blocky_screenshot.webp) ![Editor screenshot](https://voxel-tools.readthedocs.io/en/latest/images/graph_in_editor_with_fast_noise_lite.webp) ![Smooth screenshot](https://voxel-tools.readthedocs.io/en/latest/images/smooth_screenshot.webp) --- # VoxelInstanceGenerator - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelInstanceGenerator * * * VoxelInstanceGenerator[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#voxelinstancegenerator "Permanent link") ============================================================================================================================================ Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Decides where to spawn instances on top of a voxel surface. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#description "Permanent link") ----------------------------------------------------------------------------------------------------------------------- Generates the necessary information to spawn instances on top of a voxel surface. This may be used by a [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) . Note: to generate voxels, see [VoxelGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/) . Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#properties "Permanent link") --------------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [density](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_density) | 0.1 | | [EmitMode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#enumerations) | [emit\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_emit_mode) | EMIT\_FROM\_VERTICES (0) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [jitter](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_jitter) | 1.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [max\_height](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_max_height) | 3.4028235e+38 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [max\_height\_falloff](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_max_height_falloff) | 0.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [max\_scale](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_max_scale) | 1.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [max\_slope\_degrees](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_max_slope_degrees) | 180.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [max\_slope\_falloff\_degrees](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_max_slope_falloff_degrees) | 0.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [min\_height](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_min_height) | 1.1754944e-38 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [min\_height\_falloff](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_min_height_falloff) | 0.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [min\_scale](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_min_scale) | 1.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [min\_slope\_degrees](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_min_slope_degrees) | 0.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [min\_slope\_falloff\_degrees](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_min_slope_falloff_degrees) | 0.0 | | [Noise](https://docs.godotengine.org/en/stable/classes/class_noise.html) | [noise](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_noise) | | | [Dimension](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#enumerations) | [noise\_dimension](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_noise_dimension) | DIMENSION\_3D (1) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [noise\_falloff](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_noise_falloff) | 0.0 | | [VoxelGraphFunction](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/) | [noise\_graph](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_noise_graph) | | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [noise\_on\_scale](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_noise_on_scale) | 0.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [noise\_threshold](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_noise_threshold) | 0.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [offset\_along\_normal](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_offset_along_normal) | 0.0 | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [random\_rotation](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_random_rotation) | true | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [random\_vertical\_flip](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_random_vertical_flip) | false | | [Distribution](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#enumerations) | [scale\_distribution](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_scale_distribution) | DISTRIBUTION\_QUADRATIC (1) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [snap\_to\_generator\_sdf\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_snap_to_generator_sdf_enabled) | false | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [snap\_to\_generator\_sdf\_sample\_count](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_snap_to_generator_sdf_sample_count) | 2 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [snap\_to\_generator\_sdf\_search\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_snap_to_generator_sdf_search_distance) | 1.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [triangle\_area\_threshold](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_triangle_area_threshold) | 0.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [vertical\_alignment](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_vertical_alignment) | 1.0 | | [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html) | [voxel\_texture\_filter\_array](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_voxel_texture_filter_array) | PackedInt32Array(0) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [voxel\_texture\_filter\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_voxel_texture_filter_enabled) | false | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [voxel\_texture\_filter\_threshold](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_voxel_texture_filter_threshold) | 0.5 | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#methods "Permanent link") --------------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_voxel\_texture\_filter\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_get_voxel_texture_filter_mask)
( ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#) | [set\_voxel\_texture\_filter\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_set_voxel_texture_filter_mask)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
mask ) | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#enumerations "Permanent link") ------------------------------------------------------------------------------------------------------------------------- enum **EmitMode**: * **EMIT\_FROM\_VERTICES** = **0** --- Use vertices of the mesh to spawn instances. This is the fasted option, but can produce noticeable patterns. * **EMIT\_FROM\_FACES\_FAST** = **1** --- Uses faces of the mesh to spawn instances. It is a balanced option with some shortcuts taken, without causing too noticeable patterns. * **EMIT\_FROM\_FACES** = **2** --- Uses faces of the mesh to spawn instances. This is the slowest option, but should produce no noticeable patterns. * **EMIT\_ONE\_PER\_TRIANGLE** = **3** --- Uses faces of the mesh to spawn instances (where faces are triangles). Only one instance is spawned per triangle. By default, it spawns in the middle of triangles. Randomness can be added to this position with [jitter](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_jitter) . * **EMIT\_MODE\_COUNT** = **4** enum **Distribution**: * **DISTRIBUTION\_LINEAR** = **0** --- Uniform distribution. * **DISTRIBUTION\_QUADRATIC** = **1** --- Distribution with more small items, and fewer big ones. * **DISTRIBUTION\_CUBIC** = **2** --- Distribution with even more small items, and even fewer big ones. * **DISTRIBUTION\_QUINTIC** = **3** * **DISTRIBUTION\_COUNT** = **4** enum **Dimension**: * **DIMENSION\_2D** = **0** * **DIMENSION\_3D** = **1** * **DIMENSION\_COUNT** = **2** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **density** = 0.1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-density-01 "Permanent link") Controls how many instances are generated. Might give different results depending on the type of emission chosen. ### [EmitMode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#enumerations) **emit\_mode** = EMIT\_FROM\_VERTICES (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#emitmode-emit_mode-emit_from_vertices-0 "Permanent link") In which way instances are primarily emitted. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **jitter** = 1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-jitter-10 "Permanent link") Controls randomness of spawning position when [emit\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_emit_mode) is set to [EMIT\_ONE\_PER\_TRIANGLE](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_EMIT_ONE_PER_TRIANGLE) . ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **max\_height** = 3.4028235e+38[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-max_height-34028235e38 "Permanent link") Instances will not be created above this height. This also depends on the chosen [VoxelInstancer.up\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_up_mode) . ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **max\_height\_falloff** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-max_height_falloff-00 "Permanent link") Distance over which density will fade, when below [max\_height](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_max_height) . ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **max\_scale** = 1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-max_scale-10 "Permanent link") Minimum scale instances will be randomized with. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **max\_slope\_degrees** = 180.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-max_slope_degrees-1800 "Permanent link") Instances will not spawn if the ground has a slope higher than this angle. This also depends on the chosen [VoxelInstancer.up\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_up_mode) . ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **max\_slope\_falloff\_degrees** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-max_slope_falloff_degrees-00 "Permanent link") Angular distance over which density will fade, when below [max\_slope\_degrees](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_max_slope_degrees) . ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **min\_height** = 1.1754944e-38[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-min_height-11754944e-38 "Permanent link") Instances will not be created below this height. This also depends on the chosen [VoxelInstancer.up\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_up_mode) . ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **min\_height\_falloff** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-min_height_falloff-00 "Permanent link") Distance over which density will fade, when above [min\_height](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_min_height) . ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **min\_scale** = 1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-min_scale-10 "Permanent link") Maximum scale instances will be randomized with. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **min\_slope\_degrees** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-min_slope_degrees-00 "Permanent link") Instances will not spawn if the ground has a slope lower than this angle. This also depends on the chosen [VoxelInstancer.up\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_up_mode) . ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **min\_slope\_falloff\_degrees** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-min_slope_falloff_degrees-00 "Permanent link") Angular distance over which density will fade, when above [min\_slope\_degrees](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_min_slope_degrees) . ### [Noise](https://docs.godotengine.org/en/stable/classes/class_noise.html) **noise**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#noise-noise "Permanent link") Noise used to filter out spawned instances, so that they may spawn in patterns described by the noise. ### [Dimension](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#enumerations) **noise\_dimension** = DIMENSION\_3D (1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#dimension-noise_dimension-dimension_3d-1 "Permanent link") Which dimension should be used when evaluating [noise](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_noise) and [noise\_graph](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_noise_graph) . ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **noise\_falloff** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-noise_falloff-00 "Permanent link") Noise range over which density will fade. For example if falloff is 0.3, then density will fade when noise values are between 0 and 0.3. ### [VoxelGraphFunction](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/) **noise\_graph**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#voxelgraphfunction-noise_graph "Permanent link") Graph function used to filter out spawned instances, similar to [noise](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_noise) , but allows more custom noise computations. The graph must have 2 inputs (X and Z) if [noise\_dimension](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_noise_dimension) is 2D, and 3 inputs (X, Y and Z) if 3D. There must be one SDF output. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **noise\_on\_scale** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-noise_on_scale-00 "Permanent link") How much [noise](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_noise) also affects the scale of instances. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **noise\_threshold** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-noise_threshold-00 "Permanent link") Expands or shrink noise filtering. Higher values expand the areas where instances will spawn, lower values shrinks them. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **offset\_along\_normal** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-offset_along_normal-00 "Permanent link") Offsets spawned instances along the normal of the ground. The normal depends on [VoxelInstancer.up\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_up_mode) and is also affected by [vertical\_alignment](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_vertical_alignment) . ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **random\_rotation** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#bool-random_rotation-true "Permanent link") When enbabled, instances will be given a random rotation. If not, they will use a consistent rotation depending on the ground slope. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **random\_vertical\_flip** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#bool-random_vertical_flip-false "Permanent link") When enabled, instances will randomly be flipped upside down. This can be useful with small rocks to create illusion of more variety. ### [Distribution](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#enumerations) **scale\_distribution** = DISTRIBUTION\_QUADRATIC (1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#distribution-scale_distribution-distribution_quadratic-1 "Permanent link") Sets how random scales are distributed. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **snap\_to\_generator\_sdf\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#bool-snap_to_generator_sdf_enabled-false "Permanent link") Enables snapping to generator SDF. The generator's SDF values will be queried to move instances along their normal to be closerr to ground. Can help reduce the occurrence of "floating" or "buried" instances when moving close to them. This requires the terrain's generator to support series generation. Side-effects: instances might become floating or buried when seen from far away; spawning might become less even. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **snap\_to\_generator\_sdf\_sample\_count** = 2[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#int-snap_to_generator_sdf_sample_count-2 "Permanent link") How many samples per instance will be taken from the generator in order to approach the snapping position. More samples increases precision, but is more expensive. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **snap\_to\_generator\_sdf\_search\_distance** = 1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-snap_to_generator_sdf_search_distance-10 "Permanent link") Distance up and down across which snapping will search for ground location. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **triangle\_area\_threshold** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-triangle_area_threshold-00 "Permanent link") If set greater than zero, triangles of the ground with an area lower than this threshold will be ignored. Some meshing algorithms can often produce thin or small triangles that can affect distribution quality of spawned instances. If this happens, use this property to filter them out. Note: this property is relative to LOD0. The generator will scale it when spawning instances on meshes of different LOD index. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **vertical\_alignment** = 1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-vertical_alignment-10 "Permanent link") Sets how much instances will align with the ground. If 0, they will completely align with the ground. If 1, they will completely align with whichever direction is considered "up". This depends on [VoxelInstancer.up\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/#i_up_mode) . ### [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html) **voxel\_texture\_filter\_array** = PackedInt32Array(0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#packedint32array-voxel_texture_filter_array-packedint32array0 "Permanent link") Specifies which voxel texture indices on top of which instances may spawn. This only works when [voxel\_texture\_filter\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_voxel_texture_filter_enabled) is enabled, and [VoxelMesherTransvoxel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/) is used with [VoxelMesherTransvoxel.texturing\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#i_texturing_mode) set to [VoxelMesherTransvoxel.TEXTURES\_MIXEL4\_S4](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#i_TEXTURES_MIXEL4_S4) or [VoxelMesherTransvoxel.TEXTURES\_SINGLE\_S4](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/#i_TEXTURES_SINGLE_S4) . Indices are currently limited between 0 and 31 included. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **voxel\_texture\_filter\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#bool-voxel_texture_filter_enabled-false "Permanent link") When true, enables filtering of instances based on voxel texture indices. See [voxel\_texture\_filter\_array](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_voxel_texture_filter_array) . ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **voxel\_texture\_filter\_threshold** = 0.5[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#float-voxel_texture_filter_threshold-05 "Permanent link") When [voxel\_texture\_filter\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#i_voxel_texture_filter_enabled) is active, controls how much of filtered texture has to be present for instances to spawn. The value must be betweem 0 and 1. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#method-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------- ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_voxel\_texture\_filter\_mask**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#int-get_voxel_texture_filter_mask "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#) **set\_voxel\_texture\_filter\_mask**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) mask )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstanceGenerator/#void-set_voxel_texture_filter_mask-int-mask "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelToolLodTerrain - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelToolLodTerrain * * * VoxelToolLodTerrain[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#voxeltoollodterrain "Permanent link") =================================================================================================================================== Inherits: [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) Implementation of [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) specialized for uses on [VoxelLodTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/) . Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#description "Permanent link") -------------------------------------------------------------------------------------------------------------------- Functions in this class are specific to [VoxelLodTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/) . For generic functions, you may also check [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) . It's not a class to instantiate alone, you may get it from [VoxelLodTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/) using the `get_voxel_tool()` method. Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#methods "Permanent link") ------------------------------------------------------------------------------------------------------------ | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#) | [do\_graph](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#i_do_graph)
( [VoxelGeneratorGraph](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/)
graph, [Transform3D](https://docs.godotengine.org/en/stable/classes/class_transform3d.html)
transform, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
area\_size ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#) | [do\_hemisphere](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#i_do_hemisphere)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
center, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
radius, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
flat\_direction, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
smoothness=0.0 ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#) | [do\_sphere\_async](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#i_do_sphere_async)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
center, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
radius ) | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_raycast\_binary\_search\_iterations](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#i_get_raycast_binary_search_iterations)
( ) const | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [get\_voxel\_f\_interpolated](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#i_get_voxel_f_interpolated)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
position ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#) | [run\_blocky\_random\_tick](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#i_run_blocky_random_tick)
( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html)
area, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
voxel\_count, [Callable](https://docs.godotengine.org/en/stable/classes/class_callable.html)
callback, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
batch\_count=16, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
tags\_mask=4294967295 ) | | [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) | [separate\_floating\_chunks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#i_separate_floating_chunks)
( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html)
box, [Node](https://docs.godotengine.org/en/stable/classes/class_node.html)
parent\_node ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#) | [set\_raycast\_binary\_search\_iterations](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#i_set_raycast_binary_search_iterations)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
iterations ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#) | [stamp\_sdf](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#i_stamp_sdf)
( [VoxelMeshSDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/)
mesh\_sdf, [Transform3D](https://docs.godotengine.org/en/stable/classes/class_transform3d.html)
transform, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
isolevel, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
sdf\_scale ) _(deprecated)_ | Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#method-descriptions "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------- ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#) **do\_graph**( [VoxelGeneratorGraph](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/) graph, [Transform3D](https://docs.godotengine.org/en/stable/classes/class_transform3d.html) transform, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) area\_size )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#void-do_graph-voxelgeneratorgraph-graph-transform3d-transform-vector3-area_size "Permanent link") Uses a [VoxelGeneratorGraph](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/) as a brush, which allows to program SDF operations performed by the brush. The graph must have an SDF input and an SDF output, and preferably work assuming a shape of unit size. For example, an additive sphere brush may use an `SdfSphere` node with radius 1 with a `Min` to combine it with terrain SDF. See also [online documentation](https://voxel-tools.readthedocs.io/en/latest/generators/#using-voxelgeneratorgraph-as-a-brush) . ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#) **do\_hemisphere**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) center, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) radius, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) flat\_direction, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) smoothness=0.0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#void-do_hemisphere-vector3-center-float-radius-vector3-flat_direction-float-smoothness00 "Permanent link") Operates on a hemisphere, where `flat_direction` is pointing away from the flat surface (like a normal). `smoothness` determines how the flat part blends with the rounded part, with higher values producing softer more rounded edge. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#) **do\_sphere\_async**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) center, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) radius )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#void-do_sphere_async-vector3-center-float-radius "Permanent link") _(This method has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_raycast\_binary\_search\_iterations**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#int-get_raycast_binary_search_iterations "Permanent link") _(This method has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **get\_voxel\_f\_interpolated**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) position )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#float-get_voxel_f_interpolated-vector3-position "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#) **run\_blocky\_random\_tick**( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) area, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) voxel\_count, [Callable](https://docs.godotengine.org/en/stable/classes/class_callable.html) callback, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) batch\_count=16, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) tags\_mask=4294967295 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#void-run_blocky_random_tick-aabb-area-int-voxel_count-callable-callback-int-batch_count16-int-tags_mask4294967295 "Permanent link") Picks random voxels within the specified area. If voxel models have [VoxelBlockyModel.random\_tickable](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_random_tickable) set to `true` and [VoxelBlockyModel.tags\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_tags_mask) matches any bit in `tags_mask`, executes a function on them. This only works for terrains using [VoxelMesherBlocky](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/) . The given callback takes two arguments: voxel position (Vector3i), voxel value (int). The purpose of `batch_count` is to optimize the picking process through the internal data structure. The algorithm goes as follows: `voxel_count` is divided in batches of length `batch_count`. For each batch, a random block intersecting `area` is chosen, and `batch_count` voxels are picked at random inside of it. If `voxel_count` is not divisible by `batch_count`, an extra block will be picked to do the remainder. `batch` can bias randomness by concentrating picks in specific blocks, but if this function is used every frame over time, that bias should average out. If you want no bias at all, set `batch_count` to 1. ### [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) **separate\_floating\_chunks**( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) box, [Node](https://docs.godotengine.org/en/stable/classes/class_node.html) parent\_node )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#array-separate_floating_chunks-aabb-box-node-parent_node "Permanent link") Turns floating voxels into RigidBodies. Chunks of floating voxels are detected within a box. The box is relative to the voxel volume this VoxelTool is attached to. Chunks have to be contained entirely within that box to be considered floating. Chunks are removed from the source volume and transformed into RigidBodies with convex collision shapes. They will be added as child of the provided node. They will start "kinematic", and turn "rigid" after a short time, to allow the terrain to update its colliders after the removal (otherwise they will overlap). The function returns an array of these rigid bodies, which you can use to attach further behavior to them (such as disappearing after some time or distance for example). This algorithm can become expensive quickly, so the box should not be too big. A size of around 30 voxels should be ok. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#) **set\_raycast\_binary\_search\_iterations**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) iterations )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#void-set_raycast_binary_search_iterations-int-iterations "Permanent link") Picks random voxels within the specified area and executes a function on them. This only works for terrains using [VoxelMesherBlocky](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/) . Only voxels where [Voxel.random\_tickable](https://docs.godotengine.org/en/stable/classes/class_voxel.html#class-voxel-property-random-tickable) is `true` will be picked. The given callback takes two arguments: voxel position (Vector3i), voxel value (int). Only voxels at LOD 0 will be considered. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#) **stamp\_sdf**( [VoxelMeshSDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/) mesh\_sdf, [Transform3D](https://docs.godotengine.org/en/stable/classes/class_transform3d.html) transform, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) isolevel, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) sdf\_scale )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/#void-stamp_sdf-voxelmeshsdf-mesh_sdf-transform3d-transform-float-isolevel-float-sdf_scale "Permanent link") _This method is deprecated. Use [VoxelTool.do\_mesh](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_do_mesh) instead._ _Generated on Aug 20, 2026_ --- # ZN_FastNoiseLite - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * ZN\_FastNoiseLite * * * ZN\_FastNoiseLite[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#zn_fastnoiselite "Permanent link") =========================================================================================================================== Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Generates coherent and fractal noise using the [FastNoiseLite](https://github.com/Auburn/FastNoiseLite) library. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#description "Permanent link") ----------------------------------------------------------------------------------------------------------------- This is an alternative implementation of [FastNoiseLite](https://docs.godotengine.org/en/stable/classes/class_fastnoiselite.html) , based on the same library. Some differences include different default values, and use of period instead of frequency in fractal parameters. It is also used in the voxel module in order to bypass the overhead of Godot calls in GDExtension builds. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#properties "Permanent link") --------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [CellularDistanceFunction](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#enumerations) | [cellular\_distance\_function](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_cellular_distance_function) | CELLULAR\_DISTANCE\_EUCLIDEAN\_SQ (1) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [cellular\_jitter](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_cellular_jitter) | 1.0 | | [CellularReturnType](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#enumerations) | [cellular\_return\_type](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_cellular_return_type) | CELLULAR\_RETURN\_DISTANCE (1) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [fractal\_gain](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_fractal_gain) | 0.5 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [fractal\_lacunarity](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_fractal_lacunarity) | 2.0 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [fractal\_octaves](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_fractal_octaves) | 3 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [fractal\_ping\_pong\_strength](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_fractal_ping_pong_strength) | 2.0 | | [FractalType](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#enumerations) | [fractal\_type](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_fractal_type) | FRACTAL\_FBM (1) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [fractal\_weighted\_strength](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_fractal_weighted_strength) | 0.0 | | [NoiseType](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#enumerations) | [noise\_type](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_noise_type) | TYPE\_OPEN\_SIMPLEX\_2 (0) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [period](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_period) | 64.0 | | [RotationType3D](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#enumerations) | [rotation\_type\_3d](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_rotation_type_3d) | ROTATION\_3D\_NONE (0) | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [seed](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_seed) | 0 | | [ZN\_FastNoiseLiteGradient](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/) | [warp\_noise](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_warp_noise) | | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#methods "Permanent link") --------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [get\_noise\_2d](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_get_noise_2d)
( [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
x, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
y ) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [get\_noise\_2dv](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_get_noise_2dv)
( [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html)
position ) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [get\_noise\_3d](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_get_noise_3d)
( [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
x, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
y, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
z ) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [get\_noise\_3dv](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#i_get_noise_3dv)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
position ) | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#enumerations "Permanent link") ------------------------------------------------------------------------------------------------------------------- enum **NoiseType**: * **TYPE\_OPEN\_SIMPLEX\_2** = **0** * **TYPE\_OPEN\_SIMPLEX\_2S** = **1** * **TYPE\_CELLULAR** = **2** * **TYPE\_PERLIN** = **3** * **TYPE\_VALUE\_CUBIC** = **4** * **TYPE\_VALUE** = **5** enum **FractalType**: * **FRACTAL\_NONE** = **0** * **FRACTAL\_FBM** = **1** * **FRACTAL\_RIDGED** = **2** * **FRACTAL\_PING\_PONG** = **3** enum **RotationType3D**: * **ROTATION\_3D\_NONE** = **0** * **ROTATION\_3D\_IMPROVE\_XY\_PLANES** = **1** * **ROTATION\_3D\_IMPROVE\_XZ\_PLANES** = **2** enum **CellularDistanceFunction**: * **CELLULAR\_DISTANCE\_EUCLIDEAN** = **0** * **CELLULAR\_DISTANCE\_EUCLIDEAN\_SQ** = **1** * **CELLULAR\_DISTANCE\_MANHATTAN** = **2** * **CELLULAR\_DISTANCE\_HYBRID** = **3** enum **CellularReturnType**: * **CELLULAR\_RETURN\_CELL\_VALUE** = **0** * **CELLULAR\_RETURN\_DISTANCE** = **1** * **CELLULAR\_RETURN\_DISTANCE\_2** = **2** * **CELLULAR\_RETURN\_DISTANCE\_2\_ADD** = **3** * **CELLULAR\_RETURN\_DISTANCE\_2\_SUB** = **4** * **CELLULAR\_RETURN\_DISTANCE\_2\_MUL** = **5** * **CELLULAR\_RETURN\_DISTANCE\_2\_DIV** = **6** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ ### [CellularDistanceFunction](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#enumerations) **cellular\_distance\_function** = CELLULAR\_DISTANCE\_EUCLIDEAN\_SQ (1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#cellulardistancefunction-cellular_distance_function-cellular_distance_euclidean_sq-1 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **cellular\_jitter** = 1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#float-cellular_jitter-10 "Permanent link") _(This property has no documentation)_ ### [CellularReturnType](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#enumerations) **cellular\_return\_type** = CELLULAR\_RETURN\_DISTANCE (1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#cellularreturntype-cellular_return_type-cellular_return_distance-1 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **fractal\_gain** = 0.5[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#float-fractal_gain-05 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **fractal\_lacunarity** = 2.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#float-fractal_lacunarity-20 "Permanent link") _(This property has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **fractal\_octaves** = 3[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#int-fractal_octaves-3 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **fractal\_ping\_pong\_strength** = 2.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#float-fractal_ping_pong_strength-20 "Permanent link") _(This property has no documentation)_ ### [FractalType](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#enumerations) **fractal\_type** = FRACTAL\_FBM (1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#fractaltype-fractal_type-fractal_fbm-1 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **fractal\_weighted\_strength** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#float-fractal_weighted_strength-00 "Permanent link") _(This property has no documentation)_ ### [NoiseType](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#enumerations) **noise\_type** = TYPE\_OPEN\_SIMPLEX\_2 (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#noisetype-noise_type-type_open_simplex_2-0 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **period** = 64.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#float-period-640 "Permanent link") _(This property has no documentation)_ ### [RotationType3D](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#enumerations) **rotation\_type\_3d** = ROTATION\_3D\_NONE (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#rotationtype3d-rotation_type_3d-rotation_3d_none-0 "Permanent link") _(This property has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **seed** = 0[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#int-seed-0 "Permanent link") _(This property has no documentation)_ ### [ZN\_FastNoiseLiteGradient](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLiteGradient/) **warp\_noise**[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#zn_fastnoiselitegradient-warp_noise "Permanent link") _(This property has no documentation)_ Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#method-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **get\_noise\_2d**( [float](https://docs.godotengine.org/en/stable/classes/class_float.html) x, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) y )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#float-get_noise_2d-float-x-float-y "Permanent link") _(This method has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **get\_noise\_2dv**( [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) position )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#float-get_noise_2dv-vector2-position "Permanent link") _(This method has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **get\_noise\_3d**( [float](https://docs.godotengine.org/en/stable/classes/class_float.html) x, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) y, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) z )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#float-get_noise_3d-float-x-float-y-float-z "Permanent link") _(This method has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **get\_noise\_3dv**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) position )[¶](https://voxel-tools.readthedocs.io/en/latest/api/ZN_FastNoiseLite/#float-get_noise_3dv-vector3-position "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # Region format v3 - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Serialization formats * Region format v3 * * * Region format v3[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/#region-format-v3 "Permanent link") ============================================================================================================================ Version: 3 Region files allows to save large fixed-size 3D voxel volumes in a format suitable for frequent streaming and partial edition. This format is inspired by [Seed of Andromeda](https://www.seedofandromeda.com/blogs/1-creating-a-region-file-system-for-a-voxel-game) and Minecraft. It is used by `VoxelStreamRegionFiles`, which is implemented in [this C++ file](https://github.com/Zylann/godot_voxel/blob/master/streams/region/voxel_stream_region_files.cpp) Two use cases exist: - Standalone region: fixed-size voxel volume - Region forest: using multiple region files for infinite voxel worlds without boundaries. This used to be the only case region files were used for. Note The "Region" name in this document does not designate a standard, but an approach. The format described here is specific to the Godot module, and could be referred to as `Godot Voxel VXR` if a full name is needed. Migration[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/#migration "Permanent link") -------------------------------------------------------------------------------------------------------------- Older saves made using this format can be migrated if they use version 2. ### Changes in version 3[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/#changes-in-version-3 "Permanent link") Information about block size, voxel format and palette was added, so that a standalone region file contains all the necessary information to load and save voxel data. Before, this information had to be known in advance by the user. Migration will insert extra bytes and offset the rest of the file, and will write a new header over. Coordinate spaces[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/#coordinate-spaces "Permanent link") ------------------------------------------------------------------------------------------------------------------------------ This document uses 3 different coordinate spaces. Each one can be converted to another by using a multiplier. * Voxel coordinates: actual position of voxels in space * Block coordinates: position of a block of voxels with a defined size B. For example, common block size is 16x16x16 voxels. Block coordinates can be converted into voxel coordinates by multiplying it by B, giving the origin voxel within that block. * Region coordinates: position of a region of blocks with a defined size R. A region coordinate can be converted into block coordinates by multiplying it by R, giving the origin block within that region. Powers of two may be used as multipliers. Region forest[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/#region-forest "Permanent link") ---------------------------------------------------------------------------------------------------------------------- ### Filesystem structure[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/#filesystem-structure "Permanent link") A region forest is organized in multiple region files, and is contained within a root directory containing them. Region files don't need to be inside a forest to be usable. Under that directory, is located two things: * A `meta.vxrm` file * A `regions` directory Under the region directory, there must be a sub-directory, for each layer of level of detail (LOD). Those folders must be named `lodX`, where `X` is the LOD index, starting from `0`. LOD folders then contain region files for that LOD. Each region file is named using the following convention: `r.X.Y.Z.vxr`, where X, Y and Z are coordinates of the region, in the region coordinate space. * `world/` * `meta.vxrm` * `regions/` * `lod0/` * `r.0.0.0.vxr` * `r.1.6.0.vxr` * `r.32.-2.-6.vxr` * ... * `lod1/` * ... * `lod2/` * ... * ... ### Meta file[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/#meta-file "Permanent link") The meta file under the root directory contains global information about all voxel data. It is currently using JSON, but may not be edited by hand. It must contain the following fields: * `version`: integer telling the version of that format. It must be `3`. Older versions may be migrated. * `block_size_po2`: size of blocks in voxels, as an integer power of two (4 for 16, 5 for 32 etc). Blocks are always cubic. * `lod_count`: how many LOD levels there are. There will be as many LOD folders. It must be greater than 0. * `region_size_po2`: size of regions in blocks, as an integer power of two (4 for 16, 5 for 32 etc). Regions are always cubic. * `sector_size`: size of a sector within a region file, as a strictly positive integer. See [region file](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/#region-file) for more information. * `channel_depths`: array of 8 integers, representing the bit depth of each voxel channel: * `0`: 8 bits * `1`: 16 bits * `2`: 32 bits * `3`: 64 bits * See block format for more information. Region file[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/#region-file "Permanent link") ------------------------------------------------------------------------------------------------------------------ Region files are binary, little-endian. They are composed of a prologue, header, and sector data. Prologue: - "VXR_" - version: uint8_t Header: - block_size_po2: uint8_t // cubic size of the block as a power of two. Must not be zero. - region_size_x: uint8_t // How many blocks the region spans across X - region_size_y: uint8_t // How many blocks the region spans across Y - region_size_z: uint8_t // How many blocks the region spans across Z - channel_depths: uint8_t[8] // Channel depths, same as described in region forest meta files - sector_size: uint16_t - palette_hint: uint8_t - palette: uint32_t[256] - blocks: uint32_t[region_size ^ 3] SectorData: - ... ### Prologue[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/#prologue "Permanent link") It starts with four 8-bit characters: `VXR_`, followed by one byte representing the version of the format in binary form. The version must be `3`. The header starts with some metadata describing the size of the volume and the format of voxels. It no longer has a fixed size. A color palette can be optionally provided. If `palette_hint` is set to `0xff` (`255`), it must be followed by 256 8-bit RGBA values. If `palette_hint` is `0x00` (`0`), then no palette data will follow. Other values are invalid at the moment. `blocks` is a sequence of 32-bit integers, located at the end of the header. Each integer represents information about where a block is in the file, and how big its serialized data is. The count of that sequence is the number of blocks a region can contain, and remains constant for a given region size. The index of elements in that sequence is calculated from 3D block positions, in ZXY order. The index for a block can be obtained with the formula `y + block_size * (x + block_size * z)`. Each integer contains two informations: - The first byte is the number of sectors the block is spanning. Obtained as `n & 0xff`. - The 3 other bytes are the index to the first sector. Obtained as `n >> 8`. As a result, if a block is unoccupied, its value is `0`. ### Sectors[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/#sectors "Permanent link") The rest of the file is occupied by sectors. Sectors are fixed-size chunks of data. Their size is determined from the header described earlier, and also in a meta file if part of a region forest. Blocks are stored in those sectors. A block can span one or more sectors. The file is partitioned in this way to allow frequently writing blocks of variable size without having to often shift consecutive contents. When we need to load a block, the address where block information starts will be the following: header_size + first_sector_index * sector_size Once we have the address of the block, the first 4 bytes at this address will contain the size of the written data. Note: those 4 bytes are included in the total block size when the number of occupied sectors is determined. RegionBlockData - buffer_size: uint32_t - buffer The obtained buffer can be read using the block format. Block format[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/#block-format "Permanent link") -------------------------------------------------------------------------------------------------------------------- See [Block format](https://voxel-tools.readthedocs.io/en/latest/specs/block_format_v2/) Current Issues[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/#current-issues "Permanent link") ------------------------------------------------------------------------------------------------------------------------ Although this format is currently implemented and usable, it has known issues. ### Endianness[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/#endianness "Permanent link") Godot's `encode_variant` doesn't seem to care about endianness across architectures, so it's possible it becomes a problem in the future and gets changed to a custom format. The rest of this spec is not affected by this and assumes we use little-endian, however the implementation of block channels currently doesn't consider this either. This may be refined in a later iteration. ### Versioning[¶](https://voxel-tools.readthedocs.io/en/latest/specs/region_format_v3/#versioning "Permanent link") The region format should be thought of a container for instances of the block format. The former has a version number, but the latter doesn't, which is hard to manage. We may introduce separate versionning, which will cause older saves to become incompatible. User versionning may also be added as a third layer: if the game needs to replace some metadata with new ones, or swap voxel IDs around due to a change in the game, it is desirable to expose a hook to migrate old versions. --- # VoxelTerrain - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelTerrain * * * VoxelTerrain[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#voxelterrain "Permanent link") ============================================================================================================== Inherits: [VoxelNode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/) Voxel volume using constant level of detail. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#properties "Permanent link") ----------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [area\_edit\_notification\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_area_edit_notification_enabled) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [automatic\_loading\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_automatic_loading_enabled) | true | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [block\_enter\_notification\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_block_enter_notification_enabled) | false | | [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) | [bounds](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_bounds) | AABB(-536870900, -536870900, -536870900, 1073741800, 1073741800, 1073741800) | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [collision\_layer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_collision_layer) | 1 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [collision\_margin](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_collision_margin) | 0.04 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [collision\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_collision_mask) | 1 | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_debug_draw_enabled) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_shadow\_occluders](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_debug_draw_shadow_occluders) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_visual\_and\_collision\_blocks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_debug_draw_visual_and_collision_blocks) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_volume\_bounds](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_debug_draw_volume_bounds) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_voxel\_metadata](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_debug_draw_voxel_metadata) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [generate\_collisions](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_generate_collisions) | true | | [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) | [material\_override](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_material_override) | | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [max\_view\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_max_view_distance) | 128 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [mesh\_block\_size](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_mesh_block_size) | 16 | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [use\_gpu\_generation](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_use_gpu_generation) | false | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#methods "Permanent link") ----------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#) | [\_on\_area\_edited](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i__on_area_edited)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
area\_origin, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
area\_size ) virtual | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#) | [\_on\_data\_block\_entered](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i__on_data_block_entered)
( [VoxelDataBlockEnterInfo](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/)
info ) virtual | | [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) | [data\_block\_to\_voxel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_data_block_to_voxel)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
block\_pos ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_get\_draw\_flag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_debug_get_draw_flag)
( [DebugDrawFlag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#enumerations)
flag\_index ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#) | [debug\_set\_draw\_flag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_debug_set_draw_flag)
( [DebugDrawFlag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#enumerations)
flag\_index, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
enabled ) | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_data\_block\_size](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_get_data_block_size)
( ) const | | [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) | [get\_statistics](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_get_statistics)
( ) const | | [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html) | [get\_viewer\_network\_peer\_ids\_in\_area](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_get_viewer_network_peer_ids_in_area)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
area\_origin, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
area\_size ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [has\_data\_block](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_has_data_block)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
block\_position ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [is\_area\_meshed](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_is_area_meshed)
( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html)
area\_in\_voxels ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#) | [save\_block](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_save_block)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
position ) | | [VoxelSaveCompletionTracker](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/) | [save\_modified\_blocks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_save_modified_blocks)
( ) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [try\_set\_block\_data](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_try_set_block_data)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
position, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
voxels ) | | [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) | [voxel\_to\_data\_block](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_voxel_to_data_block)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
voxel\_pos ) const | Signals:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#signals "Permanent link") ----------------------------------------------------------------------------------------------------- ### block\_loaded( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) position )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#block_loaded-vector3i-position "Permanent link") Emitted when a new data block is loaded from stream. This can happen before the mesh or collider becomes available. ### block\_unloaded( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) position )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#block_unloaded-vector3i-position "Permanent link") Emitted when a data block is unloaded due to being outside view distance. ### mesh\_block\_entered( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) position )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#mesh_block_entered-vector3i-position "Permanent link") Emitted when a mesh block receives its first update since it was added in the range of viewers. This is regardless of the mesh being empty or not. It tracks changes of the same state obtained with [is\_area\_meshed](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_is_area_meshed) . ### mesh\_block\_exited( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) position )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#mesh_block_exited-vector3i-position "Permanent link") Emitted when a mesh block gets unloaded. It is the counterpart of [VoxelTerrain.mesh\_block\_entered](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#signals) . Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#enumerations "Permanent link") --------------------------------------------------------------------------------------------------------------- enum **DebugDrawFlag**: * **DEBUG\_DRAW\_VOLUME\_BOUNDS** = **0** * **DEBUG\_DRAW\_VISUAL\_AND\_COLLISION\_BLOCKS** = **1** * **DEBUG\_DRAW\_VOXEL\_METADATA** = **2** * **DEBUG\_DRAW\_FLAGS\_COUNT** = **3** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#property-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **area\_edit\_notification\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#bool-area_edit_notification_enabled-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **automatic\_loading\_enabled** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#bool-automatic_loading_enabled-true "Permanent link") If turned off, the terrain will no longer automatically load blocks around viewers locally. This may be used in multiplayer scenarios, when the terrain is client-side, because blocks will be sent by the server instead. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **block\_enter\_notification\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#bool-block_enter_notification_enabled-false "Permanent link") _(This property has no documentation)_ ### [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) **bounds** = AABB(-536870900, -536870900, -536870900, 1073741800, 1073741800, 1073741800)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#aabb-bounds-aabb-536870900-536870900-536870900-1073741800-1073741800-1073741800 "Permanent link") Defines the bounds within which the terrain is allowed to have voxels. If an infinite world generator is used, blocks will only generate within this region. Everything outside will be left empty. If any dimension of the new bounds is larger than 512 and [max\_view\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_max_view_distance) is larger than 512, then [max\_view\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#i_max_view_distance) will be clamped to 512. This measure is to avoid crashing due to a potential huge amount of chunks that would load. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **collision\_layer** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#int-collision_layer-1 "Permanent link") _(This property has no documentation)_ ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **collision\_margin** = 0.04[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#float-collision_margin-004 "Permanent link") _(This property has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **collision\_mask** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#int-collision_mask-1 "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#bool-debug_draw_enabled-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_shadow\_occluders** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#bool-debug_draw_shadow_occluders-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_visual\_and\_collision\_blocks** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#bool-debug_draw_visual_and_collision_blocks-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_volume\_bounds** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#bool-debug_draw_volume_bounds-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_voxel\_metadata** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#bool-debug_draw_voxel_metadata-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **generate\_collisions** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#bool-generate_collisions-true "Permanent link") Enables the generation of collision shapes using the classic physics engine. Use this feature if you need realistic or non-trivial collisions or physics. Note 1: you also need [VoxelViewer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/) to request collisions, otherwise they won't generate. Note 2: If you need simple Minecraft/AABB physics, you can use [VoxelBoxMover](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBoxMover/) which may perform better in blocky worlds. ### [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) **material\_override**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#material-material_override "Permanent link") _(This property has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **max\_view\_distance** = 128[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#int-max_view_distance-128 "Permanent link") Sets the maximum distance this terrain can support. If a [VoxelViewer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/) requests more, it will be clamped. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **mesh\_block\_size** = 16[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#int-mesh_block_size-16 "Permanent link") Sets how many voxels across meshes of the terrain span. Voxel chunks are stored in cubic chunks of 16x16x16 voxels, and by default meshes of the terrain match that size. But you can set this to 32 so meshes will span 2x2x2 voxel chunks. This is a performance tradeoff. Higher mesh size may speed up rendering, at the cost of slower mesh updates. Values other than 16 and 32 are not supported. Note: this setting also affects [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) chunks. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **use\_gpu\_generation** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#bool-use_gpu_generation-false "Permanent link") Enables GPU block generation, which can speed it up. This is only valid for generators that support it. Vulkan is required. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#method-descriptions "Permanent link") ---------------------------------------------------------------------------------------------------------------------------- ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#) **\_on\_area\_edited**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) area\_origin, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) area\_size )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#void-_on_area_edited-vector3i-area_origin-vector3i-area_size "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#) **\_on\_data\_block\_entered**( [VoxelDataBlockEnterInfo](https://voxel-tools.readthedocs.io/en/latest/api/VoxelDataBlockEnterInfo/) info )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#void-_on_data_block_entered-voxeldatablockenterinfo-info "Permanent link") _(This method has no documentation)_ ### [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) **data\_block\_to\_voxel**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) block\_pos )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#vector3i-data_block_to_voxel-vector3i-block_pos "Permanent link") Converts data block coordinates into voxel coordinates. Voxel coordinates of a block correspond to its lowest corner. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_get\_draw\_flag**( [DebugDrawFlag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#enumerations) flag\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#bool-debug_get_draw_flag-debugdrawflag-flag_index "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#) **debug\_set\_draw\_flag**( [DebugDrawFlag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#enumerations) flag\_index, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) enabled )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#void-debug_set_draw_flag-debugdrawflag-flag_index-bool-enabled "Permanent link") _(This method has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_data\_block\_size**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#int-get_data_block_size "Permanent link") _(This method has no documentation)_ ### [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) **get\_statistics**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#dictionary-get_statistics "Permanent link") Gets debug information about how much time is spent processing the terrain. The returned dictionary has the following structure: { "time_detect_required_blocks": int, "time_request_blocks_to_load": int, "time_process_load_responses": int, "time_request_blocks_to_update": int, "time_process_update_responses": int, "remaining_main_thread_blocks": int, "dropped_block_loads": int, "dropped_block_meshs": int, "updated_blocks": int } ### [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html) **get\_viewer\_network\_peer\_ids\_in\_area**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) area\_origin, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) area\_size )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#packedint32array-get_viewer_network_peer_ids_in_area-vector3i-area_origin-vector3i-area_size "Permanent link") _(This method has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **has\_data\_block**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) block\_position )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#bool-has_data_block-vector3i-block_position "Permanent link") _(This method has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **is\_area\_meshed**( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) area\_in\_voxels )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#bool-is_area_meshed-aabb-area_in_voxels "Permanent link") Returns true if the area has been processed by meshing. It does not mean the area actually contains a mesh. Returns false if the area has not been processed by meshing (therefore it is unknown whethere there should be a mesh here or not). When streaming terrain, this can be used to determine if an area has fully "loaded", in case the game relies meshes or mesh colliders. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#) **save\_block**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) position )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#void-save_block-vector3i-position "Permanent link") Forces a specific block to be saved. Note 1: this will only have an effect if the stream setup on this terrain supports saving. Note 2: saving is asynchronous and won't block the game. the save may complete only a short time after you call this method. ### [VoxelSaveCompletionTracker](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/) **save\_modified\_blocks**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#voxelsavecompletiontracker-save_modified_blocks "Permanent link") Forces all modified blocks to be saved. Note 1: this will only have an effect if the stream setup on this terrain supports saving. Note 2: saving is asynchronous and won't block the game. the save may complete only a short time after you call this method. Use the returned tracker object to know when saving has completed. However, saves occurring after calling this method won't be tracked by this object. Note that blocks getting unloaded as the viewer moves around can also trigger saving tasks, independently from this function. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **try\_set\_block\_data**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) position, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) voxels )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#bool-try_set_block_data-vector3i-position-voxelbuffer-voxels "Permanent link") _(This method has no documentation)_ ### [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) **voxel\_to\_data\_block**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) voxel\_pos )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTerrain/#vector3i-voxel_to_data_block-vector3-voxel_pos "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelMeshSDF - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelMeshSDF * * * VoxelMeshSDF[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#voxelmeshsdf "Permanent link") ============================================================================================================== Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Signed distance field of a mesh as voxels. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#description "Permanent link") ------------------------------------------------------------------------------------------------------------- This resource can be used to bake a mesh into a signed distance field (SDF). The data is stored as an internal voxel buffer. This can then be used as a shape or brush in voxel-based operations. Note: if you can, prefer using procedural shapes (like sphere or box) for better quality and performance. While versatile, [VoxelMeshSDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/) it is more expensive to use and currently has lower quality compared to procedural equivalents. Note 2: not all meshes can be baked. Best meshes should be manifold and represent a closed shape, with clear inside and outside. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#properties "Permanent link") ----------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) | [\_data](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i__data) | {} | | [BakeMode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#enumerations) | [bake\_mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_bake_mode) | BAKE\_MODE\_ACCURATE\_PARTITIONED (1) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [boundary\_sign\_fix\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_boundary_sign_fix_enabled) | true | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [cell\_count](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_cell_count) | 64 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [margin\_ratio](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_margin_ratio) | 0.25 | | [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) | [mesh](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_mesh) | | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [partition\_subdiv](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_partition_subdiv) | 32 | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#methods "Permanent link") ----------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#) | [bake](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_bake)
( ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#) | [bake\_async](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_bake_async)
( [SceneTree](https://docs.godotengine.org/en/stable/classes/class_scenetree.html)
scene\_tree ) | | [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) | [debug\_check\_sdf](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_debug_check_sdf)
( [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html)
mesh ) | | [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) | [get\_aabb](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_get_aabb)
( ) const | | [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) | [get\_voxel\_buffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_get_voxel_buffer)
( ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [is\_baked](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_is_baked)
( ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [is\_baking](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_is_baking)
( ) const | Signals:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#signals "Permanent link") ----------------------------------------------------------------------------------------------------- ### baked( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#baked "Permanent link") Emitted when asynchronous baking is complete. Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#enumerations "Permanent link") --------------------------------------------------------------------------------------------------------------- enum **BakeMode**: * **BAKE\_MODE\_ACCURATE\_NAIVE** = **0** --- Checks every triangle from every cell to find the closest distances. It tries to be accurate, but is much slower than other techniques. The mesh must be closed, otherwise the SDF will contain errors. Signs are calculated by getting the closest triangle and checking which side of the triangle the center of the cell is. * **BAKE\_MODE\_ACCURATE\_PARTITIONED** = **1** --- Similar to the naive method, but subdivides space into partitions in order to more easily skip triangles that don't need to be checked. Faster than the naive method, but still relatively slow. * **BAKE\_MODE\_APPROX\_INTERP** = **2** --- Experimental method subdividing space in 4x4x4 cells, and skipping SDF calculations by interpolating 8 corners instead if no triangles are present in those cells. Faster than the naive method, but not particularly interesting. Might be removed. * **BAKE\_MODE\_APPROX\_FLOODFILL** = **3** --- Approximates the SDF by calculating a thin "hull" of accurate values near triangles, then propagates those values with a 26-way floodfill. Signs are calculated only on the initial hull by doing several raycasts from the center of each cell: if the ray hits a backface, the cell is assumed to be inside. Otherwise, it is assumed to be outside. Signs are propagated as part of the floodfill. While technically not accurate, it is currently the fastest method and results are often good enough. * **BAKE\_MODE\_COUNT** = **4** --- How many baking modes there are. Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#property-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- ### [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) **\_data** = {}[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#dictionary-_data "Permanent link") _(This property has no documentation)_ ### [BakeMode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#enumerations) **bake\_mode** = BAKE\_MODE\_ACCURATE\_PARTITIONED (1)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#bakemode-bake_mode-bake_mode_accurate_partitioned-1 "Permanent link") Selects the algorithm that will be used to compute SDF from the mesh. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **boundary\_sign\_fix\_enabled** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#bool-boundary_sign_fix_enabled-true "Permanent link") Some algorithms might fail to properly compute the sign of distances on their own. Usually outside the shape has positive sign, and inside the shape has negative sign. Errors can cause the wrong sign to "leak" and propagate outside the shape. This option attempts to fix this when it happens by assuming that the border of the baked region is always outside, and propagates positive signs inwards to ensure no negative signs leak. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **cell\_count** = 64[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#int-cell_count-64 "Permanent link") Controls the resolution of the baked SDF, proportionally to one side of the 3D voxel buffer. Higher increases quality, but is slower to bake and uses more memory. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **margin\_ratio** = 0.25[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#float-margin_ratio-025 "Permanent link") Controls the addition of extra space around the mesh's baking area. Proper SDF buffers should have some margin in order to capture outside gradients. Without margin, the outside could appear cutoff or blocky when remeshed. This property adds margin based on a ratio of the size of the mesh. For example, if the mesh is 100 units wide, a margin of 0.1 will add 10 extra units of space around it. ### [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) **mesh**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#mesh-mesh "Permanent link") Mesh that will be baked when calling the [bake](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_bake) function, or when pressing the Bake button in the editor. Setting this property back to null will not erase the baked result, so you don't need the original mesh to be loaded in order to use the SDF. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **partition\_subdiv** = 32[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#int-partition_subdiv-32 "Permanent link") Controls how many subdivisions to use across the baking area when using the [BAKE\_MODE\_ACCURATE\_PARTITIONED](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_BAKE_MODE_ACCURATE_PARTITIONED) and [BAKE\_MODE\_APPROX\_FLOODFILL](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_BAKE_MODE_APPROX_FLOODFILL) modes. When using [BAKE\_MODE\_ACCURATE\_PARTITIONED](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_BAKE_MODE_ACCURATE_PARTITIONED) , that value may be proportionally adjusted based on the amount of triangles the mesh has, due to an imperfection of the algorithm. If the mesh has few triangles, lower values will perform better. If it has a lot of small triangles, higher values will perform better. However, if triangles are large or few and the value is big, this will also potentially create artifacts. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#method-descriptions "Permanent link") ---------------------------------------------------------------------------------------------------------------------------- ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#) **bake**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#void-bake "Permanent link") Bakes the SDF on the calling thread, using the currently assigned [mesh](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_mesh) . Might cause the game to stall if done on the main thread. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#) **bake\_async**( [SceneTree](https://docs.godotengine.org/en/stable/classes/class_scenetree.html) scene\_tree )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#void-bake_async-scenetree-scene_tree "Permanent link") Bakes the SDF on a separate thread, using the currently assigned [mesh](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_mesh) . See also [is\_baking](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_is_baking) , [is\_baked](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_is_baked) and [VoxelMeshSDF.baked](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#signals) . ### [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) **debug\_check\_sdf**( [Mesh](https://docs.godotengine.org/en/stable/classes/class_mesh.html) mesh )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#array-debug_check_sdf-mesh-mesh "Permanent link") Experimental. Runs some checks to verify if the baked SDF contains errors. The mesh to pass should be the mesh that was used for baking. If there are errors, the returned array will contain information about up to 2 cells of the buffer containing wrong values, in the following format: [\ cell0_position: Vector3,\ cell0_triangle_v0: Vector3,\ cell0_triangle_v1: Vector3,\ cell0_triangle_v2: Vector3,\ cell1_position: Vector3,\ cell1_triangle_v0: Vector3,\ cell1_triangle_v1: Vector3,\ cell1_triangle_v2: Vector3,\ ] If there are no errors, the returned array will be empty. This method is a leftover from when this resource was initially implemented, as an attempt to automate checks when debugging. Errors might not always indicate an unusable SDF, depending on the use case. It might be removed or changed in the future. ### [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) **get\_aabb**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#aabb-get_aabb "Permanent link") Get the reference bounding box of the baked shape. This may be a bit larger than the original mesh's AABB because of the [margin\_ratio](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#i_margin_ratio) property. ### [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) **get\_voxel\_buffer**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#voxelbuffer-get_voxel_buffer "Permanent link") Get the [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) containing the baked distance field. Results will be stored in the SDF channel. This buffer should not be modified. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **is\_baked**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#bool-is_baked "Permanent link") Gets whether the resource contains baked SDF data. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **is\_baking**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/#bool-is_baking "Permanent link") Gets whether a asynchronous baking operation is pending. _Generated on Aug 20, 2026_ --- # VoxelViewer - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelViewer * * * VoxelViewer[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#voxelviewer "Permanent link") =========================================================================================================== Inherits: [Node3D](https://docs.godotengine.org/en/stable/classes/class_node3d.html) Attach this as a child node of characters, so the voxel world will know where to load blocks around them. If no viewer is present in the world, nothing will generate. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#description "Permanent link") ------------------------------------------------------------------------------------------------------------ The voxel world uses the position and options of all the [VoxelViewer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/) nodes to determine where to load blocks, and prioritize updates. For example, a voxel placed 100 units away from a player will have much lower priority than the modifications that player is doing when digging in front of them. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#properties "Permanent link") ---------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [enabled\_in\_editor](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#i_enabled_in_editor) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [requires\_collisions](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#i_requires_collisions) | true | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [requires\_data\_block\_notifications](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#i_requires_data_block_notifications) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [requires\_visuals](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#i_requires_visuals) | true | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [view\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#i_view_distance) | 128 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [view\_distance\_vertical\_ratio](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#i_view_distance_vertical_ratio) | 1.0 | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#methods "Permanent link") ---------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_network\_peer\_id](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#i_get_network_peer_id)
( ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#) | [set\_network\_peer\_id](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#i_set_network_peer_id)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
id ) | Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#property-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **enabled\_in\_editor** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#bool-enabled_in_editor-false "Permanent link") Sets whether this viewer will cause loading to occur in the editor. This is mainly intented for testing purposes. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **requires\_collisions** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#bool-requires_collisions-true "Permanent link") If set to `true`, the engine will generate classic collision shapes around this viewer. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **requires\_data\_block\_notifications** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#bool-requires_data_block_notifications-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **requires\_visuals** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#bool-requires_visuals-true "Permanent link") If set to `true`, the engine will generate meshes around this viewer. This may be enabled for the local player. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **view\_distance** = 128[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#int-view_distance-128 "Permanent link") How far should voxels generate around this viewer. Note: the effective view distance may be limited by the terrain node. Note 2: when using [VoxelLodTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/) , this distance essentially acts as a limit to how far the last LOD extends. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **view\_distance\_vertical\_ratio** = 1.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#float-view_distance_vertical_ratio-10 "Permanent link") Modifies vertical view distance to be a ratio of the [view\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#i_view_distance) property. For example, if [view\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#i_view_distance) is 100 and this property is 0.5, then horizontal view distance will be 100 and vertical view distance will be 50. This property has limitations: it is only implemented on [VoxelLodTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/) when using [VoxelLodTerrain.STREAMING\_SYSTEM\_CLIPBOX](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_STREAMING_SYSTEM_CLIPBOX) , and applies only to the last LOD, like view distance. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#method-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------- ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_network\_peer\_id**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#int-get_network_peer_id "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#) **set\_network\_peer\_id**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) id )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelViewer/#void-set_network_peer_id-int-id "Permanent link") _(This method has no documentation)_ _Generated on Aug 20, 2026_ --- # VoxelTool - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelTool * * * VoxelTool[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#voxeltool "Permanent link") ===================================================================================================== Inherits: [RefCounted](https://docs.godotengine.org/en/stable/classes/class_refcounted.html) Inherited by: [VoxelToolBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolBuffer/) , [VoxelToolLodTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolLodTerrain/) , [VoxelToolMultipassGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolMultipassGenerator/) , [VoxelToolTerrain](https://voxel-tools.readthedocs.io/en/latest/api/VoxelToolTerrain/) Helper class to easily access and modify voxels Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#description "Permanent link") ---------------------------------------------------------------------------------------------------------- Abstract interface to access and edit voxels. It allows accessing individual voxels, or doing bulk operations such as carving large chunks or copy/paste boxes. It's not a class to instantiate alone, you may get it from the voxel objects you want to work with, because it has multiple derived implementations. By default, if an operation overlaps a non-editable area (if not loaded yet for example), the operation will be cancelled. This behavior may vary in derived classes. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#properties "Permanent link") -------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) | [channel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_channel) | | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [eraser\_value](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_eraser_value) | | | [Mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#enumerations) | [mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_mode) | | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [sdf\_scale](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_sdf_scale) | | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [sdf\_strength](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_sdf_strength) | | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [texture\_falloff](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_texture_falloff) | | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [texture\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_texture_index) | | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [texture\_opacity](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_texture_opacity) | | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [value](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_value) | | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#methods "Permanent link") -------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [color\_to\_u16](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_color_to_u16)
( [Color](https://docs.godotengine.org/en/stable/classes/class_color.html)
color ) static | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [color\_to\_u16\_weights](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_color_to_u16_weights)
( [Color](https://docs.godotengine.org/en/stable/classes/class_color.html)
\_unnamed\_arg0 ) static | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [color\_to\_u32](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_color_to_u32)
( [Color](https://docs.godotengine.org/en/stable/classes/class_color.html)
color ) static | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) | [copy](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_copy)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
src\_pos, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
dst\_buffer, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channels\_mask=255, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
with\_metadata=true ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) | [do\_box](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_do_box)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
begin, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
end ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) | [do\_mesh](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_do_mesh)
( [VoxelMeshSDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/)
mesh\_sdf, [Transform3D](https://docs.godotengine.org/en/stable/classes/class_transform3d.html)
transform, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
isolevel=0.0 ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) | [do\_path](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_do_path)
( [PackedVector3Array](https://docs.godotengine.org/en/stable/classes/class_packedvector3array.html)
points, [PackedFloat32Array](https://docs.godotengine.org/en/stable/classes/class_packedfloat32array.html)
radii ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) | [do\_point](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_do_point)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
pos ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) | [do\_sphere](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_do_sphere)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
center, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
radius ) | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_voxel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_get_voxel)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
pos ) | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [get\_voxel\_f](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_get_voxel_f)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
pos ) | | [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) | [get\_voxel\_metadata](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_get_voxel_metadata)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
pos ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) | [grow\_sphere](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_grow_sphere)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
sphere\_center, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
sphere\_radius, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
strength ) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [is\_area\_editable](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_is_area_editable)
( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html)
box ) const | | [Color](https://docs.godotengine.org/en/stable/classes/class_color.html) | [normalize\_color](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_normalize_color)
( [Color](https://docs.godotengine.org/en/stable/classes/class_color.html)
\_unnamed\_arg0 ) static | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) | [paste](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_paste)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
dst\_pos, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
src\_buffer, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channels\_mask=255 ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) | [paste\_masked](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_paste_masked)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
dst\_pos, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
src\_buffer, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channels\_mask, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
mask\_channel, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
mask\_value ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) | [paste\_masked\_writable\_list](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_paste_masked_writable_list)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
position, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
voxels, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channels\_mask, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
src\_mask\_channel, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
src\_mask\_value, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
dst\_mask\_channel, [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html)
dst\_writable\_list ) | | [VoxelRaycastResult](https://voxel-tools.readthedocs.io/en/latest/api/VoxelRaycastResult/) | [raycast](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_raycast)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
origin, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
direction, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
max\_distance=10.0, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
collision\_mask=4294967295 ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) | [set\_raycast\_normal\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_set_raycast_normal_enabled)
( [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
enabled ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) | [set\_voxel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_set_voxel)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
pos, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
v ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) | [set\_voxel\_f](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_set_voxel_f)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
pos, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
v ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) | [set\_voxel\_metadata](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_set_voxel_metadata)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
pos, [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html)
meta ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) | [smooth\_sphere](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_smooth_sphere)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
sphere\_center, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
sphere\_radius, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
blur\_radius ) | | [Vector4i](https://docs.godotengine.org/en/stable/classes/class_vector4i.html) | [u16\_indices\_to\_vec4i](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_u16_indices_to_vec4i)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
\_unnamed\_arg0 ) static | | [Color](https://docs.godotengine.org/en/stable/classes/class_color.html) | [u16\_weights\_to\_color](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_u16_weights_to_color)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
\_unnamed\_arg0 ) static | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [vec4i\_to\_u16\_indices](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_vec4i_to_u16_indices)
( [Vector4i](https://docs.godotengine.org/en/stable/classes/class_vector4i.html)
\_unnamed\_arg0 ) static | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#enumerations "Permanent link") ------------------------------------------------------------------------------------------------------------ enum **Mode**: * **MODE\_ADD** = **0** --- When editing [VoxelBuffer.CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) , will add matter. Useful for building. * **MODE\_REMOVE** = **1** --- When editing [VoxelBuffer.CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) , will subtract matter. Useful for digging. * **MODE\_SET** = **2** --- Replace voxel values without any blending. Useful for blocky voxels. * **MODE\_TEXTURE\_PAINT** = **3** --- When editing [VoxelBuffer.CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) in smooth Terrain, enables texture painting. The value of [texture\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_texture_index) will be added to texture indices of the affected voxels. The texture's weight will be blended based on the values of [texture\_falloff](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_texture_falloff) and [texture\_opacity](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_texture_opacity) . Results will differ depending on which texturing mode is used by the mesher. Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#property-descriptions "Permanent link") ----------------------------------------------------------------------------------------------------------------------------- ### [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) **channel**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#channelid-channel "Permanent link") Set which channel will be edited. When used on a terrain node, it will default to the first available channel, based on the stream and generator. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **eraser\_value**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#int-eraser_value "Permanent link") Sets which value will be used to erase voxels when editing the [VoxelBuffer.CHANNEL\_TYPE](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_TYPE) channel in [MODE\_REMOVE](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_MODE_REMOVE) mode. Only relevant for blocky voxels. ### [Mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#enumerations) **mode**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#mode-mode "Permanent link") Sets how `do_*` functions will behave. This may vary depending on the channel. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **sdf\_scale**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#float-sdf_scale "Permanent link") When working with smooth voxels, applies a scale to the signed distance field. A high scale (1 or higher) will tend to produce blocky results, and a low scale (below 1, but not too close to zero) will tend to be smoother. This is related to the [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) configuration on voxels. For 8-bit and 16-bit, there is a limited range of values the Signed Distance Field can take, and by default it is clamped to -1..1, so the gradient can only range across 2 voxels. But when LOD is used, it is better to stretch that range over a longer distance, and this is achieved by scaling SDF values. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **sdf\_strength**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#float-sdf_strength "Permanent link") When editing [VoxelBuffer.CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) of smooth Terrains in [MODE\_ADD](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_MODE_ADD) or [MODE\_REMOVE](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_MODE_REMOVE) , determines the interpolation phase between current values and values set by the tool. Can be interpreted as the amount of "matter" added or subtracted. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **texture\_falloff**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#float-texture_falloff "Permanent link") Range \[0.001..1.0\]. Determines texture blending strength when tool is set to [MODE\_TEXTURE\_PAINT](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_MODE_TEXTURE_PAINT) . Lower values produce sharper transitions. Can be compared to brush softness in an image editing program. This is only relevant with smooth voxels and texturing modes that support long gradients. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **texture\_index**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#int-texture_index "Permanent link") Index of the texture used in smooth voxel texture painting mode. The choice of this index depends on the way you setup rendering of textured voxel meshes (for example, layer index in a texture array). ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **texture\_opacity**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#float-texture_opacity "Permanent link") Range \[0.0..1.0\]. Determines the maximum weight of a [texture\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_texture_index) when tool is set to [MODE\_TEXTURE\_PAINT](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_MODE_TEXTURE_PAINT) . Can be compared to brush opacity in an image editing program. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **value**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#int-value "Permanent link") Sets which voxel value will be used. This is not relevant when editing [VoxelBuffer.CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) . Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------- ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **color\_to\_u16**( [Color](https://docs.godotengine.org/en/stable/classes/class_color.html) color )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#int-color_to_u16-color-color "Permanent link") Encodes normalized 4-float color into 16-bit integer data. It is used with the COLOR channel, in cases where the channel represents direct colors (without using a palette). ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **color\_to\_u16\_weights**( [Color](https://docs.godotengine.org/en/stable/classes/class_color.html) \_unnamed\_arg0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#int-color_to_u16_weights-color-_unnamed_arg0 "Permanent link") Encodes normalized 4-float color into 16-bit integer data, for use with the WEIGHTS channel. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **color\_to\_u32**( [Color](https://docs.godotengine.org/en/stable/classes/class_color.html) color )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#int-color_to_u32-color-color "Permanent link") Encodes normalized 4-float color into 32-bit integer data, for use with the COLOR channel. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) **copy**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) src\_pos, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) dst\_buffer, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channels\_mask=255, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) with\_metadata=true )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#void-copy-vector3i-src_pos-voxelbuffer-dst_buffer-int-channels_mask255-bool-with_metadatatrue "Permanent link") Copies voxels in a box and stores them in the passed buffer. The source format will overwrite the destination. `src_pos` is the lowest corner of the box, and its size is determined by the size of `dst_buffer`. `channels_mask` is a bitmask where each bit tells which channels will be copied. Example: `1 << VoxelBuffer.CHANNEL_SDF` to get only SDF data. Use [VoxelBuffer.ALL\_CHANNELS\_MASK](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_ALL_CHANNELS_MASK) if you want them all. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) **do\_box**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) begin, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) end )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#void-do_box-vector3i-begin-vector3i-end "Permanent link") Operate on a rectangular cuboid section of the terrain. With blocky voxels, `begin` and `end` are inclusive. With smooth voxels, `end` is exclusive. You may choose which operation to do before calling this function, by setting [mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_mode) . With blocky voxels, you may also set [value](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_value) to choose which voxel ID to use. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) **do\_mesh**( [VoxelMeshSDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/) mesh\_sdf, [Transform3D](https://docs.godotengine.org/en/stable/classes/class_transform3d.html) transform, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) isolevel=0.0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#void-do_mesh-voxelmeshsdf-mesh_sdf-transform3d-transform-float-isolevel00 "Permanent link") Applies the given mesh shape to the terrain. The model must be baked into a signed distance field with [VoxelMeshSDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMeshSDF/) . `transform` may be used to position, rotate and scale the model. Non-uniform scale might introduce artifacts. `isolevel` is a distance that inflates or contracts the model if increased or decreased respectively. Quality depends on resolution of the model's SDF, and performance will be lower than primitive shapes such as [do\_sphere](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_do_sphere) . ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) **do\_path**( [PackedVector3Array](https://docs.godotengine.org/en/stable/classes/class_packedvector3array.html) points, [PackedFloat32Array](https://docs.godotengine.org/en/stable/classes/class_packedfloat32array.html) radii )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#void-do_path-packedvector3array-points-packedfloat32array-radii "Permanent link") Traces a "tube" defined by a list of points, each having a corresponding radius to control the width of the tube at each point. The begin and end of the path is rounded. This is equivalent to placing/carving multiple connected capsules with varying top/bottom radius. The path is not using bezier or splines, each point is connected linearly to the next. If you need more smoothness, you may add points to areas that need them. The more points, the slower it is. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) **do\_point**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) pos )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#void-do_point-vector3i-pos "Permanent link") Operates on a single voxel. You may choose which operation to do before calling this function, by setting [mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_mode) . With blocky voxels, you may also set [value](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_value) to choose which voxel ID to use. This function is not well adapted to smooth voxels, and can introduce blockyness. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) **do\_sphere**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) center, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) radius )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#void-do_sphere-vector3-center-float-radius "Permanent link") Operate on voxels within a sphere. You may choose which operation to do before calling this function, by setting [mode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_mode) . With blocky voxels, you may also set [value](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_value) to choose which voxel ID to use. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_voxel**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) pos )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#int-get_voxel-vector3i-pos "Permanent link") Gets data from voxel at `pos` coordinates. The returned value will be an unsigned integer. The meaning of the value depends on [channel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_channel) the tool is set to. When using [VoxelBuffer.CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) for smooth voxels, the returned value will be an encoded value, so you may use [get\_voxel\_f](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_get_voxel_f) to get a float value instead. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **get\_voxel\_f**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) pos )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#float-get_voxel_f-vector3i-pos "Permanent link") Gets data from voxel at `pos` coordinates, interpreting it as a floating-point SDF value. This is recommended to query the [VoxelBuffer.CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) channel for smooth voxels. ### [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) **get\_voxel\_metadata**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) pos )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#variant-get_voxel_metadata-vector3i-pos "Permanent link") Gets arbitrary data attached to a specific voxel. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) **grow\_sphere**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) sphere\_center, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) sphere\_radius, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) strength )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#void-grow_sphere-vector3-sphere_center-float-sphere_radius-float-strength "Permanent link") Adds/removes (depending on `mode`) a value to/from all voxels within a sphere. Added/removed value will be equal to `strength` at the center of the sphere, and decreases linearly to zero at the surface of the sphere. Voxels outside the sphere will not be affected. `sphere_center` is position in the terrain that will be smoothed out. `sphere_radius` radius of a sphere from the `center` where voxel values will be affected. Should be greater than zero. `strength` value that controls maximal value that will be added/removed to/from voxels. Suggested range is \[0, 10\]. Note 1: This is currently implemented only for terrain that uses SDF data (smooth voxels). Note 2: This is meant to be analogous to Surface tool from Unreal Engine Voxel Plugin. Note 3: This method assumes terrain SDF is coherent. If it isn't, you may notice differences in speeds at which terrain erodes or grows. For example, some generators fallback to a constant SDF when far away from the surface in order to speed up calculations (see [VoxelGeneratorGraph.sdf\_clip\_threshold](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/#i_sdf_clip_threshold) ). Note 4: If you want to use this method to dig terrain "smoothly" by calling it every frame, an alternative is to use [do\_sphere](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_do_sphere) but instead of the center being on the surface, move it back by about 0.95% of the radius so only a small fraction of the sphere will penetrate, digging a hole progressively. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **is\_area\_editable**( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) box )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#bool-is_area_editable-aabb-box "Permanent link") Returns `true` if the specified voxel area can be edited. This can also be interpreted as the area being "loaded". Note: when using LOD, only the nearest LOD (0) is editable. Other factors can influence whether an area is editable or not, such as streaming mode or terrain bounds. ### [Color](https://docs.godotengine.org/en/stable/classes/class_color.html) **normalize\_color**( [Color](https://docs.godotengine.org/en/stable/classes/class_color.html) \_unnamed\_arg0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#color-normalize_color-color-_unnamed_arg0 "Permanent link") A helper method to set the sum of channels of the `Color` to 1. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) **paste**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) dst\_pos, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) src\_buffer, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channels\_mask=255 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#void-paste-vector3i-dst_pos-voxelbuffer-src_buffer-int-channels_mask255 "Permanent link") Paste voxels in a box from the given buffer at a specific location. `dst_pos` is the lowest corner of the box, and its size is determined by the size of `src_buffer`. `channels_mask` is a bitmask where each bit tells which channels will be modified. Example: `1 << VoxelBuffer.CHANNEL_SDF` only write SDF data. Use [VoxelBuffer.ALL\_CHANNELS\_MASK](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_ALL_CHANNELS_MASK) if you want them all. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) **paste\_masked**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) dst\_pos, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) src\_buffer, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channels\_mask, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) mask\_channel, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) mask\_value )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#void-paste_masked-vector3i-dst_pos-voxelbuffer-src_buffer-int-channels_mask-int-mask_channel-int-mask_value "Permanent link") Paste voxels in a box from the given buffer at a specific location. Voxels having a specific value in a mask channel will not be pasted. `dst_pos` is the lowest corner of the box, and its size is determined by the size of `src_buffer`. `channels_mask` is a bitmask where each bit tells which channels will be modified. Example: `1 << VoxelBuffer.CHANNEL_SDF` only write SDF data. Use [VoxelBuffer.ALL\_CHANNELS\_MASK](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_ALL_CHANNELS_MASK) if you want them all. `src_mask_channel` channel from the source buffer that will be used to lookup mask values. `src_mask_value` if voxels of the source buffer have this value in the channel specified for masking, then they won't be pasted. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) **paste\_masked\_writable\_list**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) position, [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) voxels, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channels\_mask, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) src\_mask\_channel, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) src\_mask\_value, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) dst\_mask\_channel, [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html) dst\_writable\_list )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#void-paste_masked_writable_list-vector3i-position-voxelbuffer-voxels-int-channels_mask-int-src_mask_channel-int-src_mask_value-int-dst_mask_channel-packedint32array-dst_writable_list "Permanent link") Paste voxels in a box from the given buffer at a specific location. Voxels having a specific value in a mask channel of the source buffer will not be pasted, and existing voxels at the destination will only be modified if they have specific values. `dst_pos` is the lowest corner of the box, and its size is determined by the size of `src_buffer`. `channels_mask` is a bitmask where each bit tells which channels will be modified. Example: `1 << VoxelBuffer.CHANNEL_SDF` only write SDF data. Use [VoxelBuffer.ALL\_CHANNELS\_MASK](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_ALL_CHANNELS_MASK) if you want them all. `src_mask_channel` channel from the source buffer that will be used to lookup mask values. `src_mask_value` if voxels of the source buffer have this value in the channel specified for masking, then they won't be pasted. `dst_mask_channel` channel from the destination that will be used to select writable voxels. `dst_writable_list` List of values the destination voxels must have in order to be written to. Values in that list must be between 0 and 65535. A very large amount of values can also affect performance. ### [VoxelRaycastResult](https://voxel-tools.readthedocs.io/en/latest/api/VoxelRaycastResult/) **raycast**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) origin, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) direction, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) max\_distance=10.0, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) collision\_mask=4294967295 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#voxelraycastresult-raycast-vector3-origin-vector3-direction-float-max_distance100-int-collision_mask4294967295 "Permanent link") Runs a voxel-based raycast to find the first hit from an origin and a direction. Coordinates are in world space. Returns a result object if a voxel got hit, otherwise returns `null`. This is useful when colliders cannot be relied upon. It might also be faster (at least at short range), and is more precise to find which voxel is hit. It internally uses the DDA algorithm. `collision_mask` is currently only used with blocky voxels. It is combined with [VoxelBlockyModel.collision\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBlockyModel/#i_collision_mask) to decide which voxel types the ray can collide with. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) **set\_raycast\_normal\_enabled**( [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) enabled )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#void-set_raycast_normal_enabled-bool-enabled "Permanent link") Sets whether [raycast](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#i_raycast) will compute hit normals. This is true by default. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) **set\_voxel**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) pos, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) v )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#void-set_voxel-vector3i-pos-int-v "Permanent link") Sets the raw integer value of a specific voxel on the current channel. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) **set\_voxel\_f**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) pos, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) v )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#void-set_voxel_f-vector3i-pos-float-v "Permanent link") Sets the signed distance field (SDF) value a specific voxel. This should preferably be used on the SDF channel. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) **set\_voxel\_metadata**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) pos, [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) meta )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#void-set_voxel_metadata-vector3i-pos-variant-meta "Permanent link") Attaches arbitrary data on a specific voxel. Old data is replaced. Passing `null` will erase metadata. If the underlying voxels can be saved, this metadata will also be saved, so make sure the data supports serialization (i.e you can't put nodes or arbitrary objects in it). ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#) **smooth\_sphere**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) sphere\_center, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) sphere\_radius, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) blur\_radius )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#void-smooth_sphere-vector3-sphere_center-float-sphere_radius-int-blur_radius "Permanent link") Smoothens out terrain by performing box blur in a spherical area. Strength will be maximal at the center of the sphere, and decreases linearly to zero at the surface of the sphere. Voxels outside the sphere will not be affected. `sphere_center` is position in the terrain that will be smoothed out. `sphere_radius` radius of a sphere from the `center` where voxel values will be affected. Should be greater than zero. `blur_radius` half the box blur length that will be sampled to calculate average voxel values. Higher values results in more aggressive smoothing. Should be at least 1. Note 1: This is currently implemented only for terrain that uses SDF data (smooth voxels). Note 2: Beware of using high `sphere_radius` and high `blur_radius` as the performance can drop quickly if this is called 60 times a second. ### [Vector4i](https://docs.godotengine.org/en/stable/classes/class_vector4i.html) **u16\_indices\_to\_vec4i**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) \_unnamed\_arg0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#vector4i-u16_indices_to_vec4i-int-_unnamed_arg0 "Permanent link") Decodes raw voxel integer data from the INDICES channel into a 4-integer vector. ### [Color](https://docs.godotengine.org/en/stable/classes/class_color.html) **u16\_weights\_to\_color**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) \_unnamed\_arg0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#color-u16_weights_to_color-int-_unnamed_arg0 "Permanent link") Decodes raw voxel integer data from the WEIGHTS channel into a normalized 4-float color. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **vec4i\_to\_u16\_indices**( [Vector4i](https://docs.godotengine.org/en/stable/classes/class_vector4i.html) \_unnamed\_arg0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/#int-vec4i_to_u16_indices-vector4i-_unnamed_arg0 "Permanent link") Encodes a 4-integer vector into 16-bit integer voxel data, for use in the INDICES channel. _Generated on Aug 20, 2026_ --- # VoxelGraphFunction - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelGraphFunction * * * VoxelGraphFunction[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#voxelgraphfunction "Permanent link") ================================================================================================================================ Inherits: [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) Graph for generating or processing series of 3D values. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#description "Permanent link") ------------------------------------------------------------------------------------------------------------------- Contains a graph that can be used to process series of values, such as voxel positions (when used as main function of a generator), or to be re-used into other graphs (like a sub-graph). Currently this class only stores a graph, it cannot run actual processing on its own. It is usually embedded into another resource which then makes use of the graph in a specific way. To generate voxels with it, see [VoxelGeneratorGraph](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGeneratorGraph/) . Nodes can be connected together from their outputs to the inputs of next nodes. Unconnected inputs can have default values or default implicit connections. Nodes can also have "parameters" which are constants setup per node. Nodes come in 3 main families: inputs (only have outputs), outputs (only have inputs), and others (which have both inputs and output to do some calculation). Node types are identified with the enum [NodeTypeID](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#enumerations) . This enum shouldn't be used in persistent contexts (such as save files) as its values may change between versions. Graphs can only process 32-bit floating point values. Description of node types is present in the graph editor node dialog, or at [https://voxel-tools.readthedocs.io/en/latest/graph\_nodes](https://voxel-tools.readthedocs.io/en/latest/graph_nodes) . Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#properties "Permanent link") ----------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) | [input\_definitions](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_input_definitions) | \[\] | | [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) | [output\_definitions](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_output_definitions) | \[\] | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#methods "Permanent link") ----------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) | [add\_connection](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_add_connection)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
src\_node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
src\_port\_index, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
dst\_node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
dst\_port\_index ) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [can\_connect](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_can_connect)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
src\_node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
src\_port\_index, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
dst\_node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
dst\_port\_index ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) | [clear](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_clear)
( ) | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [create\_function\_node](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_create_function_node)
( [VoxelGraphFunction](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/)
function, [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html)
position, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
id=0 ) | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [create\_node](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_create_node)
( [NodeTypeID](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#enumerations)
type\_id, [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html)
position, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
id=0 ) | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [find\_node\_by\_name](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_find_node_by_name)
( [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html)
name ) const | | [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) | [get\_connections](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_get_connections)
( ) const | | [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) | [get\_node\_default\_input](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_get_node_default_input)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
input\_index ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [get\_node\_default\_inputs\_autoconnect](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_get_node_default_inputs_autoconnect)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id ) const | | [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) | [get\_node\_gui\_position](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_get_node_gui_position)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id ) const | | [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) | [get\_node\_gui\_size](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_get_node_gui_size)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id ) const | | [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html) | [get\_node\_ids](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_get_node_ids)
( ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_node\_input\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_get_node_input_index)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id, [String](https://docs.godotengine.org/en/stable/classes/class_string.html)
input\_name ) const | | [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html) | [get\_node\_name](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_get_node_name)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_node\_output\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_get_node_output_index)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id, [String](https://docs.godotengine.org/en/stable/classes/class_string.html)
output\_name ) const | | [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) | [get\_node\_param](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_get_node_param)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
param\_index ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_node\_type\_count](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_get_node_type_count)
( ) const | | [NodeTypeID](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#enumerations) | [get\_node\_type\_id](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_get_node_type_id)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id ) const | | [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) | [get\_node\_type\_info](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_get_node_type_info)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
type\_id ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) | [paste\_graph\_with\_pre\_generated\_ids](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_paste_graph_with_pre_generated_ids)
( [VoxelGraphFunction](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/)
graph, [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html)
node\_ids, [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html)
gui\_offset ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) | [remove\_connection](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_remove_connection)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
src\_node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
src\_port\_index, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
dst\_node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
dst\_port\_index ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) | [remove\_node](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_remove_node)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) | [set\_expression\_node\_inputs](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_set_expression_node_inputs)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id, [PackedStringArray](https://docs.godotengine.org/en/stable/classes/class_packedstringarray.html)
names ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) | [set\_node\_default\_input](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_set_node_default_input)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
input\_index, [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html)
value ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) | [set\_node\_default\_input\_by\_name](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_set_node_default_input_by_name)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id, [String](https://docs.godotengine.org/en/stable/classes/class_string.html)
input\_name, [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html)
value ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) | [set\_node\_default\_inputs\_autoconnect](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_set_node_default_inputs_autoconnect)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
enabled ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) | [set\_node\_gui\_position](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_set_node_gui_position)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id, [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html)
position ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) | [set\_node\_gui\_size](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_set_node_gui_size)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id, [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html)
size ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) | [set\_node\_name](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_set_node_name)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id, [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html)
name ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) | [set\_node\_param](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_set_node_param)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
param\_index, [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html)
value ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) | [set\_node\_param\_by\_name](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_set_node_param_by_name)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id, [String](https://docs.godotengine.org/en/stable/classes/class_string.html)
param\_name, [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html)
value ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) | [set\_node\_param\_null](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_set_node_param_null)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
param\_index ) | Signals:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#signals "Permanent link") ----------------------------------------------------------------------------------------------------------- ### compiled( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#compiled "Permanent link") Emitted after the graph finished compiling, even if compiling failed. ### node\_name\_changed( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#node_name_changed-int-node_id "Permanent link") _(This signal has no documentation)_ Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#enumerations "Permanent link") --------------------------------------------------------------------------------------------------------------------- enum **NodeTypeID**: * **NODE\_CONSTANT** = **0** * **NODE\_INPUT\_X** = **1** * **NODE\_INPUT\_Y** = **2** * **NODE\_INPUT\_Z** = **3** * **NODE\_OUTPUT\_SDF** = **4** * **NODE\_CUSTOM\_INPUT** = **52** * **NODE\_CUSTOM\_OUTPUT** = **53** * **NODE\_ADD** = **5** * **NODE\_SUBTRACT** = **6** * **NODE\_MULTIPLY** = **7** * **NODE\_DIVIDE** = **8** * **NODE\_SIN** = **9** * **NODE\_FLOOR** = **10** * **NODE\_ABS** = **11** * **NODE\_SQRT** = **12** * **NODE\_FRACT** = **13** * **NODE\_STEPIFY** = **14** * **NODE\_WRAP** = **15** * **NODE\_MIN** = **16** * **NODE\_MAX** = **17** * **NODE\_DISTANCE\_2D** = **18** * **NODE\_DISTANCE\_3D** = **19** * **NODE\_CLAMP** = **20** * **NODE\_MIX** = **22** * **NODE\_REMAP** = **23** * **NODE\_SMOOTHSTEP** = **24** * **NODE\_CURVE** = **25** * **NODE\_SELECT** = **26** * **NODE\_NOISE\_2D** = **27** * **NODE\_NOISE\_3D** = **28** * **NODE\_IMAGE\_2D** = **29** * **NODE\_SDF\_PLANE** = **30** * **NODE\_SDF\_BOX** = **31** * **NODE\_SDF\_SPHERE** = **32** * **NODE\_SDF\_TORUS** = **33** * **NODE\_SDF\_PREVIEW** = **34** * **NODE\_SDF\_SPHERE\_HEIGHTMAP** = **35** * **NODE\_SDF\_SMOOTH\_UNION** = **36** * **NODE\_SDF\_SMOOTH\_SUBTRACT** = **37** * **NODE\_NORMALIZE\_3D** = **38** * **NODE\_FAST\_NOISE\_2D** = **39** * **NODE\_FAST\_NOISE\_3D** = **40** * **NODE\_FAST\_NOISE\_GRADIENT\_2D** = **41** * **NODE\_FAST\_NOISE\_GRADIENT\_3D** = **42** * **NODE\_OUTPUT\_WEIGHT** = **43** * **NODE\_OUTPUT\_SINGLE\_TEXTURE** = **45** * **NODE\_EXPRESSION** = **46** * **NODE\_POWI** = **47** * **NODE\_POW** = **48** * **NODE\_INPUT\_SDF** = **49** * **NODE\_COMMENT** = **50** * **NODE\_FUNCTION** = **51** * **NODE\_RELAY** = **54** * **NODE\_SPOTS\_2D** = **55** * **NODE\_SPOTS\_3D** = **56** * **NODE\_TYPE\_COUNT** = **59** * **NODE\_FAST\_NOISE\_2\_2D** = **57** * **NODE\_FAST\_NOISE\_2\_3D** = **58** Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#property-descriptions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------- ### [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) **input\_definitions** = \[\][¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#array-input_definitions "Permanent link") _(This property has no documentation)_ ### [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) **output\_definitions** = \[\][¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#array-output_definitions "Permanent link") _(This property has no documentation)_ Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#method-descriptions "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------- ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) **add\_connection**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) src\_node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) src\_port\_index, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) dst\_node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) dst\_port\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#void-add_connection-int-src_node_id-int-src_port_index-int-dst_node_id-int-dst_port_index "Permanent link") Connects the outputs of a node to the input of another node. Connecting a node to itself, or in a way that can lead it back to itself, is not supported. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **can\_connect**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) src\_node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) src\_port\_index, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) dst\_node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) dst\_port\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#bool-can_connect-int-src_node_id-int-src_port_index-int-dst_node_id-int-dst_port_index "Permanent link") Tests if two ports can be connected together. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) **clear**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#void-clear "Permanent link") Removes all nodes from the graph. Input and output definitions will not be cleared. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **create\_function\_node**( [VoxelGraphFunction](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/) function, [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) position, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) id=0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#int-create_function_node-voxelgraphfunction-function-vector2-position-int-id0 "Permanent link") Creates a node based on an existing graph (creates a "sub-graph instance"). ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **create\_node**( [NodeTypeID](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#enumerations) type\_id, [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) position, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) id=0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#int-create_node-nodetypeid-type_id-vector2-position-int-id0 "Permanent link") Creates a graph node of a given type at a specific visual position. The `position` parameter does not affect how the graph will perform, however it helps organizing nodes. An optional ID can be specified. If left to 0, the ID will be generated. This function then returns the ID of the node, which may be useful to modify other properties of the node later. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **find\_node\_by\_name**( [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html) name )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#int-find_node_by_name-stringname-name "Permanent link") Finds a node with the specified name and returns its ID. If the node is not found, returns 0. ### [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) **get\_connections**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#array-get_connections "Permanent link") Gets an array describing all connections between nodes. The array has the following format: [\ {\ "src_node_id": int,\ "src_port_index": int,\ "dst_node_id": int,\ "dst_port_index": int\ },\ ...\ ] ### [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) **get\_node\_default\_input**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) input\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#variant-get_node_default_input-int-node_id-int-input_index "Permanent link") _(This method has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **get\_node\_default\_inputs\_autoconnect**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#bool-get_node_default_inputs_autoconnect-int-node_id "Permanent link") _(This method has no documentation)_ ### [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) **get\_node\_gui\_position**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#vector2-get_node_gui_position-int-node_id "Permanent link") Get the position of the node in the graph editor. ### [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) **get\_node\_gui\_size**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#vector2-get_node_gui_size-int-node_id "Permanent link") Get the size of the node in the graph editor. ### [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html) **get\_node\_ids**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#packedint32array-get_node_ids "Permanent link") Get a list of IDs of all the nodes in the graph. Note: the order in which IDs are returned is not guaranteed to be the same after nodes are added or removed. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_node\_input\_index**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id, [String](https://docs.godotengine.org/en/stable/classes/class_string.html) input\_name )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#int-get_node_input_index-int-node_id-string-input_name "Permanent link") Gets the input index of a node from the input's name. ### [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html) **get\_node\_name**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#stringname-get_node_name-int-node_id "Permanent link") Gets the user-defined name of the node. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_node\_output\_index**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id, [String](https://docs.godotengine.org/en/stable/classes/class_string.html) output\_name )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#int-get_node_output_index-int-node_id-string-output_name "Permanent link") Gets the output index of a node from the output's name. ### [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) **get\_node\_param**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) param\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#variant-get_node_param-int-node_id-int-param_index "Permanent link") Get a parameter of a node. The parameter index corresponds to the position that parameter comes in when seen in the editor. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_node\_type\_count**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#int-get_node_type_count "Permanent link") Get how many types of nodes exist in the graph system. ### [NodeTypeID](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#enumerations) **get\_node\_type\_id**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#nodetypeid-get_node_type_id-int-node_id "Permanent link") Get the ID of the type of a node in the graph. ### [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) **get\_node\_type\_info**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) type\_id )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#dictionary-get_node_type_info-int-type_id "Permanent link") Gets information about a node type from [NodeTypeID](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#enumerations) . The returned data has this structure: { "name": String, "inputs": [\ {"name": String},\ ...\ ], "outputs": [\ {"name": String},\ ...\ ], "params": [\ {\ "name": String,\ "type": int (Variant::Type),\ "class_name": String,\ "default_value": Variant\ },\ ...\ ] } ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) **paste\_graph\_with\_pre\_generated\_ids**( [VoxelGraphFunction](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/) graph, [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html) node\_ids, [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) gui\_offset )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#void-paste_graph_with_pre_generated_ids-voxelgraphfunction-graph-packedint32array-node_ids-vector2-gui_offset "Permanent link") Copies nodes into another graph, and connections between them only. Resources in node parameters will be duplicated if they don't have a file path. If `node_ids` is provided with non-zero size, defines the IDs copied nodes will have in the destination graph, in the same order as [get\_node\_ids](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_get_node_ids) from the source graph. The array must have the same size as the number of copied nodes and IDs must not already exist in the destination graph. If the array is empty, they will be generated instead. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) **remove\_connection**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) src\_node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) src\_port\_index, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) dst\_node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) dst\_port\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#void-remove_connection-int-src_node_id-int-src_port_index-int-dst_node_id-int-dst_port_index "Permanent link") Removes an existing connection between two nodes of the graph. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) **remove\_node**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#void-remove_node-int-node_id "Permanent link") Removes a node from the graph. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) **set\_expression\_node\_inputs**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id, [PackedStringArray](https://docs.godotengine.org/en/stable/classes/class_packedstringarray.html) names )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#void-set_expression_node_inputs-int-node_id-packedstringarray-names "Permanent link") Configures inputs for an Expression node. `names` is the list of input names used in the expression. If you create an Expression node from code, you should call this method afterwards. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) **set\_node\_default\_input**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) input\_index, [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) value )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#void-set_node_default_input-int-node_id-int-input_index-variant-value "Permanent link") Sets the value an input of a node will have when it is left unconnected. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) **set\_node\_default\_input\_by\_name**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id, [String](https://docs.godotengine.org/en/stable/classes/class_string.html) input\_name, [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) value )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#void-set_node_default_input_by_name-int-node_id-string-input_name-variant-value "Permanent link") Sets the value an input of a node will have when it is left unconnected. The input is specified by its name as seen in the editor. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) **set\_node\_default\_inputs\_autoconnect**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) enabled )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#void-set_node_default_inputs_autoconnect-int-node_id-bool-enabled "Permanent link") Sets wether a node input with no inbound connection will automatically create a default connection when the graph is compiled. This is only available on specific nodes (for example, 2D or 3D noise defaults to XYZ inputs). On other nodes, it has no effect. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) **set\_node\_gui\_position**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id, [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) position )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#void-set_node_gui_position-int-node_id-vector2-position "Permanent link") Sets the visual position of a node of the graph, as it will appear in the editor. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) **set\_node\_gui\_size**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id, [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) size )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#void-set_node_gui_size-int-node_id-vector2-size "Permanent link") Sets the visual size of a node of the graph, as it will appear in the editor. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) **set\_node\_name**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id, [StringName](https://docs.godotengine.org/en/stable/classes/class_stringname.html) name )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#void-set_node_name-int-node_id-stringname-name "Permanent link") Sets a custom name for a node. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) **set\_node\_param**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) param\_index, [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) value )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#void-set_node_param-int-node_id-int-param_index-variant-value "Permanent link") Set a parameter of a node. The parameter index corresponds to the position that parameter comes in when seen in the editor. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) **set\_node\_param\_by\_name**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id, [String](https://docs.godotengine.org/en/stable/classes/class_string.html) param\_name, [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) value )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#void-set_node_param_by_name-int-node_id-string-param_name-variant-value "Permanent link") Set a parameter of a node, using its name as it appears in the editor. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#) **set\_node\_param\_null**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) node\_id, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) param\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#void-set_node_param_null-int-node_id-int-param_index "Permanent link") Set a parameter of a node to null. This method only exists to workaround an issue with Godot's UndoRedo system. Prefer using [set\_node\_param](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGraphFunction/#i_set_node_param) . _Generated on Aug 20, 2026_ --- # VoxelLodTerrain - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelLodTerrain * * * VoxelLodTerrain[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#voxellodterrain "Permanent link") ======================================================================================================================= Inherits: [VoxelNode](https://voxel-tools.readthedocs.io/en/latest/api/VoxelNode/) Voxel volume using variable level of detail. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#description "Permanent link") ---------------------------------------------------------------------------------------------------------------- Renders large terrain using variable level of details. This is preferably used with smooth meshing such as [VoxelMesherTransvoxel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/) . Blocky meshers can be used, but currently don't have as much support for LOD. Properties:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#properties "Permanent link") -------------------------------------------------------------------------------------------------------------- | Type | Name | Default | | --- | --- | --- | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [cache\_generated\_blocks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_cache_generated_blocks) | false | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [collision\_layer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_collision_layer) | 1 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [collision\_lod\_count](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_collision_lod_count) | 0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [collision\_margin](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_collision_margin) | 0.04 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [collision\_mask](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_collision_mask) | 1 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [collision\_update\_delay](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_collision_update_delay) | 0 | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_active\_mesh\_blocks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_draw_active_mesh_blocks) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_active\_visual\_and\_collision\_blocks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_draw_active_visual_and_collision_blocks) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_edit\_boxes](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_draw_edit_boxes) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_edited\_blocks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_draw_edited_blocks) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_draw_enabled) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_loaded\_visual\_and\_collision\_blocks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_draw_loaded_visual_and_collision_blocks) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_mesh\_updates](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_draw_mesh_updates) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_modifier\_bounds](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_draw_modifier_bounds) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_octree\_bounds](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_draw_octree_bounds) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_octree\_nodes](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_draw_octree_nodes) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_shadow\_occluders](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_draw_shadow_occluders) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_viewer\_clipboxes](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_draw_viewer_clipboxes) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_volume\_bounds](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_draw_volume_bounds) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_draw\_voxel\_metadata](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_draw_voxel_metadata) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [full\_load\_mode\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_full_load_mode_enabled) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [generate\_collisions](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_generate_collisions) | true | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [lod\_count](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_lod_count) | 4 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [lod\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_lod_distance) | 48.0 | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [lod\_fade\_duration](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_lod_fade_duration) | 0.0 | | [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) | [material](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_material) | | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [mesh\_block\_size](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_mesh_block_size) | 16 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [normalmap\_begin\_lod\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_normalmap_begin_lod_index) | 2 | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [normalmap\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_normalmap_enabled) | false | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [normalmap\_max\_deviation\_degrees](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_normalmap_max_deviation_degrees) | 60 | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [normalmap\_octahedral\_encoding\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_normalmap_octahedral_encoding_enabled) | false | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [normalmap\_tile\_resolution\_max](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_normalmap_tile_resolution_max) | 8 | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [normalmap\_tile\_resolution\_min](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_normalmap_tile_resolution_min) | 4 | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [normalmap\_use\_gpu](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_normalmap_use_gpu) | false | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [secondary\_lod\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_secondary_lod_distance) | 48.0 | | [StreamingSystem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#enumerations) | [streaming\_system](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_streaming_system) | STREAMING\_SYSTEM\_LEGACY\_OCTREE (0) | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [threaded\_update\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_threaded_update_enabled) | false | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [use\_gpu\_generation](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_use_gpu_generation) | false | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [view\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_view_distance) | 512 | | [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) | [voxel\_bounds](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_voxel_bounds) | AABB(-536870900, -536870900, -536870900, 1073741800, 1073741800, 1073741800) | Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#methods "Permanent link") -------------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [debug\_dump\_as\_scene](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_dump_as_scene)
( [String](https://docs.godotengine.org/en/stable/classes/class_string.html)
path, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
include\_instancer ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [debug\_get\_data\_block\_count](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_get_data_block_count)
( ) const | | [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) | [debug\_get\_data\_block\_info](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_get_data_block_info)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
block\_pos, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
lod ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [debug\_get\_draw\_flag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_get_draw_flag)
( [DebugDrawFlag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#enumerations)
flag\_index ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [debug\_get\_mesh\_block\_count](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_get_mesh_block_count)
( ) const | | [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) | [debug\_get\_mesh\_block\_info](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_get_mesh_block_info)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
block\_pos, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
lod ) const | | [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) | [debug\_get\_octrees\_detailed](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_get_octrees_detailed)
( ) const | | [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) | [debug\_print\_sdf\_top\_down](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_print_sdf_top_down)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
center, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
extents ) | | [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) | [debug\_raycast\_mesh\_block](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_raycast_mesh_block)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
origin, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
dir ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#) | [debug\_set\_draw\_flag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_debug_set_draw_flag)
( [DebugDrawFlag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#enumerations)
flag\_index, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html)
enabled ) | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_data\_block\_region\_extent](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_get_data_block_region_extent)
( ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_data\_block\_size](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_get_data_block_size)
( ) const | | [VoxelGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/) | [get\_normalmap\_generator\_override](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_get_normalmap_generator_override)
( ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_normalmap\_generator\_override\_begin\_lod\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_get_normalmap_generator_override_begin_lod_index)
( ) const | | [ProcessCallback](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#enumerations) | [get\_process\_callback](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_get_process_callback)
( ) const | | [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) | [get\_statistics](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_get_statistics)
( ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [is\_area\_meshed](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_is_area_meshed)
( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html)
area\_in\_voxels, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
lod\_index ) const | | [VoxelSaveCompletionTracker](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/) | [save\_modified\_blocks](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_save_modified_blocks)
( ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#) | [set\_normalmap\_generator\_override](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_set_normalmap_generator_override)
( [VoxelGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/)
generator\_override ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#) | [set\_normalmap\_generator\_override\_begin\_lod\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_set_normalmap_generator_override_begin_lod_index)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
lod\_index ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#) | [set\_process\_callback](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_set_process_callback)
( [ProcessCallback](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#enumerations)
mode ) | | [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) | [voxel\_to\_data\_block\_position](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_voxel_to_data_block_position)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
voxel\_position, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
lod\_index ) const | | [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) | [voxel\_to\_mesh\_block\_position](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_voxel_to_mesh_block_position)
( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html)
voxel\_position, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
lod\_index ) const | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#enumerations "Permanent link") ------------------------------------------------------------------------------------------------------------------ enum **ProcessCallback**: * **PROCESS\_CALLBACK\_IDLE** = **0** --- The node will use `_process` for the part of its logic running on the main thread. * **PROCESS\_CALLBACK\_PHYSICS** = **1** --- The node will use `_physics_process` for the part of its logic running on the main thread. * **PROCESS\_CALLBACK\_DISABLED** = **2** --- The node will not update. Use with caution! enum **DebugDrawFlag**: * **DEBUG\_DRAW\_OCTREE\_NODES** = **0** * **DEBUG\_DRAW\_OCTREE\_BOUNDS** = **1** * **DEBUG\_DRAW\_MESH\_UPDATES** = **2** * **DEBUG\_DRAW\_EDIT\_BOXES** = **3** * **DEBUG\_DRAW\_VOLUME\_BOUNDS** = **4** * **DEBUG\_DRAW\_EDITED\_BLOCKS** = **5** * **DEBUG\_DRAW\_MODIFIER\_BOUNDS** = **6** * **DEBUG\_DRAW\_ACTIVE\_MESH\_BLOCKS** = **7** * **DEBUG\_DRAW\_VIEWER\_CLIPBOXES** = **8** * **DEBUG\_DRAW\_LOADED\_VISUAL\_AND\_COLLISION\_BLOCKS** = **9** * **DEBUG\_DRAW\_ACTIVE\_VISUAL\_AND\_COLLISION\_BLOCKS** = **10** * **DEBUG\_DRAW\_FLAGS\_COUNT** = **12** enum **StreamingSystem**: * **STREAMING\_SYSTEM\_LEGACY\_OCTREE** = **0** --- Loads chunks around the viewer in a spherical pattern. Does not support multiple viewers. Does not support collision-only viewers. Does not support "no viewers" (will assume origin instead). Does not support per-viewer view distance, only [view\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_view_distance) is used. This was the first system to be implemented, therefore it remains available as default for compatibility. * **STREAMING\_SYSTEM\_CLIPBOX** = **1** --- Loads chunks around the viewer in concentric boxes. Supports multiple viewers and collision-only viewers. This is a better system for multiplayer streaming. Due to simplifications, chunk locations at each LOD might be less optimal than [STREAMING\_SYSTEM\_LEGACY\_OCTREE](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_STREAMING_SYSTEM_LEGACY_OCTREE) . Property Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#property-descriptions "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------- ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **cache\_generated\_blocks** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-cache_generated_blocks-false "Permanent link") If enabled, streaming the terrain will keep generated voxel data in memory around viewers, even if it wasn't edited. This can speedup voxel queries on non-edited areas and allows [VoxelStream.save\_generator\_output](https://voxel-tools.readthedocs.io/en/latest/api/VoxelStream/#i_save_generator_output) to work, but increases memory usage significantly. This option is not supported when [full\_load\_mode\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_full_load_mode_enabled) is enabled. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **collision\_layer** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-collision_layer-1 "Permanent link") Collision layer used by generated colliders. Check Godot documentation for more information. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **collision\_lod\_count** = 0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-collision_lod_count-0 "Permanent link") How many LOD levels are set to generate colliders, starting from LOD 0. Setting this property to 0 means all LODs have collision. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **collision\_margin** = 0.04[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#float-collision_margin-004 "Permanent link") Collision margin used by generated colliders. Note that it may depend on which physics engine is used under the hood, as some don't use margins. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **collision\_mask** = 1[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-collision_mask-1 "Permanent link") Collision mask used by generated colliders. Check Godot documentation for more information. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **collision\_update\_delay** = 0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-collision_update_delay-0 "Permanent link") How long to wait before updating colliders after an edit, in milliseconds. Collider generation is expensive, so the intent is to smooth it out. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_active\_mesh\_blocks** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-debug_draw_active_mesh_blocks-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_active\_visual\_and\_collision\_blocks** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-debug_draw_active_visual_and_collision_blocks-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_edit\_boxes** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-debug_draw_edit_boxes-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_edited\_blocks** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-debug_draw_edited_blocks-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-debug_draw_enabled-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_loaded\_visual\_and\_collision\_blocks** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-debug_draw_loaded_visual_and_collision_blocks-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_mesh\_updates** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-debug_draw_mesh_updates-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_modifier\_bounds** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-debug_draw_modifier_bounds-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_octree\_bounds** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-debug_draw_octree_bounds-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_octree\_nodes** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-debug_draw_octree_nodes-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_shadow\_occluders** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-debug_draw_shadow_occluders-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_viewer\_clipboxes** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-debug_draw_viewer_clipboxes-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_volume\_bounds** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-debug_draw_volume_bounds-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_draw\_voxel\_metadata** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-debug_draw_voxel_metadata-false "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **full\_load\_mode\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-full_load_mode_enabled-false "Permanent link") If enabled, data streaming will be turned off, and all voxel data will be loaded from the [stream](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_stream) into memory. This removes several constraints, such as being able to edit anywhere and allowing distant normalmaps to include edited regions. This comes at the expense of more memory usage. However, only edited regions use memory, so in practice it can be good enough. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **generate\_collisions** = true[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-generate_collisions-true "Permanent link") If enabled, chunked colliders will be generated from meshes. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **lod\_count** = 4[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-lod_count-4 "Permanent link") How many LOD levels to use. This should be tuned alongside [lod\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_lod_distance) : if you want to see very far, you need more LOD levels. This allows blocks to become larger the further away they are, to keep their numbers to an acceptable amount. In contrast, too few LOD levels means regions far away will have to use too many small blocks, which can affect performance. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **lod\_distance** = 48.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#float-lod_distance-480 "Permanent link") How far LOD 0 extends from the viewer. Each parent LOD will extend twice as far as their children LOD levels. When [full\_load\_mode\_enabled](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_full_load_mode_enabled) is disabled, this also defines how far edits are allowed. For further control of LODs beyond 0, see [secondary\_lod\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_secondary_lod_distance) . ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **lod\_fade\_duration** = 0.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#float-lod_fade_duration-00 "Permanent link") When set greater than 0, enables LOD fading. When mesh blocks get split/merged as level of detail changes, they will fade to make the transition less noticeable (or at least more pleasant). This feature requires to use a specific shader, check the online documentation or examples for more information. ### [Material](https://docs.godotengine.org/en/stable/classes/class_material.html) **material**[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#material-material "Permanent link") Material used for the surface of the volume. The main usage of this node is with smooth voxels, which means if you want more than one "material" on the ground, you need to use splatmapping techniques with a shader. In addition, many features require shaders to work properly. Check the online documentation or examples for more information. Note: if you use a [ShaderMaterial](https://docs.godotengine.org/en/stable/classes/class_shadermaterial.html) , it will be instanced on every chunk in order to support per-chunk/LOD features, so dynamic changes done to parameters will not apply. You can use [global uniforms](https://docs.godotengine.org/en/stable/tutorials/shaders/shader_reference/shading_language.html#global-uniforms) to workaround this limitation. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **mesh\_block\_size** = 16[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-mesh_block_size-16 "Permanent link") Sets how many voxels across meshes of the terrain span. Voxel chunks are stored in cubic chunks of 16x16x16 voxels, and by default meshes of the terrain match that size. But you can set this to 32 so meshes will span 2x2x2 voxel chunks. This is a performance tradeoff. Higher mesh size may speed up rendering, at the cost of slower mesh updates. Values other than 16 and 32 are not supported. Note: this setting also affects [VoxelInstancer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelInstancer/) chunks. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **normalmap\_begin\_lod\_index** = 2[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-normalmap_begin_lod_index-2 "Permanent link") From which LOD index normalmaps will be generated. There won't be normalmaps below this index. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **normalmap\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-normalmap_enabled-false "Permanent link") Enables generation of distant normalmaps. This is a feature used with smooth terrain only (SDF). It is an expensive feature but allows to bring a lot more detail to distant ground. This feature requires to use a specific shader, check the online documentation or examples for more information. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **normalmap\_max\_deviation\_degrees** = 60[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-normalmap_max_deviation_degrees-60 "Permanent link") _(This property has no documentation)_ ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **normalmap\_octahedral\_encoding\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-normalmap_octahedral_encoding_enabled-false "Permanent link") Enables octahedral compression of normalmaps, which reduces memory usage caused by distant normalmaps by about 33%, with some impact on visual quality. Your shader may be modified accordingly to decode them. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **normalmap\_tile\_resolution\_max** = 8[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-normalmap_tile_resolution_max-8 "Permanent link") Maximum resolution of tiles in distant normalmaps. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **normalmap\_tile\_resolution\_min** = 4[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-normalmap_tile_resolution_min-4 "Permanent link") Minimum resolution of tiles in distant normalmaps. This is the resolution at which normalmaps will begin with, at the LOD level defined in [normalmap\_begin\_lod\_index](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_normalmap_begin_lod_index) . Resolutions will double at each LOD level, until they reach [normalmap\_tile\_resolution\_max](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_normalmap_tile_resolution_max) . ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **normalmap\_use\_gpu** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-normalmap_use_gpu-false "Permanent link") Enables GPU detail normalmaps generation, which can speed it up. This is only valid for generators that support it. Vulkan is required. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **secondary\_lod\_distance** = 48.0[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#float-secondary_lod_distance-480 "Permanent link") Controls the size of each LOD above LOD 0, in voxels relative to those LODs (voxels of LOD N are twice as big than LOD N-1). Higher values allow to see further away before detail are decimated, but is more expensive. Note that it will not necessarily be respected accurately, and will rather be used as a target minimum distance. This is only used when [streaming\_system](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_streaming_system) is set to [STREAMING\_SYSTEM\_CLIPBOX](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_STREAMING_SYSTEM_CLIPBOX) . In other cases, [lod\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_lod_distance) is used. To control LOD 0, see [lod\_distance](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#i_lod_distance) . ### [StreamingSystem](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#enumerations) **streaming\_system** = STREAMING\_SYSTEM\_LEGACY\_OCTREE (0)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#streamingsystem-streaming_system-streaming_system_legacy_octree-0 "Permanent link") Selects the underlying algorithm used to determine when to load and unload chunks around viewers as they move around. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **threaded\_update\_enabled** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-threaded_update_enabled-false "Permanent link") When enabled, this node will run a large part of its update cycle in a separate thread. Otherwise, it will run on the main thread. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **use\_gpu\_generation** = false[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-use_gpu_generation-false "Permanent link") Enables GPU block generation, which can speed it up. This is only valid for generators that support it. Vulkan is required. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **view\_distance** = 512[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-view_distance-512 "Permanent link") Maximum distance viewers can have. If a viewer has a larger distance, it will be clamped. Note that this is only a hint and not an exact boundary. Terrain may load within that distance, but can continue beyond it, rounding up to block size of the biggest LOD. If your terrain size is finite (like an island or planet) and you want to keep it in view, you may want to set this value to a very large number. This is mainly useful for infinite terrains where a cap is desired. ### [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) **voxel\_bounds** = AABB(-536870900, -536870900, -536870900, 1073741800, 1073741800, 1073741800)[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#aabb-voxel_bounds-aabb-536870900-536870900-536870900-1073741800-1073741800-1073741800 "Permanent link") Bounds within which volume data can exist (loaded or not), in voxels. By default, it is pseudo-infinite. If you make a planet, island or some sort of arena, you may want to choose a finite size. Note, because this volume uses chunks with LOD, these bounds will snap to the closest chunk boundary. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#method-descriptions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **debug\_dump\_as\_scene**( [String](https://docs.godotengine.org/en/stable/classes/class_string.html) path, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) include\_instancer )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-debug_dump_as_scene-string-path-bool-include_instancer "Permanent link") Saves the current state of the terrain as a Godot scene file. Can be used to inspect meshes and instances in more detail in the editor. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **debug\_get\_data\_block\_count**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-debug_get_data_block_count "Permanent link") Get how many voxel data chunks are currently loaded ### [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) **debug\_get\_data\_block\_info**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) block\_pos, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) lod )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#dictionary-debug_get_data_block_info-vector3-block_pos-int-lod "Permanent link") Gets some debug information about a specific voxel data chunk. { "loading_state": int, } ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **debug\_get\_draw\_flag**( [DebugDrawFlag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#enumerations) flag\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-debug_get_draw_flag-debugdrawflag-flag_index "Permanent link") Gets whether a specific debug drawing flag is enabled. This method always returns false in exported games. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **debug\_get\_mesh\_block\_count**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-debug_get_mesh_block_count "Permanent link") Gets how many meshes the terrain currently has. ### [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) **debug\_get\_mesh\_block\_info**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) block\_pos, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) lod )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#dictionary-debug_get_mesh_block_info-vector3-block_pos-int-lod "Permanent link") Gets some debug information about a specific mesh. { "transition_mask": int, "recomputed_transition_mask": int, "loaded": bool, "meshed": bool, "mesh_state": int, "visible": bool, "visual_active": bool, "collision_active": bool } ### [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) **debug\_get\_octrees\_detailed**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#array-debug_get_octrees_detailed "Permanent link") Gets debug information about the grid of octrees used to stream the terrain at multiple levels of detail. The returned array contains alternating [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) and [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) values, where each pair corresponds to one octree at a specific position: [\ Vector3i,\ Array,\ Vector3i,\ Array,\ ...\ ] The array after positions contains info about one octree: [\ int (node state),\ null or Array (children info)\ ] When children info is not null, it contains 8 arrays structured the same way, and may be recursively traversed to obtain the state of every node of the octree. ### [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) **debug\_print\_sdf\_top\_down**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) center, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) extents )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#array-debug_print_sdf_top_down-vector3i-center-vector3i-extents "Permanent link") Captures a top-down representation of the signed distance field (SDF) at multiple LOD levels within a specific area. The returned array contains an image for each LOD. ### [Array](https://docs.godotengine.org/en/stable/classes/class_array.html) **debug\_raycast\_mesh\_block**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) origin, [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) dir )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#array-debug_raycast_mesh_block-vector3-origin-vector3-dir "Permanent link") Gets the non-empty mesh chunk positions from a rough world-space ray, up to a distance of 256 units. All LODs are checked. The returned array contains: [\ {\ "position": Vector3i,\ "lod": int\ },\ ...\ ] ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#) **debug\_set\_draw\_flag**( [DebugDrawFlag](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#enumerations) flag\_index, [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) enabled )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#void-debug_set_draw_flag-debugdrawflag-flag_index-bool-enabled "Permanent link") Sets a specific debug drawing flag. Note that debug drawing must also be enabled for it to be visible. This method does nothing in exported games. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_data\_block\_region\_extent**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-get_data_block_region_extent "Permanent link") _(This method has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_data\_block\_size**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-get_data_block_size "Permanent link") Gets the size of one cunic data block in voxels. ### [VoxelGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/) **get\_normalmap\_generator\_override**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#voxelgenerator-get_normalmap_generator_override "Permanent link") _(This method has no documentation)_ ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_normalmap\_generator\_override\_begin\_lod\_index**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#int-get_normalmap_generator_override_begin_lod_index "Permanent link") _(This method has no documentation)_ ### [ProcessCallback](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#enumerations) **get\_process\_callback**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#processcallback-get_process_callback "Permanent link") Gets which callback is used to run the main thread update of this node. ### [Dictionary](https://docs.godotengine.org/en/stable/classes/class_dictionary.html) **get\_statistics**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#dictionary-get_statistics "Permanent link") Gets debug information about how much time is spent processing the terrain. The returned dictionary has the following structure: { "time_detect_required_blocks": int, "time_request_blocks_to_load": int, "time_process_load_responses": int, "time_request_blocks_to_update": int, "time_process_update_responses": int, "remaining_main_thread_blocks": int, "dropped_block_loads": int, "dropped_block_meshs": int, "updated_blocks": int, "blocked_lods": int } Times are in microseconds. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **is\_area\_meshed**( [AABB](https://docs.godotengine.org/en/stable/classes/class_aabb.html) area\_in\_voxels, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) lod\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#bool-is_area_meshed-aabb-area_in_voxels-int-lod_index "Permanent link") Returns true if the area has been processed by meshing. It does not mean the area actually contains a mesh. Returns false if the area has not been processed by meshing (therefore it is unknown whethere there should be a mesh here or not). When streaming terrain, this can be used to determine if an area has fully "loaded", in case the game relies meshes or mesh colliders. ### [VoxelSaveCompletionTracker](https://voxel-tools.readthedocs.io/en/latest/api/VoxelSaveCompletionTracker/) **save\_modified\_blocks**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#voxelsavecompletiontracker-save_modified_blocks "Permanent link") Requests saving of all modified voxels. Saving is asynchronous and will complete some time in the future. If the game quits, the engine will ensure saving tasks get completed before the application shuts down. Use the returned tracker object to know when saving has completed. However, saves occurring after calling this method won't be tracked by this object. Note that blocks getting unloaded as the viewer moves around can also trigger saving tasks, independently from this function. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#) **set\_normalmap\_generator\_override**( [VoxelGenerator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelGenerator/) generator\_override )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#void-set_normalmap_generator_override-voxelgenerator-generator_override "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#) **set\_normalmap\_generator\_override\_begin\_lod\_index**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) lod\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#void-set_normalmap_generator_override_begin_lod_index-int-lod_index "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#) **set\_process\_callback**( [ProcessCallback](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#enumerations) mode )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#void-set_process_callback-processcallback-mode "Permanent link") Sets which process callback is used to run the main thread update of this node. By default, it uses `_process`. ### [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) **voxel\_to\_data\_block\_position**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) voxel\_position, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) lod\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#vector3i-voxel_to_data_block_position-vector3-voxel_position-int-lod_index "Permanent link") Converts a voxel position into a data block position for a specific LOD index. ### [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) **voxel\_to\_mesh\_block\_position**( [Vector3](https://docs.godotengine.org/en/stable/classes/class_vector3.html) voxel\_position, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) lod\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelLodTerrain/#vector3i-voxel_to_mesh_block_position-vector3-voxel_position-int-lod_index "Permanent link") Converts a voxel position into a mesh block position for a specific LOD index. _Generated on Aug 20, 2026_ --- # VoxelBuffer - Voxel Tools documentation * [](https://voxel-tools.readthedocs.io/en/latest/) * Scripting API * VoxelBuffer * * * VoxelBuffer[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#voxelbuffer "Permanent link") =========================================================================================================== Inherits: [RefCounted](https://docs.godotengine.org/en/stable/classes/class_refcounted.html) 3D grid storing voxel data. Description:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#description "Permanent link") ------------------------------------------------------------------------------------------------------------ This contains dense voxels data storage (every single cell holds data, there is no sparse optimization of space). Works like a normal 3D grid containing a voxel value in each cell. Organized in channels of configurable bit depth. Values can be interpreted either as unsigned integers, fixed-point or floats. See [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) for more information. Arbitrary metadata can also be stored, either for the whole buffer, or per-voxel, at higher cost. This metadata can get saved and loaded along voxels, however you must make sure the data is serializable (i.e it should not contain nodes or arbitrary objects). Methods:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#methods "Permanent link") ---------------------------------------------------------------------------------------------------- | Return | Signature | | --- | --- | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [clear](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_clear)
( ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [clear\_voxel\_metadata](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_clear_voxel_metadata)
( ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [clear\_voxel\_metadata\_in\_area](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_clear_voxel_metadata_in_area)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
min\_pos, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
max\_pos ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [compress\_uniform\_channels](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_compress_uniform_channels)
( ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [copy\_channel\_from](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_copy_channel_from)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
other, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [copy\_channel\_from\_area](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_copy_channel_from_area)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
other, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
src\_min, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
src\_max, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
dst\_min, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [copy\_voxel\_metadata\_in\_area](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_copy_voxel_metadata_in_area)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
src\_buffer, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
src\_min\_pos, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
src\_max\_pos, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
dst\_min\_pos ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [create](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_create)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
sx, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
sy, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
sz ) | | [ImageTexture3D](https://docs.godotengine.org/en/stable/classes/class_imagetexture3d.html) | [create\_3d\_texture\_from\_sdf\_zxy](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_create_3d_texture_from_sdf_zxy)
( [Format](https://docs.godotengine.org/en/stable/classes/class_image.html#enum-image-format)
output\_format ) const | | [Image\[\]](https://docs.godotengine.org/en/stable/classes/class_image[].html) | [debug\_print\_sdf\_y\_slices](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_debug_print_sdf_y_slices)
( [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
scale=1.0 ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [decompress\_channel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_decompress_channel)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [downscale\_to](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_downscale_to)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
dst, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
src\_min, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
src\_max, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
dst\_min ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [fill](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_fill)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
value, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel=0 ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [fill\_area](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_fill_area)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
value, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
min, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
max, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel=0 ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [fill\_area\_f](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_fill_area_f)
( [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
value, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
min, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
max, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [fill\_f](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_fill_f)
( [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
value, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel=0 ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [for\_each\_voxel\_metadata](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_for_each_voxel_metadata)
( [Callable](https://docs.godotengine.org/en/stable/classes/class_callable.html)
callback ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [for\_each\_voxel\_metadata\_in\_area](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_for_each_voxel_metadata_in_area)
( [Callable](https://docs.godotengine.org/en/stable/classes/class_callable.html)
callback, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
min\_pos, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
max\_pos ) | | [Allocator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) | [get\_allocator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_get_allocator)
( ) const | | [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) | [get\_block\_metadata](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_get_block_metadata)
( ) const | | [PackedByteArray](https://docs.godotengine.org/en/stable/classes/class_packedbytearray.html) | [get\_channel\_as\_byte\_array](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_get_channel_as_byte_array)
( [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations)
channel\_index ) const | | [Compression](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) | [get\_channel\_compression](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_get_channel_compression)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel ) const | | [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) | [get\_channel\_depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_get_channel_depth)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel ) const | | [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) | [get\_size](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_get_size)
( ) const | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_voxel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_get_voxel)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
x, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
y, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
z, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel=0 ) const | | [float](https://docs.godotengine.org/en/stable/classes/class_float.html) | [get\_voxel\_f](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_get_voxel_f)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
x, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
y, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
z, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel=0 ) const | | [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) | [get\_voxel\_metadata](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_get_voxel_metadata)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
pos ) const | | [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) | [get\_voxel\_tool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_get_voxel_tool)
( ) | | [int](https://docs.godotengine.org/en/stable/classes/class_int.html) | [get\_voxel\_v](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_get_voxel_v)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
pos, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel=0 ) const | | [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) | [is\_uniform](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_is_uniform)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel ) const | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [mirror](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_mirror)
( [Axis](https://docs.godotengine.org/en/stable/classes/class_vector3i.html#enum-vector3i-axis)
axis ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [op\_add\_buffer\_f](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_op_add_buffer_f)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
other, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations)
channel ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [op\_max\_buffer\_f](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_op_max_buffer_f)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
other, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations)
channel ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [op\_min\_buffer\_f](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_op_min_buffer_f)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
other, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations)
channel ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [op\_mul\_buffer\_f](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_op_mul_buffer_f)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
other, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations)
channel ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [op\_mul\_value\_f](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_op_mul_value_f)
( [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
other, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations)
channel ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [op\_select\_less\_src\_f\_dst\_i\_values](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_op_select_less_src_f_dst_i_values)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
src, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations)
src\_channel, [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
threshold, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
value\_if\_less, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
value\_if\_more, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations)
dst\_channel ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [op\_sub\_buffer\_f](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_op_sub_buffer_f)
( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/)
other, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations)
channel ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [remap\_values](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_remap_values)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel, [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html)
map ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [rotate\_90](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_rotate_90)
( [Axis](https://docs.godotengine.org/en/stable/classes/class_vector3i.html#enum-vector3i-axis)
axis, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
turns ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [set\_block\_metadata](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_set_block_metadata)
( [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html)
meta ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [set\_channel\_depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_set_channel_depth)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel, [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations)
depth ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [set\_channel\_from\_byte\_array](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_set_channel_from_byte_array)
( [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations)
channel\_index, [PackedByteArray](https://docs.godotengine.org/en/stable/classes/class_packedbytearray.html)
data ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [set\_voxel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_set_voxel)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
value, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
x, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
y, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
z, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel=0 ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [set\_voxel\_f](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_set_voxel_f)
( [float](https://docs.godotengine.org/en/stable/classes/class_float.html)
value, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
x, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
y, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
z, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel=0 ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [set\_voxel\_metadata](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_set_voxel_metadata)
( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
pos, [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html)
value ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [set\_voxel\_v](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_set_voxel_v)
( [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
value, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html)
pos, [int](https://docs.godotengine.org/en/stable/classes/class_int.html)
channel=0 ) | | [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) | [update\_3d\_texture\_from\_sdf\_zxy](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_update_3d_texture_from_sdf_zxy)
( [ImageTexture3D](https://docs.godotengine.org/en/stable/classes/class_imagetexture3d.html)
existing\_texture ) const | Enumerations:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations "Permanent link") -------------------------------------------------------------------------------------------------------------- enum **ChannelId**: * **CHANNEL\_TYPE** = **0** --- Channel used to store voxel types. Used by [VoxelMesherBlocky](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherBlocky/) . * **CHANNEL\_SDF** = **1** --- Channel used to store SDF data (signed distance field). Used by [VoxelMesherTransvoxel](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherTransvoxel/) and other smooth meshers. Values should preferably be accessed as floats. Negative values are below the isosurface (inside matter), and positive values are above the surface (outside matter). * **CHANNEL\_COLOR** = **2** --- Channel used to store color data. Used by [VoxelMesherCubes](https://voxel-tools.readthedocs.io/en/latest/api/VoxelMesherCubes/) . * **CHANNEL\_INDICES** = **3** --- Channel used to store material indices. Used with smooth voxels. * **CHANNEL\_WEIGHTS** = **4** --- Channel used to store material weights, when more than one index can be stored per voxel. Used with smooth voxels. * **CHANNEL\_DATA5** = **5** --- Free channel. Not used by the engine yet. * **CHANNEL\_DATA6** = **6** --- Free channel. Not used by the engine yet. * **CHANNEL\_DATA7** = **7** --- Free channel. Not used by the engine yet. * **MAX\_CHANNELS** = **8** --- Maximum number of channels a [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) can have. enum **ChannelMask**: * **CHANNEL\_TYPE\_BIT** = **1** --- Bitmask with one bit set at the position corresponding to [CHANNEL\_TYPE](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_TYPE) . * **CHANNEL\_SDF\_BIT** = **2** --- Bitmask with one bit set at the position corresponding to [CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) . * **CHANNEL\_COLOR\_BIT** = **4** --- Bitmask with one bit set at the position corresponding to [CHANNEL\_COLOR](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_COLOR) . * **CHANNEL\_INDICES\_BIT** = **8** --- Bitmask with one bit set at the position corresponding to [CHANNEL\_INDICES](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_INDICES) . * **CHANNEL\_WEIGHTS\_BIT** = **16** --- Bitmask with one bit set at the position corresponding to [CHANNEL\_WEIGHTS](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_WEIGHTS) . * **CHANNEL\_DATA5\_BIT** = **32** --- Bitmask with one bit set at the position corresponding to [CHANNEL\_DATA5](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_DATA5) . * **CHANNEL\_DATA6\_BIT** = **64** --- Bitmask with one bit set at the position corresponding to [CHANNEL\_DATA6](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_DATA6) . * **CHANNEL\_DATA7\_BIT** = **128** --- Bitmask with one bit set at the position corresponding to [CHANNEL\_DATA7](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_DATA7) . * **ALL\_CHANNELS\_MASK** = **255** --- Bitmask with all channel bits set. enum **Depth**: * **DEPTH\_8\_BIT** = **0** --- Voxels will be stored with 8 bits. Raw values will range from 0 to 255. Float values can take 255 values distributed from -10.0 to 10.0. Values outside the range will be clamped. * **DEPTH\_16\_BIT** = **1** --- Voxels will be stored with 16 bits. Raw values will range from 0 to 65,535. Float values can take 65,535 values distributed from -500.0 to 500.0. Values outside the range will be clamped. * **DEPTH\_32\_BIT** = **2** --- Voxels will be stored with 32 bits. Raw values will range from 0 to 4,294,967,295, and float values will use regular IEEE 754 representation (`float`). * **DEPTH\_64\_BIT** = **3** --- Voxels will be stored with 64 bits. Raw values will range from 0 to 18,446,744,073,709,551,615, and float values will use regular IEEE 754 representation (`double`). * **DEPTH\_COUNT** = **4** --- How many depth configuration there are. enum **Compression**: * **COMPRESSION\_NONE** = **0** --- The channel is not compressed. Every value is stored individually inside an array in memory. * **COMPRESSION\_UNIFORM** = **1** --- All voxels of the channel have the same value, so they are stored as one single value, to save space. * **COMPRESSION\_COUNT** = **2** --- How many compression modes there are. enum **Allocator**: * **ALLOCATOR\_DEFAULT** = **0** --- Uses Godot's default memory allocator (at time of writing, it is `malloc`). Preferred for occasional buffers with uncommon size, or very large size. * **ALLOCATOR\_POOL** = **1** --- Uses a pool allocator. Can be faster than the default allocator buffers are created very frequently with similar size. This memory will remain allocated after use, under the assumption that other buffers will need it soon after. Does not support very large buffers (greater than 2 megabytes) * **ALLOCATOR\_COUNT** = **2** Constants:[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#constants "Permanent link") -------------------------------------------------------------------------------------------------------- * **MAX\_SIZE** = **65535** --- Maximum size a buffer can have when serialized. Buffers that contain uniform-compressed voxels can reach it, but in practice, the limit is much lower and depends on available memory. Method Descriptions[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#method-descriptions "Permanent link") --------------------------------------------------------------------------------------------------------------------------- ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **clear**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-clear "Permanent link") Erases all contents of the buffer and resets its size to zero. Channel depths and default values are preserved. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **clear\_voxel\_metadata**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-clear_voxel_metadata "Permanent link") Erases all per-voxel metadata. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **clear\_voxel\_metadata\_in\_area**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) min\_pos, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) max\_pos )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-clear_voxel_metadata_in_area-vector3i-min_pos-vector3i-max_pos "Permanent link") Erases per-voxel metadata within the specified area. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **compress\_uniform\_channels**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-compress_uniform_channels "Permanent link") Finds channels that have the same value in all their voxels, and reduces memory usage by storing only one value instead. This is effective for example when large parts of the terrain are filled with air. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **copy\_channel\_from**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) other, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-copy_channel_from-voxelbuffer-other-int-channel "Permanent link") Copies all values from the channel of another [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) into the same channel for the current buffer. The depth formats must match. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **copy\_channel\_from\_area**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) other, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) src\_min, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) src\_max, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) dst\_min, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-copy_channel_from_area-voxelbuffer-other-vector3i-src_min-vector3i-src_max-vector3i-dst_min-int-channel "Permanent link") Copies values from a channel's sub-region of another [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) into the same channel for the current buffer, at a specific location. The depth formats must match. If corners of the area represent a negative-size area, they will be sorted back. If coordinates are entirely or partially out of bounds, they will be clipped automatically. Copying across the same buffer to overlapping areas is not supported. You may use an intermediary buffer in this case. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **copy\_voxel\_metadata\_in\_area**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) src\_buffer, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) src\_min\_pos, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) src\_max\_pos, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) dst\_min\_pos )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-copy_voxel_metadata_in_area-voxelbuffer-src_buffer-vector3i-src_min_pos-vector3i-src_max_pos-vector3i-dst_min_pos "Permanent link") Copies per-voxel metadata from a sub-region of another [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) into the the current buffer, at a specific location. Values will be a shallow copy. If corners of the area represent a negative-size area, they will be sorted back. If coordinates are entirely or partially out of bounds, they will be clipped automatically. Copying across the same buffer to overlapping areas is not supported. You may use an intermediary buffer in this case. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **create**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) sx, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) sy, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) sz )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-create-int-sx-int-sy-int-sz "Permanent link") Clears the buffer and gives it the specified size. ### [ImageTexture3D](https://docs.godotengine.org/en/stable/classes/class_imagetexture3d.html) **create\_3d\_texture\_from\_sdf\_zxy**( [Format](https://docs.godotengine.org/en/stable/classes/class_image.html#enum-image-format) output\_format )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#imagetexture3d-create_3d_texture_from_sdf_zxy-format-output_format "Permanent link") Creates a 3D texture from the SDF channel. If `output_format` is a 8-bit pixel format, the texture will contain normalized signed distances, where 0.5 is the isolevel, 0 is the furthest away under surface, and 1 is the furthest away above surface. Only 16-bit SDF channel is supported. Only [Image.FORMAT\_R8](https://docs.godotengine.org/en/stable/classes/class_image.html#class-image-constant-FORMAT-R8) and [Image.FORMAT\_L8](https://docs.godotengine.org/en/stable/classes/class_image.html#class-image-constant-FORMAT-L8) output formats are suported. Note: when sampling this texture in a shader, you need to swizzle 3D coordinates with `.yxz`. This is how voxels are internally stored, and this function does not change this convention. ### [Image\[\]](https://docs.godotengine.org/en/stable/classes/class_image[].html) **debug\_print\_sdf\_y\_slices**( [float](https://docs.godotengine.org/en/stable/classes/class_float.html) scale=1.0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#image-debug_print_sdf_y_slices-float-scale10 "Permanent link") Renders the contents of the SDF channel into images where blue gradients are negative values (below surface) and yellow gradients are positive (above surface). Each image corresponds to an XZ slice of the buffer. The `scale` parameter can be used to change contrast of images by scaling the SDF. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **decompress\_channel**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-decompress_channel-int-channel "Permanent link") If the given channel is currently compressed, decompresses it so that all voxel values are individually stored in full. This will use more memory. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **downscale\_to**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) dst, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) src\_min, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) src\_max, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) dst\_min )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-downscale_to-voxelbuffer-dst-vector3i-src_min-vector3i-src_max-vector3i-dst_min "Permanent link") Produces a downscaled version of this buffer, by a factor of 2, without any form of interpolation (i.e using nearest-neighbor). Metadata is not copied. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **fill**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) value, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel=0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-fill-int-value-int-channel0 "Permanent link") Fills one channel of this buffer with a specific raw value. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **fill\_area**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) value, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) min, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) max, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel=0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-fill_area-int-value-vector3i-min-vector3i-max-int-channel0 "Permanent link") Fills an area of a channel in this buffer with a specific raw value. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **fill\_area\_f**( [float](https://docs.godotengine.org/en/stable/classes/class_float.html) value, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) min, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) max, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-fill_area_f-float-value-vector3i-min-vector3i-max-int-channel "Permanent link") Fills an area of a channel in this buffer with a specific SDF value. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **fill\_f**( [float](https://docs.godotengine.org/en/stable/classes/class_float.html) value, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel=0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-fill_f-float-value-int-channel0 "Permanent link") Fills one channel of this buffer with a specific SDF value. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **for\_each\_voxel\_metadata**( [Callable](https://docs.godotengine.org/en/stable/classes/class_callable.html) callback )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-for_each_voxel_metadata-callable-callback "Permanent link") Executes a function on every voxel in this buffer which have associated metadata. The function's arguments must be (position: Vector3i, metadata: Variant). IMPORTANT: inserting new or removing metadata from inside this function is not allowed. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **for\_each\_voxel\_metadata\_in\_area**( [Callable](https://docs.godotengine.org/en/stable/classes/class_callable.html) callback, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) min\_pos, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) max\_pos )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-for_each_voxel_metadata_in_area-callable-callback-vector3i-min_pos-vector3i-max_pos "Permanent link") Executes a function on every voxel in this buffer which have associated metadata, within the specified area. IMPORTANT: inserting new or removing metadata from inside this function is not allowed. ### [Allocator](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) **get\_allocator**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#allocator-get_allocator "Permanent link") Gets which memory allocator is used by this buffer. ### [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) **get\_block\_metadata**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#variant-get_block_metadata "Permanent link") Gets metadata associated to this [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) . ### [PackedByteArray](https://docs.godotengine.org/en/stable/classes/class_packedbytearray.html) **get\_channel\_as\_byte\_array**( [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) channel\_index )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#packedbytearray-get_channel_as_byte_array-channelid-channel_index "Permanent link") Gets voxel data from a channel as uncompressed raw bytes. Check [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) for information about the data format. Note: if the channel is compressed, it will be decompressed on the fly into the returned array. If you want a different behavior in this case, check [get\_channel\_compression](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_get_channel_compression) before calling this method. ### [Compression](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) **get\_channel\_compression**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#compression-get_channel_compression-int-channel "Permanent link") Gets which compression mode the specified channel has. ### [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) **get\_channel\_depth**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#depth-get_channel_depth-int-channel "Permanent link") Gets which bit depth the specified channel has. ### [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) **get\_size**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#vector3i-get_size "Permanent link") Gets the 3D size of the buffer in voxels. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_voxel**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) x, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) y, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) z, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel=0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#int-get_voxel-int-x-int-y-int-z-int-channel0 "Permanent link") Gets the raw value of a voxel within this buffer. ### [float](https://docs.godotengine.org/en/stable/classes/class_float.html) **get\_voxel\_f**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) x, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) y, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) z, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel=0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#float-get_voxel_f-int-x-int-y-int-z-int-channel0 "Permanent link") Gets the float value of a voxel within this buffer. You may use this function if you work with SDF volumes (smooth voxels). ### [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) **get\_voxel\_metadata**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) pos )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#variant-get_voxel_metadata-vector3i-pos "Permanent link") Gets the metadata attached to a specific voxel in this buffer. ### [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) **get\_voxel\_tool**( )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#voxeltool-get_voxel_tool "Permanent link") Constructs a [VoxelTool](https://voxel-tools.readthedocs.io/en/latest/api/VoxelTool/) instance bound to this buffer. This provides access to some extra common functions. ### [int](https://docs.godotengine.org/en/stable/classes/class_int.html) **get\_voxel\_v**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) pos, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel=0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#int-get_voxel_v-vector3i-pos-int-channel0 "Permanent link") Gets the raw value of a voxel within this buffer. ### [bool](https://docs.godotengine.org/en/stable/classes/class_bool.html) **is\_uniform**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#bool-is_uniform-int-channel "Permanent link") Checks if every voxel within a channel has the same value. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **mirror**( [Axis](https://docs.godotengine.org/en/stable/classes/class_vector3i.html#enum-vector3i-axis) axis )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-mirror-axis-axis "Permanent link") Mirrors voxel values along the specified axis. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **op\_add\_buffer\_f**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) other, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) channel )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-op_add_buffer_f-voxelbuffer-other-channelid-channel "Permanent link") Computes the sum of corresponding voxels between the current buffer and the other buffer, and stores the result in the current buffer. Voxels are interpreted as signed distances (usually the [CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) channel). ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **op\_max\_buffer\_f**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) other, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) channel )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-op_max_buffer_f-voxelbuffer-other-channelid-channel "Permanent link") Computes the maximum of corresponding voxels between the current buffer and the other buffer, and stores the result in the current buffer. Voxels are interpreted as signed distances (usually the [CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) channel). ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **op\_min\_buffer\_f**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) other, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) channel )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-op_min_buffer_f-voxelbuffer-other-channelid-channel "Permanent link") Computes the minimum of corresponding voxels between the current buffer and the other buffer, and stores the result in the current buffer. Voxels are interpreted as signed distances (usually the [CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) channel). ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **op\_mul\_buffer\_f**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) other, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) channel )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-op_mul_buffer_f-voxelbuffer-other-channelid-channel "Permanent link") Computes the multiplication of corresponding voxels between the current buffer and the other buffer, and stores the result in the current buffer. Voxels are interpreted as signed distances (usually the [CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) channel). ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **op\_mul\_value\_f**( [float](https://docs.godotengine.org/en/stable/classes/class_float.html) other, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) channel )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-op_mul_value_f-float-other-channelid-channel "Permanent link") Multiplies every voxels in the buffer by the given value. Voxels are interpreted as signed distances (usually the [CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) channel). ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **op\_select\_less\_src\_f\_dst\_i\_values**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) src, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) src\_channel, [float](https://docs.godotengine.org/en/stable/classes/class_float.html) threshold, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) value\_if\_less, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) value\_if\_more, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) dst\_channel )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-op_select_less_src_f_dst_i_values-voxelbuffer-src-channelid-src_channel-float-threshold-int-value_if_less-int-value_if_more-channelid-dst_channel "Permanent link") For every voxel in the source buffer, if the value is lower than a threshold, set the corresponding voxel in the current buffer to a specific integer value, or another value otherwise. Voxels in the source buffer are interpreted as signed distances (usually the [CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) channel). ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **op\_sub\_buffer\_f**( [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) other, [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) channel )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-op_sub_buffer_f-voxelbuffer-other-channelid-channel "Permanent link") Computes the subtraction of corresponding voxels between the current buffer and the other buffer (`current - other`), and stores the result in the current buffer. Voxels are interpreted as signed distances (usually the [CHANNEL\_SDF](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_CHANNEL_SDF) channel). ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **remap\_values**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel, [PackedInt32Array](https://docs.godotengine.org/en/stable/classes/class_packedint32array.html) map )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-remap_values-int-channel-packedint32array-map "Permanent link") Remaps integer values in a channel using the passed `map` lookup table. Each index in `map` corresponds to an original value, and will be replaced by `map[original]`. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **rotate\_90**( [Axis](https://docs.godotengine.org/en/stable/classes/class_vector3i.html#enum-vector3i-axis) axis, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) turns )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-rotate_90-axis-axis-int-turns "Permanent link") Rotates voxel values by 90 degrees along the specified axis. 1 turn is 90 degrees, 2 turns is 180 degrees, 3 turns is 270 degrees (or -90), 4 turns does nothing. Negative turns go in the other direction. This may also rotate the size of the buffer, if it isn't cubic. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **set\_block\_metadata**( [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) meta )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-set_block_metadata-variant-meta "Permanent link") Sets arbitrary data on this buffer. Old data is replaced. Note, this is separate storage from per-voxel metadata. If this [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) is saved, this metadata will also be saved along voxels, so make sure the data supports serialization (i.e you can't put nodes or arbitrary objects in it). ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **set\_channel\_depth**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel, [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) depth )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-set_channel_depth-int-channel-depth-depth "Permanent link") Changes the bit depth of a given channel. This controls the range of values a channel can hold. See [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) for more information. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **set\_channel\_from\_byte\_array**( [ChannelId](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) channel\_index, [PackedByteArray](https://docs.godotengine.org/en/stable/classes/class_packedbytearray.html) data )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-set_channel_from_byte_array-channelid-channel_index-packedbytearray-data "Permanent link") Overwrites the contents of a channel from raw voxel data. Check [Depth](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#enumerations) for information about the expected data format. ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **set\_voxel**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) value, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) x, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) y, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) z, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel=0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-set_voxel-int-value-int-x-int-y-int-z-int-channel0 "Permanent link") Sets the raw value of a voxel. If you use smooth voxels, you may prefer using [set\_voxel\_f](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_set_voxel_f) . ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **set\_voxel\_f**( [float](https://docs.godotengine.org/en/stable/classes/class_float.html) value, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) x, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) y, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) z, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel=0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-set_voxel_f-float-value-int-x-int-y-int-z-int-channel0 "Permanent link") Sets the float value of a voxel. This method should be used if you work on SDF data (smooth voxels). ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **set\_voxel\_metadata**( [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) pos, [Variant](https://docs.godotengine.org/en/stable/classes/class_variant.html) value )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-set_voxel_metadata-vector3i-pos-variant-value "Permanent link") Attaches arbitrary data on a specific voxel. Old data is replaced. Passing `null` will erase metadata. If this [VoxelBuffer](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/) is saved, this metadata will also be saved along voxels, so make sure the data supports serialization (i.e you can't put nodes or arbitrary objects in it). ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **set\_voxel\_v**( [int](https://docs.godotengine.org/en/stable/classes/class_int.html) value, [Vector3i](https://docs.godotengine.org/en/stable/classes/class_vector3i.html) pos, [int](https://docs.godotengine.org/en/stable/classes/class_int.html) channel=0 )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-set_voxel_v-int-value-vector3i-pos-int-channel0 "Permanent link") _(This method has no documentation)_ ### [void](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#) **update\_3d\_texture\_from\_sdf\_zxy**( [ImageTexture3D](https://docs.godotengine.org/en/stable/classes/class_imagetexture3d.html) existing\_texture )[¶](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#void-update_3d_texture_from_sdf_zxy-imagetexture3d-existing_texture "Permanent link") Updates an existing 3D texture from the SDF channel. See [create\_3d\_texture\_from\_sdf\_zxy](https://voxel-tools.readthedocs.io/en/latest/api/VoxelBuffer/#i_create_3d_texture_from_sdf_zxy) for more information. _Generated on Aug 20, 2026_ ---