General rules

• Keywords are case-insensitive.
• Use -- for single-line comments.
• Most commands are statement-style, not function-call style.
• Arrays are currently 1-based. Literal index 0 is out of bounds.
• VERSION 0.0.0.1 after BEGIN is completely optional — it just tags the source version; bump it as the file grows.
• Do not use reserved keywords as identifiers, field names, group names, or procedure names.

Program skeleton

BEGIN
    VERSION 0.0.0.1 -- Should be incremented up

    CREATE_WINDOW "ALB APP", 960, 640

    ON TICK
        -- update logic
    END

    ON PAINT
        -- draw logic
    END

    LISTEN
END

Comments, constants, and declarations

-- comment

#MAX_ENTITIES = 64

LET score = 0
LET hp AS U16 = 100
LET name AS STRING = "ALB"

score = 0
hp AS U16 = 100
lives AS U16
name AS STRING = "ALB"

TYPE SmallHealth IS U16 RANGE 1 .. 255

TEMPORAL LET px AS I32 HISTORY 16 = 140
TEMPORAL LET py AS S32 HISTORY 16 = 86

Safe declaration types

• U0 — void, essentially
• U8, U16, U32, U64, U128
• S8 (I8, INT8), S16 (I16, INT16), S32 (I32, INT32), S64 (I64, INT64), S128 (soft on most hosts; honest 16-byte on FASM)
• F32 (SINGLE, soft FLOAT), F64, REAL (alias of F64; soft also DOUBLE, NUMBER), F128 (soft)
• PURE, RATIONAL (alias of PURE)
• FLOAT2 (F32X2), FLOAT4 (F32X4), MAT2 (MAT2X2), MAT3 (MAT3X3), MAT4 (MAT4X4)
• BOOLEAN / BOOL, STRING / BINARY, CHAR
• HW8, HW16, HW32, HW64

• STRING and BINARY map to the same binary/string storage model.
• REAL and RATIONAL are surface aliases for F64 and PURE.
• FLOAT2/FLOAT4/MAT* are valid in globals, locals, and struct fields.
• Range types via TYPE Name IS Base RANGE A .. B can be used after AS.

Class C (retro 8/16) subset

Targets: C64, FASM16/DOS. Prefer only:

• U8, U16, S8/I8, S16/I16
• HW8, HW16
• BOOLEAN/BOOL, STRING/BINARY, CHAR (soft)

Do NOT expect honest U32/U64/F32/F64/U128/PURE/FLOAT*/MAT* on Class C — the toolchain rejects or normalizes those.

Structs

STRUCT Vec2
    x AS S32
    y AS S32
END STRUCT

STRUCT PackedThing
    id AS U16
    BITFIELD flags : 8
END STRUCT

Procedures, functions, modules, imports

PROCEDURE Step(IN dx AS S32, OUT done AS BOOL) REQUIRE dx > 0
    LET done = TRUE
END PROCEDURE

FUNCTION Twice(x AS U32) AS U32
    RETURN x + x
END FUNCTION

PROCEDURE StopNow()
    RETURN()
END PROCEDURE

MODULE MathKit BEGIN
    FUNCTION Add2(x AS U32) AS U32
        RETURN x + 2
    END FUNCTION
END MODULE

DECLARE MODULE RenderKit BEGIN
    PROCEDURE Paint()
    END PROCEDURE
END DECLARE MODULE

IMPORT MathKit
IMPORT(MathKit)

IMPORT_C FUNCTION GetTickCount() AS U32 FROM "kernel32.dll"
IMPORT_C PROCEDURE FillBuffer(REF ptr AS U32, buffer_len AS U32) FROM "mylib.dll"

IMPORT_DLL FUNCTION MessageBeep(kind AS U64) AS U64 FROM ("user32.dll")
IMPORT_SO FUNCTION PretendSO(kind AS U64) AS U64 FROM ("libpretend.so")
IMPORT_DYLIB FUNCTION PretendDylib(kind AS U64) AS U64 FROM ("libpretend.dylib")

