Spade

Spade is the SPASTAZ level editor. Part 1 covers the editor itself; Part 2 is the reference for writing mods. Download Spade.

Part 1 — Using the Editor

The window

The editor 3D view is deliberately plain: flat key-light shading on a dark background, with no sky, shadows or ambient occlusion. It is a working view. Press Render to see the scene through the full lighting pipeline.

Tools

Select (Q)

Click objects in any viewport. In 2D views, the smallest brush under the cursor wins, so a small object inside a large one stays reachable.

Block (B)

Drag a box in a 2D view, press Enter to create the solid. The shape row in the menu bar picks cube, cylinder, sphere, arc or plane.

Clip (C)

Drag a cut line in a 2D view. The plane is that line extruded along the view's depth axis. Tick marks show which side survives. Several cuts can be schemed up and applied together, and holding Ctrl while dragging curves the cut.

What the kept side means

• Front / Back — Each plane trims the solid. Chaining several gives their intersection — that is how you get chamfers, bevels and faceted shapes from one brush.
• Both — Each plane also emits its offcut as a separate brush. The original is decomposed into convex pieces that tile it exactly.

Cutting an arched doorway

Select the wall, switch to Clip, set the kept side to Both with Tab, then Ctrl+drag an arc across it and tune the bulge with the wheel. Press Enter: the wall splits into the arch piece plus the surrounding pieces. Delete the piece filling the opening.

A curved cut is approximated by its segments, so an 8-segment arc becomes 8 planes. The queue holds up to 32 planes in total, which is where the 8-stroke and 16-segment limits come from.

Clipping cannot create the bent faces that free vertex editing can, so it is the safer way to shape geometry.

Vertex / Morph (V)

Click a solid to activate it; Ctrl+click adds more solids and edits them together.

Dropping a vertex onto another prompts to weld them — that is how a cube becomes a wedge or a pyramid. In a 2D view two corners often sit on the same pixel; a click takes the nearest, and clicking again steps to the one behind it.

Entity (E)

Place lights, props, spawns and physics objects. The kind row is in the menu bar. The left column also has one-click Point / Spot / Sun buttons that drop a light at the 3D view's focus, aimed where the camera is looking.

Texture (T)

Click a face in the 3D view to paint it. That is the whole workflow.

Texturing

Every face carries its own texture, scale, offset, rotation, projection mode, flips and tint.

Projection modes

Controls (Obj tab, with a brush selected)

• Scale U/V — world units per repeat, or tile count in Fit mode
• Rot / R90 — degrees about the face normal; R90 steps in quarter turns
• Off U/V — shift the texture across the surface
• Flip U / Flip V — mirror either axis
• Face R/G/B — per-face colour multiplier
• Fit / World / Reset — one-click alignment
• Copy / Paste Placement — transfer alignment between faces without changing which texture is on them

With faces selected in morph face-mode every control applies to just those faces; otherwise it applies to the whole brush.

Panels

Every numeric field accepts typed input. Type a value and click away or press Enter; out-of-range entries are clamped rather than rejected.

Camera

Hold right mouse in the 3D view:

The view cannot roll — up is pinned to world up every frame — and pitch stops just short of vertical. In 2D views the wheel zooms and middle-drag pans.

Snapping

Four independent toggles in the menu bar: Mov, Rot, Scl, Vtx. Step sizes are in the Set tab; rotation defaults to 15°. The [ and ] keys halve and double the grid.

Projects

Projects are the main way in. The manager opens before the editor; if none exists one called Untitled is created.

projects/<name>/
  maps/       .mbsptz files; Save and Open default here
  exports/
  assets/
    models/
    textures/

Opening a project loads its most recently saved map automatically. Save and Open list only that project's maps, newest first. A filename containing a slash or a drive letter is treated as an absolute path, which is how you export elsewhere.

Autosave writes _autosave.mbsptz every two minutes when something has changed. If it is newer than every real save when you open the project, you are offered recovery. It is hidden from the Open dialog.

Console

Toggle from the menu bar. Captures both editor messages and raylib's own TraceLog output, so shader compile errors and driver warnings land here alongside your own actions. Filter by Editor / Info / Warn / Error, scroll with the wheel, Follow sticks to the newest line. Everything is also printed to stdout, so running from a terminal behaves normally.

If the render window looks wrong, check here first.

Mod tools

Mods add buttons under MODS in the left column. There are two kinds:

• Command tools — Declared with tool= in the manifest. They fire once per click and return you to whatever you were doing. Each run is a single undo step.
• Mode tools — Declared with mode=. Clicking one makes it the SELECTED tool, exactly like Select or Clip: it stays highlighted and its script runs every frame until you pick something else. These can read the keyboard and mouse, so they behave like built-in tools.

A mode tool asks for its own undo steps with mod.pushundo, because pushing one every frame would fill the history in seconds. It can also stand itself down with mod.exit.

Diagnostics

Alt+P runs Check For Problems: bent (non-planar) faces, degenerate faces, coincident vertices, orphaned vertices and empty brushes. Auto-Fix All welds duplicates and recomputes winding.

Bent faces come from free vertex editing. Fix them by splitting the face along a diagonal (Ctrl+F), or use the Clip tool instead.

File layout

<executable>/
  mods/                 global mods, one subfolder each
  projects/             all projects
  resources/
    shaders/            lighting.vs/.fs, depth.vs/.fs,
                        fullscreen.vs, ssao.fs, blur.fs
    icons/              light.png, light_spot.png, light_env.png,
                        physics.png, player_start.png, entity.png
    startup/            splash.png, splash.wav (both optional)
  assets/               fallback models/ and textures/

Shaders are #version 330. If they fail to compile the editor falls back to CPU shading and says so in the Set tab — check the Console for the compiler output.

Part 2 — Modding Reference

Where mods live

<folder containing spade_editor.exe>/
  mods/
    my_mod/
      mod.txt          <- required
      something.asm
      another.asm

Mods are global, not per project: one mods/ folder next to the executable, one subfolder per mod. Loose .asm files sitting directly in mods/ are ignored — the scanner only looks at subfolders, and only ones containing a mod.txt.

Mods are scanned at startup. Mods tab → Reload Mods rescans without restarting.

The manifest

name   = Example Pack
author = your name
 
# tool = fires once per click
tool = Pillar Row | pillars.asm | Place a row of 6 pillars
tool = Scatter    | scatter.asm | Scatter cubes around the selection
 
# mode = becomes the SELECTED tool and runs every frame
mode = Paint Cubes | paint.asm | Click in a 2D view to drop cubes

One key = value per line. # and ; start comments. CRLF and LF both work. Limits: 16 mods, 12 tools each, 2048 instructions and 64 variables per script.

tool versus mode

Scripts assemble at load time, so a syntax error appears in the Mods tab as [!!] with a line number rather than when you click the button.

Language basics

A stack machine over 32-bit floats. One instruction per line, case-insensitive. Comments start with ; or #. Labels end with :.

PUSH 3          ; stack: 3
PUSH 4          ; stack: 3 4
ADD             ; stack: 7
STORE total     ; stack: empty, total = 7

There is no integer type; bitwise instructions truncate to int, operate, then convert back.

Operand order: the value pushed first is the left operand. PUSH 10 / PUSH 3 / SUB gives 7. The same holds for LT, DIV, POW and the rest.

Instruction set

Stack

Variables

64 named slots, all starting at 0. INC is the idiomatic loop counter — shorter and faster than LOAD / PUSH 1 / ADD / STORE.

Binary arithmetic

DIV, MOD and IDIV by zero abort with a line number rather than producing infinity. WRAP and SNAPTO by zero return a unchanged.

Unary arithmetic

RAND is seeded identically every run, so a mod produces the same result twice. That is deliberate: undo and re-run gives you the same thing.

Ternary

Comparison, logic and bitwise

Control flow

The compare-and-jump family reads naturally as a loop test:

LOAD i
PUSH 10
JGE done        ; if i >= 10, jump

Output

Output appears in Mods tab → Last Run and in the Console.

Host functions

CALL name. Arguments push left to right and pop automatically; every call pushes exactly one result, so POP it if unused. Out-of-range indices return -1 or 0 and do nothing. There are 225 of them.

Selection (11)

Map (6)

Camera (21)

Snapping (10)

Settings (14)

Brush (56)

Face (30)

Entity (37)

Assets (3)

System (7)

Keyboard (8)

Mouse (10)

Mod Tool State (7)

Utility (5)

Safety

Mods edit your map, so the interpreter is deliberately paranoid:

• Step limit — 2,000,000 instructions. An infinite loop reports 'step limit reached' instead of hanging the editor.
• Stack limit — 128 entries; underflow and overflow both abort with a line number.
• Return stack — 32 levels; deeper GOSUB nesting aborts.
• Bounds checks — Every brush, vertex, face, and entity index is checked against the live map.
• Undo — Each run is wrapped in an undo push, so Ctrl+Z reverts the whole thing.
• Division by zero — Aborts rather than producing infinity.

