Voxel Operations

advanced scripting

Class: All members on this page belong to VoxelPlayEnvironment. Access via VoxelPlayEnvironment.instance.

Voxel Placement

bool VoxelPlace(Vector3d position, VoxelDefinition voxelType, bool playSound = false, Color tintColor = default, float amount = 1f, int rotation = 0, bool refresh = true, bool placeMicroVoxels = true, MicroVoxels microVoxels = null, bool slabMode = false, bool playAnimation = false)

Places a voxel of the given type at the specified world position. Returns false when nothing was placed (for example, an unregistered definition). Scripted calls write the voxel directly; the placement animation only plays when explicitly requested.

position: World position (snapped to voxel grid).
voxelType: The voxel definition to place.
playSound: Play the placement sound effect.
refresh: Immediately refresh the chunk mesh. Set to false when placing many voxels in a batch, then call ChunkRedrawAll().
playAnimation: Plays the placement animation (ghost flying to the cell) before committing the write. Player build actions request it; leave false for scripted or bulk placement.

void VoxelPlace(Vector3d position, VoxelDefinition voxelType, Color tintColor, bool playSound = false, bool refresh = true)

Places a voxel with a custom tint color.

void VoxelPlace(Vector3d position, Color tintColor, bool playSound = false, bool refresh = true)

Places a voxel using the default type with the specified tint color.

void VoxelPlace(VoxelChunk chunk, int voxelIndex, Color tintColor, bool playSound = false, bool refresh = true)

Places a voxel directly in a chunk by voxel index.

void VoxelPlace(Vector3d position, Voxel voxel, bool playSound = false, bool refresh = true)

Places a complete Voxel struct (preserving all its properties).

void VoxelPlace(Vector3d position, VoxelDefinition voxelType, bool playSound, Color tintColor, float amount = 1f, int rotation = 0, bool refresh = true)

Places a voxel with full control over tint, fill amount, and rotation.

amount: Fill level (0-1). Used for water or partial voxels.
rotation: Texture rotation index.

Batch Placement

void VoxelPlace(List<Vector3d> positions, VoxelDefinition voxelType, Color32 tintColor, List<VoxelChunk> modifiedChunks = null)

Places voxels at multiple positions in one call. Optionally returns the list of modified chunks.

void VoxelPlace(List<VoxelIndex> indices, VoxelDefinition voxelType, Color tintColor, List<VoxelChunk> modifiedChunks = null)

Places voxels at specific chunk indices. Efficient for pre-computed positions.

void VoxelPlace(Vector3d boxMin, Vector3d boxMax, VoxelDefinition voxelType, List<VoxelChunk> modifiedChunks = null)

Fills a box volume with voxels of the given type.

void VoxelPlace(Vector3d boxMin, Vector3d boxMax, VoxelDefinition voxelType, Color tintColor, List<VoxelChunk> modifiedChunks = null)

Fills a box volume with tinted voxels.

void VoxelPlace(Vector3d boxMin, Vector3d boxMax, Voxel[,,] voxels, bool ignoreEmptyVoxels = false)

Places a 3D array of voxels into a volume region.

void VoxelPlace(VoxelChunk chunk, List<ModelBit> voxels)

Places voxels from model bit data directly into a chunk.

bool VoxelOverlaps(Vector3d position, VoxelDefinition type, Quaternion rotation, int layerMask = -1)

Checks whether placing a voxel at the given position would overlap with existing colliders. Useful for placement validation.

Voxel Destruction

Destroying or damaging voxels never runs structural collapse on its own. Every destroy, damage, hit and explode call takes a triggerCollapse parameter, off by default: pass true from gameplay code (weapons, tools, explosions) when unsupported voxels should fall. Collapse also requires play mode and Collapse On Destroy enabled on the World Definition. The bundled first and third person controllers, grenades, fire and debris impacts already pass it; editing code (world generation, editor tools, clearing areas) leaves it off.

