Events

The following events are exposed by VoxelPlayEnvironment class. Also check out the VoxelPlayPlayer class for additional player related events and methods.

The env.captureEvents property determines if events are triggered or not (default = yes).

Game loop events

public event GameLoadEvent OnInitialized;

Triggered when Voxel Play has finished initialization and API is ready to receive commands. You can also query the env.initialized property.

public event GameLoadEvent OnGameLoaded;

Triggers after a saved game is loaded (see Load/Save game data section for more details)

public event GameLoadEvent OnWorldLoaded;

Triggers after the world has completely loaded and chunks are rendered.

Voxel related events

public event VoxelClickEvent OnVoxelClick;

Triggered when clicking on a voxel.

public event VoxelHitEvent OnVoxelDamaged;

Triggered when a voxel is about to receive damage.

public event VoxelHitInfoEvent OnVoxelDamagedHitInfo;

Triggered when a voxel is about to receive damage (same with extra data)

This event allows you to control the final damage taken by the voxel, modifying the damage argument by reference. Example:

            env.OnVoxelDamaged += (VoxelChunk chunk, int voxelIndex, ref int damage) => damage += 5;

public event VoxelHitEvent OnVoxelAfterDamaged;

Triggered after a voxel receives damage.

public event VoxelHitEvent OnVoxelAfterDamagedHitInfo;

Triggered after a voxel receives damage (provides extra data).

public event VoxelPlaceEvent OnVoxelBeforePlace;

Triggered just before a voxel is placed. Receives position, chunk and voxelIndex. You can modify some properties, like changing the voxel type or tint color. if voxel type is set to null from the event handler, the place action is cancelled.

public event VoxelPositionEvent OnVoxelAfterPlace;

Triggered just after a voxel is placed, before the chunk is refreshed.

public event VoxelDestroyEvent OnVoxelBeforeDestroyed;

Triggered when a voxel is destroyed but just before the position is cleared.

public event VoxelDestroyEvent OnVoxelDestroyed;

Triggered after a voxel is destroyed. The position is cleared when this event is called, if you need to know which voxel definition was at the position, use OnVoxelBeforeDestroyed.

public event VoxelHitsEvent OnVoxelBeforeAreaDamage;

Triggered before voxels get area damage. The event handler receives a list of potentially affected voxels which can be modified.

public event VoxelHitsEvent OnVoxelAfterAreaDamage;

Triggered after voxels receive area damage. The event handler receives a list of affected voxel indices.

public event VoxelDropItemEvent OnVoxelBeforeDropItem;

The event signature is OnVoxelBeforeDropItem(chunk, hitInfo, out create). Pass "false" to create and call env.CreateRecoverableVoxel(position, voxelType, color) method instead.

public event VoxelSpreadBeforeEvent OnVoxelBeforeSpread;

Triggered after a voxel is about to spread (ie. water flooding). Use this to cancel spreading (by returning false) or knowing where the voxel is expanding.

public event VoxelSpreadAfterEvent OnVoxelAfterSpread;

Triggered after a voxel has expanded to another position (ie. water flooding)

public event VoxelCollapseEvent OnVoxelCollapse;

Triggered when one ore more voxels collapse and fall down. The event handler received a List<VoxelIndex>.

Chunk related events

public event VoxelChunkEvent OnChunkChanged;

Triggered after the contents of a chunk changes (ie. placing a new voxel).

public event VoxelChunkBeforeCreationEvent OnChunkBeforeCreate;

Triggered just before the chunk is filled with default contents.

Use this event OnChunkBeforeCreate to provide your own content on the fly:

            env.OnChunkBeforeCreate += (Vector3 chunkCenter, out bool overrideDefaultContents, VoxelChunk chunk, out bool isAboveSurface) =>
                <fill voxels array with your content; voxels is an array of 16x16x16 voxels>

                <set overrideDefaultContents = true>

                <set isAboveSurface = true if this chunk has some voxels above the terrain surface; not critical but will help the lightmap builder determine if the chunk sides are illuminated or not in case there's no neighbours>
                

Note: in your event you can fill the voxels array directly (chunk.voxels[x] = ...) or use the chunk.SetVoxel() method (required if voxel emits light).

public event VoxelChunkEvent OnChunkAfterCreate;

Triggered after the chunk has been filled with default contents.

public event VoxelChunkEvent OnChunkAfterFirstRender;

Triggered after the chunk has been rendered for the first time.

public event VoxelChunkEvent OnChunkRender;

Triggered every time the chunk mesh is generated and uploaded to the GPU.

public event VoxelChunkEvent OnChunkReuse;

Triggered when chunk is about to be reused. Use the canReuse argument to cancel unload at will.

public event VoxelChunkEvent OnChunkExitVisibleDistance;

Triggered when chunk exits visible distance. If "Unload Far Chunk" option is enabled, the chunk gameobject will be disabled automatically.

public event VoxelChunkEvent OnChunkEnterVisibleDistance;

Triggered when chunk enters visible distance. If "Unload Far Chunk" option is enabled and the chunk gameobject is disabled, it will be re-enabled automatically.

Model definitions related events

public event VoxelModelBuildStartEvent OnModelBuildStart;

Triggered when a model definition starts building (used when player places a model definition interactively which places it in the scene with a duration). The model and position are passed to the event. You can use the cancel parameter to abort the creation of the model.

public event VoxelModelBuildEvent OnModelBuildEnd;

Triggered when a model definition ends building (used when player places a model definition interactively which places it in the scene with a duration).The model and position are passed to the event.

Other:

public event VoxelTorchEvent OnTorchAttached;

public event VoxelTorchEvent OnTorchDetached;

public event VoxelTorchEvent OnSettingsChanged;

public event VoxelTreeBeforeCreateEvent OnTreeBeforeCreate;

public event VoxelTreeBeforeAfterEvent OnTreeAfterCreate;

To react to an event, just hook your own delegate function:

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

     void MyChunkChangedEventDelegate(VoxelChunk chunk) {
       ...
     }
}