@class soluna.app.ImeRect

输入法候选窗口矩形 IME candidate window rectangle.

@class soluna.app.ImeRect
@field x number 左上角 X / Left coordinate
@field y number 左上角 Y / Top coordinate
@field width number 宽度 / Width
@field height number 高度 / Height
@field text_color? integer 文本 ARGB 颜色；alpha 为 0 时补为 0xff / Text color in ARGB; alpha 0 is promoted to 0xff

local app = {}

应用控制模块 Application control module.

@class soluna.app

function app.quit()

请求应用优雅退出 Requests graceful application quit.

function app.set_ime_font(font_name, font_size)

设置输入法字体 Sets the IME font face and pixel size.

@overload fun()
@overload fun(font_size: number)
@param font_name? string 字体名；nil 表示平台默认字体 / Font face; nil uses platform default
@param font_size number 字体像素大小 / Font size in pixels

function app.set_ime_rect(rect)

设置输入法候选窗口矩形 Sets the IME candidate window rectangle.

@param rect? soluna.app.ImeRect nil 会清除矩形 / nil clears the rectangle

@alias soluna.Drawable integer|string|userdata

可提交给 batch 的绘制对象 Drawable object accepted by `Batch:add`.

@alias soluna.Drawable integer|string|userdata

local batch = {}

绘制批次 Render batch object.

@class Batch

function batch:add(sprite, x, y)

向批次添加 sprite、material 对象或 packed stream Adds a sprite id, material userdata, or packed command stream.

@param sprite soluna.Drawable sprite ID、material userdata 或 packed string / Sprite id, material userdata, or packed string
@param x? number X 坐标，默认 0 / X position, default 0
@param y? number Y 坐标，默认 0 / Y position, default 0

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

打开或关闭变换层 Opens or closes a transform layer.

@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 缩放倍率，不能为 0 / Scale factor, cannot be 0
@param rotation number 旋转弧度 / Rotation in radians
@param x number X 平移 / X translation
@param y number Y 平移 / Y translation

function batch:point(x, y)

把屏幕点转换到当前 layer 坐标 Transforms a screen point into the current layer space.

@param x number 屏幕 X / Screen X
@param y number 屏幕 Y / Screen Y
@return number x 转换后的 X / Transformed X
@return number y 转换后的 Y / Transformed Y

local args = {}

入口参数表 Entry argument table passed to the game script.

@class Args
@field width integer 当前窗口宽度 / Current window width
@field height integer 当前窗口高度 / Current window height
@field batch Batch 绘制批次 / Render batch
@field [integer] string 启动参数 / Startup argument

local callback = {}

游戏入口返回的 callback 表 Callback table returned by the game entry script.

@class Callback

function callback.frame(count)

每帧调用 Called once per frame.

@param count integer frame 计数 / Frame counter

function callback.key(keycode, state)

键盘事件 Keyboard event.

@param keycode integer Sokol key code / Sokol key code
@param state integer 1 为按下，0 为释放 / 1 for key down, 0 for key up

function callback.char(codepoint)

字符输入事件 Text input event.

@param codepoint integer Unicode codepoint / Unicode codepoint

function callback.mouse_button(button, state)

鼠标按钮事件 Mouse button event.

@param button integer 0 左键，1 右键，2 中键 / 0 left, 1 right, 2 middle
@param state integer 1 为按下，0 为释放 / 1 for down, 0 for up

function callback.mouse_move(x, y)

鼠标移动事件 Mouse move event.

@param x integer 逻辑像素 X / Logical pixel X
@param y integer 逻辑像素 Y / Logical pixel Y

function callback.mouse_scroll(y, x)

鼠标滚轮事件 Mouse scroll event.

@param y integer 垂直滚动量 / Vertical scroll delta
@param x integer 水平滚动量 / Horizontal scroll delta

function callback.mouse(event_type)

其它鼠标事件 Other mouse event.

@param event_type integer Sokol event type / Sokol event type

function callback.touch_begin(x, y)

