Voxels and Voxel Definitions

A voxel definition specifies the type of voxels your world will render. It's like a template for voxels and includes information like textures, render style, resistance points and other attributes for a single voxel. Voxel definitions are used extensively in the framework either in the biomes collection, when placing voxels on the world using scripting, etc.

Check out this video to learn how to create a voxel definition:

Current Voxel Definition's fields include:

• Render Type: choose one of the following:
  • Opaque 3 textures (fully opaque, no ambient occlusion). Allows 3 textures: top, down and sides. Does not cast ambient occlusion.
  • Opaque 3 textures (normal terrain voxels, fully opaque and cast shadows, occlusion). Allows 3 textures: top, down and sides.
  • Opaque 3 textures with animation. Adds animation feature (see "Additional Textures" below).
  • Opaque 6 textures: similar to Opaque voxels but allows up to 6 different textures, one per each side. Also allows rotation (see VoxelRotateTextures method).
  • Opaque No AO (special voxels, fully opaque but do not get global illumination nor occlusion)
  • CutOut: voxels with transparent parts inside them (like tree leaves).
  • CutOut Cross: used by vegetation.
  • Water: used by water, lava, etc.
  • Transparent: similar to Opaque 6 textures type but allows transparency. Can render in double sided mode (see Double Sided Glass option in Voxel Environment inspector).
  • Empty: does not render geometry but can produce colliders and NavMesh if wished. Useful to create invisible barriers.
  • Custom: this voxel will be rendered as a normal gameobject defined by the model property. Check this page for more info about custom voxels.
• Custom Packing: custom packing refers to the ability to pack the textures in a different texture array which allows you to use different texture sizes (by default, all textures are rescaled to the texture size setting in Voxel Play Environment inspector - but using custom packing you can override this behaviour and use a different texture size only for this voxel definition). See more details about custom packing here.
• Override Material: allows you to use a custom material/shader for rendering this voxel. Note that this option only applies to the default render types above except Custom (custom voxels always use the material associated to the custom gameobject or will use a default VP Model material by default). This is an advanced option which requires shader knowledge as you have to provide an alternate material and shader. Check Overriding Material section for more details.
• Texture Top: this is the top texture of the voxel. When "Dense Trees" option is enabled, this texture is used for part of the meshes of the tree leaves that sticks out from the regular block.
• Texture Side / Front / Back / Left / Right: the texture for the side of the voxel (only Opaque/Transparent 6 textures types show a different texture slot per side).
• Texture Bottom: texture for the bottom of the voxel.
• Additional Textures: when render type is set to Opaque 3 textures with animation, you can add additional textures in this slot and specify a transition speed.
• Emission Intensity: a value greater than 0 will cause the voxel to emit light. This light contribution is added to the voxelized lighting (smooth lighting). It's not a regular light so only regular voxels or gameobjects using the Voxel Play Behaviour with "Enable Voxel Light" option enabled will receive this emitted light.
• Compute Lighting: for custom voxels, this option calculates the surrounding light levels and bake it into the vertex colors of the mesh. This allows the custom voxel to show a smoother transition of light across its vertices. Note: this option is experimental and due to the variety of shape that a prefab can have, results can vary from one prefab to a different one. This option is also expensive so do not use it on custom voxels that may be placed massively.
• Place Facing Player: if enabled, when the player places a voxel of this type it will be rotated facing the player. Only available for types supporting 6 textures.
• Texture Rotation: if enabled, the side textures can be rotated using code (see VoxelRotateTextures method). Only available for types supporting 6 textures.
• Resistance Points: the hit points for the voxel before being destroyed. There’re two special values: 0 means the voxel cannot be hit (like water) while 255 means the voxel cannot be damaged.
• Build Sound: the sound played when the player places a voxel of this type.
• Footfalls: a list of footstep sounds when the player walks over this voxel.
• Jump / Landing sound: custom sounds when the player jumps or lands on this voxel.
• Impact / Destruction sounds: custom sounds for damaging or destroying this voxel.
• Can Be Collected: whether this voxel can be added to the player inventory upon destruction.
• Navigatable: whether this voxel can be included in the NavMesh generation (only opaque voxels are considered).
• WindAnimation: used by CutOut render type. Specifies if this voxel receives wind animation. Most tree leaves use CutOut render type and has WindAnimation set to true but some times don't (ie. cactus).
• Model: the model property is available when Render Type is set to Custom. Assign your own gameobject (prefab) and Voxel Play will instantiate it when this voxel type is used.
  • Offset: models are placed on the center of the voxel space. This parameter lets you add a displacement for the voxel center. For example, half-height voxels have a -0.25 in the offset y to align them with the bottom (and a y-scale of 0.5f to cover the half of the voxel).
  • Scale: scale for the model. This value is multiplied by the actual model gameobject scale.
  • Rotation: rotation for the model.
