<< Main


Current version is BVT_029, released May 17, 2018.

The Blackbox Voxel Tool attempts to generalize pixel art,
merge workflows of 2d and 3d, marry retro with modern,
remove difference between pixel and tile mapping,
and explore this unified potential for a strong workflow,
that maximizes the practical sense of pixel art,
as well as distinction to other graphical media,
platform agnostic and time independent.

Its logic is strict but satisfying and powerful.

Some of the target features are:
-- extreme scale
-- mixed resolution
-- indexed HDR colour rendering
-- advanced palette management
-- pixel power user controls
-- seamless on the fly tiling
-- multi window editing
-- flexible memory model
-- animation by frame
-- transparency
-- layers

This user guide assumes the US English keyboard layout.

Control Modes

There are two control modes: Free Camera Mode and Free Mouse Mode.

Cam mode is default, most useful to move around.
Mouse mode is good for concentrating on painting.

You switch between modes by pressing key Spacebar.

Free Camera Mode:

----- w, a, s, d, q, e: Move forward, right, left, backward, down, up.

----- Mouse Move: Look around

Free Mouse Mode:

----- w, a, s, d, q, e: Pan up, right, down, left, zoom out, zoom in.

----- Mouse Move: Move Pointer

In both modes, increase or decrease Size of current Selection with Mouse wheel up or down.
Which also adjusts movement speed within certain limits, different from selection limits.
Alternatively use key c or key z for Mousewheel up or down, and key x for Middle mouse button.
While holding shift, these keys and buttons scroll the colour palette. While holding Ctrl, you scroll the palette page-wise.

You can toggle on/off grid view with the Tabulator key.

You can toggle on/off the default smart select for a rougher method with key g.
While the finer smart select is more useful most often, sometimes it's really nice to select more sweepingly.

Press key v to toggle walk/run speed. Useful for getting closer to details.

Key f for hiding entire GUI. Useful for moving around quickly.
Remembers last selection size and move speed upon switch off,
so you can make use of speed changes by mouse wheel while moving,
yet still quickly go back to your intended work mode. Use this often.
Hitting Space also re-enables GUI to last setting and enters Mouse Mode.

shift + f to toggle hide only cube selection graphic.
Good for adjusting palette on scene without having selection distract you.

Tool Modes

There are various Tool Modes for manipulating the cubes.
The current tool mode decides the functionality of mouse buttons.
These modes are assigned to the number keys 1 - 0.


Left Button: Add Cube to selected side

----- While holding Shift: Overwrite current selection

Right Button: Remove selected cube

----- While holding Shift: Shoot-through removal in path


Left Button: Paint selected side with selected colour

----- While holding Shift: Paint cubes wholesome

Right Button: Pick colour of selected cube or Mark tile for copy

----- While holding Shift: force mark tile for copy on single or partial cube.

----- While holding Alt: Assign or mix colour of selected cube to current slot of palette.

----- While holding Alt+Ctrl: Assign or mix colour of selected side to all Marked slots of palette.


Left Button: Turn cubes transparent.

Right Button: Turn cubes back to opaque.


Transparency is fixed to 50% for now.

In later updates for the GUI, you may adjust that.

... more to be released in future versions.

Switch the functions of left and right by pressing the Middle Mouse Button or key x.
But you can also just assign one of the mouse functions of one mode, while keeping the function of the other.

shift + num: only assign the mode's default Left to mouse while keeping current right
ctrl + num: only assign the mode's default Right to mouse while keeping current Left

By combining switch and selective mode assignment, you can customize controls on the fly.

Active Capslock makes the Shift functions permanent without need to hold shift.
While Capslock is active, holding shift has the reverse effect.

Key r always picks colour from selected cube side, regardless of current function mode.
while shift assigns colour of selected cube side to current slot of palette.
When more than one cube is selected, instead of picking colour, it is picked as tile.

