Voxel2Pixel

Voxel2Pixel is an MIT-licensed C# 13.0 .NET Standard 2.0 library created by Ben McLean for rendering voxel models as pixel art assets from a variety of fixed camera perspectives and palette limitations intended for use in retro-styled video games.

Also in this repo is the BenVoxel project to develop an open standard for interoperable voxel model file formats.

Usage

Importing a model

VoxFileModel model = new(@"..\..\..\Sora.vox");
IVoxelColor voxelColor = new NaiveDimmer(model.Palette);

The VoxFileModel class is used for importing MagicaVoxel files. The Sora.vox file contains a test model based on the character Sora from Kingdom Hearts.

Colors are specified in RGBA8888 format. The IVoxelColor interface is used to determine which colors to draw sprites with. The NaiveDimmer class implements IVoxelColor by interpolating lighter and darker versions from the provided palette, which in this snippet comes from the imported MagicaVoxel file.

Drawing a sprite

Sprite sprite = new SpriteMaker
{
	Model = model,
	VoxelColor = new NaiveDimmer(model.Palette),
	Perspective = Perspective.Iso,
	Outline = true,
	ScaleX = 2,
}.Make();
byte[] texture = sprite.Texture;
ushort width = sprite.Width,
	height = sprite.Height;

The SpriteMaker class uses builder pattern to construct Sprite objects.

The Sprite class provides a byte[] Texture array containing RGBA8888 format pixels and a ushort Width property for the texture's size. These would be referenced to export images.

Creating a texture atlas

Dictionary<string, Sprite> sprites = [];
byte direction = 0;
foreach (SpriteMaker spriteMaker in new SpriteMaker()
	{
		Model = model,
		VoxelColor = new NaiveDimmer(model.Palette),
		Outline = true,
	}.Iso8())
	sprites.Add("Sprite" + direction++, spriteMaker.Make());
Sprite output = new(sprites, out TextureAtlas textureAtlas);

The SpriteMaker.Iso8 method generates makers for a series of 8 sprites using alternating isometric and 3/4ths camera perspectives from the 8 winds of the compass.

The sprites are then placed into a Dictionary<string, Sprite> data structure to associate each sprite with a unique name.

Finally, all the sprites are combined into one texture atlas, where output is a Sprite instance containing the texture and textureAtlas contains the metadata.

Dependencies

Voxel2Pixel

Package	License	Included Via	Purpose
BenVoxel	MIT	Project	Open standard for voxel model files
Cromulent.Encoding.Z85	MIT	NuGet	BenVoxel JSON format encoding/decoding
FileToVoxCore	MIT	NuGet	Parses MagicaVoxel files
PolySharp	MIT	NuGet	Polyfills newer C# language features
RectPackSharp	MIT	NuGet	Packs rectangles for texture atlases

Voxel2Pixel.Test

The Voxel2Pixel.Test project also depends on SixLabors.ImageSharp, Magick.NET and SkiaSharp for image file output, but the actual Voxel2Pixel library does not include these.

Voxel2Pixel.Web

Package	License	Included Via	Purpose
Voxel2Pixel	MIT	Project	Voxel model rendering
MudBlazor	MIT	NuGet	UI components
SixLabors.ImageSharp	Six Labors Split License	NuGet	Image file output

Note that using the other non-test projects without the web front-end does not impose the conditions of the Six Labors Split License.