This section covers the public API of Voxel Play – the API is a set of functions and events you can use to integrate your gamelogic into Voxel Play.


The World API of Voxel Play can be accessed using this script:


using VoxelPlay;
public class MyScript : MonoBehaviour {
     VoxelPlayEnvironment env;
     void Start() {
          env = VoxelPlayEnvironment.instance;
          …
     }
}


Now, you can use all the functions using env.XXX where XXX is the name of a property or method detailed in the next sections.

Important: you need to ensure Voxel Play has finished initializing before calling any method. You can check if Voxel Play is ready checking the env.initialized property or using the OnInitialized event. Example:


using VoxelPlay;

public class MyScript : MonoBehaviour {

    VoxelPlayEnvironment env;

    void Start () {
        env = VoxelPlayEnvironment.instance;
        env.OnInitialized += OnInitialized;
    }

    void OnInitialized() {
        // ready to call API...
    }
}



Example 1: How to place a voxel at a specific position


string voxelTypeName = "VoxelBrickWall";
VoxelDefinition vd = env.GetVoxelDefinition(voxelTypeName);
env.VoxelPlace(new Vector3(10,10,10), vd);


Example 2: How to place a voxel at the aim position


Ray ray = Camera.main.ScreenPointToRay(Input.mousePosition);
if (env.RayCast(ray, out VoxelHitInfo hitInfo)) {
    VoxelDefinition brickWall = env.GetVoxelDefinition("VoxelBrickWall");
    env.VoxelPlace(hitInfo.center + hitInfo.normal, brickWall);
}


Example 3: How to get the chunk and voxel index for any position


if (env.GetVoxelIndex(position, out VoxelChunk chunk, out int voxelIndex)) {
    Debug.Log("The chunk containing the position " + position + " is at " + chunk.position + " and the index of that voxel in that chunk is: " + voxelIndex);
}


In the code above, you pass a position as Vector3 and the GetVoxelIndex method will give you the chunk and the index of that voxel in the chunk.voxels array. Many methods of the API allows you to pass either the position or the chunk + voxelIndex values.


Voxel Play provides lot of methods to place voxels. For example if you want to place many voxels in one call, the VoxelPlace method has a overload that accepts a list of positions.



Example 4: How to get the voxel at a specific position


Vector3 position = new Vector3 (10, 10, 10);
Voxel voxel = env.GetVoxel (position);
if (!voxel.isEmpty) {
       Debug.Log ("There's a voxel at " + position + " of type " + voxel.type.name);
}



Example 5: React to commands entered by user through the console


void Start () {
    env = VoxelPlayEnvironment.instance;
    VoxelPlayUI.instance.OnConsoleNewMessage += NewConsoleCommand;
}

bool NewConsoleCommand (string text) {
    if (text.ToUpper ().StartsWith ("/PLACE")) {
        env.ShowMessage ("User entered <color=yellow>PLACE</color> command!");
        return true; // captures this command
    }
    return false; // let Voxel Play process this command
}



Example 6: Add items to the player inventory


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


// Add 5 units of a the voxel type with name "VoxelDoorLeft"
VoxelDefinition vd = env.GetVoxelDefinition ("VoxelDoorLeft");
VoxelPlayPlayer.instance.AddInventoryItem (env.GetItemByType (ItemCategory.Voxel, vd), 5);



Learn more about the existing methods / properties in the next section. If you have any question or suggestion, please join our Discord channel and post it there!