# Voxel Documenation

:::info
Current Version: 0.8
[Devforum Post](https://devforum.roblox.com/t/update-voxel-free-volumetric-lighting-v08-late-beta-rewrite/3259368)
[Download (Itch.io)](https://sparkk-systems.itch.io/voxel)
:::

Voxel is a Roblox Volumetric Lighting/Fog engine that uses `BillboardGui` objects to imitate volumetrics.

This page is a guide to using the Voxel module in your experiences.

# Setup

To get started, place the module named `Voxel` inside of `ReplicatedStorage` (Recommended) or place it in any other Service accessible by the client.

Create a `LocalScript` inside of `StarterPlayerScripts` (Required) and add the following lines:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Voxel = require(ReplicatedStorage.Voxel)

local config : Voxel.VoxelSettings = {
	Density = 4,
	Opacity = 0.02,
	Distance = 100,
	finalOpacity = 0.01,
	texture = "rbxasset://textures/ui/GuiImagePlaceholder.png"
}

local VoxelInstance = Voxel.load(true, config)

# VoxelSettings

The `VoxelSettings` need to include (PascalCase):
* Density : number (any) -- How many `BillboardGui` objects per 10 studs
* Opacity : number (0-1) -- The opacity of each `ImageLabel` object
* Distance : number (any) -- The distance in studs of the Volumetric Lighting/Fog

Optional settings (camelCase):
* finalOpacity : number (0-1) -- Makes the opacity change from the start to the end `Opacity > finalOpacity`
* texture : string (Asset ID) -- Sets the image on `ImageLabel` objects

# Functions

.load
-

>[!Important] Needed
> `.load` is needed for Voxel to run

local VoxelInstance = Voxel.load(InitialState, VoxelSettings)

* `InitialState` is if Voxel is visible at start
* `VoxelSettings` is a `VoxelSettings` type

:set
-

Sets Settings

VoxelInstance:set(ChangedSettings)

* `ChangedSettings` is a table that includes changed `VoxelSettings`

:toggle
-

Toggles the State (Visibility)

VoxelInstance:set(Boolean)

:getCurrentState
-

Returns a Boolean depending on the State (Visibility)

local State = VoxelInstance:getCurrentState()

# Deprecated Functions

> Not Updated

These are functions that connect to the classic Voxel module `Voxel > VoxelClassic`, these are unstable and do not make use of OOP.

.Initiate
-

>[!Caution] Deprecated
> Use `.load` instead

Voxel.Initiate(segmentTable, lightInfluence, brightness, particles, particleTransparency)

* `segmentTable` is a Table of settings (not a VoxelSettings type)
* `lightInfluence` is a number that changes the `LightInfluence` property of the `BillboardGui` objects
* `brightness` is a number that changes the `Brightness` property of the `BillboardGui` objects
* `particles` is a boolean that enables the `particle` volumetype
* `ParticleTransparency` is a number that changes the `Transparency` value on the `ParticleEmitter` objects

Example of `SegmentTable`:

segmentTable = {	
	{length = 20, opacity = 0.995, distance = 0.5, color = Color3.new(1,1,1)},
	{length = 10, opacity = 0.993, distance = 1, color = Color3.new(1,1,1)},
	{length = 5, opacity = 0.99, distance = 4, color = Color3.new(1,1,1)},
	{length = 10, opacity = 0.99, distance = 5, color = Color3.new(1,1,1)},
}

.Toggle
-

>[!Caution] Deprecated
> Use `:toggle` instead

Voxel.Toggle(visible, volumetype)

* `visible` is a boolean that enables or disables VoxelClassic, does not affect Voxel
* `volumetype` is what volumetric lighting type you want to disable, this includes:
* `billboard`, toggles `BillboardGui` objects
* `particle`, toggles `ParticleEmitter` objects
* `both`, toggles both `billboard` and `particle`