Introduction & Basic Snippets

Modified on Thu, 28 Dec 2023 at 11:45 AM

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.


Initialization of the Engine


The 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.


API methods that start with "Get" prefix return data about voxels or chunks, while methods that start with "Voxel" or "Chunk" will change a voxel or chunk or produce some effect over a specific voxel or chunk.


For example, GetVoxelRotation will return the rotation of a voxel while VoxelSetRotation will change the rotation of the voxel.


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...
    }
}



Delayed initialization


Instead of making Voxel Play to initialize when your scene starts, you can delay the initialization in two ways:


A) Make Voxel Play Environment a prefab and instantiate it when you need it.


B) Or enable the option "Delayed Initialization" at the bottom of Voxel Play Environment inspector. Then, you can call env.Init() or env.InitAndLoadSaveGame() methods to initialize the engine.



Basic scripts



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! 



Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons

Feedback sent

We appreciate your effort and will try to fix the article