Ace of Spades

+------------------------------+
| VOXED voxel editor reference |
+------------------------------+

-------------------------------- INTRODUCTION --------------------------------

The user interface isn't so easy right now - there are a lot of keys you
need to memorize. There are a lot of weird combinations that are useful, but
sometimes it's not so obvious, so please explore and try to be creative.
In my documentation, when I use the word "box", I am referring to a cube,
where the lengths of the 3 sides aren't necessarily of equal length. I prefer
to reserve the word "rectangle" for 2D primitives only. Also, any controls
that have a prefix of "KP" means that I'm talking about the key on the KeyPad.
One of the most confusing things are the 3 different types of cursors. You
should try to understand this before reading the rest of the documentation.

Screen-cursor: This is the dot that's ALWAYS in the center of the screen.

Numbered-cursor: These are the "spheres" that appear when you press SPACE bar.
They have a number in the middle of them, starting with 0 and
incrementing as you insert more of them (up to 100). They are
intended mainly for editing functions which require 3 or more
points as input (for example, the sector & lathe tools) These
cursors can only be moved by dragging them with the mouse.
These are usually used BEFORE you insert an object.

Mini-cursor: These are smaller "spheres" that get inserted automatically
after you insert an object, such as a box or sphere. They
have no numbers inside them. Mini-cursors must be moved with
the keypad controls: (1,2,3,4,5,Enter)
These are usually used AFTER you insert an object.

------------------------------- GETTING AROUND -------------------------------

ESC Quit
M Map
Mouse X/Y Turn left/right, Look up/down (Press 'Y' to invert)
Arrows Move Forward/Backward/Left/Right
R.CTRL Move Up
KP0 Move Down
R.SHIFT Hold down to speed up movement (by 4 times)
L.SHIFT Hold down to slow down movement (by 4 times)
KP*, KP/ Zoom in/out. Use the other / (next to SHIFT) to reset
R.MouseBut Hold this down and move mouse left/right to tilt screen.

------------------------------- SIMPLE EDITING -------------------------------