Hold the Ctrl key while pointing on cubes activates the LINE tool. The moment you press Ctrl it marks the beginning of a line while moving your mouse to select the end of line. This is visualized with a helper line. Upon pressing the mouse buttons, the function is executed for the whole line.
While keep holding ctrl resets beginning of new line to new location upon each new click.
While the Line tool is active you can't change selection size with mousewheel, but you can scroll colour palette page-wise.

Copy Tiles

Copy&Paste transforms the workflow of Blackbox into Pattern Orientation.

Whenever you have selected more than one cube,
the Pick tool marks that for Copy&Paste, instead of colour.
Remember, you Pick either by pressing key "r",
or by default Right Click Mouse in Paint Mode (key "2").

A marker graphic indicates picked tile.
whenever your current selection leaves
the area you Picked, a marker shows
the location you will copy&paste.

Be sure to give this new feature a lot of attention.
Experiment with patterns of beauty, construct fractals.
This feature becomes very powerful with experience

Always look out for picking reusable patterns in micro or macro,
similar to how you would pick colour.

As you should expect, you can easily resize the copy upon paste
simply by changing selection size with mousewheel.
There are various uses for that:
-- prepare your tileset at a comfortable work size,
and then miniaturize it upon actual use,
to fully leverage world scale.
-- hide your tileset as "micro film" within world.
-- fractal construct mass and shape very quickly.

This current copy is a straight location copy, instead of instanced.
That's probably going to change later, but in the meantime this enables
some interesting fractal tricks, like "infinite mirror"-esque effects.
It happens when you try to paste within the area you picked for copy.

Hard copy is very expensive, both in processing and memory usage.
This will be circumvented when referenced soft copy from tile palette comes later.

When a tile has holes through which you can see other tiles behind,
this may be problematic to paint with, since it may shoot-through.
Until this is fixed, remember that you have alternate Selection modes.
Use key "g" to toggle default Smart Select. Turning it off can avoid the problem.

Rotation & Flipping

Copy&Paste auto-rotates the tile.

This depends on:
The side you were picking the tile at,
and the side you are pasting to.

This is useful for both,
intuitively painting tiles on different walls,
and rotating a tile on the same spot.

Holding key Shift while Picking a tile,
deactivates auto-rotation for that tile upon paste.
The sides of picking and pasting then don't matter.

There is also manual rotation and Flipping:

When holding key Alt, the movement keys w, a, s, d, q, e
flip and rotate the currently selected side of cube or tile.

ALT + q, e: counter-clockwise and clockwise side rotation.
ALT + w, a, s, d: Flipping of side, left, down, right.

Use this to further adjust the normal auto-rotation of pasting.

This feature plays to an advantage in workflow of 3d.
You can reduce the minimum amount of tiles required for a full set,
and greatly enhance visual variety at little to no extra work.
Further takes advantage in fractal mass construction methods.

Colour Control

You can adjust the HSL values of a palette's current slot colour.

INS, DEL (or u, j): increase/decrease HUE component
HOME, END (or i, k): increase/decrease Saturation component
PGUP, PGDOWN (or o, l): increase/decrease Luminance component

Holding shift turns these keys to RGB controls, modifiying the red, green and blue component of colour.
Holding ctrl affects all Marked colours in palette. (see section on colour Marking).

The scene updates after you are done modifying colours.

All colours are indexed. They are bound to the slot of palette.
When you change the colour of a slot, all cubes that were painted with that slot colour change their colour too.
Use this to further adjust colours after you are basically done drawing. Also applies to whole palette swaps.
Palette colours keep their integrity together while on mass modification, allowing to play with extreme effects (HDR).
But first and last colour in palette are system fixed and not modifiable.

Pressing key Backspace or key Comma deactivates/activates the currently selected slot.
While holding ctrl deactivates an entire block of active colours beneath.

Deactivated slots are unaffected by wholesome palette manipulation.
And can be passed by colour block movements in palette.
Deactivated Slots still remember their last colour, until overwritten.
Changing colour components on a deactivated slot also activates it.