A failed run leaves the map as it was at the point of failure; it does not roll back automatically, but Ctrl+Z will.

Worked example

Taper a brush: pull every vertex above the midline toward the centre line.

CALL sel.brush
STORE b
 
LOAD b
PUSH 0
JLT done                  ; nothing selected
 
LOAD b
CALL brush.vertcount
STORE n
 
PUSH 0.45
STORE k
 
PUSH 0
STORE i
 
loop:
  LOAD i
  LOAD n
  JGE finish
 
  LOAD b
  LOAD i
  CALL brush.gety
  STORE vy
 
  LOAD vy
  PUSH 0
  JLE next                ; leave the bottom half alone
 
  LOAD b
  LOAD i
  CALL brush.getx
  LOAD k
  MUL
  STORE nx
 
  LOAD b
  LOAD i
  CALL brush.getz
  LOAD k
  MUL
  STORE nz
 
  LOAD b
  LOAD i
  LOAD nx
  LOAD vy
  LOAD nz
  CALL brush.setv
  POP
 
next:
  INC i
  JMP loop
 
finish:
  LOAD b
  CALL brush.fixwind
  POP
 
done:
  HALT

Call brush.fixwind after moving vertices by hand. Pulling a vertex through a face inverts it, and an inverted face renders inside-out.

Camera example

Frame the selected brush: aim the camera at its centre from a distance based on its size.

CALL sel.brush
STORE b
LOAD b
PUSH 0
JLT done
 
; centre of the brush
LOAD b
CALL brush.centrex
STORE cx
LOAD b
CALL brush.centrey
STORE cy
LOAD b
CALL brush.centrez
STORE cz
 
; radius from the bounding box diagonal
LOAD b
CALL brush.maxx
LOAD b
CALL brush.minx
SUB
STORE w
 
LOAD w
PUSH 2.5
MUL
PUSH 4
MAX                       ; never closer than 4 units
STORE dist
 
LOAD cx
LOAD cy
LOAD cz
LOAD dist
CALL cam.orbit
POP
 
done:
  HALT

Reading input

key.down, key.pressed and key.released take a raylib key code. Letters and digits are their ASCII values, so 'A' is 65 and '0' is 48. Common codes:

key.shift, key.ctrl and key.alt cover the modifiers without needing codes. Mouse buttons are 0 left, 1 right, 2 middle.

mouse.vp reports which viewport the cursor is over (0 3D, 1 top, 2 front, 3 side, -1 none), and mouse.worldx/y/z give the cursor position in world space for the 2D views — which is what you need to place anything under the pointer.

Mode tool example

A tool that drops a grid-snapped cube wherever you click in a 2D view, and exits on Escape. Declare it with mode= so it stays selected.

; exit when Escape is pressed
PUSH 256
CALL key.pressed
JZ carry_on
CALL mod.exit
POP
HALT
 
carry_on:
; only act on a fresh left click inside a 2D viewport
PUSH 0
CALL mouse.pressed
JZ done
 
CALL mouse.vp
STORE vp
LOAD vp
PUSH 1
JLT done                  ; -1 or 0 means not a 2D view
 
; snap the cursor position to the grid
CALL mouse.worldx
CALL snap
STORE px
CALL mouse.worldy
CALL snap
STORE py
CALL mouse.worldz
CALL snap
STORE pz
 
; one undo step per placement, not per frame
CALL mod.pushundo
POP
 
PUSH 0                    ; cube
LOAD px
LOAD py
LOAD pz
PUSH 2
PUSH 2
PUSH 2
CALL brush.add
POP
 
; count what we placed, in state that survives the frame
PUSH 0
CALL mod.get
PUSH 1
ADD
STORE total
PUSH 0
LOAD total
CALL mod.set
POP
LOAD total
CALL log
POP
 
done:
  HALT

mod.get and mod.set give each tool 32 float slots that persist between frames. Ordinary variables are cleared every run, so anything a mode tool needs to remember goes in a slot.

Idioms

Counted loop — there is no FOR.

PUSH 0
STORE i
loop:
  LOAD i
  PUSH 10
  JGE done
  ; body
  INC i
  JMP loop
done:

A subroutine. Put them after HALT so they only run when called.

PUSH 4
GOSUB cube_at_x
HALT
 
cube_at_x:
  STORE px
  PUSH 0
  LOAD px
  PUSH 0
  PUSH 0
  PUSH 2
  PUSH 2
  PUSH 2
  CALL brush.add
  POP
  RET

Discard results. Every CALL pushes something; ignore it inside a loop and the stack overflows.

Error messages