触摸开始 Touch begin event.

@param x integer 逻辑像素 X / Logical pixel X
@param y integer 逻辑像素 Y / Logical pixel Y

function callback.touch_moved(x, y)

触摸移动 Touch move event.

@param x integer 逻辑像素 X / Logical pixel X
@param y integer 逻辑像素 Y / Logical pixel Y

function callback.touch_end(x, y)

触摸结束 Touch end event.

@param x integer 逻辑像素 X / Logical pixel X
@param y integer 逻辑像素 Y / Logical pixel Y

function callback.touch_cancelled(x, y)

触摸取消 Touch cancelled event.

@param x integer 逻辑像素 X / Logical pixel X
@param y integer 逻辑像素 Y / Logical pixel Y

function callback.window_resize(width, height)

窗口尺寸变化 Window resize event.

@param width integer 新窗口宽度 / New window width
@param height integer 新窗口高度 / New window height

local coroutine = {}

ltask 兼容 coroutine 模块 ltask-compatible coroutine module.

@class soluna.coroutine

function coroutine.create(f)

创建受 ltask 跟踪的 coroutine Creates a coroutine tracked by the ltask bridge.

@param f function coroutine 函数 / Coroutine function
@return thread co coroutine 线程 / Coroutine thread

function coroutine.resume(co, ...)

恢复 coroutine Resumes a tracked coroutine.

@param co thread coroutine 线程 / Coroutine thread
@param ... any 传入参数 / Arguments
@return boolean ok 是否成功 / Whether resume succeeded
@return any ... 返回值或错误 / Return values or error

function coroutine.yield(...)

挂起当前 coroutine Yields from the current coroutine.

@param ... any 返回给 resume 的值 / Values returned to resume
@return any ... 下次 resume 传入的值 / Values passed by the next resume

local crypt = {}

密码辅助模块 Cryptography helper module.

@class soluna.crypt

function crypt.hexencode(data)

编码为小写十六进制字符串 Encodes binary data as lower-case hex.

@param data string 二进制数据 / Binary data
@return string hex 十六进制字符串 / Hex string

function crypt.sha1(data)

计算 SHA-1 摘要 Calculates SHA-1 digest.

@param data string 输入数据 / Input data
@return string hash 20 字节摘要 / 20-byte digest

local datalist = {}

datalist 解析模块 Datalist parser module.

@class soluna.datalist

function datalist.parse(data)

解析 datalist 文本 Parses datalist text.

@param data string datalist 文本 / Datalist text
@return table parsed 解析结果 / Parsed result

function datalist.quote(str)

为 datalist 格式引用字符串 Quotes a string for datalist syntax.

@param str string 原始字符串 / Raw string
@return string quoted quoted 字符串 / Quoted string

@class soluna.file.Attributes

文件属性表 File attribute table.

@class soluna.file.Attributes
@field mode "file"|"directory"|"link"|"socket"|"named pipe"|"char device"|"block device"|"other" 文件类型 / File type
@field dev integer 设备号 / Device id
@field ino integer inode / Inode
@field nlink integer 硬链接数 / Hard link count
@field uid integer owner user id / Owner user id
@field gid integer owner group id / Owner group id
@field rdev integer special file device id / Special file device id
@field access integer 最后访问时间 / Last access time
@field modification integer 最后修改时间 / Last modification time
@field change integer 最后状态变化时间 / Last status change time
@field size integer 文件大小 / File size
@field permissions string 权限字符串 / Permission string

local file = {}

文件加载模块 File loading module.

@class soluna.file

function file.load(filename, mode)

加载文件内容 Loads file contents.

@param filename string 文件路径 / File path
@param mode? string 本地文件打开模式，默认 `"rb"` / Local file open mode, default `"rb"`
@return string? content 文件内容；失败返回 nil / File contents, nil on failure

function file.attributes(filename)

获取文件属性 Gets file attributes.