bool VoxelDestroy(Vector3d position, bool triggerCollapse = false)

Destroys the voxel at the specified world position. Returns true if a voxel was destroyed.

triggerCollapse: Run the structural collapse check after the destruction so unsupported voxels fall as debris. Off by default; needs play mode and Collapse On Destroy enabled on the World Definition.

bool VoxelDestroy(VoxelChunk chunk, int voxelIndex, bool triggerCollapse = false)

Destroys a voxel by its chunk reference and index.

bool VoxelDestroy(Bounds bounds, bool triggerCollapse = false)

Destroys every voxel inside the bounds in one batch.

Voxel Damage

bool VoxelDamage(Vector3d position, int damage, bool playSound = false)

Applies damage to the voxel at the given position. The voxel is destroyed when damage exceeds its resistance. Returns true if the voxel was destroyed.

bool VoxelDamage(Vector3d position, int damage, bool addParticles, bool playSound, bool triggerCollapse = false)

Same as above with particle control and optional structural collapse.

bool VoxelDamage(Vector3d position, Vector3 hitDirection, int damage, bool addParticles = false, bool playSound = false, bool triggerCollapse = false)

Applies directional damage with optional particle effects.

bool VoxelDamage(Vector3d voxelPosition, Vector3d hitPoint, Vector3 normal, int damage, bool addParticles = false, bool playSound = false, bool triggerCollapse = false)

Applies damage with precise surface hit information for accurate particle spawning.

bool VoxelDamage(VoxelHitInfo hitInfo, int damage, bool addParticles = false, bool playSound = false)

Applies damage using a VoxelHitInfo struct (typically from a raycast).

bool VoxelDamage(VoxelHitInfo hitInfo, int damage, bool addParticles = false, bool playSound = false, bool showDamageCracks = true, bool canAddRecoverableVoxel = true, bool triggerCollapse = false)

Full damage with control over visual cracks, recoverable voxel spawning and structural collapse.

showDamageCracks: Show crack overlay texture as the voxel takes damage.
canAddRecoverableVoxel: Allow the destroyed voxel to drop a recoverable item.
triggerCollapse: Run the structural collapse check after the destruction so unsupported voxels fall as debris. Off by default; needs play mode and Collapse On Destroy enabled on the World Definition.

Area Damage

int VoxelDamage(Vector3d origin, int damage, int radius, bool attenuateDamageWithDistance, bool addParticles, bool playSound = false, bool showDamageCracks = false, bool canAddRecoverableVoxel = true, bool triggerCollapse = false)

Applies damage to all voxels within a radius. Returns the number of voxels destroyed. Useful for explosions.

radius: Blast radius in voxel units.
attenuateDamageWithDistance: Reduce damage for voxels farther from the origin.

int VoxelDamage(Vector3d origin, int damage, int radius, bool attenuateDamageWithDistance, bool addParticles, List<VoxelIndex> damagedVoxels, bool playSound = false, bool showDamageCracks = false, bool canAddRecoverableVoxel = true, bool triggerCollapse = false)

Area damage that also returns a list of all damaged voxel indices for post-processing.

Voxel Collapse

void VoxelCollapse(Vector3d position, int budget, List<VoxelIndex> voxelIndices = null, float debrisLifetime = 0)

Runs the structural collapse check around the given position: any group of voxels left without support falls as debris. This is the same check the destroy and damage calls run when their triggerCollapse parameter is true.

budget: Connectivity search budget, like Collapse Amount on the World Definition.
voxelIndices: Optional output list of collapsed voxel indices.
debrisLifetime: Lifetime in seconds of the debris bodies. 0 keeps them in the scene forever.

Voxel Resistance

int GetVoxelResistancePoints(Vector3d position)

Returns the remaining resistance (durability) points of the voxel at the given position.

int GetVoxelResistancePoints(VoxelChunk chunk, int voxelIndex)

Returns the resistance points of a voxel by chunk reference.

Code Example

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!");
    }
}

Was this page helpful? |