EXPORT_DLL PROCEDURE ExportedPulse()
EXPORT_SO PROCEDURE ExportedSO()
EXPORT_DYLIB FUNCTION ExportedValue() AS U64

• BEGIN after MODULE, DECLARE MODULE, PROCEDURE, and FUNCTION is optional.
• In .albi interface files prefer DECLARE MODULE … END DECLARE MODULE; in .alb use MODULE … END MODULE.
• Parameters may use IN/OUT; IMPORT_C parameters support optional REF and AS Type.
• IMPORT_*/EXPORT_* dynamic-library forms lower on -t fasm and -t c; EXPORT_* auto-enables DLL output on FASM.
• Prefer RETURN CAST(expr AS Type) for mixed-arithmetic returns.

Call forms — all valid: CALL FuncName x, y, z · FuncName(x, y, z) · FuncName(x, y, z); · Module.FuncName(x, y, z); — prefer the trailing ; in new code.

LET is optional after declaration: declare with LET, reassign without it — LET hp AS S32 = 0 then hp = ….

Arrays and data layout

STRICT cells[64] AS U16
STRICT grid[32, 32] AS U8
LET cells[1] = 10
LET v = grid[i, j]

SLIDE queue[64, 8] AS U16

PARALLEL swarm[128]
    x AS S32
    y AS S32
    hp AS U16
END PARALLEL

LET swarm[1].x = 100
SWAPPOP swarm[dead_slot], active_count

• Indexing is 1-based; PARALLEL access is group[i].field.
• SWAPPOP group[idx], count — dense O(1) removal; copies the last live slot into idx and decrements count. Order is not preserved.

Networking and memory firewall

Native FASM / C backends.

NETWORK_SOCKET ServerSocket
    PROTOCOL TCP
    PORT 8080
    BUFFER_SIZE 128
END_SOCKET

MEMORY_FIREWALL NetSandbox
    PERMIT_READ ServerSocket
    PERMIT_WRITE ServerSocket
    PERMIT_READ rx_buffer
    PERMIT_WRITE rx_buffer
    DENY_ALL
END_FIREWALL

PROCEDURE ExerciseNetwork() BOUND_TO NetSandbox
    NETWORK_LISTEN ServerSocket
    NETWORK_ACCEPT ServerSocket INTO ActiveClient
    NETWORK_RECEIVE ActiveClient INTO rx_buffer
    NETWORK_SEND ActiveClient FROM tx_buffer
    NETWORK_CLOSE ActiveClient
    NETWORK_CLOSE ServerSocket
END PROCEDURE

Markov and fixed neural topologies

Native FASM / C backends.

MARKOV_MODEL WeatherPredictor
    STATES 3
    TRANSITION_MATRIX
        [0.7, 0.2, 0.1]
        [0.3, 0.4, 0.3]
        [0.2, 0.5, 0.3]
    END_MATRIX
END_MODEL

NEURAL_TOPOLOGY EnemyAI
    LAYER Input SIZE 4
    LAYER Dense SIZE 8 ACTIVATION ReLU
    LAYER Output SIZE 2 ACTIVATION Sigmoid
END_TOPOLOGY

PREDICT_MARKOV WeatherPredictor FROM CurrentState INTO NextState
INFER_NETWORK EnemyAI FROM SensorData INTO ActionProbabilities
TRAIN_NETWORK EnemyAI WITH TrainingSet EXPECTED TargetData EPOCHS 2

Emotion modifiers

Native FASM64 only — FASM16 fails loud.

EMOTION Hero
    AXES Joy Fear Anger Calm
END_EMOTION

SET_AXIS Hero Joy 40
ADD_AXIS Hero Anger 15
BLEND_EMOTION Hero TO Calm BY 10
DECAY_EMOTION Hero BY 1
GET_AXIS Hero Joy INTO joy
DOMINANT_EMOTION Hero INTO dom

PREDICT_MARKOV Walk FROM State INTO Next WITH EMOTION Hero
INFER_NETWORK Net FROM Sensors INTO Out WITH EMOTION Hero