@param filename string 文件路径 / File path
@return soluna.file.Attributes|string? attributes 本地文件返回属性表，zip 文件可返回 `"file"` 或 `"directory"` / Local files return attributes; zip files may return `"file"` or `"directory"`

function file.exist(filename)

判断文件是否存在 Checks whether a file exists.

@param filename string 文件路径 / File path
@return boolean? exists 存在时为 true，否则为 nil / true when found, nil otherwise

function file.local_exist(filename)

判断本地文件是否存在 Checks whether a local file exists.

@param filename string 文件路径 / File path
@return boolean? exists 存在时为 true，否则为 nil / true when found, nil otherwise

function file.local_load(filename, mode)

加载本地文件内容 Loads local file contents.

@param filename string 文件路径 / File path
@param mode? string 打开模式，默认 `"rb"` / Open mode, default `"rb"`
@return string? content 文件内容；失败返回 nil / File contents, nil on failure

function file.dir(path)

遍历目录条目 Iterates directory entries.

@param path string 目录路径 / Directory path
@return fun(): string? iterator 迭代器 / Iterator
@return userdata? state 本地目录句柄 / Local directory handle

local font = {}

字体模块 Font module.

@class soluna.font

function font.import(data)

导入 TrueType 字体数据 Imports TrueType font data.

@param data string TTF/TTC 字体数据 / TTF/TTC font data

function font.name(name)

按字体族名获取 font id Gets a font id by family name.

@param name string 字体族名 / Font family name
@return integer? fontid 字体 id；找不到时为 nil / Font id, nil when not found

function font.cobj()

返回字体管理器 C 指针 Returns the native font manager pointer.

@return lightuserdata fontcobj 字体管理器指针 / Font manager pointer

local font_system = {}

系统字体模块 System font module.

@class soluna.font.system

function font_system.ttfdata(name)

按字体族名读取系统 TTF/TTC 数据 Reads system TTF/TTC data by family name.

@param name string 字体族名 / Font family name
@return string? data 字体数据；wasm 或失败时可能为 nil / Font data, nil on wasm or failure

local image = {}

图片模块 Image module.

@class soluna.image

function image.load(data)

从 PNG 数据加载 RGBA 图片 Loads RGBA image data from PNG bytes.

@param data string PNG 数据 / PNG bytes
@return string? data RGBA 像素数据，失败时为 nil / RGBA pixels, nil on failure
@return integer|string width_or_error 成功时为宽度，失败时为错误信息 / Width on success, error message on failure
@return integer? height 高度 / Height

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

按比例缩放 RGBA 或灰度图片 Resizes RGBA or grayscale image data by scale factors.

@param data string RGBA 或灰度像素数据 / RGBA or grayscale pixels
@param width integer 原始宽度 / Source width
@param height integer 原始高度 / Source height
@param scale_x number X 缩放倍率 / X scale factor
@param scale_y? number Y 缩放倍率，默认等于 `scale_x` / Y scale factor, default is `scale_x`
@return string data 缩放后的像素数据 / Resized pixels
@return integer width 新宽度 / New width
@return integer height 新高度 / New height

local element = {}

layout 元素对象 Layout element object.

@class soluna.layout.Element

function element:update(attr)

更新元素 Yoga 属性 Updates Yoga attributes on the element.

@param attr table 属性表 / Attribute table

function element:get()

读取元素布局结果 Reads calculated element layout.

@return number x X 坐标 / X coordinate
@return number y Y 坐标 / Y coordinate
@return number w 宽度 / Width
@return number h 高度 / Height

function element:attribs()

返回元素属性表 Returns the element attribute table.

@return table attrs 属性表 / Attribute table

@class soluna.layout.Document

layout 文档对象 Layout document object.

@class soluna.layout.Document
@field [string] soluna.layout.Element 按 id 访问元素 / Element access by id

@class soluna.layout.Item

layout 绘制条目 Calculated drawable layout item.

@class soluna.layout.Item
@field x number X 坐标 / X coordinate
@field y number Y 坐标 / Y coordinate
@field w number 宽度 / Width
@field h number 高度 / Height
@field [string] any datalist 属性 / Datalist attributes