Palette Management

Arrow keys up or down to move in colour palette, which comes in entire pages.
While holding shift moves a colour up or down the palette, by swapping the colours of slots.
While holding ctrl moves an entire block of active colours above or beneath, up or down the palette;
when block connects with another block in palette, they become one and move together.
While holding ctrl + shift also moves an entire block of active colours the same way,
but when the block connects with another block in palette, it passes through it instead, colour by colour, trading places.

Arrow key left or right swaps palette entirely to another, for palette cycling.
While holding shift copies the current slot colour to the same slot of next palette on switching.
While holding ctrl copies the whole block of active slot colours beneath to the same slots of next palette on switching.
While holding ctrl + shift copies all the colours of palette to the next palette while switching.

Press key Enter or key Period to Mark current colour in the palette.
while ctrl, marks entire block of active colours beneath.

More specifically, key Enter toggles the mark,
and ctrl + enter toggles mark for entire block;
unmarked colours become marked,
marked colours become unmarked.

The mark is remembered when moving colours
and on transfer between different palettes.

When using ctrl with the HSL/RGB colour component modifier keys,
the change now affects only all the marked colours in the palette.

This allows more effective colour palette management.

Considering all this, it's probably most useful in general to
organize your palette in separate blocks of active colour.

You can reorganize your palette at any moment without messing up the scene you're working on.

The first and last slot of a palette are the system colour slots.
They can't be moved or manipulated. But they don't count towards the max colours of a palette.

There is a scroll bar indicator to colour palette list,
for better orientation and management.

In the lower left corner next to palette menu bar,
is an indicator for detected graphics chip vendor,
Green square is Nvidea, Red for AMD, Blue Intel, Black undefined.

Next to the gfx detect indicator, is the indicator for cube count,
Every square in row means 50k cubes available in total from memory.
They flip between a dark and bright shade for better differentiation.
A white line going through them means how many cubes currently in use.

You can resize the palette menu bar.
shift + F9: increase size of palette bar.
ctrl + F9: decrease size of palette bar.


Basic animation by frame.

key Plus/Minus for going to next/previous frame.
shift + Plus/Minus to insert new frame between current and next or delete current frame.
ctrl + Plus/Minus to copy content of current frame to the next/previous frame (overwrite).
shift + ctrl + Plus/Minus to insert new frame and copy current content at once.
Alt + Plus/Minus for swapping current frame with next/previous, instead of overwriting.

Keys Period/Comma are synonym to Plus/Minus.

Keys Multiply or Divide for increasing or decreasing the timing of frame.
shift + Multiply or Divide for modifying the step size for an increase or decrease.
The timing is copied over with a frame.

keys m or n is synonym to Multiply or Divide.

To watch your animation press the number 0 (toggle).

You can edit the scene while the animation is actively running on your main screen.
This gives you the ability to make some cool effects with little work.
Usually, the effect will look like "moving ants" following along the path you draw.
But depending on the editing mode, also allows for other tricks like cascaded animations.
By assigning each frame a different palette, you can paint realtime with animated colour.

Or go into presentation mode with key p;
you can combine the animation with rotation.

Your colour palettes are global for all frames.
But each frame can have a different palette assigned.

The cube count is also global for all frames, instead of per frame.
That means you can have more or less voxels on different frames.
Use this to distribute your pool of cubes where needed most.
This way you make efficient use of memory.

Current maximum frames is 300. Even though you can freely distribute cubes,
the more frames you use, the less cubes can you spend on a single frame.
Using 300 frames means, each frame can't have more than 5000 cubes.
Having 1 frame means, you can spend all 1500000 cubes on it.
Having 10 frames means, you can spend 1450000 cubes max on any one of them,
or distribute these cubes in any other way you like across these 10 frames.

Note: Animation is still rudimentary.
It needs a more "gridless" copy of cubes.
The GUI needs a greater upgrade for more info.
But even though it is slightly awkward and disorienting,
seeing how frame animation interacts with the rest is interesting.

