Scripting Support (C#)

Getting Started

Add using VoxelPlay; at the top of your script. VP4 APIs use the same patterns as VP3. No additional setup is needed beyond importing the Voxel Play package.

using UnityEngine;
using VoxelPlay;

public class MyScript : MonoBehaviour {
    public ModelDefinition model;

    void Start() {
        // Create a standalone textured GameObject from a model
        GameObject go = VoxelPlayEnvironment.ModelCreateGameObject(model);
        go.transform.position = Vector3.zero;

        // Export the model to OBJ for external tools
        VoxelPlayOBJExporter.ExportModelToOBJ(model, Application.dataPath + "/../Export");
    }
}

OBJ Export

VoxelPlayOBJExporter is a static utility class for exporting voxel models to OBJ format with textures.

ExportModelToOBJ

static string ExportModelToOBJ(
    ModelDefinition md,
    string outputFolder,
    Vector3? scale = null,      // null = Vector3.one
    bool useTextures = true     // false = geometry only
);

Exports a ModelDefinition to .obj + .mtl + PNG textures. Returns the path of the generated OBJ file, or null on failure. Supports regular voxels, microvoxels with dual materials, and rotated model bits.

ExportVoxelToOBJ

static string ExportVoxelToOBJ(
    VoxelDefinition vd,
    string outputFolder,
    Vector3? scale = null,
    bool useTextures = true
);

Exports a single VoxelDefinition (including its microvoxels and secondary material) to OBJ.

Model Conversion (Enhanced)

VoxelPlayConverter static methods for generating standalone GameObjects. These existing methods now include full microvoxel texture support with primary/secondary material routing.

GenerateVoxelObject (ModelDefinition)

static GameObject GenerateVoxelObject(
    ModelDefinition md, Vector3 offset, Vector3 scale,
    bool useTextures = true, bool useNormalMaps = true,
    bool usePBR = false, GameObject updateGameObject = null
);

Generates a textured GameObject from a ModelDefinition. Mixed models (regular + microvoxel bits) are packed into a single mesh with a single TextureArray material. Pass an existing GameObject via updateGameObject to update it in place.

GenerateVoxelObject (VoxelDefinition)

static GameObject GenerateVoxelObject(
    VoxelDefinition vd, Vector3 offset, Vector3 scale,
    bool useTextures = true, bool useNormalMaps = true,
    bool usePBR = false, GameObject updateGameObject = null
);

Generates a textured GameObject from a single VoxelDefinition. Microvoxels render with correct primary and secondary textures based on the layout mode (Slabs, TopCap) and per-quad palette routing.

Convenience Wrappers

// On VoxelPlayEnvironment (instance or static)
GameObject ModelCreateGameObject(ModelDefinition md, ...);
GameObject VoxelCreateGameObject(ModelDefinition md, ...);

Delegate to VoxelPlayConverter.GenerateVoxelObject. Signatures unchanged from VP3.

Microvoxel Thumbnails

// MicroVoxels instance method
Texture2D GenerateThumbnail(int width = 256, int height = 256);

Renders a preview image of the microvoxel shape to a Texture2D. Uses a temporary camera and command buffer - no scene objects are affected. Works at runtime and in the editor. The caller is responsible for destroying the returned texture.

PBR Texture Packing

// TextureTools static method
static Texture2D PackSurfaceMap(
    Texture2D metallic, Texture2D smoothness,
    Texture2D occlusion, Texture2D height,
    int resolution = 256
);

Packs four separate PBR channel textures into a single surface map for the VP PBR model shader. Call at runtime or use the editor utility under the VoxelDefinition inspector.

Model Placement

// VoxelPlayEnvironment - enhanced ModelPlace
void ModelPlace(
    Vector3d position, ModelDefinition model,
    ...,
    bool skipEmptyVoxels = false
);

New skipEmptyVoxels parameter. When true, empty positions in the model do not overwrite existing voxels (e.g. water), so models can be placed inside filled volumes without creating air pockets.

Biome Lookup

// VoxelPlayEnvironment - new 3-parameter overload
BiomeDefinition GetBiome(float altitude, float moisture, float temperature);

Adds the temperature axis for VP4's 3-axis biome selection. See Biome System Upgrades for details on configuring BiomeZone temperature ranges.

Microvoxel methods

Six new overloads on VoxelPlayEnvironment for placing and destroying microvoxels at an explicit world position, without a VoxelHitInfo or normal-based offset. Designed for procedural generators and world-edit / brush tools. They share the existing MicroVoxelPlace / MicroVoxelDestroy name; C# discriminates by the 2nd parameter type (int = cube, Vector3d = AABB, float = sphere radius).

Cube at position

bool MicroVoxelPlace(Vector3d position, int size, VoxelDefinition voxelType, Color tintColor = default, int rotation = 0);
bool MicroVoxelDestroy(Vector3d position, int size, float probability = 1f);

Places or destroys a cube of size x size x size microvoxels centered on a world position. When microVoxelsSnap is enabled (default) and the cube fits in a single parent voxel, a fast path skips per-microvoxel lookups and just toggles bits.

Axis-aligned bounding box

bool MicroVoxelPlace(Vector3d boxMin, Vector3d boxMax, VoxelDefinition voxelType, Color tintColor = default, int rotation = 0);
bool MicroVoxelDestroy(Vector3d boxMin, Vector3d boxMax, float probability = 1f);

Fills or clears every microvoxel whose center lies inside the given AABB. Bounds are taken as-is (no snap), so callers can paint arbitrary rectangular regions.

Sphere brush

bool MicroVoxelPlace(Vector3d center, float radius, VoxelDefinition voxelType, Color tintColor = default, int rotation = 0);
bool MicroVoxelDestroy(Vector3d center, float radius, float probability = 1f);

Sphere brush. radius is in world units (1 unit = 1 voxel; MicroVoxels.SIZE = 1/16 unit per microvoxel). Microvoxels whose center is within radius of center are placed or removed.

Demo 1 (Earth) exposes these on the keyboard: P paints a 4x4x4 cube, K destroys it, U paints a sphere, all using the currently selected inventory voxel.