Troubleshooting

intermediate troubleshooting

Voxel Play 3 · Troubleshooting & FAQ

Troubleshooting

Common issues encountered when working with Voxel Play 3, with causes and solutions.

Scene & Setup Issues

SymptomCauseSolution
No terrain appears at play time World Definition not assigned or terrain generator missing Select the VoxelPlayEnvironment GameObject and assign a World Definition in the inspector. Ensure it has at least one terrain generator and one biome.
Player falls through the world on start Chunks have not finished generating before the player spawns Enable Wait For Terrain in the FPS Controller options, or set a fixed spawn point on solid terrain. See Avoid Fall Below Terrain.
Pink / magenta voxels Shaders not compiled for the current render pipeline If using URP, ensure the Voxel Play URP shaders are imported. Check Edit > Project Settings > Graphics for the correct pipeline asset. See URP Support.
Console error: "VoxelPlayEnvironment not found" Missing VoxelPlayEnvironment component in the scene Add VoxelPlayEnvironment to a GameObject or use the menu GameObject > Voxel Play > Create Voxel Play Environment.
Voxels render but no collisions Collider generation is disabled or chunk distance too large Check Environment Options > Colliders settings. Reduce chunk distance if mesh colliders are consuming too much memory. See Colliders & NavMesh.

Rendering & Visual Issues

SymptomCauseSolution
Shadow flickering on voxel surfaces Shadow bias too low or shadow distance too large for the scene scale Increase shadow bias in the directional light. Reduce shadow distance. See Shadows Flicker.
Water is opaque / not transparent in URP Depth texture not enabled on the URP asset Select the URP Renderer asset and enable Depth Texture. See Water Not Transparent in URP.
Texture seams or bleeding between voxels Mipmap bleeding from texture atlas Enable Custom Texture Packing with padding, or increase texture atlas resolution. See Custom Texture Packing.
Chunks pop in or disappear abruptly Chunk pool size too small or view distance changes at runtime Increase Chunk Pool Size in Environment Options. Avoid changing view distance rapidly. See Chunk Distance.
Regular Unity lights do not affect voxels Voxel Play uses its own lighting system by default Enable Use Unity Lights in Environment Options, or configure point light voxel sources. See Regular Lights.

Performance Issues

SymptomCauseSolution
Low FPS with large view distances Too many chunks being rendered simultaneously Reduce view distance. Enable Low Memory Mode. Use chunk pool size of 5000–8000 for mobile. See Mobile Support.
GC spikes in the Editor profiler Editor overhead and debug allocations Profile in a standalone build. Editor GC is not representative of runtime. See Profile GC Spikes.
Memory usage keeps growing Chunks are not being recycled Enable Unload Far Chunks and verify chunk pool is not set to unlimited. Check Chunk Lifecycle.
WebGL crashes with out-of-memory Default WebGL memory allocation too small Increase WebGL memory to 1024 MB minimum in Player Settings. Enable Low Memory Mode.

Scripting & API Issues

SymptomCauseSolution
VoxelPlayEnvironment.instance returns null Code runs before Voxel Play initializes (e.g., in Awake) Use Start() or subscribe to the OnInitialized event. See Events.
Voxel changes not visible after VoxelPlace Chunk mesh not refreshed Use VoxelPlace with refresh: true parameter, or call ChunkRedraw after batch operations. See Voxel Operations API.
Save file does not restore custom voxels Custom voxel definitions not registered before loading Register all custom VoxelDefinition assets before calling LoadGame. See Loading & Saving.
Events fire multiple times Subscribing to events in OnEnable without unsubscribing in OnDisable Always unsubscribe in OnDisable or use -= before +=. See Events.

Multiplayer Issues

SymptomCauseSolution
Voxel changes not syncing between clients Custom voxel operations not using the multiplayer API Use the VoxelPlayMultiplayer methods instead of direct voxel calls. See Multiplayer API.
Different terrain on host vs client Different random seeds or world definitions Ensure all clients use the same World Definition and seed. The seed is set in the World Definition asset.

Still Stuck?

Was this page helpful?