Voxel Play 3

https://kronnect.com/docs/voxel-play/
Admin
A complete voxel engine framework for Unity that enables creation of infinite, procedurally...
Tokens:112,453
Snippets:1,516
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### virtual void Init()

Source: https://kronnect.com/docs/voxel-play/terrain-generators

Initialization method called once when the world starts.

```APIDOC
## virtual void Init()

### Description
Called once when the world initializes. Use this for one-time setup tasks like noise generator configuration, texture loading, or pre-computing lookup tables.
```

--------------------------------

### Voxel Play Model and Torch Placement Example

Source: https://kronnect.com/docs/voxel-play-4/items-models-api

Demonstrates using VoxelPlayEnvironment to highlight and place models with animations, and attaching torches to voxel hits.

```csharp
using VoxelPlay;

public class VoxelCrafter : MonoBehaviour
{
    public ModelDefinition houseModel;

    void PlaceHouseAtCursor()
    {
        var env = VoxelPlayEnvironment.instance;

        // Raycast to find placement point
        Ray ray = Camera.main.ScreenPointToRay(Input.mousePosition);
        if (env.RayCast(new Rayd(ray), out VoxelHitInfo hit, 50f))
        {
            // Show build preview
            env.ModelHighlight(houseModel, hit.voxelCenter);

            if (Input.GetMouseButtonDown(0))
            {
                // Build with animation
                env.ModelPlace(
                    hit.voxelCenter + Vector3d.up,
                    houseModel,
                    buildDuration: 2f,
                    callback: (model, pos) => {
                        env.ShowMessage("House built!");
                    }
                );
            }
        }
    }

    void SpawnTorch()
    {
        var env = VoxelPlayEnvironment.instance;
        Ray ray = Camera.main.ScreenPointToRay(Input.mousePosition);

        if (env.RayCast(new Rayd(ray), out VoxelHitInfo hit, 20f))
        {
            env.TorchAttach(hit);
        }
    }
}
```

--------------------------------

### Implement Init Method

Source: https://kronnect.com/docs/voxel-play-4/detail-generators

Override the Init method to perform setup tasks like initializing arrays or loading noise textures when the world initializes. This method runs on the main thread.

```csharp
public override void Init() { ... }
```

--------------------------------

### Export Model to OBJ Example

Source: https://kronnect.com/docs/voxel-play-4/scripting

Demonstrates creating a GameObject from a model and exporting it to an OBJ file using VoxelPlayOBJExporter.

```csharp
using UnityEngine;
using VoxelPlay;

public class MyScript : MonoBehaviour {
    public ModelDefinition model;

    void Start() {
        // Create a standalone textured GameObject from a model
        GameObject go = VoxelPlayEnvironment.ModelCreateGameObject(model);
        go.transform.position = Vector3.zero;

        // Export the model to OBJ for external tools
        VoxelPlayOBJExporter.ExportModelToOBJ(model, Application.dataPath + "/../Export");
    }
}
```

--------------------------------

### Subscribe to Voxel Reaction Events

Source: https://kronnect.com/docs/voxel-play-4/scripting

Example of using OnVoxelReactionBefore to suppress default effects and trigger custom steam effects.

```csharp
env.OnVoxelReactionBefore += (VoxelChunk a, int ia, VoxelChunk b, int ib,
                             VoxelReactionRule rule, ref bool suppressEffects) => {
    Vector3d pos = env.GetVoxelPosition(a, ia);
    suppressEffects = true;   // skip the built-in vapor, play our own
    env.CreateSteamEffect(pos, amount: 16, scale: 0.2f, color: new Color32(230, 230, 235, 255));
    return true;              // let the reaction proceed
};
```

--------------------------------

### LineCast

Source: https://kronnect.com/docs/voxel-play-4/environment-api

Gets all voxels or chunks along a line between two points.

```APIDOC
## LineCast

### Description
Gets all voxels along a line between two points. Returns the number of voxels found. The output array must be pre-allocated.

### Method
int LineCast(Vector3d startPosition, Vector3d endPosition, VoxelIndex[] indices, int startIndex = 0, int minOpaque = 0)

### Parameters
- **startPosition** (Vector3d) - Required - Starting point of the line.
- **endPosition** (Vector3d) - Required - Ending point of the line.
- **indices** (VoxelIndex[]) - Required - Pre-allocated array to store results.
- **startIndex** (int) - Optional - Starting index in the array.
- **minOpaque** (int) - Optional - Minimum opacity of the voxels to report.
```

