LOLang Technical Specification

LOLang is an embeddable, high-performance scripting language built for making games. It features low-overhead game logic, native windowing, 2D canvas drawing, 3D mesh and PBR rendering, procedural terrain, audio synthesis, and real-time networking.

Installation & PATH Configuration

Once the engine executable (lolang.exe or lolang) is placed on your machine, registering its folder in your path environment variable allows it to be invoked from any terminal or working directory.

Windows Configuration

1. Locate the directory containing lolang.exe (e.g., C:\LOLang\).
2. Press Win, search for Environment Variables, and open Edit the system environment variables.
3. Click Environment Variables...
4. Under User Variables (or System Variables), select Path and click Edit...
5. Click New and paste the containing folder path (e.g., C:\LOLang\ — exclude the binary filename).
6. Click OK on all open dialogs to commit the changes.

Alternatively, update the registry variable directly via Command Prompt:

setx PATH "%PATH%;C:\LOLang"

macOS & Linux Configuration

Append the binary directory to your active shell configuration file (~/.zshrc for default macOS shell, ~/.bashrc for standard Linux distros):

export PATH="$PATH:/path/to/lolang/folder"

Reload your shell configuration file to apply updates immediately:

source ~/.zshrc   // or source ~/.bashrc

Running Scripts & CLI Commands

With lolang added to your global PATH, executing scripts or launching interactive sessions can be performed via standard flags.

Native Binary Compilation

LOLang scripts can be linked together and compiled into standalone native executables that run independently without external runtime binaries.

lolang --compile game.lol -o game.exe

Multiple script files can be linked together into a single unified output binary:

lolang --compile main.lol levels.lol enemies.lol -o mygame.exe

Syntax & Core Conventions

LOLang scripts execute sequentially top-to-bottom. Semicolons at the end of statements are optional; one statement per line is standard.

Comments

// Single-line comments run to the end of the line
let speed = 120 // Trailing line comments are supported

Console Output & Input

print("System Initialization")
input(username)
print("Operator Registered: " + username)

Variables & Type System

Variables are declared using the let or local keyword. Dynamic typing is used throughout the environment.

let score = 0            // Number (64-bit float)
let entityName = "Unit_01" // String
let active = true          // Boolean
let target = nil          // Nil (Null)
let inventory = {}         // Table / Object

Operator Mechanics

let hp = 100
let critical = hp < 20 and not shielded
print("Current Health: " + hp + "/100")

Control Flow Logic

Conditional Logic

if hp <= 0 then
    print("Status: Terminated")
elseif hp < 20 then
    print("Status: Critical")
else
    print("Status: Operational")
end

Iteration Structures

// Conditional Iteration Loop
let counter = 0
while counter < 5 do
    print(counter)
    counter = counter + 1
end

// Numeric Range For Loop
for i = 1 to 5 do
    print("Step: " + tostring(i))
end

// Range Loop with Explicit Step
for i = 10 to 0 step -2 do
    print(i) // Outputs: 10, 8, 6, 4, 2, 0
end

Function Declarations

Functions are declared using the func keyword and return values via the return statement. Omitting an expression from a return statement yields nil.

func calculateDistance(x1, y1, x2, y2)
    let dx = x2 - x1
    let dy = y2 - y1
    return sqrt(dx * dx + dy * dy)
end

let dist = calculateDistance(0, 0, 3, 4)
print(dist) // Outputs: 5

Anonymous Functions & Closures

Functions are first-class values: func(...) ... end used as an expression produces an anonymous function, which can be stored, passed around, and closes over variables from its enclosing scope.

func makeCounter(start)
    let count = start
    return func()
        count = count + 1
        return count
    end
end

let nextId = makeCounter(100)
print(nextId()) // 101
print(nextId()) // 102

Variadic Parameters & Multi-Return

A trailing ... in a parameter list collects any extra positional arguments into a table bound to args. A function can return several values at once, which are only unpacked when consumed by a matching let a, b = ... destructuring assignment — anywhere else the result behaves as a single opaque value.

func sum(...)
    let total = 0
    for n in args do total = total + n end
    return total
end

print(sum(1, 2, 3, 4)) // 10

func minMax(t)
    // ... compute lo/hi ...
    return lo, hi
end

let lowest, highest = minMax(scores)

Tables & Array Containers

Tables represent LOLang's single unified data structure, serving as key-value dictionaries, structs, and 1-indexed arrays.

Named Struct Usage

let entity = { x = 10, y = 5, hp = 30 }
print(entity.hp)
entity.hp = entity.hp - 5