Control flow

IF hp > 0 THEN
    LET alive = TRUE
ELSE
    LET alive = FALSE
END IF

WHILE hp > 0
    LET hp = hp - 1
END WHILE

REPEAT
    LET hp = hp - 1
UNTIL hp = 0

FOR i = 1 TO 10 THEN
    PRINT i
END FOR

FOREACH item IN collection THEN
    PRINT item
END

MATCH mode
    0 =>
        state = 1
        flash = 0
    1 => state = 2
    ELSE => state = 99
END MATCH

SELECT mode
    CASE 0
        state = 1
        flash = 0
    CASE 1 => state = 2
    CASE ELSE => state = 99
END SELECT

BREAK
CONTINUE

• MATCH arms use value => body (no CASE); default is ELSE => ….
• SELECT uses CASE value body, optional =>; default is CASE ELSE => … or ELSE => ….
• Prefer multiline IF once a branch has more than one action.

Logic / Prolog / knowledge

ASSERT(score >= 0)
ASSERT danger(1)
RETRACT danger(1)
UPDATE danger(1) TO 0

IF ?- danger(1) THEN
    PRINT "danger"
END IF

LET found = FIND danger(X)
FINDALL danger(X) INTO hits

KNOWS Mode IS 3

RULE risky(X) :- danger(X), charged(1).
CONSTRAINT safe(X) :- danger(X).

Enums

ENUM Color
    Red,
    Green,
    Blue
END ENUM

Temporal and state

TEMPORAL LET fuel AS U16 HISTORY 8 = 100

LET now_fuel = fuel@NOW
LET old_fuel = fuel@PAST
LET next_fuel = fuel@FUTURE
LET timeline_fuel = fuel@TIMELINE

ADVANCE
ADVANCE 2

SAVE_STATE()
LOAD_STATE()

Events

ON TICK
    -- simulation
END

ON PAINT
    -- rendering
END

ON KEY
    -- key event block
END

ON KNOWS_CHANGE danger(X)
    PRINT X
END

Graphics and UI

CREATE_WINDOW "Demo", 320, 200
SETFULLSCREEN TRUE
SETRESIZABLE FALSE
SETSTRETCHY TRUE

CLEAR $050511
COLOR $FF3300

DRAW RECT x, y, w, h
FILL RECT x, y, w, h
DRAW LINE x1, y1, x2, y2
DRAW CIRCLE cx, cy, r
FILL CIRCLE cx, cy, r
DRAW TRIANGLE x1, y1, x2, y2, x3, y3
PLOT x, y

TEXT x, y, "HELLO"
DRAW TEXT(x, y, "HELLO")

SET_ALPHA 1, 255
SET_CLIP x, y, w, h
SET_ORIGIN x, y

LOCATE 1, 1
MSG_BOX "Hello", "ALB"

Numeric expressions are not auto-formatted for DRAW TEXT — convert values to strings first.

Static assets, LUTs, viewports, and safe blits

SetShoebox "assets"

StaticSprite RomanIdle
    Source "roman_idle.bmp"
    Format Indexed8Bit
    Width 16
    Height 16
    Frames 1
End StaticSprite

StaticSurface VideoBuffer
    Width 320
    Height 200
    Format Rgb565
End StaticSurface

ColorLut TeamRed
    Entry 0 Is $000000
    Entry 1 Is $FF0000
    Entry 2 Is $E0E0E0
End ColorLut

VisualRule RomanUnitVisual(UnitId)
    When Knows IsMoving(UnitId) Use RomanIdle Frame 0
    Default Use RomanIdle Frame 0
End VisualRule

RenderViewport MainCamera
    Bounds 0, 0, 320, 200
End RenderViewport

ApplyLut TeamRed To RomanUnitVisual With 1
BlitSafe RomanUnitVisual With 1 To VideoBuffer At 150, 100 ConstrainTo MainCamera Mode AlphaMask

Input, display, and environment

PRINT score
PRINT "HP=" | hp
PRINT$ "STRING PIPE" | name