--------------------------------

### Access Voxel Index

Source: https://kronnect.com/docs/voxel-play/faq

Example of accessing chunk contents via the API.

```csharp
GetVoxelIndex(position)
```

--------------------------------

### Access Voxel Data

Source: https://kronnect.com/docs/voxel-play-4/faq

Example of accessing voxel contents via the API.

```csharp
GetVoxel`Index`(position)
```

--------------------------------

### Spawning and configuring a pathfinding agent

Source: https://kronnect.com/docs/voxel-play-4/pathfinding-api

Demonstrates creating a kinematic agent, setting movement parameters, and managing destinations.

```csharp
GameObject mob = GameObject.CreatePrimitive(PrimitiveType.Capsule);
Destroy(mob.GetComponent<Collider>()); // agents move kinematically, no physics needed
mob.transform.position = spawnPosition;

VoxelPlayPathAgent agent = mob.AddComponent<VoxelPlayPathAgent>();
agent.target = player;   // chases the player and repaths automatically
agent.speed = 4f;
agent.maxDrop = 3;       // accepts drops of up to 3 voxels

// or send it to a fixed destination instead:
agent.SetDestination(new Vector3(120, 60, -40));
agent.ClearDestination(); // back to chasing the target

// arrival check
if (!agent.hasPath) {
    // no path yet or already arrived
}
```

--------------------------------

### Get Neighbor Voxel Index

Source: https://kronnect.com/docs/voxel-play-4/faq

Retrieves the chunk and index of a neighboring voxel using coordinate offsets.

```csharp
public bool GetVoxelIndex (VoxelChunk chunk, int voxelIndex, int offsetX, int offsetY, int offsetZ, out VoxelChunk otherChunk, out int otherVoxelIndex, bool createChunkIfNotExists = false)
```

--------------------------------

### Subscribe to Voxel Play Environment Events

Source: https://kronnect.com/docs/voxel-play-4/events

Demonstrates how to hook into initialization, voxel destruction, placement modification, chunk generation, and lifecycle management within a MonoBehaviour.

```csharp
using VoxelPlay;

public class VoxelEventHandler : MonoBehaviour
{
    void Start()
    {
        var env = VoxelPlayEnvironment.instance;

        // Wait for initialization
        env.OnInitialized += () => {
            Debug.Log("Voxel Play ready!");
        };

        // Track voxel destruction
        env.OnVoxelDestroyed += (chunk, voxelIndex) => {
            Vector3d pos = env.GetVoxelPosition(chunk, voxelIndex);
            Debug.Log($"Voxel destroyed at {pos}");
        };

        // Modify voxel type or tint color before placement
        env.OnVoxelBeforePlace += (Vector3d position, VoxelChunk chunk, int voxelIndex,
            ref VoxelDefinition voxelType, ref Color32 tintColor) => {
            // Example: force all placed voxels to have a red tint
            tintColor = new Color32(255, 100, 100, 255);
        };

        // Custom chunk generation
        env.OnChunkBeforeCreate += (Vector3d chunkCenter,
            out bool overrideDefaultContents, VoxelChunk chunk,
            out bool isAboveSurface) => {
            overrideDefaultContents = false;
            isAboveSurface = false;
            // Add custom ore to every chunk after default generation
            for (int i = 0; i < chunk.voxels.Length; i++)
            {
                if (Random.value < 0.001f)
                {
                    VoxelDefinition ore = env.GetVoxelDefinition("Gold");
                    chunk.voxels[i].Set(ore);
                }
            }
        };

        // Monitor chunk lifecycle
        env.OnChunkEnterVisibleDistance += (chunk) => {
            // Load custom data for this chunk
        };
        env.OnChunkReuse += (VoxelChunk chunk, out bool canReuse) => {
            canReuse = true; // set false to prevent recycling
            // Save custom data before chunk is recycled
        };
    }
}
```

--------------------------------

### Build and Damage Voxels in C#

Source: https://kronnect.com/docs/voxel-play-4/voxel-operations-api

Demonstrates how to place voxels in a loop with deferred mesh updates and how to apply radial damage to the environment.