Editing Modes

Timeline mode:
Pressing key t toggles on/off the Timeline mode.
When active, operations like Add, Delete, Copy, rotate, flip affect all frames at once.

You can copy a whole animated tile across all frames at once.
You can easily make stable changes on a running animation.

Timeline also affects the palette management:
All palettes assigned to frames are affect the same by changing or moving colours.
This also includes mixing colours with alt-pick.

Timeline has two more sub modes: Forward and Backward.
key shift + t: Timeline Forward only affects all frames from your current frame forward.
key ctrl + t: Timeline Backward only affects all frames from your current frame backward.
This also affects operations on colour palette, as assigned to frames.

In a running animation, Timeline forward behaves like recording your actions.
Timeline Backward behaves like undoing your actions across the animation.

Timeshift Copy:
The marker for copy tile now remembers the frame it was placed on.
That means you can copy marked content from one frame to another.
It is especially useful for adding new animations to an existing animation,
without having to do a full scene frame copy.

An active animation or Timline copy overrides a Timeshift copy, for full animation copy.

Presentation View

Use key p to toggle Presentation view on/off.

When in this mode, your view is set to orthographic projection on scene,
shift + p to enter Presentation mode with perspective distortion instead of orthographic view.
while in Presentation mode, shift + p toggles orthographic view. Press only p to exit Presentation as usual.

Your controls change in Presentation: press keys w, a, s, d, q, e to rotate scene.

Ctrl + rotation key to keep a little spin in that direction going on its own.
Doing that several times in the same direction speeds it up.
In the opposite direction slows it back down again.
Doing a manual rotation in same direction or opposite cancels the auto spin.
Press key Enter to pause/resume all spinning.

Combine different directions at different speeds.
Finding weird spin patterns is fun to play with.
The Presentation mode remembers your auto spin settings,
so toggle in and out to work on your scene or watch it.

Shift + rotation key for one step by 45 degree.

You can swap palettes (arrow), toggle grid (tab),
reset view (b) and toggle mouse (spacebar) as usual.

Cameras and Window

Your mini cams are useful for keeping an overview.

Switch your main view to that of a mini cam by pressing the F1 - F4 keys,
While holding shift sets your current main view to a mini cam.
While holding ctrl toggles on/off that mini cam.

Your mini cams don't have to be visible for switching or setting.
When setting a mini cam from main view, it also sets it with the same grid view mode.

Mini cams can swap places.
Keep holding any of F1 to F4,
then press another cam of F1 to F4.

Press key b to set your main view back to its default status.
while holding any of F1 to F4 sets the selected mini cam back to default status.
while holding ctrl sets all mini cams back to their default status.

Press tab to toggle on/off grid view.
while holding any of F1 to F4 toggles grid for selected mini cam.

Mass cam modifaction:
ctrl + tab to toggle grid for all mini cams.
ctrl + shift + tab to include main cam.
ctrl + b to reset all mini cams.
ctrl + shift + b to include main cam.

Hold cam key F1 - F4 + number 0 to assign running animation to mini cam. It toggles.
Hold Ctrl + number key 0 to toggle all mini cams for animation at once. + shift to include main.
Mini cams in animation work even if the main screen is not in animation.
This gives you a preview on your animation work in progress.

Press F11 to toggle visibility of all active minicams.
While holding shift increase size of mini cams by one step.
While holding ctrl decreases size of mini cams by one step.

Press F9 to toggle visibility of palette view.

Added controls for transparent graphical user interface.
alt + F9 to toggle backround of palette menu bar.
alt + F11 to toggle backround of cams menu bar.

Press F12 to toggle between windowed or fullscreen mode.
The program remembers last size and location of window between switches.

ESC to exit into window mode. while in window mode, ESC exits program.


You can save your work to file.

key F5 for saving model and palette to file save.bvt
shift + F5 for saving only model to file save.vmp.
ctrl + F5 for saving only colour palette to file save.vcp.