• PromotesTo: specifies another Voxel Definition to which this voxel changes when placing another copy on the same location. Useful for converting half-blocks into full-blocks. In your half-block definition assign a full-block voxel type to this property and Voxel Play will replace the half block by the full sized block.
• Trigger Collapse: if this voxel is destroyed, voxels above and nearby will fall if they're flagged with "Will Collapse" attribute.
• Will Collapse: if true, this voxel type will be included in the falling group of voxels. For example, a tree bark can have both Trigger Collapse and Will Collapse flags while tree leaves should only be marked with "Will Collapse" as destroying a leave won't cause the tree to fall.
• Spreads: only available on Water render type. Specifies if this voxel type will spread or flood.
• Drains: only available on Water render type. Specifies if the amount of water is reduced when the liquid expands. This setting is usually applied to normal water voxels (the water one can pick up and place) while the Sea water should have this setting set to false (to prevent player from draining the Sea or a lake).
• SpreadDelay: the interval at which the voxel propagates in seconds.
• SpreadDelayRandom: additional delay that's added to the SpreadDelay to produce a random spread effect (the additional value will be a random value between 0 and SpreadDelayRandom).
• DiveColor: the color used to render the underwater effect.
• PlayerDamage: the damage taken by the user when in contact with this voxel type.
• PlayerDamageDelay: the interval in seconds between damage hits by this voxel type.
• IgnoresRayCast: RayCastFast will pass through this voxel type.
• Trigger Enter Event: enable to raise an OnVoxelEnter event from the FPS controller when player enters a voxel of this type. Only occurs if voxel is not solid, like empty, water, cutout or vegetation.
• Trigger Walk Event: enable to raise an OnVoxelWalk event from the FPS controller when player walks on a voxel of this type.

How to create Custom Voxel Definitions (ie. half blocks or voxels with other shapes)

In Voxel Play you can specify that a voxel definition uses a different mesh instead of the normal cube. In fact what you can specify is a whole gameobject which can also carry custom scripts. Voxel Play will create a copy of the gameobject (aka model) when generating the chunk. Note that Voxel Play bakes the colors and lighting into vertices so as long as you use one of the "VP Model*" materials included in VoxelPlay / Resources / Materials all instances of the model will use dynamic batching to reduce draw calls.

Voxel textures requirements

To use a texture in a voxel make sure you have the correct Import Settings:

• Read/Write enabled
• MipMaps: disabled
• Filter: point
• Wrap Mode: repeat

Example:

Voxel Play packs all textures in a texture array and all texture must have the same size defined by the Texture Size parameter of Voxel Play Environment component. Textures will automatically be rescaled on demand to fit that resolution.

Where voxel definitions are stored and referenced

Voxel Play will find and load all voxel definitions stored under any folder under the main folder of your world.

The world folder should be inside any Resources folder.

Voxel definitions can also be stored anywhere if they're referenced by any world structure. For example, the World Definition has a More Voxels section which you can use to manually add references to voxel definitions that are not located under the World definition folder. Same applies if you add voxel definitions to a biome (like vegetation or models).

Example of folder organization:

In the screenshot above, the Earth world definition asset is located inside the Earth folder. Then, there can be any number of subfolders, each one with any number of assets, voxel definitions, materials, textures, etc.

You can also create voxel definitions at runtime and add them to the system using the AddVoxelDefinition method. Check out this page for more information.