```csharp
using VoxelPlay;

public class VoxelBuilder : MonoBehaviour
{
    void BuildWall()
    {
        var env = VoxelPlayEnvironment.instance;
        VoxelDefinition brick = env.GetVoxelDefinition("Brick");

        // Build a 10x5 wall
        for (int x = 0; x < 10; x++)
        {
            for (int y = 0; y < 5; y++)
            {
                env.VoxelPlace(
                    new Vector3d(x, y, 0),
                    brick,
                    playSound: false,
                    refresh: false  // defer mesh rebuild
                );
            }
        }

        // Refresh all chunks at once
        env.ChunkRedrawAll();
    }

    void Explode(Vector3d center)
    {
        var env = VoxelPlayEnvironment.instance;
        int destroyed = env.VoxelDamage(
            center,
            damage: 100,
            radius: 5,
            attenuateDamageWithDistance: true,
            addParticles: true,
            playSound: true
        );
        Debug.Log($"Destroyed {destroyed} voxels!");
    }
}
```

--------------------------------

### Get Custom Voxel GameObject Reference

Source: https://kronnect.com/docs/voxel-play-4/faq

Retrieves the instantiated GameObject for a custom voxel at a specific position.

```csharp
GameObject voxelGameObject = env.GetVoxelGameObject(position);
```

--------------------------------

### Tracking MicroVoxel Changes

Source: https://kronnect.com/docs/voxel-play-4/microvoxels-api

Example of using the changedMicroVoxels list to process only modified microvoxels after a destruction operation.

```C#
List<MicroVoxelIndex> changed = new List<MicroVoxelIndex>();
env.MicroVoxelDestroy(explosionCenter, radius, 1f, changed);
foreach (MicroVoxelIndex m in changed) {
    // only the microvoxels that really changed, no rescan of the brush volume
}
```

--------------------------------

### Accessing Voxel Play API and Events

Source: https://kronnect.com/docs/voxel-play/programming-guide

Demonstrates how to retrieve the VoxelPlayEnvironment singleton, place a voxel, and subscribe to destruction events.

```csharp
using VoxelPlay;

// Get the singleton instance
VoxelPlayEnvironment env = VoxelPlayEnvironment.instance;

// Place a voxel
VoxelDefinition stone = env.GetVoxelDefinition("Stone");
env.VoxelPlace(new Vector3d(0, 10, 0), stone);

// Subscribe to events
env.OnVoxelDestroyed += (chunk, voxelIndex) => {
    Debug.Log("Voxel destroyed!");
};
```

--------------------------------

### Extending VoxelPlayEnvironment with partial classes

Source: https://kronnect.com/docs/voxel-play-4/customizing-asset

Create a new file with the same namespace and class name to add custom methods that can access private fields of the original class.

```csharp
namespace VoxelPlay {  
public partial class VoxelPlayEnvironment : MonoBehavior {  
  
public bool MyVoxelDestroy (VoxelChunk chunk, int voxelIndex) {  
... your code goes here ...  
}  
}  
}
```

--------------------------------

### VoxelPlayEnvironment API Usage

Source: https://kronnect.com/docs/voxel-play-4/scripting

Demonstrates how to access the VoxelPlayEnvironment singleton, retrieve voxel definitions, place voxels in the world, and subscribe to destruction events.

```APIDOC
## VoxelPlayEnvironment API

### Description
The `VoxelPlayEnvironment` class is the primary entry point for the Voxel Play 4 API. It is a singleton that provides methods for world manipulation and event hooks.

### Usage
Add `using VoxelPlay;` to your script to access the API.

### Methods
- **VoxelPlayEnvironment.instance**: Returns the singleton instance of the environment.
- **GetVoxelDefinition(string name)**: Retrieves a `VoxelDefinition` by its name.
- **VoxelPlace(Vector3d position, VoxelDefinition voxel)**: Places a voxel at the specified world position.

### Events
- **OnVoxelDestroyed**: An event triggered when a voxel is destroyed. Signature: `(Chunk chunk, int voxelIndex)`.

### Example
```csharp
using VoxelPlay;

// Get the singleton instance
VoxelPlayEnvironment env = VoxelPlayEnvironment.instance;

// Place a voxel
VoxelDefinition stone = env.GetVoxelDefinition("Stone");
env.VoxelPlace(new Vector3d(0, 10, 0), stone);

// Subscribe to events
env.OnVoxelDestroyed += (chunk, voxelIndex) => {
    Debug.Log("Voxel destroyed!");
};
```
```

--------------------------------

### Implementing a Custom Input Controller

Source: https://kronnect.com/docs/voxel-play-4/custom-input

To create a custom controller, define a class that inherits from VoxelPlayInputController and implement the Initialize and UpdateInputState methods.

