DOCSEARCHbyAlgolia
Submit Docs

Voxel Tools for Godot

repository·master·Indexed 26 days ago

https://github.com/zylann/godot_voxel

A C++ extension for Godot Engine 4 enabling the creation of complex volumetric 3D terrains. It supports blocky (Minecraft-style) and smooth (Transvoxel-based) terrain types with features including infinite paging, custom generators, physics integration, and real-time editing. The toolkit includes FastNoise2 for SIMD-accelerated noise generation, VoxelAStarGrid3D for voxel-based pathfinding, and VoxelBlockSerializer for data serialization with LZ4 and ZSTD compression.

Tokens
66.2K
Snippets
39
Records
452
Agent score
86%

What's inside godot_voxel

  1. Overview of Voxel Generators

    master

    A VoxelGenerator is a procedural source used to generate voxels for specific areas or single positions. They are lightweight alternatives to storing massive voxel datasets.

    Key Concepts:

    • Execution: Generators run on the CPU and primarily work with blocks of voxels (e.g., 16x16x16).
    • Channels: Data is split into channels. Use the TYPE channel (0) for blocky voxels (like Minecraft) and the SDF channel (1) for smooth terrain/distance fields.
    • Thread Safety: The generate_block method is thread-safe and can be called by multiple threads simultaneously.
    • Default Behavior: If no generator is assigned to a volume, blocks are filled with air by default.

  2. Overview of Voxel Tools for Godot

    master
    Voxel Tools for Godot is a C++ module/extension designed for creating volumetric terrains in Godot Engine 4. Unlike heightmap-based terrains, it supports overhangs, tunnels, and real-time in-game editing (creation/destruction).

  3. Key features of Voxel Tools

    master

    Voxel Tools provides several advanced terrain capabilities:

    • Polygon-based rendering: Voxels are transformed into chunked meshes.
    • Physics: Supports Godot physics integration and fast Minecraft-like collisions.
    • Infinite Terrains: Achieved by paging chunks in and out.
    • Data Streaming: Voxel data can be streamed from various sources, including custom generators.
    • Terrain Styles:
      • Blocky: Minecraft-style with multiple materials and baked ambient occlusion.
      • Smooth: Uses Transvoxel for level of detail.
    • Storage: Supports 8-bit or 16-bit channels for general-purpose voxel data.
    • Decoration: Includes an instancing system to spawn foliage, rocks, and other decorations on surfaces.

  4. Use VoxelModifier to non-destructively affect terrain

    master

    The VoxelModifier class is a base class for voxel modifiers that act as extensions to a terrain's generator. They allow you to non-destructively affect a limited volume of voxels. Modifiers can be stacked.

    Important Constraints:

    • Only works with VoxelLodTerrain.
    • Only works with smooth terrain (SDF).
    • Runtime edits made via VoxelTool will override modifier values.

  6. Use VoxelBlockyLibraryBase for VoxelMesherBlocky models

    master
    The VoxelBlockyLibraryBase resource contains the list of models used by VoxelMesherBlocky. Models must be baked using the bake() method before they can be used efficiently at runtime. Depending on the specific implementation (e.g., VoxelBlockyLibrary or VoxelBlockyTypeLibrary), this process may involve a simple list of models or high-level types that generate variant models.

  7. Use FastNoise2 for high-performance coherent noise

    master

    The FastNoise2 resource is a wrapper for the FastNoise2 library, providing coherent noise generation with SIMD (Single Instruction, Multiple Data) support. This allows for significantly faster generation compared to scalar implementations like FastNoiseLite.

    Important Usage Note: Because FastNoise2 uses an internal node-based structure, changes to properties are not applied immediately. You must call update_generator() after modifying properties to rebuild the internal graph and apply the changes.

  8. Use VoxelColorPalette for efficient colored voxels

    master

    The VoxelColorPalette is a resource that stores a limited list of up to 256 colors in an 8-bit format. This allows for quick indexing and a small memory footprint when storing colored voxels. It is designed to be used with VoxelMesherCubes.

    Important Note: Colors are internally stored using 8-bit components. Any floating-point values used via Godot's Color class will be rounded to the nearest 8-bit value.

  9. Use VoxelBlockyModel for voxel types

    master

    A VoxelBlockyModel represents the visual and physical properties of a specific voxel TYPE. To use it, you must store the model within a VoxelBlockyLibrary. Once in the library, it can be utilized by VoxelTerrain or directly by a VoxelMesherBlocky.

    Common implementations include:

    • VoxelBlockyModelCube
    • VoxelBlockyModelEmpty
    • VoxelBlockyModelFluid
    • VoxelBlockyModelMesh

  11. Use VoxelGraphFunction for voxel generation and processing

    master

    A VoxelGraphFunction is a resource containing a graph used to process series of 3D values, such as voxel positions. It is primarily used as a component within other resources, most commonly as the core logic for a VoxelGeneratorGraph to generate voxels.

    Key Concepts:

    • Node Families: Nodes are categorized into inputs (outputs only), outputs (inputs only), and others (both inputs and outputs for calculations).
    • Connections: Nodes are connected by linking outputs to inputs. Unconnected inputs can use default values or default implicit connections.
    • Parameters: Nodes can contain constant values defined per node.
    • Data Type: Graphs only process 32-bit floating point values.
    • Persistence Warning: Node types are identified by the NodeTypeID enum. Do not use these enum values in persistent contexts (like save files) as they may change between versions.

    To use this for actual voxel generation, you must embed it into a VoxelGeneratorGraph.