Voxel Play Environment Options

Modified on Thu, 25 May 2023 at 07:30 PM

Select your Voxel Play Environment in the hierarchy to show the current environment options:



The Voxel Play Environment script allows you to customize general gameplay settings, quality and effects, voxel generation as well as the sky properties.


Note that you can define any number of worlds separately (see Creating Worlds section) and assign one of them to the Voxel Play Environment component.


Also you can customize any of this properties from script using VoxelPlayEnvironment.instance.property = xxx.



General Section


  • Character Controller: the character controller script reference (automatically assigned when you create the Voxel Play FPS Controller).
  • World: assign your world definition asset to this slot. Voxel Play comes with a sample world (Earth) and you can duplicate, modify or create your own worlds (see Creating World Definitions section). Although the World Definition is stored in a separated ScriptableObject file, you can expand/collapse the world settings right here clicking on the button:


  • Render in Editor: check this option to render the Voxel Play environment at Editor time – this option is useful if you want to populate the scene according to the voxel terrain. The “Low Priority” toggle pauses the rendering if you move the camera in the Scene View so it reduces any lag while you operates in the Scene View.

Click “Regenerate” to delete all voxels and creates them again. Clicking this button will automatically enable the “Render In Editor” option.

Click “Delete Chunks” to delete all voxels and disable the “Render In Editor” option in one step.



Quality and Effects


  • Global Illumination: in addition to support for daylight time and Unity standard shadows, Voxel Play computes light bounces on the environment – you can test this feature as you dig on the terrain – as you move to the inner areas of the ground, the light will be reduced until you get pitch black. Same occurs if you cover your position with voxels or cover all windows in a room: everything will go black. Use torches to illuminate your path into the closed areas or underground. This option is also known as "Smooth Lighting".
    If you disable this option, Voxels will only be affected by daylight and shadows. It will also increase the performance of the chunk generation (once they are generated or updated, performance won’t be affected).
  • Enable Shadows: when checked, voxels will cast and receive shadows. Shadows can be deactivated to improve performance on mobile devices.
  • Shadows On Water: when checked, water voxels will use a grabpass to blend shadows into water which can be time-consuming in some systems. Consider this option as a high-end FX option.
  • Smooth Lighting: during the chunk generation, Voxel Play computes vertices occlusion and adds this information to the mesh. This effect adds more depth and beauty to the environment and is very fast as no additional render passes nor SSAO image effects are required. Torch lighting is also included in this computation. If you disable this option, generation and rendering will be a bit faster although light differences between faces will be more visible.
  • Ambient Light: this is the minimum amount of light when no other illumination affects any voxel – this is only used on voxels above ground and represent the atmosphere or ambient light caused by stars and the Moon.
  • Texture Size: allows you to control the size of the textures. It's recommended that you rescale and optimize your voxel textures using the same size - Voxel Play will automatically scale any texture that does not match the size given here so if you're using bigger textures the extra disk space required will be wasted.
  • Enable Tinting: when enabled, voxels support individual tint color. You can set specific voxel colors when calling VoxelPlace method. Note: Voxel Play shaders use texture arrays. The number of textures that can be used using this method is usually maxed at 256 for OpenGL 3.x (higher in later versions). If you need more than 256 voxel variations, enable this option. Then you can use the same textures with different colors when placing voxels at performance expense. By default this option is disabled, which means that you can only use textures for voxels (if you need a pure red and pure yellow voxel then you need to use two textures but if you enable this option you can use the same white texture and tint it in red or yellow depending on the voxel).
  • Double Sided Glass: this option controls whether the transparent voxel types render the opposite face. Note that even with this option enabled, Voxel Play will optimize the face count when multiple transparent voxels are placed together so only the boundary faces are visible.
  • Transparent Bling: enables/disables a quick random reflection/bling effect on transparent/glass voxels. This effect only occurs every 5-6 seconds aprox.
  • Enable Outline: adds a colored outline around solid voxels (no vegetation, tree leaves or water for example). The outline effect is embedded into the shader itself so it's quite fast.
  • Normal Mapping: enables normal maps on voxels. Normal maps should be assigned for all voxel textures. Normal maps do not use alpha channel so you can save them using PNG RGB format for example.
  • Relief Mapping: enabled parallax occlusion mapping using relief mapping variation which adds elevation to textures. The displacement map is an elevation map that only uses grayscale colors. Voxel Play will use the red channel of the texture, regardless of the format. You can use PNG Grayscale format for the displacement maps.
  • Enable Curvature: enables shader-based curvature. This is a vertex displacement effect that applies to all Voxel Play shaders. The asset also includes 3 standard shaders compatible with curvature (VoxelPlay/FX/Curved/Standard, Standard Emission and Unlit). Read included shaders for more details.
  • See-Through: when this option is enabled, any voxel occluding the character (ie. voxels between camera and character within a given radius) will be rendered with transparency so the character remains visible. You can customize the radius of the effect as well as a height offset which is the elevation from the current character altitude (to avoid making the ground transparent). For details about this effect please visit the SeeThrough help page in Advanced Features section.



Voxel Generation