@class soluna.layout.Result

layout 计算结果 Calculated layout item list.

@class soluna.layout.Result
@field [integer] soluna.layout.Item 绘制条目 / Drawable item
@field width number 根节点宽度 / Root width
@field height number 根节点高度 / Root height

local layout = {}

Yoga layout 模块 Yoga layout module.

@class soluna.layout

function layout.load(filename_or_list, scripts)

加载 layout 定义 Loads a layout definition.

@param filename_or_list string|table layout 文件路径或已解析 datalist / Layout file path or parsed datalist
@param scripts? fun(name: string): table children 动态 children resolver / Dynamic children resolver
@return soluna.layout.Document document layout 文档 / Layout document

function layout.calc(document)

计算 layout 并返回绘制条目 Calculates layout and returns drawable items.

@param document soluna.layout.Document layout 文档 / Layout document
@return soluna.layout.Result items 绘制条目列表 / Drawable item list

@class soluna.lfs.Attributes

本地文件属性表 Local file attribute table.

@class soluna.lfs.Attributes
@field mode "file"|"directory"|"link"|"socket"|"named pipe"|"char device"|"block device"|"other" 文件类型 / File type
@field size integer 文件大小 / File size
@field access integer 最后访问时间 / Last access time
@field modification integer 最后修改时间 / Last modification time
@field change integer 最后状态变化时间 / Last status change time
@field permissions string 权限字符串 / Permission string

local lfs = {}

本地文件系统模块 Local filesystem module.

@class soluna.lfs

function lfs.attributes(filename, member)

获取文件属性 Gets file attributes.

@param filename string 文件路径 / File path
@param member? string 可选属性名 / Optional attribute name
@return soluna.lfs.Attributes|integer|string|nil attributes 属性表或指定属性 / Attribute table or selected attribute
@return string? err 错误信息 / Error message
@return integer? errno 系统错误码 / System errno

function lfs.dir(path)

遍历目录条目 Iterates directory entries.

@param path string 目录路径 / Directory path
@return fun(): string? iterator 迭代器 / Iterator
@return userdata state 目录句柄 / Directory handle

local matmask = {}

mask material 模块 Mask material module.

@class soluna.material.mask

function matmask.mask(sprite, color)

创建带颜色遮罩的 sprite command stream Creates a colored mask sprite command stream.

@param sprite integer 1-based sprite id / 1-based sprite id
@param color integer ARGB 颜色，alpha 为 0 时补为 0xff / ARGB color; alpha 0 is promoted to 0xff
@return string stream 可传给 `batch:add` 的 packed stream / Packed stream for `batch:add`

local matquad = {}

quad material 模块 Quad material module.

@class soluna.material.quad

function matquad.quad(width, height, color)

创建纯色矩形 command stream Creates a solid rectangle command stream.

@param width integer 宽度 / Width
@param height integer 高度 / Height
@param color integer ARGB 颜色，alpha 为 0 时补为 0xff / ARGB color; alpha 0 is promoted to 0xff
@return string stream 可传给 `batch:add` 的 packed stream / Packed stream for `batch:add`

@alias soluna.material.text.Block fun(text: string, width?: integer, height?: integer): string, integer

文本块创建函数 Text block builder function.

@alias soluna.material.text.Block fun(text: string, width?: integer, height?: integer): string, integer

@alias soluna.material.text.Cursor fun(text: string, position: integer, width?: integer, height?: integer): integer, integer, integer, integer, integer, integer

光标位置查询函数 Text cursor query function.

@alias soluna.material.text.Cursor fun(text: string, position: integer, width?: integer, height?: integer): integer, integer, integer, integer, integer, integer

local mattext = {}

text material 模块 Text material module.

@class soluna.material.text

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

创建文本块和光标查询函数 Creates text block and cursor query functions.