```APIDOC
public class MyController : VoxelPlayInputController {
	public override bool Initialize() {
		// Initialization logic here
		return true;
	}

	public override void UpdateInputState() {
		// Read inputs and update input state here
	}
}
```

--------------------------------

### Execute Voxel Reactions and Effects

Source: https://kronnect.com/docs/voxel-play-4/scripting

Methods to manually trigger reactions and spawn custom steam effects.

```csharp
// Manually attempt a reaction between two touching voxels. Returns true if a rule fired.
bool TryVoxelReaction(VoxelChunk chunk1, int voxelIndex1, VoxelChunk chunk2, int voxelIndex2);

// Spawn the same vapor puff burst reactions use, anywhere you like.
void CreateSteamEffect(Vector3d position, int amount = 8, float scale = 0.15f,
                       float duration = 1.5f, Color32 color = default);
```

--------------------------------

### Ensure Chunk Readiness Before Spawning Mobs

Source: https://kronnect.com/docs/voxel-play-4/faq

Verify that a chunk is generated and has a NavMesh ready before spawning objects to prevent them from falling through the terrain.

```csharp
VoxelPlayEnvironment env = VoxelPlayEnvironment.instance;
if (!env.initialized)
return;
```

```csharp
Vector3 position = new Vector3 (Random.value * 50 - 25, 51f, 70);
StartCoroutine(Spawn(position));
```

```csharp
...
IEnumerator Spawn(Vector3 position) {
    VoxelChunk chunk = null;
    while (chunk == null || !env.ChunkHasNavMeshReady (chunk)) {
         env.GetChunk (position, out chunk, true);
         yield return null;
    }
     // now it's safe to create the gameobject at position
    ...
}
```

--------------------------------

### VoxelPour and VoxelPourCompute Methods

Source: https://kronnect.com/docs/voxel-play-4/scripting

Use VoxelPour to paint liquid cascades directly into the world, or VoxelPourCompute to calculate the liquid distribution without modifying the world state.

```csharp
void VoxelPour(Vector3d source, VoxelDefinition liquid,
                     int poolRadius = 8, int maxVoxels = 2000,
                     System.Func<Vector3d, bool> isSolid = null,
                     bool seekShortestPath = false);

// Same cascade, computed but not written: fills the cells and their liquid levels
void VoxelPourCompute(Vector3d source, int poolRadius, int maxVoxels,
                            System.Func<Vector3d, bool> isSolid,
                            List<Vector3d> cells, List<byte> levels,
                            bool seekShortestPath = false);
```

--------------------------------

### IVoxelPlayPlayer Inventory Methods

Source: https://kronnect.com/docs/voxel-play-4/custom-player

Methods for managing player inventory items, including adding, selecting, and consuming items.

```csharp
        void AddInventoryItem (ItemDefinition [] newItems);
        bool AddInventoryItem (ItemDefinition newItem, float quantity = 1);
        void PickUpItem (ItemDefinition newItem, float quantity = 1);
        void UnSelectItem ();
        bool SetSelectedItem (int itemIndex);
        bool SetSelectedItem (InventoryItem item);
        bool SetSelectedItem (VoxelDefinition vd);
        InventoryItem GetSelectedItem ();
        List<InventoryItem> items { get; }
        int selectedItemIndex { get; set; }
        List<InventoryItem> GetPlayerItems ();
        bool HasItem (ItemDefinition item);
        InventoryItem ConsumeItem ();
        void ConsumeItem (ItemDefinition item);
        float GetItemQuantity (ItemDefinition item);
```

--------------------------------

### CreateMicroVoxels(bool[,,], ref MicroVoxels, bool)

Source: https://kronnect.com/docs/voxel-play-4/microvoxels-api

Builds a MicroVoxels instance from a 3D boolean occupancy array of size [16, 16, 16].

```APIDOC
## bool CreateMicroVoxels(bool[,,] occupancy, ref MicroVoxels mv, bool shared = true)

### Description
Builds a MicroVoxels instance from a 3D boolean occupancy array of size [16, 16, 16]. Each true entry maps to an occupied cell.

### Parameters
- **occupancy** (bool[,,]) - Required - 3D boolean array of size [16, 16, 16].
- **mv** (ref MicroVoxels) - Required - The MicroVoxels instance to populate.
- **shared** (bool) - Optional - When true, reuses identical shapes from the internal cache. Default is true.
```

--------------------------------

### Configure Super Chunks via Script

Source: https://kronnect.com/docs/voxel-play-4/super-chunks

Enable and configure Super Chunks settings programmatically through the Voxel Play environment instance.

