Soluna Web Lab
home · contents · index

Contents

Index

App

local app = {}

Soluna app module


@meta soluna.app
@class soluna.app

function app.quit() end

Quits the application Signals the application to exit gracefully.

function app.set_ime_font(font_name, font_size) end

Sets the IME (Input Method Editor) font Configures the font used for IME text input display.


@param font_name string Font name for IME display
@param font_size integer Font size for IME display

function app.set_ime_rect(x, y, width, height) end

Sets the IME (Input Method Editor) position rectangle Defines the screen position where IME candidate window should appear.


@param x integer X position of IME rectangle
@param y integer Y position of IME rectangle
@param width integer Width of IME rectangle
@param height integer Height of IME rectangle

Args

local batch = {}


@meta
@class Batch

function batch:add(sprite, x, y) end

Adds a sprite to the render batch The sprite can be:


@param sprite number|userdata|string Sprite ID, material object, or command string
@param x? number X position (default: 0)
@param y? number Y position (default: 0)

function batch:layer(scale, rotation, x, y) end

Creates or closes a transformation layer Layers apply scale, rotation, and translation transformations to all sprites added while the layer is active. Layers can be nested. Usage:


@overload fun(self: Batch)
@overload fun(self: Batch, rotation: number)
@overload fun(self: Batch, x: number, y: number)
@overload fun(self: Batch, scale: number, x: number, y: number)
@param scale number Scale factor (cannot be 0)
@param rotation number Rotation in radians
@param x number X translation
@param y number Y translation

local args = {}


@class Args
@field width integer Current window width
@field height integer Current window height
@field batch Batch Render batch object

Callback

local callback = {}


@meta
@class Callback

function callback.frame(count) end

Called every frame


@param count integer Frame number

function callback.key(keycode, state) end

Called on keyboard events


@param keycode integer Key code
@param state integer 0=release, 1=press, 2=repeat

function callback.char(char) end

Called on character input events


@param char string UTF-8 character

function callback.mouse_button(button, state) end

Called on mouse button events


@param button integer 0=left, 1=right, 2=middle
@param state integer 0=release, 1=press

function callback.mouse_move(x, y) end

Called on mouse movement


@param x integer Mouse X position
@param y integer Mouse Y position

function callback.mouse_scroll(dx, dy) end

Called on mouse wheel scroll


@param dx number Horizontal scroll delta
@param dy number Vertical scroll delta

function callback.window_resize(width, height) end

Called on window resize


@param width integer New window width
@param height integer New window height

Coroutine

local coroutine = {}

Soluna coroutine module


@meta soluna.coroutine
@class soluna.coroutine

function coroutine.create(f) end

Creates a new coroutine Creates a coroutine compatible with ltask framework. The coroutine is tracked for ltask yield/resume handling.


@param f function Coroutine function
@return thread co Coroutine thread object

function coroutine.resume(co, ...) end

Resumes a coroutine Resumes execution of a coroutine. Handles ltask framework yielding automatically. Returns true and results on success, or false and error message on failure.


@param co thread Coroutine to resume
@param ... any Arguments to pass to coroutine
@return boolean success True if resumed successfully
@return any ... Return values from coroutine or error message

function coroutine.yield(...) end

Yields from current coroutine Suspends execution of current coroutine and returns control to caller. Compatible with ltask framework.


@param ... any Values to return to resume caller
@return any ... Values passed from resume

Crypt

local crypt = {}

Soluna crypt module


@meta soluna.crypt
@class soluna.crypt

function crypt.hexencode(data) end

Encodes binary data to hexadecimal string Converts binary data to a hexadecimal string representation (lowercase).


@param data string Binary data to encode
@return string hex Hexadecimal string (lowercase)

function crypt.sha1(data) end

Computes SHA-1 hash of input data Returns the SHA-1 hash as binary data (20 bytes).


@param data string Input data to hash
@return string hash Binary SHA-1 hash (20 bytes)

Datalist

local datalist = {}

Soluna datalist module


@meta soluna.datalist
@class soluna.datalist

function datalist.parse(data) end

Parses datalist format data


@param data string Datalist format text
@return table parsed Parsed data structure

