> For the complete documentation index, see [llms.txt](https://thebitcave.gitbook.io/magicavoxel-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://thebitcave.gitbook.io/magicavoxel-resources/shaders/shader-reference.md).

# Shader Reference

## Introduction

In MagicaVoxel, a shader is a fragment of code used to generate shapes and colors in your project. Basically it's a processor for your voxel model.

You can execute a shader by typing the `xs` command in the console:

```
xs [option] [shader-name] [arg0] ... [arg7]
```

The shader-name parameter will be based on the shader itself. You can add up to 8 parameters (`arg0` to `arg8`), if the shader expects them.

Available options are:

* `-n`: followed by a number, it will iterate the shader a number of times

{% hint style="info" %}
For an introductory tutorial, please check the [Writing Your First Shader](/magicavoxel-resources/tutorials/writing-your-first-shader.md) tutorial.
{% endhint %}

## Built-in

A shader comes with a number of built-in functions and inputs.

### Inputs

These are the available inputs you can use in your shader:

* `uniform vec3 iVolumeSize`: the voxel volume (i.e.: the object you are editing) dimensions
* `uniform float iColorIndex`: the selected color index in the current editor palette
* `uniform vec3 iMirror`: the editor *Mirror Mode* (0 if not enabled, 1 if enabled) for each direction (x, y, z)
* `uniform vec3 iAxis`: the editor *Axis Mode* (0 if not enabled, 1 if enabled) for each direction (x, y, z)
* `uniform float iIter`: the current iteration index
* `uniform vec4 iRand`: a random number
* `uniform float iArgs[8]`: an array of user parameters. Use it to pass any custom data you may need

### Functions

These are the available functions you can use in your shader:

* `float voxel(vec3 v)`: returns the voxel color index at position `v`. If no voxel is present, it will return 0

### The map() Function

Each shader should have a `map()` function with this syntax:

```
float map(vec3 v) {
  // your code here
}
```

This method will generate a new voxel (of a defined color index) al position `v`.

#### Example

The following code will fill the full space of your voxel model wil voxels of color index 4:

```
float map(vec3 v) {
	return 4;
}
```

![The result of the above code](https://2848349403-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M1GLjicm2G4TkYoBqY2%2F-M4mhDUhGDQoJ62nRjJu%2F-M4mrQZjN3LbINnQ0-g1%2Fbasic_shader.png?alt=media\&token=7facc81c-d595-460e-94ea-2a577b049ffa)