```csharp
env.enableSuperChunks = true;
env.superChunksExtension = 60;
env.superChunksQuality = SuperChunksQuality.Medium;
```

--------------------------------

### Place Models at Runtime

Source: https://kronnect.com/docs/voxel-play-4/faq

Populates a 3D array of voxel definitions and places them in the scene relative to the camera position.

```csharp
int sizeX = 12, sizeY = 12, sizeZ = 12;
VoxelDefinition[,,] model = new VoxelDefinition[sizeY, sizeZ, sizeX];
VoxelDefinition vd = env.GetVoxelDefinition (1);
for (int y = 0; y < sizeY; y++) {
    for (int z = 0; z < sizeZ; z++) {
        for (int x = 0; x < sizeX; x++) {
            model [y, z, x] = vd;
        }
    }
}

VoxelPlayFirstPersonController fpsController = VoxelPlayFirstPersonController.instance;
env.ModelPlace (Camera.main.transform.position + Camera.main.transform.forward * 100, model);
```

--------------------------------

### Define and Place Custom Voxels at Runtime

Source: https://kronnect.com/docs/voxel-play-4/faq

Creates a new VoxelDefinition instance and registers it with the environment, followed by an optional placement at the crosshair position.

```csharp
    VoxelDefinition vd = env.GetVoxelDefinition ("Brick");
    if (vd == null) {
        vd = ScriptableObject.CreateInstance<VoxelDefinition> ();
        vd.name = "Brick";
        vd.renderType = RenderType.Opaque;
        vd.textureTop = texture;
        vd.textureSide = texture;
        vd.textureBottom = texture;
        env.AddVoxelDefinition (vd);
    }

    VoxelPlayFirstPersonController fpsController = VoxelPlayFirstPersonController.instance;
    if (fpsController.crosshairOnBlock) {
        Vector3 pos = fpsController.crosshairHitInfo.voxelCenter + fpsController.crosshairHitInfo.normal;
        env.VoxelPlace (pos, vd); 
    }
```

--------------------------------

### Console Methods

Source: https://kronnect.com/docs/voxel-play/ui-console-api

Methods for managing the in-game console visibility and displaying messages.

```APIDOC
## Console Methods

### IsConsoleVisible
Returns true if the console is visible.

### ToggleConsoleVisibility(bool state)
Shows or hides the console based on the provided state.

### AddConsoleText(string text)
Adds custom text to the console.

### AddMessage(string text, float displayTime = 4f, bool flash = true, bool openConsole = false)
Adds a custom message to the status bar and console.

### HideStatusText()
Hides the status bar.
```

--------------------------------

### Implement ExploreArea Method

Source: https://kronnect.com/docs/voxel-play-4/detail-generators

Override the ExploreArea method to define the logic for generating details within a specific area of the world.

```csharp
public override bool ExploreArea(Vector3d currentPosition, bool checkOnlyBorders, long endTime) { ... }
```

--------------------------------

### ItemSpawn

Source: https://kronnect.com/docs/voxel-play-4/items-models-api

Spawns an item at a specific world position as a pickup.

```APIDOC
## ItemSpawn

### Description
Spawns an item at the given world position. The item appears as a pickup in the world.

### Method
Method Call

### Signature
GameObject ItemSpawn(string itemDefinitionName, Vector3d position, int quantity = 1)

### Parameters
- **itemDefinitionName** (string) - The name of the item definition.
- **position** (Vector3d) - The world position to spawn the item.
- **quantity** (int) - Number of items in the stack.
```

--------------------------------

### VoxelPlayUI Inventory Methods

Source: https://kronnect.com/docs/voxel-play-4/ui-console-api

Methods available via VoxelPlayUI.instance to manage inventory visibility and navigation.

```APIDOC
## Inventory Methods

### IsInventoryVisible()
Returns true if the inventory is visible.

### ToggleInventoryVisibility(bool state)
Shows or hides the inventory.

### InventoryNextPage()
Advances to the next inventory page.

### InventoryPreviousPage()
Shows the previous inventory page.

### RefreshInventoryContents()
Redraws the inventory contents.

### ShowSelectedItem(InventoryItem inventoryItem)
Displays the currently selected item.

### HideSelectedItem()
Hides the selected item.
```

--------------------------------

### Other UI Methods

Source: https://kronnect.com/docs/voxel-play/ui-console-api

Methods for managing additional UI elements like the initialization panel and debug window.

