API REFERENCE
Complete Lua API for the Dino8 retro game SDK.
GLOBALS
CALLBACKS
_draw runs in world space (affected by camera), while _ui runs in screen space (ignores camera). Use _draw for gameplay and _ui for HUD, menus, and overlays that should stay fixed on screen.kwargs is a table of key-value pairs from CLI --key value args passed after the project path. Empty table if no args.-- run with: dino8 run . --scene cave --debug function _init(kwargs) -- kwargs = {scene="cave", debug="true"} local scene = kwargs.scene or "start" load_scene(scene) end function _update() -- game logic end function _draw() cls() -- render end
CONFIGURATION
conf.d8 that returns a table describing the game. This is where you set the title, resolution, assets, filters, and more. All values are available at runtime via the read-only CONFIG global — e.g. CONFIG.title, CONFIG.version, CONFIG.width.Metadata
| Field | Default | Description |
|---|---|---|
| title | "dino8" | Game title, shown in window title bar and used for save data. |
| author | "Unknown" | Creator name. |
| version | "0.1.0" | Semantic version string. |
| description | "A retro game SDK" | Short project description. |
| type | "game" | Project type: "game", "tool", or "data". |
| tags | nil | Array of tag strings for categorization. |
| thumbnail | nil | Path to a thumbnail image file. |
| entry | "main.d8" | Entry script file, relative to the project directory. |
| engine | nil | Target major engine version (integer). If the engine’s major version is lower, the project won’t run and will prompt you to update. If the engine is newer, a compatibility warning is shown. Omit to skip the check. |
Display
| Field | Default | Description |
|---|---|---|
| width | 128 | Canvas width in pixels. |
| height | 128 | Canvas height in pixels. |
| scale | 4 | Window scale multiplier. |
| fullscreen | false | Start in fullscreen mode. |
| speed | 1.0 | Game speed multiplier (0.5 = half speed, 2.0 = double). |
| gif_scale | 2 | Scale factor for GIF capture output. |
Assets
| Field | Default | Description |
|---|---|---|
| assets.sprites | nil | Path to sprite sheet PNG. |
| assets.map | nil | Path to tilemap JSON file. |
| assets.music | nil | Array of music file paths. Supports wildcards. |
SFX Clips
| Field | Default | Description |
|---|---|---|
| sfx_clips.<name>.path | — | Wildcard path to sound files (e.g. "sfx/hit_*.wav"). |
| sfx_clips.<name>.pitch | 1.0 | Fixed number or {min, max} range for random pitch. |
| sfx_clips.<name>.volume | 1.0 | Fixed number or {min, max} range for random volume. |
| sfx_clips.menu.navigate | nil | Clip name to play for pause menu navigation. |
| sfx_clips.menu.select | nil | Clip name to play for pause menu selection. |
| sfx_clips.menu.back | nil | Clip name to play for pause menu back/cancel. |
Filters
| Field | Default | Description |
|---|---|---|
| filters.upscale.type | none | Upscale filter: "scale2x", "hq2x", "hq3x", "hq4x", or "xbrz". |
| filters.scanline.enabled | false | Enable scanline effect. |
| filters.scanline.intensity | 0.2 | Scanline intensity (0.0–1.0). |
| filters.crt.enabled | false | Enable CRT screen effect. |
| filters.crt.curvature | 0.1 | CRT screen curvature amount. |
| filters.crt.glow | 0.2 | CRT glow intensity. |
| filters.chromatic.enabled | false | Enable chromatic aberration. |
| filters.chromatic.intensity | 0.5 | Chromatic aberration intensity. |
Custom Palette
| Field | Default | Description |
|---|---|---|
| palette | Dawnbringer 16 | Array of colors in 0xRRGGBB format. Up to 254 entries. |
Custom Fonts
font_style(3).| Field | Default | Description |
|---|---|---|
| font_styles[n].font | — | Path to a TTF font file. |
| font_styles[n].size | 10 | Font size in pixels. |
| font_styles[n].line_height | 0 | Line height (0 = font default). |
| font_styles[n].kerning | 0 | Extra letter spacing in pixels. |
Mobile
| Field | Default | Description |
|---|---|---|
| orientation | "landscape" | Screen orientation: "landscape", "portrait", or "both". |
| mobile_controls | true | Show on-screen virtual touch controls. |
| render_offset | 0.5 | Vertical position of the game canvas (0 = top, 0.5 = center, 1 = bottom). |
Publishing
dino8 push to upload to itch.io.| Field | Default | Description |
|---|---|---|
| itch.user | nil | Your itch.io username. |
| itch.game | nil | Your itch.io game slug. |
| itch.channel | "html5" | Upload channel. |
return { -- metadata title = "dino-quest", author = "doodleclan", version = "1.2.0", description = "A tiny dino adventure", type = "game", tags = { "platformer", "retro" }, thumbnail = "assets/thumb.png", entry = "main.d8", engine = 0, -- display width = 256, height = 144, scale = 3, fullscreen = false, speed = 1.0, gif_scale = 2, -- assets assets = { sprites = "assets/sprites.png", map = "assets/world.json", music = { "assets/music/title.ogg", "assets/music/level*.ogg", }, }, -- sound effects sfx_clips = { jump = { path = "assets/sfx/jump_*.wav", pitch = { 0.9, 1.1 }, volume = 0.7, }, land = { path = "assets/sfx/land.wav", pitch = 1.0, volume = { 0.4, 0.6 }, }, coin = { path = "assets/sfx/coin*.wav", pitch = { 0.95, 1.05 }, }, hurt = { path = "assets/sfx/hurt.wav", }, menu = { navigate = "coin", select = "jump", back = "hurt", }, }, -- filters filters = { upscale = { type = "hq2x", }, scanline = { enabled = true, intensity = 0.15, }, crt = { enabled = true, curvature = 0.1, glow = 0.2, }, chromatic = { enabled = false, intensity = 0.5, }, }, -- custom palette (replaces default) palette = { 0x140C1C, 0x442434, 0x30346D, 0x4E4A4E, 0x854C30, 0x346524, 0xD04648, 0x757161, 0x597DCE, 0xD27D2C, 0x8595A1, 0x6DAA2C, 0xD2AA99, 0x6DC2CA, 0xDAD45E, 0xDEEED6, }, -- custom fonts font_styles = { { font = "assets/fonts/pixel.ttf", size = 8, line_height = 10, kerning = 0, }, { font = "assets/fonts/title.ttf", size = 16, line_height = 20, kerning = 1, }, }, -- mobile orientation = "landscape", mobile_controls = true, render_offset = 0.5, -- itch.io publishing itch = { user = "doodleclan", game = "dino-quest", channel = "html5", }, }
DRAWING
PALETTE
TEXT
chr(0x2082) for subscript 2)FONT
Dino8 includes a built-in pixel font (dino8.ttf) with broad multilingual coverage plus custom glyphs for input controls and symbols.
Supported Character Sets
Basic Latin + Western European
Full diacritic coverage for all standard ASCII characters plus accented and special letters used by English, French, German, Spanish, Italian, Portuguese, Dutch, Swedish, Norwegian, Danish, Finnish, Polish, Turkish, and other Latin-script languages.
| Language | Extra Characters |
|---|---|
| French | é è ê ë î ï ô û ù ç à |
| German | ä ö ü ß |
| Spanish | á é í ó ú ñ ¿ ¡ |
| Nordic | å ä ö |
Japanese (Complete Syllabary)
Full support for modern game text with all 46 Hiragana, all 46 Katakana, dakuten (voiced) and handakuten (half-voiced) forms, all small/yōon combinations, and double-consonant support.
| Set | Coverage |
|---|---|
| Hiragana | あいうえお かきくけこ さしすせそ たちつてと なにぬねの はひふへほ まみむめも やゆよ らりるれろ わをん |
| Katakana | アイウエオ カキクケコ サシスセソ タチツテト ナニヌネノ ハヒフヘホ マミムメモ ヤユヨ ラリルレロ ワヲンー |
| Voiced (゛) | がぎぐげご ざじずぜぞ だぢづでど ばびぶべぼ ガギグゲゴ ザジズゼゾ ダヂヅデド バビブベボ |
| Half-voiced (゚) | ぱぴぷぺぽ パピプペポ |
| Small kana | ぁぃぅぇぉ っゃゅょゎ ァィゥェォ ッャュョヮ |
| Kanji | 一三上下世 二人剣勝右 土大始小左 日星月死水 火王界終負 風魔 |
| Punctuation | 、。「」!? |
Custom Input Glyphs
Use these escape codes in print() strings to show input icons inline with text. Also accessible via the GLYPH table.
| Glyph | Name | Usage |
|---|---|---|
| Cursor | GLYPH.CURSOR | |
| Menu | GLYPH.MENU | |
| Left | GLYPH.LEFT | |
| Right | GLYPH.RIGHT | |
| Up | GLYPH.UP | |
| Down | GLYPH.DOWN | |
| Action A | GLYPH.ACTION_A | |
| Action B | GLYPH.ACTION_B | |
| Bumper L | GLYPH.BUMPER_L | |
| Bumper R | GLYPH.BUMPER_R |
Symbol Glyphs
Custom pixel glyphs for common game symbols. Access via the GLYPH global table.
| Glyph | Name | Usage |
|---|---|---|
| ← | Left arrow | GLYPH.ARROW_LEFT |
| ↑ | Up arrow | GLYPH.ARROW_UP |
| → | Right arrow | GLYPH.ARROW_RIGHT |
| ↓ | Down arrow | GLYPH.ARROW_DOWN |
| ▲ | Up triangle | GLYPH.TRI_UP |
| ▶ | Right triangle (play) | GLYPH.TRI_RIGHT |
| ▼ | Down triangle | GLYPH.TRI_DOWN |
| ◀ | Left triangle | GLYPH.TRI_LEFT |
| ▴ | Small up triangle | GLYPH.TRI_UP_SM |
| ▸ | Small right triangle | GLYPH.TRI_RIGHT_SM |
| ▾ | Small down triangle | GLYPH.TRI_DOWN_SM |
| ◂ | Small left triangle | GLYPH.TRI_LEFT_SM |
| ■ | Filled square (stop) | GLYPH.SQUARE |
| □ | Outline square | GLYPH.SQUARE_OUTLINE |
| ● | Filled circle | GLYPH.CIRCLE |
| ○ | Outline circle | GLYPH.CIRCLE_OUTLINE |
| █ | Full block | GLYPH.BLOCK |
| ⏸ | Pause (double bar) | GLYPH.PAUSE |
| ★ | Star | GLYPH.STAR |
| ☆ | Star outline | GLYPH.STAR_OUTLINE |
| ✓ | Check mark | GLYPH.CHECK |
| ✗ | Ballot X | GLYPH.CROSS |
| ♪ | Eighth note | GLYPH.NOTE |
| ♫ | Beamed eighth notes | GLYPH.NOTES |
| ♥ | Heart | GLYPH.HEART |
| ♡ | Heart outline | GLYPH.HEART_OUTLINE |
| ♠ | Spade | GLYPH.SPADE |
| ♣ | Club | GLYPH.CLUB |
| ♦ | Diamond | GLYPH.DIAMOND |
function _draw() -- Input glyphs via GLYPH table print(GLYPH.UP .. GLYPH.DOWN .. GLYPH.LEFT .. GLYPH.RIGHT .. " TO MOVE", 4, 10, 7) print(GLYPH.ACTION_A .. " JUMP " .. GLYPH.ACTION_B .. " ATTACK", 4, 20, 7) -- Symbol glyphs via GLYPH table print(GLYPH.HEART .. " LIVES: 3", 4, 30, 8) print(GLYPH.STAR .. " SCORE: 1000", 4, 40, 10) print(GLYPH.TRI_RIGHT .. " PLAY", 4, 50, 7) end
SPRITES
CAMERA
_draw. Use _ui for elements that should ignore the camera.TRANSFORM
cam_push/cam_pop to isolate transforms.-- rotate a house around its center cam_push() cam_translate(cx, cy) -- move origin to pivot cam_rotate(angle) -- rotate around it cam_translate(-cx, -cy) -- offset back draw_house() cam_pop()
-- scale a card from its center cam_push() cam_translate(cx, cy) -- move origin to center cam_scale(sx, sy) -- scale around it cam_translate(-ox, -oy) -- offset to top-left draw_card() cam_pop()
CLIPPING
RENDER TARGETS
SNAPSHOT
FILTERS
CUSTOM SHADERS
POLYGON
BEZIER CURVES
MASK
KEYBOARD & BUTTONS
btn/btnp use remappable bindings; key/keyp read physical keys directly. Up to 4 players supported.MOUSE
GAMEPAD
btn/btnp with the player argument for per-controller input.TOUCH & MOBILE
SOUND EFFECTS
MUSIC
TABLE UTILITIES
MATH
COLLISION
UTILITIES
EASING
Ease table. Default: Ease.Quad. Available curves: Quad, Cubic, Quart, Quint, Sine, Expo, Circ, Back, Elastic, Bounceease_in(t, Ease.Bounce)ease_out(t, Ease.Elastic)ease_in_out(t, Ease.Back)PERSISTENCE
FILE I/O
LEVELS & TILEMAPS
tileset_cols enables 2D grid tileset layout.-- create a 4x3 level local lvl = create_level({ id = 1, width = 4, height = 3, grid_size = 16, tileset = "assets/tiles.png", tileset_cols = 8, tiles = { 0, 0, 0, 0, 0, 0, 0, 0, 1, 2, 2, 3, }, }) -- draw visible region function _draw() draw_level(lvl, 0,0, -- cell origin 0,0, -- screen pos 4,3) -- cells w,h end -- swap a tile at runtime set_tile(lvl, 1, 2, 5) -- read it back local t = get_tile(lvl, 1, 2) -- t == 5
PHYSICS
dt seconds — use when you need fixed-step control instead of automatic stepping-- set up gravity gravity(0, 200) -- create a ball and a floor local ball = body("circle", 64, 32, 8) local floor = body("static_box", 64, 120, 128, 8) -- launch the ball to the right body_push(ball, 500, 0) function _draw() cls() local x, y = body_pos(ball) circfill(x, y, 8, 7) end
PARTICLES
| field | default | description |
|---|---|---|
| sprite | nil | Image ID for sprite particles. Omit for pixel particles. |
| frame | nil | Source rect {sx, sy, sw, sh} within sprite sheet. |
| frame_range | nil | Animation frames {start, end} for sprite sheet animation. |
| anim_duration | nil | Seconds for one animation cycle. |
| anim_loop | false | Loop the sprite animation. |
| max | 256 | Particle pool size. |
| rate | 0 | Particles emitted per second. 0 = burst only. |
| life | 1 | Particle lifetime in seconds, or {min, max} for random range. |
| speed | 0 | Emission speed in px/sec, or {min, max} for random range. |
| direction | 0 | Emission angle in radians. |
| spread | 0 | Emission cone width in radians (6.28 = full circle). |
| gravity | 0 | Downward pull: number or {gx, gy} for directional. |
| damping | 1.0 | Velocity multiplier per frame. 1.0 = no damping. |
| colors | nil | Palette indices for color progression over lifetime. |
| size | 1 | Particle scale, or {start, end} to animate over lifetime. |
| spin | 0 | Rotation speed in rad/sec, or {min, max} for random range. |
| area | nil | Emission shape: {"circ", r} or {"rect", w, h}. |
-- fire sparks emitter local sparks = emitter({ rate = 30, life = {0.3, 0.8}, speed = {20, 60}, spread = 6.28, colors = {10, 9, 8}, size = {2, 0}, gravity = 40, }) function _draw() cls() emitter_draw(sparks, 64, 64) end -- one-shot burst on click local poof = emitter({ rate = 0, life = 0.4, speed = {30, 80}, spread = 6.28, colors = {7, 6}, }) emit(poof, 20)
TWEENS
local ball = { x=0, y=64 } -- slide ball to x=120 over 1s tween(ball, 1, { x=120 }) -- bounce ease with callback tween(ball, 0.5, { y=32 }, Ease.Bounce, function() print("landed!") end)
-- do something after 2 seconds timer(2, function() print("done!") end) -- tick every 0.5s for 3s timer(3, 0.5, { on_interval = function(t) print("tick", t) end, on_complete = function() print("finished") end, })
local p = { x=0, y=0 } -- move right, then down chain( tween(p, 0.5, { x=100 }), tween(p, 0.5, { y=80 }), function() print("path done") end )
local a = { x=0 } local b = { x=0 } -- animate both at once group( tween(a, 1, { x=100 }), tween(b, 0.5, { x=50 }), function() print("both done") end )
WINDOW
TIME
T and DT globals.PLATFORM
GIF CAPTURE
SCREENSHOT
NOTIFICATIONS
CONSOLE & LOADING
WEBSOCKET
websocket_send are auto-encoded to JSON. Works on both native and web builds.HTTP
http_post are auto-encoded to JSON.