Items & Models

advanced scripting

Voxel Play 3 · Scripting / API

Class: All members on this page belong to VoxelPlayEnvironment. Access via VoxelPlayEnvironment.instance.

Item Definitions

ItemDefinition GetItemDefinition(ItemCategory category, VoxelDefinition voxelType = null)

Returns the item definition for the given category and optional voxel type.

ItemDefinition GetItemDefinition(ItemCategory category, string objName)

Returns the item definition matching the category and object name.

ItemDefinition GetItemDefinition(string name)

Returns the item definition by name.

Item Spawning

GameObject ItemThrow(Vector3d position, Vector3 direction, float velocity, ItemDefinition itemDefinition)

Throws an item as a physics projectile from the given position. Returns the created GameObject.

direction: Throw direction (will be normalized).
velocity: Initial speed of the thrown item.

GameObject ItemSpawn(string itemDefinitionName, Vector3d position, int quantity = 1)

Spawns an item at the given world position. The item appears as a pickup in the world.

quantity: Number of items in the stack.

Torches

GameObject TorchAttach(VoxelHitInfo hitInfo, ItemDefinition torchDefinition = null, bool refreshChunks = true)

Places a torch at the location specified by a raycast hit. The torch is oriented based on the hit normal. Returns the torch GameObject.

torchDefinition: Torch item definition. If null, uses the default torch.
refreshChunks: Immediately refresh chunk lighting to include the new torch.

GameObject TorchAttach(Vector3d worldPos, Vector3 normal, ItemDefinition torchDefinition = null, bool refreshChunks = true)

Places a torch at a specific position with the given surface normal for orientation.

void TorchDetach(VoxelChunk chunk, GameObject gameObject)

Removes a torch from the world.

Model Placement

void ModelPlace(Vector3d position, ModelDefinition model, int rotationDegrees = 0, float colorBrightness = 1f, bool fitTerrain = false, List<VoxelIndex> indices = null)

Places a voxel model at the given position instantly.

rotationDegrees: Rotation in degrees (0, 90, 180, or 270).
colorBrightness: Color brightness multiplier.
fitTerrain: Adjust the model's vertical position to match terrain height.
indices: Optional output list of all voxel indices placed by the model.

void ModelPlace(Vector3d position, ModelDefinition model, out Boundsd bounds, int rotationDegrees = 0, float colorBrightness = 1f, bool fitTerrain = false, List<VoxelIndex> indices = null)

Places a model and outputs the world-space bounds of the placed model.

void ModelPlace(Vector3d position, ModelDefinition model, float buildDuration, int rotationDegrees = 0, float colorBrightness = 1f, bool fitTerrain = false, VoxelModelBuildEndEvent callback = null)

Places a model with an animated build effect over the specified duration.

buildDuration: Time in seconds for the build animation.
callback: Optional callback invoked when the build completes.

void ModelPlace(Vector3d position, Color[,,] colors)

Places a model defined as a 3D color array. Each non-transparent color becomes a colored voxel.

void ModelPlace(Vector3d position, VoxelDefinition[,,] voxels, Color[,,] colors = null)

Places a model defined as a 3D array of voxel definitions with optional per-voxel colors.

void ModelPlace(Vector3d position, Voxel[,,] voxels, bool useUnpopulatedChunks)

Places a model from a raw 3D voxel array.

void ModelPlace(VoxelChunk chunk, List<ModelBit> bits)

Places model bits directly into a chunk. Low-level method for custom model loading.

void ModelFillInside(ModelDefinition model)

Fills the interior of a hollow model with voxels. Useful for making models solid for physics.

Model Definition Creation

static ModelDefinition ModelDefinition.Create(int sizeX, int sizeY, int sizeZ)

Creates an empty model definition with the specified dimensions.

static ModelDefinition ModelDefinition.Create(int sizeX, int sizeY, int sizeZ, List<VoxelDefinition> voxelDefinitions, List<MicroVoxels> microVoxels = null)

Creates a model from a flat list of voxel definitions (one per position in XYZ order). Optionally includes microvoxel data per position.

static ModelDefinition ModelDefinition.Create(int sizeX, int sizeY, int sizeZ, List<Voxel> voxels, List<MicroVoxels> microVoxels = null)

Creates a model from a flat list of Voxel structs (extracted from chunks). Optionally includes microvoxel data per position.

static ModelDefinition ModelDefinition.Create(int sizeX, int sizeY, int sizeZ, VoxelDefinition voxelDefinition, List<Color> colors)

Creates a model using a single voxel type with varying per-voxel colors.

ModelDefinition ModelWorldCapture(Bounds bounds, bool captureVoxelTintColor = true)

Captures a region of the live world into a ModelDefinition, including voxel types, colors, microvoxels, properties and light sources.

Model GameObjects

GameObject ModelCreateGameObject(ModelDefinition modelDefinition)

Creates a standalone Unity GameObject from a voxel model definition. Not part of the voxel grid.

GameObject ModelCreateGameObject(ModelDefinition modelDefinition, Vector3 offset, Vector3 scale)

Creates a model GameObject with custom position offset and scale.

GameObject ModelHighlight(ModelDefinition modelDefinition, Vector3d position)

Creates a semi-transparent preview of the model at the given position. Useful for build placement previews.

UI & Messaging

void ShowMessage(string txt, float displayDuration = 4, bool flashEffect = false, bool openConsole = false, bool allowDuplicatedMessage = false, string colorName = null)

Displays a message in the in-game console.

displayDuration: Seconds the message remains visible.
flashEffect: Flash the message for emphasis.
openConsole: Automatically open the console panel.
colorName: HTML color name for the message text.

void ShowError(string errorMessage)

Displays an error message in the console (red text).

void LogMessage(string txt)

Logs a message to the console without displaying it as a popup.

void SetBuildMode(bool buildMode)

Enables or disables the built-in build mode UI, allowing the player to place and remove voxels.

Code Example

using VoxelPlay;

public class VoxelCrafter : MonoBehaviour
{
    public ModelDefinition houseModel;

    void PlaceHouseAtCursor()
    {
        var env = VoxelPlayEnvironment.instance;

        // Raycast to find placement point
        Ray ray = Camera.main.ScreenPointToRay(Input.mousePosition);
        if (env.RayCast(new Rayd(ray), out VoxelHitInfo hit, 50f))
        {
            // Show build preview
            env.ModelHighlight(houseModel, hit.voxelCenter);

            if (Input.GetMouseButtonDown(0))
            {
                // Build with animation
                env.ModelPlace(
                    hit.voxelCenter + Vector3d.up,
                    houseModel,
                    buildDuration: 2f,
                    callback: (model, pos) => {
                        env.ShowMessage("House built!");
                    }
                );
            }
        }
    }

    void SpawnTorch()
    {
        var env = VoxelPlayEnvironment.instance;
        Ray ray = Camera.main.ScreenPointToRay(Input.mousePosition);

        if (env.RayCast(new Rayd(ray), out VoxelHitInfo hit, 20f))
        {
            env.TorchAttach(hit);
        }
    }
}

Was this page helpful? |