```APIDOC
## Other Methods

### ToggleInitializationPanel(bool visible, string text = "", float progress = 0)
Shows or hides the loading panel with optional text and progress.

### ToggleDebugWindow(bool visible)
Shows or hides the debug window.
```

--------------------------------

### Basic Player API Usage

Source: https://kronnect.com/docs/voxel-play-4/player-api

Demonstrates how to access the VoxelPlayPlayer instance to modify player properties like total life.

```csharp
using VoxelPlay;

public class MyScript : MonoBehaviour {
    void Start() {
        VoxelPlayPlayer.instance.totalLife = 5;
    }
}
```

--------------------------------

### Generate and Save MicroVoxel Thumbnail

Source: https://kronnect.com/docs/voxel-play-4/microvoxels

Creates a preview texture of a microvoxel shape and saves it as a PNG file. The caller must manually destroy the returned Texture2D to prevent memory leaks.

```csharp
// Generate a 256x256 thumbnail
Texture2D thumbnail = myVoxelDefinition.microVoxels.GenerateThumbnail(256, 256);

// Save to PNG
byte[] png = thumbnail.EncodeToPNG();
System.IO.File.WriteAllBytes("thumbnail.png", png);

// Remember to destroy the texture when done
Destroy(thumbnail);
```

--------------------------------

### Enable Anti-Tiling Globally

Source: https://kronnect.com/docs/voxel-play-4/anti-tiling

Enable the anti-tiling feature within the Voxel Play environment settings.

```csharp
env.enableAntiTiling = true;
```

--------------------------------

### Define a Custom Input Controller

Source: https://kronnect.com/docs/voxel-play-4/custom-input

Create a custom controller by inheriting from VoxelPlayInputController and implementing the required initialization and update methods.

```csharp
public class MyController: VoxelPlayInputController { ... }
```

--------------------------------

### Model GameObject Methods

Source: https://kronnect.com/docs/voxel-play/items-models-api

Methods for creating and previewing voxel model GameObjects in the Unity scene.

```APIDOC
## ModelCreateGameObject

### Description
Creates a standalone Unity GameObject from a voxel model definition.

### Signatures
- `GameObject ModelCreateGameObject(ModelDefinition modelDefinition)`
- `GameObject ModelCreateGameObject(ModelDefinition modelDefinition, Vector3 offset, Vector3 scale)`

## ModelHighlight

### Description
Creates a semi-transparent preview of the model at the given position, useful for build placement previews.

### Parameters
- **modelDefinition** (ModelDefinition) - The model to preview.
- **position** (Vector3d) - The world position for the preview.
```

--------------------------------

### ShowMessage

Source: https://kronnect.com/docs/voxel-play-4/items-models-api

Displays a message in the in-game console.

```APIDOC
## void ShowMessage(string txt, float displayDuration = 4, bool flashEffect = false, bool openConsole = false, bool allowDuplicatedMessage = false, string colorName = null)

### Description
Displays a message in the in-game console.

### Parameters
- **txt** (string) - The message text to display.
- **displayDuration** (float) - Seconds the message remains visible (default: 4).
- **flashEffect** (bool) - Flash the message for emphasis (default: false).
- **openConsole** (bool) - Automatically open the console panel (default: false).
- **allowDuplicatedMessage** (bool) - Allow duplicate messages (default: false).
- **colorName** (string) - HTML color name for the message text (default: null).
```

--------------------------------

### Build a custom slab voxel from an occupancy array

Source: https://kronnect.com/docs/voxel-play-4/microvoxels-api

Defines a custom shape using a 16x16x16 boolean array and places it into the environment.

```csharp
using VoxelPlay;
using UnityEngine;

public class CustomShape : MonoBehaviour
{
    public VoxelDefinition stone;

    void Start()
    {
        var env = VoxelPlayEnvironment.instance;

        // Build a pyramid that occupies the bottom half of a voxel
        bool[,,] occ = new bool[16, 16, 16];
        for (int y = 0; y < 8; y++)
        {
            int margin = y;
            for (int x = margin; x < 16 - margin; x++)
            {
                for (int z = margin; z < 16 - margin; z++)
                {
                    occ[x, y, z] = true;
                }
            }
        }

        MicroVoxels shape = null;
        env.CreateMicroVoxels(occ, ref shape);

        env.VoxelPlace(
            new Vector3d(4, 32, 4),
            stone,
            placeMicroVoxels: true,
            microVoxels: shape
        );
    }
}
```

--------------------------------

### VoxelPlayUI Console Methods

