Events

advanced scripting

Voxel Play 3 · Scripting / API

Class: All events on this page belong to VoxelPlayEnvironment. Subscribe via VoxelPlayEnvironment.instance.OnEventName += handler;

Voxel Damage Events

event VoxelHitEvent OnVoxelDamaged(VoxelChunk chunk, int voxelIndex, ref int damage)

Fired when a voxel receives damage. Provides the chunk and voxel index.

event VoxelHitInfoEvent OnVoxelDamagedHitInfo(VoxelHitInfo hitInfo, ref int damage)

Fired when a voxel receives damage with full hit information (point, normal, direction).

event VoxelHitAfterEvent OnVoxelAfterDamaged(VoxelChunk chunk, int voxelIndex, int damage)

Fired after damage has been applied to a voxel. Use for post-damage effects.

event VoxelHitInfoAfterEvent OnVoxelAfterDamagedHitInfo(VoxelHitInfo hitInfo, int damage)

Fired after damage with full hit information.

event VoxelHitsEvent OnVoxelBeforeAreaDamage(List<VoxelIndex> voxelIndices)

Fired before area damage is applied. The voxel list can be modified to exclude specific voxels from the blast.

event VoxelHitsEvent OnVoxelAfterAreaDamage(List<VoxelIndex> voxelIndices)

Fired after area damage has been applied to all affected voxels.

Voxel Lifecycle Events

event VoxelCancelableEvent OnVoxelBeforeDestroyed(VoxelChunk chunk, int voxelIndex, ref bool cancel)

Fired just before a voxel is destroyed. Set cancel = true in the handler to prevent destruction. The voxel data is still accessible.

event VoxelEvent OnVoxelDestroyed(VoxelChunk chunk, int voxelIndex)

Fired after a voxel has been destroyed and removed from the world.

event VoxelPlaceEvent OnVoxelBeforePlace(Vector3d position, VoxelChunk chunk, int voxelIndex, ref VoxelDefinition vd, ref Color32 tintColor)

Fired before a voxel is placed. Modify the voxelDefinition or tintColor ref parameters to change what gets placed.

event VoxelPositionEvent OnVoxelAfterPlace(Vector3d position, VoxelChunk chunk, int voxelIndex)

Fired after a voxel has been placed successfully.

event VoxelDropItemEvent OnVoxelBeforeDropItem(VoxelHitInfo hitInfo, out bool canBeCollected)

Fired before a recoverable voxel item is spawned (e.g., when a voxel is destroyed and drops a pickup).

event VoxelDropItemAfterEvent OnVoxelAfterDropItem(VoxelHitInfo hitInfo, GameObject obj)

Fired after a recoverable voxel item has been spawned. Provides the hit info and the created GameObject.

Voxel Interaction Events

event VoxelClickEvent OnVoxelClick(VoxelChunk chunk, int voxelIndex, int buttonIndex)

Fired when the player clicks on a voxel. Provides the chunk, voxel index, and mouse button used.

event VoxelCollapseEvent OnVoxelCollapse(List<VoxelIndex> indices)

Fired when voxels collapse due to lack of support (gravity).

Chunk Events

event VoxelChunkEvent OnChunkChanged(VoxelChunk chunk)

Fired when any voxel in a chunk is modified (placed, destroyed, or changed).

event VoxelChunkUnloadEvent OnChunkReuse(VoxelChunk chunk, out bool canReuse)

Fired when a chunk is about to be recycled (unloaded). Use to save chunk-specific data.

event VoxelChunkBeforeCreationEvent OnChunkBeforeCreate(Vector3d chunkCenter, out bool overrideDefaultContents, VoxelChunk chunk, out bool isAboveSurface)

Fired before a chunk is populated by the terrain generator. Override the chunk contents by modifying the voxel array directly.

event VoxelChunkEvent OnChunkAfterCreate(VoxelChunk chunk)

Fired after a chunk has been created and populated with terrain data.

event VoxelChunkBeforeDetailGenerationEvent OnChunkBeforeDetailGeneration(VoxelChunk chunk, VoxelPlayDetailGenerator generator, out bool cancelDetailGeneration)

Fired just before a detail generator runs on a chunk. Set cancelDetailGeneration = true to skip the generator for this chunk.

event VoxelChunkBeforeDetailGenerationEvent OnChunkBeforeDetailGeneration(VoxelChunk chunk, VoxelPlayDetailGenerator generator, out bool cancelDetailGeneration)

Fired just before a detail generator runs on a chunk. Set cancelDetailGeneration = true to skip the generator for this chunk.

event VoxelChunkEvent OnChunkAfterFirstRender(VoxelChunk chunk)

Fired the first time a chunk's mesh is rendered. Use for one-time initialization.

event VoxelChunkEvent OnChunkRender(VoxelChunk chunk)

Fired every time a chunk's mesh is refreshed (rebuilt).

event VoxelChunkEvent OnChunkExitVisibleDistance(VoxelChunk chunk)