INPUT "Name", player_name

LET pressed = KEY(4)
LET click = MOUSE_CLICK(0)

LET mx = MOUSE_X
LET my = MOUSE_Y
LET wheel = MOUSE_WHEEL

LET sw = SCREEN_WIDTH
LET sh = SCREEN_HEIGHT
LET vw = VIRTUAL_WIDTH
LET vh = VIRTUAL_HEIGHT

LET c = READ_PIXEL(x, y)

Use KEY(code), not KEY_STATE(code). READ_PIXEL(x, y) is expression-style and does use parentheses.

File I/O

LET h = OPEN("data.bin", "r")
LET n = FILELEN("data.bin")
LET pos = FILESEEK(h, 0)
LET chunk = READ(h, 128)

WRITE h, "hello"
CLOSE h

LOAD "save.bin" INTO blob
FLUSH blob INTO "save.bin"

READLINE line

Memory / system / bare metal

LET b = PEEK(addr)
LET v = DEREF(ptr)
POKE addr, value

CLAIM obj
DROP obj
SWEEP 64
BIND parent TO child1, child2

CALL Worker(1, 2)
SPAWN Worker(1, 2)
SYNC

DELAY 16
PLAY SOUND "intro.wav"

ATOMIC
    LET counter = counter + 1
END ATOMIC

CEASE
LISTEN

String operators

• | is string concatenation — not bitwise OR. It auto-stringifies non-string operands.
• & is an alias for | — identical AST and runtime call.
• Bitwise: OR / XOR / AND.

DRAW TEXT(8, 8, "TIME: " | hour_s | ":" | min_s)
PRINT "FRAME=" | frame_idx | "  SAMPLE=" | nebula[32, 32, 1]

LET mask = flags OR 0x04
LET mask = flags XOR 0xFF

Builtin expression calls

LET n = LEN(s)
LET a = LEFT(s, 4)
LET b = RIGHT(s, 4)
LET c = MID(s, 2, 3)
LET code = ASC(s)

LET r = RND(10)
LET y = CHOOSE(flag, 100, 200)
LET ok = COLLIDE_RECT(x1, y1, w1, h1, x2, y2, w2, h2)

LET s2 = SIN(v)
LET c2 = COS(v)
LET q = SQRT(v)

LET pow1 = 2 ^ 8
LET pow2 = 2 ** 8

LET a = CAST(expr AS U32)
LET b = U8(expr)
LET sz = SIZEOF(expr)
LET ty = TYPEOF(expr)
LET off = OFFSETOF(MyStruct, field)

PURE fraction helpers

LET p = PURE(1, 2)
LET s = PURE_ADD(a, b)
LET d = PURE_SUB(a, b)
LET m = PURE_MUL(a, b)
LET q = PURE_DIV(a, b)
LET pw = PURE_POW(a, b)
LET num = PURE_NUM(p)
LET den = PURE_DEN(p)

CALL PRINT_PURE(p)

Comptime, include, try/catch, reversible ops

COMPTIME
    PRINT "compile time"
END COMPTIME

INCLUDE "shared.albi"

TRY
    THROW "boom"
CATCH err
    PRINT err
END TRY

REVADD cell, 5
REVSUB cell, 2
REVXOR cell, 1
REVSWAP a, b
REVNEG cell

Native escape hatches:

ENABLEC
    raw_counter = 123;
END ENABLE

ENABLEASM_X64
    ASM
        mov rax, 0FF0000h
        push rax
        sub rsp, 40
        mov rcx, qword [rsp + 40]
        call ALB_Set_Color
        add rsp, 48
    END ASM
DISABLEASM

Gotchas

• Use KEY(code), not KEY_STATE(code).
• The third argument to TEXT/DRAW TEXT must be text, not a raw number.
• CREATE_WINDOW "Title", w, h and CREATE_WINDOW("Title", w, h) are both valid.
• Use 1-based indexes for arrays and parallel groups.
• Prefer RETURN CAST(expr AS S32) over RETURN S32(expr) for typed results.
• MATCH default arms use ELSE => ….
• ASSERT(expr) is runtime assert; ASSERT p(x) is a logic-KB mutation — different syntax.
• Names like dx, ax, rax, r8 are legal — only ALB reserved keywords are off-limits.