@param fontcobj lightuserdata `font.cobj()` 返回的字体管理器指针 / Font manager pointer returned by `font.cobj()`
@param fontid integer `font.name()` 返回的字体 id / Font id returned by `font.name()`
@param size? integer 字体像素大小，默认 16 / Font pixel size, default 16
@param color? integer ARGB 颜色，默认 `0xff000000` / ARGB color, default `0xff000000`
@param alignment? string 对齐代码，如 `"LT"`、`"CV"`、`"RB"` / Alignment code such as `"LT"`, `"CV"`, `"RB"`
@return soluna.material.text.Block block 创建 packed text stream / Creates packed text stream
@return soluna.material.text.Cursor cursor 查询光标矩形 / Queries cursor rectangle

@alias Sprite integer|integer[]

单个 sprite id 或动画帧 id 列表 Single sprite id or animation frame id list.

@alias Sprite integer|integer[]

@alias SpriteBundle table<string, Sprite?>

sprite bundle 名称到 id 的映射 Sprite bundle name-to-id mapping.

@alias SpriteBundle table<string, Sprite?>

@class soluna.IconImage

窗口图标图片描述 Window icon image descriptor.

@class soluna.IconImage
@field data string|userdata|lightuserdata RGBA 像素数据 / RGBA pixel buffer
@field w? integer 宽度；也可使用 `width` / Width; `width` is also accepted
@field h? integer 高度；也可使用 `height` / Height; `height` is also accepted
@field width? integer 宽度；`w` 的别名 / Width alias for `w`
@field height? integer 高度；`h` 的别名 / Height alias for `h`
@field stride? integer 每行字节数，默认 `width * 4` / Row stride in bytes, default `width * 4`
@field size? integer `lightuserdata` 数据大小 / Buffer size for `lightuserdata`

@class soluna.PreloadSprite

运行时预加载 sprite 图片 Runtime preloaded sprite image.

@class soluna.PreloadSprite
@field filename string 虚拟文件名 / Virtual filename
@field content string RGBA 像素数据 / RGBA pixel data
@field w integer 宽度 / Width
@field h integer 高度 / Height

@class soluna.AudioPlayOptions

音频播放选项 Audio playback options.

@class soluna.AudioPlayOptions
@field group? string audio bus 名称 / Audio bus name
@field volume? number 线性音量倍率 / Linear volume multiplier
@field pan? number 声像，范围通常为 `[-1.0, 1.0]` / Stereo pan, usually in `[-1.0, 1.0]`
@field pitch? number pitch 倍率 / Pitch multiplier
@field loop? boolean 是否循环播放 / Whether playback loops
@field stream? boolean 是否流式播放 / Whether to stream instead of preloading

local AudioVoice = {}

音频播放实例 Audio playback instance.

@class soluna.AudioVoice

function AudioVoice:stop(fade_seconds)

停止播放 Stops playback.

@param fade_seconds? number fade out 秒数 / Fade-out seconds
@return boolean ok voice 有效且请求成功时为 true / true when the voice is valid and the request succeeds

function AudioVoice:playing()

返回是否仍在播放 Returns whether the voice is still playing.

@return boolean playing 是否播放中 / Whether it is playing

function AudioVoice:set_volume(volume)

设置 voice 音量 Sets voice volume.

@param volume number 线性音量倍率 / Linear volume multiplier
@return boolean ok voice 有效时为 true / true when the voice is valid

function AudioVoice:set_pan(pan)

设置 voice 声像 Sets voice pan.

@param pan number 声像 / Stereo pan
@return boolean ok voice 有效时为 true / true when the voice is valid

function AudioVoice:set_pitch(pitch)

设置 voice pitch Sets voice pitch.

@param pitch number pitch 倍率 / Pitch multiplier
@return boolean ok voice 有效时为 true / true when the voice is valid

function AudioVoice:set_loop(loop)

设置 voice 是否循环 Sets whether the voice loops.

@param loop boolean 是否循环 / Whether to loop
@return boolean ok voice 有效时为 true / true when the voice is valid