function datalist.quote(str) end

Quotes a string for datalist format


@param str string String to quote
@return string quoted Quoted string

File

local file = {}

Soluna file module


@meta soluna.file
@class soluna.file

function file.load(filename) end

Loads a file’s contents


@param filename string File path
@return string? content File contents or nil on error

function file.attributes(filename) end

Gets file attributes


@param filename string File path
@return table? attributes File attributes or nil

function file.exist(filename) end

Checks if a file exists


@param filename string File path
@return boolean? exists True if file exists, nil if not

function file.local_exist(filename) end

Checks if a local file exists


@param filename string File path
@return boolean? exists True if file exists, nil if not

function file.local_load(filename) end

Loads a local file’s contents


@param filename string File path
@return string? content File contents or nil

function file.dir(path) end

Iterates over directory entries


@param path string Directory path
@return function iterator Iterator function

Font

local font = {}

Soluna font module


@meta soluna.font
@class soluna.font

function font.import(data) end

Imports a TrueType font


@param data string Raw TTF font data

function font.name(name) end

Gets font ID by name


@param name string Font name (empty string for last imported font)
@return integer? fontid Font ID, or nil if font not found

function font.cobj() end

Gets the font system C object


@return userdata fontcobj Font system object

Font System

font_system

local font_system = {}

Soluna font system module


@meta soluna.font.system
@class soluna.font.system

function font_system.ttfdata(name) end

Loads system font data by name


@param name string Font name (e.g., "Arial", "微软雅黑")
@return string? data TTF font data or nil if not found

Image

local image = {}

Soluna image module


@meta soluna.image
@class soluna.image

function image.load(data) end

Loads an image from binary data


@param data string Image file data (PNG, JPG, etc.)
@return userdata? imagedata Image data, or nil on error
@return integer|string width_or_error Image width, or error message on failure
@return integer? height Image height

function image.resize(data, width, height, scale_x, scale_y) end

Resizes an image by scale factors The image data can be either RGBA (4 channels) or grayscale (1 channel). Size is validated: for RGBA data must be widthheight4, for grayscale must be width*height.


@param data userdata Image data (external string from image.load)
@param width integer Source image width
@param height integer Source image height
@param scale_x number Horizontal scale factor (e.g., 0.5 for half width)
@param scale_y? number Vertical scale factor (default: same as scale_x)
@return userdata imagedata Resized image data
@return integer width New width (width * scale_x, rounded)
@return integer height New height (height * scale_y, rounded)

Layout

local layout = {}

Soluna layout module


@meta soluna.layout
@class soluna.layout

function layout.load(filename_or_list, scripts) end

Loads a layout definition from a file or table The filename_or_list parameter can be:

The scripts parameter is optional and provides a function table for script resolution.


@param filename_or_list string|table Layout definition file path or parsed list
@param scripts? table Script resolver function table
@return table document Layout document object with element access by ID

function layout.calc(document) end

Calculates layout positions and dimensions Runs the Yoga layout calculation on the document and updates all element positions. Returns an array of element objects, each with x, y, w, h fields set to calculated values.


@param document table Layout document from layout.load()
@return table[] elements Array of element objects with calculated x, y, w, h positions

Lfs

local lfs = {}

Soluna lfs module


@meta soluna.lfs
@class soluna.lfs

function lfs.attributes(filename) end

Gets file attributes


@param filename string File path
@return table? attributes File attributes or nil

function lfs.dir(path) end

Iterates over directory entries


@param path string Directory path
@return function iterator Iterator function

Material Mask

material_mask

local matmask = {}

Soluna material mask module


@meta soluna.material.mask
@class soluna.material.mask

function matmask.mask(sprite, color) end

Creates a colored mask sprite. Color format: 0xAARRGGBB (native-endian 32-bit integer). If the alpha byte is 00 it is forced to 0xFF (fully opaque).


@param sprite integer 1-based sprite index (will be stored as 0-based internally)
@param color  integer Color in 0xAARRGGBB format (e.g. 0xFF00FF00 for opaque green)
@return userdata mask Binary blob containing the packed mask_primitive; push it as a Lua string

Material Quad

material_quad