This section allows you to control the generation and rendering voxel engine:


  • Chunks Pool Size: enter the total number of chunks that Voxel Play can reserve. When new chunks are required and all the slots in the pool have been used, old slots will be reused to create new chunks (old or distant chunks will be “discarded” and their memory reused for the new chunks).
  • Prewarm in Editor: while in Unity Editor, instead of allocating the entire pool size at start, Voxel Play will just reserve this amount of chunk memory so game can start faster during development inside the editor. Please note that as this group of chunks have been used, a new set of the same amount of chunks will be reserved which will cause a GC spike in the profiler. This is normal behaviour and won't occur in the build since the entire pool is reserved at start. You can also set a value for Prewarm equal to the total Chunk Pool Size, then the behaviour will be very similar with respect to a build.
  • Low Memory Mode: don't preserve memory for internal rendering buffers which results in faster start up and also minimum memory requirements. It's recommended to use this option on mobile or WebGL platforms.
  • Loading Screen: Voxel Play can show a loading screen while chunks pool is created.
  • Used (%): the amount of chunks or percentage of pool currently used.
  • Only Render in Frustum: as the title says, enabling this option will avoid generating and/or rendering any chunk that’s not visible (inside the camera’s frustum). This option makes the visible chunks render a lot faster.
  • Visible Chunk Distance: the distance of the farther chunk that will be generated or rendered (a value of 10 means 10 chunks in front of the player – each chunk contains 16x16x16 voxels).
  • Unload Far Chunks: when this option is enabled, chunks further than Visible Chunk Distance will be disabled and re-enabled when they enter the visible distance.
  • Force Chunk Distance: this is the distance where all chunks will be generated and rendered before game starts. If player “teleports” to a new area, game will pause until all chunks inside the “Force Chunk Distance” are rendered.
  • Max CPU Time Per Frame: enter the FPS budget dedicated to generate chunk content. This is the maximum time per frame that Voxel Play will spend. For example, a value of 30 means do not use more than 30ms. Note that if all visible chunks are rendered, Voxel Play will be idle until you move the character position or rotate the camera and new chunks need to be generated.
  • Max Chunks Per Frame, Max Trees Per Frame, Max Bushes Per Frame: these values control the maximum number of chunks, trees or bushes that can be generated on every frame. Usually you will want to give priority to chunks, then trees and bushes, hence a value of 50 for chunks and 10 for trees and bushes each are the default values.
  • Enable Collliders: when enabled, Voxel Play will automatically generate collider meshes for the opaque voxels contained in a chunk (no collider is generated for vegetation or tree leaves).
  • Enable Trees / Enable Vegetation: quick toggles to remove / allow trees and vegetation generation.
  • Dense Trees: when enabled, additional faces are added to regular leaf voxel creating a denser foliage. If disabled, only visible faces will be rendered which leads to shallower trees (and also can improve performance on low-end platforms).



Sky Properties


Common settings related to the sky shared by all worlds:

  • Sun: choose a directional light in your scene that represent the Sun.
  • Fog Amount, Fog Distance, Fog Falloff: controls the appearance of the fog in the scene. The fog produces a smooth transition between terrain and the far clip distance of the camera. You can configure additional sky properties in the World Definition file.
  • Enable Clouds: generates and animates random cloud voxel shapes.


UI & Game Features


These are some public properties exposed by VoxelPlayEnvironment script that you can change in the inspector in addition to using scripting (C#):

  • Enable Build Mode / Build Mode ON: the build mode enables the player to destroy and place new voxels with a single click. In Build Mode all available voxels in the world are automatically available in the player inventory. Note that Build Mode is only available in Play Mode when user pressed key B.
  • Enable Console / Show Console: shows the console in the Game View by pressing F1 (only available in Play Mode).
  • Enable Status Bar / Status Bar Color: shows/hides status bar.
  • Enable Inventory: enables/disables built-in inventory UI, shown when user presses TAB key.
  • Enable Debug Window: enables/disables built-in top debug window, shown when user presses F2 key.
  • Save Filename: this is the default save file that will be loaded when game starts. If no file with this name exists, Voxel Play will ignore this option and will generate the world according to the defined settings. At runtime you can modify this value using scripting (C#) to enable the player save their changes in different files.
  • Welcome Text / Welcome Duration: this is an optional message that’s displayed during the start of the game for the duration specified.
  • UI & Crosshair Prefabs: in case you want to customize the UI Canvas provided by Voxel Play, create a duplicate of the existing prefab in Resources/VoxelPlay/UI and assign the new prefabs here.
  • Particles Layer: when a voxel is hit or destroyed, a few particles are created. The particles uses physics to bounce over the voxels. To optimize collision checks, particles can’t collide each other and to allow this, it’s necessary to assign all particles to the same layer. You can choose any layer or leave the default layer for this. Do not choose a layer where the player can belong to.
  • Voxels Layer: the layer used to render chunks.


The behaviour of saving the ongoing game changes if you’re running in Unity Editor or in a build:

  • In Unity Editor: Voxel Play will look for any savefile resource located inside the World Definition folder (example: Voxel Play/Resources/Worlds/Earth/SavedGames folder). When you save any change in Play Mode, Voxel Play will replace this resource file.
  • In a Build: Voxel Play will look for any savefile located in the Application.PersistentDataPath folder. If none is found, it will try to load any default resource with same name in Voxel Play/Resources/Worlds/Name of World/SavedGames. When you save any change, Voxel Play will save the modifications inside Application.PersistentDataPath folder.



Default Assets


This section allows you to define default sounds if the voxels don't use specific ones. It also enables you to specify a custom voxel definition as the default voxel type. The default voxel is used when you use methods to create voxels based on a color. For example, you call VoxelPlace(position, Color.red). In this case, Voxel Play will use the default voxel and tint it in red.


Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons

Feedback sent

We appreciate your effort and will try to fix the article