(These functions don't require an understanding of the cursor types)

Home Insert sphere (mini-cursor becomes center)
End Delete sphere (mini-cursor becomes center)
ALT+Home Voxel spray (hold it down) - works like spraypaint, but
inserts voxels instead of changing color.
ALT+End Voxel suck (hold it down): works like spraypaint, but deletes
voxels instead of changing color.

[ and ] Decrease/increase radius of sphere, ellipsoid, or cylinder
; and ' Change superquadric power (p) of sphere (default:p=2)
abs(x)^p + abs(y)^p + abs(z)^p = r^p
Notice when p=2 in this equation, it's a sphere.
Sounds complex, but it really isn't. Try it!
These keys also change the brightness of the flash function

X Paint color onto individual voxel permanently
Tab Select current drawing color to color under screen-cursor
KP+ and KP- Change procedural texture. There are 7 currently defined:
0:cur Solid color from the color bar
1:floor Set to first color below position (default)
2:jit Take current color and randomize a little
3:many A funny looking RGB color cube
4:sph Use this one for shading spheres
5:wood An interesting wood pattern
6:png Enabled when you load a PNG file using 'V' key,
otherwise it acts like the "0:cur" mode.

\ Undo/Redo most recent modification

------------------------------ COLOR SELECTION -------------------------------

Color can be selected before you insert an object, but it is best to select
it afterwards, so you don't end up changing the color of the previous object.

L.Enter Activate/Deactivate color bar
L.MouseBut Select color (when color bar is activated)
R.MouseBut Hold and move mouse up/down. Use this to change the palette
brightness (when color bar is activated)

--------------------------- LIGHTING MANIPULATION ----------------------------

I recommend you saving the map BEFORE you go nuts with the lighting. This
is because the lighting functions tend to deteriorate the colors of the map
if you use them too much.

F Flash! This is the main lighting function. Press it and
everything you can see (within a distance) will brighten.
ALT+F Old flash. Use in the same way as F, but this uses an older
lighting algorithm which has moire pattens on the curves.
Caps Lock Darken all intensities on map by 25% Useful before a flash.
Z Hold to blend nearby intensities. Use this to remove the
aliasing you see after a "flash".
SHIFT+Z Hold to blend nearby voxel colors.
S Hold to delete thin voxels. By thin voxel, I mean any voxel
with air on opposite sides. If you use this before a
"flash", you can improve the lighting. (It removes the
possibility of a voxel getting brightened on one side and
it appearing bright on the back side as well.)
L.CTRL Hold to brighten area slowly, randomly, & smoothly. This is a
different effect from "flash", and also a lot slower.
L.CTRL+L.ALT Hold to darken area slowly, randomly, and smoothly.

-------------------------- MINI-CURSOR MANIPULATION --------------------------

KP1,KP2,KP3,KP5 Move mini-cursor Forward/Backward/Left/Right 1 unit
KP4 Move mini-cursor Up 1 unit
KPEnter Move mini-cursor Down 1 unit
KP. If .KV6 sprite is selected, this x-flips the object (so the
writing is backwards). This is a good way to save memory.
KP9 Toggle between 1 mini-cursor and all mini-cursors. When you
see only 1 mini-cursor, dragging that point will move just
that 1 point. When you see more than 1 mini-cursor, the
keypad controls will move the entire object without
changing its size. When you switch back to the 1 mini-
cursor, the vertex selected is the one closest to the
voxel under the screen-cursor. Has no effect for objects
that use only 1 mini-cursor.

NOTE: Some of these keys also let you manipulate numbered cursors.

------------------------ NUMBERED-CURSOR MANIPULATION ------------------------

Space Insert numbered-cursor. A sphere with a number inside it is
inserted at the point under the screen-cursor.
Backspace Remove last numbered-cursor
/ Remove ALL numbered-cursors. Also resets zoom & angle mode.

L.MouseBut Drag numbered-cursor (direction restricted to the arrows)
L+R MouseButs When dragging numbered-cursors around, use this to change the
axes. You should see the "arrows" change orientation.
Note: You must have BOTH mouse buttons held down!
PGUP/PGDN Raise lower ceiling/floor of sector object. You must have at
least 3 numbered-cursors for this to take effect.

------------------------------ ADVANCED EDITING ------------------------------

Insert/Delete:
Less than 2 numbered-cursors active:
Insert/Delete box. The box starts out as an individual voxel
(1*1*1) where both mini-cursors are at the same point. To
incease the size, use the mini-cursor controls:
(1,2,3,5,4,Enter on keypad)
2 or more numbered-cursors active:
Fills the selected volume with solid voxels (Insert) or air
(Delete).
Special mode: if you have 3 or more numbered-cursors, and
you select .PNG procedural texturing, then it will treat
the alpha channel as a signed-char height offset for 3D
bump-mapping.

E / SHIFT+E Insert/Delete Ellipsoid (The mini-cursors are the foci)
L / SHIFT+L Insert/Delete Cylinder/Line (The mini-cursors are endpoints)
W / SHIFT+W Insert/Delete Walls. You must have at least 3 numbered-
cursors first to use this. Then you must use PGUP/PGDN.
C / SHIFT+C Insert/Delete Ceiling. Requires >= 3 numbered-cursors.
T / SHIFT+T Insert/Delete Rotational sweep. Requires >= 3 numbered-
cursors. Cursors #0 and #1 become axis of rotation.
Everything on the right side of a clockwise-drawn loop
will be included as part of the object. It's ok to have
points on the left side of the axis, but that area will be
ignored.
H / SHIFT+H Insert/Delete a randomly generated convex hull.
B / SHIFT+B Insert/Delete Blobs. Requires numbered-cursors. (Not fully
working yet)
3 Insert triangle. You must have at least 3 numbered cursors.

4 3D floodfill, starting at camera's location. Floodfill is
restricted to numbered-cursor boxes if there are 2 cursors.
5 Lassoo tool. This tool is for filling in cracks - polygons
that don't have coplanar points. Press '5' with the mouse
cursor on each point of a loop and you should see a path
connecting from the previous point. Make sure there is a
relatively short path (< ~128 voxels) along the surface
between each pair of points. When you complete the loop,
press '6' to fill in the gaps.
6 Used in conjunction with '5'. See '5'.

D Duplicate box. First specify source box using two numbered-
cursors. Then press D at the point where you want
numbered-cursor #0 to be copied to.
Shift+D Same as 'D' but doesn't copy air voxels.

U Insert .KV6/.KVX/.VOX file. If you select a .KV6 file, then
the object will stay separated from the map. If you select
a .KVX/.VOX file, then the object will permanently become
a part of the map.

You can use 'U' to insert a dummy "DOT" sprite. To do this,
type any invalid filename, such as "ASDF" at the openfile
dialog and it will be saved as "DOT" in the .SXL file.

You can use 'U' to insert a dummy "BOX" sprite. To do this,
first make a box with 2 numbered cursors, then press 'U'.
It uses the vx5sprite .s field for the first corner,
vx5sprite .h for the second corner, and .p for the
"sphere" handle in VOXED. You can use this info too.

V Set procedural texture to .PNG file.
P Paints selected .PNG file onto the voxel map, projected in
exactly the same way as what you're looking at.
= First select a box with 2 numbered cursors. This key then
re-calculates all colors inside the box, preserving the
state of air or solid.

KP6 For .KVX/.VOX: Rotate object (Switches between x,y,z axis)
KP7,KP8,KP9 For .KVX/.VOX: Flip/Mirror axis (I don't remember which key
does what, but I know all 48 possible 90ø cases are in
there. Keep pressing on the keys until it looks right.)

KP7,KP8 For .KV6: Rotate object left/right
KP6,KP9 For .KV6: Rotate object up/down (depends on your orientation)

-------------------- MODES & OTHER MISCELLANEOUS CONTROLS --------------------

` Toggle global shading mode:
0: no shading (default)
1: normal estimation, light sources (in this mode,
pressing 'F' inserts a temporary light source)
2: normal estimation, no light sources (brighter!)
KP. Toggle shading (default) / no shading on cube faces (if
.KV6 sprite is not selected).
, and . Select raycast resolution (1-16), 1:best quality&default
R Toggle smart raycast resolution mode (lower quality when
turning quickly, higher quality when still) Default is
disabled.
Numlock Toggle raycasting cut-off distance: 256 (default) or no limit
(slow, especially if you're outside)
A Toggle anglemode (horizon correction (default) vs. free
direction)
G Toggle grid and grid alignment size (16 or 32)

2 Shoot an invisible fireball (just a toy)
F10 Enable MIP-MAPPING.

Scroll lock Panic Quit (DOS version only): Use to escape from lock-ups.
Try to avoid using this key whenever possible.

------------------------------ LOADING & SAVING ------------------------------

ALT+F2 Load .VXL map.
ALT+F3 Save .VXL map. (NOTE: Use F3 to save .SXL separately)
F3 Save .SXL file. (Game data: sky, sprite locations, etc...)
F5 Load new sky from file.
F6 Edit global user string (stored in .SXL files)
F7 Save floating object to .KV6 (put cursor on object)

F12 Screencapture exactly what you see to VXL5####.PNG
ALT+F12 Surroundcapture to VXL5####.PNG (2560*1024 resolution)

NOTE: Both F12 and ALT-F12 create valid .PNG files, but I use absolutely
NO COMPRESSION when storing them! You can reduce their size A LOT if you
are willing to re-compress them with another utility.

------------------------ Known Limitations / Problems ------------------------

Pentium III only! A lot of my new sprite & z-buffer code uses the new
Pentium III instructions. If you don't have a Pentium III or compatible
processor, then the engine will give an invalid opcode exception. It
would probably take a few hours to get the code working again on an
MMX-capable machine (with a noticable decrease in frame rate).

Memory: You WILL need at least 128MB of RAM to run this. Do not attempt to run
it on anything less.

"alloc: vbuf full". Right now, I allocate 64MB of memory to store the voxel
map. If voxlap5 suddenly exits out with this message, it means the board
is too complex - too much surface area for the board map to fit within
this limit, or the memory is too fragmented. In the future, I might
implement a way of defragmenting the cache, or a better warning, or maybe
even a disk cacheing system so this never happens.

The following issue applies to the DOS version only:

VESA 2.0 linear mode crashes under NT. I don't know why, but I know how to
replace the code with slower VESA code that doesn't crash.

-------------------------------- COMMAND LINE --------------------------------

>voxed [SXL/VXL/DTA/BSP map name] [/(xdim)x(ydim)] [/win]
(options can be listed in any order)

If you do not specify a Master sprite file (.SXL), Voxlap5 format (.VXL),
Comanche format (.DTA), or Quake 3 format (.BSP), then voxlap5 tries to load
VXL/DEFAULT.SXL. If that doesn't exist, then it loads a built-in map, with a
gray plain, called "UNTITLED.VXL". You start inside a box in the middle.
Voxlap5 supports all 32-bit color modes where xdim<=640 and ydim<=480.
Default is 320*200 fullscreen mode. If the mode isn't found, then the DOS
version defaults to true-color emulation mode (320x400 8 bit color which
should work on all VGA compatible video cards). The windows version has no
emulation mode and just exits with an error message.

Some examples:
>voxed /640x480
Use hi-res VESA mode (640x480x32) To specify resolution, you must have
a lowercase 'x' separating the x- and y- dimensions and there can't be
any spaces in between.
>voxed /480x360 /win
Set resolution to 480x360 and use windowed mode instead of fullscreen.
>voxed 1
If you have Novalogic's classic game Comanche Maximum Overkill, then
copy (C1.DTA & D1.DTA) into the voxlap directory and it will load them.
>voxed c:\games\id\q3ademo\demoq3\q3dm17.bsp
If you extract *.BSP from Quake3's PAK0.PK3 file, then it will convert
the geometry from a Quake map. No textures are converted, so the best
way to view the map is to go wild and press 'F' everywhere.
>voxed asdf
Force loading of boring gray plain (assuming asdf doesn't exist)
>voxed /0
Forces truecolor emulation (DOS version only)

------------------------ Documentation Update History ------------------------

11/20/2000: VOXLAP5 documentation first written
11/21/2000: Documentation revised for clarity
02/25/2001: Added windows command line info
03/19/2001: Made DOS command line same as windows version
03/28/2001: Added documentation for P & =
05/16/2001: Updated for .KV6 keys (KP6-KP9)
06/23/2001: Updated limitations, added 3D bump & Q3 info
03/05/2002: Added some info about .SXL files & new keys related to lighting
05/14/2002: Added info about 4,5,6,Shift+D, and dummy sprite info with 'U'

------------------------------------------------------------------------------
VOXLAP5 programmed by Ken Silverman (http://www.advsys.net/ken)
Modified by Ben Aksoy (http://www.ace-spades.com)