Chunk structure

All chunks in Voxel Play are represented by the VoxelChunk class.

Make sure you have read the introduction of what's a chunk and understand the chunk lifecycle.

The VoxelChunk class

The VoxelChunk class exposes many fields, most of them are of internal use. Here're some interesting fields:

class VoxelChunk ... {

    Voxel[] voxels;                 

    A linearized array containing all the chunks in this voxel (size = 16*16*16). See structure below.

    Vector3 position;

    The center of the chunk in world space

    bool isAboveSurface;

    If this chunk is above or crossing terrain surface.

    bool modified;                  

    True if this chunk has been modified by the player during the session

    bool isRendered;              

    True if this the chunk mesh has been generated.

    VoxelChunk top, bottom, right, left, forward, back;

    The chunk neighbours.

    bool Contains(Vector3 position)

    Returns true if this chunk contains a given position. Example: myChunk.Contains(position) returns true/false.

}

As stated, every chunk is a cube of 16x16x16 voxels. Each voxel occupy 1 unit in world space.

Examininig voxels in a chunk

There're a few ways to examine the voxel at a given position.

The easiest way

The easiest way is to use the GetVoxel method:

public Voxel GetVoxel (Vector3 position, bool createChunkIfNotExists = true, bool onlyRenderedVoxels = false)

Passing a world space position to this method will return the current voxel. By default this method will force the chunk to be generated if for any reason it's an empty place (ie. the camera has not reached this area yet). If you want to make sure the voxel is also rendered (the mesh has been generated so it's visible somewhere) pass "onlyRenderedVoxels=true".

If there's nothing at the position, the returned voxel has the property isEmpty = true.

Although this method is very easy to use, it involves getting a full Voxel structure. Using this in a loop can be slow so there're faster alternate ways to examine the chunk contents.

Going faster...

A second way is to use the GetVoxelIndex method. This method has several overloads, but this one is the most commonly used:

public bool GetVoxelIndex (Vector3 position, out VoxelChunk chunk, out int voxelIndex, bool createChunkIfNotExists = true)

This method returns the chunk and the index of the voxel in the voxels array. For example:

                VoxelPlayEnvironment env = VoxelPlayEnvironment.instance;
                VoxelChunk chunk;
                int voxelIndex;
                if (env.GetVoxelIndex (position, out chunk, out voxelIndex)) {
                    if (!chunk.voxels[voxelIndex].hasContent == 1) {
                        Debug.Log ("There's a voxel and its type is " + chunk.voxels [voxelIndex].type.name);
                    }
                }

The fastest way

Note that both GetVoxel and GetVoxelIndex need to determine to which chunk the position belongs to. If you know the chunk (already have a VoxelChunk object) you can examine the voxels array directly which results in the fastest way to query voxels in a chunk.

The index of a voxel in the chunk is determined by this formula:

voxelIndex = Y * (16*16) + Z * 16 + X

Note that XYZ coordinates are world-aligned so Y=0 is at bottom of the chunk, Z=0 is pointing "South" and X=0 is left.

X, Y and Z values are in the range of 0..15.

There're two methods that converts between the XYZ in a chunk and the index in the array:

public int GetVoxelIndex (int px, int py, int pz)

public void GetVoxelChunkCoordinates (int voxelIndex, out int px, out int py, out int pz)

Now that you know how to fetch voxels from world or a chunk, learn what info is contained in each voxel here.