Reserved keywords

Do not use any of these as identifiers or field names.

• A: ADVANCE, AND, APPLY_LUT, AS, ASM, ASSERT, ATOMIC
• B: BEGIN, BIND, BITFIELD, BLEND, BLIT_SAFE, BOUNDS, BREAK
• C: CALL, CASE, CAST, CATCH, CEASE, CHOOSE, CIRCLE, CLAIM, CLAMP, CLEAR, CLOSE, COLOR, COLOR_LUT, COMPTIME, CONSTRAINT, CONSTRAIN_TO, CONTINUE, CREATE_WINDOW, CROSS
• D: DECLAREMODULE, DEFAULT, DEFINE, DELAY, DEREF, DISABLEASM, DOT, DRAW, DROP
• E: ELSE, ENABLEASM, ENABLEC, END, ENDMODULE, ENDIF, ENSURE, ENTRY, ENUM
• F: FALSE, FILL, FIND, FINDALL, FLUSH, FLOAT2, FLOAT4, FMA, FOR, FOREACH, FORMAT, FRAME, FRAMES, FROM, FUNCTION, FUTURE
• H: HEIGHT, HISTORY
• I: IF, IMPORT, IMPORT_C, IN, INCLUDE, INLINEC, INPUT, INTO, IS
• K: KEY, KNOWS, KNOWS_CHANGE
• L: LEFT$, LEN, LERP, LET, LINE, LISTEN, LOAD, LOAD_STATE, LOCATE
• M: MATCH, MAT2, MAT3, MAT4, MID$, MOD, MODULE, MOUSE_CLICK, MODE, MOUSE_X, MOUSE_Y, MOUSE_WHEEL, MSG_BOX
• N: NORMALIZE, NOT, NOW
• O: OFFSETOF, ON, OPEN, OR, OUT
• P: PAINT, PARALLEL, PAST, PEEK, PIXEL, PLAY, PLOT, POKE, POLY, PREDICATE, PRINT, PRINT$, PROCEDURE, PROVE
• R: RANGE, READ, READLINE, READ_PIXEL, RECT, REF, RENDER_VIEWPORT, REPEAT, REQUIRE, RETRACT, RETURN, REVADD, REVERSIBLE, REVNEG, REVNOT, REVROL, REVROR, REVSUB, REVSWAP, REVXOR, RND, RULE
• S: SAVE_STATE, SELECT, SET_ALPHA, SET_CLIP, SET_ORIGIN, SETFULLSCREEN, SETRESIZABLE, SETSHOEBOX, SETSTRETCHY, SHL, SHR, SIZEOF, SLIDE, SOUND, SOURCE, SPAWN, SPLAT, STATIC_SPRITE, STATIC_SURFACE, STEP, STRICT, STRING, SWAPPOP, STRUCT, SWEEP, SYNC, SYS_RENDERER
• T: TEMPORAL, THEN, THROW, TICK, TIMELINE, TO, TRIANGLE, TRUE, TRY, TYPE, TYPEOF
• U: UNTIL, UPDATE, USE
• V: VERSION, VIRTUAL_HEIGHT, VIRTUAL_WIDTH, VISUAL_RULE, VMOUSE_X, VMOUSE_Y
• W: WHEN, WHILE, WIDTH, WITH, WRITE
• X: XOR

Authoring advice

• Prefer concrete statement syntax over invented function-call syntax.
• Prefer the examples in this sheet over intuition.
• Arrays and PARALLEL groups are 1-based.
• If a name looks like a command (FILL, DRAW, MATCH, PARALLEL), do not use it as an identifier.

Get unstuck

• Handbook — the learner-safe subset, explained.
• Examples — runnable .alb programs.
• Forum — ask questions, share programs.
• Contact — [email protected]

← Back home · Learn · IDE