3D in VPy

VPy can draw 3D: meshes (.vmesh) and scenes (.vscene) in perspective, with hidden-line removal, occluders and fog. The builtins call the SDK's vpy3d — the same 3D layer C games use — and the compiler links it into the game when the program uses any of them.

On m6809 and pitrex, a .vec with z coordinates and DRAW_VECTOR_3D gives simple 3D (see VPy Language). The meshes and scenes themselves are made in the 3D Editors.

A complete example

A mesh at assets/meshes/ship.vmesh, turning in front of the camera, with its name floating above it. Build it with target = "uvm2" in the .vpyproj.

META TITLE = "SHIP"
 
pose: i32 = [0] * 12        # where the ship is
spin: i32 = [0] * 12        # how it is turned
angle = 0
 
def main():
    LOAD_MESH("ship")
    CAMERA_LOOK_AT(0, 0, -2000, 0, 0, 0)
 
def loop():
    angle = (angle + 16) & 4095           # 4096 = one turn
    XF_ROT_Y(spin, angle)
    XF_TRANSLATE(pose, 0, 0, 0)
    XF_MUL(pose, pose, spin)              # spin first, then move
    DRAW_MESH("ship", pose, 110)
    TEXT_BILLBOARD("SHIP", 0, 700, 0, 200, 80, 2)   # 2 = centred

Units and transforms

A transform is a global i32 array of 12 elements: a Q14 rotation, then a translation. Declare one per placement you need ([0] * 12 is the short form).

Camera and projection

To bank the view, pass SIN_Q14(roll), COS_Q14(roll), 0 as the up direction.

Meshes

A mesh must be loaded before it is drawn. Meshes are named by string literal and must exist: a missing one is a compile error.

Slots. Every mesh argument also takes a slot, so a function can be handed the mesh it draws:

def figure(p, body):
    DRAW_MESH(body, p, 100)
 
def loop():
    figure(pose, MESH("scout"))

If LOAD_MESH returns 0, raise VPY3D_POOL_* in the project's [uvm2] defs.

Occluders and lines

Occluders are invisible solids that hide whatever is drawn after them. Draw near to far.

A .vmesh can also carry its own occluders, which go into the table when the mesh is drawn (see 3D Editors).

Fog

br = FOG(110, x, y, z, 3000, 17500)
DRAW_MESH("ship", pose, br)

Scenes

A .vscene arranges .vmesh pieces: placed, repeated, following the player's position, with fog and groups.

dist = 0
 
def main():
    LOAD_SCENE("tunnel")
    CAMERA_LOOK_AT(0, 0, 0, 0, 0, 1000)
 
def loop():
    dist += 40
    DRAW_SCENE("tunnel", 0, 0, dist, 90, 1)   # group bit 0 on

Hits and damage marks

More than four mark sets: raise VPYX_MARK_SETS in [uvm2] defs.

hit: i32 = [0] * 7
 
def shoot(ox, oy, oz, dx, dy, dz):
    if RAY_MESH(hit, "ship", pose, ox, oy, oz, dx, dy, dz, 20000) >= 0:
        MARKS_ADD(0, pose, hit[0], hit[1], hit[2], hit[3], hit[4], hit[5])

Text and drawings in the world

text is a string literal, or a variable or parameter holding one:

TEXT_BILLBOARD(LABEL_NUM("SCORE ", score), 0, 900, 4000, 250, 90, 2)

Effects (FX_*)

Short-lived pieces that fly, fall, bounce on a floor and fade. Spawn them, then call FX_STEP() and FX_DRAW() once per frame. Velocities are units per second, gravity units per second², life in frames. Each spawn returns how many pieces it made.

def explode():
    FX_SHATTER("ship", pose, 0, 0, 0, 0, 0, 0,
               2200, 1024, 45, 120)
 
def loop():
    FX_STEP()
    FX_DRAW(1)

Skeletons (BONE_*)

Bones in a tree, each with an optional mesh, posed by rotations or by IK. A skeleton is a number, 0 or 1 by default; bone -1 in BONE_ROT / BONE_ROT_MUL is the root.

Soft bodies (SOFT_*)

Cloth sheets and blobs of points and springs. Each one made is a body number; call SOFT_STEP() and SOFT_DRAW(body, …) once per frame.

Skeletons and clips as constant tables

A .vskel skeleton or a .vclip library of poses and clips is imported like a module, with no .vpy file behind it. The compiler reads the asset and turns it into constants:

import humanoid      # assets/skeletons/**/humanoid.vskel
import moves         # assets/clips/**/moves.vclip, and its skeleton
 
def loop():
    twist = moves.T_POSES[moves.POSE_GUARD][moves.JOINT_TWIST]

• A .vclip gives its poses (T_POSES[N_POSES][N_JOINTS]), clips (T_CLIPS, T_KEYS), properties, marks and sets (T_SET_CLIPS, T_SET_POSES), with names such as POSE_<p>, CLIP_<c>, JOINT_<j>.
• A .vskel gives its bones (T_BONES), turns (T_ROTS, T_TURNS), variants, meshes per bone (T_BONE_MESHES), sockets, and T_MESHES: each mesh's MESH("name") slot.
• Names are upper-cased. Poses, clips and sets are numbered alphabetically, so read everything by name.
• A .vpy module of the same name wins; a .vclip and a .vskel of one name are an error.

Your program builds the character with one BONE_ADD per bone and turns it each frame from these tables. Both formats are described in 3D Editors.

Memory and pool sizes

Pool sizes go in the project's [uvm2] defs:

A .um2 runs from SRAM, where code and data share 512 KB, so a big game may need VPYX_LAYERS_OS. A program's variables live in the 16 KB the runtime reserves at the top of SRAM: scalars in about 2.9 KB, array data in 12 KB. Running out of either is a compile error.

Not available from VPy yet

• Terrain
• Bone animation clips: the .vclip format and its editor exist, and VPy reads clips as constant tables, but there are no builtins that play a clip on a skeleton yet. Interpolate between poses in your own code.

The C side has both; see vpy3d and Animation.