Fired when a chunk leaves the visible render distance.

event VoxelChunkEvent OnChunkEnterVisibleDistance(VoxelChunk chunk)

Fired when a chunk enters the visible render distance.

Torch Events

event VoxelTorchEvent OnTorchAttached(VoxelChunk chunk, LightSource lightSource)

Fired when a torch is placed in the world.

event VoxelTorchEvent OnTorchDetached(VoxelChunk chunk, LightSource lightSource)

Fired when a torch is removed from the world.

Environment Events

event VoxelPlayEvent OnBeforeWorldLoad()

Fired just before the world initializes and all systems are created. Useful to set the world seed or change settings before loading.

event VoxelPlayEvent OnInitialized()

Fired when Voxel Play has finished initializing. Safe to start calling API methods.

event VoxelPlayEvent OnGameLoaded()

Fired when a saved game has been loaded.

event VoxelPlayEvent OnWorldLoaded()

Fired when the world has finished loading completely (save file loaded, world ready, engine idle).

event VoxelPlayEvent OnWorldLoaded()

Fired when the world has finished loading completely (save file loaded, world ready, engine idle).

event VoxelPlayEvent OnSettingsChanged()

Fired when Voxel Play settings are changed at runtime.

event VoxelPlayEvent OnSeeThroughHeightOffsetChanged()

Fired when the see-through height offset changes (camera enters/exits underground areas).

event VoxelPlayEvent OnPlayerEnterChunk()

Fired when the player enters a new chunk. Useful for region-based triggers.

event VoxelPlayEvent OnCollectVoxelDefinitions()

Fired during initialization to collect voxel definitions. Use this to call AddVoxelDefinition for runtime/scripted voxels so they are included in the initial texture arrays.

event VoxelPlayEvent OnCollectVoxelDefinitions()

Fired during initialization to collect voxel definitions. Use this to call AddVoxelDefinition for runtime/scripted voxels so they are included in the initial texture arrays.

event OriginShiftPreEvent OnOriginPreShift(Vector3 shift)

Fired before the world origin is shifted (floating-point precision management for large worlds).

event OriginShiftPostEvent OnOriginPostShift(Vector3 shift)

Fired after the world origin has been shifted. Update any world-space references in your scripts.

Model Events

event VoxelModelBuildStartEvent OnModelBuildStart(ModelDefinition model, Vector3d position, out bool cancel)

Fired when an animated model build starts (via ModelPlace with buildDuration).

event VoxelModelBuildEndEvent OnModelBuildEnd(ModelDefinition model, Vector3d position)

Fired when an animated model build completes.

event VoxelModelBuildEndWithIndicesEvent OnModelBuildEndWithIndices(ModelDefinition model, Vector3d position, List<VoxelIndex> indices)

Fired when an animated model build completes. Provides a list of VoxelIndex elements with the positions of placed voxels.

Terrain Events

event TreeBeforeCreateEvent OnTreeBeforeCreate(Vector3d position, ModelDefinition model)

Fired before a tree is created by the terrain generator. Return false to cancel tree creation at this location.

event TreeAfterCreateEvent OnTreeAfterCreate(Vector3d position, ModelDefinition model, List<VoxelIndex> indices)

Fired after a tree has been created. Provides the tree position and type.

Water Spread Events

event VoxelSpreadBeforeEvent OnVoxelBeforeSpread(VoxelDefinition voxeltype, Vector3d newPosition, VoxelDefinition voxelOnNewPosition)

Fired before a voxel spreads (water/lava flow). Return false from the handler to cancel the spread at this position.

event VoxelSpreadAfterEvent OnVoxelAfterSpread(VoxelDefinition voxeltype, Vector3d newPosition)

Fired after a voxel has spread to a new position.

Save/Load Events

event LoadGameEvent OnLoadCustomGameData(string tag, byte[] contents)

Fired when loading a saved game. Provides a tag and byte array for custom data previously saved with OnSaveCustomGameData.

event SaveGameEvent OnSaveCustomGameData(SaveGameCustomDataWriter writer)

Fired when saving the game. Use the SaveGameCustomDataWriter to write custom data that will be restored on load.

Water Spread Events

event VoxelSpreadBeforeEvent OnVoxelBeforeSpread(VoxelDefinition voxeltype, Vector3d newPosition, VoxelDefinition voxelOnNewPosition)

Fired before a voxel spreads (water/lava flow). Return false from the handler to cancel the spread at this position.

event VoxelSpreadAfterEvent OnVoxelAfterSpread(VoxelDefinition voxeltype, Vector3d newPosition)

Fired after a voxel has spread to a new position.

Save/Load Events

event LoadGameEvent OnLoadCustomGameData(string tag, byte[] contents)

Fired when loading a saved game. Provides a tag and byte array for custom data previously saved with OnSaveCustomGameData.

event SaveGameEvent OnSaveCustomGameData(SaveGameCustomDataWriter writer)