key F6 for loading model and palette from file save.bvt.
shift + F6 for loading only model from file save.vmp.
ctrl + F6 for loading only colour palette from file save.vcp.

The file system allows for many changes while keeping backwards compatibility.
Your old work files will always be usable in newer versions of Blackbox.

While saving or loading a scene, the program seems to freeze until finished.
File sizes are between about 3 to 6 MB for a full scene, depending on the scene structure.
Compressing the file as .zip shrinks it down to about 0.25 MB.

It is possible that a person saves a full scene work to file and gives it to another person.
The other person may have less video memory than the first. In that case the scene cannot be fully loaded.
Though it will try to salvage and load as much as possible from the scene as fits into the smaller memory.

Terrain Generation

It is possible to create a procedural terrain. Takes a couple seconds.

Simply pressing F8 generates a terrain of random type.

You can pick what kind of terrain you want specifically.
Keep holding key F8, and while holding press a number from 0 to 9.

The numbers represent the general world level of the terrain.
Starting from 0 Underworld to high mountain region on 9.

Also remember, that since the terrain colour theme draws from the palette,
you can change the palette such to change the nature of the landscape to your desire.
For example, you can turn the default mountains from dry and rocky to ice bergs and glaciers.

Note that saving a very complex terrain to file might take a while longer than usual.

Also note that the terrain function automatically extends the first 32 colour in the palette
to a full 256 colours now, to fit the various terrains.
But it only does this once when you generate for the first time.
You have the ability to manually force a palette extension on next generation.
To do this, press Shift + F8.
You can also deactivate Palette extension on terrain generation.
Useful if you want to keep a full palette that hasn't been used for terrain yet.
Press ctrl + F8 (+ number) to generate terrain without palette extension on first time.

The terrain varies, press repeatedly until you found what you are looking for.

Terrain sizes automatically adapt for lower end graphics card and limited video ram.
The generation now adapts to available resources:
high: 1024x1024 @ 256 colours
medium: 512x512 @ 128 colours
low: 256x256 @ 64 colours

You can also manually set of detail level for terrain.
Lower detail settings generate and save considerably faster.
The default detail level depends on the available amount of cubes for your PC.

low: alt + ctrl + F8
medium: alt + shift + F8
high: alt + shift + ctrl + F8

But it will only accept the chosen detail if it has the resources for it available
to completely finish the terrain, else it will revert to default detail for this system.

Also note, that this manual setting only works on the first time of generation in your session,
due unpracticality of the the current GUI and avoiding conflicts of the palette extension.

Experimental Effects

You can test this real-time interactive effects experiment.
Like the terrain, this feature is just for first testing purposes.
It will be better developed sometimes in the future along other components.

Press F7 to start fire effect.
Shift + F7 for volumetric Dunes.
Pressing F7 while any above are running, toggles pause/unpause.

Press Ctrl + F7 for water effect.
Ctrl + Shift + F7 for volumetric water waves.
Pressing Ctrl + F7 while any above are running, toggles pause/unpause.

When an effect is started, a special palette is generated.
As usual, you can change the colour scheme manually.

Most of these effects can be played with simply by painting into the scene.
In general, the further down the colour in the palette, the more intense the affect.

While both the terrain and these effects make full use of the 8-bit colour palette,
in order to demonstrate a maximum stylistic difference to previous showcases
in just how smooth pixel graphics can look despite these limitations,
both could run at a much lower colour count with satisfying results.


Current maximum numbers:
sizes: 16
colours: 256
palettes: 256

max frames: 600, depending on voxel usage.
virtual resolution: 32768 x 32768 x 32768
cubes: 3 million, depending on available vram.

Comes with preset colour palette Dawnbringer 32.


Blackbox does not use more than 2gb video ram on the graphics card,
though running several instances of it can make use of more.

This current version of tool is just a Demo experiment for studies.

<< Main