Source: https://kronnect.com/docs/voxel-play-4/ui-console-api

Methods available via VoxelPlayUI.instance to manage console visibility and display messages.

```APIDOC
## Console Methods

### IsConsoleVisible()
Returns true if the console is visible.

### ToggleConsoleVisibility(bool state)
Shows or hides the console based on the provided state.

### AddConsoleText(string text)
Adds custom text to the console.

### AddMessage(string text, float displayTime = 4f, bool flash = true, bool openConsole = false)
Adds a custom message to the status bar and console. 
- **text** (string): The message to display.
- **displayTime** (float): Duration in seconds.
- **flash** (bool): Whether to flash the message.
- **openConsole** (bool): Whether to open the console automatically.

### HideStatusText()
Removes the status bar text.
```

--------------------------------

### Implement a Flat Terrain Generator

Source: https://kronnect.com/docs/voxel-play-4/terrain-generators

Create a custom terrain generator by inheriting from VoxelPlayTerrainGenerator. Ensure the isAboveSurface flag is set correctly to optimize lighting calculations.

```csharp
using UnityEngine;
using VoxelPlay;

[CreateAssetMenu(menuName = "Voxel Play/Terrain Generators/Flat Terrain",
                 fileName = "FlatTerrainGenerator", order = 200)]
public class FlatTerrainGenerator : VoxelPlayTerrainGenerator {

    [Header("Flat terrain settings")]
    public int altitude = 40;
    public VoxelDefinition terrainVoxel;
    public Color32 voxelColor = new Color32(255, 255, 255, 255);

    public override bool PaintChunk(VoxelChunk chunk) {
        // Bottom Y position of this chunk in world space
        int chunkBottomY = FastMath.FloorToInt(
            chunk.position.y - VoxelPlayEnvironment.CHUNK_HALF_SIZE);

        // If the entire chunk is above our terrain, skip it
        if (chunkBottomY >= altitude) {
            return false;
        }

        // How many rows (in local Y) are solid inside this chunk
        int maxY = altitude - chunkBottomY;
        int lastVoxel = maxY * ONE_Y_ROW;
        if (lastVoxel > chunk.voxels.Length)
            lastVoxel = chunk.voxels.Length;

        // Fill solid voxels
        for (int k = 0; k < lastVoxel; k++) {
            chunk.voxels[k].Set(terrainVoxel, voxelColor);
        }

        // Mark surface chunks so VP computes lighting correctly
        int chunkTopY = (int)chunk.position.y
            + VoxelPlayEnvironment.CHUNK_HALF_SIZE;
        chunk.isAboveSurface = chunkTopY >= altitude;

        return true;
    }
}
```

--------------------------------

### VoxelPlayUI Other Methods

Source: https://kronnect.com/docs/voxel-play-4/ui-console-api

Additional UI control methods for loading panels and debug windows.

```APIDOC
## Other Methods

### ToggleInitializationPanel(bool visible, string text = "", float progress = 0)
Shows or hides the loading panel.

### ToggleDebugWindow(bool visible)
Shows or hides the debug window.
```

--------------------------------

### Define a Custom UI Class

Source: https://kronnect.com/docs/voxel-play-4/custom-ui

Create a custom UI script by inheriting from the VoxelPlayUI base class.

```csharp
public partial class VoxelPlayUIDefault : VoxelPlayUI {
...
}
```

--------------------------------

### ModelDefinition.Create

Source: https://kronnect.com/docs/voxel-play-4/model-definition-structure

Static methods to instantiate a new ModelDefinition object with specified dimensions and optional initial data.

```APIDOC
## static ModelDefinition Create(int sizeX, int sizeY, int sizeZ)
## static ModelDefinition Create(int sizeX, int sizeY, int sizeZ, List<VoxelDefinition> voxelDefinitions)
## static ModelDefinition Create(int sizeX, int sizeY, int sizeZ, List<Voxel> voxels)
## static ModelDefinition Create(int sizeX, int sizeY, int sizeZ, VoxelDefinition vd, List<Color> colors)

### Description
Creates a new instance of a ModelDefinition. Various overloads allow initialization from existing voxel definitions, voxel lists, or color arrays.

### Parameters
- **sizeX** (int) - Required - Width of the model.
- **sizeY** (int) - Required - Height of the model.
- **sizeZ** (int) - Required - Depth of the model.
- **voxelDefinitions** (List<VoxelDefinition>) - Optional - Initial list of voxel definitions.
- **voxels** (List<Voxel>) - Optional - Initial list of voxels.
- **vd** (VoxelDefinition) - Optional - Base voxel definition.
- **colors** (List<Color>) - Optional - Initial color list.
```