Fired when saving the game. Use the SaveGameCustomDataWriter to write custom data that will be restored on load.

Player Events

Class: Events in this section belong to VoxelPlayPlayer. Subscribe via VoxelPlayPlayer.instance.OnEventName += handler;
event OnPlayerInventoryEvent OnItemSelectedChanged(int selectedItemIndex, int prevSelectedItemIndex)

Fired when the player changes the selected item in the inventory. Provides the new selected item index and the previous selected item index.

event OnPlayerGetDamageEvent OnPlayerGetDamage(ref int damage, int remainingLifePoints)

Fired when the player receives damage. The damage parameter is passed by ref and can be modified to adjust the actual damage taken. Also provides the remaining life points after damage.

event OnPlayerIsKilledEvent OnPlayerIsKilled()

Fired when the player is killed (life reaches zero or below).

event OnPlayerInventoryItemQuantityChange OnItemAdded(ItemDefinition item, float quantity)

Fired when an item is added to the player inventory. Provides the ItemDefinition and the quantity added.

event OnPlayerInventoryItemQuantityChange OnItemConsumed(ItemDefinition item, float quantity)

Fired when an item is consumed from the player inventory. Provides the ItemDefinition and the remaining quantity.

event OnPlayerInventoryClear OnItemsClear()

Fired when all items are cleared from the player inventory.

Water Spread Events

event VoxelSpreadBeforeEvent OnVoxelBeforeSpread(VoxelDefinition voxeltype, Vector3d newPosition, VoxelDefinition voxelOnNewPosition)

Fired before a voxel spreads (water/lava flow). Return false from the handler to cancel the spread at this position.

event VoxelSpreadAfterEvent OnVoxelAfterSpread(VoxelDefinition voxeltype, Vector3d newPosition)

Fired after a voxel has spread to a new position.

Save/Load Events

event LoadGameEvent OnLoadCustomGameData(string tag, byte[] contents)

Fired when loading a saved game. Provides a tag and byte array for custom data previously saved with OnSaveCustomGameData.

event SaveGameEvent OnSaveCustomGameData(SaveGameCustomDataWriter writer)

Fired when saving the game. Use the SaveGameCustomDataWriter to write custom data that will be restored on load.

Water Spread Events

event VoxelSpreadBeforeEvent OnVoxelBeforeSpread(VoxelDefinition voxeltype, Vector3d newPosition, VoxelDefinition voxelOnNewPosition)

Fired before a voxel spreads (water/lava flow). Return false from the handler to cancel the spread at this position.

event VoxelSpreadAfterEvent OnVoxelAfterSpread(VoxelDefinition voxeltype, Vector3d newPosition)

Fired after a voxel has spread to a new position.

Save/Load Events

event LoadGameEvent OnLoadCustomGameData(string tag, byte[] contents)

Fired when loading a saved game. Provides a tag and byte array for custom data previously saved with OnSaveCustomGameData.

event SaveGameEvent OnSaveCustomGameData(SaveGameCustomDataWriter writer)

Fired when saving the game. Use the SaveGameCustomDataWriter to write custom data that will be restored on load.

Code Example

using VoxelPlay;

public class VoxelEventHandler : MonoBehaviour
{
    void Start()
    {
        var env = VoxelPlayEnvironment.instance;

        // Wait for initialization
        env.OnInitialized += () => {
            Debug.Log("Voxel Play ready!");
        };

        // Track voxel destruction
        env.OnVoxelDestroyed += (chunk, voxelIndex) => {
            Vector3d pos = env.GetVoxelPosition(chunk, voxelIndex);
            Debug.Log($"Voxel destroyed at {pos}");
        };

        // Modify voxel type or tint color before placement
        env.OnVoxelBeforePlace += (Vector3d position, VoxelChunk chunk, int voxelIndex,
            ref VoxelDefinition voxelType, ref Color32 tintColor) => {
            // Example: force all placed voxels to have a red tint
            tintColor = new Color32(255, 100, 100, 255);
        };

        // Custom chunk generation
        env.OnChunkBeforeCreate += (Vector3d chunkCenter,
            out bool overrideDefaultContents, VoxelChunk chunk,
            out bool isAboveSurface) => {
            overrideDefaultContents = false;
            isAboveSurface = false;
            // Add custom ore to every chunk after default generation
            for (int i = 0; i < chunk.voxels.Length; i++)
            {
                if (Random.value < 0.001f)
                {
                    VoxelDefinition ore = env.GetVoxelDefinition("Gold");
                    chunk.voxels[i].Set(ore);
                }
            }
        };

        // Monitor chunk lifecycle
        env.OnChunkEnterVisibleDistance += (chunk) => {
            // Load custom data for this chunk
        };
        env.OnChunkReuse += (VoxelChunk chunk, out bool canReuse) => {
            canReuse = true; // set false to prevent recycling
            // Save custom data before chunk is recycled
        };
    }
}
Was this page helpful?