local matquad = {}

Soluna material quad module


@meta soluna.material.quad
@class soluna.material.quad

function matquad.quad(width, height, color) end

Creates a colored rectangle sprite Color format: RGBA as 32-bit integer 0xRRGGBBAA. If alpha channel (high byte) is 0, it defaults to 0xFF (opaque).


@param width integer Rectangle width in pixels
@param height integer Rectangle height in pixels
@param color integer Color in RGBA format (0xRRGGBBAA, e.g., 0xFF0000FF for opaque red)
@return userdata sprite Sprite object for rendering with batch:add()

Material Text

material_text

local mattext = {}

Soluna material text module


@meta soluna.material.text
@class soluna.material.text

function mattext.block(fontcobj, fontid, size, color, alignment) end

Creates a text block renderer Returns two functions: 1. block(text, width, height) - creates a renderable text sprite 2. cursor(text, position, width, height) - calculates cursor position in text Color format: RGBA as 32-bit integer. If alpha channel (high byte) is 0, defaults to 0xFF (opaque). Alignment codes (case-insensitive, can be combined): Horizontal: L (left), C (center), R (right) Vertical: T (top), V (center), B (bottom) Examples: “LT” (left-top), “CV” (center-vertical), “RB” (right-bottom)


@param fontcobj userdata Font system C object from font.cobj()
@param fontid integer Font ID from font.name()
@param size? integer Font size in pixels (default: 16)
@param color? integer Text color (RGBA as 0xRRGGBBAA, default: 0xff000000 = opaque black)
@param alignment? string Alignment code (default: no alignment)
@return fun(text: string, width: integer, height: integer): userdata block_function Creates text sprite
@return fun(text: string, position: integer, width: integer, height: integer): integer, integer, integer, integer, integer, integer cursor_function Returns x, y, w, h, actual_position, descent

Soluna

local soluna = {}

Soluna Game Engine API Reference This file documents the Soluna API using Lua meta annotations. Sprite ID type for single sprites or animation frames Sprite bundle mapping sprite names to IDs


@meta
@alias Sprite integer|integer[]
@alias SpriteBundle table<string, Sprite?>
@class soluna

soluna.platform = "windows"

Current platform identifier


@type "windows"|"macos"|"linux"|"wasm"

soluna.version = ""

Version string


@type string

soluna.version_api = 0

API version number


@type number

function soluna.settings() end

Returns the game settings table


@return table settings Game configuration from .game file

function soluna.set_window_title(text) end

Sets the window title


@param text string The window title text

function soluna.set_icon(data) end

Sets the window icon


@param data table Array of icon data tables with {data=..., width=..., height=...}

function soluna.gamedir(name) end

Returns the game data directory path


@param name? string Project name (defaults to settings.project)
@return string path Absolute path to game data directory

function soluna.load_sprites(filename) end

Loads a sprite bundle from a file


@param filename string Path to sprite definition file (.dl format)
@return SpriteBundle sprites Sprite bundle mapping sprite names to IDs

Text

local text = {}

Soluna text module


@meta soluna.text
@class soluna.text

function text.init(bundle_file) end

Initializes the text system with an icon bundle Loads an icon sprite bundle and makes it available for embedding in text via text.convert. The bundle is kept in memory to prevent garbage collection.


@param bundle_file string Path to icon sprite bundle file (.dl format)

text.convert = {}

Table that converts text strings with embedded icon tags and color codes Usage: local converted = text.convert[original_text] Supports:

The table uses weak keys/values for memory efficiency.


@type table<string, string>

Url

local url = {}

Soluna url module


@meta soluna.url
@class soluna.url

function url.open(link) end

Opens a URL in the system’s default web browser


@param link string The URL to open

Zip

local zip = {}

Soluna zip module


@meta soluna.zip
@class soluna.zip

function zip.open(filename, mode) end

Opens a ZIP file for reading or writing Opens a ZIP archive. Mode “r” opens for reading, “w” creates a new archive. Returns a file handle or nil on error.


@param filename string Path to ZIP file
@param mode "r"|"w" Open mode: "r" for read, "w" for write
@return userdata? zipfile ZIP file handle or nil on error