1-Indexed Array Usage

let coins = {}
push(coins, { x = 3, z = -2 })
push(coins, { x = 8, z = 4 })

let index = 1
while index <= table_size(coins) do
    let coin = coins[index]
    print(coin.x + ", " + coin.z)
    index = index + 1
end

Events System (on / emit)

Provides a signal architecture for decoupling logic components across scripts.

on "enemy_died" do
    score = score + 10
    print("Updated Score: " + score)
end

emit "enemy_died"

Module Imports

External source files are imported directly using the import statement, resolved relative to the calling script's location.

import "utils.lol"

Windowing & Engine Game Loop

Graphical execution follows a structured sequence: initialize window resources, enter the main process loop, poll input, clear render buffers, draw scene elements, and present the finished frame buffer.

window("LOLang Engine", 960, 600)

while true do
    update()
    clear_screen()

    // Scene drawing calls executed here

    frame_end(true)
end

2D Canvas Drawing API

CPU-side pixel canvas that renders elements directly over 3D scenes. Ideal for heads-up displays, text layers, and 2D games.

set_color(255, 255, 255)
draw_text("Current Score: " + score, 20, 20)

Native 2D Drawing Statements

An alternative keyword syntax available for 2D canvas operations, supporting rapid scripting and REPL usage.

Meshes & Procedural Primitives

Functions to load Wavefront .obj files or generate procedural geometries, returning integer mesh handles.

let cubeHandle = create_cube(1.5)

// Params: mesh, pos(x,y,z), rot(rx,ry,rz in degrees), scale(sx,sy,sz), color(r,g,b,a), useTexture
draw_mesh(cubeHandle, 0, 0, 0,  0, 45, 0,  1, 1, 1,  200, 100, 80, 255, false)

Rendering State

PBR Models Subsystem (glTF)

Supports physically-based rendering models with base color, normal maps, and metallic-roughness textures loaded from binary glTF (.glb) containers.

let biplane = load_model("biplane.glb")
draw_model(biplane, px, py, pz,  pitch, yaw, roll,  1, 1, 1)

Procedural Terrain Generation

Generates height-banded terrain dynamically using deterministic seed routines without requiring external mesh geometry files.

let terrain = create_terrain(2000, 2000, 100, 100, 7, 150)
draw_terrain(terrain, 0, -60, 0)

let floorHeight = terrain_height_at(terrain, playerX, playerZ, 0, -60, 0)
if playerY <= floorHeight then
    print("Surface Contact Detected")
end

Skybox Rendering Subsystem

Manages cubemap background environments via six orthogonal face textures.

Camera Subsystem Controls

Supports dual projection tracking modes: Orbit Mode (revolves around a target origin point) and FPS Mode (free-flying direction matrix).

Orbit Camera Controls (Default)

First-Person (FPS) Controls

camera_mode("fps")
if keydown("W") then camera_move(5 * dt(), 0, 0) end
camera_look(mouse_x() * 0.1, 0)

Lighting & Distance Fog

set_light(-0.3, -0.7, -0.4,  255, 250, 235,  110, 110, 120)
set_fog(120, 180, 240, 900)

Keyboard & Mouse Input Handling

Functions to query input device states, supporting character keys, control keys, functional keys (F1–F24), and mouse clicks.

if keydown("LEFT") then playerX = playerX - speed * dt() end
if keypressed("SPACE") then triggerJump() end

Audio Synthesis & Playback

Features a built-in multi-track synthesizer engine for dynamic audio generation alongside sample file playback systems.

Synthesizer Interface

Simple Sound Playback

synth_note(0, 440, "square", 0.15, 0.6) // Synthesizes a short test beep

UDP Networking Engine

Socket interface built for peer-to-peer communication and LAN multiplayer architectures.

let socket = net_open(9931)
net_send(socket, "192.168.1.10", 9932, "Ping Payload")

let packet = net_recv(socket)
if packet != nil then
    print(packet.ip + ": " + packet.data)
end

HTTP Protocol Subsystem

Synchronous HTTP communication API designed for simple web interactions.

let response = http_get("http://api.example.com/status")
if response.ok then
    print(response.body)
else
    print("Request failed: " + response.error)
end

Native Files & GUI Dialogs

Access native OS file selection and color picker dialog windows.

System Execution & Path Integration

Math Standard Library

Strings & Type Conversion

Miscellaneous Utilities

Interactive Compiler Workstation

Test statement compilation and evaluate system response states within the live execution environment interface.

// Waiting for compiler input action...