function AudioVoice:seek(seconds)

跳转播放位置 Seeks to a playback position.

@param seconds number 目标秒数 / Target seconds
@return boolean ok voice 有效且 seek 成功时为 true / true when valid and seek succeeds

function AudioVoice:tell()

返回当前播放位置 Returns the current playback position.

@return number? seconds 当前秒数 / Current seconds
@return string? err 错误信息 / Error message

local AudioBus = {}

音频 bus 句柄 Audio bus handle.

@class soluna.AudioBus

function AudioBus:set_volume(volume)

设置 bus 音量 Sets bus volume.

@param volume number 线性音量倍率 / Linear volume multiplier
@return boolean ok bus 存在时为 true / true when the bus exists

local soluna = {}

Soluna 主模块 Soluna root module.

@class soluna
@field platform "windows"|"macos"|"linux"|"wasm" 当前平台 / Current platform
@field version string 运行时版本字符串 / Runtime version string
@field version_api integer API 版本号 / API version number

function soluna.settings()

返回 `.game` 设置表 Returns the `.game` settings table.

@return table settings 游戏设置 / Game settings

function soluna.set_window_title(text)

设置窗口标题 Sets the window title.

@param text string 标题文字 / Window title

function soluna.set_icon(data)

设置窗口图标 Sets one icon image or an icon image list.

@param data soluna.IconImage|soluna.IconImage[] 图标数据 / Icon data

function soluna.gamedir(name)

返回并创建游戏数据目录 Returns and creates the game data directory.

@param name? string 项目名，默认来自 `settings.project` / Project name, default from `settings.project`
@return string path 绝对路径，结尾带 `/` / Absolute path ending with `/`

function soluna.load_sprites(filename)

加载 sprite bundle Loads a sprite bundle.

@param filename string|table `.dl` 文件路径或已解析 bundle 表 / `.dl` path or parsed bundle table
@return SpriteBundle sprites sprite 名称映射 / Sprite name mapping

function soluna.preload(sprites)

预加载运行时生成的 RGBA sprite 图片 Preloads runtime-generated RGBA sprite images.

@param sprites soluna.PreloadSprite|soluna.PreloadSprite[] 单个 sprite 或列表 / One sprite or a list

function soluna.load_sounds(filename)

加载音频定义 bundle Loads an audio definition bundle.

@param filename string `sounds.dl` 文件路径 / `sounds.dl` path

function soluna.play_sound(name, opts)

播放音频并返回 voice Plays a sound and returns a voice handle.

@param name string `sounds.dl` 中的音频名 / Sound name from `sounds.dl`
@param opts? soluna.AudioPlayOptions 播放选项覆盖 / Playback option overrides
@return soluna.AudioVoice? voice voice 句柄 / Voice handle
@return string? err 错误信息 / Error message

function soluna.audio_bus(name)

返回 audio bus 句柄 Returns an audio bus handle.

@param name string bus 名称 / Bus name
@return soluna.AudioBus? bus bus 句柄 / Bus handle
@return string? err 错误信息 / Error message

local text = {}

文本预处理模块 Text preprocessing module.

@class soluna.text
@field convert table<string, string> 文本转换缓存表 / Text conversion cache table

function text.init(bundle_file)

初始化内嵌 icon bundle Initializes the embedded icon bundle.

@param bundle_file string icon bundle `.dl` 文件路径 / Icon bundle `.dl` path

local url = {}

URL 模块 URL module.

@class soluna.url

function url.open(link)

用系统默认浏览器打开 URL Opens a URL with the system default browser.

@param link string URL / URL

local zip = {}

ZIP 模块 ZIP module.

@class soluna.zip

function zip.open(filename, mode)

打开 ZIP 文件 Opens a ZIP archive.

@param filename string ZIP 文件路径 / ZIP file path
@param mode "r"|"w"|"a" 打开模式：读、写、追加 / Open mode: read, write, append
@return userdata? zipfile ZIP 句柄；失败时为 nil / ZIP handle, nil on failure