--------------------------------

### Procedural MicroVoxel Generation

Source: https://kronnect.com/docs/voxel-play-4/microvoxels

Create and populate a MicroVoxels object using SetOccupied and apply it via VoxelPlace.

```csharp
MicroVoxels mv = new MicroVoxels();
mv.SetOccupied(x, y, z);
VoxelPlace(..., microVoxels: mv);
```

```csharp
mv.palette = new Color32[] { ... };
mv.colorIndices[index] = k;
```

```csharp
VoxelPlace(positions, voxelType, microVoxelsList);
```

--------------------------------

### Add Items to Player Inventory via Scripting

Source: https://kronnect.com/docs/voxel-play-4/faq

Use VoxelPlayPlayer.instance.AddInventoryItem to populate the player's inventory after the environment has initialized.

```csharp
VoxelPlayEnvironment env;

        void Start () {
            env = VoxelPlayEnvironment.instance;

            // When Voxel Play is ready, do some stuff...
            env.OnInitialized += OnInitialized;
        }

        void OnInitialized () {

            // Item definitions are stored in Items folder within the world name folder

            // Add 3 torches to initial player inventory
            VoxelPlayPlayer.instance.AddInventoryItem (env.GetItemDefinition (ItemCategory.Torch), 3);

            // Add a shovel (no need to specify quantity it's 1 unit)
            VoxelPlayPlayer.instance.AddInventoryItem (env.GetItemDefinition ("Shovel"));

            // Add a sword 
            VoxelPlayPlayer.instance.AddInventoryItem (env.GetItemDefinition ("Sword"));
}
```

--------------------------------

### OriginShiftApply

Source: https://kronnect.com/docs/voxel-play-4/origin-shift

Manually applies a world position change.

```APIDOC
## OriginShiftApply

### Description
Manually applies a world position change where the new origin is given in the pivot parameter.

### Parameters
- **pivot** (Vector3) - The new origin position.

### Signature
`public void OriginShiftApply(Vector3 pivot);`
```

--------------------------------

### Deferred Voxel Placement Methods

Source: https://kronnect.com/docs/voxel-play-4/scripting

Use these methods to queue voxel placement or batch operations. Call these from the main thread.

```csharp
// Single write
void VoxelPlaceDeferred(Vector3d position, int voxelIndex, VoxelDefinition voxelDefinition,
                              Color32 color, MicroVoxels microVoxels, DeferredVoxelWriteFlags flags,
                              byte waterLevel = 0, int rotation = 0);

// Batch overload: groups positions by chunk for you (no manual voxel index)
void VoxelPlaceDeferred(List<Vector3d> worldPositions, VoxelDefinition voxelDefinition,
                               Color32 color, MicroVoxels microVoxels, DeferredVoxelWriteFlags flags,
                               byte waterLevel = 0, List<byte> waterLevels = null,
                               int rotation = 0);
```

--------------------------------

### Manage Deferred Torches

Source: https://kronnect.com/docs/voxel-play-4/scripting

Methods for registering, clearing, and processing torches that are materialized based on proximity to the camera.

```csharp
// Register a torch to be materialized on demand (does not instantiate yet)
void TorchAttachDeferred(Vector3d worldPos, Vector3 normal, ItemDefinition torchDefinition);

// Clear all deferred torches recorded for a chunk (e.g. before re-recording it)
void TorchClearDeferred(Vector3d chunkWorldPos);

// Materialize/recycle deferred torches around an observer (called by the lighting manager)
void ProcessDeferredTorches(Vector3 observerPos);
```

--------------------------------

### VoxelPlayEnvironment Convenience Wrappers

Source: https://kronnect.com/docs/voxel-play-4/scripting

Delegates to VoxelPlayConverter.GenerateVoxelObject using matching signatures.

```csharp
// On VoxelPlayEnvironment (instance or static)
GameObject ModelCreateGameObject(ModelDefinition md, ...);
GameObject VoxelCreateGameObject(ModelDefinition md, ...);
```

--------------------------------

### Subscribe to Voxel Play Events

Source: https://kronnect.com/docs/voxel-play-4/events

General syntax for subscribing to events within the VoxelPlayEnvironment instance.

```csharp
VoxelPlayEnvironment.instance.OnEventName += handler;
```
Tokens:
Raw