1. Game Development

1.1. Lua

Singe uses the Lua programming language (http://www.lua.org) for scripting game logic. Lua is fast, lightweight, object-oriented, easy to use, and actually used in the games industry. This book does not teach it; Learn to Program with Singe, in the same download as this one, does, from nothing to a finished game in thirty-one lessons. Video tutorials for Lua are on the Kangaroo Punch YouTube channel, and the language’s own reference is at http://www.lua.org.

1.2. Basic Rules

  • Singe is cross-platform. Things you do not normally need to worry about on Windows are important. Filenames are case-sensitive —  MyScript.singe and myscript.singe are not the same file. You should also use UNIX path separators — / rather than \. This both makes your code cleaner (no double-escaped backslashes) and works everywhere Singe is supported.

  • Pick a distinctive name for your game folder. Do not use spaces.

  • Use the included Singe Framework. Do not copy the framework into your game scripts. By including the provided framework you help with future compatibility as Singe is updated. Begin (or end) your game script with:

    dofile("Singe/Framework.singe")
  • Keep your game self-contained. If you build on a third-party framework or share code between your games, copy it into your game directory. Never reference a directory beside your game; the only file outside your game a script may load is Singe/Framework.singe. A single-file game (see Single-File Games) packs exactly one directory, and a game that reaches outside it cannot be packed.

  • Stay out of the Singe/ folder. This is managed by Singe and anything added or changed here is subject to future deletion.

  • Include a games.dat. This is extremely important for new users. While other front ends and Singe-based menu systems exist, it is vital that you include data for the built-in menu system. Almost all support issues are due to missing or malformed games.dat files.

  • Do not distribute non-essential files. Never ship Singe binaries or Singe-provided scripts with your game. Do not ship index files generated from the videos.

1.3. Reloading While You Work

Run the game with --reload (-R) and Singe watches every loose script file the game has loaded. Save a change to one of them and the game starts again from its script a moment later: everything the script made goes (sprites, sounds, fonts, videos, GUIs, the 3D scene, physics, emitters, the overlay back to its default size, the effects volume and the mouse back to their startup state), the engine stays (the window, the GPU, the controllers), the disc is parked on its first frame again as at startup, and the script runs afresh, so a 52 MB model is back on screen in the time it takes to load it rather than the time it takes to start Singe. A key or button held through the reload is ignored until it is released, as at a fresh start. F5 reloads on demand, and a script can ask for it with singeReload(). Packed games have nothing to watch; the option is for a game in a directory. A script error on reload is printed and the game sits empty until the next reload fixes it; the file stays watched, so saving the fix is enough. Because the reload runs the same teardown that quitting does, anything a script leaks shows up here first.

1.4. Debugging in ZeroBrane Studio

ZeroBrane Studio is a free Lua IDE, and Singe carries what it takes to run and debug a game from it: breakpoints, stepping, the Stack and Watch windows, a game that holds still while it is stopped, a stop in the IDE when an error is about to end the game, and autocompletion and tooltips for the whole API in English, French, Italian, German, or Spanish. The debugger half is MobDebug, built into Singe and started by --debug, so a game needs no line of its own; anything else that speaks MobDebug’s protocol can connect the same way.

1.4.1. Setting It Up

Singe unpacks a ZeroBrane Studio package into its support folder, as Singe/ZeroBrane/singe.lua, and keeps it current from one release to the next. Tell ZeroBrane Studio where it is with one line in its user.lua (Edit > Preferences > Settings: User), then restart it:

package "/home/me/Singe/Singe/ZeroBrane/singe.lua"

Singe then appears under Project > Lua Interpreter, with Project > Debug With Singe and a Singe button on the toolbar to start a game under the debugger in one step. .singe files open as Lua, .rml documents as XML, and .rcss style sheets as CSS. Make the game’s folder the project (Project > Project Directory > Choose). The package looks for Singe in that folder and the three above it, taking the newest build for your machine, and then on the PATH; when it finds none it asks the first time you run a game, and remembers. Project > Choose Singe Executable picks another, and path.singe = "/path/to/Singe" in user.lua overrides both.

1.4.2. Running and Debugging

Project > Run (F6) starts the game, and Project > Start Debugging (F5) starts it under the debugger. The script is the project’s start file when one is set (right click it in the project tree and choose Set As Start File), and the file being edited otherwise; when that is one of the game’s modules rather than a .singe file, the project’s only .singe file runs instead. Singe starts in the folder holding its executable, as the menu would start it, so Singe/Framework.singe and every name relative to that folder resolve as they always do, and the game’s games.dat entry supplies its video and settings. Project > Command Line Parameters adds options of your own, -v and a video for a game without an entry among them.

Click in the margin to set a breakpoint. The game stops there with its locals in the Stack window, the Watch window evaluates expressions, and Step Into (F10), Step Over (Shift+F10), and Step Out (Ctrl+F10) behave as in any Lua program, inside singeMain too. Project > Break stops a game wherever it is. While the game is stopped, the disc, every video, and every sound pause just as for the pause key, and go on from the same place afterwards.

When an error is about to end the game — a Lua error, or an engine call handed something it cannot use — the IDE stops first, in the Singe folder’s Debugger.singe, and the Output window says what went wrong. The Stack window keeps the script’s own frames below that file, with their locals as they were. Continue, and the game ends as it would have, with the error and a traceback in the Output window; double click a line of the traceback to open the file there.

The game runs with --reload, so saving a script starts the game again and the debugger with it, breakpoints and all. Project > Reload Singe When a Script Changes turns that off.

1.4.3. Autocompletion and the Reference

Autocompletion offers every function, callback, and constant of the API, and a tooltip gives the arguments and the first paragraph of the entry. Project > Analyze (Shift+F7) knows the API as well, so it flags a misspelled call rather than every call. ZeroBrane Studio’s own language setting picks the tooltips' language: language = "fr" in user.lua gives French, and the same goes for Italian (it), German (de), and Spanish (es). Right click a name and choose Look Up in Singe Reference to open its entry in a browser; Help > Singe Reference opens the start. Both need the documentation download unpacked beside Singe, as Singe-Docs-v3.00 or Singe-Docs-v3.00-fr and so on, the one in ZeroBrane Studio’s language taken first; singe = { reference = "/path/to/Reference.html" } in user.lua names another.

1.4.4. Debugging a Cabinet

The debugger works across a network. On the machine with ZeroBrane Studio, open the game’s folder as the project and choose Project > Start Debugger Server. On the cabinet, start the game with --debug=HOST, where HOST is that machine’s name or address; the port is 8172 unless --debug=HOST:PORT says otherwise, and the first machine has to accept connections on it. A cabinet that starts its games from the menu can carry debug = "HOST:PORT" in its settings file instead, and every game it starts connects, the menu among them. The IDE stops each one at its first line, where Continue (F5) sets it going; debugger.runonstart = true in user.lua lets it run straight on to the first breakpoint. The cabinet reports its own paths, which ZeroBrane Studio maps onto the project’s files the first time it stops, so the same game folder on both machines is all it needs. With nothing listening, a game plays as usual once the attempt to connect gives up, which takes no more than two seconds.

1.4.5. Limits

  • Debug a game loose, from its folder. A packed .game has no files on disk for the IDE to open.

  • An error inside singeMain stops in Framework.singe, which runs singeMain as a coroutine; the message names the line of your script.

  • While the IDE has the game stopped, the window does not redraw, and closing it waits until you continue. Stop Process (Shift+F5) ends the game at once.

  • Singe stops a script that never returns when its window is closed, but not under the debugger, which owns the script while it runs; Break finds where it is stuck.

1.5. Deterministic Test Mode

--deterministic is a testing facility, not a way to play. It makes the engine ignore real time altogether: instead of asking the machine what time it is, the engine runs on a virtual clock that moves a fixed step — 15 milliseconds by default — exactly once a frame. Everything paced by time follows that clock: physics steps, sprite and model animation, particles, navigation, the GUI’s animations and transitions, os.clock(), singeGetTicks(), and a bare os.time() (a game that seeds its generator from the wall clock when a game starts seeds it from the virtual one, so it draws the same numbers every run; os.time given a date table converts it as Lua always has). The disc follows it too: while it is playing, each video frame stays on for as many engine frames as its presentation time is worth on that clock (two or three at the default step for a thirty-frame disc), as in real play, and a paused or searched disc stays where it was put. Lua’s generator and the engine’s own are seeded from a fixed number. Nothing waits for anything, so the game runs as fast as the machine will let it.

The point of all this is that a screenshot taken at a fixed frame number is the same picture in every run. Without it, frame 40 is a different moment each time — the physics has taken a different number of steps and the disc is on a different video frame — so two runs of the same unchanged game can differ by a million pixels, and a real change can hide inside that noise.

What it costs is everything that depends on real time. Audio still plays on the device’s own clock, which no virtual clock reaches, so sound drifts away from the picture and means nothing — unless the run is recorded with --record, when the sound is mixed into memory one step at a time along with the picture, so a recording made this way is exact frame by frame and sample by sample (see singeRecordStart). The frame rate means nothing either, and neither does anything a game measures in seconds. Never report a performance number, an audio problem or a timing problem from a run in this mode, and never ship a launcher that uses it.

The number the option carries, if it carries one, is both the size of the step and the seed the generators start from, 1 to 1000:

Singe --deterministic          the default 15 ms step, seeded with 15
Singe --deterministic=20       a 20 ms step, seeded with 20

Two runs at the same number are identical; two runs at different numbers are each repeatable but not the same as each other, which is how a test asks for a different but equally reproducible run. It may be set in a settings file as deterministic like any other option.

1.5.1. Reference Screenshots

The scenes in testScripts each take a screenshot or two at a fixed frame number and quit by themselves, so in this mode they make a set of reference pictures a later change can be compared against pixel for pixel. To record them, run every scene with the option and keep what lands in the data directory:

for n in 2 3 4 5 6 7 8 9 10 11 13 14 15 16 18 19 21 22 23 24 25 26 \
         36 37 38 39 40 41 42 43 44 45 48 49 50 51; do
    Singe -w -d data --deterministic -v Singe/menuBackground.mkv \
          testScripts/scene$n.singe
done

The scenes left out of that loop want their own options, the same ones the table in testScripts/README.md gives them: scene12 runs with no disc at all, scene17 with the disc, and scene20 with -C 720x480, all three with SDL_GPU_DRIVER=nothing; scene27 to scene35 want -x 1280 -y 720 -C 1280x720 and no disc; scene46 wants -g '10 5'; and scene47 wants --bezeldir=testScripts/bezels --bezel=cabinet.png. Copy the singe*.png files out of data/testScripts after each run, since the next run numbers its screenshots from zero again.

Comparing a later build is then a matter of running the same commands and asking for the difference, which must be nothing:

compare -metric AE reference/scene36-singe000.png new/scene36-singe000.png null:

1.6. Where Files Live

Paths inside a script are relative to the directory Singe was started from, not to the script. Use the DIR global, which Framework.singe sets to the script’s own directory, so a game works no matter where it is installed:

crosshair = spriteLoad(DIR .. "sprite_Crosshair.png")

Everything Singe writes goes to the data directory (singeGetDataPath()), data/ beside the games unless --datadir says otherwise, so a game can live on read-only media. Singe 2.x wrote saves and settings into the game’s own directory; a game that still does so fails on a read-only install, so keep every io.output under singeGetDataPath().

1.7. Packaging Your Game

A finished game ships as one .game file, described next. Nothing else is needed: the player copies the file beside the Singe binary and the menu lists it. Singe no longer installs archives.

1.8. Single-File Games

A game can be one file. singe --pack writes a game directory into an SQLite database, and Singe runs it from there: scripts, sprites, sounds, fonts, framefiles, and video all load straight out of the database, and installing the game is copying the file next to the executable. The menu lists every .game file it finds beside the game directories.

Singe --pack MyGame MyGame.game       Pack the MyGame directory into MyGame.game
Singe MyGame.game                     Run the first games.dat entry in it
Singe --entry=2 MyGame.game           Run its second entry
Singe --unpack MyGame.game MyGame     Write the files back out
Singe --patch MyGame.game fixes       Replace files from a directory (or a patch database)

Nothing in a game has to change to be packed. Every name a script uses, whether through dofile, require, io.open and its relatives, spriteLoad, soundLoad, fontLoad, videoLoad, a framefile, or a controls.cfg, goes through one lookup. For a loose game that lookup is the plain filesystem, relative to the directory Singe was started from, exactly as before. For a packed game a name is tried in three places, in this order, and the first hit wins:

  1. A loose directory named like the database without its extension (MyGame/ beside MyGame.game). This is how you keep editing a packed game, and how a player mods one: files dropped there beat the packed copies.

  2. The game’s data directory, under files/. Everything a game writes with io.output or io.open(name, "w") lands here, so a saved game.cfg beats the packed original and the database is never written.

  3. The database itself.

Inside a database, names are matched without regard to case, with either path separator, and relative to the game root. A leading component equal to the game’s own directory name is ignored, so MyGame/Cfg/game.cfg, Cfg/game.cfg, and DIR .. "Cfg/game.cfg" all find the same file. The name of the database itself (MyGame.game, with or without a trailing separator) is the game root, as . is from inside. Names starting with Singe/ or with the data directory stay on the filesystem; Singe/Framework.singe and singeGetDataPath() work as always, and such a name may use .. as long as it stays below that prefix (the controls.cfg at the root of the data directory is found that way). Any other relative name with a .. component resolves nowhere inside a packed game: io.open returns nil with a message saying the name reaches outside the game, lfs.attributes returns nil, and spriteLoad and its kind report the file as missing. The game root is a directory, not a file: io.open on it returns nil, and lfs.mkdir and lfs.rmdir refuse it. lfs.dir on a packed directory lists the union of the three places, sorted without regard to case; when a loose file and a packed one differ only in case, the loose spelling is listed. lfs.attributes on a packed file answers as the real lfs does: the whole table with one argument, one field by name (an unknown name raises an error), or a table of yours filled in; a missing file returns nil, a message and the error number. require("name") finds name.lua, name/init.lua, or name.singe under the script’s directory, then under the game root.

io.open, io.lines and io.input on a name that lives only inside the database hand back a file of Singe’s own rather than one of Lua’s. Lua’s file handle is a C FILE *, and a database row is not a file, so reading one used to mean writing it out beside the game and opening that copy; Singe’s handle reads the row where it lies. It answers to everything Lua’s does — read with every format ("a", "l", "L", "n", and a byte count), lines, seek, close, flush and setvbuf — io.type calls it a file, io.read and io.close take it, and it closes itself when it is collected or when a <close> variable goes out of scope. The one difference is that writing to it is an error, because what it is reading is inside the database and the database is never written. A game writing a file gets a real one in its data directory exactly as before, and so does every name that is not packed. testScripts/packedIo is the test that holds all of this to Lua’s own behavior; its header says how to run it.

The packer refuses a directory that has no games.dat, that contains controls.dat, Framework.singe, a file whose extension is exe, sh, bat, or cmd, or an extensionless file whose name starts with singe, that has a top level entry named like the directory itself (that would make the own-directory rule ambiguous), or whose scripts and data files reach outside the game with ..; it reports every such file, with the line. Two files whose names differ only by case cannot both be packed. Stale .index files are skipped. --unpack refuses a database whose stored names would land outside the target directory (an absolute path, a drive letter, or a .. component). A game that references another game’s directory (a shared framework beside it) must copy that directory inside first. Before the database is committed, its games.dat is checked: every entry needs a SCRIPT, and each SCRIPT, VIDEO, CABINET, MARQUEE, and ATTRACT it names must be a file in the database (or under Singe/); a bad path is reported with the entry’s title and the pack is refused. --patch runs the same check on the patched game, so a patch cannot leave a dangling path behind either.

--patch takes either a directory laid out like the game, whose files replace the packed ones, or a .patch file made by --pack from such a directory (Singe --pack fixes MyGame-1.1.patch; a patch needs no games.dat). Files the patch does not name are left alone. Either way the change is one transaction: the game is intact if it is interrupted. A patch may also carry a removed(path) table naming files to delete. A .patch can be unpacked like a game, but it cannot be run and the menu ignores it.

A patch that replaces a large file with a small one leaves the space the old contents used inside the database, where SQLite keeps it for the next thing written rather than giving it back. That is fine for a patch that changes a script, and wasteful for a developer who repacks a video a dozen times: the .game can end up several times the size of its contents. So --patch looks at the free space when the transaction has committed and, when there is at least a megabyte of it, compacts the database and says how much it recovered:

>>> Recovered 8007680 bytes of space the old contents were using

The result is byte for byte the size of a fresh pack of the same files. Compacting rewrites the whole file, so it is skipped when there is little to gain. Nothing else in Singe needs this; a game is only ever written by the packer.

A packed game’s data directory is named for the database and then for the script’s directory inside it: MyGame/ for a MyGame.game whose script sits at its root under the data directory (data/MyGame/ by default), which is where the loose MyGame/MyGame.singe has it, so saves and settings are shared between a loose install and a packed one; a script packed in a subdirectory (Game/Main.singe) gets MyGame/Game/. The video index goes there too.

That directory belongs to the game, not to the name of its file. A game with a GAME_ID in its games.dat marks the directory as its own the first time it writes there, with a small package.id file holding the id, and from then on finds it by that id: rename MyGame.game, or move it to another folder, and it still uses MyGame/. A different game whose file is also called MyGame.game gets a directory of its own, MyGame- and the first eight characters of its id. A directory from before this was kept carries no mark and goes to the first game of that name to run. A game with no GAME_ID has only its file name to go by, so two such games with the same file name share a directory, as they always did.

Earlier 3.00 builds gave a packed game whose script sat in a subdirectory the data directory Game/ under the base, which every archive with that layout shared. Such a game’s saves now belong under MyGame/Game/; move them by hand. Earlier 3.00 builds also kept the game’s own folder, the one its games.dat names the script under, so a MyGame.game packed from MyGame/ wrote to MyGame/MyGame/; move what is there up one level.

When Singe runs a game from a database the menu passes CONTAINER in the games.dat entry it launches; the field is set by the menu, never by hand.

For your own data, require("sqlite3") gives scripts the lsqlite3 binding to the same SQLite the engine uses. Keep databases the game writes in singeGetDataPath():

local sqlite3 = require("sqlite3")
local db = sqlite3.open(singeGetDataPath() .. "scores.db")
db:exec("CREATE TABLE IF NOT EXISTS scores (name TEXT, score INTEGER)")
for row in db:nrows("SELECT name, score FROM scores ORDER BY score DESC LIMIT 10") do
    print(row.name, row.score)
end
db:close()

sqlite3.open finds a name the way io.open does, so a database can ship inside the game — level tables, dialogue, item lists — and still open when the game is packed. Opened read only, a packed database is read where it lies, with nothing copied:

local levels = sqlite3.open(DIR .. "levels.db", sqlite3.OPEN_READONLY)

Opened for writing, the default of sqlite3.open, a packed database is copied once to the game’s data directory, under files/ like everything else a packed game writes, and the copy is opened. From then on the name means the copy, read only or not, and the packed original is never changed. A loose game’s database opens in place exactly as before. testScripts/packedSql is the test; its header says how to run it.

The file format, for anyone writing tools: three tables. meta(key, value) holds version (1), gamedir (the packed directory’s name), chunk (chunk size in bytes, 4194304), and packer. assets(path, name, size, data) has one row per file, path being the lower case forward-slash key and name the author’s spelling; files no larger than the chunk size are in data, larger ones have data NULL and live in chunks(path, chunk, data) as consecutive numbered pieces. Singe opens the database read only and immutable, so it runs from read-only media and never journals beside it.

1.9. Event Driven…​ Or Not?

Traditionally, Singe used an event-driven programming model — Singe handles everything and only calls your code when it needs to tell you something or update the screen. This is efficient and is how most Lua-based game engines work, but it can be verbose. As of Singe 2.10 there is a new threaded model that allows you to write procedural code.

1.9.1. Event Driven

With the event-driven programming model, Singe controls the main program loop and is in charge of the order of execution. Singe automatically handles all the details of decoding and presenting video and audio. It manages controllers, mice, and keyboard input. When Singe needs something game-specific, it calls part of your script. The most basic Singe script that demonstrates all the existing callbacks looks like this:

-- Singe Game Skeleton.

-- Load the Singe Framework.
dofile("Singe/Framework.singe")

-- Declare any global variables you need here.

function onControllerMoved(axis, value, which)
    --[[
        Reports which controller axis was moved as well as its current value.
        (Range: -32768 to 32767.) This is used for analog devices. Digital
        input is handled by onInput and onKey.
    --]]
end

function onInputPressed(what, device)
    --[[
        When in keyboard MODE_NORMAL, input events are reported here when the
        key or button is first depressed. For a full list of keys, buttons,
        and controllers, see Singe/Framework.singe. For MODE_FULL, this event
        will be called with the keysym of the key pressed. When the switch
        came from a mouse or a light gun, device is that device's index
        (0 for the first), as Hypseus passes it, so a two-gun game can tell
        its players apart; for a key or a pad it is nil.
    --]]
end

function onInputReleased(what, device)
    --[[
        When in keyboard MODE_NORMAL, input events are reported here when the
        key or button is released. For a full list of keys, buttons, and
        controllers, see Singe/Framework.singe. For MODE_FULL, this event
        will be called with the keysym of the key released. device is as
        for onInputPressed.
    --]]
end

function onKeyPressed(key, scancode)
    --[[
        When in keyboard MODE_FULL, input events are reported here when the
        key is pressed. Both the keysym and scancode are returned. For a list
        of available scancodes, see Singe/Framework.singe.
    --]]
end

function onKeyReleased(key, scancode)
    --[[
        When in keyboard MODE_FULL, input events are reported here when the
        key is released. Both the keysym and scancode are returned. For a
        list of available scancodes, see Singe/Framework.singe.
    --]]
end

function onMouseMoved(x, y, xr, yr, which)
    --[[
        Called when the mouse is moved. When in SINGLE_MOUSE mode, absolute
        X and Y values as well as the relative change in position are
        returned. For MANY_MOUSE mode, only the relative change is available
        as well as which mouse was moved.
    --]]
end

function onOverlayUpdate()
    --[[
        This is the only place you can safely perform drawing operations.
        If you wish to display a targeting cursor, you will need to save the
        mouse position from onMouseMoved in global variables and then use
        those here to render the cursor.
    --]]

    -- Tell Singe if we changed the display or not.
    return(OVERLAY_UPDATED)  -- Or OVERLAY_NOT_UPDATED if no drawing was done.
end

function onShutdown()
    -- Called when the user exits your game. Free loaded resources here.
end

function onSoundCompleted(channel)
    -- The sound on "channel" just finished playing.
end

-- Note:  There is no "onStartup" event.
--        Any startup code you need can be placed here.

1.9.2. Threaded

As of Singe 2.10, you can use the classic procedural programming model. To use this model, declare a singeMain() function and include the Singe framework at the end of your program rather than at the beginning. Lua is not truly multithreaded, so this model relies on the game developer to cooperatively multitask by calling singeYield() anywhere code consumes a substantial amount of time. As with the event-driven model, Singe still manages all input, video decoding, and audio decoding. A sample threaded program looks like this:

function singeMain()
    local x = 10
    local y = 10

    while true do
        colorBackground(0, 0, 0, 255)
        overlayClear()

        colorForeground(255, 255, 255, 255)
        overlayPrint(x, y, "+")

        if keyboardGetLastUp() == SCANCODE.LEFT.value  then x = x - 1 end
        if keyboardGetLastUp() == SCANCODE.RIGHT.value then x = x + 1 end
        if keyboardGetLastUp() == SCANCODE.UP.value    then y = y - 1 end
        if keyboardGetLastUp() == SCANCODE.DOWN.value  then y = y + 1 end

        singeYield()
    end
end

dofile("Singe/Framework.singe")

1.9.3. Hybrid

The two models combine freely. When singeMain exists, Framework.singe installs its own onOverlayUpdate, but every other callback still fires: define onInputPressed, onSoundCompleted, or onShutdown next to singeMain and they are called between the coroutine’s yields. A typical split keeps the game’s flow procedural while reacting to input and audio events:

local fired = false

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        fired = true
    end
end

function onSoundCompleted(channel)
    if channel == gunshotChannel then
        soundPlay(reloadSound)
    end
end

function singeMain()
    while true do
        if fired then
            fired = false
            gunshotChannel = soundPlay(gunshotSound)
        end
        singeYield()
    end
end

dofile("Singe/Framework.singe")

Do not define onOverlayUpdate yourself in this model; draw from inside singeMain instead. An error raised inside singeMain ends the game with a traceback, and returning from singeMain quits cleanly.

1.10. Pausing

Every game gets a working pause for free. While the pause key is enabled (the default), pressing the key mapped to INPUT_PAUSE makes the engine pause the disc, every loaded video, and every sound, draw a PAUSED indicator over the last frame, and stop running the script: no onOverlayUpdate, no singeMain resumption, no input, mouse, controller, or sound callbacks. Timers built on Lua libraries stop with it because nothing runs them. Pressing the key again resumes everything that was playing and the script continues where it left off. Only the engine’s own switches (pause, quit, screenshot, grab) still work while frozen.

Inputs are kept truthful across the freeze. Anything the script believes is held down is released with onInputReleased (or onKeyReleased in MODE_FULL) when the pause starts, and whatever is still physically held when the pause ends is pressed again. A joystick held through a pause never sticks.

A game that wants its own pause behavior (a pause menu, a story freeze that the player may not skip) calls singeSetPauseKeyEnabled(false). The key is then delivered to the script as SWITCH_PAUSE and the game drives singeSetPauseFlag itself, which pauses the media without freezing the script.

In MODE_FULL the keyboard belongs entirely to the game, so keys mapped to the engine’s switches do nothing there (a p typed into a high score entry must stay a p). Gamepad and mouse buttons mapped to those switches keep working in either mode, since they cannot be typed.

1.11. games.dat

The games.dat file allows Singe to automatically locate new games when they are installed by the end user. This file is extremely important and must be included with every Singe game. Place games.dat in the top-most directory of your game. An example containing multiple games:

GAMES = {
    {
        TITLE         = "Asteroid Patrol",
        SCRIPT        = "Collection/AsteroidPatrol.singe",
        VIDEO         = "Collection/frame_AsteroidPatrol.txt",
        STRETCH       = false,
        NO_MOUSE      = false,
        RESOLUTION_X  = 720,
        RESOLUTION_Y  = 480,
        SINDEN_GUN    = "",
        GAME_ID       = "6f1e7b62-0a4e-4d9c-9b2f-1c7a5e3d8a10",
        CABINET       = "Collection/cabinet_AsteroidPatrol.png",
        MARQUEE       = "Collection/marquee_Collection.png",
        ATTRACT       = "Collection/video_AsteroidPatrol.mkv",
        ATTRACT_START = 3000,
        ATTRACT_END   = 3500,
        YEAR          = 2026,
        PLATFORM      = "Laserdisc",
        DEVELOPER     = "Your Studio",
        PUBLISHER     = "Your Studio",
        GENRE         = "Shooter",
        DESCRIPTION   = "Keep the asteroids away from the station for as long as you can.",
        CREATOR       = "Scott Duensing",
        SOURCE        = "http://kangaroopunch.com"
    },
    -- ... additional entries ...
}

The keys SCRIPT, VIDEO, CANVAS_X, CANVAS_Y, STRETCH, NO_MOUSE, RESOLUTION_X, RESOLUTION_Y, SINDEN_GUN, AUDIO_TRACK, AUDIO_DELAY, AUDIO_SUFFIX, GAME_ID, LEGACY_SPRITE_ARGS, REQUIRES, and TIER are read by the engine when the menu (or your own script, through scriptExecute / scriptPush) launches the entry; they override the command line. The VIDEO line is the disc: an entry that names one is a laserdisc game, and an entry that leaves it out or blank runs without a disc and may set CANVAS_X / CANVAS_Y (default 720x480); see Games Without a Disc. AUDIO_SUFFIX = "-es" plays <base>-es.ogg beside the disc’s video instead of the audio inside it, for a release whose other languages ship as separate files, the same thing --altaudio does. LEGACY_SPRITE_ARGS = true runs a game written for Singe 2.10 with the old sprite argument order (see Migrating from Singe 2.10). The remaining keys are read by the menu for display.

REQUIRES says what the game needs of a machine, as a list of names: "SCENE" (the 3D scene), "GUI" (GUI documents), "SHADOWS", "POST" (bloom and the other effects that want float render targets), "SKIN" (skinned models), and "MORPH" (morph targets). No REQUIRES means 2D. The menu marks a game this machine cannot run and says why instead of starting it, and you rarely write the list yourself: the engine notices what a game uses as it runs, says in the trace when the game uses something REQUIRES does not list, and --pack writes the list into an entry that has none. TIER (0 to 3) is how much machine the game wants; the menu measures this machine’s tier from its own backdrop and marks a game that wants more as one that may run slowly. See singeCapabilities.

REQUIRES = { "SCENE", "SHADOWS" },
TIER     = 1,

A script launched directly, by name or by its directory, gets the same treatment: Singe looks for a games.dat in the script’s directory and up to three directories above it, and if an entry’s SCRIPT names the launched script (entry paths count from the directory above the games.dat, so Collection/games.dat names Collection/AsteroidPatrol.singe), that entry’s keys apply. The one difference from a menu launch is precedence: an option typed on the command line (--framefile, --disc, --stretch, --nomouse, --xresolution, --yresolution, --sindengun, --audio, --audiodelay, --altaudio, --canvas) keeps its value, since the person typing it meant it. A value from a settings file does not: it is a default, and the entry describes the game better (see The Settings File). A games.dat that fails to run is reported and ignored for a direct launch.

1.12. Games Without a Disc

Singe no longer assumes a laserdisc. A game is a laserdisc game only when it names one: a VIDEO in its games.dat entry, or --disc (or a --framefile) on the command line. Everything else runs without a disc, and the world is a canvas instead of a video frame: CANVAS_X / CANVAS_Y in games.dat or --canvas=WxH on the command line, 720x480 by default so a discless game looks like a standard definition laserdisc game unless it asks otherwise.

Without a disc the engine draws on black, the overlay defaults to half the canvas as usual, and the disc* and vldp* functions become harmless: discGetState reports DISC_EJECTED, discGetFrame returns 0, discGetWidth / discGetHeight return the canvas, vldpGetPixel returns black, and the transport calls trace and do nothing. Everything else — the overlay, sprites, fonts, sounds, extra videos through videoLoad, input, and both programming models — is identical. The global SINGE_DISC tells a script which kind of game it is running as.

1.13. GUI

Menus, option pages, HUDs and high score entry used to be built out of fontPrint, overlayBox and a hand rolled cursor. Singe 3 adds a GUI: a document written in RML (an HTML-like markup) and styled by RCSS (a CSS-like style sheet), laid out and drawn by RmlUi, with text wrapping, flexbox, nine-slice panels from your own artwork, transitions, animations, form controls and a focus model a gamepad can drive. A GUI is one RmlUi context of a fixed size rendered into its own texture, redrawn whenever its picture changes (see guiRefresh), and that texture goes wherever a texture can: composited over the overlay with guiDraw, or shown on a material in the 3D scene with materialSetGui, so the same options page works flat on the screen and on the monitor of a modeled arcade cabinet. A GUI needs the GPU device the 3D scene uses, so it is unavailable on a machine without one (see Performance and Requirements); guiNew ends the script rather than answering false, so ask singeHasGpu first if your game can do without. The bundled menu does exactly that, and draws itself into the overlay instead when the answer is no (see The two renderers). Every call named here has an entry in the Gui section of the reference.

The language reference for RML and RCSS is RmlUi’s own documentation at https://mikke89.github.io/RmlUiDoc/, and it is worth reading before the first document; this chapter covers what Singe adds on top.

1.13.1. Documents and Style Sheets

guiNew(width, height) makes a GUI and returns an integer handle; up to sixteen exist at once. guiLoad(gui, name) loads an RML document into it, shows it and returns a document handle (up to thirty-two per GUI); guiHide, guiShow and guiClose do what their names say, and guiDelete drops the GUI, its documents and its texture. A document is usually the size of its GUI, and a GUI is usually the size of the overlay for a full screen page or the size of the panel for a HUD element:

local gui = guiNew(overlayGetWidth(), overlayGetHeight())
local doc = guiLoad(gui, DIR .. "options.rml")

The document name goes through the virtual file system like a sprite’s, so it may live loose on disk or inside a packed game, and it is resolved relative to the directory Singe was started in, so prepend DIR for files shipped with your game, exactly as for spriteLoad. Names inside a document (a style sheet’s href, an image in a decorator, a sprite sheet’s src) resolve relative to the file that names them, as RmlUi does, and then through the same lookup, so a document, its style sheet and its images sit beside each other in the game directory and a packed game finds them all. Two kinds of name are taken as they are: the engine’s own files under Singe/, and absolute paths.

The same rule read the other way lets a document that lives under Singe/ reach a game’s files: a relative name resolves from the document’s own directory, so from Singe/Menu.rml the name ../Collection/cabinet.png is Collection/cabinet.png in the game directory, and a name under ../MyGame.game/ is a file inside that packed game. The bundled menu does exactly this for the cabinet and marquee art of the selected game, setting an image decorator on the art panel from Lua so the picture is fitted inside it whatever its size:

-- Menu.singe: fit a game's picture into one of the art panels.
function menuArt(id, file)
    local path = tostring(file or "")
    if path:sub(1, 6):lower() ~= "singe/" then
        path = "../" .. path
    end
    menuElement(id).style.decorator = 'image("' .. path .. '" contain)'
end

An RML document is a <head> with a title, style sheet links or an inline <style>, and a <body> of elements. A minimal one, using the shipped theme:

<rml>
<head>
	<title>Options</title>
	<link type="text/rcss" href="Singe/gui.rcss"/>
	<style>
		body { width: 100%; height: 100%; }
		.panel { margin: 30dp; }
	</style>
</head>
<body id="options">
	<div class="panel">
		<h1>Options</h1>
		<p class="muted" id="status">Choose a difficulty and press Start.</p>
		<button id="go">Start</button>
	</div>
</body>
</rml>

RmlUi draws nothing it has not been told the size of, and every element is display: inline until a style says otherwise, so a style sheet is not optional. Singe/gui.rcss is the theme the engine ships: it gives the body, headings and paragraphs a size and a color, makes div a block, and styles every form control. Link it first and override what you like in a sheet of your own or an inline <style>; the later rule wins as in CSS. Lengths in the theme are dp, RmlUi’s density independent pixel, which is a pixel at the GUI’s own size.

Text needs a font face. The engine loads Singe/FreeSansBold.ttf for every GUI as the fallback face (the face that serves any glyph no other face has); its family name is FreeSans and its weight is bold, which is what the theme’s body rule asks for. guiLoadFont(name) adds one of the game’s own faces for every GUI, and guiLoadFont(name, true) makes it the fallback instead. A document names a face by the family name inside the file, not the file name, so load fonts before the documents that use them:

guiLoadFont(DIR .. "fonts/Orbitron-Bold.ttf")
h1 { font-family: Orbitron; font-weight: bold; }

RmlUi’s RCSS effects are drawn in full. Children of a rounded or transformed element are clipped to its shape (a scrolling list with border-radius meets its frame at the curve), filter: opacity() fades a group as one (the opacity property fades each piece on its own, as RmlUi defines it), mask-image cuts an element out by an image’s alpha, box-shadow casts hard or soft shadows, and filter and backdrop-filter take blur, drop-shadow, brightness, contrast, invert, grayscale, sepia, hue-rotate and saturate. The linear-gradient, radial-gradient and conic-gradient decorators (repeating or not) draw as such; the shipped theme’s panels, buttons and progress bars use them. Three limits: the custom shader decorator is not supported (it is refused with a warning), a gradient carries at most sixteen color stops (more are dropped), and effects nest at most eight layers deep (a deeper element draws without its own layer). Every effect renders through a layer the size of the GUI, and a blur through several passes, so on a Pi keep them to a few elements and watch guiGetStats, which counts the layers, passes and bytes a frame cost.

1.13.2. Theming

A theme is a directory of RCSS and images, and a game ships its own look the way it ships sprites. The usual shape is one sheet linked after Singe/gui.rcss that restyles the theme’s classes and adds its own, with the artwork beside it. The shipped theme defines:

  • .panel — a bordered, rounded, translucent box with padding, the frame of a page or a dialog.

  • .list — a scrolling box whose child div elements are rows: they take focus, highlight on hover and focus, and a row with the selected class stays highlighted. A vertical scrollbar appears when the rows overflow.

  • .muted — dimmer text, for hints and status lines.

  • The form controls: button and input.submit, input.text, input.password and textarea, input.checkbox and input.radio, input.range with its track and slider, select with its arrow and drop-down box, and progress with its fill; each with hover, focus and active states, and each focusable with tab-index: auto so a gamepad can reach it.

A panel from your own artwork is a nine-slice decorator over a sprite sheet, and animations are RCSS keyframes, so a loading bar that fills by itself needs no script at all:

@spritesheet crate {
	src: crate.png;
	crate-outer: 0px 0px 40px 40px;
	crate-inner: 10px 10px 20px 20px;
}

.crate {
	display: block;
	decorator: ninepatch(crate-outer, crate-inner, 1.0);
	padding: 14dp;
}

@keyframes fill {
	from { width: 0%; }
	to   { width: 100%; }
}

.bar fill {
	animation: 3s cubic-in-out infinite alternate fill;
}

1.13.3. Scripting a Document

There are two APIs, and it helps to be clear which is which. The flat gui* calls in Singe’s own style create a GUI, load and draw documents, route input and reach elements by id: guiGetValue(gui, doc, id) reads a form control’s value, or any other element’s inner RML, as a string; guiSetValue(gui, doc, id, value) writes one; and guiSetHandler(gui, doc, id, event, function) calls a Lua function when the element fires an event ("click", "change", "submit", or any other RmlUi event name). The function receives (gui, document, id, event, value), with value the element’s value as a string at the moment of the event: a text field’s text, a select option’s value, a range in RmlUi’s own formatting ("48.000000"), a button’s inner RML. Everything a page needs day to day is covered by those three calls:

guiSetHandler(gui, doc, "go", "click", function(g, d, id, event, value)
    local name = guiGetValue(g, d, "name")
    local hard = guiGetValue(g, d, "difficulty") == "hard"
    startGame(name, hard)
end)
guiSetHandler(gui, doc, "volume", "change", function(g, d, id, event, value)
    soundSetVolume(math.floor(tonumber(value)))
    guiSetValue(g, d, "status", "Volume " .. math.floor(tonumber(value)))
end)

Everything else inside a document is RmlUi’s Lua API, which runs on the game’s own Lua state: a <script> block in a document, and onclick and the other on* attributes, run with the game’s globals, so they can call your functions and the gui* calls alike. From the script side the same objects are reachable through the rmlui global: contexts are named gui0, gui1, …​ after their handles, and documents are keyed by the id of their <body>, so the button above is rmlui.contexts["gui0"].documents["options"]:GetElementById("go"), and :DispatchEvent("click", {}) on it presses it from script (useful for tests that run without a mouse). Elements, their attributes, classes, styles and children, data-model bindings that mirror a Lua table into a document, and the rest of the object model are documented with RmlUi’s Lua plugin at https://mikke89.github.io/RmlUiDoc/; guiSetHandler is the by-id shortcut, not a replacement. A document closed through that API (document:Close()) is forgotten by the engine, and its handle raises an error afterwards.

1.13.4. Input

A new GUI only displays, which is right for a HUD or a sign; guiSetInput(gui, true) makes it take input, and guiSetInput(gui, false) turns that off again. For a GUI that takes input:

  • The mouse and a light gun (which is a mouse) arrive in overlay coordinates, mapped through the Sinden border and the overscan scale exactly as for onMouseMoved, in MOUSE_SINGLE mode. The engine finds the GUI under the pointer — the last one drawn flat there this frame is on top, and failing that a surface in the scene whose material shows one (see below) — and scales the position into that GUI’s own pixels. A press on an element is the GUI’s; the left, right and middle buttons click, and the wheel scrolls.

  • Keys go to every GUI taking input, and a key that a focused element used (a character in a text field, an arrow that moved focus, Return on a button) is consumed. While a text or password field or a textarea has focus the engine runs SDL’s text input, so typed text arrives as text, with the keyboard layout and any on screen keyboard or IME respected.

  • Pad and mouse switches (the framework’s SWITCH_* mappings from a gamepad or mouse button) are translated into the keys a document understands: the four directions become the arrow keys, INPUT_ACTION_1 is Return and INPUT_ACTION_2 is Escape. A switch mapped to a keyboard key already reached the GUI as that key.

The rule that makes a HUD safe is that an event an element used never reaches the game: a consumed key does not arrive as onInputPressed or onKeyPressed, a click on a button does not arrive as a mouse switch, a translated direction that moved focus does not arrive as SWITCH_UP. Everything a document did not use falls through to the usual callbacks, so a HUD that takes input still lets the fire button through, and a page with nothing focused lets every key through.

Focus and navigation are the document’s own affair. The shipped theme gives every control and every .list row tab-index: auto, so Tab moves between them, Return activates the focused control, and arrow keys move between controls with RmlUi’s nav properties (nav-up, nav-down, nav-left, nav-right, or nav: auto for all four). A page for a cabinet with a stick and two buttons wants those on everything it expects the player to reach:

button, .list div { nav: auto; }

1.13.5. A GUI in the Scene

materialSetGui(material, gui) shows a GUI’s texture as a material’s base color texture, updated every frame, beside materialSetVideo and materialSetView: a monitor, a cockpit panel, a sign. Pair it with materialSetUnlit when the picture should not be shaded, and leave it lit when it should. Nothing else changes; the material is lit, blended and reflected like any other, and the same GUI can be drawn flat over the overlay in the same frame.

sceneProbeGui(x, y) answers which GUI is on the surface under an overlay point and where on it: a ray from the camera through the point against every visible mesh whose material shows a GUI, returning the handle and the pixel in that GUI’s own coordinates, or nil when the point is off every such surface. The engine asks it the same question when the mouse or a light gun points at the scene and nothing drawn flat is under the pointer, so a click on the monitor in a 3D cabinet presses the button under it without any script involvement; the call is there for a game that wants to know for itself, for a laser sight, a hover effect, or a test.

local screen = materialNew()
materialSetGui(screen, gui)
materialSetUnlit(screen, true)
nodeSetMesh(monitor, meshPlane(3.0, 2.0), screen)
nodeSetRotation(monitor, 90, 0, 0)

1.13.6. Reloading, Performance, and Limits

A GUI belongs to the script that made it. Quitting, scriptPush, scriptExecute and a reload (see Reloading While You Work) tear every GUI and document down with the rest of the script’s state, and the script makes them again when it runs; nothing from the rmlui object model survives, so do not keep those objects in globals a reload would reuse.

Every GUI updates every frame whether or not it is drawn anywhere, so a document keeps running its animations and scripts off screen, and a GUI that is finished with should be deleted rather than merely hidden. It is redrawn into its texture only when its picture changes, so a page or a HUD that stands still costs the GPU almost nothing (see guiRefresh). The cost of a frame that does change is the size of the texture and the complexity of the document: on a desktop a full screen page is cheap, on a Raspberry Pi keep a GUI to the overlay’s size or smaller and prefer one GUI with several documents to several GUIs. Each font face costs an atlas per size it is used at, so a page that uses one face at three sizes pays for three atlases; a dozen sizes is a dozen. Sixteen GUIs may exist at once, each with thirty-two documents, and sixteen guiDraw calls are honored per frame.

What a document can show, and what it cannot:

  • Pictures come from files. Images, sprite sheets and image decorators load PNG and the other formats Singe reads, from disk or from a packed game. A document cannot show a Singe sprite, a video, the 3D scene or anything drawn while the game runs, and a script cannot hand it pixels. The other way round works: a GUI’s texture goes onto a 3D material with materialSetGui.

  • Decorators: image, text, tiled-horizontal, tiled-vertical, tiled-box, ninepatch, the two-color gradient (and its horizontal-gradient and vertical-gradient names), and linear-gradient, radial-gradient and conic-gradient with their repeating- forms, with at most sixteen color stops. The custom shader decorator is refused.

  • Filters: opacity, blur, drop-shadow, brightness, contrast, invert, grayscale, sepia, hue-rotate and saturate. Any other name is ignored with a warning in the trace.

  • Layers: filters, opacity below 1, mask images and box shadows each draw through a layer the size of the GUI, and at most eight stack at once; one past that draws without its layer, and so without its effect.

  • Images larger than 64 MB are refused.

  • RML and RCSS are RmlUi’s, close to HTML and CSS but not the same: there is flexbox and no CSS grid, and a document is scripted in Lua, through guiSetHandler and the rmlui object, rather than in JavaScript. RmlUi’s own documentation is the authority on what the languages hold.

1.13.7. A Worked Example

An options page over the disc: a panel from the shipped theme with a name field, a volume slider, a difficulty list and two buttons, drawn over the overlay and driven by the mouse or the stick. The document, options.rml, beside the script:

<rml>
<head>
	<title>Options</title>
	<link type="text/rcss" href="Singe/gui.rcss"/>
	<style>
		body { width: 100%; height: 100%; }
		.panel { margin: 30dp; }
		.field { display: block; margin: 6dp 0; }
		label { display: inline-block; width: 140dp; }
		input.text { width: 300dp; }
		button, input { nav: auto; }
		#status { min-height: 30dp; }
	</style>
</head>
<body id="options">
	<div class="panel">
		<h1>Options</h1>
		<div class="field"><label>Name</label><input type="text" id="name" value="Dirk"/></div>
		<div class="field"><label>Volume</label><input type="range" id="volume" min="0" max="63" step="1" value="48"/></div>
		<div class="field"><label>Difficulty</label>
			<select id="difficulty">
				<option value="easy">Easy</option>
				<option value="normal" selected>Normal</option>
				<option value="hard">Hard</option>
			</select>
		</div>
		<div class="field"><label>Attract</label><input type="checkbox" id="attract" checked/> plays the intro</div>
		<div class="field"><button id="go">Start</button><button id="back">Back</button></div>
		<p id="status" class="muted">Press Start when ready.</p>
	</div>
</body>
</rml>

The script loads it into a GUI the size of the overlay, wires the three elements it cares about, and draws it every frame until the player presses Start; the disc plays underneath the whole time:

dofile("Singe/Framework.singe")

local gui      = guiNew(overlayGetWidth(), overlayGetHeight())
local doc      = guiLoad(gui, DIR .. "options.rml")
local settings = { name = "Dirk", volume = 48, hard = false }
local inMenu   = true

local function report(text)
    guiSetValue(gui, doc, "status", text)
end

guiSetHandler(gui, doc, "volume", "change", function(g, d, id, event, value)
    settings.volume = math.floor(tonumber(value))
    soundSetVolume(settings.volume)
    report("Volume " .. settings.volume)
end)

guiSetHandler(gui, doc, "difficulty", "change", function(g, d, id, event, value)
    settings.hard = (value == "hard")
    report("Difficulty " .. value)
end)

guiSetHandler(gui, doc, "go", "click", function(g, d)
    settings.name = guiGetValue(g, d, "name")
    guiHide(g, d)
    guiSetInput(g, false)
    inMenu = false
    discPlay()
end)

guiSetHandler(gui, doc, "back", "click", function()
    singeQuit()
end)

function onInputPressed(what)
    -- Only what the page did not use arrives here: nothing while it has
    -- focus, everything once it is hidden.
    if not inMenu and what == SWITCH_BUTTON1 then
        fire()
    end
end

function onOverlayUpdate()
    overlayClear()
    if inMenu then
        guiDraw(gui)
    else
        fontPrint(10, 10, settings.name .. "  " .. (settings.hard and "HARD" or "NORMAL"))
    end
    return OVERLAY_UPDATED
end

The same page on the screen of a modeled cabinet is the five lines from A GUI in the Scene in place of guiDraw, and a click on the monitor presses the button under it.

1.14. Subtitles

A game can ship a SubRip subtitle file and have Singe show it over the disc as it plays. Three calls do the whole job: srtLoad reads the file, srtEnable switches it on, and srtPosition says where the lines sit. srtClear takes whatever is up off again. The feature came from Hypseus Singe and the four calls are its own.

if srtLoad("subs/english.srt") then
    srtPosition(80)
    srtEnable(true)
end

1.14.1. The File Format

SubRip (.srt) is a plain text file of numbered cues:

1
00:00:04,120 --> 00:00:06,880
Stay away from the caves.

2
00:00:07,000 --> 00:00:09,500
I mean it -- the caves
are where they nest.

Each cue is a number on a line of its own, then a line holding two timestamps separated by -→, then one or more lines of text, then a blank line. A timestamp is HH:MM:SS,mmm: hours, minutes and seconds separated by colons, and milliseconds after a comma. The cue number is read and thrown away, so the numbers need not be in order or even correct.

The parser is deliberately forgiving in the places a hand-edited file goes wrong. Carriage returns, leading spaces and trailing spaces are stripped from every line, so a file written on Windows loads unchanged. A cue whose time line has no -→, or whose timestamps do not parse, is skipped and the file goes on loading. A cue with no text is skipped. A cue’s lines are joined with line breaks and shown as written, and <, > and & reach the screen as themselves rather than being taken for markup.

What is not supported: the positioning coordinates some tools append to the time line are ignored (srtPosition decides the height), and SubRip’s occasional <i> and <b> tags are shown as text rather than obeyed. Cues may overlap in time; the last one that has started wins.

srtLoad answers false and loads nothing when the file cannot be read, when nothing in it parses, or when there is no disc — so a broken file is a false a game can act on and not a crash. It prints a warning naming the file in each case.

1.14.2. The Timing

Timestamps are turned into disc frame numbers as the file is loaded, using the frame rate of the disc that is loaded at the time, and the engine matches every drawn frame against those frame numbers. Two things follow from that.

First, a subtitle survives a seek. Sending the disc anywhere — discSearch, discSkipForward, a step, a frame file crossing into another segment — puts up the cue covering wherever it landed, on the next drawn frame, forwards or backwards. Nothing has to be reloaded and no clock has to be reset.

Second, the file must be timed against the disc, not against the wall clock. A .srt cut for a video at a different frame rate lands in the wrong place, and one loaded before the disc has been opened does not load at all. Load subtitles after the disc, which for an ordinary game means from the script’s body.

A cue is shown while the disc’s frame is between its two frames inclusive. The subtitle is drawn again only when the cue changes, so subtitles cost nothing while a line is up.

1.14.3. Styling

The lines are an RmlUi document, not a blitted text line, so they are styled the way a GUI is. Two files ship in the Singe folder and are extracted beside the others at first run:

  • Singe/subtitle.rml — the document. It has one element, #slot, that the engine writes the current cue or banner into.

  • Singe/subtitle.rcss — the look. .cue is the block that carries the height srtPosition asked for, as an inline top; .cue .text is the bar of text inside it, which by default is white on a dark rounded panel that hugs the text rather than spanning the picture.

Both are written afresh at every start, like everything in the Singe folder, so editing them changes nothing for long. To restyle, a game ships its own copies: subtitle.rml beside its script, its link pointing at a sheet of its own (subtitle.rcss beside it, say), and Singe draws that document instead of its own; the program trace says so. The engine only ever sets the contents of #slot and the top of .cue, so anything else — the face, the size, the colors, the panel, a border, a shadow — belongs in the game’s sheet and survives an engine upgrade. The document is drawn over the picture, above the overlay, below the screen space GUIs, follows the video rectangle wherever --scalefactor, --shiftx, a bezel cutout or --rotate put it, and takes no mouse input, so a click passes straight through it.

overlayBanner uses the same document, so a banner and a subtitle look alike and a game that restyles one restyles both.

On a machine with no GPU there are no GUIs at all; srtLoad still parses the file and answers truthfully, and nothing is drawn. A warning says so once.

1.15. 3D Scenes

Singe 3 draws a 3D scene between the laserdisc video and the 2D overlay. Everything you already know still applies: sprites, text and the overlay sit on top of the scene, and the video shows through wherever the scene’s background is transparent. A game that never calls a 3D function is unaffected, and a game without a disc (see Games Without a Disc) can be a 3D game outright.

The sections below build up a scene in the order you will write one: nodes, then meshes and materials, lights, the camera, the look of the frame as a whole, models, and finally the things that sit on top of all that. Every call named here has an entry in the Lua API Reference.

1.15.1. What a Scene Is Made Of

Everything in a scene is a node in one tree, and node 0 is the root. A node has a position, a rotation and a scale relative to its parent, and it may carry one thing: a mesh with a material, a light, a sprite, or a line of text. A loaded model becomes a subtree of nodes under one root, so the same calls move a modeled character and a scripted cube alike.

The scene is right-handed with +Y up and -Z forward, like glTF and Blender’s export. Units are whatever your models use, and the primitives take the same units; physics (see Physics) assumes meters. Rotations are degrees, given as three Euler angles applied as yaw, pitch and roll, or as a quaternion when the value came from a model. A node’s own forward is its -Z: the camera looks down it, directional and spot lights shine down it, and nodeLookAt turns it toward a world point.

There are two ways to fill a scene, freely mixed:

  • Build it from script with the primitive meshes (meshBox, meshSphere, meshPlane, meshCylinder, meshCone, meshTorus, meshHeightmap) or your own vertex data (meshNew), plus materials, lights and a camera.

  • Load models in glTF 2.0 binary form (.glb) with modelLoad, then place them with modelInstance as many times as you like. Blender, Maya, 3ds Max and every major engine export .glb.

A minimal scene is a mesh, a light and a camera:

sceneEnable(true)
sceneSetBackground(0, 0, 0, 0)     -- Transparent: the disc shows behind the scene.

local red = materialNew()
materialSetColor(red, 220, 40, 40)

local cube = nodeNew()
nodeSetMesh(cube, meshBox(1, 1, 1), red)

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 2, 4, 3)
nodeLookAt(sun, 0, 0, 0)

local camera = nodeNew()
nodeSetPosition(camera, 0, 1.5, 5)
nodeLookAt(camera, 0, 0, 0)
cameraSet(camera)

function onOverlayUpdate()
    nodeRotate(cube, 0, 1, 0)      -- One degree a frame about its own Y.
    return OVERLAY_UPDATED
end

sceneEnable(true) is the one call every 3D game makes, and on a machine that cannot draw 3D it is the call that fails (see Performance and Requirements). Without a camera the scene is viewed from (0, 0, 5) looking at the origin, and without a background call the scene’s background is opaque black.

1.15.2. Nodes

A node’s transform is set outright (nodeSetPosition, nodeSetRotation, nodeSetQuaternion, nodeSetScale) or nudged (nodeMove, nodeRotate), always in its parent’s space. nodeSetParent re-hangs a node, keeping its local transform; nodeGetWorldPosition reads where it ended up after every parent has had its say. nodeSetVisible hides a node and everything under it, and nodeDelete frees it and its children, along with any body, emitter or sound attached to them.

Names come from models: nodeFind(name, root) finds a joint or a part by the name it had in the file, under the instance given as root. A scripted node can be named too (nodeSetName), which is what nodeFind without a root searches.

-- A turret on a tank: the barrel is a child of the turret, the turret of the hull,
-- so turning the turret carries the barrel and moving the hull carries both.
local hull   = nodeNew()
local turret = nodeNew()
local barrel = nodeNew()
nodeSetMesh(hull, meshBox(2, 0.8, 3.2), olive)
nodeSetMesh(turret, meshCylinder(0.7, 0.5, 16), olive)
nodeSetMesh(barrel, meshCylinder(0.1, 1.8, 8), steel)
nodeSetParent(turret, hull)
nodeSetParent(barrel, turret)
nodeSetPosition(turret, 0, 0.65, 0)
nodeSetPosition(barrel, 0, 0, -1.2)
nodeSetRotation(barrel, 90, 0, 0)          -- Lay the cylinder along -Z.

function onOverlayUpdate()
    local stick = controllerGetAxis(0, GAMEPAD_AXIS_RIGHT_X) / 32767   -- -1 to 1.
    nodeRotate(turret, 0, stick * 2, 0)
    return OVERLAY_NOT_UPDATED
end

Two calls bridge the scene and the overlay. sceneProject(x, y, z) turns a world point into overlay coordinates, so a name tag or a health bar drawn with fontPrint can follow a 3D object. sceneUnproject(sx, sy, distance) goes the other way: the world point that far along the ray through an overlay pixel, which with physicsRaycast is mouse picking.

function onMouseMoved(x, y, dx, dy, which)
    -- The mouse points along a ray from the camera; what it hits is the target.
    local cx, cy, cz = nodeGetWorldPosition(camera)
    local fx, fy, fz = sceneUnproject(x, y, 50)
    local hit = physicsRaycast(cx, cy, cz, fx - cx, fy - cy, fz - cz, 50)
    highlighted = hit
end

1.15.3. Meshes and Materials

A mesh is geometry; a material is how it looks; a node joins one of each (nodeSetMesh(node, mesh, material)). Share both freely: one meshBox and one material can sit on a thousand nodes, and that sharing is what makes the renderer fast (see Performance and Requirements). meshNew builds a mesh from tables of positions, normals, texture coordinates and indices when the primitives will not do.

A material starts as a base color with alpha (materialSetColor) and the glTF metallic-roughness look: materialSetMetallic and materialSetRoughness from 0 to 1. Roughness near 0 gives a mirror-sharp highlight and 1 a matte surface; a metal tints its highlights and reflections with its own color and has no diffuse color of its own. Beyond that:

  • materialSetEmissive makes a surface give off light of its own color (a screen, a lamp, hot metal); it does not light other things, but it does bloom (see The Look of the Frame).

  • materialSetUnlit shows the color as it is, ignoring every light: HUD elements in the scene, the built-in glow of a bulb’s glass.

  • materialSetDoubleSided draws the back of open shapes, such as a plane seen from below or a flag.

  • materialSetBlend makes the alpha count, for glass, ghosts and water. Blended meshes draw after everything opaque, sorted by distance, and do not cast shadows.

  • materialSetCutoff keeps only the texels whose alpha reaches the cutoff and throws the rest away, which is how leaves, fences, grates and chain link are drawn: one quad, most of it gone. Unlike blending it needs no sorting and it still casts a shadow, and the shadow is cut out too, so a tree throws leaf shadows rather than the shadow of its quad. What survives the cutoff is opaque: a half-transparent texel is either kept whole or dropped, never blended, so nothing behind the scene (the disc picture, most visibly) tints a leaf. A cutoff of 0 (the default) turns masking off. A model loaded from glTF brings its own: MASK sets the cutoff from the file, BLEND turns blending on, and OPAQUE does neither.

The texture of a material can be any loaded sprite’s image (materialSetTexture), the laserdisc itself or a loaded video (materialSetVideo), a second camera’s picture (materialSetView, see The Camera and Views), or a GUI document (materialSetGui, see GUI). A modeled arcade cabinet can play the disc on its own screen, or show its options page there. Texture coordinates come from the mesh; the primitives map an image once across each face, and materialSetTiling repeats it, which is what ground and walls want. Textures are mipmapped and filtered anisotropically, so a floor stays crisp into the distance; materialSetFilter(material, FILTER_NEAREST) keeps pixel art blocky instead.

local stone = materialNew()
materialSetTexture(stone, spriteLoad(DIR .. "flagstones.png"))
materialSetTiling(stone, 12, 12)             -- Twelve repeats across the plane.
materialSetRoughness(stone, 0.9)

local floor = nodeNew()
nodeSetMesh(floor, meshPlane(24, 24), stone)

local glass = materialNew()
materialSetColor(glass, 180, 220, 255, 90)   -- Alpha 90 of 255.
materialSetBlend(glass, true)
materialSetRoughness(glass, 0.05)

Four more maps give a surface detail its geometry lacks, and a loaded model brings them along when its file has them:

  • materialSetNormalMap bends the lighting with a tangent-space normal map, so bricks stand out of a flat wall. A strength above 1 exaggerates it.

  • materialSetOcclusionMap darkens crevices that ambient light and the sky cannot reach.

  • materialSetMetallicRoughnessMap varies metallic and roughness across the surface, packed the glTF way (roughness in green, metallic in blue) and multiplied by the material’s own factors, so set those to 1 when the map should rule.

  • materialSetEmissiveMap says which parts glow, tinted and scaled by materialSetEmissive.

local brick = materialNew()
materialSetTexture(brick, spriteLoad(DIR .. "brick.png"))
materialSetNormalMap(brick, spriteLoad(DIR .. "brickNormal.png"), 1.5)
materialSetMetallicRoughnessMap(brick, spriteLoad(DIR .. "brickMetalRough.png"))
materialSetMetallic(brick, 1)
materialSetRoughness(brick, 1)
materialSetEmissiveMap(brick, spriteLoad(DIR .. "brickEmissive.png"))
materialSetEmissive(brick, 180, 100, 40)     -- The mortar glows orange.
Compressed textures

A PNG is decoded to four bytes a texel on the GPU, plus a third again for its mipmaps; a level the size of Sponza holds 390 MB of textures that way, more than a Raspberry Pi 4 shares with its display. Textures shipped as KTX2 files (Basis Universal, made by util/compressTextures.py from PNGs or from a whole .gltf) stay compressed on the GPU at a quarter of the size or less, in whichever block format the machine has: BC7 on desktops, ASTC on Apple GPUs and the Pi 4, ETC2 on any OpenGL ES 3 part (every handheld’s Mali, the Pi under GLES), BC3 on older cards, and plain RGBA where nothing else exists, all from the one file. Give a .ktx2 name in place of a sprite to materialSetTexture and the map calls, and a model whose file uses KHR_texture_basisu loads them on its own. sceneGetStats reports the texture memory in use, so you can see the difference.

materialSetTexture(ground, DIR .. "flagstones.ktx2")
local draws, drawn, calls, textureKB = sceneGetStats()
debugPrint("textures: " .. textureKB .. " KB")

1.15.4. Lights and Shadows

Up to eight lights shine at once, and each is a node, so lights parent and animate like anything else:

  • LIGHT_DIRECTIONAL is a sun: only its direction matters, and everything is lit the same. An intensity of 1 lights a white surface facing it to white.

  • LIGHT_POINT is a bulb, fading with distance, and lightSetRange stops it altogether beyond a distance. Its intensity is its brightness at the bulb itself, half of it one unit away, so a bulb that has to light a room needs a number in the tens.

  • LIGHT_SPOT is a cone with an inner angle that is fully lit and an outer angle where the light has faded to nothing (lightSetCone).

sceneSetAmbient adds a little light from everywhere so shadows are not black; a sky does that better (see The Look of the Frame). Colors given as 0 to 255 are sRGB, like everything else in Singe, and are converted to linear light on the way in, so a light of 128, 128, 128 is a quarter as bright as white, not half.

Any light can cast soft-edged shadows from everything opaque (lightSetShadow). Directional and spot lights cast through a shadow map; point lights through a cube map that reaches every direction, so a bulb may sit inside what it lights (a room, a lamp shade, the cabinet): closed meshes cast from their back faces too, and the shadow’s depth range is fitted to the casters around the light. nodeSetShadow(node, false) excuses a mesh from casting: the bulb’s own glass, a glowing sign, a name tag. sceneSetShadowSize sets the map’s resolution (256 to 4096, default 1024) and trades sharpness for speed.

A directional light’s shadow is split into cascades along the view (sceneSetShadowCascades, three by default), each a map fitted to a slice of what the camera sees, so shadows stay sharp close up in a large level and still reach as far as sceneSetShadowDistance. One cascade fits a single map to the whole scene, which suits small scenes and orthographic cameras. A view (viewNew) draws with the same maps, taking for each point the finest cascade that covers it, so a monitor shows the shadows the window does.

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 30, 40, 20)
nodeLookAt(sun, 0, 0, 0)
lightSetIntensity(sun, 2.5)
lightSetColor(sun, 255, 240, 220)
lightSetShadow(sun, true)
sceneSetShadowSize(2048)
sceneSetShadowDistance(80)              -- Three cascades out to 80 units.

local lamp = lightNew(LIGHT_POINT)
nodeSetPosition(lamp, 3, 3.1, -2)
lightSetColor(lamp, 255, 230, 190)
lightSetIntensity(lamp, 12)
lightSetRange(lamp, 14)
lightSetShadow(lamp, true)              -- A cube map: six passes a frame.
nodeSetShadow(bulbGlass, false)         -- The glass around it casts nothing.

1.15.5. The Camera and Views

Any node can be the camera (cameraSet); it looks down its own -Z, so nodeLookAt aims it, and hanging it under a moving node makes a chase camera. cameraSetPerspective(fovDegrees, near, far) is the default lens; cameraSetOrthographic(height, near, far) draws without perspective, for diagrams, HUD-like scenes and side-on games. Keep near as large as the scene allows, because the depth buffer’s precision is spent between near and far.

local camera = nodeNew()
nodeSetParent(camera, car)
nodeSetPosition(camera, 0, 2.5, 7)      -- Behind and above the car, in its space.
nodeLookAt(camera, 0, 1, 0)
cameraSet(camera)
cameraSetPerspective(55, 0.1, 300)

A view is a second camera rendered to a texture every frame and shown on a material: a security monitor, a rear-view mirror, a portal, a picture in picture. viewNew(width, height) makes one at that resolution, viewSetCamera gives it a camera node, and materialSetView puts its picture on any mesh. Views share the frame’s shadows and skip bloom, and each one renders the scene again, so keep them few and small. Each view turns billboards (see Sprites and Text in the Scene) to its own camera and draws transparent materials back to front from it, so a monitor sees name tags face on and glass in the right order.

local rearCamera = nodeNew()
nodeSetParent(rearCamera, car)
nodeSetPosition(rearCamera, 0, 1.2, -2)
nodeSetRotation(rearCamera, 0, 180, 0)      -- Looking back.
local rear = viewNew(384, 256)
viewSetCamera(rear, rearCamera)

local mirror = materialNew()
materialSetView(mirror, rear)
materialSetUnlit(mirror, true)
local panel = nodeNew()
nodeSetParent(panel, car)
nodeSetMesh(panel, meshPlane(0.6, 0.2), mirror)
nodeSetPosition(panel, 0, 1.6, 0.5)
nodeSetRotation(panel, 90, 0, 0)            -- The plane faces up; stand it facing the driver.

1.15.6. The Look of the Frame

The scene is lit in linear light. Colors you give as 0 to 255 are sRGB and are decoded on the way in, textures are decoded by the GPU as they are sampled, lights add up without clipping, and at the end of the frame a tone curve brings the result back to the screen. What that means in practice:

  • sceneSetExposure(stops) brightens or darkens the whole frame like a camera’s exposure: +1 doubles the light, -1 halves it, so a cave and a beach can share the same lights and materials.

  • sceneSetTonemap picks the curve: TONEMAP_NEUTRAL (the default, which keeps colors where glTF viewers keep them and compresses only the brightest light), TONEMAP_ACES (a filmic look with more contrast), or TONEMAP_NONE (clip at white).

  • sceneSetBloom(threshold, strength) makes everything brighter than the threshold glow: the sun through a window, a bulb, an emissive sign, a flame. The glow is taken from the scene’s light before the tone curve, so only what is truly bright blooms; a threshold of 1 is white.

The sky and its light

sceneSetSky(file) wraps the scene in an equirectangular panorama. A Radiance .hdr keeps its full range; a PNG or JPEG works too. The sky is drawn behind everything, and unless sceneSetEnvironment(false) it also lights the scene: its overall color from every direction replaces the flat ambient, and its reflection shows on metals and glossy surfaces, sharp on a mirror and blurred as roughness rises. Without a sky, metals have nothing to reflect and only the ambient and the lights shape them. sceneSetSkyIntensity scales the sky and its light together, so one panorama serves noon and dusk.

Fog

sceneSetFog(r, g, b, near, far) fades everything, particles included, toward a color between two distances. The sky is never fogged, so match the fog’s color to the sky’s horizon and the far edge of the scene disappears into it.

sceneSetSky(DIR .. "harbor.hdr")
sceneSetSkyIntensity(0.8)
sceneSetFog(190, 200, 215, 40, 160)        -- The color of the sky at the horizon.
sceneSetExposure(-0.5)                     -- A little darker than the sun would make it.
sceneSetBloom(1.0, 0.35)                   -- Only what is brighter than white glows.

1.15.7. Models and Animation

modelLoad takes a .glb by the same game-relative name spriteLoad takes, and a packed .game carries it along. The file must be self-contained: meshes, skins, animations and textures all inside the one file, which is Blender’s default export. A model that refers to a .bin or an image beside it is refused with a message naming the file, for the same reason a packed game has to be self-contained. Materials use the metallic-roughness model with KHR_materials_emissive_strength and KHR_texture_basisu; a texture addressed through a second set of texture coordinates reads the first set, and KHR_texture_transform is ignored, each with a line in the program trace. A skin may have up to 128 joints. Loading is the expensive part; modelInstance then places a copy of the model’s node tree, as many times as you like, and every instance shares the file’s meshes and materials. modelDelete frees the model; instances keep their nodes, bare.

local foxModel = modelLoad(DIR .. "Fox.glb")
local pack = {}
for i = 1, 6 do
    local fox = modelInstance(foxModel)
    nodeSetScale(fox, 0.02)                -- The file is in centimeters.
    nodeSetPosition(fox, i * 1.5 - 5, 0, 0)
    pack[i] = fox
end

A model’s animations are listed by modelGetAnimations and driven per instance with animationPlay(node, nameOrIndex, loop, speed, fade) on the instance’s root node, plus pause, resume, stop and seek calls. Node animation (things moving), skinning (characters deforming) and morph targets (blend shapes: faces, lip sync, muscle bulges) all work. Animations advance with real time and hold while the game is paused. A morph weight can also be set from script with nodeSetMorph, by name or number, on the node that carries the mesh.

A fade in seconds crossfades from whatever was playing, so a walk becomes a run without a snap. When nothing was playing (after animationStop, or when a ragdoll has been switched off), the fade starts from the pose the nodes are in, so a character eases up from where it fell. Up to four more clips can play at once on layers above the base (animationPlayLayer), each blended in by animationSetLayerWeight and limited to part of the skeleton by animationSetLayerMask: a look-around on the neck while the legs walk, a wave on one arm over a run.

animationPlay(fox, "Walk", true)
animationPlayLayer(fox, 1, "Survey", true, 1, 0.5)           -- Head turns, blended in over half a second
animationSetLayerMask(fox, 1, nodeFind("b_Neck_04", fox))    -- ... on the neck and above only.

function onCollision(a, b, x, y, z, speed)
    if (a == fox or b == fox) and speed > 3 then
        animationPlay(fox, "Run", true, 1.2, 0.4)   -- Faster, crossfaded in 0.4 s.
    end
end

1.15.8. Sound in the Scene

A sound effect can be placed in the scene so it is heard from where it is. soundSetPosition(channel, x, y, z) puts a playing channel at a world point, soundSetNode(channel, node) makes it follow a node instead, and soundSetRange(channel, near, far) says where it is at full volume and where it has faded to silence. Sounds are heard from the camera unless soundSetListener names another node (the player’s head, for a third-person game), and they pan left and right as the listener turns. A channel not placed in the scene plays as it always has, with soundSetPan for stereo.

local crackle = soundPlay(fireSound, -1)          -- Loops forever.
soundSetNode(crackle, brazier)
soundSetRange(crackle, 2, 18)                     -- Full within 2 units, gone at 18.
soundSetListener(hero)

1.15.9. Sprites and Text in the Scene

Any node can show a picture instead of a mesh. nodeSetSprite(node, sprite, height) puts a loaded sprite (every frame of an animated one, with nodeSetSpriteFrame choosing) on a quad that many world units tall, lit like anything else and casting shadows unless nodeSetShadow says otherwise. nodeSetText(node, text, height) does the same with a line of text in the selected font and color, unlit. Both are meshes as far as the rest of the engine is concerned: they parent, scale, and take a material’s blend.

nodeSetBillboard turns a node to face the camera every frame: BILLBOARD_ALL squarely (name tags, glows, impostors), BILLBOARD_Y about its own up axis only (trees, health bars, anything that must stay upright), and BILLBOARD_NONE to stop. It works on meshes too.

local tag = nodeNew()
nodeSetParent(tag, fox)
nodeSetPosition(tag, 0, 110, 0)         -- In the Fox's centimeters, above its head.
nodeSetScale(tag, 50)                   -- Undo the instance's 0.02 scale.
nodeSetText(tag, "FOX", 0.6)
nodeSetBillboard(tag, BILLBOARD_ALL)
nodeSetShadow(tag, false)

local icon = nodeNew()
nodeSetParent(icon, fox)
nodeSetPosition(icon, 0, 150, 0)
nodeSetScale(icon, 50)
nodeSetSprite(icon, spriteLoad(DIR .. "crate.png"), 0.5)
nodeSetBillboard(icon, BILLBOARD_Y)

1.15.10. In Front of the Overlay

The scene normally draws beneath the overlay, so anything drawn on the overlay covers it. nodeSetLayer(node, LAYER_FRONT) moves a node, and everything parented to it, into the front layer instead: the same camera draws it after the overlay, lit by the same lights and finished by the same exposure, tone curve, and bloom, so a spinning logo, a 3D title, or a model on a high score table can stand over 2D artwork. The front layer is its own picture, cleared to transparent, so the overlay shows wherever it draws nothing, and nothing in the scene behind the overlay can hide it. GUIs and the particles drawn over the overlay still go on top of it.

Front nodes still cast shadows on the scene. The sky, 3D particles, and debug lines stay in the scene, and views (viewNew) draw only the scene’s nodes. The layer costs a second render pass, and only on frames with something in it.

-- A gold coin turning over the 2D title screen.
local coin = nodeNew()
nodeSetMesh(coin, meshCylinder(1, 0.2, 48), gold)
nodeSetRotation(coin, 90, 0, 0)
nodeSetLayer(coin, LAYER_FRONT)

function onOverlayUpdate()
    overlayClear()
    spriteDraw(titleArt, 0, 0)
    nodeRotate(coin, 0, 2, 0)
    return OVERLAY_UPDATED
end

1.15.11. Terrain

meshHeightmap(image, sizeX, sizeY, sizeZ) turns a grayscale image into rolling ground: one vertex per pixel, black low and white sizeY high, with normals from the slopes and texture coordinates across the whole. Give its material a texture and materialSetTiling to repeat it every few units. Images may be up to 1025 pixels each way; a 257 pixel map over 120 units gives a vertex every half unit, which is plenty for hills.

A BODY_STATIC body with SHAPE_MESH on that node becomes a height field, far cheaper than the triangles would be, so cars drive it and players walk it as they are. terrainGetHeight(node, x, z) says how high the ground is at a point, for placing things on it without a ray cast.

local ground = materialNew()
materialSetTexture(ground, DIR .. "grass.ktx2")
materialSetTiling(ground, 24, 24)
local hills = nodeNew()
nodeSetMesh(hills, meshHeightmap(DIR .. "hills.png", 120, 14, 120), ground)
bodyNew(hills, BODY_STATIC, SHAPE_MESH)             -- A height field.

for i = 1, 20 do
    local x, z = math.random(-50, 50), math.random(-50, 50)
    local tree = modelInstance(treeModel)
    nodeSetPosition(tree, x, terrainGetHeight(hills, x, z), z)
end

1.15.12. Navigation

A navigation mesh tells characters where they can walk. navNew(radius, height, maxSlope, maxStep) starts one for a given agent size, navAddNode feeds it the level’s geometry (a model instance’s root does the whole model), and navBuild bakes the walkable surface: floors, ramps and stairs the agent can climb, minus a margin around every wall and column. Baking Sponza takes a tenth of a second on a desktop; navSave and navLoad keep a baked mesh in the game’s data folder for machines where it takes longer, and a mesh shipped with the game loads the same way. navDraw shows the mesh over the scene while you are getting the parameters right.

Queries then answer the questions a game asks: navPath returns the corners of the shortest route between two points, navNearest snaps a point onto the mesh, navRaycast says whether a straight walk is blocked, and navRandomPoint picks somewhere to wander to.

Agents (navAgentNew) walk the mesh for you. navAgentMoveTo sends one somewhere and it steers around the other agents on the way, moving its node (or driving a player controller on it, with navAgentSetPlayer) and calling onNavArrived when it gets there. navAgentGetVelocity tells you whether to play the walk or the run.

local nav = navNew(0.4, 1.6, 45, 0.3)   -- An agent 0.8 wide, 1.6 tall, climbing 0.3.
navAddNode(nav, level)
navBuild(nav)

local guards = {}
for i = 1, 6 do
    local guard = modelInstance(guardModel)
    local x, y, z = navRandomPoint(nav)
    nodeSetPosition(guard, x, y, z)
    animationPlay(guard, "Walk", true)
    local agent = navAgentNew(nav, guard, 0.35, 1.6, 1.4)
    navAgentMoveTo(agent, navRandomPoint(nav))
    guards[agent] = guard
end

function onNavArrived(agent)
    navAgentMoveTo(agent, navRandomPoint(nav))   -- Off to the next spot.
end

1.15.13. Performance and Requirements

The scene needs a GPU that speaks Vulkan (Linux), Direct3D 12 (Windows 10 and later), Metal (macOS) or OpenGL ES 3.1. The ES backend is what brings in the cheap Linux handhelds and the Raspberry Pi, whose Mali and VideoCore parts have a mature GLES driver and either no Vulkan at all or an immature one; it is chosen automatically when none of the other three is available, and it draws the same picture from the same shaders. The Raspberry Pi 4 remains the minimum Pi for 3D: the Pi 3 has only OpenGL ES 2.0, which cannot express the scene’s skinning or morph targets. On a machine without any of them, 2D games run exactly as before (2D physics included) and the first 3D call ends the game with an error naming the problem.

Meshes outside the camera’s view are skipped, and copies of the same mesh with the same material draw as one instanced call, so a forest of one tree costs about what one tree costs. sceneGetStats reports the draws collected, how many were in view, how many draw calls that took, and the texture memory in use. To help it along:

  • Share meshes and materials between nodes (one meshBox, many nodes; one model, many modelInstance calls) rather than making one per object.

  • Skinned and morphing meshes and blended ones draw one at a time; keep them to what the scene needs.

  • Antialiasing (4x multisampling) is on wherever the GPU offers it; sceneSetAntialias(false) buys back speed on a Pi, as does a smaller sceneSetShadowSize and fewer shadow-casting point lights, each of which costs six passes.

  • Keep an eye on triangle counts and texture sizes on small boards, ship KTX2 textures, and load a model once rather than twice.

function onOverlayUpdate()
    local draws, drawn, calls, textureKB = sceneGetStats()
    overlayClear()
    local text = string.format("%d/%d meshes, %d calls, %d KB", drawn, draws, calls, textureKB)
    fontPrint(10, 10, text)
    return OVERLAY_UPDATED
end

1.16. Physics

Bodies, joints, triggers and ray casts live in the 3D scene and ride on Jolt Physics. A body attaches to a node the way a mesh does, and from then on the node and the body are one thing: the body’s shape is sized in world units and scaled by the node, and whichever of the two moves, the other follows. Units are meters, kilograms and seconds, and gravity defaults to 0, -9.81, 0. Physics does not need a GPU; see 2D Games.

1.16.1. Bodies

bodyNew(node, type, shape, a, b, c) gives a node a body of one of three types:

  • A static body (BODY_STATIC) stays where the node was when the body was made: floors, walls, the cabinet. Moving its node afterwards does not move the body.

  • A kinematic body (BODY_KINEMATIC) follows its node wherever the script or an animation moves it, and pushes dynamic bodies out of its way without being pushed itself: a paddle, a moving platform, a character’s hand.

  • A dynamic body (BODY_DYNAMIC) is moved by the simulation and drives its node: it falls, bounces, slides and gets pushed. Do not move its node yourself; give it velocities, forces or impulses instead (bodySetVelocity, bodyApplyForce, bodyApplyImpulse).

The shape is a box, sphere, capsule or cylinder sized by a, b and c (SHAPE_BOX takes width, height and depth; SHAPE_SPHERE a radius; SHAPE_CAPSULE and SHAPE_CYLINDER a radius and a height along Y), a convex hull of the node’s mesh (SHAPE_HULL, everything under the node, so a model instance’s root works), or the mesh’s exact triangles (SHAPE_MESH, static and kinematic bodies only; on a heightmap mesh it is a height field, see Terrain).

floor = nodeNew()
nodeSetMesh(floor, meshBox(14, 0.2, 14), stone)
nodeSetPosition(floor, 0, -1.9, 0)
bodyNew(floor, BODY_STATIC, SHAPE_BOX, 14, 0.2, 14)

for i = 1, 6 do
    local crate = nodeNew()
    nodeSetMesh(crate, meshBox(0.6, 0.6, 0.6), wood)
    nodeSetPosition(crate, -1, -1.5 + (i - 1) * 0.62, 0)
    bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.6, 0.6, 0.6)
    bodySetMass(crate, 5)
end

paddle = nodeNew()
nodeSetMesh(paddle, meshBox(0.3, 1.2, 1.6), red)
nodeSetPosition(paddle, -4, -1.2, 0)
bodyNew(paddle, BODY_KINEMATIC, SHAPE_BOX, 0.3, 1.2, 1.6)

function onOverlayUpdate()
    nodeMove(paddle, 0.06, 0, 0)   -- The kinematic paddle sweeps through the stack.
    return OVERLAY_UPDATED
end
Mass and materials

A dynamic body’s mass comes from its shape’s volume at the density of water, so a box the size of a door weighs 140 kilograms and a nudge will not move it. Set bodySetMass on anything you want to feel light, and size impulses to the mass: an impulse of mass * speed sets that speed. bodySetFriction and bodySetBounce make ice and rubber; bodySetEnabled takes a body out of the world and puts it back without losing it.

Timing

The world steps at a fixed sixty times a second from the wall clock, after animations have posed their nodes and before the scene renders, so a kinematic body driven by an animation pushes with the right velocity. Pausing the game pauses physics; physicsSetEnabled(false) pauses it on its own. bodyIsResting says when a body has settled, which is when a thrown thing has stopped and a score can be counted. A body, player, ragdoll, soft body or vehicle whose node has been deleted is released at the start of the next frame, enabled or not and paused or not, so its slot is free again; a node handle that nodeNew later hands out afresh carries none of the old node’s physics, and playerExists and its kind answer false for it until it gets its own.

1.16.2. Events and Queries

Define onCollision(nodeA, nodeB, x, y, z, speed) and Singe calls it once for each new contact, with the point and the speed the two bodies met at, so a bump and a crash can sound different. A body made a trigger with bodySetTrigger pushes nothing but reports what enters and leaves it through onTrigger(trigger, other, entered): a finish line, a doorway, a danger zone. physicsRaycast finds the first body along a ray; with sceneUnproject for the ray, that is mouse picking (see Nodes). A list of nodes as its last argument is left out of the search, so a shot fired from inside the player’s own body does not stop there.

finish = nodeNew()
nodeSetPosition(finish, 0, 1, -40)
bodyNew(finish, BODY_STATIC, SHAPE_BOX, 12, 2, 0.5)
bodySetTrigger(finish, true)

function onTrigger(trigger, other, entered)
    if trigger == finish and other == car and entered then
        lapDone()
    end
end

function onCollision(a, b, x, y, z, speed)
    if speed > 6 then
        local channel = soundPlay(crashSound)
        soundSetPosition(channel, x, y, z)
    end
end

1.16.3. Joints

jointHinge, jointBall and jointSlider connect two bodies, or a body and the world when the second node is -1: doors, pendulums, drawers, the wheels of a side-on car. The anchor and the axis are given in world space where the bodies stand when the joint is made. Hinges and sliders take limits (jointSetLimits): a positive hinge angle is a right-hand turn of the first node about the axis, and a positive slider distance is along it.

door = nodeNew()
nodeSetMesh(door, meshBox(0.9, 2.0, 0.05), oak)
nodeSetPosition(door, 0.45, 1.0, 0)
bodyNew(door, BODY_DYNAMIC, SHAPE_BOX, 0.9, 2.0, 0.05)
bodySetMass(door, 20)
local hinge = jointHinge(door, -1, 0, 1.0, 0, 0, 1, 0)   -- On the frame, about Y.
jointSetLimits(hinge, 0, 110)                            -- Opens one way, 110 degrees.

Bodies on model instances work like any other: bodyNew(instanceRoot, BODY_DYNAMIC, SHAPE_HULL) wraps the whole model in a convex hull. A skinned character is best a player (below) or a kinematic capsule that pushes things rather than being pushed.

1.16.4. 2D Games

Physics is not tied to the 3D scene. Nodes exist on every machine, GPU or not, so a 2D game can give nodes bodies, call physicsSet2D(true) so they move in X and Y and turn about Z only, work in overlay coordinates with gravity pointing down the screen, and draw sprites where the nodes are. This is the form that runs on a Raspberry Pi 3, which has no 3D.

physicsSet2D(true)
physicsSetGravity(0, 900, 0)          -- Pixels per second squared; overlay Y runs down.

floor = nodeNew()
nodeSetPosition(floor, 360, 470, 0)
bodyNew(floor, BODY_STATIC, SHAPE_BOX, 720, 20, 50)

crate = nodeNew()
nodeSetPosition(crate, 200, -40, 0)
bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 40, 40, 50)
bodySetMass(crate, 1)

function onOverlayUpdate()
    local x, y = nodeGetPosition(crate)
    local _, _, angle = nodeGetRotation(crate)
    spriteRotate(crateArt, angle)
    spriteDraw(crateArt, x, y, true)
    return OVERLAY_UPDATED
end

Give every 2D body some depth (the third size) so shapes overlap in Z; 50 is fine. Circles are SHAPE_SPHERE. Players and 2D emitters (see Particles) work in this world too, and a platformer is a player with playerMove(node, vx).

1.16.5. Players

A body goes where forces send it; a player goes where the script says. playerNew puts a character controller on a node: a capsule by default (playerNew(node, radius, height)), or any convex bodyNew shape (playerNew(node, SHAPE_BOX, w, h, d) for a robot, playerNew(node, SHAPE_SPHERE, r, 0) for something that rolls yet still climbs steps, SHAPE_HULL for the model’s own outline; three arguments always mean a capsule, so a sphere spells its sizes out). The shape stands on the node’s origin, which is the feet. Each frame the script gives playerMove the horizontal velocity it wants, and the controller walks along floors, climbs steps up to playerSetStep, slides along walls, refuses slopes steeper than playerSetSlope, falls under gravity, rides moving platforms, and shoves light dynamic bodies out of the way (playerSetPush). playerJump works only with ground underfoot and says whether it did. The node’s rotation is the script’s: turn it to face the way it walks, and hang the model under it as a child.

hero = nodeNew()
nodeSetPosition(hero, 0, 0, 0)
playerNew(hero, 0.3, 1.0)               -- A capsule of radius 0.3, 1 tall, feet at the node.
fox = modelInstance(modelLoad(DIR .. "Fox.glb"))
nodeSetParent(fox, hero)

function onInputPressed(switch)
    if switch == SWITCH_BUTTON1 then
        playerJump(hero, 4.5)               -- Needs ground underfoot.
    end
end

function onOverlayUpdate()
    local vx = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_X) / 32767 * 3
    local vz = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_Y) / 32767 * 3
    playerMove(hero, vx, vz)
    if vx ~= 0 or vz ~= 0 then
        nodeSetRotation(hero, 0, math.deg(math.atan(-vx, -vz)), 0)
    end
    return OVERLAY_NOT_UPDATED
end

Players report onCollision when they start touching a body and onTrigger when they enter or leave a sensor, with their node in the place a body’s node would take, so a door, a pickup and a lava pit work the same for a player as for a ball. playerIsOnGround and playerGetGround say what the player stands on, for footstep sounds and for dropping off a platform on purpose. In a 2D world a player is a platformer character: playerMove(node, vx) runs along X, gravity points down the screen, and everything else is the same. The controller’s tolerances scale with the shape, so a 30 pixel capsule in a sprite game behaves like a 0.3 meter one in a 3D game.

1.16.6. Vehicles

A vehicle is a dynamic body (the chassis, made with bodyNew like any body, facing -Z with Y up) that Jolt drives through wheels: vehicleNew(node, VEHICLE_CAR) for anything with axles, VEHICLE_MOTORCYCLE for two wheels in a line that lean through turns and balance, or VEHICLE_TANK for wheels on two tracks that turn on the spot. Wheels are nodes: vehicleAddWheel(node, wheelNode, radius, width, suspension) takes the wheel’s position from where its node is relative to the chassis, and from then on the engine poses that node every frame (its X axis is the axle, so a meshCylinder wheel wants a child turned 90 degrees). Wheels found in a model with nodeFind("wheelFL", car) work the same. By default the front wheels steer and all of them drive; vehicleSetWheel says otherwise.

Each frame the script hands over the driver: vehicleDrive(node, forward, right, brake, handBrake). The engine, automatic gearbox and differentials are Jolt’s with a 1500 kg car’s defaults; vehicleSetEngine, vehicleSetGears, vehicleSetSuspension, vehicleSetSteering, vehicleSetBrakes and vehicleSetAntiRoll tune them, and any change rebuilds the vehicle in place at the next step. vehicleGetSpeed, vehicleGetRpm and vehicleGetGear feed a dashboard. A vehicle is still a body: it jumps ramps, hits walls, shoves crates and reports onCollision.

car = nodeNew()
nodeSetMesh(car, meshBox(1.8, 0.5, 4.0), paint)
nodeSetPosition(car, 0, 1, 0)
bodyNew(car, BODY_DYNAMIC, SHAPE_BOX, 1.8, 0.5, 4.0)
bodySetMass(car, 1500)
vehicleNew(car, VEHICLE_CAR)
local corners = {
    { -0.95, -0.2, -1.4 }, { 0.95, -0.2, -1.4 },   -- Front left and right ...
    { -0.95, -0.2, 1.4 }, { 0.95, -0.2, 1.4 },     -- ... rear left and right.
}
for i, p in ipairs(corners) do
    local wheel = nodeNew()
    nodeSetParent(wheel, car)
    nodeSetPosition(wheel, p[1], p[2], p[3])
    vehicleAddWheel(car, wheel, 0.35, 0.25, 0.4)
end

function onOverlayUpdate()
    local throttle = controllerGetAxis(0, GAMEPAD_AXIS_RIGHT_TRIGGER) / 32767
    local brake    = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_TRIGGER) / 32767
    local steer    = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_X) / 32767
    vehicleDrive(car, throttle, steer, brake, 0)
    return OVERLAY_NOT_UPDATED
end

Tanks take forward as throttle and right as the turn (with no throttle they pivot), and ignore the steering, brake and anti-roll tuning, since their tracks brake and turn on their own. The motorcycle’s lean spring is scaled to the chassis, so a light bike balances as well as a heavy one. Wheeled vehicles need a 3D world; a side-on 2D car is a body with two hinged wheels, which the joint calls already build.

1.16.7. Water

bodySetWater(node, density, linearDrag, angularDrag) fills a static body with water: the top of its box is the surface, and every dynamic body inside floats, sinks or rolls by Jolt’s buoyancy against that surface (the submerged part of the shape counts, so a tilted crate rights itself), slowed by the drags. bodySetCurrent gives the water a flow. density is a multiplier, 1 for water, and each floating body’s own bodySetBuoyancy (default 1.2, which floats gently; below 1 sinks) scales it. The volume is a trigger, so onTrigger fires on the way in and out for splashes. Water is not drawn: give the volume’s node a blended material, or none.

A player in water swims: playerIsSwimming says so, playerMove(node, vx, vy, vz) then steers in three axes, it sinks slowly with no vertical input (playerSetSwim sets that rate and the water’s drag), and the current carries it. A boat is a buoyant hull that vehicleNew(node, VEHICLE_BOAT) gives a propeller and a rudder: vehicleSetThrust says how hard it pushes and where in the hull, vehicleSetRudder how hard it turns, and vehicleDrive works as for a car, all only while the propeller is under a surface.

pool = nodeNew()
nodeSetMesh(pool, meshBox(8, 3, 12), blue)   -- Blended blue, drawn as the water.
nodeSetPosition(pool, 0, -1.5, 0)            -- Its top, at Y = 0, is the surface.
bodyNew(pool, BODY_STATIC, SHAPE_BOX, 8, 3, 12)
bodySetWater(pool, 1.0, 0.6, 0.2)
bodySetCurrent(pool, 0.5, 0, 0)              -- Drifting toward +X.
bodySetBuoyancy(crate, 1.6)                  -- Rides high.
bodySetBuoyancy(anchor, 0.3)                 -- Goes down.

1.16.8. Ragdolls

ragdollNew(node) looks under a model instance for its skin and turns the skeleton into a ragdoll recipe: every joint with a child joint becomes a capsule along that bone, jointed to the nearest bone above it by a swing-twist joint with sensible limits, and leaf joints (fingers, ears, the tip of a tail) ride along with their parents. Nothing moves until ragdollActivate: then the animation stops, bodies are made where the bones are, and from that moment physics drives the joint nodes, so the skinned mesh flops, hits the floor and comes to rest with the rest of the world.

ragdollApplyImpulse shoves one bone by its joint’s name. ragdollSetStrength powers every joint toward the pose the ragdoll was activated in, which turns a limp fall into a stagger or lets a downed character pull its limbs back in; it does not stand a body up, since nothing pushes off the floor. ragdollDeactivate hands the skeleton back to animation from wherever it lies, and an animationPlay with a fade then eases it up from there. Tune a bone that looks wrong with ragdollSetJoint before activating.

fox = modelInstance(foxModel)
ragdollNew(fox)                            -- Recipe from the skin; still animated.
function onCollision(a, b, x, y, z, speed)
    if (a == hero or b == hero) and speed > 3 then
        playerSetEnabled(hero, false)
        ragdollActivate(fox)                 -- Physics drives the skeleton now.
        ragdollApplyImpulse(fox, "b_Spine02_03", 40, 30, 0)
    end
end

1.16.9. Soft Bodies

Cloth, rope and jelly are meshes whose vertices are simulated. softNew(node, SOFT_CLOTH) turns the node’s mesh into cloth, its vertices (welded by position) into particles joined by stretch, shear and bend constraints, where the node has put it in the world; a subdivided meshPlane(width, depth, columns, rows) is the usual start. softNew(node, SOFT_BODY) does the same for a closed mesh and softSetPressure inflates it: a balloon, a jelly. softNew(node, SOFT_ROPE, x, y, z, segments, radius) runs a chain of particles from the node’s position to that point and gives the node a tube mesh around them (set its look with nodeSetMaterial).

Soft bodies collide with everything rigid, fall under gravity, and are drawn by the mesh they came from, which the engine rewrites every frame. softPin holds the nearest particle where it is or to a node (the flag’s edge to the pole, the rope’s top to the crane); softSetStiffness, softSetMass and softSetDamping tune the material. A node whose mesh is shared with other nodes changes them too, so give a soft body a mesh of its own.

flag = nodeNew()
nodeSetMesh(flag, meshPlane(1.6, 1.0, 16, 10), red)
nodeSetPosition(flag, -4.2, 2.4, 0)
nodeSetRotation(flag, 90, 0, 0)                 -- Hanging upright.
softNew(flag, SOFT_CLOTH)
for _, y in ipairs({ 1.9, 2.15, 2.4, 2.65, 2.9 }) do
    softPin(flag, -5, y, 0)                     -- Along the pole.
end

Cost scales with the particle count: a 20 by 20 sheet is 441 particles and fine on a Raspberry Pi 4; keep cloth to a few hundred particles and a rope to a dozen segments. Particles collide with rigid bodies, not faces, so a fine enough mesh (particles closer than the smallest thing that will land on it) is what stops a crate falling through. There is no self-collision: cloth can pass through itself when crumpled. Skinned meshes cannot be soft.

1.16.10. Seeing the Physics

When a crate falls through the floor or a joint bends the wrong way, physicsSetDebug draws what the simulation actually holds as lines over the scene each frame:

  • DEBUG_SHAPES: the bodies in wireframe, colored by state (sleeping, moving, static), with the players in yellow.

  • DEBUG_CONSTRAINTS: the joints, ragdoll joints and vehicle constraints with their limits.

  • DEBUG_CONTACTS: a red cross where bodies met this step.

  • DEBUG_VELOCITIES: a line along each moving body’s velocity.

  • DEBUG_STATIC: the static bodies' shapes as well, which stay off otherwise because a level mesh is a lot of lines.

Add them together, or use DEBUG_ALL for the first four. DEBUG_NONE turns it off, and it costs nothing while off. A script draws its own lines the same way with lineDraw (a ray cast, a path, a bounding box), one frame at a time like the overlay, and navDraw shows a navigation mesh.

if debugging then
    physicsSetDebug(DEBUG_SHAPES + DEBUG_CONTACTS)
end

function onOverlayUpdate()
    local hit, hx, hy, hz = physicsRaycast(gunX, gunY, gunZ, aimX, aimY, aimZ, 60)
    if hit then
        lineDraw(gunX, gunY, gunZ, hx, hy, hz, 255, 255, 0)
    end
    return OVERLAY_NOT_UPDATED
end

1.16.11. Where It Runs

Physics runs on the CPU and needs no GPU, but the library is built for SSE4.1 on x86 (2008 and later) and NEON on the Pi; a machine below that gets an error from the first bodyNew. The simulation uses every core but one, so a four-core Pi steps on three threads; the program trace says how many.

1.17. Particles

Sparks, smoke, fire, rain, dust, magic: anything made of many small short-lived things is a job for an emitter. An emitter holds a recipe (how many a second, how long they live, how fast and which way they set off, what pulls on them, how they grow, fade and spin) and a pool of particles it runs from that recipe. The script sets the recipe once, then starts the emitter for a steady stream (emitterStart), bursts it for a one-off puff (emitterBurst), or both. The engine moves every live particle every frame, and stops moving them while the game is paused.

One emitter API serves the overlay and the 3D scene; only the units and the drawing differ. Everything given as a minimum and a maximum (emitterSetLife, emitterSetSpeed, emitterSetSize) is drawn at random between the two for every particle.

1.17.1. 2D Emitters

emitterNew() with no argument makes a 2D emitter. It lives in overlay coordinates, Y down, so a fountain’s gravity is positive Y. Move it with emitterSetPosition, and draw it from onOverlayUpdate with emitterDraw. The overlay itself is a picture the CPU paints, so particles are not painted into it: the GPU draws them, either above the whole overlay (PARTICLE_OVER, the default) or beneath it and above the video and the 3D scene (PARTICLE_UNDER, for smoke behind the score). 2D emitters run on every machine Singe runs on, the Raspberry Pi 3 included, and go well with 2D physics: read a body’s node position and give it to emitterSetPosition.

sparks = emitterNew()
emitterSetBlend(sparks, PARTICLE_ADD)
emitterSetLife(sparks, 0.3, 0.7)
emitterSetSpeed(sparks, 80, 200)
emitterSetDirection(sparks, 0, -1)       -- Up the screen.
emitterSetSpread(sparks, 70)
emitterSetGravity(sparks, 0, 500)
emitterSetSize(sparks, 5, 1)
emitterSetColor(sparks, 255, 255, 200, 255, 255, 120, 0, 0)

function onOverlayUpdate()
    overlayClear()
    emitterSetPosition(sparks, grinderX, grinderY)
    emitterDraw(sparks)
    return OVERLAY_UPDATED
end

1.17.2. 3D Emitters

emitterNew(node) makes a 3D emitter attached to a node. Particles are born at the node’s world position (spread over emitterSetRadius), in world units, and draw themselves in the scene as camera-facing billboards after every mesh: depth-tested against the geometry, never writing depth, unlit unless asked, casting and receiving no shadows. By default a particle stays where it was born once it leaves the emitter (smoke keeps drifting where it was made while the torch moves on); emitterSetLocal makes the whole cloud follow the node instead. Deleting the node deletes its emitters.

flame = emitterNew(torchTip)
emitterSetBlend(flame, PARTICLE_ADD)
emitterSetRate(flame, 140)
emitterSetLife(flame, 0.4, 0.9)
emitterSetSpeed(flame, 0.6, 1.4)
emitterSetDirection(flame, 0, 1, 0)
emitterSetSpread(flame, 15)
emitterSetSize(flame, 0.35, 0.05, 0.3)
emitterSetColor(flame, 255, 200, 90, 255, 255, 40, 0, 0)
emitterStart(flame)

1.17.3. The Picture

A particle is a textured quad. Without a texture it is a soft disc the engine provides; emitterSetTexture gives it a loaded sprite instead (a puff, a spark streak, a snowflake), and for an animated sprite emitterSetFrames picks a random frame per particle, so one atlas of puffs gives a varied cloud. Blending is normal (PARTICLE_ALPHA) or additive (PARTICLE_ADD, for anything that glows). emitterSetColor gives the color and alpha at birth and at death, and the particle fades between them over its life; emitterSetSize does the same for its size, with a third value for how fast it spins.

1.17.4. Trails, Collisions, Lit, and Soft Particles

emitterSetTrail(emitter, length, width) keeps the last few positions of every particle and draws a ribbon through them, fading toward the tail: sparks, tracer rounds, comets, in 2D and 3D alike. emitterSetCollide lets particles bounce: off a horizontal floor at a height you give (COLLIDE_FLOOR, free), or off the physics world by ray casts (COLLIDE_SCENE, 3D only, capped per frame so a big emitter spreads the cost over a few frames).

Two more are for 3D only. emitterSetLit shades each particle by the scene’s lights and sky as a small sphere facing the camera, so smoke takes a brazier’s color and dust glints in the sun (shadows are not read). emitterSetSoftness fades a particle out over a distance where it meets geometry, so smoke does not cut into a floor or a fountain into its pool; this costs one extra depth pass of the scene per frame while any emitter uses it.

smoke = emitterNew(brazier)
emitterSetTexture(smoke, spriteLoad(DIR .. "puff.png"))
emitterSetRate(smoke, 30)
emitterSetLife(smoke, 2, 4)
emitterSetSpeed(smoke, 0.3, 0.6)
emitterSetDirection(smoke, 0, 1, 0)
emitterSetSize(smoke, 0.3, 1.2, 0.2)
emitterSetColor(smoke, 90, 90, 90, 160, 60, 60, 60, 0)
emitterSetLit(smoke, true)                  -- Takes the fire's color from below.
emitterSetSoftness(smoke, 0.4)              -- No hard edge where it meets the bowl.
emitterStart(smoke)

embers = emitterNew(brazier)
emitterSetBlend(embers, PARTICLE_ADD)
emitterSetTrail(embers, 6, 0.02)            -- A short streak behind each ember.
emitterSetCollide(embers, COLLIDE_FLOOR, 0.3, 0.8, 0)   -- Bounce off the ground at Y = 0.
emitterStart(embers)

1.17.5. Cost

Particles are cheap to simulate and cost what they cover on screen. A few thousand small ones are nothing; a handful of large additive ones over the whole screen are what slow a Raspberry Pi 4 down. The pool is capped by emitterSetMax (default 1000); when it is full, no more are born until some die.

1.18. Describing a Game Instead of Writing One

A game can be written as a description — a table of layers, entities and rules — and compiled into an ordinary Singe game by Forge, the authoring tool. Forge is a separate project with its own download and its own book.

1.19. Migrating from Singe 2.10

Singe 3.00 moved the sprite handle to the first argument of spriteDraw, spriteLoop, spriteQuality, spriteRotate, spriteRotateAndScale, spriteScale, and spriteSetFrame, so every sprite call now matches the video* family. To update a game, move the last argument of each of those calls to the front:

spriteDraw(x, y, cursor)          -- 2.10
spriteDraw(cursor, x, y)          -- 3.00
spriteRotate(angle, cursor)       -- 2.10
spriteRotate(cursor, angle)       -- 3.00

A game you cannot edit can opt into the old order instead. Either set the global before loading the framework:

SINGE_LEGACY_SPRITE_ARGS = true
dofile("Singe/Framework.singe")

or add LEGACY_SPRITE_ARGS = true to its games.dat entry. Nothing else changed shape, but a few behaviors did:

  • Handles and counts are returned as Lua integers; videoIsPlaying returns a boolean; mouseSetMode returns nothing.

  • Errors inside callbacks now end the game with a traceback instead of being printed and ignored, matching how argument errors have always behaved.

  • Held keys no longer repeat in MODE_NORMAL.

  • Nothing is written beside the game. Without --datadir the data directory is data/<game>/ under the game directory, where 2.x used the game’s own directory; saves, settings and high scores belong under singeGetDataPath().

  • math.randomseed accepts a fractional seed, as it did under 2.10’s Lua; it is floored before Lua 5.4’s generator sees it. os.clock is wall time since the engine started, not processor time.

  • The disc is parked on frame 1 by the engine before your script runs; Framework.singe no longer seeks when it is loaded.

  • onMouseMoved in MANY_MOUSE mode passes real movement in its third and fourth arguments, and onControllerMoved passes the controller index (0 to 3) instead of SDL’s instance ID.

  • mouseEnable / mouseDisable and singeEnablePauseKey / singeDisablePauseKey still work, as aliases of mouseSetEnabled and singeSetPauseKeyEnabled.

  • A laserdisc is no longer assumed. A games.dat entry with a VIDEO is a laserdisc game, as before; one without runs on a canvas instead. On the command line pass --disc (or --framefile), since a video found beside the script no longer implies a disc. See Games Without a Disc.

  • The pause key now pauses the whole game, not just the media: the script is frozen until the key is pressed again, and SWITCH_PAUSE is delivered to the script only when the key has been disabled. It acts on the key press rather than the release. See Pausing.

  • fontPrint keeps the strings it renders, and overlayClear refills only what was drawn since the last clear, so a HUD reprinted every frame is cheap. Rendering text with fontToSprite for performance is deprecated; it still works, and is still the way to get text you can measure, scale, or turn. See fontToSprite.

1.20. Engine Constants

The engine defines these globals before any script runs, so they are available to controls.cfg and to Framework.singe alike:

Constant Meaning

SWITCH_UP …​ SWITCH_RECORD

Values passed to onInputPressed / onInputReleased in MODE_NORMAL. SWITCH_MOUSE_DISCONNECT is raised by the engine itself when a mouse or light gun is unplugged, once as a press and once as a release; no key or button produces it. SWITCH_RECORD is the recording switch, which the engine acts on itself, as it does the screenshot switch.

FONT_QUALITY_SOLID, FONT_QUALITY_SHADED, FONT_QUALITY_BLENDED

Arguments for fontQuality.

MODE_NORMAL, MODE_FULL

Arguments for keyboardSetMode.

MOUSE_SINGLE, MOUSE_MANY (also SINGLE_MOUSE, MANY_MOUSE)

Arguments for mouseSetMode.

OVERLAY_NOT_UPDATED, OVERLAY_UPDATED

Return values for onOverlayUpdate.

RENDER_PIXELATED, RENDER_SMOOTH

Arguments for spriteQuality / videoQuality.

SPRITE_ALPHA, SPRITE_ADD, SPRITE_MULTIPLY

Blending for spriteSetBlend.

DISC_STOPPED, DISC_PLAYING, DISC_PAUSED, DISC_EJECTED

Return values of discGetState.

LIGHT_DIRECTIONAL, LIGHT_POINT, LIGHT_SPOT

Arguments for lightNew.

BODY_STATIC, BODY_DYNAMIC, BODY_KINEMATIC

Body types for bodyNew.

SHAPE_BOX, SHAPE_SPHERE, SHAPE_CAPSULE, SHAPE_CYLINDER, SHAPE_HULL, SHAPE_MESH

Collision shapes for bodyNew.

JOINT_HINGE, JOINT_BALL, JOINT_SLIDER

Joint types (the joint* calls name them directly).

DEBUG_NONE, DEBUG_SHAPES, DEBUG_CONSTRAINTS, DEBUG_CONTACTS, DEBUG_VELOCITIES, DEBUG_STATIC, DEBUG_ALL

What physicsSetDebug draws; add them together.

PARTICLE_ALPHA, PARTICLE_ADD

Blending for emitterSetBlend.

PARTICLE_OVER, PARTICLE_UNDER

Where 2D particles draw, for emitterSetLayer.

COLLIDE_NONE, COLLIDE_FLOOR, COLLIDE_SCENE

What particles bounce off, for emitterSetCollide.

BILLBOARD_NONE, BILLBOARD_ALL, BILLBOARD_Y

How a node faces the camera, for nodeSetBillboard.

LAYER_SCENE, LAYER_FRONT

Whether a node draws beneath the overlay or in front of it, for nodeSetLayer.

VEHICLE_CAR, VEHICLE_MOTORCYCLE, VEHICLE_TANK, VEHICLE_BOAT

Kinds of vehicle for vehicleNew.

SOFT_CLOTH, SOFT_BODY, SOFT_ROPE

Kinds of soft body for softNew.

FILTER_LINEAR, FILTER_NEAREST

Texture sampling for materialSetFilter.

TONEMAP_NEUTRAL, TONEMAP_ACES, TONEMAP_NONE

Tone curves for sceneSetTonemap.

SOUND_ERROR_INVALID, SOUND_REMOVE_HANDLE

-1, what soundPlay returns when no channel is free.

SINGE_VERSION_MAJOR, SINGE_VERSION_MINOR, SINGE_VERSION_STRING, SINGE_FRAMEWORK_VERSION

The engine version, as integers, as a string ("v3.00"), and as the number singeVersion() returns.

SINGE_DEAD_ZONE

The DEAD_ZONE from controls.cfg, in raw axis units.

SINGE_TRIGGER_THRESHOLD

The analog trigger threshold in those same raw units; 0 when the triggers are on SINGE_DEAD_ZONE, which is the default.

SINGE_LEGACY_SPRITE_ARGS

True when the game asked for the 2.10 sprite argument order.

SINGE_DISC

True when the game has a laserdisc; false when the canvas is the world.

SINGE_GAMEPAD_BASE, SINGE_GAMEPAD_STRIDE, SINGE_AXIS_STRIDE, SINGE_GAMEPAD_BUTTON_OFFSET, SINGE_MOUSE_BASE, SINGE_MOUSE_STRIDE, SINGE_MAX_CONTROLLERS, SINGE_MAX_MICE, SINGE_CONTROLLER_AXES, SINGE_CONTROLLER_BUTTONS

Layout of the controller and mouse input codes, and how many axes and buttons a pad has; Framework.singe builds the GAMEPAD_N and MOUSE_N tables from them, and a service screen walks a pad with them.

SINGE_SCALE_MIN, SINGE_SCALE_MAX, SINGE_SHIFT_MIN, SINGE_SHIFT_MAX, SINGE_ROTATE_STEP

What vldpSetScale, vldpSetShift and vldpSetRotate will take. Clamp to these rather than to your own copies: a shift out of range ends the script.

Framework.singe adds the SCANCODE and MODIFIER tables (SDL’s key and modifier values), GAMEPAD_0 to GAMEPAD_3, MOUSE_0 to MOUSE_3, the GAMEPAD_AXIS_* indexes for controllerGetAxis, and DIR.

1.21. Included Libraries

In addition to the standard Lua libraries and the Singe API, the following libraries are also available for use in Singe programs without the need to install any additional software:

Library Purpose

Copas

Asynchronous networking

LuaFileSystem

Expanded filesystem support

json.lua

JavaScript Object Notation encoding and decoding

binaryheap

Binary heap data structure

timerwheel

Efficient timer scheduling

LuaSec

TLS / SSL communication

LuaSocket

TCP and UDP

LuaRS232

RS232 serial port access

lsqlite3

SQLite databases, require("sqlite3")

md5

require("md5") for sum, hexsum, exor, crypt and decrypt; the PUC-Rio library Hypseus bundles, whose sumhexa it names hexsum

LuaBitOp

require("bit") for the bitwise operations of Lua 5.1, which 5.4 has as operators

lrandom

require("random") for a Mersenne Twister generator, separate from math.random

Lua CJSON

require("cjson") for JSON encoding and decoding, beside the json module above

LPeg

require("lpeg") for parsing expression grammars

middleclass

require("middleclass") for classes, if you would rather build entities out of them than out of tables

lume

require("lume") for the small things every game needs: lerp, clamp, round, shuffle, split, serialize, weightedchoice

inspect

require("inspect") to print a table in a shape a person can read, for when debugPrint is the debugger

bump

require("bump") for moving things that must not pass through each other — it answers where a mover ends up, which the collide calls deliberately do not

MobDebug

require("mobdebug"), the debugger ZeroBrane Studio talks to; --debug starts it, so a game needs no line of its own

RmlUi

The GUI’s own object model, the rmlui global (see GUI)

Their usage is beyond the scope of this document. The md5, LuaBitOp, lrandom, Lua CJSON, and LPeg libraries are there because Hypseus exposes them, so a game written against Hypseus finds the same modules under the same names; nothing in Singe needs them.

1.22. Audio Sync

Singe presents video against the audio clock: a frame is shown when the sound that belongs with it is heard. The engine measures its own audio path at startup. SDL cannot report how much audio is queued between the mixer and the speaker, so Singe drains the device once, before anything audible plays, and counts the burst of buffers SDL uses to refill it; that burst is the queue depth, and the clock subtracts it. Run with --program to see the measurement in the trace (Audio device queue: …​).

What the engine cannot see is anything downstream of the operating system’s audio server: a DAC, an HDMI receiver, a Bluetooth link. Those add a fixed delay that varies by machine. If actions on screen visibly precede their sound, pass the missing milliseconds with --audiodelay=MS, put AUDIO_DELAY = MS in games.dat, or let the game set it from a service menu with singeSetAudioDelay. Positive values mean the audio is late; the video is held back to match. A negative value handles the rare case of audio arriving early.

The bundled menu has a calibration screen for that downstream delay. Press the key mapped to INPUT_SERVICE (the 9 key by default) on the game list and choose Audio Delay from the service tools (see The Service Tools). The screen is a page of the menu’s document: it covers the menu in black, shows the delay being tried and the device queue the engine measured, plays a click once a second and turns white for one frame at each flash. Adjust with left and right (10 ms) and up and down (1 ms) until the flash and the click happen together, then press button 1 to save. Start resets to zero and button 2 (or the service key again) cancels. The value is stored in machine.cfg in the data root and applied by the engine to every game on that machine, whether launched from the menu or from the command line; it is added to any per-game AUDIO_DELAY. Recalibrate after changing speakers, headphones, or displays.

The screen works because the click and the disc audio share one mixer device and one queue: the flash is scheduled the measured queue plus the candidate value after the click, so when the two coincide the candidate is exactly the delay the engine cannot see. Display lag is folded in for free. A game can read the values with singeGetAudioCalibration and singeGetAudioLatency, or offer its own screen with singeSetAudioCalibration.

Two properties of the video file itself also matter. AAC audio carries encoder priming samples that the container must tell decoders to skip; files muxed without that information (an MP4 with no edit list, a Matroska file with no codec delay) play their audio about 20 milliseconds late, which AUDIO_DELAY can absorb. And when the first video frame is timestamped later than the first audio sample, Singe honors the container’s timing, so leading audio is not lost.

1.23. Video, Audio, and Container Formats

Singe decodes video with FFmpeg’s libraries directly, using the platform’s hardware decoder when it offers one for the codec (VA-API or VDPAU on Linux, D3D11VA on Windows, VideoToolbox on macOS, and on an ARM board the V4L2 decoders — the memory-to-memory one, which on a Pi 4 covers H.264, the stateless Request API one a Pi 5 uses for HEVC, and Rockchip’s own on an RK3588) and its own software decoder otherwise; the program trace reports which, and --softwarevideo forces software. Any container and codec the bundled FFmpeg can demux and decode will play: MP4, MKV, MPEG program streams, AVI, AV1 and the classic Daphne .m2v elementary streams with a matching .ogg audio file next to them. Every audio track in the file is available to discSetAudioTrack / videoSetAudioTrack; all tracks must share one sample format, channel count, and rate.

A laserdisc held interlaced fields, and a rip that kept them combs on every progressive display. --deinterlace decides what happens: auto, the default, runs bwdif over the frames the file marks interlaced and leaves everything else alone, so a progressive disc pays nothing; on is for a file whose flags are wrong; off never touches the picture. One picture comes out for each one that goes in — a disc is addressed by frame number, so a deinterlacer that turned each frame into two fields would move every frame in the index.

The first time a video is opened, Singe indexes it and stores the index next to the game’s other data (<name>-<hash>.index, the hash made from the video’s full name so two videos with one base name keep separate indexes). Indexing is one pass over the file without decoding, a few seconds even for a feature length disc, and happens again if the video changes. When a video is loaded, Singe reports its keyframe spacing in the program trace (--program), with a warning there if keyframes are more than two seconds apart, because a seek has to decode forward from the previous keyframe. Decoding happens on a separate thread, so a slow seek shows the previous frame a little longer instead of stalling the game.

A framefile’s segments are opened as the disc reaches them, not all at once: the one playing, the one after it, and room for a seek to move between two. A long framefile can have hundreds of segments — one released game has 213 — and holding a decoder open for every one of them costs hundreds of open files for no gain. A framefile that names a file which is not there still says so at startup.

For laserdisc footage the constraints are frame accuracy and seek speed, not compression. H.264 in MP4 or MKV with a short keyframe interval (one or two seconds) seeks quickly and plays on every supported platform; long keyframe intervals make discSearch visibly slow because the decoder must walk from the previous keyframe. Standard definition (720x480 or 720x576) is the sweet spot. High definition sources work but cost proportionally more CPU on Raspberry Pi class hardware, and the overlay defaults to half the video resolution, so oversized video buys little.

Sound effects and music are read by SDL_mixer first and by FFmpeg for anything it turns down, so between them they cover:

  • WAV, AIFF, AU and VOC for uncompressed audio. Short uncompressed WAV files give the lowest latency, and are what a gunshot should be.

  • Ogg Vorbis, Opus, MP3, FLAC and WavPack.

  • AAC (.m4a, .aac), ALAC, AC-3, WMA, APE, TTA, Speex and AMR — everything else the bundled FFmpeg decodes.

  • Tracker modules through libxmp: MOD, S3M, XM and IT, and fifty-odd others including 669, AMF, MED, OKT, PTM, STM and ULT.

  • Chiptunes through game-music-emu: NSF and NSFE, SPC, VGM, GBS, AY, GYM, HES, KSS and SAP. The gzipped VGZ form is not read; ungzip it to VGM first. One that does not say how long it is plays until it falls silent, which can be never, so it is decoded as it plays rather than up front.

  • MIDI, synthesized from a SoundFont. See MIDI.

The Audio: line of the trace header (--program or --trace) lists the decoders the build actually carries.

Pictures work the same way: SDL_image first, FFmpeg for the rest. That covers PNG, JPEG, WebP, GIF, BMP, TGA, PCX, PNM, LBM, QOI, XCF, XPM and SVG from SDL_image, and TIFF, OpenEXR, JPEG 2000, DDS, PSD, DPX, AVIF and HEIC from FFmpeg. An animated GIF or WEBP loads as a sprite animation; see spriteLoad, which also takes a size for rasterizing an SVG. Radiance .hdr and OpenEXR both work as a sky (sceneSetSky) and keep their full range.

Fonts are read by FreeType: TrueType, OpenType, WOFF, WOFF2, Type 1, BDF and PCF, with color glyphs (both the bitmap and the vector kind) and HarfBuzz shaping for Arabic, Hebrew and the Indic scripts.

2. Lua API Reference

This chapter documents the Lua API exposed by the Singe engine — every function your game script can call, and every callback Singe will invoke on you. It is aimed at developers writing new games or porting video-heavy games from other engines.

2.1. Conventions

Every API entry below follows the same structure:

  • Signature(s) in a code fence, showing every accepted form.

  • Description of what the function does and any side effects.

  • Parameters listed inline, or as a table when there are more than two.

  • Returns line describing the value pushed back to Lua (omitted when the function returns nothing).

  • Notes, if there are gotchas worth flagging.

  • Since — the Singe version the function first appeared in.

  • See also — related functions you will likely use in the same call site.

  • Example — a short, realistic snippet in the shape of real game code.

An entry that begins Hypseus extension is there so that a game written for Hypseus Singe runs here unchanged. The same goes for an argument form marked as Hypseus’s on a function that otherwise takes Singe’s own.

Do not write new games against the Hypseus API. Those entries exist for compatibility, not as a recommendation. Several of them answer a fixed value because the thing they describe does not exist in Singe, some are accepted and ignored, and others carry scales and argument orders inherited from another engine — videoGetVolume() counts to 64 where the rest of Singe counts to 100, and the spriteAnim names take the sprite last where every Singe sprite call takes it first. Each entry names the Singe equivalent to use instead. New code that sticks to the Singe API is shorter, consistent with itself, and will not be surprised when a compatibility answer stays constant.

A few rules apply across the whole API:

  • Colors are 8-bit per channel: red, green, blue, and opacity are each integers from 0 to 255.

  • Overlay coordinates are in the current overlay resolution (set by overlaySetResolution), not screen pixels. The default overlay resolution is half the video resolution in each dimension; call overlaySetResolution to change it.

  • Handles returned by *Load functions (sprites, sounds, fonts, videos) are opaque integers. Pass them back unchanged to the other functions in that namespace. Do not do math on them.

  • Invalid arguments abort the script. If a function is called with the wrong number of arguments, wrong types, or a handle that has already been unloaded, Singe terminates the running script with an error — it does not return nil or a failure code. Validate user input in your script before handing it to the API.

  • Drawing must happen from onOverlayUpdate. Calls to any overlay*, spriteDraw, videoDraw, or fontPrint function from other callbacks will not be reflected on screen and may corrupt the overlay. This is the one rule that catches every new Singe developer.

2.2. Animation

These calls drive the animations a model carries, per instance. Every one takes the root node returned by modelInstance; other nodes raise an error, except animationIsPlaying, which answers false. Animations are numbered from 1 in the order modelGetAnimations lists them, or named as the file names them. A clip plays on the base layer, and up to four more can play on layers 1 to 4 above it; the time, pause, resume and seek calls address the base layer only. Time is in seconds, advances with the wall clock by at most a tenth of a second a frame, and holds while the game is paused. Node animation, skinning and morph target weights are all driven. See the Animation part of 3D Scenes.

2.2.1. animationGetTime

seconds = animationGetTime(node)

The current time into the base layer’s clip, playing or paused, in the clip’s own seconds (a speed of 2 moves it twice as fast). A looping clip wraps back to 0 at its end; a non-looping one stops at its length. Nothing played yet gives 0. Clips on the upper layers are not reported. A node that is not an instance root ends the script.

Returns: Seconds as a number.

Since: 3.00. See also: animationSetTime, animationIsPlaying

Example
-- Play the footstep once each time the walk cycle passes its two contact points.
function onOverlayUpdate()
    local t = animationGetTime(hero)
    if (lastStepTime < 0.25 and t >= 0.25) or (lastStepTime < 0.75 and t >= 0.75) then
        soundPlay(footstep)
    end
    lastStepTime = t
    return OVERLAY_NOT_UPDATED
end

2.2.2. animationIsPlaying

playing = animationIsPlaying(node)

Whether the base layer’s clip is advancing on this instance. A non-looping clip stops playing when it reaches its end, and animationPause and animationStop both make this false; a looping clip stays true until stopped. Unlike the other calls here, a node that is not an instance root does not end the script but answers false.

Returns: Boolean.

Since: 3.00. See also: animationPlay, animationPause

Example
-- Back to idling once the one-shot attack has run out.
function onOverlayUpdate()
    if attacking and not animationIsPlaying(hero) then
        attacking = false
        animationPlay(hero, "Idle", true, 1, 0.2)
    end
    return OVERLAY_NOT_UPDATED
end

2.2.3. animationPause

animationPause(node)

Freezes the base layer’s clip at its current time; the nodes hold that pose until animationResume continues it or another clip is played. Clips on the upper layers keep running. Pausing an instance that has nothing playing is harmless. A node that is not an instance root ends the script.

Since: 3.00. See also: animationResume, animationSetTime

Example
-- A cutscene freezes the crowd while the camera moves.
function beginCutscene()
    for _, npc in ipairs(crowd) do
        animationPause(npc)
    end
    cameraSet(cutsceneCamera)
end

2.2.4. animationPlay

animationPlay(node, nameOrIndex)
animationPlay(node, nameOrIndex, loop)
animationPlay(node, nameOrIndex, loop, speed)
animationPlay(node, nameOrIndex, loop, speed, fade)

Starts one of the model’s clips from its beginning on the base layer of this instance, replacing whatever was playing there; the pose updates at once. With a fade the old clip keeps running while it fades out over that many seconds, and when nothing was playing the fade starts from the pose the nodes are in now (a ragdoll that was just switched off, a scripted pose), with nodes the new clip does not animate easing back to the model’s rest pose. A node that is not an instance root, a name the model does not have, or a number outside 1 to the clip count ends the script.

Parameters:

  • node — the instance’s root node from modelInstance.

  • nameOrIndex — a clip name as the file stores it, or its number from 1 in modelGetAnimations order.

  • loop — boolean, default true. When false the clip stops at its last keyframe and animationIsPlaying becomes false.

  • speed — playback rate, default 1. 2 is twice as fast; 0.5 is half.

  • fade — seconds to crossfade from what was playing, default 0 (a snap).

Example
-- A guard that idles until the player is spotted, then runs.
guardModel = modelLoad(DIR .. "Models/Guard.glb")
guard      = modelInstance(guardModel)
animationPlay(guard, "Idle")

function onSpotted()
    animationPlay(guard, "Run", true, 1.3, 0.4)
end

2.2.5. animationPlayLayer

animationPlayLayer(node, layer, nameOrIndex)
animationPlayLayer(node, layer, nameOrIndex, loop)
animationPlayLayer(node, layer, nameOrIndex, loop, speed)
animationPlayLayer(node, layer, nameOrIndex, loop, speed, fade)

Plays a clip on one of the four layers above the base, blended over whatever is beneath it by the layer’s weight (animationSetLayerWeight, default 1) and limited to part of the skeleton when a mask is set (animationSetLayerMask). Higher layers blend over lower ones; each layer runs its own clip, time and loop independently of the base. nameOrIndex, loop, speed and fade mean what they do in animationPlay, with one difference: a fade on a layer that was empty ramps the layer’s weight in from 0 instead of crossfading from a pose. A layer outside 1 to 4, a node that is not an instance root, or a clip the model does not have ends the script.

Parameters:

  • node — the instance’s root node.

  • layer — 1 to 4.

  • nameOrIndex — a clip name or number, as in animationPlay.

  • loop — default true.

  • speed — default 1.

  • fade — seconds, default 0.

Example
-- Walk with the whole body, look about with the head only.
animationPlay(fox, "Walk", true)
animationPlayLayer(fox, 1, "Survey", true, 1, 0.5)
animationSetLayerMask(fox, 1, nodeFind("b_Neck_04", fox))

-- Later, wave with one arm over whatever the legs are doing.
function onGreet()
    animationPlayLayer(fox, 2, "Wave", false, 1, 0.2)
end

2.2.6. animationResume

animationResume(node)

Continues the base layer’s clip from where animationPause froze it, or from wherever animationSetTime moved it meanwhile. Resuming a clip that is already playing changes nothing. An instance with no clip on its base layer (never played, or stopped) ends the script, as does a node that is not an instance root.

Since: 3.00. See also: animationPause, animationSetTime

Example
function endCutscene()
    for _, npc in ipairs(crowd) do
        animationResume(npc)
    end
    cameraSet(gameCamera)
end

2.2.7. animationSetLayerMask

animationSetLayerMask(node, layer, maskNode)
animationSetLayerMask(node, layer)

Limits a layer to maskNode and everything under it, so the clip on that layer moves only that part of the model and the rest keeps following the layers beneath. maskNode must be one of the instance’s own nodes, found with nodeFind(name, node); the instance root itself does not count. Leaving maskNode out, or passing nil, lifts the limit. The mask stays on the layer across later animationPlayLayer calls. A layer outside 1 to 4 ends the script, and so does a node that is not an instance root or a maskNode that is not part of that instance.

Parameters:

  • node — the instance’s root node.

  • layer — 1 to 4.

  • maskNode — a joint or node of the instance; omitted or nil for the whole model.

Example
-- Aim the upper body at the target while the legs keep walking.
spine = nodeFind("b_Spine02_03", hero)
animationSetLayerMask(hero, 1, spine)
animationPlayLayer(hero, 1, "AimForward", true)

function onHolster()
    animationStop(hero, 1)
    animationSetLayerMask(hero, 1)
end

2.2.8. animationSetLayerWeight

animationSetLayerWeight(node, layer, weight)

How much a layer’s clip shows over what is beneath it, 0 (not at all) to 1 (fully, the default); values outside that range are clamped. The weight belongs to the layer, not the clip, so it survives animationPlayLayer and animationStop on that layer. Change it a little every frame to fade a layer in or out by hand, or let a fade on animationPlayLayer do it once. A layer outside 1 to 4 or a node that is not an instance root ends the script.

Since: 3.00. See also: animationPlayLayer, animationSetLayerMask

Example
-- The limp gets worse as health drops.
function onHealthChanged(health)
    local limp = 1 - health / maxHealth
    animationSetLayerWeight(hero, 1, limp)
end

2.2.9. animationSetTime

animationSetTime(node, seconds)

Jumps the base layer’s clip to a time in its own seconds; negative values become 0. The pose updates at once whether or not the clip is playing, so a paused instance can be scrubbed to an exact frame, and a playing one continues from the new time. Any crossfade in progress on the base layer is cut short. An instance with no clip on its base layer ends the script, as does a node that is not an instance root.

Example
-- A door whose opening clip follows a lever the player drags.
animationPlay(door, "Open", false)
animationPause(door)

function onLeverMoved(fraction)
    animationSetTime(door, fraction * doorClipLength)
end

2.2.10. animationStop

animationStop(node)
animationStop(node, layer)

Stops and forgets every clip on the instance, or only the clip on one layer above the base (1 to 4); the base layer alone cannot be stopped without the layers above it. The nodes keep their last pose, which a following animationPlay with a fade eases out of. After stopping everything, animationResume and animationSetTime end the script until something is played again. Layer weights and masks are kept. A layer outside 1 to 4 or a node that is not an instance root ends the script.

Example
-- Hand the body to the physics ragdoll: freeze the pose, then let it fall.
function onKilled()
    animationStop(hero)
    ragdollActivate(hero)
end

-- The wave on layer 2 is done; the walk beneath it carries on.
function onWaveFinished()
    animationStop(hero, 2)
end

2.3. Bezel

Cabinet artwork and the arcade scoreboard that goes with it. mainBezelLoaded asks about the artwork --bezel loaded; the scoreBezel family drives the score panel, an RmlUi document the engine ships and a game may replace with its own copy, scoreBezel.rml beside its script. Every call here is a Hypseus Singe extension, kept so its games run unchanged, and every one of them is described from the player’s side in Bezels.

The panel starts switched off, as it does in Hypseus, and only a game turns it on. Values given to it are remembered whether it is showing or not, so a game may set them before it enables the panel. Each readout has the number of digits Hypseus’s scoreboard has — six for a score, two for the credits, one for a life count — and a value is shown right justified in them with leading zeros; a score of more than six digits shows its last six. Hypseus’s negative values are understood too: -2 lights a dash in every digit, -4 an H and -5 an A, and -1, -3 and any other negative number light nothing.

2.3.1. mainBezelLoaded

loaded, id = mainBezelLoaded()

Hypseus extension. Whether --bezel loaded cabinet artwork, and the identifier of the file it loaded. The identifier is the 64 bit FNV-1a hash of the file’s bytes written out as a decimal string, which is what Hypseus reports, so a game that recognizes a particular bezel by its number recognizes the same file here. With no artwork loaded the answers are false and "0".

Returns: boolean, and the identifier as a string.

Since: 3.00, as a Hypseus Singe extension. See also: setOverlayOnTop, Bezels

Example
-- Only draw the sprite frame when the player has no artwork of their own.
local loaded, id = mainBezelLoaded()
if not loaded then
    spriteDraw(frameSprite, 0, 0)
end

2.3.2. scoreBezelClear

scoreBezelClear()

Hypseus extension. Blanks every readout on the score panel: the credits, both scores and both life counts show nothing at all, leaving only the dim digits behind them. The values are not forgotten, but the next scoreBezelCredits, scoreBezelScore or scoreBezelLives lights the panel again with whatever it is then holding. Safe to call with the panel switched off.

Since: 3.00, as a Hypseus Singe extension. See also: scoreBezelEnable

2.3.3. scoreBezelCredits

scoreBezelCredits(credits)

Hypseus extension. Sets the credit readout, which has two digits. Also lights a panel that scoreBezelClear blanked.

Parameters:

  • credits — integer; the last two digits are shown.

Since: 3.00, as a Hypseus Singe extension. See also: scoreBezelScore

2.3.4. scoreBezelEnable

scoreBezelEnable(enabled)
scoreBezelEnable(enabled, type)

Hypseus extension. Shows or hides the score panel. The first true builds it from the game’s own scoreBezel.rml beside its script when there is one, or else from Singe/scoreBezel.rml; hiding and showing it again after that costs nothing and keeps its values. It starts hidden, which is how Hypseus ships as well, so a game that never calls this behaves exactly as it did before — and should ask scoreBezelGetState before assuming it has one.

Hypseus’s type chooses among its five scoreboard backends. Singe has one, an RmlUi document, so the argument is checked and ignored. A machine with no GPU has no GUIs at all; there the panel cannot be built, scoreBezelGetState keeps answering false, and a warning is printed once. A non-boolean first argument aborts the script.

Parameters:

  • enabled — boolean.

  • type — integer, accepted and ignored.

Since: 3.00, as a Hypseus Singe extension. See also: scoreBezelGetState, Bezels

Example
-- The engine's panel when there is one, sprites when there is not.
scoreBezelEnable(true, 0)
if scoreBezelGetState() then
    scoreBezelTwinScoreOn(twoPlayer)
    scoreBezelCredits(credits)
else
    drawSpriteScoreboard()
end

2.3.5. scoreBezelGetState

state = scoreBezelGetState()

Hypseus extension. Whether the score panel is showing. Every Hypseus game asks this before using the panel and draws its own scoreboard with sprites when the answer is false, which is the right fallback and not a failure.

Returns: boolean.

Since: 3.00, as a Hypseus Singe extension. See also: scoreBezelEnable

2.3.6. scoreBezelLives

scoreBezelLives(player, lives)

Hypseus extension. Sets a player’s life readout, which has one digit. player is 1 or 2; any other number is ignored, and so is 2 until scoreBezelTwinScoreOn(true) has put the second player’s readouts on the panel. Also lights a panel that scoreBezelClear blanked.

Parameters:

  • player — 1 or 2.

  • lives — integer; the last digit is shown.

Since: 3.00, as a Hypseus Singe extension. See also: scoreBezelScore

2.3.7. scoreBezelScore

scoreBezelScore(player, score)

Hypseus extension. Sets a player’s score readout, which has six digits. player is 1 or 2, with the same rule for 2 as scoreBezelLives. Also lights a panel that scoreBezelClear blanked.

Parameters:

  • player — 1 or 2.

  • score — integer; the last six digits are shown.

Since: 3.00, as a Hypseus Singe extension. See also: scoreBezelLives

Example
function addScore(points)
    score = score + points
    if scoreBezelGetState() then
        scoreBezelScore(1, score)
    end
end

2.3.8. scoreBezelTwinScoreOn

scoreBezelTwinScoreOn(enabled)

Hypseus extension. Puts the second player’s score and life readouts on the panel, or takes them off again and leaves the room to the other two. Switching them off also blanks the panel, exactly as it does in Hypseus, so follow it with a value if the first player’s readouts should stay lit. While they are off, scoreBezelScore(2, …​) and scoreBezelLives(2, …​) do nothing. A non-boolean argument aborts the script.

Parameters:

  • enabled — boolean.

Since: 3.00, as a Hypseus Singe extension. See also: scoreBezelScore

2.4. Body

A body gives a scene node a place in the physics world. There is one body per node, addressed by the node handle: a static body stays where the node was when the body was made, a kinematic body follows its node each step and pushes without being pushed, and a dynamic body is moved by the simulation and drives its node. Sizes, positions and velocities are in world units (meters in a 3D scene, overlay pixels in a 2D world), masses in kilograms, and time in seconds. Every call here ends the script when the node has no body; a call that only makes sense for one kind of body (a force on a static body, say) is ignored on the others, except bodySetMass, which raises. See Physics in Game Development for how bodies, nodes and the frame fit together.

2.4.1. bodyNew

bodyNew(node, type, shape)
bodyNew(node, type, shape, a)
bodyNew(node, type, shape, a, b)
bodyNew(node, type, shape, a, b, c)

Gives the node a body of the given type, placed where the node is in the world right now (its parents included), with a collision shape sized by a, b and c in world units and scaled by the node’s world scale. A second call on the same node replaces the first, and a node that had a player loses it. A dynamic body’s mass comes from its shape’s volume at the density of water, so set bodySetMass on anything meant to feel light. Changing the node’s scale later does not resize the body. Ends the script for an unknown type or shape, when physics is not available on this machine, when the world already holds 4096 bodies, or when the shape cannot be built (a dynamic SHAPE_MESH, or a hull with no mesh under the node).

Parameters:

  • type — BODY_STATIC, BODY_DYNAMIC or BODY_KINEMATIC.

  • shape — SHAPE_BOX (a, b, c are width, height and depth), SHAPE_SPHERE (a is the radius), SHAPE_CAPSULE or SHAPE_CYLINDER (a is the radius, b the total height along Y, caps included), SHAPE_HULL (a convex hull of the node’s mesh and everything under it, no sizes), or SHAPE_MESH (the exact triangles, static and kinematic bodies only; a heightmap mesh becomes a height field).

  • a, b, c — the sizes the shape needs; missing ones are 0 and any size is raised to at least 0.001.

Notes: A sphere is scaled by the node’s largest scale axis, a capsule or cylinder radius by the larger of X and Z. A capsule shorter than twice its radius is a sphere with a sliver in the middle.

Example
-- A light crate and a duck model as a hull, dropped onto the floor.
crate = nodeNew()
nodeSetMesh(crate, meshBox(0.6, 0.6, 0.6), wood)
nodeSetPosition(crate, -1, 1, 0)
bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.6, 0.6, 0.6)
bodySetMass(crate, 5)
duck = modelInstance(modelLoad(DIR .. "Models/Duck.glb"))
nodeSetPosition(duck, 3, 2, 0)
bodyNew(duck, BODY_DYNAMIC, SHAPE_HULL)

2.4.2. bodyApplyForce

bodyApplyForce(node, fx, fy, fz)
bodyApplyForce(node, fx, fy, fz, px, py, pz)

Adds a force, in newtons, to a dynamic body for the steps of this frame only; call it every frame to keep pushing. Without a point the force acts through the center of mass and only moves the body; with a world point (px, py, pz) it also spins the body about its center. A force accelerates by force divided by mass, so size it to bodySetMass. Static and kinematic bodies ignore it.

Parameters:

  • fx, fy, fz — the force in newtons along each world axis.

  • px, py, pz — optional world point the force acts at; omit for the center of mass.

Since: 3.00. See also: bodyApplyImpulse, bodySetMass

Example
-- A fan blows the balloon across the room while the switch is on.
function onOverlayUpdate()
    if fanOn then
        local bx, by, bz = nodeGetPosition(balloon)
        if bx < fanReach then
            bodyApplyForce(balloon, 2.5, 0.4, 0)
        end
    end
    return OVERLAY_NOT_UPDATED
end

2.4.3. bodyApplyImpulse

bodyApplyImpulse(node, ix, iy, iz)
bodyApplyImpulse(node, ix, iy, iz, px, py, pz)

Changes a dynamic body’s momentum at once: an impulse of mass times speed adds that speed. Without a point it acts through the center of mass; with a world point (px, py, pz) it also spins the body, so hitting a crate near its top tips it over. This is the call for a hit, a kick, an explosion or a launch, where bodyApplyForce is for a push that lasts. Static and kinematic bodies ignore it.

Parameters:

  • ix, iy, iz — the impulse in kilogram meters per second along each world axis.

  • px, py, pz — optional world point the impulse acts at; omit for the center of mass.

Since: 3.00. See also: bodyApplyForce, bodySetVelocity, physicsRaycast

Example
-- Flick whatever the mouse is over straight up, at the point it was hit.
local mx, my = mouseGetPosition(0)
local ox, oy, oz = sceneUnproject(mx, my, 0)
local fx, fy, fz = sceneUnproject(mx, my, 10)
local hit, hx, hy, hz = physicsRaycast(ox, oy, oz, fx - ox, fy - oy, fz - oz)
if hit and hit ~= floor then
    bodyApplyImpulse(hit, 0, 3, 0, hx, hy, hz)
end

2.4.4. bodyDelete

bodyDelete(node)

Removes the body from the world; the node and its mesh stay where they are. Every joint attached to the body, and any vehicle built on it, goes with it. Deleting the node removes its body too, so this is only needed to keep a node without its body. Ends the script when the node has no body.

Since: 3.00. See also: bodyNew, bodySetEnabled, jointDelete

Example
-- A collected coin stops being solid and floats up as a plain node.
function onTrigger(trigger, other, entered)
    if trigger == coin and other == hero and entered then
        bodyDelete(coin)
        collected = collected + 1
        coinRising = true
    end
end

2.4.5. bodyGetAngularVelocity

x, y, z = bodyGetAngularVelocity(node)

How fast the body is spinning about each world axis, in radians per second, as of the last step. A static body reports zero. Useful for a wheel’s sound pitch or a spin counter.

Returns: Three numbers, radians per second about X, Y and Z.

Since: 3.00. See also: bodySetAngularVelocity, bodyGetVelocity

Example
-- The roulette wheel has stopped when it barely turns.
function onOverlayUpdate()
    local _, spin = bodyGetAngularVelocity(wheel)
    if spinning and math.abs(spin) < 0.05 then
        spinning = false
        announceWinner(pocketUnder(ball))
    end
    return OVERLAY_NOT_UPDATED
end

2.4.6. bodyGetVelocity

x, y, z = bodyGetVelocity(node)

How fast the body is moving along each world axis, in world units per second, as of the last step. A static body reports zero; a kinematic body reports the velocity its node’s movement implied.

Returns: Three numbers, units per second along X, Y and Z.

Since: 3.00. See also: bodySetVelocity, bodyGetAngularVelocity

Example
-- Play a whoosh when the ball is really moving.
function onOverlayUpdate()
    local vx, vy, vz = bodyGetVelocity(ball)
    local speed = math.sqrt(vx * vx + vy * vy + vz * vz)
    if speed > 8 and not whooshing then
        soundPlay(whoosh)
        whooshing = true
    elseif speed < 2 then
        whooshing = false
    end
    return OVERLAY_NOT_UPDATED
end

2.4.7. bodyIsResting

resting = bodyIsResting(node)

Whether the simulation has put the body to sleep because it stopped moving. Static bodies and bodies taken out of the world with bodySetEnabled count as resting. A resting body wakes on its own when something touches it or when a velocity, force or impulse is applied.

Returns: Boolean.

Since: 3.00. See also: bodySetEnabled, bodySetVelocity

Example
-- The round ends once every pin has settled.
function onOverlayUpdate()
    local settled = true
    for _, pin in ipairs(pins) do
        settled = settled and bodyIsResting(pin)
    end
    if settled then
        scoreFrame()
    end
    return OVERLAY_NOT_UPDATED
end

2.4.8. bodySetAngularVelocity

bodySetAngularVelocity(node, x, y, z)

Sets the spin about each world axis, in radians per second, and wakes the body. Static bodies ignore it. A kinematic body’s spin is overwritten from its node at the next step, so the call only lasts for dynamic bodies.

Since: 3.00. See also: bodyGetAngularVelocity, bodySetVelocity

Example
-- Toss the coin: up, and spinning end over end.
function tossCoin()
    nodeSetPosition(coin, 0, 1.2, 0)
    bodySetVelocity(coin, 0, 4, 0)
    bodySetAngularVelocity(coin, 25, 0, 0)
    tossed = true
end

2.4.9. bodySetBounce

bodySetBounce(node, bounce)

Sets the body’s restitution, from 0 (stops dead) to 1 (bounces back with everything it arrived with); values outside that range are clamped. The default is 0.1. The two touching bodies' values combine, so a lively ball on a dead floor still bounces.

Since: 3.00. See also: bodySetFriction, bodyNew

Example
-- A rubber ball dropped onto the scene.
ball = nodeNew()
nodeSetMesh(ball, meshSphere(0.3, 32), blue)
nodeSetPosition(ball, 0, 3, 0)
bodyNew(ball, BODY_DYNAMIC, SHAPE_SPHERE, 0.3)
bodySetMass(ball, 0.5)
bodySetBounce(ball, 0.7)

2.4.10. bodySetBuoyancy

bodySetBuoyancy(node, factor)

How the body floats when it is inside a water volume: 1 is neutral, more floats higher, less sinks, and 0 is a stone. The default is 1.2, which floats gently. The factor multiplies the water’s own density from bodySetWater, and negative values are clamped to 0. Only dynamic bodies are moved by water, but the value may be set on any body.

Since: 3.00. See also: bodySetWater, bodySetCurrent

Example
-- A crate that rides high, an anchor that goes down, a ball that bobs.
bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.8, 0.8, 0.8)
bodySetMass(crate, 20)
bodySetBuoyancy(crate, 1.6)
bodyNew(anchor, BODY_DYNAMIC, SHAPE_BOX, 0.5, 0.5, 0.5)
bodySetMass(anchor, 200)
bodySetBuoyancy(anchor, 0.3)
bodyNew(ball, BODY_DYNAMIC, SHAPE_SPHERE, 0.4)
bodySetBuoyancy(ball, 2.0)

2.4.11. bodySetCurrent

bodySetCurrent(node, x, y, z)

Sets the flow inside a water volume, in world units per second along each world axis; dynamic bodies floating in it drift with the flow and a swimming player is carried by it. The default is no flow. Set it on the node that bodySetWater was called on; on any other body it is stored and does nothing.

Since: 3.00. See also: bodySetWater, bodySetBuoyancy

Example
-- A river that carries anything dropped in it downstream.
river = nodeNew()
nodeSetMesh(river, meshBox(6, 3, 12), water)
nodeSetPosition(river, 10, -1.5, 0)
bodyNew(river, BODY_STATIC, SHAPE_BOX, 6, 3, 12)
bodySetWater(river, 1.0, 0.8, 0.2)
bodySetCurrent(river, 0, 0, 2.5)

2.4.12. bodySetEnabled

bodySetEnabled(node, enabled)

Takes the body out of the world with false: it stops colliding, stops moving, no longer drives or follows its node, and counts as resting. true puts it back where it is, awake. The body keeps its shape, mass and settings, so this is cheaper than deleting and remaking it for something that comes and goes.

Since: 3.00. See also: bodyIsResting, bodyDelete

Example
-- The drawbridge is solid only while it is down.
function lowerBridge()
    animationPlay(bridge, "Lower", false)
    bodySetEnabled(bridgeDeck, true)
end

function raiseBridge()
    animationPlay(bridge, "Raise", false)
    bodySetEnabled(bridgeDeck, false)
end

2.4.13. bodySetFriction

bodySetFriction(node, friction)

Sets the surface friction: 0 is ice, 0.5 (the default) is ordinary, higher values grip more. Negative values are clamped to 0. The two touching bodies' values combine, so a slippery floor needs a low value on the floor, not on everything that walks on it.

Since: 3.00. See also: bodySetBounce, bodyNew

Example
-- A frozen pond in the middle of the level.
pond = nodeNew()
nodeSetMesh(pond, meshBox(6, 0.1, 6), ice)
nodeSetPosition(pond, 8, -1.95, 0)
bodyNew(pond, BODY_STATIC, SHAPE_BOX, 6, 0.1, 6)
bodySetFriction(pond, 0.02)

2.4.14. bodySetMass

bodySetMass(node, kilograms)

Rescales a dynamic body’s mass and, with it, its inertia. Do this for anything meant to feel light or heavy: the default is the shape’s volume at the density of water, so a door-sized box weighs about 140 kilograms and a nudge will not move it. Forces and impulses scale with mass, so set the mass before tuning them. Ends the script when the body is not dynamic or the mass is not positive.

Since: 3.00. See also: bodyNew, bodyApplyImpulse, playerSetPush

Example
-- A crate the hero can shove and an anvil nobody can.
bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.6, 0.6, 0.6)
bodySetMass(crate, 5)
bodyNew(anvil, BODY_DYNAMIC, SHAPE_BOX, 0.5, 0.3, 0.3)
bodySetMass(anvil, 200)

2.4.15. bodySetTrigger

bodySetTrigger(node, trigger)

Makes the body a trigger with true: it pushes nothing and stops nothing, but onTrigger reports each body or player that enters and leaves it. false makes it solid again: whatever was inside it is forgotten without a leave, while a trigger the body itself stands in goes on reporting it. A trigger is usually a static box or sphere placed over a doorway, a finish line or a danger zone. Rays from physicsRaycast hit triggers like any other body.

Notes: A player is reported inside a trigger when their bounding boxes overlap, so a round trigger is a square one for players.

Since: 3.00. See also: onTrigger, bodyNew, bodySetWater

Example
-- A finish line across the track.
line = nodeNew()
nodeSetPosition(line, 0, 0, -20)
bodyNew(line, BODY_STATIC, SHAPE_BOX, 6, 3, 0.5)
bodySetTrigger(line, true)

function onTrigger(trigger, other, entered)
    if trigger == line and other == car and entered then
        lapDone()
    end
end

2.4.16. bodySetVelocity

bodySetVelocity(node, x, y, z)

Sets the body’s velocity along each world axis, in world units per second, and wakes it. This replaces whatever speed the body had, where bodyApplyImpulse adds to it. Static bodies ignore it, and a kinematic body’s velocity is overwritten from its node’s movement at the next step.

Example
-- Serve the ball toward whichever side lost the last point.
function serve()
    nodeSetPosition(ball, 0, 0.5, 0)
    bodyNew(ball, BODY_DYNAMIC, SHAPE_SPHERE, 0.15)
    bodySetMass(ball, 0.1)
    local dir = (lastWinner == 1) and -1 or 1
    bodySetVelocity(ball, 4 * dir, 2, (math.random() - 0.5) * 2)
end

2.4.17. bodySetWater

bodySetWater(node, density)
bodySetWater(node, density, linearDrag)
bodySetWater(node, density, linearDrag, angularDrag)

Fills a static body with water and makes it a trigger: the top of its shape is the surface, and every dynamic body inside floats, sinks or rolls by buoyancy against that surface (the submerged part of the shape counts, so a tilted crate rights itself), slowed by the drags. A player whose middle is below the surface swims. Because the volume is a trigger, onTrigger fires on the way in and out. The water is not drawn: give the node a blended material, or none. Ends the script when the body is not static.

Parameters:

  • density — a multiplier, 1 for water; each body’s own bodySetBuoyancy scales it. Negative values are clamped to 0.

  • linearDrag — how quickly the water slows movement through it; default 0.5.

  • angularDrag — how quickly it slows spinning; default 0.1.

Notes: Players and boats see at most eight water volumes; more than that still float bodies but are not swum in.

Example
-- A pool cut into the deck; its top, at Y = 0, is the surface.
pool = nodeNew()
nodeSetMesh(pool, meshBox(8, 3, 12), water)
nodeSetPosition(pool, 0, -1.5, 0)
bodyNew(pool, BODY_STATIC, SHAPE_BOX, 8, 3, 12)
bodySetWater(pool, 1.0, 0.6, 0.2)

function onTrigger(trigger, other, entered)
    if trigger == pool and entered then
        soundPlay(splash)
    end
end

2.5. Camera

The camera is a node like any other: place it with nodeSetPosition, aim it with nodeLookAt, parent it to a moving object for a chase view, and name it with cameraSet. It looks down its own -Z. Without a camera node the scene is viewed from (0, 0, 5) looking at the origin. The projection is set separately and applies to whichever node is the camera: perspective with a 60 degree vertical field of view from 0.1 to 1000 units by default, or orthographic with cameraSetOrthographic. Rendered views (viewNew) share the projection but look from their own nodes. See 3D Scenes.

2.5.1. cameraSet

cameraSet(node)
cameraSet(-1)

Makes a node the camera: the scene is drawn from its world position looking down its own -Z, so its parents' movement and rotation count. Any node will do, including one that also carries a mesh or a light, and switching cameras is one call. -1 restores the default view from (0, 0, 5) looking at the origin. Deleting the camera node also falls back to the default view. Ends the script for a node handle that is not valid.

Example
-- A chase camera behind the player's car, and a fixed one for the replay.
chaseCamera = nodeNew(car)
nodeSetPosition(chaseCamera, 0, 2, 6)
nodeLookAt(chaseCamera, nodeGetWorldPosition(car))
cameraSet(chaseCamera)

function onReplayStart()
    replayCamera = nodeNew()
    nodeSetPosition(replayCamera, 30, 12, 30)
    nodeLookAt(replayCamera, 0, 0, 0)
    cameraSet(replayCamera)
end

2.5.2. cameraSetOrthographic

cameraSetOrthographic(height, near, far)

Switches to a parallel projection showing height world units top to bottom, the width following the layer’s aspect ratio, from near to far in front of the camera. Distance does not shrink things, which suits diagrams, isometric and side-on views, and HUD-like scenes. The setting applies to the current and any later camera node until cameraSetPerspective is called. A directional light’s shadow uses a single map under an orthographic camera, whatever sceneSetShadowCascades says.

Parameters:

  • height — the visible height, in world units.

  • near — the closest distance drawn, in world units in front of the camera.

  • far — the farthest distance drawn.

Example
-- An isometric view of the board:  12 units tall, from high up and to the side.
boardCamera = nodeNew()
nodeSetPosition(boardCamera, 20, 20, 20)
nodeLookAt(boardCamera, 0, 0, 0)
cameraSet(boardCamera)
cameraSetOrthographic(12, 1, 100)

2.5.3. cameraSetPerspective

cameraSetPerspective(fov, near, far)

Switches to the usual perspective projection, the default. fov is the vertical field of view in degrees (default 60); near and far (defaults 0.1 and 1000) bound what is drawn, in world units in front of the camera. Depth precision is spread between the two, so keep near as large as the scene allows and far no larger than needed: 0.05 to 100 for a room, 0.1 to 400 for a landscape. The setting applies to the current and any later camera node, and to rendered views.

Parameters:

  • fov — vertical field of view in degrees; a wide 70 feels fast, a narrow 40 feels like a long lens.

  • near — the closest distance drawn.

  • far — the farthest distance drawn.

Since: 3.00. See also: cameraSetOrthographic, cameraSet, sceneProject

Example
-- A tighter lens for the cockpit view, the default for the outside.
function setView(inside)
    if inside then
        cameraSet(cockpitCamera)
        cameraSetPerspective(45, 0.05, 300)
    else
        cameraSet(chaseCamera)
        cameraSetPerspective(60, 0.1, 400)
    end
end

2.6. Collide

Whether two flat things touch. Jolt answers this in three dimensions for bodies (see Body); these answer it for the overlay, which is where a light gun’s hitboxes and a 2D game’s everything live.

They are plain functions: no handles, no state, nothing to create or free, and nothing to update each frame. Coordinates are whatever you are already drawing in — overlay pixels, usually. A rectangle is a corner and a size, the way every drawing call in the engine takes one. Touching exactly at an edge counts as touching, and a rectangle with no width or height touches nothing at all.

None of these move anything. When you want to know not just whether two things met but where the mover ends up — sliding along a wall rather than stopping dead in it — require("bump") and let it do that; it is bundled for exactly that reason.

2.6.1. collideCircles

touching = collideCircles(x1, y1, radius1, x2, y2, radius2)

Whether two circles overlap. Cheaper than it looks: nothing takes a square root to answer a yes or no question.

Parameters:

  • x1, y1, radius1 — numbers; the first circle.

  • x2, y2, radius2 — numbers; the second.

Returns: true or false.

Since: 3.00. See also: collideRectCircle

2.6.2. collidePointCircle

inside = collidePointCircle(pointX, pointY, x, y, radius)

Whether a point falls within a circle. The edge counts as inside.

Parameters:

  • pointX, pointY — numbers; the point.

  • x, y, radius — numbers; the circle.

Returns: true or false.

Since: 3.00.

2.6.3. collidePointPolygon

inside = collidePointPolygon(pointX, pointY, points)

Whether a point falls within a polygon of any shape, concave ones included. The table is a flat list of x, y, x, y — the shape a hitbox already has in most games — and the winding does not matter. Fewer than three corners contains nothing. At most 256 corners.

Parameters:

  • pointX, pointY — numbers; the point.

  • points — table; an even number of numbers, x and y in turn.

Returns: true or false.

Since: 3.00.

Example
-- Did the shot land on the dragon, whose outline is not a rectangle?
local dragon = { 120,40, 200,60, 210,140, 150,180, 100,120 }

function onInputPressed(key)
    if key == SWITCH_BUTTON1 then
        local x, y = mouseGetPosition(0)
        if collidePointPolygon(x, y, dragon) then
            hit()
        end
    end
end

2.6.4. collidePointRect

inside = collidePointRect(pointX, pointY, x, y, width, height)

Whether a point falls within a rectangle. The edge counts as inside.

Parameters:

  • pointX, pointY — numbers; the point.

  • x, y, width, height — numbers; the rectangle.

Returns: true or false.

Since: 3.00.

Example
-- A hitbox the size of the sprite it belongs to.
local x, y = mouseGetPosition(0)
if collidePointRect(x, y, enemyX, enemyY, spriteGetWidth(enemy), spriteGetHeight(enemy)) then
    kill(enemy)
end

2.6.5. collideRectCircle

touching = collideRectCircle(x, y, width, height, circleX, circleY, radius)

Whether a rectangle and a circle overlap, by finding the rectangle’s nearest point to the circle’s center.

Parameters:

  • x, y, width, height — numbers; the rectangle.

  • circleX, circleY, radius — numbers; the circle.

Returns: true or false.

Since: 3.00.

2.6.6. collideRects

touching = collideRects(x1, y1, width1, height1, x2, y2, width2, height2)

Whether two rectangles overlap. The one you will reach for most.

Parameters:

  • x1, y1, width1, height1 — numbers; the first rectangle.

  • x2, y2, width2, height2 — numbers; the second.

Returns: true or false.

Since: 3.00. See also: collidePointRect

2.6.7. collideSegments

crossing = collideSegments(ax1, ay1, ax2, ay2, bx1, by1, bx2, by2)

Whether two line segments cross: a shot along a path against a wall, or the step a mover wants to take against the edge it must not pass. Segments lying along one another answer false, because "where do they cross" has no single answer then.

Parameters:

  • ax1, ay1, ax2, ay2 — numbers; the first segment’s ends.

  • bx1, by1, bx2, by2 — numbers; the second’s.

Returns: true or false.

Since: 3.00.

2.7. Color

The foreground and background colors are engine globals rather than per-call arguments: set them with colorForeground and colorBackground, and every later drawing call reads them until they change. The foreground color is used by the overlay* shape primitives and by TrueType text from fontPrint and fontToSprite; the background color is used by overlayClear and by FONT_QUALITY_SHADED text. overlayPrint uses neither. Channels are integers from 0 to 255, clamped into that range, and both colors accept an optional alpha. See the Overlay and Font sections for the calls that consume them.

2.7.1. colorBackground

colorBackground(r, g, b)
colorBackground(r, g, b, a)

Sets the background color: what overlayClear fills the overlay with, and what FONT_QUALITY_SHADED text from fontPrint and fontToSprite paints behind its glyphs. At startup it is transparent black, and alpha defaults to 0 when omitted, so colorBackground(0, 0, 0) followed by overlayClear() makes the overlay invisible again. A partial alpha over black dims the video; 255 hides it. Out-of-range channel values are clamped rather than rejected.

Parameters:

  • r, g, b — red, green, and blue, 0 to 255.

  • a — opacity, 0 (transparent) to 255 (opaque); default 0.

Since: 1.x See also: colorForeground, overlayClear, fontQuality

Example
-- Solid black behind the calibration screen, transparent during play.
function onOverlayUpdate()
    if calibrating then
        colorBackground(0, 0, 0, 255)
    else
        colorBackground(0, 0, 0, 0)
    end
    overlayClear()
    drawHud()
    return OVERLAY_UPDATED
end

2.7.2. colorForeground

colorForeground(r, g, b)
colorForeground(r, g, b, a)

Sets the foreground color used by overlayBox, overlayCircle, overlayEllipse, overlayLine, and overlayPlot, and the text color for fontPrint and fontToSprite. At startup it is opaque white, and alpha defaults to 255 when omitted, the opposite of colorBackground. Sprites and overlayPrint are drawn with their own pixels and are not tinted. Out-of-range channel values are clamped rather than rejected.

Parameters:

  • r, g, b — red, green, and blue, 0 to 255.

  • a — opacity, 0 (transparent) to 255 (opaque); default 255.

Example
-- Score in white, last-life warning in red, both from the same font.
function onOverlayUpdate()
    overlayClear()
    fontSelect(hudFont)
    colorForeground(255, 255, 255)
    fontPrint(8, 8, "Score: " .. score)
    if lives == 1 then
        colorForeground(255, 32, 32)
        fontPrint(8, 32, "LAST LIFE")
    end
    return OVERLAY_UPDATED
end

2.8. Command Line

Three calls report numbers the user chose when Singe was started. They exist so a game can be tuned from the launcher rather than by editing the game. All three are Hypseus Singe extensions, and Singe does nothing with the values itself: the game decides what they mean. The options are described in Command Line Options, and they may also be set in a settings file (see The Settings File).

None of the three changes during a run, so read each one once and keep it.

2.8.1. getFValue

value = getFValue()

Hypseus extension. Returns the number given as --fvalue, or 0 when the option was not used. It is a channel of one number from whoever started Singe to the game, meant for a value a front end wants to vary between launches — a difficulty, a starting credit count, a menu index. The engine only carries it.

The value runs from 0 to 100000 and keeps three decimals, which is what Hypseus keeps, so a game comparing the number sees the same one it saw there.

Returns: number.

Since: 3.00 (Hypseus) See also: ratioGetX, ratioGetY

Example
-- The launcher passes --fvalue 2 for the hard cabinet.
local difficulty = getFValue()
if difficulty == 0 then
    difficulty = 1
end

2.8.2. ratioGetX

factor = ratioGetX()

Hypseus extension. Returns the number given as --xratio, or 0 when the option was not used. Light gun games written for Hypseus read it and stretch their own gun coordinates with it, for a cabinet whose screen is not the shape the video was mastered in — 1.33 maps a 16:9 panel onto 4:3 footage. Singe does not apply it to anything; the game does the arithmetic, exactly as in Hypseus, which is why every game that reads it treats 0 and anything below 1 as 1.

The value runs from 0 to 100 and keeps two decimals, as Hypseus keeps it.

Returns: number.

Since: 3.00 (Hypseus) See also: ratioGetY, getFValue, mouseGetPosition

Example
-- The shape of the gun coordinates this cabinet wants.
local ratioX = ratioGetX()
if ratioX <= 1 then
    ratioX = 1
end
local offsetX = (ratioX - 1) * (overlayGetWidth() / 2)

2.8.3. ratioGetY

factor = ratioGetY()

Hypseus extension. The vertical half of the pair: the number given as --yratio, or 0 when the option was not used. See ratioGetX.

Returns: number.

Since: 3.00 (Hypseus) See also: ratioGetX, getFValue

Example
local ratioY = ratioGetY()
if ratioY <= 1 then
    ratioY = 1
end

2.9. Controller

Singe supports up to four game controllers, indices 0 through 3, opened automatically at startup and whenever one is plugged in or removed; there is no controllerLoad. Analog axes are reported through onControllerMoved (see Engine Callbacks) and polled with controllerGetAxis, in SDL’s raw range of -32768 to 32767. Digital buttons, and each direction of each axis, are switches like keys: they reach onInputPressed and onInputReleased when controls.cfg maps a code from the GAMEPAD_0 through GAMEPAD_3 tables (for example INPUT_ACTION_1 = { GAMEPAD_0.BUTTON_A }), and controllerGetButton polls a button’s live state. SINGE_DEAD_ZONE, from the DEAD_ZONE entry in controls.cfg, is the threshold the engine itself uses before an axis direction counts as a pressed switch; treat axis motion below it as noise. One axis at a time may be given a different threshold with DEAD_ZONES, and the analog triggers a threshold of their own with TRIGGER_THRESHOLD (read back as SINGE_TRIGGER_THRESHOLD); see Dead Zones and Triggers. A device SDL does not recognize as a gamepad is opened as one anyway, through a mapping Singe writes for it, so an arcade encoder or a flight stick appears in these slots like any pad — see Every Device Is a Gamepad.

2.9.1. controllerDoRumble

controllerDoRumble(strength, duration)
controllerDoRumble(controller, strength, duration)

Hypseus extension. Rumbles a controller with both motors at one of four strengths for one of four durations. The two argument form addresses controller 0. A slot with no controller does nothing (Hypseus aborts there, so its games guard with controllerIsValid); a strength or duration outside 1 to 4, or an index outside 0 to 3, aborts the script. A controller without rumble support ignores the call.

Parameters:

  • controller — controller index, 0 through 3.

  • strength — 1 to 4, a quarter to full strength.

  • duration — 1 to 4, giving 150, 300, 600 or 1200 ms.

Since: 3.00, as a Hypseus Singe extension. See also: controllerIsValid, controllerGetButton

Example
-- A short kick on every hit, a long full-strength one when the player dies.
function onHit()
    if controllerIsValid(0) then
        controllerDoRumble(0, 2, 1)
    end
end

function onPlayerDied()
    if controllerIsValid(0) then
        controllerDoRumble(0, 4, 4)
    end
end

2.9.2. controllerGetAxis

value = controllerGetAxis(controller, axis)

Returns the position of an analog axis as the engine last saw it. The value is updated from every axis event, including motion inside the dead zone, and is 0 for a controller that is not connected or an axis that has never moved. Sticks range from -32768 to 32767; triggers rest at 0 and reach 32767 when fully pressed. An index outside 0 to 3, or an axis outside 0 to 5, aborts the script.

Parameters:

  • controller — controller index, 0 through 3.

  • axis — GAMEPAD_AXIS_LEFT_X (0), GAMEPAD_AXIS_LEFT_Y (1), GAMEPAD_AXIS_RIGHT_X (2), GAMEPAD_AXIS_RIGHT_Y (3), GAMEPAD_AXIS_LEFT_TRIGGER (4) or GAMEPAD_AXIS_RIGHT_TRIGGER (5).

Returns: integer, -32768 to 32767.

Since: 2.00 See also: controllerGetButton, onControllerMoved

Example
-- Steer with the left stick, throttle with the right trigger.
function onOverlayUpdate()
    local steer    = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_X)
    local throttle = controllerGetAxis(0, GAMEPAD_AXIS_RIGHT_TRIGGER)
    if math.abs(steer) > SINGE_DEAD_ZONE then
        heading = heading + (steer / 32768) * turnRate
    end
    speed = speed + (throttle / 32767) * acceleration
    drawHud()
    return OVERLAY_UPDATED
end

2.9.3. controllerGetButton

pressed = controllerGetButton(controller, button)

Returns whether a button is held right now, read directly from the controller rather than from the event queue. Use it for hold-to-charge and similar cases where onInputPressed and onInputReleased are awkward. A slot with no controller returns false. The button code must come from the GAMEPAD_N table of the same controller index; a code from another controller’s table, or an axis code, falls outside the button range and aborts the script, as does an index outside 0 to 3.

Parameters:

  • controller — controller index, 0 through 3.

  • button — a BUTTON_* or DPAD_* value from the matching table, such as GAMEPAD_0.BUTTON_A.value.

Returns: boolean.

Example
-- Charge while A is held, fire on release.
function onOverlayUpdate()
    if controllerGetButton(0, GAMEPAD_0.BUTTON_A.value) then
        charge = math.min(charge + 1, chargeMax)
    elseif charge > 0 then
        fireShot(charge)
        charge = 0
    end
    drawChargeBar(charge)
    return OVERLAY_UPDATED
end

2.9.4. controllerGetName

name = controllerGetName(controller)

The name of the device in a controller slot, as SDL reports it, or nil when the slot is empty. A device SDL did not recognize reports its own name through the mapping Singe wrote for it, so a service screen can list an arcade encoder by name as readily as a branded pad. An index outside 0 to 3 aborts the script.

Parameters:

  • controller — controller index, 0 through 3.

Returns: string, or nil.

Since: 3.00 See also: controllerIsValid, mouseGetName

Example
-- A service screen listing what is plugged in.
for slot = 0, 3 do
    if controllerIsValid(slot) then
        fontPrint(20, 20 + slot * 18, string.format("Pad %d:  %s", slot + 1, controllerGetName(slot)))
    else
        fontPrint(20, 20 + slot * 18, string.format("Pad %d:  not connected", slot + 1))
    end
end

2.9.5. controllerGetPadding

padding = controllerGetPadding()

Hypseus extension, always 0 in Singe. Hypseus adds this offset to a switch code that came from a gamepad, so a game can tell which device pressed what and still recover the switch by subtracting it. Singe delivers gamepad input as ordinary mapped switches carrying no such mark, so it answers 0: a game testing for the padded range takes its other branch and reads the switch as it stands.

Returns: an integer, always 0.

Since: 3.00 See also: controllerSetPadding

2.9.6. controllerHowMany

count = controllerHowMany()

Hypseus extension. How many gamepads are open, of the four slots Singe has. Since every joystick Singe can open becomes a gamepad (see Every Device Is a Gamepad), an arcade encoder or a spinner is counted here as well.

The count changes as devices are plugged in and out, so read it when you need it rather than once at startup. It says nothing about which slots are filled: a device may leave slot 0 empty while slot 1 is in use, so controllerIsValid is still the way to ask about a particular slot.

Parameters: none.

Returns: number, 0 to 4.

Since: 3.00, as a Hypseus Singe extension. See also: controllerIsValid, controllerGetName, mouseHowMany

Example
-- Offer two player only when there is something for player two to hold.
local twoPlayer = controllerHowMany() >= 2

2.9.7. controllerIsValid

valid = controllerIsValid(controller)

Hypseus extension. Returns whether a controller is open in the slot right now; controllers come and go with hot plugging, so ask before every controllerDoRumble. An index outside 0 to 3 aborts the script.

Parameters:

  • controller — controller index, 0 through 3.

Returns: boolean.

Since: 3.00, as a Hypseus Singe extension. See also: controllerDoRumble, controllerGetAxis

Example
-- Show the pad hints only when there is a pad to hint about.
function drawAttract()
    if controllerIsValid(0) then
        fontPrint(HINT_X, HINT_Y, "Press A to start")
    else
        fontPrint(HINT_X, HINT_Y, "Press 1 to start")
    end
end

2.9.8. controllerSetPadding

controllerSetPadding(boolean)

Hypseus extension, accepted and ignored. See controllerGetPadding for why the offset it asks for does not exist in Singe. Turning it on without marking the events would be worse than leaving it off, because the game would then subtract an offset from switch codes that never carried one.

Returns: nothing.

Since: 3.00 See also: controllerGetPadding

2.10. Debug

Two calls for seeing what a script is doing: debugPrint writes text, and lineDraw draws a line over the 3D scene for one frame (physicsSetDebug and navDraw draw through the same lines). Printed output goes to the console Singe was started from, so it is visible during development and harmless in a cabinet, where --noconsole silences it. When Singe runs with --trace, every API call including this one is also written with its arguments to trace.txt in the data directory, which is the way to get a permanent record. Command line options are listed in the chapter on running Singe. When printing is not enough, ZeroBrane Studio stops the game at a breakpoint, shows what is in its variables, and steps through it a line at a time.

2.10.1. The Trace Header

Whichever of --program and --trace opened it, trace.txt begins with a block describing the machine and the run, between two rules so it can be pasted whole into a bug report:

----------------------------------------------------------------
Singe:     v3.00
Command:   ./Singe -w -p -d data --screen 2 MyGame
OS:        Linux 6.8.0-124-generic (x86_64)
CPU:       Intel(R) Xeon(R) CPU E5-2680 v4 @ 2.40GHz, 8 cores, 20177 MB
Renderer:  gpu, GPU driver vulkan
Decoder:   hardware vaapi or vdpau where the codec allows, software otherwise
SDL:       built 3.4.16, linked 3.4.16
Settings:  haptic=0 screen=2 volume_vldp=80
Game:      MyGame/MyGame.singe
----------------------------------------------------------------

Renderer is the renderer that was actually created and the GPU backend it chose, or a note that there is no GPU device and 3D is unavailable. Decoder is what will be tried for video on this machine; which decoder a particular video actually got is traced as that video opens, a few lines further down, since a codec may offer no hardware path. Settings lists what the settings file supplied, none when there was none. Every game in a queue gets its own file and its own header.

2.10.2. debugPrint

debugPrint(message)

Prints a line to the console (standard output). Nothing is printed when Singe was started with --noconsole; with --trace the call and its message also land in trace.txt. The argument must be a string or a number; anything else aborts the script, so wrap values in tostring or use string.format. It is cheap enough to leave in shipping code but is not throttled, so a print inside onOverlayUpdate runs every frame.

Parameters:

  • message — the text to print; a number is converted.

Since: 1.x See also: singeGetTicks

Example
-- Log why the shot missed, with the frame it happened on.
function resolveShot(x, y)
    local hit = targetAt(x, y)
    if not hit then
        debugPrint(string.format("miss at %d,%d on frame %d", x, y, discGetFrame()))
        soundPlay(missClip)
        return
    end
    score = score + hit.points
end

2.10.3. lineDraw

lineDraw(x0, y0, z0, x1, y1, z1)
lineDraw(x0, y0, z0, x1, y1, z1, r, g, b)

Draws a straight line between two world-space points over the scene for the current frame only, white unless a color is given. Call it every frame to keep a line on screen, as with the overlay. The line is depth tested against the scene but does not write depth, so it hides behind walls like anything else and never occludes. Nothing is drawn while the scene is disabled. It is meant for seeing what a script is doing (a ray cast, a path, a bounding box); physicsSetDebug and navDraw draw through the same lines.

Parameters:

  • x0, y0, z0 — the start point, in world units.

  • x1, y1, z1 — the end point, in world units.

  • r, g, b — the line color, 0 to 255 per channel, clamped; white when omitted.

Since: 3.00. See also: physicsSetDebug, navDraw, physicsRaycast

Example
-- Show where the turret is aiming and whether the shot would land.
function onOverlayUpdate()
    local tx, ty, tz = nodeGetWorldPosition(turret)
    local hit, hx, hy, hz = physicsRaycast(tx, ty, tz, aimX, aimY, aimZ, 40)
    if hit then
        lineDraw(tx, ty, tz, hx, hy, hz, 255, 255, 0)
    else
        lineDraw(tx, ty, tz, tx + aimX * 40, ty + aimY * 40, tz + aimZ * 40, 120, 120, 120)
    end
    return OVERLAY_UPDATED
end

2.11. Disc

The disc is the main laserdisc video, the one Singe was originally built to emulate. A game has at most one disc, opened at startup from the VIDEO named in games.dat or from --disc / --framefile on the command line; a game that names none runs without a disc (see Games Without a Disc). All disc* functions operate on this single implicit disc and take no handle. Frame numbers are zero based positions in the video file (or in the combined framefile) and are the time reference for every branch decision in a laserdisc game. Without a disc the query functions return 0, discGetState reports DISC_EJECTED, and the transport functions trace and do nothing. Extra clips layered on top of the disc are the job of the Video family.

2.11.1. discAudio

discAudio(channel, enabled)

Turns one channel of the disc’s soundtrack on or off. The channel is set to the configured laserdisc volume (--volume_vldp, default 100) when enabled is true and to 0 when it is false; the other channel is left as it is. Many original titles carried narration or a data track on one channel only, and this is the call that silences it. A channel other than 1 or 2 terminates the script. Without a disc the call does nothing.

Parameters:

  • channel — 1 for the left channel, 2 for the right.

  • enabled — boolean. true restores the channel to the configured laserdisc volume, false silences it.

Example
-- The right channel of this disc carries the arcade's data track.
function startGame()
    discAudio(1, true)
    discAudio(2, false)
    discSkipToFrame(SCENE_FIRST_FRAME)
end

2.11.2. discAudioSuffix

opened = discAudioSuffix(suffix)

Hypseus extension. Switches the disc to a separate audio file beside its video: <base><suffix>.ogg, where the base is the video file’s name without its extension, so movie.m2v with "-es" plays movie-es.ogg. The file is opened at the current frame and playback realigns, as discSetAudioTrack does, keeping the volume, the play state and the track index when the new file has that many tracks. With a frame file every segment switches. An empty suffix restores the default audio: the .ogg beside an .m2v, or the audio inside any other container. Returns true when the file opened; when it is missing the previous audio keeps playing, nothing is remembered, and false comes back (Hypseus leaves silence in that case). The suffix is forgotten when the script reloads. Without a disc the call returns false. Use it for a language menu whose tracks ship as separate files; tracks inside one file are the job of discSetAudioTrack.

Parameters:

  • suffix — string appended to the video’s base name, such as "-es"; "" for the default audio.

Returns: boolean.

Since: 3.00, as a Hypseus Singe extension. See also: discSetAudioTrack, discGetAudioTracks, discAudio

Example
-- Language files ship as movie.ogg, movie-es.ogg and movie-fr.ogg.
languages = { { "English", "" }, { "Spanish", "-es" }, { "French", "-fr" } }

function applyLanguage(index)
    if not discAudioSuffix(languages[index][2]) then
        discAudioSuffix("")
        index = 1
    end
    settings.language = index
end

2.11.3. discChangeSpeed

discChangeSpeed(...)

Does nothing. Real laserdisc players could run at other than 1x; Singe’s software player cannot, so the call accepts any arguments, logs a trace line and returns. It is kept so that pre-2.00 scripts load without edits.

Notes:

Unimplemented. Retained for backward compatibility only. There is no replacement; playback speed is fixed at the video file’s frame rate.

Since: 1.x See also: discPlay, discSkipToFrame

Example
-- Old scripts sometimes bracketed a slow-motion replay with speed changes.
-- The calls are harmless today, but the replay plays at normal speed.
discChangeSpeed(0.5)
discSkipToFrame(REPLAY_FIRST_FRAME)
discChangeSpeed(1)

2.11.4. discGetAudioTrack

track = discGetAudioTrack()

Returns the zero based index of the audio track the disc is currently playing. At startup the engine selects the track named by --audio or the AUDIO_TRACK entry in games.dat (default 0) when the disc has that many tracks. Returns 0 without a disc.

Returns: integer track index.

Example
-- Cycle to the next dub each time the player presses the language key.
function onInputPressed(what)
    if what == SWITCH_BUTTON2 then
        local next = (discGetAudioTrack() + 1) % discGetAudioTracks()
        discSetAudioTrack(next)
        languageLabel = discGetLanguageDescription(discGetLanguage(next))
    end
end

2.11.5. discGetAudioTracks

count = discGetAudioTracks()

Returns how many audio streams the disc’s video file contains. Multiple streams are typically alternate language dubs. A silent video reports 0, and so does a game without a disc, so guard loops and modulo arithmetic against zero.

Returns: integer count, 0 or more.

Example
-- Build a language-select menu from the disc's audio tracks.
languages = {}
for track = 0, discGetAudioTracks() - 1 do
    local code = discGetLanguage(track)
    local name = discGetLanguageDescription(code)
    table.insert(languages, { track = track, label = name })
end

2.11.6. discGetSubtitleLanguage

language = discGetSubtitleLanguage(track)

The language a subtitle track inside the disc’s own container is labeled with, as the ISO 639 code the file carries (eng, fra, spa). A track the file labels with nothing answers an empty string, which is not an error — plenty of files label nothing.

Parameters:

  • track — number; 0 to discGetSubtitleTracks() - 1.

Returns: a string.

Since: 3.00. See also: discGetSubtitleTracks, srtLoadTrack

2.11.7. discGetSubtitleTracks

count = discGetSubtitleTracks()

How many subtitle tracks the disc’s own container holds. 0 with no disc, and 0 for a disc whose subtitles ship as a separate .srt — which is the usual arrangement, and what srtLoad is for.

Tracks that hold pictures rather than words (the DVD and Blu-ray kinds, VobSub and PGS) are counted here so the numbering matches what any other player shows, but srtLoadTrack cannot read them: there is nothing to read, only bitmaps of the words.

Parameters:

  • None.

Returns: a number.

Since: 3.00. See also: srtLoadTrack, discGetSubtitleLanguage

Example
-- Offer whatever languages the disc itself carries.
for track = 0, discGetSubtitleTracks() - 1 do
    languages[#languages + 1] = { track = track, code = discGetSubtitleLanguage(track) }
end

2.11.8. discGetFrame

frame = discGetFrame()

Returns the frame the disc is currently showing. With a framefile the number is the position in the combined sequence, so segment boundaries are invisible to the script. Returns 0 while the disc is stopped and without a disc. Poll it from onOverlayUpdate to react to the video reaching a decision point.

Returns: integer frame number.

Since: 1.x See also: discSearch, discSkipToFrame, discGetState

Example
-- Loop the attract sequence and show a prompt during the duck window.
function onOverlayUpdate()
    local frame = discGetFrame()
    if frame >= ATTRACT_LAST_FRAME then
        discSkipToFrame(ATTRACT_FIRST_FRAME)
    elseif frame >= DUCK_FIRST_FRAME and frame <= DUCK_LAST_FRAME then
        drawPrompt("DUCK")
    end
    return OVERLAY_UPDATED
end

2.11.9. discGetFrameCount

frames = discGetFrameCount()

The number of frames on the disc, which is one past the highest frame discSearch will find. A framefile answers for the whole disc rather than for the segment playing, so the count does not change as segments come and go. Without a disc it answers 0.

Returns: integer frame count, 0 without a disc.

Since: 3.00. See also: discGetFrame, discSearch

Example
-- Seek to the middle of the disc, wherever that is.
discSearch(math.floor(discGetFrameCount() / 2))

2.11.10. discGetHeight

height = discGetHeight()

Returns the height of the disc’s video in pixels. Without a disc it returns the canvas height (CANVAS_Y in games.dat or --canvas, default 480), so it is always the size of the background the overlay is stretched over. Pair it with discGetWidth to give the overlay the same resolution as the video.

Returns: integer height in pixels.

Example
-- Draw at native disc resolution so pixel checks and drawing share one grid.
overlaySetResolution(discGetWidth(), discGetHeight())
crosshairLimitX = discGetWidth() - 1
crosshairLimitY = discGetHeight() - 1

2.11.11. discGetLanguage

code = discGetLanguage(track)

Returns the language tag stored in the video file for one of the disc’s audio tracks. The tag is a three letter ISO 639 code such as "eng" or "jpn". Tracks without a three letter tag return "unk", and so does every track when there is no disc. With a disc, a track outside 0 to discGetAudioTracks() - 1 terminates the script.

Returns: string language code.

Example
-- Prefer the Japanese dub when the disc carries one.
for track = 0, discGetAudioTracks() - 1 do
    if discGetLanguage(track) == "jpn" then
        discSetAudioTrack(track)
        break
    end
end

2.11.12. discGetState

state = discGetState()

Returns the transport state of the disc as one of the DISC_* constants. A game without a disc reports DISC_EJECTED; after discStop the disc reports DISC_STOPPED until the next discPlay, discSearch or discSkipToFrame; otherwise the state is DISC_PLAYING while the video advances and DISC_PAUSED when it does not. There is no separate searching state; a disc that is seeking reports DISC_PAUSED or DISC_PLAYING according to what was requested.

Returns: one of the following constants, defined by the engine and available to every script.

Constant Value Meaning

DISC_STOPPED

2

Stopped (discStop was called)

DISC_PLAYING

3

Playing

DISC_PAUSED

4

Paused

DISC_EJECTED

5

The game has no disc (see Games Without a Disc)

Since: 1.x (RDG) See also: discPlay, discPause, discStop

Example
-- The pause key must not resume a freeze the story script asked for.
function onInputPressed(what)
    if what == SWITCH_PAUSE then
        if discGetState() == DISC_PAUSED and not storyPaused then
            discPlay()
        elseif discGetState() == DISC_PLAYING then
            discPause()
        end
    end
end

2.11.13. discGetWidth

width = discGetWidth()

Returns the width of the disc’s video in pixels. Without a disc it returns the canvas width (CANVAS_X in games.dat or --canvas, default 720). Together with discGetHeight this is the size the overlay is scaled onto, which is why the shipped menu passes both to overlaySetResolution.

Returns: integer width in pixels.

Example
-- Center a title sprite on whatever the disc's width happens to be.
overlaySetResolution(discGetWidth(), discGetHeight())
titleSprite = spriteLoad("graphics/title.png")
titleX = (discGetWidth() - spriteGetWidth(titleSprite)) / 2

2.11.14. discPause

discPause()

Pauses playback on the current frame, which stays on screen. The disc’s audio pauses with it. The call is ignored while the disc is stopped and does nothing without a disc. Resume with discPlay.

Since: 1.x See also: discPlay, discStop, singeSetPauseFlag

Example
-- Hold the last frame of the scene while the player chooses a door.
function onOverlayUpdate()
    if discGetFrame() >= SCENE_LAST_FRAME and not choosing then
        discPause()
        choosing = true
    end
    return OVERLAY_UPDATED
end

2.11.15. discPauseAtFrame

discPauseAtFrame(frame)

Seeks to frame, shows it and pauses. This is the same binding as discSearch under a second name; the two are interchangeable in every respect, including the clamping rules described there. Prefer discSearch in new code and keep discPauseAtFrame only when porting old scripts.

Notes:

Legacy alias. Use discSearch in new code.

Since: 1.18 See also: discSearch, discPlay

Example
-- Ported 1.x code:  park on the scene's first frame until the player is ready.
function onInputPressed(what)
    if what == SWITCH_START1 then
        discPauseAtFrame(SCENE_FIRST_FRAME)
        waitingForPlayer = true
    end
end

2.11.16. discPlay

discPlay()

Starts or resumes playback from the current frame and clears the stopped state set by discStop. Audio resumes with the video, and the playback clock restarts from the current frame so a long pause does not cause a jump. Does nothing without a disc, apart from clearing the stopped flag.

Since: 1.x See also: discPause, discStop, discSkipToFrame

Example
-- Standard attract-mode start:  cue the first frame, then roll.
function attractBegin()
    discSearch(ATTRACT_FIRST_FRAME)
    overlayClear()
    discPlay()
    attractRunning = true
end

2.11.17. discSearch

discSearch(frame)

Seeks the disc to frame, shows that frame and pauses on it, clearing the stopped state if the disc was stopped. The disc holds the frame until discPlay, discSkipToFrame or another transport call. A negative frame clamps to the first frame and one past the end clamps to the last; with a framefile the segment containing the frame is selected and the position is clamped inside it. Does nothing without a disc.

Parameters:

  • frame — target frame number, zero based.

Since: 1.x See also: discSkipToFrame, discPlay, discGetFrame

Example
-- Player picked the left corridor:  cue the scene and wait for the go.
function goLeft()
    discSearch(CORRIDOR_LEFT_FIRST_FRAME)
    soundPlay(SOUND_DOOR)
    waitingForPlayer = true
end

2.11.18. discSearchBlanking

discSearchBlanking(...)

Does nothing. On laserdisc hardware this chose whether the screen blanked while the player sought a frame; Singe’s software player seeks without blanking, so the call accepts any arguments, logs a trace line and returns.

Notes:

Unimplemented. Retained for backward compatibility only. There is no replacement.

Since: 1.x See also: discSearch, discSkipBlanking

Example
-- Pre-2.00 scripts often set the blanking modes once at startup.  Harmless.
discSearchBlanking(false)
discSkipBlanking(false)
discSearch(TITLE_FRAME)

2.11.19. discSetAudioTrack

discSetAudioTrack(track)

Switches the disc to another audio track. Queued audio from the old track is dropped and playback realigns, so the change is heard almost immediately. With a disc, a track outside 0 to discGetAudioTracks() - 1 terminates the script; without a disc the call does nothing. Use it to implement a language menu or to honor a preference saved between sessions.

Parameters:

  • track — zero based audio track index.

Example
-- Apply the language the player chose in the options screen.
function applyLanguage(choice)
    if choice >= 0 and choice < discGetAudioTracks() then
        discSetAudioTrack(choice)
        settings.language = choice
        saveSettings()
    end
end

2.11.20. discSetFPS

discSetFPS(...)

Does nothing. The frame rate comes from the video file, so the call accepts any arguments, logs a trace line and returns. Nothing in the shipped Framework.singe calls it; only pre-2.00 scripts do.

Notes:

Unimplemented. Retained for backward compatibility only. The frame rate is read from the video file and cannot be set from a script.

Since: 1.x See also: discGetFrame, discSkipToFrame

Example
-- A ported 1.x script.  The call is ignored; frames per second is a property of the file.
discSetFPS(29.97)
discSearch(TITLE_FRAME)
discPlay()

2.11.21. discSkipBackward

discSkipBackward(frames)

Seeks backward by frames from the current frame without changing the play or pause state: a playing disc keeps playing from the new position, a paused disc stays paused on it. The call is ignored while the disc is stopped and without a disc. The delta is not validated; a negative value skips forward, and a delta larger than the current frame clamps at frame 0. With a framefile the delta applies to the frame number discGetFrame reports, so a skip may cross into an earlier segment.

Parameters:

  • frames — number of frames to subtract from the current frame.

Example
-- Replay the last second (30 frames) when the player misses a prompt.
function missedPrompt()
    lives = lives - 1
    discSkipBackward(30)
    promptShown = false
end

2.11.22. discSkipBlanking

discSkipBlanking(...)

Does nothing. It once chose whether the screen blanked during a skip on laserdisc hardware; Singe’s software player never blanks, so the call accepts any arguments, logs a trace line and returns.

Notes:

Unimplemented. Retained for backward compatibility only. There is no replacement.

Since: 1.x See also: discSearchBlanking, discSkipToFrame

Example
-- Pre-2.00 scripts often set the blanking modes once at startup.  Harmless.
discSearchBlanking(false)
discSkipBlanking(false)
discSearch(TITLE_FRAME)

2.11.23. discSkipForward

discSkipForward(frames)

Seeks forward by frames from the current frame without changing the play or pause state. Mirror of discSkipBackward: ignored while stopped and without a disc, the delta is not validated, and a target past the last frame clamps at the last frame. With a framefile the delta applies to the frame number discGetFrame reports, so a skip may cross into a later segment.

Parameters:

  • frames — number of frames to add to the current frame.

Example
-- Let a returning player skip the two-second scene intro.
function onInputPressed(what)
    if what == SWITCH_BUTTON1 and inSceneIntro then
        discSkipForward(60)
        inSceneIntro = false
    end
end

2.11.24. discSkipToFrame

discSkipToFrame(frame)

Seeks to frame and starts playing from it no matter the disc’s state, clearing the stopped state if necessary. Contrast with discSearch, which seeks and pauses. A frame before the start or past the end clamps to the first or last frame; with a framefile the segment containing the frame is selected and the position is clamped inside it. Does nothing without a disc, apart from clearing the stopped flag.

Parameters:

  • frame — target frame number, zero based.

Since: 1.x See also: discSearch, discPlay, discGetFrame

Example
-- Skip the intro on a replay.
function startGame()
    if hasPlayedBefore then
        discSkipToFrame(GAMEPLAY_FIRST_FRAME)
    else
        discSkipToFrame(INTRO_FIRST_FRAME)
    end
end

2.11.25. discStepBackward

discStepBackward()

Moves the disc back exactly one frame and pauses on it, whatever the previous play state. Stepping at frame 0 stays on frame 0. Ignored while the disc is stopped, like discSkipBackward. Intended for frame-accurate debugging and service screens. Does nothing without a disc.

Example
-- Service screen:  left and right nudge the disc one frame at a time.
function onInputPressed(what)
    if what == SWITCH_LEFT then
        discStepBackward()
    elseif what == SWITCH_RIGHT then
        discStepForward()
    end
end

2.11.26. discStepForward

discStepForward()

Moves the disc forward exactly one frame and pauses on it, whatever the previous play state. Stepping on the last frame stays on the last frame. Like discStepBackward it is ignored while the disc is stopped. Does nothing without a disc.

Example
-- Frame finder:  step through a scene and print the frame number.
function onOverlayUpdate()
    overlayClear()
    overlayPrint(8, 8, "Frame " .. discGetFrame())
    if stepping then
        discStepForward()
    end
    return OVERLAY_UPDATED
end

2.11.27. discStop

discStop()

Stops the disc. Playback pauses, the video is replaced by the classic blue screen, discGetState reports DISC_STOPPED and discGetFrame returns 0 until the disc is started again. While stopped, discPause, discSkipForward, discSkipBackward, discStepForward and discStepBackward are ignored. Any of discPlay, discSearch or discSkipToFrame clears the stopped state. A second discStop is ignored.

Since: 1.x See also: discPlay, discPause, discGetState

Example
-- Game over:  drop to the blue screen behind the score table.
function gameOver()
    discStop()
    soundPlay(SOUND_GAME_OVER)
    showScores = true
end

2.12. Emitter

Emitters spawn, move and draw particles; see Particles. Handles are integers. A 2D emitter lives in overlay coordinates, Y down, and draws when emitterDraw asks from onOverlayUpdate; a 3D emitter sits on a node, lives in world units, and draws itself in the scene. The recipe calls can be made in any order, before or after the emitter starts, and take effect on the next particles born (a few, noted below, act on the live ones too). Everything given as a minimum and maximum is drawn at random between them for every particle. Particles advance with the wall clock, at most a tenth of a second per frame, and hold while the game is paused.

2.12.1. emitterNew

emitter = emitterNew()
emitter = emitterNew(node)

Makes an emitter. With no argument it is a 2D one at overlay position (0, 0), moved with emitterSetPosition; with a node it is a 3D one whose particles are born at that node’s world position, and it needs the 3D scene, so on a machine without one the call ends the script (2D emitters work everywhere). A new emitter is not streaming; call emitterStart or emitterBurst. Deleting the node deletes its emitters. Defaults: 50 particles a second, living one to two seconds, 30 degree spread, white fading to transparent, normal blending, no gravity, drag, spin, radius, texture, trail or collision, a pool of 1000; a 2D emitter starts them up the screen at 50 to 100 overlay units a second shrinking from 16 to 4, a 3D one up the Y axis at 1 to 2 world units a second shrinking from 0.2 to 0.05.

Returns: The emitter handle.

Example
-- Exhaust from the ship's engine node; the recipe is set before the stream starts.
exhaust = emitterNew(nodeFind("Engine", ship))
emitterSetBlend(exhaust, PARTICLE_ADD)
emitterSetRate(exhaust, 120)
emitterSetLife(exhaust, 0.3, 0.6)
emitterSetDirection(exhaust, 0, 0, 1)
emitterSetSpeed(exhaust, 3, 5)
emitterSetSize(exhaust, 0.3, 0.05)
emitterSetColor(exhaust, 120, 180, 255, 255, 30, 60, 255, 0)
emitterStart(exhaust)

2.12.2. emitterDelete

emitterDelete(emitter)

Removes the emitter, its live particles and its copy of the texture at once; nothing fades out. Use emitterStop instead to let the last particles finish. A 3D emitter is also removed on its own when its node is deleted. A handle that is not a live emitter ends the script, so clear the variable afterward.

Since: 3.00. See also: emitterNew, emitterStop, emitterIsActive

Example
-- The explosion is over: free its emitter once the last spark has died.
function onOverlayUpdate()
    if explosion ~= nil and not emitterIsActive(explosion) then
        emitterDelete(explosion)
        explosion = nil
    end
    return OVERLAY_NOT_UPDATED
end

2.12.3. emitterSetTexture

emitterSetTexture(emitter, sprite)
emitterSetTexture(emitter)

The picture each particle wears: a loaded sprite, or none (one argument, or nil) for the built-in soft disc. The emitter keeps its own copy of the sprite’s pixels, every frame of an animated sprite included, so the sprite may be unloaded afterward. Setting the texture resets the frame range to frame 0 and moves every live particle to frame 0, so call emitterSetFrames after it, not before. Blending and tint apply to the picture as they do to the disc.

Since: 3.00. See also: emitterSetFrames, spriteLoad, emitterSetBlend

Example
-- Snow: a sheet of six flake shapes, one picked at random per particle.
flakes = spriteLoadFrames(6, DIR .. "Sprites/flakes.png")
snow   = emitterNew()
emitterSetTexture(snow, flakes)
emitterSetFrames(snow, 0, 5)
emitterSetDirection(snow, 0, 1)
emitterSetSpeed(snow, 20, 40)
emitterSetLife(snow, 6, 9)
emitterSetSize(snow, 6, 6, 0.4)
emitterStart(snow)

2.12.4. emitterSetFrames

emitterSetFrames(emitter, first, last)

With an animated sprite as the texture, each new particle takes a random frame from first to last and keeps it for life; frames count from 0. Values are clamped to the frames the texture has, and last is raised to first when it is smaller. Default: frame 0 only, which is also what emitterSetTexture resets to. With the built-in disc or a single-frame sprite the range has no effect.

Since: 3.00. See also: emitterSetTexture, spriteLoad

Example
-- The puff sheet has four soft puffs, then four harder debris chunks.
emitterSetTexture(smoke, puffSheet)
emitterSetFrames(smoke, 0, 3)
emitterSetTexture(debris, puffSheet)
emitterSetFrames(debris, 4, 7)

2.12.5. emitterSetBlend

emitterSetBlend(emitter, mode)

How particles combine with what is behind them. PARTICLE_ALPHA (default) blends normally, for smoke, dust, rain and debris; PARTICLE_ADD adds light, for fire, sparks, glows and magic, and never darkens. Takes effect on the live particles at once. Anything other than those two constants ends the script.

Since: 3.00. See also: emitterSetColor, emitterSetTexture

Example
-- Sparks glow; the smoke above them does not.
emitterSetBlend(sparks, PARTICLE_ADD)
emitterSetColor(sparks, 255, 220, 120, 255, 255, 80, 20, 0)
emitterSetBlend(smoke, PARTICLE_ALPHA)
emitterSetColor(smoke, 160, 160, 170, 120, 120, 120, 130, 0)

2.12.6. emitterSetLayer

emitterSetLayer(emitter, layer)

2D only: where emitterDraw puts the particles. PARTICLE_OVER (default) draws above everything on the overlay; PARTICLE_UNDER draws beneath the overlay and above the video and the 3D scene, for smoke behind the score. On a 3D emitter the setting is accepted and ignored. Anything other than those two constants ends the script.

Since: 3.00. See also: emitterDraw, emitterSetPosition

Example
-- Rain falls behind the HUD, the hit sparks in front of it.
rain = emitterNew()
emitterSetLayer(rain, PARTICLE_UNDER)
hits = emitterNew()
emitterSetLayer(hits, PARTICLE_OVER)

function onOverlayUpdate()
    overlayClear()
    emitterDraw(rain)
    drawHud()
    emitterDraw(hits)
    return OVERLAY_UPDATED
end

2.12.7. emitterSetRate

emitterSetRate(emitter, perSecond)

How many particles a second a started emitter makes; default 50, negative values become 0. Fractions accumulate, so 0.5 makes one every two seconds. Change it while streaming to throttle a flame or a thruster. A full pool (emitterSetMax) makes no more until some die, whatever the rate.

Since: 3.00. See also: emitterStart, emitterBurst, emitterSetMax

Example
-- The thruster's plume follows the throttle.
function onControllerMoved(axis, value, which)
    if axis == GAMEPAD_AXIS_RIGHT_TRIGGER then
        throttle = value / 32767
        emitterSetRate(plume, 30 + 300 * throttle)
    end
end

2.12.8. emitterSetLife

emitterSetLife(emitter, minSeconds, maxSeconds)

How long each new particle lives, drawn at random between the two; default 1 to 2. Its size and color run from their start to their end over that time, so life sets the pace of every fade. The minimum is held at 0.001 or above and the maximum is raised to the minimum when it is smaller. Live particles keep the life they were born with.

Since: 3.00. See also: emitterSetSize, emitterSetColor, emitterSetRate

Example
-- Muzzle flash: a burst that is gone in a tenth of a second.
flash = emitterNew(muzzle)
emitterSetBlend(flash, PARTICLE_ADD)
emitterSetLife(flash, 0.05, 0.1)
emitterSetSpeed(flash, 2, 6)
emitterSetSize(flash, 0.15, 0.4)

function onFire()
    emitterBurst(flash, 12)
end

2.12.9. emitterSetSoftness

emitterSetSoftness(emitter, distance)

3D only: fades a particle out over distance world units where it meets geometry behind it, so a smoke puff does not draw a hard line where it crosses a wall and a fountain sinks into its pool instead of cutting it. 0 (the default) switches it off; negative values become 0. While any emitter uses it the scene’s depth is rendered once more per frame, so a Raspberry Pi should use it sparingly. A 2D emitter stores the value and ignores it.

Since: 3.00. See also: emitterSetLit, emitterSetBlend

Example
-- Smoke from the brazier softens against the post it rises past.
smoke = emitterNew(brazierTop)
emitterSetRate(smoke, 25)
emitterSetLife(smoke, 1.5, 2.5)
emitterSetSize(smoke, 0.2, 0.9, 0.2)
emitterSetColor(smoke, 160, 160, 170, 120, 120, 120, 130, 0)
emitterSetLit(smoke, true)
emitterSetSoftness(smoke, 0.3)
emitterStart(smoke)

2.12.10. emitterSetSpeed

emitterSetSpeed(emitter, min, max)

Starting speed of each new particle, drawn at random between the two, in overlay units a second (2D) or world units a second (3D); defaults 50 to 100 in 2D and 1 to 2 in 3D. The maximum is raised to the minimum when it is smaller. Speed sets how far a particle gets before drag, gravity and its life take over.

Example
-- A fountain throws drops hard and straight; dust barely moves.
emitterSetSpeed(fountain, 4.0, 5.0)
emitterSetSpread(fountain, 8)
emitterSetSpeed(dust, 0.05, 0.2)
emitterSetSpread(dust, 180)

2.12.11. emitterSetDirection

emitterSetDirection(emitter, x, y)
emitterSetDirection(emitter, x, y, z)

The mean direction new particles set off in; only the direction matters, not the length. 2D default (0, -1), up the screen since overlay Y grows downward; 3D default (0, 1, 0), up the world Y axis. A 2D emitter ignores z; a 3D emitter given two values gets z = 0. A zero vector is treated as (0, -1, 0). The direction is in world axes for a 3D emitter, not the node’s, so turn it yourself when the node turns.

Since: 3.00. See also: emitterSetSpread, emitterSetSpeed

Example
-- Exhaust streams out behind the ship whichever way it faces.
function onOverlayUpdate()
    local heading = math.rad(shipYaw)
    emitterSetDirection(exhaust, -math.sin(heading), 0, -math.cos(heading))
    return OVERLAY_NOT_UPDATED
end

2.12.12. emitterSetSpread

emitterSetSpread(emitter, degrees)

Half the angle of the cone (3D) or fan (2D) around the direction that new particles are thrown into, 0 to 180; 0 is a straight line, 180 is every direction. Default 30; values outside the range are clamped. In 3D the directions are spread evenly over the cone’s cap, so a wide cone does not bunch toward its axis.

Since: 3.00. See also: emitterSetDirection, emitterSetRadius

Example
-- Fireworks go everywhere; the torch flame stays in a tight column.
emitterSetSpread(fireworks, 180)
emitterSetSpread(flame, 15)

2.12.13. emitterSetGravity

emitterSetGravity(emitter, x, y)
emitterSetGravity(emitter, x, y, z)

A constant acceleration on every particle, in overlay units (2D) or world units (3D) a second squared: (0, 500) pulls 2D sparks down the screen, (0, -20) lets 2D smoke rise, (0, -9.8, 0) is Earth in the scene. Default none. It applies to the live particles from the next frame. Particles are not physics bodies; give them emitterSetCollide to bounce off a floor or the scene.

Example
-- Sparks fall, smoke rises, both from the same grinder.
emitterSetGravity(sparks, 0, 500)
emitterSetGravity(smoke, 0, -20)

-- Underwater, the bubbles head for the surface.
emitterSetGravity(bubbles, 0, 3, 0)

2.12.14. emitterSetDrag

emitterSetDrag(emitter, perSecond)

How quickly particles lose their velocity: every frame the velocity is multiplied by 1 - perSecond * dt, never below 0, so 1 takes most of the speed away within a second and 0 (the default) keeps it forever. Negative values become 0. Smoke, embers and fireworks slow down; sparks and rain do not. Applies to the live particles from the next frame.

Since: 3.00. See also: emitterSetGravity, emitterSetSpeed

Example
-- A firework shell: fast out, then hanging and falling.
fireworks = emitterNew()
emitterSetBlend(fireworks, PARTICLE_ADD)
emitterSetSpeed(fireworks, 120, 320)
emitterSetSpread(fireworks, 180)
emitterSetGravity(fireworks, 0, 220)
emitterSetDrag(fireworks, 0.8)
emitterSetLife(fireworks, 0.8, 1.6)

2.12.15. emitterSetSize

emitterSetSize(emitter, start, finish)
emitterSetSize(emitter, start, finish, variation)

Size at birth and at death, in overlay units (2D) or world units (3D), changing evenly over the particle’s life; defaults 16 to 4 in 2D and 0.2 to 0.05 in 3D. variation (0 to 1, default 0) scales both sizes of each new particle by one random factor between 1 - variation and 1 + variation, so a puff is a little bigger or smaller for its whole life. Negative sizes become 0 and variation is clamped. A textured particle is drawn as a square of that size; a wider picture is squashed.

Since: 3.00. See also: emitterSetLife, emitterSetColor, emitterSetSpin

Example
-- Smoke grows as it thins; sparks shrink to nothing.
emitterSetSize(smoke, 12, 48, 0.2)
emitterSetSize(sparks, 5, 1)

2.12.16. emitterSetCollide

emitterSetCollide(emitter, mode)
emitterSetCollide(emitter, mode, bounce)
emitterSetCollide(emitter, mode, bounce, friction)
emitterSetCollide(emitter, mode, bounce, friction, floor)

What particles bounce off. COLLIDE_NONE (default) is nothing; COLLIDE_FLOOR is a horizontal plane at height floor, below which (larger Y in 2D, smaller Y in 3D) a particle is put back on the plane and reflected; COLLIDE_SCENE is the physics world, for 3D emitters only, by a ray cast per particle along its motion each frame, capped at 200 casts per emitter per frame and resumed where they left off, so a big emitter spreads the cost over a few frames. On a 2D emitter COLLIDE_SCENE is accepted and does nothing. A mode other than those three ends the script.

Parameters:

  • mode — COLLIDE_NONE, COLLIDE_FLOOR or COLLIDE_SCENE.

  • bounce — how much speed survives a hit, 0 to 1, default 0.5; clamped.

  • friction — how much sliding speed is lost per hit, 0 to 1, default 0.2; clamped.

  • floor — height of the floor plane, in world units for a 3D emitter or overlay units for a 2D one, default 0. Used by COLLIDE_FLOOR only.

Example
-- Sparks bounce on the workshop floor (overlay row 440) and leave streaks.
sparks = emitterNew()
emitterSetBlend(sparks, PARTICLE_ADD)
emitterSetGravity(sparks, 0, 500)
emitterSetCollide(sparks, COLLIDE_FLOOR, 0.4, 0.2, 440)
emitterSetTrail(sparks, 6, 3)

-- Embers in the scene bounce off whatever the physics world holds.
emitterSetCollide(embers, COLLIDE_SCENE, 0.3, 0.5)

2.12.17. emitterSetColor

emitterSetColor(emitter, r, g, b, a, r2, g2, b2, a2)

Color and opacity at birth (r, g, b, a) and at death (r2, g2, b2, a2), each 0 to 255, changing evenly over the particle’s life; values outside the range are clamped. Default white and opaque to white and transparent. The tint multiplies the texture or the built-in disc, so a white picture takes the color exactly. A fade in and out needs two emitters or a texture with the shape in it; one recipe runs one straight ramp.

Since: 3.00. See also: emitterSetBlend, emitterSetLife, emitterSetSize

Example
-- Flame: bright yellow at the base, dying to dim red and gone.
emitterSetColor(flame, 255, 200, 90, 255, 255, 40, 0, 0)
-- Dust motes fade in from nothing and hang; their life ends them.
emitterSetColor(dust, 255, 240, 200, 0, 255, 240, 200, 160)

2.12.18. emitterSetSpin

emitterSetSpin(emitter, min, max)

Rotation speed of each new particle in degrees a second, drawn at random between the two; negative values spin the other way, and a range that straddles 0 gives both. Every particle starts at a random angle whether or not it spins. Default none. The maximum is raised to the minimum when it is smaller. Spin shows on a textured particle or a trail; the built-in disc is round and looks the same at any angle.

Since: 3.00. See also: emitterSetTexture, emitterSetSize

Example
-- Leaves tumble; embers hardly turn.
emitterSetTexture(leaves, leafSprite)
emitterSetSpin(leaves, -180, 180)
emitterSetSpin(embers, -20, 20)

2.12.19. emitterSetRadius

emitterSetRadius(emitter, radius)

New particles are born anywhere within this distance of the emitter’s origin, evenly over a disc (2D) or a ball (3D), in overlay or world units. Default 0, a point; negative values become 0. A radius fills a volume, a torch head or a patch of dust in the air, where a point would give a needle.

Since: 3.00. See also: emitterSetSpread, emitterSetPosition

Example
-- Dust in a room-sized ball of air, most of it already there when the level starts.
air = nodeNew()
nodeSetPosition(air, 0, 2, 0)
dust = emitterNew(air)
emitterSetRadius(dust, 2.5)
emitterSetSpread(dust, 180)
emitterSetSpeed(dust, 0.05, 0.2)
emitterSetLife(dust, 4, 6)
emitterStart(dust)
emitterBurst(dust, 120)

2.12.20. emitterSetLit

emitterSetLit(emitter, lit)

3D only: shades each particle by the scene’s lights and sky as if it were a small sphere facing the camera, so smoke takes a brazier’s color and dust glints in the sun. Off by default; shadows are not consulted. With PARTICLE_ADD the lighting is still applied to the tint before it is added. A 2D emitter stores the value and ignores it.

Since: 3.00. See also: emitterSetSoftness, emitterSetBlend

Example
-- Smoke over each brazier picks up its firelight.
for _, brazier in ipairs(braziers) do
    local smoke = emitterNew(brazier.top)
    emitterSetRate(smoke, 12)
    emitterSetLife(smoke, 2.5, 4)
    emitterSetColor(smoke, 90, 80, 75, 90, 50, 45, 45, 0)
    emitterSetLit(smoke, true)
    emitterStart(smoke)
end

2.12.21. emitterSetLocal

emitterSetLocal(emitter, local)

Whether live particles follow the emitter. false (default) leaves each one where it was born, so a torch carried through a room leaves smoke behind it; true keeps the whole cloud relative to the emitter’s origin, so a thruster plume moves with the ship. Switching it moves the live particles between frames of reference without a jump. On a 3D emitter the origin is the node’s world position; on a 2D one it is the emitterSetPosition point, so a local 2D cloud slides with that too. Trails follow the same rule.

Since: 3.00. See also: emitterSetPosition, emitterSetRadius

Example
-- A magic aura that stays wrapped around the wizard as she walks.
aura = emitterNew(nodeFind("Chest", wizard))
emitterSetLocal(aura, true)
emitterSetRadius(aura, 0.6)
emitterSetSpeed(aura, 0.05, 0.15)
emitterSetSpread(aura, 180)
emitterSetBlend(aura, PARTICLE_ADD)
emitterStart(aura)

2.12.22. emitterSetMax

emitterSetMax(emitter, count)

The pool: how many particles may be alive at once, default 1000. A full pool makes no more, from the stream or a burst, until some die. Changing the count rebuilds the pool and kills every live particle, so set it before starting. Size the pool to rate times longest life, plus the biggest burst. A count below 1 ends the script.

Since: 3.00. See also: emitterSetRate, emitterBurst, emitterGetCount

Example
-- 300 drops a second living up to 1.6 seconds needs about 480; leave room.
fountain = emitterNew(spout)
emitterSetRate(fountain, 300)
emitterSetLife(fountain, 1.0, 1.6)
emitterSetMax(fountain, 600)
emitterStart(fountain)

2.12.23. emitterSetPosition

emitterSetPosition(emitter, x, y)

2D only: where new particles are born, in overlay coordinates; default (0, 0). Set it every frame to follow a sprite or a 2D physics body. Live particles stay where they are unless emitterSetLocal is on. A 3D emitter follows its node and ends the script here; move the node instead.

Since: 3.00. See also: emitterDraw, emitterSetLocal, emitterSetRadius

Example
-- Sparks fly from wherever the grinder sprite is this frame.
function onOverlayUpdate()
    overlayClear()
    spriteDraw(grinder, grinderX, grinderY)
    emitterSetPosition(sparks, grinderX + 24, grinderY + 8)
    emitterDraw(sparks)
    return OVERLAY_UPDATED
end

2.12.24. emitterSetTrail

emitterSetTrail(emitter, length, width)

A ribbon behind every particle through its last length positions, one recorded per frame (2 to 16; 0 or 1 for none, the default), width across in world or overlay units, in 2D and 3D alike. The ribbon carries the particle’s current tint, fades to transparent toward its tail, and is textured by the middle column of the particle’s picture so the disc’s soft edge becomes the ribbon’s. Values are clamped to the range. Changing the length rebuilds the trail storage, so live particles start their ribbons again. Sparks, embers, tracer rounds, comets.

Example
-- Tracer rounds: tiny, fast, and all streak.
tracers = emitterNew(gunMuzzle)
emitterSetBlend(tracers, PARTICLE_ADD)
emitterSetSpeed(tracers, 40, 50)
emitterSetSpread(tracers, 2)
emitterSetSize(tracers, 0.04, 0.04)
emitterSetLife(tracers, 0.8, 1.0)
emitterSetTrail(tracers, 8, 0.03)

2.12.25. emitterStart

emitterStart(emitter)

Begins the steady stream at the rate set; from then on the emitter makes particles every frame until emitterStop. Starting an emitter that is already streaming changes nothing. The stream needs no drawing call to run; a 2D emitter that is streaming but not drawn still spends its pool.

Since: 3.00. See also: emitterStop, emitterSetRate, emitterBurst

Example
-- The engine lights when the player throttles up and dies when they cut it.
function onThrottle(open)
    if open then
        emitterStart(exhaust)
    else
        emitterStop(exhaust)
    end
end

2.12.26. emitterStop

emitterStop(emitter)

Ends the stream; the live particles finish their lives and any fraction of a particle owed is dropped. emitterBurst still works on a stopped emitter, and emitterIsActive stays true until the last particle dies. Use emitterClear to remove the particles at once as well.

Since: 3.00. See also: emitterClear, emitterStart, emitterIsActive

Example
-- The torch goes out: stop the flame, let the last smoke drift away.
function onTorchDoused()
    emitterStop(flame)
    emitterStop(smoke)
    soundPlay(hiss)
end

2.12.27. emitterBurst

emitterBurst(emitter, count)

Makes count particles at once from the current recipe, stream or no stream: an explosion, a splash, a puff. Only as many as the pool has room for are made; emitterSetMax sets the room. A 2D emitter bursts at its emitterSetPosition point, a 3D one at its node, spread over emitterSetRadius.

Since: 3.00. See also: emitterStart, emitterSetMax, emitterSetRadius

Example
-- Fireworks: a shell bursts somewhere over the disc every second or so.
function onOverlayUpdate()
    if frames % 60 == 0 then
        emitterSetPosition(fireworks, 120 + (frames * 7) % (width - 240), 80 + (frames * 13) % 160)
        emitterBurst(fireworks, 260)
    end
    overlayClear()
    emitterDraw(fireworks)
    frames = frames + 1
    return OVERLAY_UPDATED
end

2.12.28. emitterClear

emitterClear(emitter)

Kills every live particle now and forgets any fraction of a particle owed. The stream is not stopped: a started emitter goes on making new particles next frame, so call emitterStop as well to empty it for good. Use it when a scene changes and the old sparks must not linger.

Since: 3.00. See also: emitterStop, emitterDelete

Example
-- Restarting the level: the emitters stay, the old particles go.
function resetLevel()
    for _, emitter in ipairs(levelEmitters) do
        emitterStop(emitter)
        emitterClear(emitter)
    end
    placePlayer()
end

2.12.29. emitterDraw

emitterDraw(emitter)

2D only, from onOverlayUpdate: queues the emitter’s particles to be drawn this frame, above or beneath the overlay per emitterSetLayer, in overlay coordinates mapped onto the window. Emitters on the same layer draw in the order they were queued. The queue empties every frame, so the call belongs in every frame the particles should show; not drawing an emitter does not stop it. Up to 64 emitters per layer draw in a frame. A 3D emitter draws itself in the scene and ends the script here.

Example
function onOverlayUpdate()
    overlayClear()
    emitterSetPosition(smoke, chimneyX, chimneyY)
    emitterDraw(smoke)
    emitterDraw(sparks)
    fontPrint(20, 20, "Score " .. score)
    return OVERLAY_UPDATED
end

2.12.30. emitterGetCount

count = emitterGetCount(emitter)

How many of the emitter’s particles are alive this frame, 0 to the pool size. Useful for tuning a pool, for an on-screen budget, or for knowing when a burst has died away.

Returns: The live count, an integer.

Since: 3.00. See also: emitterSetMax, emitterIsActive

Example
-- Development overlay: how much of each pool is in use.
function onOverlayUpdate()
    overlayClear()
    fontPrint(20, 20, string.format("live %d / %d", emitterGetCount(fireworks), fireworksPool))
    return OVERLAY_UPDATED
end

2.12.31. emitterIsActive

active = emitterIsActive(emitter)

Whether the emitter is streaming or still has live particles: true from emitterStart or emitterBurst until the stream is stopped and the last particle has died, false once the explosion is over. A streaming emitter whose pool happens to be empty is still active.

Returns: Boolean.

Since: 3.00. See also: emitterStop, emitterGetCount, emitterDelete

Example
-- One-shot explosions live in a list and are freed when they burn out.
function onOverlayUpdate()
    for i = #explosions, 1, -1 do
        if not emitterIsActive(explosions[i]) then
            emitterDelete(explosions[i])
            table.remove(explosions, i)
        end
    end
    return OVERLAY_NOT_UPDATED
end

2.13. Font

Singe has two text renderers. The built-in console font is drawn by overlayPrint and needs no assets; the font* family loads TrueType files at a fixed point size and renders them either straight onto the overlay with fontPrint or into a reusable sprite with fontToSprite. Font handles are integers from fontLoad, and the engine keeps one globally selected font, which fontLoad sets to the font it just loaded and fontSelect changes. Text is rendered in the current foreground color at the quality chosen by fontQuality, and text positions are overlay coordinates. Release fonts with fontUnload; Singe/FreeSansBold.ttf ships with the engine and is always available.

2.13.1. fontLoad

result = fontLoad(filename, pointSize)

Opens a TrueType font at one point size and makes it the selected font. The size is fixed for the life of the handle, so load the same file once per size you need. The name goes through the virtual file system like any other asset; prepend DIR for files shipped with your game, or use Singe/FreeSansBold.ttf for the bundled face. A file that cannot be opened ends the script with Unable to open and the name.

Parameters:

  • filename — path to a .ttf file.

  • pointSize — integer point size.

Returns: integer font handle.

Since: 1.x See also: fontSelect, fontUnload, fontQuality

Example
-- Two sizes of the bundled face: large for the title, small for the HUD.
fontQuality(FONT_QUALITY_BLENDED)
titleFont = fontLoad("Singe/FreeSansBold.ttf", 32)
hudFont   = fontLoad("Singe/FreeSansBold.ttf", 18)

fontSelect(titleFont)
titleSprite = fontToSprite("GAME OVER")
fontSelect(hudFont)

2.13.2. fontPrint

fontPrint(x, y, text)

Renders a string with the selected font, the current quality, and the current foreground color (plus the background color for FONT_QUALITY_SHADED), then blits it onto the overlay with its top-left corner at (x, y). Call it from onOverlayUpdate, every frame if need be: the engine keeps each string it renders, keyed by the font, quality, colors, and text, and a later call asking for the same one only blits it. Strings not printed for about a second are forgotten, and a font’s strings go when it is unloaded, so text that changes costs no more than it always did and text that does not is nearly free. A whole page of high scores reprinted every frame is fine. With no font selected the script ends with an error.

Parameters:

  • x, y — top-left corner in overlay coordinates; fractions are truncated.

  • text — the string to render.

Example
-- Live audio calibration readout; the text changes every frame, so render it directly.
function onOverlayUpdate()
    overlayClear()
    colorForeground(255, 255, 255, 255)
    fontSelect(hudFont)
    fontPrint(MARGIN_X, MARGIN_Y, "AUDIO DELAY CALIBRATION")
    fontPrint(MARGIN_X, MARGIN_Y + 30, "Delay: " .. calibrationDelay .. " ms")
    fontPrint(MARGIN_X, MARGIN_Y + 60, "Left / Right: 10 ms     Up / Down: 1 ms")
    return OVERLAY_UPDATED
end

2.13.3. fontQuality

fontQuality(mode)

Selects how fontPrint and fontToSprite rasterize text from now on. The setting is global, not per font, and starts at FONT_QUALITY_SOLID. Sprites already made by fontToSprite keep the quality they were rendered with. A value outside the three constants ends the script with an error.

Parameters:

  • mode — FONT_QUALITY_SOLID (1): fastest, one-bit edges, no anti-aliasing. FONT_QUALITY_SHADED (2): anti-aliased glyphs on a solid rectangle of the background color. FONT_QUALITY_BLENDED (3): anti-aliased glyphs with per-pixel alpha that blend over anything; the usual choice.

Since: 1.x See also: fontPrint, fontToSprite, colorBackground

Example
-- Blended text over the video, but a shaded label box for the debug readout.
fontQuality(FONT_QUALITY_BLENDED)
titleSprite = fontToSprite("HIGH SCORES")

colorBackground(0, 0, 0, 255)
fontQuality(FONT_QUALITY_SHADED)
debugLabel = fontToSprite("FRAME")
fontQuality(FONT_QUALITY_BLENDED)

2.13.4. fontSelect

fontSelect(id)

Makes a loaded font the one used by fontPrint and fontToSprite. The selection persists until the next fontSelect or fontLoad, since loading also selects. It can be changed as often as needed, including several times within one onOverlayUpdate. An unknown or unloaded handle (or no number at all) leaves the current font selected and prints a warning, as Hypseus Singe lets it pass.

Since: 1.x See also: fontLoad, fontPrint, fontToSprite

Example
-- Title in the large face, score in the small one, every frame.
function onOverlayUpdate()
    overlayClear()
    fontSelect(titleFont)
    fontPrint(TITLE_X, 40, "HIGH SCORES")
    fontSelect(hudFont)
    fontPrint(8, 8, "Score: " .. score)
    return OVERLAY_UPDATED
end

2.13.5. fontToSprite

result = fontToSprite(text)

Renders a string with the selected font, quality, and colors into a new sprite and returns its handle. The sprite is independent of the font from then on, so it survives fontUnload, and it works with every sprite* call: draw it, measure it, scale or rotate it, and free it with spriteUnload. For a string that changes, render a new sprite and unload the old one. With no font selected the script ends with an error.

Rendering text to a sprite for performance is deprecated. fontPrint now keeps what it renders, so printing the same string every frame costs about what drawing a sprite made from it does, without the sprite to manage. Use fontToSprite when the text has to be a sprite: to scale it, rotate it, flip it, or measure it with spriteGetWidth and spriteGetHeight.

Returns: integer sprite handle.

Example
-- A title that spins and grows in:  text that has to be a sprite, to be turned and scaled.
titleSprite = fontToSprite("GAME OVER")
titleFrames = 0

function onOverlayUpdate()
    titleFrames = titleFrames + 1
    spriteRotate(titleSprite, (titleFrames * 12) % 360)
    spriteScale(titleSprite, math.min(titleFrames / 30, 1))
    spriteDraw(titleSprite, overlayGetWidth() / 2, overlayGetHeight() / 2, true)
    return OVERLAY_UPDATED
end

2.13.6. fontUnload

fontUnload(id)

Closes a font and invalidates its handle. Sprites made from it with fontToSprite are unaffected. If the unloaded font was the selected one, no font is selected afterward and the next fontPrint or fontToSprite ends the script with an error until fontSelect or fontLoad picks another.

Since: 2.00 See also: fontLoad, fontSelect, onShutdown

Example
-- Release the fonts and the text sprites they produced.
function onShutdown()
    spriteUnload(titleSprite)
    for _, line in ipairs(descriptionLines) do
        spriteUnload(line)
    end
    fontUnload(titleFont)
    fontUnload(hudFont)
end

2.14. Gui

A GUI is an RmlUi document tree of a fixed size rendered into its own texture every frame: guiNew makes one and returns an integer handle, guiLoad puts an RML document in it and returns a document handle, guiDraw composites it over the overlay and materialSetGui shows it on a material in the scene. Documents are HTML-like RML styled by CSS-like RCSS, loaded through the virtual file system like sprites; Singe/gui.rcss is the shipped theme and Singe/FreeSansBold.ttf the fallback face. The by-id helpers guiGetValue, guiSetValue and guiSetHandler reach elements without the object model; everything else is RmlUi’s Lua API on the rmlui global, where a GUI is the context named gui followed by its handle. Up to sixteen GUIs exist at once, each with thirty-two documents. A GUI needs the GPU device, so guiNew ends the script on a machine without one; a bad GUI handle raises No GUI N, and a bad document handle No document N in GUI G. See GUI in Game Development.

2.14.1. guiClose

guiClose(gui, document)

Unloads the document from the GUI, dropping its elements, its handlers and its scripts. The document handle is invalid afterwards. A document closed by its own script through RmlUi’s API (document:Close()) is unloaded the same way. Raises No document N in GUI G for a handle that is not valid.

Since: 3.00. See also: guiLoad, guiHide, guiDelete

Example
-- The high score entry page is only needed once; drop it after the name is in.
guiSetHandler(gui, entryPage, "enter", "click", function(g, d)
    scores[#scores + 1] = { name = guiGetValue(g, d, "name"), score = score }
    guiClose(g, d)
    entryPage = nil
end)

2.14.2. guiDelete

guiDelete(gui)

Frees the GUI, every document in it and its texture, and stops the per-frame update and render it cost. Materials showing it through materialSetGui go back to their own texture. The handle is invalid afterwards and ends the script if used again; since a GUI keeps rendering whether or not it is drawn, delete the ones a game is finished with rather than hiding them.

Since: 3.00. See also: guiNew, guiClose, materialSetGui

Example
-- The options page lives only while the player is in it.
function closeOptions()
    guiDelete(optionsGui)
    optionsGui = nil
    discPlay()
end

2.14.3. guiDraw

guiDraw(gui)
guiDraw(gui, x, y)
guiDraw(gui, x, y, width, height)

Composites the GUI’s texture over the overlay for this frame, in overlay coordinates, so it obeys the Sinden border and the overscan scale like everything else on the overlay: covering the whole overlay with one argument, at its own size with a corner at x, y, or scaled into the width by height rectangle. The call’s place in the script’s drawing decides what is under the GUI and what is over it: everything drawn on the overlay before it stays underneath, and everything drawn after it — until the next guiDraw, or the script’s next turn — goes on a layer of its own composited over that GUI. A pointer drawn after the HUD is drawn over the HUD; a second document drawn after that sits over the pointer, with its own layer above. Up to sixteen such layers a frame; a call past that draws its GUI with nothing over it. overlayClear clears whichever layer is being drawn on, and overlaySetMonochrome grays the base overlay only. The call lasts one frame; make it from onOverlayUpdate (or singeMain) every frame the GUI should be visible. GUIs draw above the overlay in the order called (the last on top), under PARTICLE_OVER particles and the pause indicator, and the GUI drawn last under the pointer is the one that receives the mouse. Up to sixteen calls are honored per frame; more are ignored. Any other argument count raises Expected 1, 3 or 5 arguments.

Parameters:

  • x, y — the top left corner, in overlay coordinates.

  • width, height — the size to draw at, in overlay pixels; the GUI’s own size when left out.

Since: 3.00. See also: guiNew, materialSetGui, overlaySetResolution

Example
-- The HUD sits in the bottom right corner at a third of the overlay's width, and the gun's
-- sight is drawn after it, so the sight is never hidden by the panel.
function onOverlayUpdate()
    overlayClear()
    guiSetValue(hud, hudPage, "lives", tostring(lives))
    guiDraw(hud, overlayGetWidth() * 0.66, overlayGetHeight() * 0.8, overlayGetWidth() * 0.33, overlayGetHeight() * 0.2)
    local x, y = mouseGetPosition(0)
    spriteDraw(sight, x, y, true)
    return OVERLAY_UPDATED
end

2.14.4. guiDrawScreen

guiDrawScreen(gui)
guiDrawScreen(gui, x, y)
guiDrawScreen(gui, x, y, width, height)

The same as guiDraw, except that the rectangle is measured across the whole window instead of across the picture. The coordinates are still overlay coordinates — 0, 0 is the top left of the window and overlayGetWidth(), overlayGetHeight() the bottom right — so a GUI can sit on the bezel artwork beside the picture, above it, or below it. With no bezel, and with no --scalefactor, --shiftx or --shifty, the picture is the whole window and this is exactly guiDraw.

Screen space GUIs draw after everything else, the bezel artwork included, and share the sixteen draws a frame with guiDraw. A click finds them the same way: the pointer is carried into screen space before it is tested, so a screen space GUI that takes input receives the mouse wherever it was drawn.

Parameters:

  • x, y — the top left corner, in overlay coordinates measured across the window.

  • width, height — the size to draw at; the GUI’s own size when left out.

Since: 3.00. See also: guiDraw, Bezels, scoreBezelEnable

Example
-- A map on the left hand pillar of the cabinet artwork, outside the picture.
function onOverlayUpdate()
    overlayClear()
    guiDrawScreen(mapGui, 8, 44, 38, 114)
    return OVERLAY_UPDATED
end

2.14.5. guiGetHeight

height = guiGetHeight(gui)

The GUI’s height in its own pixels, as given to guiNew. Ends the script for a handle that is not valid.

Returns: An integer.

Since: 3.00. See also: guiGetWidth, guiNew

Example
-- Center a small dialog on the overlay.
local x = (overlayGetWidth() - guiGetWidth(dialog)) / 2
local y = (overlayGetHeight() - guiGetHeight(dialog)) / 2
guiDraw(dialog, x, y)

2.14.6. guiGetStats

stats = guiGetStats()

What rendering every GUI cost in the last completed frame, for tuning documents that use filters, masks and shadows (each of which draws through a layer the size of the GUI). The counters cover all GUIs together. They are all zero on a frame where no GUI’s picture changed, since nothing was redrawn (see guiRefresh).

Returns: A table with the fields drawCalls (indexed draws, including mask writes, composites and filter passes), layerPushes (layers entered for filters, mask images and box shadows), filterPasses (full-size passes and blits inside filter chains; a blur costs several), maskWrites (draws into the stencil clip mask), layerBytes (bytes of layer textures currently allocated; each is the size of its GUI at four bytes a pixel) and passes (render passes begun; every layer switch begins one).

Since: 3.00. See also: guiNew, GUI

Example
-- Watch what a screen full of effects costs.
local s = guiGetStats()
debugPrint(string.format("gui draws %d layers %d filters %d passes %d, %d KB of layers", s.drawCalls, s.layerPushes, s.filterPasses, s.passes, s.layerBytes // 1024))

2.14.7. guiGetValue

value = guiGetValue(gui, document, id)

The value of the element with that id in the document, as a string: a form control’s value (a text field’s text, a select option’s value, a range in RmlUi’s own formatting such as "85.000000", a checkbox’s or radio button’s value attribute, "on" when it has none, whether or not it is checked; its state is its checked attribute, read through RmlUi’s API), or, for any other element, its inner RML. Returns nil when no element has that id, so a page can be probed without ending the script; a bad GUI or document handle ends it. Values longer than 4095 characters are cut.

Returns: A string, or nil.

Since: 3.00. See also: guiSetValue, guiSetHandler

Example
-- Read the whole form when Start is pressed.
guiSetHandler(gui, doc, "go", "click", function(g, d)
    player.name  = guiGetValue(g, d, "name")
    player.hard  = guiGetValue(g, d, "difficulty") == "hard"
    player.volume = math.floor(tonumber(guiGetValue(g, d, "volume")))
end)

2.14.8. guiGetWidth

width = guiGetWidth(gui)

The GUI’s width in its own pixels, as given to guiNew. Ends the script for a handle that is not valid.

Returns: An integer.

Since: 3.00. See also: guiGetHeight, guiNew

Example
-- Is the probed point in the right half of the monitor's page?
local g, px, py = sceneProbeGui(mouseX, mouseY)
if g ~= nil and px > guiGetWidth(g) / 2 then
    showRightTooltip()
end

2.14.9. guiHide

guiHide(gui, document)

Hides the document: it is not drawn and takes no input, but it keeps its elements and values and guiShow brings it back as it was. Raises No document N in GUI G for a handle that is not valid.

Since: 3.00. See also: guiShow, guiClose

Example
-- Two pages in one GUI: the options page hides while the controls page shows.
guiSetHandler(gui, options, "controls", "click", function()
    guiHide(gui, options)
    guiShow(gui, controls)
end)

2.14.10. guiLoad

document = guiLoad(gui, filename)

Loads an RML document into the GUI, shows it, and returns an integer document handle for the other calls. The name goes through the virtual file system like a sprite’s, resolved relative to the directory Singe was started in, so prepend DIR for files shipped with your game; style sheets, images and fonts named inside the document resolve relative to the file that names them and then through the same lookup, so a packed game finds them. The document’s <script> blocks and on* attributes run on the game’s Lua state, and it is reachable as rmlui.contexts["guiN"].documents["<body id>"]. A document that cannot be loaded ends the script with the name and RmlUi’s reason (a missing file, a parse error); RmlUi’s own warnings about the markup and style go to the console. Each GUI holds up to thirty-two documents.

Returns: The document handle, an integer.

Since: 3.00. See also: guiNew, guiShow, guiHide, guiClose, guiLoadFont

Example
-- The title page and the HUD share one GUI the size of the overlay.
gui   = guiNew(overlayGetWidth(), overlayGetHeight())
title = guiLoad(gui, DIR .. "gui/title.rml")
hud   = guiLoad(gui, DIR .. "gui/hud.rml")
guiHide(gui, hud)

2.14.11. guiLoadFont

guiLoadFont(filename)
guiLoadFont(filename, fallback)

Loads a TrueType or OpenType face for every GUI, so documents can name it by the family name inside the file in font-family (with font-weight and font-style picking among the faces of one family). With fallback true the face also serves any glyph no other face has, which is what the engine’s own Singe/FreeSansBold.ttf does until then (family FreeSans, weight bold, the face the shipped theme uses). Load fonts before the documents that use them. Each face costs a glyph atlas per size it is used at. A file that cannot be opened ends the script with Unable to load and the name.

Parameters:

  • filename — the font file, through the virtual file system like fontLoad.

  • fallback — true to make this the fallback face; false (the default) for an ordinary face.

Since: 3.00. See also: guiLoad, fontLoad

Example
-- The game's display face for headings; the shipped FreeSans stays for body text.
guiLoadFont(DIR .. "fonts/Orbitron-Bold.ttf")
gui  = guiNew(overlayGetWidth(), overlayGetHeight())
menu = guiLoad(gui, DIR .. "gui/menu.rml")

2.14.12. guiNew

gui = guiNew(width, height)

Makes a GUI width by height pixels, rendered into its own texture every frame whether or not it is drawn, and returns its handle. The size is the document’s coordinate space: 100% of the body is the whole texture, and a dp is one of its pixels. A GUI the size of the overlay suits a full screen page; a HUD element or a monitor in the scene wants a smaller one, and a Raspberry Pi wants everything modest. A new GUI only displays until guiSetInput turns input on. Raises The size must be positive for a zero or negative size, and No GUI available when sixteen are already in use or the machine has no GPU device (a GUI needs the same device as the 3D scene).

Parameters:

  • width — the texture’s width in pixels.

  • height — the texture’s height in pixels.

Returns: The GUI handle, an integer.

Since: 3.00. See also: guiLoad, guiDraw, guiDelete, materialSetGui

Example
-- A page the size of the overlay, drawn over the disc.
overlaySetResolution(discGetWidth(), discGetHeight())
gui = guiNew(overlayGetWidth(), overlayGetHeight())
doc = guiLoad(gui, DIR .. "gui/attract.rml")

function onOverlayUpdate()
    overlayClear()
    guiDraw(gui)
    return OVERLAY_UPDATED
end

2.14.13. guiRefresh

guiRefresh(gui)

Draws the GUI again on the next frame even if nothing about it seems to have changed. A GUI is only redrawn when its picture changes: when a frame’s document draws exactly what the last frame drew, and nothing new was made in between, the texture already holds that picture and is kept, which saves the GPU most of a GUI’s cost on the frames a HUD or a menu stands still. Changes made through RML, RCSS, the RmlUi Lua interface or the gui* calls are all seen. This call is the way out should one ever be missed — a GUI that stops updating when it should — and a game should not need it; if it does, that is worth reporting. A GUI that does not exist ends the script.

Since: 3.00. See also: guiDraw, guiGetStats

Example
-- A workaround while a missed change is reported:  redraw the HUD every frame.
function onOverlayUpdate()
    guiRefresh(hud)
    guiDraw(hud)
    return OVERLAY_UPDATED
end

2.14.14. guiSetHandler

guiSetHandler(gui, document, id, event, function)
guiSetHandler(gui, document, id, event, nil)

Calls function(gui, document, id, event, value) whenever the element with that id fires the named event: "click" for buttons and rows, "change" for form controls, "submit" for a form, or any other RmlUi event name ("focus", "mouseover", "keydown", …​). value is the element’s value at that moment as a string, as guiGetValue would return it (a range comes as RmlUi formats it, "85.000000", so pass it through tonumber). One function is kept per element and event; setting another replaces it, and nil removes it. The handler belongs to the id, not to one element: when the element is replaced — a list rebuilt through inner_rml makes new elements — set the handler again after the rebuild and it attaches to the element that carries the id now. Handlers run as the events happen, between the game’s own callbacks, and an error in one ends the game like an error in any callback. Ids are at most 63 characters. Raises No element "id" in document N of GUI G when the element does not exist, and Argument 5 must be a function or nil for anything else in that place.

Parameters:

  • id — the element’s id attribute.

  • event — the RmlUi event name.

  • function — the Lua function to call, or nil to stop calling one.

Since: 3.00. See also: guiGetValue, guiSetValue, guiSetInput

Example
-- A volume slider takes effect as it moves; Start reads the rest of the form.
guiSetHandler(gui, doc, "volume", "change", function(g, d, id, event, value)
    soundSetVolume(math.floor(tonumber(value)))
end)

guiSetHandler(gui, doc, "go", "click", function(g, d)
    startGame(guiGetValue(g, d, "name"), guiGetValue(g, d, "difficulty"))
end)

2.14.15. guiSetInput

guiSetInput(gui, enabled)

Whether the mouse and light gun, keys, typed text and the framework switches from a pad or mouse reach the GUI. A new GUI only displays, which suits a HUD or a sign; turn input on for a menu or a form. While it is on, the pointer reaches the GUI wherever it is drawn flat (the last drawn on top) or shown on a surface in the scene, every key goes to it except Tab, which the GUI is given only while a text field is being typed in (RmlUi uses it to move focus and never hands it back, and a game whose keys include Tab would otherwise lose it), a text field with focus turns on SDL’s text input, and the pad’s directions arrive as arrow keys with ACTION_1 as Return and ACTION_2 as Escape. What an element uses never reaches onInputPressed, onKeyPressed or the mouse callbacks; what nothing used falls through to them as usual. Ends the script for a handle that is not valid.

Since: 3.00. See also: guiSetHandler, guiDraw, sceneProbeGui

Example
-- The HUD never takes input; the pause page does while it is up.
guiSetInput(hud, false)

function onInputPressed(what)
    if what == SWITCH_START1 then
        guiShow(gui, pausePage)
        guiSetInput(gui, true)
        singeSetPauseFlag(true)
    end
end

2.14.16. guiSetValue

guiSetValue(gui, document, id, value)

Sets the value of the element with that id: a form control’s value (a text field’s text, a range’s number, a select option’s value; a checkbox’s checked state is an attribute, set through RmlUi’s API), or, for any other element, its inner RML, so a paragraph or a div can be rewritten with plain text or with markup. The document lays itself out again on the next frame. Raises No element "id" in document N of GUI G when the element does not exist.

Parameters:

  • id — the element’s id attribute.

  • value — the new value, a string; numbers are converted.

Since: 3.00. See also: guiGetValue, guiSetHandler

Example
-- The score line and the lives row are rewritten every frame; the row is markup.
function onOverlayUpdate()
    guiSetValue(hud, hudPage, "score", string.format("%08d", score))
    guiSetValue(hud, hudPage, "lives", string.rep("<img src=\"ship.png\"/>", lives))
    overlayClear()
    guiDraw(hud)
    return OVERLAY_UPDATED
end

2.14.17. guiShow

guiShow(gui, document)

Shows a document hidden by guiHide (a document is shown when guiLoad returns, so the call is not needed then). A shown document is drawn wherever its GUI is and takes input when its GUI does. Raises No document N in GUI G for a handle that is not valid.

Since: 3.00. See also: guiHide, guiLoad

Example
-- The game over page comes up when the last life goes.
function onLastLifeLost()
    guiSetValue(gui, gameOver, "final", string.format("%08d", score))
    guiShow(gui, gameOver)
end

2.15. Joint

Joints connect two bodies, or a body and the world when the second node is -1, and hand back an integer joint handle that the other calls take. Anchors and axes are given in world space at the moment the joint is made, with the bodies where they are then, so place the nodes and give them bodies before jointing them. Distances are in world units and hinge angles in degrees. Deleting either body, or its node, deletes the joint; a handle that has been deleted ends the script when passed back. See Physics in Game Development, Joints.

2.15.1. jointHinge

joint = jointHinge(nodeA, nodeB, ax, ay, az, dx, dy, dz)

Makes a hinge between the two bodies through the world point (ax, ay, az) along the axis (dx, dy, dz): a door, a wheel, a lever, a seesaw. The bodies keep that point and axis in common and may only turn about it. The axis is normalized, so its length does not matter; a zero axis becomes (0, 1, 0). Both nodes must carry a body, or nodeB may be -1 to hinge nodeA to the world. Ends the script when a node has no body or the joint cannot be made.

Parameters:

  • nodeA — the body whose turn is measured; a positive jointSetLimits angle is its right-hand turn about the axis.

  • nodeB — the other body, or -1 for the world.

  • ax, ay, az — the anchor, a world point the hinge axis passes through.

  • dx, dy, dz — the hinge axis in world space.

Returns: The joint handle.

Since: 3.00. See also: jointSetLimits, jointDelete, jointBall

Example
-- A door hinged to the world along its left edge, opening 100 degrees one way.
door = nodeNew()
nodeSetMesh(door, meshBox(1.4, 2.2, 0.1), wood)
nodeSetPosition(door, -0.1, -0.62, 1.4)
bodyNew(door, BODY_DYNAMIC, SHAPE_BOX, 1.4, 2.2, 0.1)
bodySetMass(door, 8)
hinge = jointHinge(door, -1, -0.85, -0.62, 1.4, 0, 1, 0)
jointSetLimits(hinge, 0, 100)
-- Later, a shove near the handle swings it open.
bodyApplyImpulse(door, 0, 0, -60, 0.5, -0.62, 1.45)

2.15.2. jointBall

joint = jointBall(nodeA, nodeB, ax, ay, az)

Makes a ball-and-socket joint at the world point (ax, ay, az): the bodies may turn any way about it but cannot separate. A pendulum, a chain link, a hanging sign, a ragdoll shoulder. Both nodes must carry a body, or nodeB may be -1 to hang nodeA from a fixed point in the world. A ball joint has no limits, so jointSetLimits refuses it. Ends the script when a node has no body or the joint cannot be made.

Parameters:

  • nodeA — the first body.

  • nodeB — the other body, or -1 for the world.

  • ax, ay, az — the anchor, the world point the bodies pivot about.

Returns: The joint handle.

Since: 3.00. See also: jointHinge, jointDelete, bodyApplyImpulse

Example
-- A chain of four links hanging from a hook, each balled to the one above.
local above = -1
for i = 1, 4 do
    local link = nodeNew()
    nodeSetMesh(link, meshSphere(0.12, 16), iron)
    nodeSetPosition(link, 2, 3 - i * 0.3, 0)
    bodyNew(link, BODY_DYNAMIC, SHAPE_SPHERE, 0.12)
    bodySetMass(link, 1)
    jointBall(link, above, 2, 3.15 - i * 0.3, 0)
    above = link
end

2.15.3. jointSlider

joint = jointSlider(nodeA, nodeB, ax, ay, az, dx, dy, dz)

Lets the bodies slide relative to each other only along the axis (dx, dy, dz) through the anchor (ax, ay, az), keeping their orientation: a drawer, a piston, a lift, a sliding door. The axis is normalized, so its length does not matter; a zero axis becomes (0, 1, 0). Both nodes must carry a body, or nodeB may be -1 to run nodeA along a rail fixed in the world. Ends the script when a node has no body or the joint cannot be made.

Parameters:

  • nodeA — the body whose travel is measured; a positive jointSetLimits distance is along the axis.

  • nodeB — the other body, or -1 for the world.

  • ax, ay, az — a world point on the rail.

  • dx, dy, dz — the direction of travel in world space.

Returns: The joint handle.

Since: 3.00. See also: jointSetLimits, jointHinge, bodySetVelocity

Example
-- A crate on a rail along X, pushed sideways at the start and stopped 2.4 units on.
crate = nodeNew()
nodeSetMesh(crate, meshBox(0.5, 0.5, 0.5), wood)
nodeSetPosition(crate, -0.6, 0.9, -3.0)
bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.5, 0.5, 0.5)
slider = jointSlider(crate, -1, -0.6, 0.9, -3.0, 1, 0, 0)
jointSetLimits(slider, 0, 2.4)
bodySetVelocity(crate, 3, 0, 0)

2.15.4. jointSetLimits

jointSetLimits(joint, low, high)

Bounds a hinge’s angle in degrees, or a slider’s travel in world units, either side of where the joint started. A positive hinge angle is a right-hand turn of nodeA about the axis; a positive slider distance is along the axis. low is clamped to at most 0 and high to at least 0, so the starting pose is always inside the range. Call it again to change the range at any time. Ends the script for a ball joint or a handle that no longer exists.

Parameters:

  • joint — the handle from jointHinge or jointSlider.

  • low — the farthest negative angle or distance, 0 or below.

  • high — the farthest positive angle or distance, 0 or above.

Notes: The two bodies swap roles if they are given the other way round, which mirrors the sign of the range.

Since: 3.00. See also: jointHinge, jointSlider

Example
-- A lever that rocks 30 degrees each way, then locks once the puzzle is solved.
lever = nodeNew()
nodeSetMesh(lever, meshBox(0.1, 0.8, 0.1), iron)
nodeSetPosition(lever, 4, 1.2, 0)
bodyNew(lever, BODY_DYNAMIC, SHAPE_BOX, 0.1, 0.8, 0.1)
pivot = jointHinge(lever, -1, 4, 0.8, 0, 0, 0, 1)
jointSetLimits(pivot, -30, 30)

function lockLever()
    jointSetLimits(pivot, 0, 0)
end

2.15.5. jointDelete

jointDelete(joint)

Removes the joint; the bodies are free of each other again and keep whatever velocity they had. Joints also go away with either of their bodies, so this is only needed to free two bodies that both stay. Ends the script for a handle that does not exist or was already deleted.

Since: 3.00. See also: jointHinge, jointBall, bodyDelete

Example
-- The rope snaps when the crate hanging from it is hit hard enough.
function onCollision(a, b, x, y, z, speed)
    if (a == crate or b == crate) and speed > 6 and rope then
        jointDelete(rope)
        rope = nil
        soundPlay(snap)
    end
end

2.16. Joystick

Every controller Singe opens is a gamepad and is read through the controller* calls; a device SDL does not recognize reaches them through a mapping Singe writes for it, so there is nothing else to call. See Every Device Is a Gamepad. The two calls here are about letting a stick stand in for a mouse.

2.16.1. joyMouseEnable

joyMouseEnable(enabled)

Hypseus extension. Turns joystick-to-mouse on or off while the game runs. With it on, the left stick of gamepad slot 0 drives the pointer the game sees, through the same onMouseMoved a real mouse reaches, held inside the picture; --js_range is the speed and the axis obeys its own dead zone. It is what makes a light gun game playable on a cabinet with a stick and no mouse.

It starts from --joymouse, which is off by default, and a singeReload puts it back there. Singe differs from Hypseus in that default: the shipped controls.cfg already binds that stick to the four direction switches, and driving the cursor as well without being asked would surprise every existing game.

Parameters:

  • enabled — boolean.

Returns: nothing.

Since: 3.00 (Hypseus) See also: joyMouseIsEnabled, onMouseMoved, mouseGetPosition

Example
-- A gun game that lets the player aim with the stick when no mouse is plugged in.
if mouseHowMany() == 0 then
    joyMouseEnable(true)
end

2.16.2. joyMouseIsEnabled

enabled = joyMouseIsEnabled()

Whether the stick is driving the mouse cursor right now, whether that was decided by --joymouse or by joyMouseEnable.

Returns: boolean.

Since: 3.00 See also: joyMouseEnable

2.17. Keyboard

Singe reads the keyboard in one of two modes chosen with keyboardSetMode. In MODE_NORMAL (the default) keys are translated through the mappings in controls.cfg into the SWITCH_* values that reach onInputPressed and onInputReleased, and unmapped keys are ignored; in MODE_FULL every key reaches the script raw, through onKeyPressed and onKeyReleased as well as onInputPressed and onInputReleased. Whatever the mode, keyboardIsDown, keyboardGetLastDown and keyboardGetLastUp poll the live keyboard state, which is what the threaded model wants (see Threaded). A scancode names a physical key position (the A key is scancode 4 on every layout) while a keysym is the character the key produces; the SCANCODE table in Framework.singe names every scancode, keyboardIsDown takes scancodes, and onKeyPressed delivers both. The callbacks themselves are described under Engine Callbacks.

2.17.1. keyboardCatchQuit

keyboardCatchQuit(catch)

Hypseus extension. Hands the quit switch to the script, exactly as singeSetQuitKeyEnabled(not catch) does: keyboardCatchQuit(true) stops the engine quitting on INPUT_QUIT, and false returns it. It is a function defined in Framework.singe, kept so games written for Hypseus Singe run unchanged.

Notes: Legacy alias.

New code should call singeSetQuitKeyEnabled.

Since: 3.00, as a Hypseus Singe extension. See also: singeSetQuitKeyEnabled, singeQuit

Example
-- Hypseus game code; the modern spelling is singeSetQuitKeyEnabled(false).
if keyboardCatchQuit ~= nil then
    keyboardCatchQuit(true)
end

function onInputPressed(what)
    if what == SWITCH_QUIT then
        askToQuit()
    end
end

2.17.2. keyboardGetLastDown

scancode = keyboardGetLastDown()

Returns the scancode of the key pressed most recently in the current frame, or 0 when nothing has been pressed since the last frame. The value is cleared after every onOverlayUpdate call, which makes it a one-shot "was a key just pressed" poll for the threaded model. Controller and mouse buttons are recorded here too, as their GAMEPAD_N and MOUSE_N codes, since the engine routes them through the same path as keys. The value is kept regardless of keyboard mode and of the controls.cfg mappings.

Returns: integer scancode, or 0.

Since: 2.10 See also: keyboardGetLastUp, keyboardIsDown

Example
-- Threaded model: react to one key press per frame.
function singeMain()
    while true do
        local key = keyboardGetLastDown()
        if key == SCANCODE.ESCAPE.value then
            singeQuit()
        elseif key == SCANCODE.SPACE.value then
            jump()
        end
        singeYield()
    end
end

2.17.3. keyboardGetLastUp

scancode = keyboardGetLastUp()

Returns the scancode of the key released most recently in the current frame, or 0 when nothing has been released since the last frame. It is cleared after every onOverlayUpdate call, like keyboardGetLastDown, and records controller and mouse button codes the same way.

Returns: integer scancode, or 0.

Since: 2.10 See also: keyboardGetLastDown, keyboardIsDown

Example
-- A charged shot fires when the fire key is let go.
function singeMain()
    while true do
        if keyboardIsDown(SCANCODE.LCTRL.value) then
            charge = math.min(charge + 1, chargeMax)
        elseif keyboardGetLastUp() == SCANCODE.LCTRL.value then
            fireShot(charge)
            charge = 0
        end
        singeYield()
    end
end

2.17.4. keyboardGetMode

mode = keyboardGetMode()

Returns the keyboard mode in effect: MODE_NORMAL (0) or MODE_FULL (1). Every script starts in MODE_NORMAL, including after a reload.

Returns: integer mode.

Since: 1.x (RDG) See also: keyboardSetMode

Example
-- Shared text-entry helper that restores whatever mode the caller had.
function promptForName()
    local previous = keyboardGetMode()
    keyboardSetMode(MODE_FULL)
    entering = true
    restoreMode = previous
end

2.17.5. keyboardGetModifiers

modifiers = keyboardGetModifiers()

Returns the modifier keys held right now as a bitmask of SDL KMOD_* bits. Test it with a bitwise and against the values in the MODIFIER table: the single-key entries such as MODIFIER.LSHIFT and the combined MODIFIER.SHIFT, MODIFIER.CTRL, MODIFIER.ALT and MODIFIER.GUI, which cover either side. It reads the live state, so it works in every keyboard mode and from any callback.

Returns: integer bitmask.

Since: 2.10 See also: keyboardGetLastDown, onKeyPressed

Example
-- Shift+Tab toggles the statistics overlay.
function onKeyPressed(keysym, scancode)
    if scancode == SCANCODE.TAB.value then
        if keyboardGetModifiers() & MODIFIER.SHIFT.value ~= 0 then
            showStats = not showStats
        end
    end
end

2.17.6. keyboardIsDown

down = keyboardIsDown(scancode)

Tests whether a key is physically held right now, from the state the engine keeps for every key event it sees. It does not depend on the keyboard mode or on controls.cfg, and it works from any callback, so it suits movement that should continue while a key is held. Scancodes outside the range SDL defines return false rather than aborting.

Parameters:

  • scancode — a value from the SCANCODE table, such as SCANCODE.LEFT.value.

Returns: boolean.

Since: 2.10 See also: keyboardGetLastDown, controllerGetButton

Example
-- Eight-way movement from held keys.
function onOverlayUpdate()
    local dx = 0
    local dy = 0
    if keyboardIsDown(SCANCODE.LEFT.value)  then dx = dx - 1 end
    if keyboardIsDown(SCANCODE.RIGHT.value) then dx = dx + 1 end
    if keyboardIsDown(SCANCODE.UP.value)    then dy = dy - 1 end
    if keyboardIsDown(SCANCODE.DOWN.value)  then dy = dy + 1 end
    playerX = playerX + dx * speed
    playerY = playerY + dy * speed
    drawPlayer()
    return OVERLAY_UPDATED
end

2.17.7. keyboardSetMode

keyboardSetMode(mode)

Switches between the two keyboard models. In MODE_NORMAL only keys mapped in controls.cfg reach the script, as SWITCH_* values, key repeat is dropped so each press arrives once, and the engine acts on its own switches (pause, quit, screenshot, mouse grab). In MODE_FULL every key reaches onInputPressed and onInputReleased as its keysym and onKeyPressed and onKeyReleased as keysym and scancode, the text a press produces reaches onTextInput, key repeat is delivered for text entry, and keyboard mappings of the engine’s own switches are ignored so that the game keeps every key; controller and mouse button mappings still act, and those buttons still reach the script as their SWITCH_* values, since they cannot be typed. Most games set the mode once at startup; a game with text entry switches to MODE_FULL for the duration and back. Any other value aborts the script. In MODE_FULL the keysyms of four keys are also switch numbers — Backspace is 8 (SWITCH_BUTTON3), Tab 9 (SWITCH_COIN1), Return 13, and Escape 27 — so a script that reads onInputPressed for a pad or mouse switch and also expects those keys should check keyboardIsDown for the key before treating the value as the switch.

Parameters:

  • mode — MODE_NORMAL (0) or MODE_FULL (1).

Since: 1.x (RDG) See also: keyboardGetMode, onInputPressed, onKeyPressed

Example
-- High score entry takes raw keys, then gameplay mode comes back.
function beginInitials()
    initials = ""
    keyboardSetMode(MODE_FULL)
end

function onKeyPressed(keysym, scancode)
    if scancode == SCANCODE.RETURN.value then
        keyboardSetMode(MODE_NORMAL)
        saveScore(initials, score)
    elseif keysym >= string.byte("a") and keysym <= string.byte("z") and #initials < 3 then
        initials = initials .. string.char(keysym):upper()
    end
end

2.18. Light

Lights are nodes carrying a light, made by lightNew and moved, parented and animated with the node calls. Up to eight visible lights shine in a frame, in node order; sceneSetAmbient and a sky from sceneSetSky add light from everywhere. Directional and spot lights shine down the node’s -Z, so aim them with nodeLookAt or nodeSetRotation; point lights only need a position. Colors are integers from 0 to 255, intensities are multipliers in the scene’s linear light, angles are degrees, and distances are world units. Every lightSet* call ends the script for a node that does not carry a light. See 3D Scenes for lighting, exposure and shadows.

2.18.1. lightNew

node = lightNew(type)
node = lightNew(type, parent)

Makes a new node carrying a light and returns the node handle. The light starts white at intensity 1, with no range limit and, for a spot, a cone of 20 to 30 degrees. Place and aim it with the node calls: nodeSetPosition for a point or spot light, nodeLookAt for a directional or spot light. A light parented to a moving node moves with it, so a headlight on a car or a torch in a hand is one call. Ends the script for an unknown type or when no node can be made.

Parameters:

  • type — LIGHT_DIRECTIONAL (a sun; only its direction matters), LIGHT_POINT (a bulb fading with distance in every direction), or LIGHT_SPOT (a cone down the node’s -Z).

  • parent — the parent node; the root when omitted.

Returns: The light’s node handle, an integer.

Example
-- Warm key light from the upper left, a cool fill from the right,
-- and a headlight that rides with the car.
key = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(key, -3, 4, 3)
nodeLookAt(key, 0, 0, 0)
lightSetColor(key, 255, 235, 200)
lightSetIntensity(key, 1.4)

fill = lightNew(LIGHT_POINT)
nodeSetPosition(fill, 3, 1, 2)
lightSetColor(fill, 150, 190, 255)
lightSetIntensity(fill, 4)
lightSetRange(fill, 10)

headlight = lightNew(LIGHT_SPOT, car)
nodeSetPosition(headlight, 0.6, 0.5, -1.8)
lightSetIntensity(headlight, 30)

2.18.2. lightSetColor

lightSetColor(node, r, g, b)

The light’s color, 0 to 255 per channel (out-of-range values are clamped), treated as sRGB; white by default. Brightness belongs in lightSetIntensity, so keep the color for the hue (a warm 255, 230, 190 bulb, a cool 150, 190, 255 moon) and leave at least one channel near 255. Ends the script when the node carries no light.

Since: 3.00. See also: lightSetIntensity, lightNew

Example
-- The neon sign cycles through its colors.
signLight = lightNew(LIGHT_POINT)
nodeSetPosition(signLight, 2, 3, -1)
lightSetIntensity(signLight, 8)
lightSetRange(signLight, 6)
neon = { { 255, 40, 120 }, { 40, 220, 255 }, { 255, 210, 40 } }

function onOverlayUpdate()
    local phase = math.floor(singeGetTicks() / 700) % #neon + 1
    lightSetColor(signLight, neon[phase][1], neon[phase][2], neon[phase][3])
    return OVERLAY_UPDATED
end

2.18.3. lightSetCone

lightSetCone(node, innerDegrees, outerDegrees)

The shape of a spot light’s cone, both angles measured from the axis (the node’s -Z): full brightness within innerDegrees, fading smoothly to nothing at outerDegrees. The defaults are 20 and 30. A narrow gap between the two gives a hard-edged theater spot, a wide one a soft pool. The values are stored for every light but only a LIGHT_SPOT uses them. Ends the script when the node carries no light.

Parameters:

  • node — the light’s node.

  • innerDegrees — half angle of full brightness, in degrees from the axis.

  • outerDegrees — half angle where the light reaches nothing, in degrees from the axis; raised to innerDegrees when smaller.

Since: 3.00. See also: lightNew, lightSetRange, nodeLookAt

Example
-- A stage spot on the singer, hard edged, from the lighting rig.
spot = lightNew(LIGHT_SPOT)
nodeSetPosition(spot, 0, 8, 4)
nodeLookAt(spot, nodeGetWorldPosition(singer))
lightSetColor(spot, 255, 245, 220)
lightSetIntensity(spot, 80)
lightSetCone(spot, 8, 10)
lightSetShadow(spot, true)

2.18.4. lightSetIntensity

lightSetIntensity(node, intensity)

The light’s brightness multiplier in the scene’s linear light, default 1. A directional light of intensity 1 lights a white surface facing it to white. A point or spot light fades with distance as 1 / (1 + d^2), so its intensity is the brightness at the light itself, half of it one unit away and a hundredth ten units away; bulbs usually want values well above 1, 10 to 50 for a room, and sceneSetExposure brings the whole scene back into range. Ends the script when the node carries no light.

Since: 3.00. See also: lightSetRange, sceneSetExposure, lightSetColor

Example
-- A lantern that flickers in the wind.
lantern = lightNew(LIGHT_POINT, lanternNode)
lightSetColor(lantern, 255, 200, 140)
lightSetRange(lantern, 9)

function onOverlayUpdate()
    local flicker = 10 + math.random() * 3
    lightSetIntensity(lantern, flicker)
    return OVERLAY_UPDATED
end

2.18.5. lightSetRange

lightSetRange(node, range)

How far a point or spot light reaches, in world units; 0 (the default) means no limit. The light fades to exactly nothing at the range, on top of its distance falloff, so lights do not pop as objects cross it. A range also bounds how far a shadow-casting light’s shadow map has to reach, which keeps its shadows sharp. Directional lights ignore it. Ends the script when the node carries no light.

Since: 3.00. See also: lightSetIntensity, lightSetShadow

Example
-- Street lamps down the road, each lighting its own stretch.
for i = 0, 9 do
    local lamp = lightNew(LIGHT_POINT)
    nodeSetPosition(lamp, 4, 5, -i * 20)
    lightSetColor(lamp, 255, 220, 170)
    lightSetIntensity(lamp, 20)
    lightSetRange(lamp, 14)
end

2.18.6. lightSetShadow

lightSetShadow(node, shadow)

Makes the light cast shadows from everything opaque in the scene, or stops it; off by default. Any of the eight lights may cast, in any mix. A spot light gets one shadow map; a directional light gets one map per cascade (sceneSetShadowCascades); a point light gets a cube map of six views, which covers every direction (a bulb inside a room) at six times the cost. nodeSetShadow excuses a mesh from casting. Ends the script when the node carries no light.

Notes: Each shadow map costs one extra pass over the scene per frame, a cube map six, and a cascaded sun as many as it has cascades; the maps' size is set by sceneSetShadowSize. A modern integrated GPU manages eight casters comfortably; a Raspberry Pi wants one or two at 512.

Example
-- The sun casts shadows; the lamps only light.  The bulb's own glass
-- must not shadow its lamp.
sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 3, 6, 4)
nodeLookAt(sun, 0, 0, 0)
lightSetShadow(sun, true)

lamp = lightNew(LIGHT_POINT)
nodeSetPosition(lamp, 3, 3.1, -2)
lightSetIntensity(lamp, 12)
lightSetRange(lamp, 14)
nodeSetShadow(bulbGlass, false)

2.19. Material

A material is how a mesh looks: a base color with alpha, an optional base texture from a sprite, a KTX2 file, a video or a rendered view, and the glTF metallic-roughness parameters with four optional maps. materialNew returns an integer handle; pass it to nodeSetMesh or nodeSetMaterial, and to every materialSet* call. Materials are shared, so changing one changes every mesh drawn with it, and a node without one draws white and half rough. Colors are integers from 0 to 255 per channel and are treated as sRGB; factors such as roughness run from 0 to 1. A bad handle ends the script. See 3D Scenes for how materials are lit.

2.19.1. materialNew

material = materialNew()

Allocates a new material and returns its handle. It starts white and opaque (color 255, 255, 255, 255), with roughness 0.5, metallic 0, no emissive color, tiling 1, 1, linear filtering, single sided, lit, and no texture or maps. Set what differs from that and hand the handle to nodeSetMesh. Loaded models bring their own materials, so this is for meshes built from script. Ends the script on a machine with no usable GPU.

Returns: The material handle, an integer.

Example
-- Brushed gold for a trophy, translucent blue glass for its case.
gold = materialNew()
materialSetColor(gold, 255, 200, 60)
materialSetMetallic(gold, 1)
materialSetRoughness(gold, 0.35)

glass = materialNew()
materialSetColor(glass, 80, 160, 255, 90)
materialSetBlend(glass, true)
materialSetRoughness(glass, 0.1)

trophy = nodeNew()
nodeSetMesh(trophy, meshCone(0.3, 0.8, 24), gold)

2.19.2. materialDelete

materialDelete(material)

Frees the material and any texture it uploaded. Every node that was drawn with it falls back to the default look (white, half rough), so reassign those nodes with nodeSetMaterial first if they should keep a look. The handle is invalid afterwards and ends the script if used again. The private material a node makes for itself under nodeSetSprite or nodeSetText belongs to the node and cannot be deleted; the call ends the script, and clearing the sprite or text frees it. Materials are cheap; deleting them matters mostly for ones that carried large textures.

Since: 3.00. See also: materialNew, nodeSetMaterial

Example
-- Swap the level's ground look when the season changes.
function setSeason(texture)
    local look = materialNew()
    materialSetTexture(look, texture)
    materialSetTiling(look, 16, 16)
    nodeSetMaterial(ground, look)
    if groundLook then
        materialDelete(groundLook)
    end
    groundLook = look
end

2.19.3. materialSetBlend

materialSetBlend(material, blend)

When true the material is drawn translucent, blending by the base color’s alpha multiplied by the texture’s alpha, after every opaque mesh and sorted farthest first. Blended meshes do not write depth, so leave it false (the default) for solid surfaces: an opaque mesh with blending on can show things behind it drawing through. Use it with an alpha below 255 from materialSetColor or a texture with transparency.

Since: 3.00. See also: materialSetColor, materialSetTexture

Example
-- A force field that fades in when it is hit.
field = materialNew()
materialSetColor(field, 60, 200, 255, 0)
materialSetBlend(field, true)
materialSetDoubleSided(field, true)
nodeSetMesh(shield, meshSphere(2, 32), field)

function onShieldHit()
    materialSetColor(field, 60, 200, 255, 160)
end

2.19.4. materialSetColor

materialSetColor(material, r, g, b)
materialSetColor(material, r, g, b, a)

Sets the base color, 0 to 255 per channel (out-of-range values are clamped), with a defaulting to 255. The color is treated as sRGB and lit in linear light. When the material has a texture, video or view, the color multiplies it, so white leaves the picture as is and a darker color tints it. The alpha only shows through with materialSetBlend.

Parameters:

  • material — the material handle.

  • r, g, b — red, green and blue, 0 to 255.

  • a — opacity, 0 to 255; 255 when omitted.

Example
-- Team colors on the one car mesh.
teamLooks = {}
for team, rgb in ipairs({ { 220, 40, 40 }, { 40, 90, 220 }, { 240, 200, 30 } }) do
    local look = materialNew()
    materialSetColor(look, rgb[1], rgb[2], rgb[3])
    materialSetMetallic(look, 0.6)
    materialSetRoughness(look, 0.3)
    teamLooks[team] = look
end
nodeSetMesh(playerCar, carMesh, teamLooks[1])

2.19.5. materialSetCutoff

materialSetCutoff(material, cutoff)

Discards every texel whose alpha falls below cutoff and draws the rest fully opaque, in the lit pass and the shadow pass alike, so a leaf card casts the shadow of its leaves rather than of its quad. This is glTF’s alpha masking: unlike materialSetBlend it needs no sorting, but a texel is kept whole or dropped, never blended. The cutoff is clamped to 0 through 1, and 0, the default, turns masking off. A model loaded from glTF arrives with the cutoff its file gives a MASK material.

Parameters:

  • material — integer material handle.

  • cutoff — number; the alpha, 0 to 1, a texel needs to be drawn.

Example
-- A chain-link fence:  one textured quad, the holes cut out, both sides drawn.
fence = materialNew()
materialSetTexture(fence, spriteLoad(DIR .. "Art/chainLink.png"))
materialSetCutoff(fence, 0.5)
materialSetDoubleSided(fence, true)
panel = nodeNew()
nodeSetMesh(panel, meshPlane(4, 2), fence)
nodeSetPosition(panel, 0, 1, -5)
nodeSetRotation(panel, 90, 0, 0)

2.19.6. materialSetDoubleSided

materialSetDoubleSided(material, doubleSided)

Draws both faces of every triangle instead of culling the back face. Needed for open shapes seen from behind, such as a single meshPlane viewed from below, a flag, or a leaf card. Closed shapes look the same either way, so leave it false (the default) for them: a double-sided material costs fill rate and shadows are cast from both faces too.

Since: 3.00. See also: meshPlane, materialSetBlend

Example
-- A banner hanging over the street, readable from both sides.
cloth = materialNew()
materialSetTexture(cloth, spriteLoad(DIR .. "Art/banner.png"))
materialSetDoubleSided(cloth, true)
materialSetRoughness(cloth, 0.9)
banner = nodeNew()
nodeSetMesh(banner, meshPlane(3, 1), cloth)
nodeSetPosition(banner, 0, 4, -6)
nodeSetRotation(banner, 90, 0, 0)

2.19.7. materialSetEmissive

materialSetEmissive(material, r, g, b)

The light the surface gives off on its own, 0 to 255 per channel (out-of-range values are clamped), added on top of the lighting: screens, lamp bulbs, neon, instrument panels. The default is black, no glow. It lights nothing else and casts no light; put a light node at the same place for that. With materialSetEmissiveMap the map says where on the surface this color applies. Emissive surfaces bright enough to pass the threshold of sceneSetBloom glow.

Notes: An unlit material (materialSetUnlit) shows its base color only; the emissive color is ignored on it.

Example
-- A warning lamp that pulses red when the reactor overheats.
lampLook = materialNew()
materialSetColor(lampLook, 60, 10, 10)
nodeSetMesh(lamp, meshSphere(0.15, 16), lampLook)

function onOverlayUpdate()
    local pulse = (math.sin(singeGetTicks() / 120) + 1) / 2
    if overheating then
        materialSetEmissive(lampLook, math.floor(255 * pulse), 20, 20)
    else
        materialSetEmissive(lampLook, 0, 0, 0)
    end
    return OVERLAY_UPDATED
end

2.19.8. materialSetEmissiveMap

materialSetEmissiveMap(material, sprite)
materialSetEmissiveMap(material, "file.ktx2")
materialSetEmissiveMap(material, nil)
materialSetEmissiveMap(material)

A texture saying which parts of the surface glow. Its color is multiplied by the color from materialSetEmissive, so set that too: white to use the map’s own colors, or a tint. The image comes from a loaded sprite (a copy is uploaded, so the sprite may be unloaded afterwards) or from a .ktx2 file by name, kept compressed on the GPU. With nil or no second argument the map is removed. Ends the script when the texture cannot be uploaded or the file is not a KTX2 texture.

Example
-- A control panel whose buttons and readouts light up.
panel = materialNew()
materialSetTexture(panel, spriteLoad(DIR .. "Art/panel.png"))
materialSetEmissiveMap(panel, spriteLoad(DIR .. "Art/panelLights.png"))
materialSetEmissive(panel, 255, 255, 255)
materialSetRoughness(panel, 0.6)
nodeSetMesh(nodeFind("Panel", cockpit), meshPlane(1.2, 0.4), panel)

function onPowerDown()
    materialSetEmissive(panel, 0, 0, 0)
end

2.19.9. materialSetFilter

materialSetFilter(material, filter)

How the material’s textures are sampled. FILTER_LINEAR (the default) blends between texels and between mipmap levels, with anisotropic filtering on surfaces seen at a grazing angle. FILTER_NEAREST picks the closest texel and the closest mipmap level, so pixel art stays crisp on a quad. Every texture carries a full mipmap chain, so a texture seen small never sparkles either way. Any other value ends the script.

Since: 3.00. See also: materialSetTexture, materialSetUnlit

Example
-- A 16 by 16 pixel tile drawn on a block without smearing.
pixelLook = materialNew()
materialSetTexture(pixelLook, spriteLoad(DIR .. "Art/dirt16.png"))
materialSetFilter(pixelLook, FILTER_NEAREST)
materialSetRoughness(pixelLook, 1)
block = nodeNew()
nodeSetMesh(block, meshBox(1, 1, 1), pixelLook)

2.19.10. materialSetGui

materialSetGui(material, gui)
materialSetGui(material, nil)
materialSetGui(material)

Shows a GUI from guiNew as the material’s base color texture, updated every frame: a monitor, a cockpit panel, a sign, with the same document a guiDraw would show flat. Usually paired with materialSetUnlit so the page is not shaded by the lights, and tinted by the base color like any texture. With nil or no second argument the material goes back to its own texture, which is kept underneath; deleting the GUI does the same. Setting a GUI drops any video or view the material was showing. While the GUI takes input, the mouse or a light gun pointing at a surface drawn with the material reaches it through the same probe as sceneProbeGui. Ends the script for a GUI handle that is not valid.

Example
-- The options page on the screen of the modeled cabinet.
options = guiNew(720, 480)
page    = guiLoad(options, DIR .. "gui/options.rml")
screen  = materialNew()
materialSetGui(screen, options)
materialSetUnlit(screen, true)
nodeSetMesh(nodeFind("Screen", cabinet), meshPlane(3.0, 2.0), screen)

2.19.11. materialSetMetallic

materialSetMetallic(material, metallic)

How metallic the surface is, 0 for dielectrics (paint, plastic, wood, skin) to 1 for metals, which tint their highlights and reflections with the base color. The default is 0. Values between are for blends and worn surfaces; most materials want one end or the other. With materialSetMetallicRoughnessMap the map’s blue channel multiplies this value. A metal has little to reflect without a sky from sceneSetSky, so pair the two.

Example
-- Chrome bumper, painted body.
chrome = materialNew()
materialSetColor(chrome, 240, 240, 245)
materialSetMetallic(chrome, 1)
materialSetRoughness(chrome, 0.15)

paint = materialNew()
materialSetColor(paint, 30, 80, 200)
materialSetMetallic(paint, 0)
materialSetRoughness(paint, 0.4)
nodeSetMaterial(nodeFind("Bumper", car), chrome)
nodeSetMaterial(nodeFind("Body", car), paint)

2.19.12. materialSetMetallicRoughnessMap

materialSetMetallicRoughnessMap(material, sprite)
materialSetMetallicRoughnessMap(material, "file.ktx2")
materialSetMetallicRoughnessMap(material, nil)
materialSetMetallicRoughnessMap(material)

A texture varying the finish across the surface: its green channel multiplies the roughness from materialSetRoughness and its blue channel the metallic value from materialSetMetallic, the way glTF packs them, so a map from a glTF tool works as is. Set both factors to 1 to use the map’s values alone. The image comes from a sprite or a .ktx2 file by name; nil or no second argument removes the map. Ends the script when the texture cannot be uploaded.

Example
-- Scratched metal plating:  shiny where the paint has worn off.
plating = materialNew()
materialSetTexture(plating, DIR .. "Textures/plating.ktx2")
materialSetMetallicRoughnessMap(plating, DIR .. "Textures/platingMetalRough.ktx2")
materialSetMetallic(plating, 1)
materialSetRoughness(plating, 1)
materialSetNormalMap(plating, DIR .. "Textures/platingNormal.ktx2")
nodeSetMesh(hullPanel, meshPlane(4, 2), plating)

2.19.13. materialSetNormalMap

materialSetNormalMap(material, sprite)
materialSetNormalMap(material, sprite, strength)
materialSetNormalMap(material, "file.ktx2")
materialSetNormalMap(material, "file.ktx2", strength)
materialSetNormalMap(material, nil)
materialSetNormalMap(material)

A tangent-space normal map (the usual bluish kind, flat at 128, 128, 255) that tilts the lighting per texel so bricks, grooves and rivets catch the light without extra geometry. Every mesh has tangents for it: a model’s own when the file carries them, otherwise computed from the UVs. The image comes from a sprite or a .ktx2 file by name; nil or no second argument removes the map. Ends the script when the texture cannot be uploaded.

Parameters:

  • material — the material handle.

  • sprite or "file.ktx2" — the map, from a loaded sprite or a KTX2 file; nil or omitted removes it.

  • strength — how far the bumps tilt the lighting, 1 (the default) as authored, 0 flat, above 1 exaggerated.

Example
-- A brick wall from a flat plane, its mortar lines catching the low sun.
brick = materialNew()
materialSetTexture(brick, spriteLoad(DIR .. "Art/brick.png"))
materialSetNormalMap(brick, spriteLoad(DIR .. "Art/brickNormal.png"), 1.5)
materialSetRoughness(brick, 0.9)
materialSetTiling(brick, 6, 2)
wall = nodeNew()
nodeSetMesh(wall, meshPlane(12, 4), brick)
nodeSetPosition(wall, 0, 2, -3)
nodeSetRotation(wall, 90, 0, 0)

2.19.14. materialSetOccluder

materialSetOccluder(material, occluder)

Makes the material write depth and no color. Whatever the mesh covers is hidden as if the mesh were solid, but the mesh itself is not seen: what was drawn behind it — a painted backdrop, the disc — shows through. It is the stand-in for something that is in a picture but not in the scene: a pillar in a painted room that a 3D character has to walk behind, a doorway, a table. An occluder casts no shadow, since the painting already has one, and takes no light. false (the default) makes the material ordinary again.

Since: 3.00. See also: materialSetBlend, materialSetUnlit

Example
-- A pillar that is in the painting:  an invisible box where it stands, so
-- the hero disappears behind it and reappears on the other side.
hidden = materialNew()
materialSetOccluder(hidden, true)
pillar = nodeNew()
nodeSetMesh(pillar, meshBox(0.8, 4, 0.8), hidden)
nodeSetPosition(pillar, 2, 2, -3)

2.19.15. materialSetOcclusionMap

materialSetOcclusionMap(material, sprite)
materialSetOcclusionMap(material, sprite, strength)
materialSetOcclusionMap(material, "file.ktx2")
materialSetOcclusionMap(material, "file.ktx2", strength)
materialSetOcclusionMap(material, nil)
materialSetOcclusionMap(material)

An ambient occlusion map, occlusion in the red channel (white for open, dark for crevices), that darkens the ambient and sky light in corners and folds. Direct light from light nodes is not affected, as in glTF. The image comes from a sprite or a .ktx2 file by name; nil or no second argument removes the map. Ends the script when the texture cannot be uploaded.

Parameters:

  • material — the material handle.

  • sprite or "file.ktx2" — the map, from a loaded sprite or a KTX2 file; nil or omitted removes it.

  • strength — how much of the map to apply, 0 none to 1 (the default) fully.

Example
-- Baked shading for the cave walls, half strength so the lamps still reach the corners.
rock = materialNew()
materialSetTexture(rock, DIR .. "Textures/caveRock.ktx2")
materialSetNormalMap(rock, DIR .. "Textures/caveRockNormal.ktx2")
materialSetOcclusionMap(rock, DIR .. "Textures/caveRockAO.ktx2", 0.5)
materialSetRoughness(rock, 1)
nodeSetMaterial(nodeFind("Walls", cave), rock)

2.19.16. materialSetRoughness

materialSetRoughness(material, roughness)

How rough the surface is, 0 for a mirror-tight highlight to 1 for matte. The default is 0.5. Highlights follow the GGX model, so low values give a small bright spot and sharp sky reflections, high values a broad soft sheen and blurred ones. With materialSetMetallicRoughnessMap the map’s green channel multiplies this value.

Example
-- Wet the road when it rains:  the same asphalt, tighter highlights.
asphalt = materialNew()
materialSetColor(asphalt, 50, 50, 55)
materialSetRoughness(asphalt, 0.95)
nodeSetMesh(road, meshPlane(8, 200), asphalt)

function onWeatherChange(raining)
    if raining then
        materialSetRoughness(asphalt, 0.25)
    else
        materialSetRoughness(asphalt, 0.95)
    end
end

2.19.17. materialSetTexture

materialSetTexture(material, sprite)
materialSetTexture(material, "file.ktx2")
materialSetTexture(material, nil)
materialSetTexture(material)

Uses a sprite’s image as the base color texture (a copy is uploaded, so the sprite may be unloaded afterwards), or a KTX2 file by name, kept compressed on the GPU in the block format the machine has (see Compressed textures in 3D Scenes). With nil or no second argument the texture is removed and the material shows its base color alone. Setting a texture also drops any video or view the material was showing. Texture coordinates come from the mesh; the primitives map an image once across each face, and materialSetTiling repeats it. A name that is not a KTX2 file ends the script (load other pictures with spriteLoad), as does a failed upload.

Example
-- A crate textured from a sprite the game already loads for the menu,
-- and a floor from a compressed texture shipped with the game.
crateArt  = spriteLoad(DIR .. "Art/crate.png")
crateLook = materialNew()
materialSetTexture(crateLook, crateArt)
crate = nodeNew()
nodeSetMesh(crate, meshBox(1, 1, 1), crateLook)

floorLook = materialNew()
materialSetTexture(floorLook, DIR .. "Textures/tiles.ktx2")
materialSetTiling(floorLook, 10, 10)
nodeSetMesh(floor, meshPlane(20, 20), floorLook)

2.19.18. materialSetTiling

materialSetTiling(material, u, v)

How many times the material’s textures (base and maps alike) repeat across a surface’s 0 to 1 UV range, 1 and 1 by default. 24, 24 on a heightmap 120 units across tiles a texture every five units. Textures repeat past their edges, so the picture needs to tile cleanly. Values below 1 show part of the image; negative values mirror it.

Parameters:

  • material — the material handle.

  • u — repeats across the surface’s U direction.

  • v — repeats across the surface’s V direction.

Since: 3.00. See also: materialSetTexture, meshHeightmap

Example
-- Grass every five units across the hills.
ground = materialNew()
materialSetTexture(ground, DIR .. "Textures/grass.ktx2")
materialSetTiling(ground, 24, 24)
materialSetRoughness(ground, 0.95)
hills = nodeNew()
nodeSetMesh(hills, meshHeightmap(DIR .. "Art/hills.png", 120, 14, 120), ground)
bodyNew(hills, BODY_STATIC, SHAPE_MESH)

2.19.19. materialSetUnlit

materialSetUnlit(material, unlit)

Shows the base color and texture exactly as they are, ignoring every light, the ambient and the sky: for video screens, monitors showing a view, skyboxes, and flat-shaded looks. Fog still applies. The emissive color and the maps are not used on an unlit material. The default is false.

Example
-- The arcade cabinet's marquee:  a picture that is lit from inside, so the
-- room's lights should not shade it.
marquee = materialNew()
materialSetTexture(marquee, spriteLoad(DIR .. "Art/marquee.png"))
materialSetUnlit(marquee, true)
nodeSetMesh(nodeFind("Marquee", cabinet), meshPlane(0.7, 0.2), marquee)

2.19.20. materialSetView

materialSetView(material, view)
materialSetView(material, nil)
materialSetView(material)

Shows a rendered view from viewNew as the material’s base color texture, updated every frame: a security monitor, a rear-view mirror, a portal. Usually paired with materialSetUnlit so the picture is not shaded by the lights, and tinted by the base color like any texture. With nil or no second argument the material goes back to its own texture, which is kept underneath. Setting a view drops any video the material was showing. Ends the script for a view handle that is not valid.

Example
-- A rear-view mirror on the player's car.
rearCamera = nodeNew(car)
nodeSetPosition(rearCamera, 0, 1.2, -0.5)
nodeSetRotation(rearCamera, 0, 180, 0)
rearView = viewNew(384, 256)
viewSetCamera(rearView, rearCamera)
mirror = materialNew()
materialSetView(mirror, rearView)
materialSetUnlit(mirror, true)
nodeSetMesh(nodeFind("Mirror", car), meshPlane(0.3, 0.1), mirror)

2.19.21. materialSetVideo

materialSetVideo(material)
materialSetVideo(material, video)

Uses the laserdisc (no video) or a video loaded with videoLoad as the base color texture, updated every frame while it plays. Usually paired with materialSetUnlit so the picture is not tinted by the lights. The video keeps playing whether or not it is also drawn on the overlay, and several materials may show the same one. Setting a video drops any texture or view the material had; materialSetTexture takes it off again.

Notes: The disc form ends the script in a game without a disc, and so does a bad video handle.

Since: 3.00. See also: videoLoad, materialSetUnlit, materialSetTexture

Example
-- A modeled cabinet whose screen shows the laserdisc, and a wall of
-- monitors looping an attract clip.
cabinet = modelInstance(modelLoad(DIR .. "Models/Cabinet.glb"))
screen  = materialNew()
materialSetVideo(screen)
materialSetUnlit(screen, true)
nodeSetMesh(nodeFind("Screen", cabinet), meshPlane(0.6, 0.45), screen)

attract = videoLoad(DIR .. "Video/attract.mp4")
videoPlay(attract)
monitors = materialNew()
materialSetVideo(monitors, attract)
materialSetUnlit(monitors, true)

2.20. Mesh

A mesh is geometry on the GPU: a primitive the engine builds, a terrain from an image, or vertex data from your script. Handles are integers returned by the mesh* constructors; any number of nodes can share one mesh, and nodes drawing the same mesh with the same material draw as one instanced call, so make one mesh and many nodes. Sizes are in scene units and each primitive is centered on its node’s origin unless stated otherwise, so the node’s transform places, turns, and scales it. Texture coordinates run from 0 to 1 once across each face or surface. Every constructor needs the 3D renderer described in 3D Scenes and aborts the script when it is unavailable.

2.20.1. meshBox

mesh = meshBox(width, height, depth)

A box width along X, height along Y, and depth along Z, centered on the origin. Each of the six faces has its own four vertices with a flat normal, so edges shade crisply, and the texture is laid once across every face. Crates, walls, floors, and car bodies are all boxes.

Returns: The mesh handle.

Since: 3.00. See also: nodeSetMesh, meshPlane, bodyNew

Example
-- A stone floor slab and a stack of crates sharing one mesh.
local floor = nodeNew()
nodeSetMesh(floor, meshBox(16, 0.2, 10), stone)
nodeSetPosition(floor, 0, -0.1, 0)
local crateMesh = meshBox(0.6, 0.6, 0.6)
for i = 1, 4 do
    local crate = nodeNew()
    nodeSetMesh(crate, crateMesh, wood)
    nodeSetPosition(crate, 0, i * 0.6 - 0.3, -2)
    bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.6, 0.6, 0.6)
end

2.20.2. meshCone

mesh = meshCone(radius, height)
mesh = meshCone(radius, height, segments)

A cone standing on Y with a closed base: the base circle of radius at -height / 2 and the apex at +height / 2. segments (default 24, at least 3) is how many facets go round it; the sides shade smoothly across them. The texture wraps once round the sides and is laid once across the base. Above 1024, segments is taken as 1024.

Returns: The mesh handle.

Since: 3.00. See also: meshCylinder, nodeSetMesh

Example
-- A lampshade over the bulb, and a row of pine trees from one cone each.
local shade = nodeNew(stand)
nodeSetMesh(shade, meshCone(0.45, 0.5, 24), brass)
nodeSetPosition(shade, 0, 0.9, 0)
local foliage = meshCone(0.8, 2.0, 12)
for i = 1, 5 do
    local tree = nodeNew()
    nodeSetMesh(tree, foliage, pine)
    nodeSetPosition(tree, i * 3 - 9, 1.0, -6)
end

2.20.3. meshCylinder

mesh = meshCylinder(radius, height)
mesh = meshCylinder(radius, height, segments)

A cylinder along Y, closed at both ends, from -height / 2 to +height / 2. segments (default 24, at least 3) is how many facets go round it, shaded smoothly. For a wheel or a coin, rotate the node 90 degrees about X or Z so the axis lies where you need it. Above 1024, segments is taken as 1024.

Returns: The mesh handle.

Since: 3.00. See also: meshCone, meshTorus, nodeSetRotation

Example
-- A lamp post, and a tire lying on its side as a wheel.
local post = nodeNew()
nodeSetMesh(post, meshCylinder(0.08, 3, 10), dark)
nodeSetPosition(post, 3, 1.5, -2)
local tire = nodeNew(wheel)
nodeSetMesh(tire, meshCylinder(0.35, 0.25, 16), rubber)
nodeSetRotation(tire, 0, 0, 90)

2.20.4. meshDelete

meshDelete(mesh)

Frees the mesh’s GPU buffers and its CPU copy. Nodes that used it are left with no mesh (and no morph weights) and draw nothing until given another; the handle becomes invalid and may be reused by a later constructor. Meshes are not freed when a node is deleted, so delete a mesh yourself when nothing will use it again.

Since: 3.00. See also: meshNew, nodeSetMesh, nodeDelete

Example
-- Rebuild the track from a new heightmap between rounds.
function loadTrack(image)
    if trackMesh then
        meshDelete(trackMesh)
    end
    trackMesh = meshHeightmap(image, 200, 20, 200)
    nodeSetMesh(track, trackMesh, tarmac)
    bodyNew(track, BODY_STATIC, SHAPE_MESH)
end

2.20.5. meshHeightmap

mesh = meshHeightmap(image, sizeX, sizeY, sizeZ)

A terrain mesh from a grayscale image, 2 to 1025 pixels each way: one vertex per pixel across sizeX by sizeZ units centered on the node, each raised by the pixel’s red channel (0 black to 255 white) times sizeY, with the image’s top row at the far (-Z) edge. Normals are computed from the slopes and texture coordinates run 0 to 1 across the whole, so materialSetTiling sets the texture’s repeat. The height samples are kept: terrainGetHeight reads them, and a SHAPE_MESH body on the node becomes a height field. A file that cannot be opened or decoded, the wrong size, or no 3D renderer aborts the script.

Parameters:

  • image — the picture’s game-relative name, any format spriteLoad reads.

  • sizeX — the terrain’s width along X in world units.

  • sizeY — the height of a white pixel above a black one.

  • sizeZ — the terrain’s depth along Z in world units.

Returns: The mesh handle.

Since: 3.00. See also: terrainGetHeight, materialSetTiling, bodyNew

Example
local ground = materialNew()
materialSetTexture(ground, spriteLoad("grass.png"))
materialSetTiling(ground, 24, 24)
materialSetRoughness(ground, 0.95)
local hills = nodeNew()
nodeSetMesh(hills, meshHeightmap("hills.png", 120, 14, 120), ground)
bodyNew(hills, BODY_STATIC, SHAPE_MESH)
-- The dragon's feet on the slope, wherever the ground is there.
nodeSetPosition(dragon, -8, terrainGetHeight(hills, -8, 3) or 0, 3)

2.20.6. meshNew

mesh = meshNew(positions, normals, uvs, indices)

Builds geometry from tables of numbers. Tangents for normal mapping are computed for you, and so are smooth normals when normals is nil, by averaging the triangles that share each vertex. Triangles are front facing when their vertices run counter-clockwise seen from outside; give the material materialSetDoubleSided if the back must show. A table of the wrong shape, or an index outside the vertex list, aborts the script with a message saying which.

Parameters:

  • positions — x, y, z for every vertex, one after another; at least one vertex.

  • normals — x, y, z per vertex, the same count as positions, or nil to have them computed.

  • uvs — u, v per vertex (0 to 1, v down the image), or nil for none (every vertex at 0, 0).

  • indices — three vertex numbers per triangle, counted from 1 as the vertices appear in positions; at least one triangle.

Returns: The mesh handle.

Since: 3.00. See also: nodeSetMesh, materialSetDoubleSided, meshDelete

Example
-- A flat arrow pointing along +X, seen from above (double sided so it works from below too).
local arrow = meshNew(
    { 0, 0, -0.5,   1, 0, 0,   0, 0, 0.5,   -0.6, 0, -0.5,   -0.6, 0, 0.5 },
    nil,
    nil,
    { 1, 2, 3,   4, 1, 3,   4, 3, 5 })
local marker = materialNew()
materialSetColor(marker, 255, 200, 40)
materialSetDoubleSided(marker, true)
local pointer = nodeNew()
nodeSetMesh(pointer, arrow, marker)
nodeSetPosition(pointer, 0, 0.05, 0)

2.20.7. meshPlane

mesh = meshPlane(width, depth)
mesh = meshPlane(width, depth, columns)
mesh = meshPlane(width, depth, columns, rows)

A flat rectangle in the XZ plane facing +Y, width along X and depth along Z, centered on the origin, with the texture laid once across it. Two arguments give a single quad. columns (and rows, which defaults to columns) subdivide it into that many quads each way, which a soft body (softNew) needs to bend as cloth; both must be at least 1. Rotate the node 90 degrees about X to stand it up facing +Z. It is single sided unless its material is double sided.

Returns: The mesh handle.

Example
-- The ground, a screen showing the disc, and a flag that will be cloth.
local plain = nodeNew()
nodeSetMesh(plain, meshPlane(60, 60), ground)
local tv = nodeNew()
nodeSetMesh(tv, meshPlane(3.0, 2.2), screen)
nodeSetPosition(tv, 0, 1.6, -4)
nodeSetRotation(tv, 90, 0, 0)
local flag = nodeNew()
nodeSetMesh(flag, meshPlane(1.6, 1.0, 16, 10), cloth)
nodeSetPosition(flag, 0.8, 2.5, 0)
nodeSetRotation(flag, 90, 0, 0)

2.20.8. meshSphere

mesh = meshSphere(radius)
mesh = meshSphere(radius, segments)

A sphere of radius, centered on the origin, built from latitude and longitude bands: segments (default 32, at least 3) around the equator and half as many from pole to pole. The texture wraps once round it, v from the top pole to the bottom. Fewer segments make a lighter mesh for balls seen from afar; more make a smoother silhouette up close. Above 1024, segments is taken as 1024.

Returns: The mesh handle.

Since: 3.00. See also: meshTorus, nodeSetMesh, bodyNew

Example
-- A glass ball on the floor, and a small marker sphere that shares a look.
local ball = nodeNew()
nodeSetMesh(ball, meshSphere(0.7, 48), glass)
nodeSetPosition(ball, -1.5, 0.7, 0)
bodyNew(ball, BODY_DYNAMIC, SHAPE_SPHERE, 0.7)
local dot = nodeNew()
nodeSetMesh(dot, meshSphere(0.08, 16), marker)
nodeSetPosition(dot, 0, 1.2, 0)

2.20.9. meshTorus

mesh = meshTorus(radius, tubeRadius)
mesh = meshTorus(radius, tubeRadius, segments)

A ring lying in the XZ plane around Y, centered on the origin: radius from the center to the middle of the tube and tubeRadius the tube’s own. segments (default 32, at least 3) go around the ring and half as many (at least 3) around the tube. The texture wraps once round the ring in u and once round the tube in v. Above 1024, segments is taken as 1024.

Returns: The mesh handle.

Since: 3.00. See also: meshSphere, meshCylinder

Example
-- A gold ring standing on edge for the ball to roll through.
local gold = materialNew()
materialSetColor(gold, 255, 200, 80)
materialSetMetallic(gold, 1)
materialSetRoughness(gold, 0.25)
local ring = nodeNew()
nodeSetMesh(ring, meshTorus(1.2, 0.25, 40), gold)
nodeSetPosition(ring, 0, 1.2, -2)
nodeSetRotation(ring, 90, 0, 0)

2.21. Microphone

A microphone, for a singing game or anything that listens. One recording device is open at a time, heard as one channel at 48000 samples a second whatever the hardware gives; SDL converts. Singe keeps the newest eight seconds of what it hears, and every call below answers from that, so asking costs nothing the game did not already pay for.

What a game usually wants is micPitch — the note being sung — and micLevel. A game that analyses the sound itself, or sends it somewhere, reads the samples with micRead; the Voice calls encode them for a network.

The microphone closes when the game ends. Nothing is opened until a script asks.

A sung note reaches the game a little after it was sung: the sound card, the driver, and the buffers each hold it for a moment. A singing game that judges timing subtracts that. micCalibrate measures it by playing clicks through the speakers and timing them coming back, and the answer is kept for the machine, like the audio calibration. Monitoring and calibration have only been tested without real hardware so far; the pitch, level, reading, and recording have been tested with a known signal.

2.21.1. micCalibrate

started = micCalibrate()

Measures the microphone’s latency: plays five clicks through the speakers, a fraction of a second apart, and times each one coming back through the microphone. It takes a few seconds; micCalibration says when it is done. The answer is the middle of the clicks heard, and is kept for this machine. Do it in a quiet room, with the speakers loud enough for the microphone to hear them.

Returns: true when it started; false with no microphone open or no speaker to play the clicks.

Since: 3.00. See also: micCalibration, micLatency

2.21.2. micCalibration

state, latency = micCalibration()

How a calibration is going.

Returns: state, one of "idle", "running", "done", or "failed" (fewer than three of the clicks were heard back), and the latency in milliseconds once one is known, otherwise nil.

Since: 3.00. See also: micCalibrate

Example
local state, latency = micCalibration()
if state == "done" then
	message = "Your microphone runs " .. latency .. " ms behind."
elseif state == "failed" then
	message = "I could not hear the clicks.  Turn the speakers up and try again."
end

2.21.3. micClose

micClose()

Stops listening, and stops any recording and monitoring with it. The microphone also closes when the game ends.

Since: 3.00.

2.21.4. micIsOpen

open = micIsOpen()

Returns: true while a microphone is open.

Since: 3.00.

2.21.5. micLatency

milliseconds = micLatency()

Returns: the time between a sound being made and the game hearing it, as measured on this machine by micCalibrate (at any time, in any game), or set by micSetLatency; nil until then.

Since: 3.00.

2.21.6. micLevel

rms, peak = micLevel()

How loud the last moment heard was.

Returns: the RMS and the peak of the last block of samples, each 0 to 1. A steady tone at full scale reads about 0.71 RMS. Both are 0 with no microphone open.

Since: 3.00.

2.21.7. micList

names = micList()

Returns: a list of the names of the microphones this machine has, for micOpen. It is taken afresh each time, so a microphone plugged in since the last call appears.

Since: 3.00.

2.21.8. micMonitor

ok = micMonitor(on [, volume])

Plays what the microphone hears back through the speakers, so a singer hears themselves over the music. Off until asked for: on most hardware the voice comes back late enough to be off-putting, and on a laptop the speakers feed the microphone. Anything waiting to be played longer than a tenth of a second is dropped rather than heard late.

Parameters:

  • on — boolean.

  • volume — number, 0 to 1; 1 unless given.

Returns: true, or false with no microphone open or no speaker to play to.

Since: 3.00.

2.21.9. micOpen

opened = micOpen([name])

Starts listening, to the microphone named (from micList) or the machine’s default. A microphone already open is closed first.

Returns: true when it opened.

Since: 3.00.

Example
if not micOpen() then
	message = "No microphone.  This game needs one."
end

2.21.10. micPitch

hz, clarity = micPitch()

The note being sung, found in the newest 43 milliseconds heard. It finds a fundamental between 50 and 2000 Hz, which covers every singing voice, and it answers within a hertz or two on a clean tone.

Returns: the fundamental in Hz, and how clearly the sound is one note, 0 to 1. With nothing voiced — silence, a breath, a cough, a crowd — hz is 0. Turn Hz into a note number with 69 + 12 * math.log(hz / 440, 2): 69 is the A above middle C, and every 1 is a semitone.

Since: 3.00.

Example
local hz, clarity = micPitch()
if hz > 0 and clarity > 0.8 then
	local note = 69 + 12 * math.log(hz / 440, 2)
	local off  = note - targetNote          -- semitones sharp (positive) or flat
	if math.abs(off) < 0.5 then
		score = score + 1
	end
end

2.21.11. micRead

samples = micRead([max])

What was heard since the last call, oldest first.

Parameters:

  • max — number, the most samples to return; everything waiting unless given.

Returns: a string of 16-bit samples, two bytes each, little endian, one channel at 48000 a second: #samples / 2 of them. Read one with string.unpack("<i2", samples, n * 2 - 1). A game that does not read for more than eight seconds loses the oldest.

Since: 3.00.

2.21.12. micRecordStart

started = micRecordStart(name)

Writes everything heard from now on to a WAV file (one channel, 16-bit, 48000 a second) until micRecordStop. The name is any file the game may write, and goes where the game’s other written files go.

Returns: true when the file was opened.

Since: 3.00.

2.21.13. micRecordStop

micRecordStop()

Finishes the recording.

Since: 3.00.

2.21.14. micSetLatency

micSetLatency(milliseconds | nil)

Sets this machine’s microphone latency, as a service menu does from a measurement made some other way; nil forgets it. It is kept with the machine’s other settings.

Parameters:

  • milliseconds — number, 0 to 1000, or nil.

Since: 3.00.

2.22. MIDI

Two unrelated things share this name, and it is worth keeping them apart.

A MIDI file is music, and it plays like any other music: hand .mid to musicLoad. Singe synthesizes it from a SoundFont, because a MIDI file holds notes rather than sound. It ships no SoundFont — a good one is tens of megabytes for a format almost no game uses — so name one with --soundfont, put one at Singe/soundfont.sf2 so a packed game carries its own, or let Singe find the one your distribution installed. The SoundFont: line of the trace header says which was used. With no SoundFont anywhere, loading a .mid fails and says so.

MIDI ports are the calls below. They send and receive live messages on a real port: a cabinet driving an external sound module, or a keyboard, a fader box or a control surface read as another input device. Nothing here synthesizes anything, and nothing here touches a MIDI file.

Ports are numbered from 0. Nothing is opened until a script first asks — a MIDI port costs a file descriptor and a round of driver configuration, and a game that never mentions MIDI never pays for it — so the first of these calls is what takes stock of the machine, and midiRescan looks again for a device plugged in since. One input port and one output port may be open at a time. Channels are 1 to 16 as a person counts them, not 0 to 15 as the wire does, and every other value is 0 to 127. On a machine with no MIDI at all — no ports, or no MIDI library installed — the counts are 0, the open calls answer false, and the sending calls answer false; nothing fails.

Linux reaches every port on the ALSA sequencer, which is both the hardware interfaces and any synthesizer or other program registering one. macOS uses CoreMIDI and Windows the multimedia MIDI calls, where output device 0 is usually the synthesizer the system itself provides.

2.22.1. midiCloseInput

midiCloseInput()

Stops listening to the input port. onMidiMessage stops firing. Closing a port that is not open does nothing.

Parameters:

  • None.

Returns: nothing.

Since: 3.00. See also: midiOpenInput

2.22.2. midiCloseOutput

midiCloseOutput()

Releases the output port. The sending calls answer false from now on. Closing a port that is not open does nothing.

Parameters:

  • None.

Returns: nothing.

Since: 3.00. See also: midiOpenOutput

2.22.3. midiControlChange

sent = midiControlChange(channel, control, value)

Moves a controller on the open output port: volume is controller 7, pan is 10, the sustain pedal is 64.

Parameters:

  • channel — number; 1 to 16.

  • control — number; 0 to 127.

  • value — number; 0 to 127.

Returns: true when the message went out.

Since: 3.00. See also: midiSend

Example
-- Duck the module's volume while a character speaks.
midiControlChange(1, 7, 40)

2.22.4. midiInputCount

count = midiInputCount()

How many MIDI input ports this machine has. 0 when there are none, or when the platform has no MIDI at all.

Parameters:

  • None.

Returns: a number.

Since: 3.00. See also: midiInputName

2.22.5. midiInputName

name = midiInputName(index)

The name of an input port, for a settings screen that lets a player choose one.

Parameters:

  • index — number; 0 to midiInputCount() - 1.

Returns: a string, or nil when the index names no port.

Since: 3.00. See also: midiInputCount

Example
-- A settings screen listing the input ports, one to a row.
function onOverlayUpdate()
    overlayClear()
    for i = 0, midiInputCount() - 1 do
        overlayPrint(1, i + 1, midiInputName(i))
    end
    return OVERLAY_UPDATED
end

2.22.6. midiIsInputOpen

open = midiIsInputOpen()

Whether an input port is open.

Parameters:

  • None.

Returns: true or false.

Since: 3.00. See also: midiOpenInput

2.22.7. midiIsOutputOpen

open = midiIsOutputOpen()

Whether an output port is open. Worth asking before a burst of messages, since each one would otherwise answer false separately.

Parameters:

  • None.

Returns: true or false.

Since: 3.00. See also: midiOpenOutput

2.22.8. midiNoteOff

sent = midiNoteOff(channel, key)

Releases a note on the open output port. A note left on sounds until something stops it, so every midiNoteOn needs one of these.

Parameters:

  • channel — number; 1 to 16.

  • key — number; 0 to 127, where 60 is middle C.

Returns: true when the message went out.

Since: 3.00. See also: midiNoteOn

2.22.9. midiNoteOn

sent = midiNoteOn(channel, key, velocity)

Sounds a note on the open output port.

Parameters:

  • channel — number; 1 to 16. Channel 10 is percussion on a General MIDI device.

  • key — number; 0 to 127, where 60 is middle C.

  • velocity — number; 0 to 127, how hard the key was struck.

Returns: true when the message went out.

Since: 3.00. See also: midiNoteOff

Example
-- A stinger on an external module when the player is hit.
midiNoteOn(10, 49, 110)
midiNoteOff(10, 49)

2.22.10. midiOpenInput

opened = midiOpenInput(index)

Listens to one input port. onMidiMessage then fires for every message that arrives. Whichever input port was open is closed first.

Parameters:

  • index — number; 0 to midiInputCount() - 1.

Returns: true when the port opened.

Since: 3.00. See also: midiCloseInput, onMidiMessage

Example
if midiInputCount() > 0 then
	midiOpenInput(0)
end

2.22.11. midiOpenOutput

opened = midiOpenOutput(index)

Takes one output port for the sending calls. Whichever output port was open is closed first.

Parameters:

  • index — number; 0 to midiOutputCount() - 1.

Returns: true when the port opened.

Since: 3.00. See also: midiCloseOutput

2.22.12. midiOutputCount

count = midiOutputCount()

How many MIDI output ports this machine has.

Parameters:

  • None.

Returns: a number.

Since: 3.00. See also: midiOutputName

2.22.13. midiOutputName

name = midiOutputName(index)

The name of an output port.

Parameters:

  • index — number; 0 to midiOutputCount() - 1.

Returns: a string, or nil when the index names no port.

Since: 3.00. See also: midiOutputCount

2.22.14. midiPitchBend

sent = midiPitchBend(channel, value)

Bends a channel. 8192 is the middle, meaning no bend; how far 0 and 16383 reach is the receiving device’s own setting, usually two semitones.

Parameters:

  • channel — number; 1 to 16.

  • value — number; 0 to 16383.

Returns: true when the message went out.

Since: 3.00.

2.22.15. midiProgramChange

sent = midiProgramChange(channel, program)

Chooses the sound a channel plays. The numbers are the receiving device’s; on a General MIDI device 0 is a grand piano.

Parameters:

  • channel — number; 1 to 16.

  • program — number; 0 to 127.

Returns: true when the message went out.

Since: 3.00.

2.22.16. midiRescan

midiRescan()

Looks for ports again, for a device plugged in while the game is running. An open port stays open. Indexes are only as stable as the list, so read the names again after this rather than assuming port 2 is still what it was.

Parameters:

  • None.

Returns: nothing.

Since: 3.00. See also: midiInputCount, midiOutputCount

2.22.17. midiSend

sent = midiSend(byte [, byte [, byte]])
sent = midiSend(string)

Any message at all, for the ones the named calls do not cover. Given numbers it sends them as they are, which is a status byte and up to two data bytes — and note that the status byte carries the channel in its low four bits, counting from 0, unlike every other call here. Given a string it sends the whole string, which is how a system exclusive message goes out.

Parameters:

  • byte — number; 0 to 255, one to three of them.

  • string — a string of bytes, sent unchanged.

Returns: true when the message went out.

Since: 3.00. See also: midiNoteOn, midiControlChange

Example
-- All notes off on channel 1, which has no named call.
midiSend(0xB0, 123, 0)

-- A system exclusive message, bytes and all.
midiSend(string.char(0xF0, 0x7E, 0x7F, 0x09, 0x01, 0xF7))

2.23. Model

Models are glTF 2.0 binary files (.glb) loaded once and placed any number of times. A model must be self-contained (buffers and images inside the file); one referring to a file beside it is refused. Loading gives an integer handle; modelInstance builds the model’s nodes into the scene and returns their root, which every node* and animation* call then takes. Positions and sizes inside a model are in world units, as the file stores them; the root node scales the whole instance. See 3D Scenes.

2.23.1. modelLoad

model = modelLoad(name)

Reads a .glb through the same lookup as every other asset (game directory, data directory, packed database), uploads its meshes and materials to the GPU once, and keeps its node tree, skins and animations for instancing. Call it once at startup and instance the handle as many times as needed; loading the same file twice makes two copies on the GPU. It needs the 3D scene, so on a machine without a suitable GPU it fails like any other 3D call. A bad file ends the script with a message naming the problem: the file could not be read, is not glTF, refers to an external buffer or image, fails validation, holds a primitive that could not be uploaded, has a skin with more than 128 joints, or has a skinned mesh naming a joint numbered 128 or more. A skinned mesh naming a joint beyond the skins that use it loads, as does an animation whose keyframes cannot be read (that sampler is skipped); either is noted in the program trace. A texture that cannot be decoded, or a missing KTX2 image, does not fail the load; the material goes without that map and the program trace (--program) says which one.

Returns: The model handle, an integer.

Since: 3.00. See also: modelInstance, modelGetAnimations, modelDelete

Example
-- Load once, place three times.
treeModel = modelLoad(DIR .. "Models/Tree.glb")
for i = 1, 3 do
    local tree = modelInstance(treeModel)
    nodeSetPosition(tree, i * 3 - 6, 0, -4)
    nodeSetRotation(tree, 0, i * 70, 0)
end

2.23.2. modelDelete

modelDelete(model)

Frees the model’s meshes, materials and parsed data. Every instance made from it is forgotten at the same time: its nodes stay in the scene (position, parent and children intact) but draw nothing, its animations stop where they are, and a later animation* call on its root ends the script because the node is no longer a model instance. Delete the instance roots with nodeDelete when the nodes are not wanted either. A handle that is not a loaded model ends the script.

Since: 3.00. See also: modelLoad, modelInstance, nodeDelete

Example
-- Leaving the hangar level: drop its props and the model behind them.
function unloadHangar()
    for _, crate in ipairs(hangarCrates) do
        nodeDelete(crate)
    end
    hangarCrates = {}
    modelDelete(crateModel)
    crateModel = nil
end

2.23.3. modelGetAnimations

names = modelGetAnimations(model)

Lists the model’s animation clips in file order as a table of strings, so names[3] is the clip that animationPlay(node, 3) plays. A clip the exporter left unnamed gives an empty string; it can still be played by number. A model with no animations gives an empty table. A handle that is not a loaded model ends the script.

Returns: A table of strings indexed from 1.

Since: 3.00. See also: animationPlay, modelLoad

Example
-- Find the clips by name once, so the rest of the game uses numbers.
guardModel = modelLoad(DIR .. "Models/Guard.glb")
guardClips = {}
for index, name in ipairs(modelGetAnimations(guardModel)) do
    guardClips[name] = index
end
if guardClips["Idle"] == nil then
    debugPrint("Guard.glb has no Idle clip")
end

2.23.4. modelInstance

node = modelInstance(model)
node = modelInstance(model, parent)

Builds the model’s node tree under a new root node, itself under parent or the scene root. The root is a plain node: position, rotate, scale or parent it like any other, and delete it with nodeDelete to remove the whole instance. The model’s own nodes take their glTF names (or their mesh’s name when the node is unnamed) so nodeFind(name, node) reaches them; a mesh with several materials becomes one child node per part; lights in the file become scene lights with the file’s color, intensity, range and cone; skins are attached and morph weights set. The nodes stand in the file’s pose until an animation plays. A handle that is not a loaded model or a parent that is not a node ends the script, as does running out of nodes.

Returns: The instance’s root node handle.

Since: 3.00. See also: modelLoad, nodeFind, animationPlay, nodeDelete

Example
-- A turret on the tank's hull, so it turns with the hull and pivots on its own.
tank   = modelInstance(hullModel)
turret = modelInstance(turretModel, tank)
nodeSetPosition(turret, 0, 1.1, -0.3)
barrel = nodeFind("Barrel", turret)

function onOverlayUpdate()
    nodeSetRotation(turret, 0, aimYaw, 0)
    nodeSetRotation(barrel, aimPitch, 0, 0)
    return OVERLAY_UPDATED
end

2.24. Mouse

Singe reads up to four mice, and treats light guns as mice. In the default single-mouse mode every pointing device drives one cursor reported as mouse 0; mouseSetMode(MOUSE_MANY) tells the devices apart, which a two-player light gun cabinet needs. Positions arrive in overlay coordinates, not screen pixels, through onMouseMoved (see Engine Callbacks) and on demand from mouseGetPosition. Mouse buttons and the wheel are switches like keys: they reach onInputPressed and onInputReleased when controls.cfg maps a code from the MOUSE_0 through MOUSE_3 tables, and the shipped defaults map the left button to SWITCH_BUTTON3, the right to SWITCH_BUTTON1 and the middle to SWITCH_BUTTON2. The engine starts with the mouse captured, and enabled unless --nomouse was given or no mouse was found.

2.24.1. mouseDisable

mouseDisable()

Turns mouse input off, exactly as mouseSetEnabled(false) does. It is a function defined in Framework.singe, kept so older games run unchanged.

Notes: Legacy alias.

New code should call mouseSetEnabled with false.

Since: 1.18 (RDG) See also: mouseSetEnabled, mouseEnable

Example
-- Older game code; the modern spelling is mouseSetEnabled(false).
function cutsceneBegin()
    mouseDisable()
    discSearch(CUTSCENE_START)
end

2.24.2. mouseEnable

mouseEnable()

Turns mouse input on, exactly as mouseSetEnabled(true) does, and like it stays off when Singe was started with --nomouse. It is a function defined in Framework.singe, kept so older games run unchanged.

Notes: Legacy alias.

New code should call mouseSetEnabled with true.

Since: 1.18 (RDG) See also: mouseSetEnabled, mouseDisable

Example
-- Older game code; the modern spelling is mouseSetEnabled(true).
function cutsceneEnd()
    mouseEnable()
    discSearch(LEVEL_START)
end

2.24.3. mouseGetName

name = mouseGetName(mouse)

The name the mouse driver gives a device, or nil when there is no device with that index. Two guns on a cabinet are told apart by it on a service screen, which is otherwise guesswork when both report as mouse 0 and 1. An index outside 0 to 3 aborts the script.

Parameters:

  • mouse — device index, 0 through 3.

Returns: string, or nil.

Since: 3.00 See also: mouseHowMany, mouseSetMode, controllerGetName

Example
-- Name the guns on the calibration screen.
mouseSetMode(MOUSE_MANY)
for device = 0, mouseHowMany() - 1 do
    fontPrint(20, 20 + device * 18, string.format("Gun %d:  %s", device + 1, mouseGetName(device)))
end

2.24.4. mouseGetPadding

padding = mouseGetPadding()

Hypseus extension, always 0, for the reason controllerGetPadding gives. Hypseus adds this offset to the input codes its mice report in relative mode; Singe’s codes carry no such offset, so there is nothing to subtract.

Returns: an integer, always 0.

Since: 3.00 See also: controllerGetPadding

2.24.5. mouseGetPosition

x, y = mouseGetPosition(index)

Returns the last reported position of a mouse in overlay coordinates, the same values the most recent onMouseMoved for that device carried. In single-mouse mode only mouse 0 moves; in many-mouse mode each device has its own position, starting at the center of the video. The position stops updating while mouse input is disabled. Poll it from onOverlayUpdate or singeMain when that is simpler than tracking the callback. An index outside 0 to 3 aborts the script.

Parameters:

  • index — mouse index, 0 through 3.

Returns: two integers, x and y, in overlay coordinates.

Example
-- Draw the crosshair where the gun points.
function onOverlayUpdate()
    overlayClear()
    drawTargets()
    if singeWantsCrosshairs() then
        local x, y = mouseGetPosition(0)
        spriteDraw(crosshair, x, y, true)
    end
    return OVERLAY_UPDATED
end

2.24.6. mouseHowMany

count = mouseHowMany()

Returns the number of mice the engine found at startup, 0 through 4. Devices plugged in later are not counted. When none were found the mouse stays disabled. Use it to decide whether to offer a second light gun player.

Returns: integer, 0 to 4.

Since: 1.18 (RDG) See also: mouseSetMode, mouseGetPosition

Example
-- Two guns present: give each player a cursor.
if mouseHowMany() >= 2 then
    mouseSetMode(MOUSE_MANY)
    players = 2
else
    players = 1
end

2.24.7. mouseSetCaptured

mouseSetCaptured(captured)

Grabs the mouse, confining it to the Singe window and hiding the cursor, or releases it and shows the cursor again. The engine captures the mouse at startup, so most games never call this; a windowed level editor or a game that wants the desktop cursor visible releases it. The switch mapped to INPUT_GRAB in controls.cfg toggles the same state from the keyboard.

Parameters:

  • captured — boolean; true grabs and hides, false releases and shows.

Since: 2.00 See also: mouseSetEnabled, mouseGetPosition

Example
-- The level editor wants the desktop cursor; gameplay hides it again.
function editorToggle()
    editing = not editing
    mouseSetCaptured(not editing)
end

2.24.8. mouseSetEnabled

mouseSetEnabled(enabled)

Turns mouse input on or off. While off, motion, button and wheel events are discarded before they reach the script: onMouseMoved stops firing, mouse buttons no longer produce switches, and mouseGetPosition keeps returning the last position it had. The cursor itself still moves. Enabling honors --nomouse; when Singe was started with that option the mouse stays off. A non-boolean argument aborts the script.

Parameters:

  • enabled — boolean.

Since: 3.00 See also: mouseSetCaptured, mouseSetMode, mouseEnable

Example
-- Ignore the gun while the attract loop plays.
function attractBegin()
    mouseSetEnabled(false)
    discSearch(ATTRACT_START)
end

function attractEnd()
    mouseSetEnabled(true)
end

2.24.9. mouseSetMode

mouseSetMode(mode)

Chooses how mice are read. In MOUSE_SINGLE (the default) the window’s pointer events drive one cursor reported as device 0, with absolute positions and relative motion both converted to overlay coordinates. In MOUSE_MANY each physical device is read separately: relative motion is integrated into a per-device position clamped to the video area, absolute devices such as tablets and some light guns are mapped onto the video, and onMouseMoved reports the device index. Both modes deliver the same five buttons and the vertical wheel as switches. SINGLE_MOUSE and MANY_MOUSE are accepted as older spellings; any other value aborts the script. --manymouse is the user’s own decision and outranks this call: with it given the mode is MOUSE_MANY from the start and mouseSetMode(MOUSE_SINGLE) does not switch it off, so a two-gun cabinet can be made to work from outside a game that never asks.

Parameters:

  • mode — MOUSE_SINGLE (100) or MOUSE_MANY (200).

Since: 1.18 (RDG) See also: mouseHowMany, onMouseMoved, mouseGetPosition

Example
-- Cooperative light gun game: each gun steers its own cursor.
mouseSetMode(MOUSE_MANY)

function onMouseMoved(x, y, xr, yr, which)
    if which < 2 then
        cursorX[which + 1] = x
        cursorY[which + 1] = y
    end
end

2.25. Music

Background music, loaded and played apart from the sound effects and carrying its own volume. Hypseus runs music on a second mixer for exactly that reason, and Singe gives it its own gain instead: musicSetVolume never moves a sound effect and soundSetVolume never moves the music.

A music handle is its own kind of handle, not a sound handle and not a channel: one handle is one track, and it plays, pauses, resumes and stops on its own. There is no channel limit, unlike the sixteen sound effect channels.

The volume scale is Hypseus’s, 0 to 128, nearly twice the 0 to 63 the sound family uses, so a game written for Hypseus keeps its own numbers. Music starts as loud as the sound effects do, at whatever --volume_nonvldp set; Hypseus instead starts its music mixer a third of the way up, which every Hypseus game immediately overwrites with musicSetVolume(soundGetVolume() * 2).

Every format the sound family reads is read here: WAV, Ogg Vorbis, Opus, FLAC, MP3, WavPack and the rest. The trace header written by --program and --trace lists exactly which decoders the build carries, on its Audio: line.

Pausing the engine (the pause key, or singeSetPauseFlag) pauses the music with it, and resuming brings it back; a reload stops and frees every track.

2.25.1. musicGetPosition

seconds = musicGetPosition(id)

Where the listener is in a playing track, in seconds: the mixer’s own position, less what is still on its way to the speakers — the device queue, the machine’s audio calibration, and the game’s audio delay — so a picture timed to it lands with the sound. It is the clock to animate to when the music leads, as in a demo or a rhythm game, and it stays with the song however long it plays, where counting frames or ticks drifts. The mixer moves its position a buffer at a time, so between moves the answer runs on with the clock, never more than 50 ms, and it moves smoothly every frame. A paused track holds still. A track that is not playing answers -1.

Parameters:

  • id — number; a music handle.

Returns: number; seconds into the track, or -1.

Example
-- Flash on every beat of a 120 beat a minute song, on the beat as it is heard.
function onOverlayUpdate()
    colorBackground(0, 0, 0)
    overlayClear()
    local t = musicGetPosition(song)
    if t >= 0 and (t * 2) % 1 < 0.1 then
        colorBackground(255, 255, 255, 120)
        overlayClear()
    end
    return OVERLAY_UPDATED
end

2.25.2. musicIsPlaying

playing = musicIsPlaying([id])

Hypseus extension. Whether that track is playing, or — with no handle — whether any music is. A paused track is not playing.

Parameters:

  • id — optional number; a music handle.

Returns: boolean.

Since: 3.00, as a Hypseus Singe extension. See also: musicPlay, musicPause

Example
if not musicIsPlaying(theme) then
    musicPlay(theme, -1)
end

2.25.3. musicLoad

id = musicLoad(filename)

Hypseus extension. Loads a music track through the virtual file system and returns its handle. The whole file is decoded up front, as a sound is, so a long track costs memory, unless it is a chiptune that does not say how long it is, or would decode to more than 512 MB, either of which is decoded as it plays; the handle is valid until musicUnload or a reload.

A file that is missing, or that no compiled-in decoder can read, terminates the script, as soundLoad does.

Parameters:

  • filename — string; a path the virtual file system can reach.

Returns: number, the music handle.

Since: 3.00, as a Hypseus Singe extension. See also: musicPlay, musicUnload, soundLoad

Example
local theme = musicLoad("music/attract.mp3")
musicSetVolume(96)
musicPlay(theme, -1)

2.25.4. musicPause

musicPause([id])

Hypseus extension. Pauses that track where it is, or every piece of music when no handle is given. musicResume picks it up again.

Parameters:

  • id — optional number; a music handle.

Returns: nothing.

Since: 3.00, as a Hypseus Singe extension. See also: musicResume, musicStop

Example
-- The player opened the map; hold the music rather than restart it.
musicPause()

2.25.5. musicPlay

id = musicPlay(id [, loops])

Hypseus extension. Plays a track from its beginning and answers its handle, which is how Hypseus’s games keep it (sndHandle = musicPlay(music)) to stop the piece later. loops means what soundPlay's does: 0, the default, plays once, -1 plays forever, and N repeats N more times. The count is clamped to -1 to 64, as Hypseus clamps it, so a game asking for more gets what it would have got there.

Playing a track that is already playing starts it again from the beginning.

Parameters:

  • id — number; a music handle.

  • loops — optional number; -1 to 64. Default 0.

Returns: number; the handle it was given.

Since: 3.00, as a Hypseus Singe extension. See also: musicStop, musicSetVolume

Example
musicPlay(theme, -1)     -- Round and round until something stops it.

2.25.6. musicResume

musicResume([id])

Hypseus extension. Resumes a paused track, or every paused piece of music when no handle is given.

Hypseus’s own zero argument form does nothing at all; Singe’s resumes everything, which is what pairs with musicPause.

Parameters:

  • id — optional number; a music handle.

Returns: nothing.

Since: 3.00, as a Hypseus Singe extension. See also: musicPause

Example
musicResume()

2.25.7. musicSetVolume

volume = musicSetVolume(volume)

Hypseus extension. Sets the gain over every piece of music at once, on Hypseus’s 0 to 128 scale, and answers the level it took. It moves nothing but music: the sound effects keep whatever soundSetVolume gave them, and soundSetVolume leaves the music alone.

A level outside 0 to 128 terminates the script. The level applies to tracks already playing and to any loaded afterwards, and goes back to the starting level on a reload.

Parameters:

  • volume — number; 0 to 128.

Returns: number, the level that was set.

Since: 3.00, as a Hypseus Singe extension. See also: soundSetVolume, musicPlay

Example
-- What a Hypseus game writes:  the sound level, doubled onto the music scale.
musicSetVolume(soundGetVolume() * 2)

2.25.8. musicStop

musicStop([id [, fadeMs]])

Hypseus extension. Stops that track, or every piece of music when no handle is given (a nil handle counts as none). fadeMs fades it out over that many milliseconds instead of cutting it; 0, the default, stops at once. A negative fade terminates the script.

Parameters:

  • id — optional number; a music handle.

  • fadeMs — optional number; milliseconds to fade out over. Default 0.

Returns: nothing.

Since: 3.00, as a Hypseus Singe extension. See also: musicPlay, musicPause

Example
musicStop(theme, 1500)   -- Away over a second and a half.

2.25.9. musicUnload

musicUnload(id)

Hypseus extension. Stops the track and frees it. The handle is invalid afterwards and using it terminates the script.

Parameters:

  • id — number; a music handle.

Returns: nothing.

Since: 3.00, as a Hypseus Singe extension. See also: musicLoad

Example
musicUnload(theme)

Navigation meshes baked from scene geometry, and the crowd agents that walk them (see 3D Scenes, Navigation). navNew and navLoad return a mesh handle and navAgentNew an agent handle; both are integers, checked on every call, and an invalid one terminates the script. Positions are world units, speeds units a second and slopes degrees. Up to eight meshes at once, 128 agents on each and 256 in all. The queries and the agents need a mesh that navBuild has baked or navLoad has read; before that the queries return nil, navDraw draws nothing and navAgentNew ends the script.

navAddNode(nav, node)

Adds the node’s mesh, and the mesh of every node under it, to the geometry the navigation mesh will be baked from, as they stand in the world right now, so place them first. A model instance’s root node adds the whole model, and a level built from primitives can be added node by node. Only mesh geometry counts: bodies, sprites and text add nothing. Ends the script once the mesh has been built.

Since: 3.00. See also: navNew, navBuild, modelInstance

Example
-- The ground and the walls are walkable geometry; the crates are not, they move.
local nav = navNew(0.4, 1.8, 45, 0.4)
navAddNode(nav, ground)
for _, wall in ipairs(walls) do
    navAddNode(nav, wall)
end
navAddNode(nav, modelInstance(towerModel))
navBuild(nav)
navAgentDelete(agent)

Takes the agent off the mesh and frees its handle; the node stays where it is and is not moved again. Deleting the mesh with navDelete does this for every agent on it. An invalid handle terminates the script.

Since: 3.00. See also: navAgentNew, navDelete

Example
-- A guard that dies stops navigating; the ragdoll takes the model from here.
function killGuard(guard)
    navAgentDelete(guard.agent)
    guard.agent = nil
    ragdollActivate(guard.model)
    ragdollApplyImpulse(guard.model, "b_Spine02_03", 0, 20, -30)
end
x, y, z = navAgentGetVelocity(agent)

How the crowd is moving the agent this frame, in world units a second along each axis; its length runs up to the agent’s speed and falls to zero as it stops. For choosing between an idle, a walk and a run animation, or scaling the walk cycle to the ground covered.

Returns: Three numbers.

Since: 3.00. See also: navAgentMoveTo, animationPlay

Example
function onOverlayUpdate()
    for agent, fox in pairs(foxes) do
        local vx, vy, vz = navAgentGetVelocity(agent)
        local speed      = math.sqrt(vx * vx + vz * vz)
        local clip       = (speed < 0.1) and "Survey" or ((speed < 2.5) and "Walk" or "Run")
        if fox.clip ~= clip then
            animationPlay(fox.node, clip, true, 1, 0.2)
            fox.clip = clip
        end
    end
    return OVERLAY_NOT_UPDATED
end
arrived = navAgentIsArrived(agent)

Whether the agent has reached the last target navAgentMoveTo gave it: within one and a half of its radii of the target and nearly stopped. It turns true at the moment onNavArrived fires and stays true until the next navAgentMoveTo; it is false for an agent that was never sent anywhere or was stopped on the way.

Returns: True or false.

Since: 3.00. See also: onNavArrived, navAgentMoveTo, navAgentStop

Example
-- The patrol waits at each post for a while before moving on.
function onOverlayUpdate()
    if navAgentIsArrived(patrol) then
        waitFrames = waitFrames + 1
        if waitFrames > 180 then
            post       = post % #posts + 1
            waitFrames = 0
            navAgentMoveTo(patrol, posts[post][1], posts[post][2], posts[post][3])
        end
    end
    return OVERLAY_NOT_UPDATED
end
ok = navAgentMoveTo(agent, x, y, z)

Sends the agent walking to the point of the mesh nearest x, y, z, looking up to 2 units sideways and 4 up or down for one. The crowd plans the route over the following frames and steers the agent round the other agents on the way; onNavArrived fires once it gets there. Returns false, and leaves the agent as it was, when no point of the mesh is near enough or the crowd refuses the request. A new target replaces the old one at any time.

Parameters:

  • agent — the handle from navAgentNew.

  • x, y, z — the destination in world units; it is snapped onto the mesh.

Returns: True when the agent set off.

Since: 3.00. See also: navAgentStop, navNearest, navPath

Example
-- The sidekick follows the hero, re-aimed twice a second.
function onOverlayUpdate()
    ticks = ticks + 1
    if ticks % 30 == 0 then
        local hx, hy, hz = nodeGetWorldPosition(hero)
        if not navAgentMoveTo(sidekickAgent, hx, hy, hz) then
            navAgentStop(sidekickAgent)       -- The hero is off the mesh:  jumping, swimming
        end
    end
    return OVERLAY_NOT_UPDATED
end
agent = navAgentNew(nav, node, radius, height, speed)

Puts an agent of that size on the mesh at the point nearest the node’s world position (the raw position when nothing is within 2 units sideways and 4 up or down), walking at speed units a second and accelerating at 8 units a second squared. The radius and height are kept at 0.01 or more, as navNew keeps its own. From then on the engine moves the node along the mesh every frame, in its parent’s frame, and turns it about Y to face the way it is going whenever it moves faster than 0.05 units a second; nodes look down -Z, as models do. The crowd steers agents round each other, anticipates turns and keeps them apart. To drive a player controller on the node instead of placing the node, see navAgentSetPlayer. Ends the script when the mesh is not built or 128 agents are already on it.

Parameters:

  • nav — a built mesh from navNew or navLoad.

  • node — the node to move; usually a model instance’s root.

  • radius — the agent’s radius for keeping clear of others, in world units; the mesh’s own radius or less.

  • height — the agent’s height, in world units.

  • speed — top walking speed, in world units a second.

Returns: The agent’s handle, an integer.

Example
for i = 1, 6 do
    local fox = modelInstance(foxModel)
    nodeSetScale(fox, 0.01)
    nodeSetPosition(fox, navRandomPoint(nav))
    animationPlay(fox, "Walk", true)
    local agent = navAgentNew(nav, fox, 0.35, 1.0, 1.4)
    navAgentMoveTo(agent, navRandomPoint(nav))
end

function onNavArrived(agent)
    navAgentMoveTo(agent, navRandomPoint(nav))
end
navAgentSetPlayer(agent, player)

With true, the agent stops placing its node and instead feeds its velocity, each frame, to the player controller on the node as a playerMove (horizontal only), so stairs, slopes, pushing and collisions keep working; before every crowd update the controller’s world position is read back as the agent’s own, so being shoved off course is planned around. The node still turns to face its way. The node needs a controller from playerNew, or nothing moves. With false the agent goes back to placing the node itself.

Since: 3.00. See also: playerNew, playerMove, navAgentNew

Example
-- A companion who follows the hero through the level and can be knocked about.
local companion = nodeNew()
nodeSetPosition(companion, 2, 0.05, 0)
playerNew(companion, 0.3, 1.0)
local companionFox = modelInstance(foxModel)
nodeSetParent(companionFox, companion)
nodeSetScale(companionFox, 0.01)
local companionAgent = navAgentNew(nav, companion, 0.3, 1.0, 2.0)
navAgentSetPlayer(companionAgent, true)
navAgentStop(agent)

Forgets the agent’s target: the crowd stops steering it toward anything, it slows to a stand where it is, and onNavArrived does not fire. Other agents still walk round it. Send it somewhere with navAgentMoveTo to set off again.

Since: 3.00. See also: navAgentMoveTo, navAgentIsArrived

Example
-- Guards freeze when the alarm sounds and turn toward the noise.
function raiseAlarm(x, y, z)
    for _, guard in ipairs(guards) do
        navAgentStop(guard.agent)
        nodeLookAt(guard.node, x, y, z)
        animationPlay(guard.node, "Survey", true, 1, 0.3)
    end
    soundPlay(alarm)
end
navBuild(nav)

Bakes the walkable mesh from everything navAddNode added: floors and slopes up to the mesh’s angle, steps up to its height, with the agent’s radius trimmed off round every wall and drop, and anything with less than the agent’s height above it left out. The bake works on cells a third of the agent’s radius across and covers at most 4096 by 4096 of them, so a small radius over a big level is slow and can fail; a tenth of a second for Sponza on a desktop, a few seconds on a Raspberry Pi. The geometry that was added is freed afterward, and nothing more can be added; bake another mesh instead. navSave keeps the result. Ends the script when nothing was added, the mesh is already built, or the bake fails.

Since: 3.00. See also: navNew, navAddNode, navSave, navDraw

Example
-- The bake happens once, while the title screen is up, and is kept for next time.
local sponza = modelInstance(modelLoad("Models/Sponza.glb"))
local nav    = navNew(0.4, 1.6, 45, 0.3)
navAddNode(nav, sponza)
navBuild(nav)
navSave(nav, "sponza.nav")
if debugging then
    navDraw(nav)                              -- One frame, to eyeball the bake
end
navDelete(nav)

Frees the mesh and every agent on it; their nodes stay where they are. The mesh handle and the agent handles are invalid afterward and terminate the script if used. The slot is free for a new navNew or navLoad.

Since: 3.00. See also: navNew, navAgentDelete

Example
function loadLevel(index)
    if levelNav then
        navDelete(levelNav)                   -- Takes the old level's agents with it
    end
    nodeDelete(levelRoot)
    levelRoot = modelInstance(levels[index].model)
    levelNav  = navNew(0.4, 1.6, 45, 0.3)
    navAddNode(levelNav, levelRoot)
    navBuild(levelNav)
end
navDraw(nav)
navDraw(nav, r, g, b)

Draws the baked mesh’s polygons as lines over the scene for this frame, cyan unless colored, each polygon as a fan of triangles so a polygon with more than three sides shows its diagonals. Call it every frame while looking; it costs three lines per triangle, and a mesh that is not built yet draws nothing. For checking that a bake covers the floor and stays off the furniture, alongside physicsSetDebug.

Parameters:

  • nav — the mesh.

  • r, g, b — the line color, 0 to 255 each; default 0, 255, 255.

Since: 3.00. See also: lineDraw, navBuild, physicsSetDebug

Example
function onOverlayUpdate()
    if showNavMesh then
        navDraw(nav)                          -- Cyan over the floor
        local path = navPath(nav, heroX, heroY, heroZ, goalX, goalY, goalZ)
        if path then
            for i = 2, #path do
                lineDraw(path[i - 1][1], path[i - 1][2], path[i - 1][3], path[i][1], path[i][2], path[i][3], 255, 60, 40)
            end
        end
    end
    return OVERLAY_NOT_UPDATED
end
nav = navLoad(name, agentRadius, agentHeight)

Loads a mesh navSave wrote, looked for among the game’s files first (so a baked mesh can ship with the game, packed or not) and then in the game’s data folder. The mesh comes back built, ready for agents and queries, and takes no more navAddNode. The slope and step it was baked with are in the file; the agent radius and height are what the crowd steers with, so give the values it was baked for. Ends the script when the file cannot be read, is not a navigation mesh, is shorter than the mesh its header describes (truncated, or edited by hand), or no mesh slot is free.

Parameters:

  • name — the file’s name, relative to the game directory or the data folder.

  • agentRadius — the agent radius the mesh was baked for, in world units.

  • agentHeight — the agent height it was baked for, in world units.

Returns: The mesh handle, an integer.

Since: 3.00. See also: navSave, navNew

Example
-- The shipped bake for the museum; agents 0.8 wide and 1.7 tall.
local museum = modelInstance(modelLoad("museum.glb"))
local nav    = navLoad("museum.nav", 0.4, 1.7)
for _, visitor in ipairs(visitors) do
    visitor.agent = navAgentNew(nav, visitor.node, 0.35, 1.7, 1.2)
    navAgentMoveTo(visitor.agent, navRandomPoint(nav))
end
x, y, z = navNearest(nav, x, y, z)

The closest point of the mesh to a point, searching up to 2 units sideways and 4 up or down, or nil when there is nothing that near. For snapping a spawn point, a drop or a click onto the floor before handing it to an agent, and for finding the floor’s height under a point.

Parameters:

  • nav — the mesh.

  • x, y, z — the point to snap, in world units.

Returns: Three numbers, or nil.

Since: 3.00. See also: navPath, navAgentMoveTo, sceneUnproject

Example
-- Spawn the enemy on the floor nearest the spawner, or not at all.
function spawnEnemy(spawner)
    local sx, sy, sz = nodeGetWorldPosition(spawner)
    local x, y, z    = navNearest(nav, sx, sy, sz)
    if x then
        local enemy = modelInstance(enemyModel)
        nodeSetPosition(enemy, x, y, z)
        enemies[#enemies + 1] = { node = enemy, agent = navAgentNew(nav, enemy, 0.4, 1.8, 2.5) }
    end
end
nav = navNew(agentRadius, agentHeight, maxSlope, maxStep)

Starts a navigation mesh for agents of that radius and height that can climb steps up to maxStep units and slopes up to maxSlope degrees. The radius and height are kept at 0.01 or more, the slope between 0 and 89 and the step at 0 or more. The radius also sets the bake’s resolution, a cell being a third of it, so it decides how long navBuild takes and how big a level it can cover. Add geometry with navAddNode, then navBuild. Ends the script when eight meshes already exist.

Parameters:

  • agentRadius — the agents' radius, in world units; walls are padded by this.

  • agentHeight — how tall they are; lower ceilings are not walkable.

  • maxSlope — the steepest walkable slope, in degrees.

  • maxStep — the highest step they climb, in world units.

Returns: The mesh handle, an integer.

Since: 3.00. See also: navAddNode, navBuild, navLoad

Example
-- Sponza for an agent 0.8 wide and 1.6 tall that climbs 0.3 and walks slopes to 45 degrees.
local sponza = modelInstance(modelLoad("Models/Sponza.glb"))
local nav    = navNew(0.4, 1.6, 45, 0.3)
navAddNode(nav, sponza)
navBuild(nav)
points = navPath(nav, x0, y0, z0, x1, y1, z1)

The corners of the shortest walk from one point to another, both snapped onto the mesh first, as a table of { x, y, z } tables with the first at the start and the last at the end; up to 256 corners. When the end cannot be reached the walk stops at the nearest reachable point on the way, so the last corner is always somewhere an agent can stand. nil when either end is nowhere near the mesh or no path is found. For drawing a route, measuring how far something is on foot, or moving something along it yourself; agents do this on their own.

Parameters:

  • nav — the mesh.

  • x0, y0, z0 — where the walk starts.

  • x1, y1, z1 — where it ends.

Returns: A table of { x, y, z } tables, or nil.

Since: 3.00. See also: navAgentMoveTo, navRaycast, navNearest

Example
-- How far the exit is on foot, for the map's distance readout.
function walkingDistance(fromX, fromY, fromZ, toX, toY, toZ)
    local path  = navPath(nav, fromX, fromY, fromZ, toX, toY, toZ)
    local total = 0
    for i = 2, #(path or {}) do
        local dx = path[i][1] - path[i - 1][1]
        local dz = path[i][3] - path[i - 1][3]
        total    = total + math.sqrt(dx * dx + dz * dz)
    end
    return path and total or nil
end
x, y, z = navRandomPoint(nav)

A random point on the walkable mesh, anywhere it reaches, for wandering, scattering pickups or placing a spawn. nil only when the mesh is not built.

Returns: Three numbers, or nil.

Since: 3.00. See also: navAgentMoveTo, navNearest

Example
-- Scatter twenty coins over the floor, each a little above it.
for i = 1, 20 do
    local x, y, z = navRandomPoint(nav)
    local coin    = nodeNew()
    nodeSetMesh(coin, coinMesh, gold)
    nodeSetPosition(coin, x, y + 0.3, z)
    coins[#coins + 1] = coin
end
blocked, x, y, z = navRaycast(nav, x0, y0, z0, x1, y1, z1)

Whether a straight walk from one point to another leaves the mesh, at a wall or a drop, and where it would. The start is snapped onto the mesh; false alone means the way is clear, or that the start is nowhere near the mesh. When blocked, the point is where the line crosses the mesh’s edge, its height interpolated between the two ends. A cheap check for whether a shortcut exists before asking navPath.

Parameters:

  • nav — the mesh.

  • x0, y0, z0 — where the walk starts.

  • x1, y1, z1 — where it would end.

Returns: false, or true and the point where the walk leaves the mesh.

Since: 3.00. See also: navPath, physicsRaycast

Example
-- A thrown grenade only rolls as far as the floor lets it.
function landingSpot(fromX, fromY, fromZ, toX, toY, toZ)
    local blocked, hx, hy, hz = navRaycast(nav, fromX, fromY, fromZ, toX, toY, toZ)
    if blocked then
        return hx, hy, hz
    end
    return toX, toY, toZ
end
navSave(nav, name)

Writes the baked mesh to the game’s data folder under name, for navLoad next time, or to copy into the game directory to ship. The mesh must be built. Ends the script when it is not, or when the file cannot be written.

Since: 3.00. See also: navLoad, navBuild

Example
-- Baked once on this machine, then loaded from the data folder in later runs.
local nav = navNew(0.4, 1.6, 45, 0.3)
navAddNode(nav, level)
navBuild(nav)
navSave(nav, "level1.nav")
debugPrint("Navigation mesh baked and saved.")

2.27. Net

What the engine adds underneath Singe/Net.singe, the menu’s HTTP client. Most games never touch it: posting a score or fetching a catalogue goes through Net.singe, which calls this for you.

2.27.1. netTrustHost

ok = netTrustHost(connection, host)

Makes a LuaSec client connection refuse a certificate that is not for host. Call it after ssl.wrap and before the handshake. A context made with verify = "peer" checks that the server’s certificate chains to a root it trusts, which says the certificate is genuine but not whose it is: without this call a genuine certificate for any other name is accepted, and connection:sni(host) does not change that, since it only tells the server which certificate to present. With it, the handshake fails unless the certificate lists host among its names, or among its addresses when host is an IP address. A wildcard in a certificate stands for one whole label.

Parameters:

  • connection — a connection from ssl.wrap. Anything else ends the script.

  • host — string, the name or address being connected to.

Returns: true, or false when the name could not be set.

Since: 3.00. See also: netTrustSystem

Example
-- The certificate has to be for the server that was asked for.
local wrapped = ssl.wrap(sock, context)
wrapped:sni("scores.example.com")
netTrustHost(wrapped, "scores.example.com")

2.27.2. netTrustSystem

lists, report = netTrustSystem(context)

Adds the machine’s own trusted root certificates to a LuaSec client context, on top of whatever the context already holds (normally the shipped Singe/cacerts.pem). A connection made with the context then verifies when either list knows the server’s root. The machine’s list is, in order: the file or directory named by SSL_CERT_FILE or SSL_CERT_DIR when set; otherwise the distribution’s bundle on Linux (the first of the usual six places that exists), the root system store on Windows, or the system anchors on macOS. cacerts.local.pem in the data folder is added as well when it exists; the engine never writes it.

lists is how many lists added anything. report names what was consulted, one what path per line (what is system or local), for an error message a person can act on.

Since: 3.00. See also: utilSha256

Example
-- One context for every request:  the shipped bundle, then this machine's roots on top.
local ssl     = require("ssl")
local context = ssl.newcontext({ mode = "client", protocol = "any", verify = "peer", cafile = "Singe/cacerts.pem" })
local lists, report = netTrustSystem(context)

debugPrint("Trusting the shipped bundle and " .. lists .. " more:\n" .. report)

2.28. Node

Every object in a scene is a node in one tree: node 0 is the root, and every other node hangs under a parent. A node carries a position, a rotation, and a scale relative to that parent, and may draw a mesh with a material, show a sprite or a line of text, or shine as a light; children inherit the transform of everything above them. Handles are integers returned by nodeNew, modelInstance, and lightNew; a handle whose node has been deleted aborts the script when passed back, and a freed handle may be reused by a later nodeNew. Positions and sizes are in scene units and rotations in degrees, with +Y up and -Z forward as described in 3D Scenes.

2.28.1. nodeNew

node = nodeNew()
node = nodeNew(parent)

Creates an empty node at its parent’s origin, unrotated, at scale 1, visible, casting shadows, with no mesh or material. Without parent the node goes under the root; with one it becomes that node’s last child and moves with it from then on. Empty nodes serve as pivots and groups: place one, then hang meshes, lights, or a camera under it and move the group as a whole.

Returns: The node handle.

Since: 3.00. See also: nodeSetMesh, nodeSetParent, nodeDelete, lightNew

Example
-- A turret whose barrel pivots on the turret, which turns on the base.
local steel  = materialNew()
materialSetColor(steel, 140, 145, 150)
local base   = nodeNew()
local turret = nodeNew(base)
local barrel = nodeNew(turret)
nodeSetMesh(base,   meshCylinder(1, 0.3), steel)
nodeSetMesh(turret, meshSphere(0.6), steel)
nodeSetMesh(barrel, meshCylinder(0.1, 1.2), steel)
nodeSetPosition(barrel, 0, 0, -0.8)
nodeSetRotation(barrel, 90, 0, 0)

2.28.2. nodeDelete

nodeDelete(node)

Removes the node and everything under it, freeing every handle in that subtree; a sprite or text on any of them is released too. Meshes and materials the nodes drew are untouched, since other nodes may share them. If the deleted node was the camera, the scene falls back to the default view. The root node cannot be deleted; asking aborts the script.

Since: 3.00. See also: nodeNew, nodeSetVisible, meshDelete

Example
-- Shots live for two seconds, then their nodes go.
function fireShot(ship)
    local shot = nodeNew()
    nodeSetMesh(shot, shotMesh, tracer)
    nodeSetPosition(shot, nodeGetWorldPosition(ship))
    shots[#shots + 1] = { node = shot, born = os.clock() }
end

function reapShots()
    for i = #shots, 1, -1 do
        if os.clock() - shots[i].born > 2 then
            nodeDelete(shots[i].node)
            table.remove(shots, i)
        end
    end
end

2.28.3. nodeFind

node = nodeFind(name)
node = nodeFind(name, root)

Searches depth first for the first node named name, starting at root (the scene root when omitted) and checking root itself before its children, each child’s subtree in turn. Returns nil when nothing matches. Model nodes carry the names from their glTF file, so a bone, a mesh, or a marker empty placed in Blender can be found by that name under the instance’s root. Names set with nodeSetName are found the same way.

Returns: A node handle, or nil.

Example
-- Hang a torch on the hero's right hand, found by its bone name.
local hero = modelInstance(heroModel)
local hand = nodeFind("hand_R", hero)
if hand then
    local torch = modelInstance(torchModel)
    nodeSetParent(torch, hand)
    nodeSetPosition(torch, 0, 0.05, 0)
    nodeSetRotation(torch, 0, 0, -90)
end

2.28.4. nodeGetChildren

children = nodeGetChildren(node)

The node’s direct children as a table of handles, in the order they were attached; re-parenting a node puts it at the end of its new parent’s list. Grandchildren are not included; recurse to walk a whole subtree. An empty table means the node has no children.

Returns: A table of node handles.

Since: 3.00. See also: nodeGetParent, nodeFind, nodeSetParent

Example
-- Give every part of a loaded prop the same worn material.
local function paint(node, material)
    nodeSetMaterial(node, material)
    for _, child in ipairs(nodeGetChildren(node)) do
        paint(child, material)
    end
end

local crate = modelInstance(crateModel)
paint(crate, wornWood)

2.28.5. nodeGetMorph

weight = nodeGetMorph(node, nameOrIndex)

The current weight of one morph target of the node’s mesh, given by name or by number from 1 in the order nodeGetMorphs lists them. The node is the one carrying the mesh, not a model instance’s root. A name or number the mesh does not have aborts the script.

Returns: A number, 0 until something sets the target.

Since: 3.00. See also: nodeSetMorph, nodeGetMorphs

Example
-- Ease the smile in over several frames instead of snapping it on.
function onOverlayUpdate()
    local now    = nodeGetMorph(face, "smile")
    local target = happy and 1 or 0
    nodeSetMorph(face, "smile", now + (target - now) * 0.1)
    return OVERLAY_UPDATED
end

2.28.6. nodeGetMorphs

names = nodeGetMorphs(node)

The morph targets of the node’s mesh as a table of names, in the order the file stores them; that order is the numbering nodeSetMorph and nodeGetMorph accept. Exporters that write no names give empty strings, and those targets can still be set by number. A node with no mesh, or a mesh without targets, gives an empty table.

Returns: A table of strings.

Since: 3.00. See also: nodeSetMorph, nodeGetMorph, modelLoad

Example
-- Map the face's target names to numbers once, so lip sync can index them.
local head    = nodeFind("Head", hero)
local visemes = {}
for index, name in ipairs(nodeGetMorphs(head)) do
    if name ~= "" then
        visemes[name] = index
    end
end
debugPrint(string.format("%d morph targets on the head", #nodeGetMorphs(head)))

2.28.7. nodeGetName

name = nodeGetName(node)

The node’s name: whatever nodeSetName gave it or its glTF name for a model node, an empty string when it has neither. The root node is named root.

Returns: A string.

Since: 3.00. See also: nodeSetName, nodeFind

Example
-- Print a model's node tree to the console while working out bone names.
local function dump(node, depth)
    debugPrint(string.rep("  ", depth) .. nodeGetName(node) .. " (" .. node .. ")")
    for _, child in ipairs(nodeGetChildren(node)) do
        dump(child, depth + 1)
    end
end

dump(modelInstance(heroModel), 0)

2.28.8. nodeGetParent

parent = nodeGetParent(node)

The handle of the node’s parent, or nil for the root. Every other node has a parent, even if only the root.

Returns: A node handle, or nil.

Since: 3.00. See also: nodeSetParent, nodeGetChildren

Example
-- Climb from a picked mesh node to the top of its model instance.
local function instanceRoot(node)
    local parent = nodeGetParent(node)
    while parent and parent ~= 0 do
        node   = parent
        parent = nodeGetParent(node)
    end
    return node
end

2.28.9. nodeGetPosition

x, y, z = nodeGetPosition(node)

The node’s position relative to its parent, as last set by nodeSetPosition, nodeMove, or the engine (a body, a vehicle, or an animation moving it). For where the node is in the world, use nodeGetWorldPosition.

Returns: Three numbers.

Since: 3.00. See also: nodeSetPosition, nodeGetWorldPosition, nodeMove

Example
-- The camera trails the car, three units up, three to the right, and nine behind.
function onOverlayUpdate()
    local cx, cy, cz = nodeGetPosition(car)
    nodeSetPosition(camera, cx + 3, cy + 3, cz + 9)
    nodeLookAt(camera, cx, cy, cz - 3)
    return OVERLAY_UPDATED
end

2.28.10. nodeGetQuaternion

x, y, z, w = nodeGetQuaternion(node)

The node’s rotation relative to its parent as a unit quaternion, the form models and animations store. Use it to copy a rotation between nodes or to keep a pose without the ambiguity of Euler angles.

Returns: Four numbers.

Since: 3.00. See also: nodeSetQuaternion, nodeGetRotation

Example
-- Remember the door's pose before the ragdoll test, then put it back.
local px, py, pz     = nodeGetPosition(door)
local qx, qy, qz, qw = nodeGetQuaternion(door)

function resetDoor()
    nodeSetPosition(door, px, py, pz)
    nodeSetQuaternion(door, qx, qy, qz, qw)
end

2.28.11. nodeGetRotation

x, y, z = nodeGetRotation(node)

The node’s rotation relative to its parent as Euler angles in degrees, decomposed the same way nodeSetRotation composes them: turned about Y, then tilted about X, then rolled about Z. The angles describe the same rotation that was set but need not be the same numbers: X comes back between -90 and 90, and when it reaches 90 or -90 the twist is given to Y with Z reported as 0.

Returns: Three numbers.

Since: 3.00. See also: nodeSetRotation, nodeGetQuaternion

Example
-- A compass in the overlay from the ship's heading.
function onOverlayUpdate()
    local _, heading = nodeGetRotation(ship)
    overlayClear()
    fontPrint(20, 20, string.format("Heading %03d", (360 - heading) % 360))
    return OVERLAY_UPDATED
end

2.28.12. nodeGetScale

x, y, z = nodeGetScale(node)

The node’s own scale per axis, as set by nodeSetScale (1, 1, 1 for a new node). Parents' scales are not folded in.

Returns: Three numbers.

Since: 3.00. See also: nodeSetScale

Example
-- Grow the power-up toward full size, a little each frame.
function onOverlayUpdate()
    local size = nodeGetScale(powerUp)
    if size < 1 then
        nodeSetScale(powerUp, math.min(1, size + 0.05))
    end
    return OVERLAY_UPDATED
end

2.28.13. nodeGetWorldPosition

x, y, z = nodeGetWorldPosition(node)

Where the node’s origin is in world space, with every parent’s transform applied, as of the last rendered frame. Changes made this frame (yours, or a body’s) show after the next render, and a node created this frame reports 0, 0, 0 until then. This is the position to feed sceneProject or a distance check.

Returns: Three numbers.

Since: 3.00. See also: sceneProject, nodeLookAt, nodeGetPosition

Example
-- A name tag in the overlay above the duck, wherever the physics took it.
function onOverlayUpdate()
    local dx, dy, dz = nodeGetWorldPosition(duck)
    local sx, sy     = sceneProject(dx, dy + 0.8, dz)
    overlayClear()
    if sx then
        fontPrint(sx - 20, sy, "DUCK")
    end
    return OVERLAY_UPDATED
end

2.28.14. nodeLookAt

nodeLookAt(node, x, y, z)

Rotates the node so its own -Z points at a world position, keeping its +Y as close to world up as the direction allows. That is what cameras and lights want, and it serves a turret or a head tracking a target as well. Only the node’s rotation changes; its position stays. If the target coincides with the node’s position nothing changes.

Notes: The world point is converted into the parent’s space using the parent’s transform from the last rendered frame; a node whose parent moved this same frame aims from where the parent was.

Since: 3.00. See also: cameraSet, lightNew, nodeSetRotation

Example
local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, -8, 3, 6)
nodeLookAt(sun, 0, 0, 0)
lightSetShadow(sun, true)

local camera = nodeNew()
nodeSetPosition(camera, 0, 2.2, 7)
nodeLookAt(camera, 0, 1.3, 0)
cameraSet(camera)

2.28.15. nodeMove

nodeMove(node, dx, dy, dz)

Moves the node along its own axes: the offset is turned by the node’s current rotation and added to its position, so nodeMove(ship, 0, 0, -0.1) drives the ship forward wherever it is pointing and nodeMove(ship, 0.1, 0, 0) strafes it right. Use nodeSetPosition for an absolute place in the parent’s space.

Since: 3.00. See also: nodeSetPosition, nodeRotate

Example
-- Tank controls:  turn with left and right, drive with up and down.
function onOverlayUpdate()
    if keyboardIsDown(SCANCODE_LEFT)  then nodeRotate(tank, 0,  2, 0) end
    if keyboardIsDown(SCANCODE_RIGHT) then nodeRotate(tank, 0, -2, 0) end
    if keyboardIsDown(SCANCODE_UP)    then nodeMove(tank, 0, 0, -0.08) end
    if keyboardIsDown(SCANCODE_DOWN)  then nodeMove(tank, 0, 0,  0.04) end
    return OVERLAY_UPDATED
end

2.28.16. nodeRotate

nodeRotate(node, dx, dy, dz)

Turns the node by the given degrees about its own axes, on top of its current rotation: nodeRotate(wheel, 5, 0, 0) every frame spins the wheel on its own X however the axle is tilted. The three angles are combined the way nodeSetRotation combines them (Y, then X, then Z) before being applied. Positive angles turn counter-clockwise when looking down the axis toward the origin.

Since: 3.00. See also: nodeSetRotation, nodeMove, nodeSetQuaternion

Example
-- The logo turns half a degree a frame about its own up axis.
local logo = modelInstance(logoModel)
nodeSetPosition(logo, 0, -2.5, 0)
nodeSetRotation(logo, 0, -30, 0)

function onOverlayUpdate()
    nodeRotate(logo, 0, 0.5, 0)
    return OVERLAY_UPDATED
end

2.28.17. nodeSetBillboard

nodeSetBillboard(node, mode)

Turns the node to face the camera every frame. BILLBOARD_ALL faces it squarely, taking all three axes from the camera; BILLBOARD_Y turns about world up only, so the node stays upright (trees, health bars); BILLBOARD_NONE, the default, does not turn at all. The node’s world position and scale are kept and its own rotation is ignored while a mode is set. Any other value aborts the script. It works on meshes as well as sprites and text, and turns to whichever camera is drawing: a view sees the billboard face on too, while its shadow follows the window’s camera.

Since: 3.00. See also: nodeSetSprite, nodeSetText, cameraSet

Example
-- A name over the fox facing the camera squarely, and a crate icon that
-- turns about its own up axis only.
local tag = nodeNew()
nodeSetParent(tag, fox)
nodeSetPosition(tag, 0, 110, 0)
nodeSetScale(tag, 50)
nodeSetText(tag, "FOX", 0.6)
nodeSetBillboard(tag, BILLBOARD_ALL)
nodeSetShadow(tag, false)
local icon = nodeNew()
nodeSetParent(icon, fox)
nodeSetPosition(icon, 0, 150, 0)
nodeSetScale(icon, 50)
nodeSetSprite(icon, spriteLoad("crate.png"), 0.5)
nodeSetBillboard(icon, BILLBOARD_Y)

2.28.18. nodeSetLayer

nodeSetLayer(node, layer)

Chooses where in the window the node is drawn. LAYER_SCENE, the default, draws it in the scene beneath the overlay; LAYER_FRONT draws it after the overlay, by the same camera with the same lights, into a transparent layer of its own. A node in the front layer takes its children with it, whatever their own setting. Any other value aborts the script. See In Front of the Overlay.

Since: 3.00. See also: sceneEnable, nodeSetVisible, emitterSetLayer

Example
-- The player's ship stands on the 2D map screen while it is open, and goes
-- back into the world when it closes.
function showMap(open)
    nodeSetLayer(ship, open and LAYER_FRONT or LAYER_SCENE)
end

2.28.19. nodeSetMaterial

nodeSetMaterial(node, material)
nodeSetMaterial(node, nil)

Puts a material on whatever mesh the node has, keeping the mesh. nil removes it, leaving the default look: white, half rough, untextured. Use it to restyle a model’s part, to swap a highlight material in and out, or to dress a mesh the engine made for you, such as a rope’s tube from softNew. A material handle that does not exist aborts the script.

Since: 3.00. See also: nodeSetMesh, materialNew, softNew

Example
-- The rope hangs from the crane; the engine makes its tube, we dress it.
local hemp = materialNew()
materialSetColor(hemp, 170, 140, 90)
materialSetRoughness(hemp, 1)
local rope = nodeNew()
nodeSetPosition(rope, 4, 4, -1)
softNew(rope, SOFT_ROPE, 6.5, 4, -1, 16, 0.04)
nodeSetMaterial(rope, hemp)
softSetMass(rope, 1.5)
softPin(rope, 4, 4, -1, crane)

2.28.20. nodeSetMesh

nodeSetMesh(node, mesh)
nodeSetMesh(node, mesh, material)

Gives the node a mesh to draw, with a material or, when omitted, the default look (white, half rough). Both arguments must be live handles; a missing mesh or material aborts the script. Any node can draw, including a node inside a model instance, and any number of nodes can share one mesh. The node’s morph weights are sized to the new mesh’s targets and start at 0.

Example
-- A car body with four wheels, each a cylinder turned so its X is the axle.
local car = nodeNew()
nodeSetMesh(car, meshBox(1.8, 0.5, 4.0), paint)
nodeSetPosition(car, 0, 0.9, 0)
local tireMesh = meshCylinder(0.35, 0.25, 16)
for _, p in ipairs({ { -0.95, -0.2, -1.4 }, { 0.95, -0.2, -1.4 }, { -0.95, -0.2, 1.4 }, { 0.95, -0.2, 1.4 } }) do
    local wheel = nodeNew(car)
    nodeSetPosition(wheel, p[1], p[2], p[3])
    local tire = nodeNew(wheel)
    nodeSetMesh(tire, tireMesh, rubber)
    nodeSetRotation(tire, 0, 0, 90)
end

2.28.21. nodeSetMorph

nodeSetMorph(node, nameOrIndex, weight)

Sets how much of one morph target (blend shape) the node’s mesh shows, by name or by number from 1; weights are usually 0 to 1 and several targets add up. The node is the one carrying the mesh, which for a model is a child of the instance root (nodeFind by the mesh’s name, or nodeGetChildren). A target the mesh does not have aborts the script. An animation with a weights channel writes the weights every frame while it plays, overriding what you set.

Notes: Up to eight targets with non-zero weights apply per mesh in a frame; with more, the eight strongest by absolute weight are used.

Since: 3.00. See also: nodeGetMorph, nodeGetMorphs, animationPlay

Example
-- Lip sync from a table of mouth openings per disc frame.
local face = nodeFind("Head", hero)

function onOverlayUpdate()
    nodeSetMorph(face, "mouthOpen", mouthByFrame[discGetFrame()] or 0)
    return OVERLAY_UPDATED
end

2.28.22. nodeSetName

nodeSetName(node, name)

Names the node so nodeFind can find it later, replacing any name it had (a model node’s glTF name included). Names need not be unique; nodeFind returns the first match in depth-first order.

Since: 3.00. See also: nodeFind, nodeGetName

Example
-- Spawned crates are named so the level script can find them by slot.
for slot = 1, 6 do
    local crate = nodeNew()
    nodeSetMesh(crate, crateMesh, wood)
    nodeSetPosition(crate, slot * 1.5 - 5, 0.5, -3)
    nodeSetName(crate, "crate" .. slot)
end
nodeSetVisible(nodeFind("crate4"), false)

2.28.23. nodeSetParent

nodeSetParent(node, parent)

Moves the node, with its whole subtree, under another parent, becoming that parent’s last child. The node’s local position, rotation, and scale are kept as they are, so it now sits at that offset from the new parent and moves with it; pass 0 to return it to the root. The root cannot be moved, and a node cannot go under itself or one of its own descendants; either aborts the script.

Since: 3.00. See also: nodeGetParent, nodeNew, nodeSetPosition

Example
-- Picking up a crate:  it rides in the hand from now on, set down later.
function pickUp(crate)
    nodeSetParent(crate, nodeFind("hand_R", hero))
    nodeSetPosition(crate, 0, 0.3, 0)
    nodeSetRotation(crate, 0, 0, 0)
end

function putDown(crate, x, y, z)
    nodeSetParent(crate, 0)
    nodeSetPosition(crate, x, y, z)
end

2.28.24. nodeSetPosition

nodeSetPosition(node, x, y, z)

Places the node at x, y, z in its parent’s space; for a node under the root that is world space. Children come along. A node with a dynamic body on it is moved by the physics afterward; set its position before bodyNew, or teleport it through the body calls.

Since: 3.00. See also: nodeMove, nodeGetPosition, nodeSetRotation

Example
-- Crates dropped along a ridge, each six units above the ground there.
for i = 1, 10 do
    local crate  = nodeNew()
    local x, z   = -20 + i * 4, -12
    nodeSetMesh(crate, meshBox(1, 1, 1), wood)
    nodeSetPosition(crate, x, (terrainGetHeight(hills, x, z) or 0) + 6, z)
    nodeSetRotation(crate, i * 17, i * 31, 0)
    bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 1, 1, 1)
end

2.28.25. nodeSetQuaternion

nodeSetQuaternion(node, x, y, z, w)

Sets the node’s rotation relative to its parent as a quaternion, for values that came from nodeGetQuaternion, a model, or your own math. The quaternion is normalized on the way in, so it need not be unit length.

Since: 3.00. See also: nodeSetRotation, nodeGetQuaternion

Example
-- The ghost copies the hero's pose exactly, a beat behind.
local qx, qy, qz, qw = nodeGetQuaternion(hero)
local px, py, pz     = nodeGetPosition(hero)
history[#history + 1] = { px, py, pz, qx, qy, qz, qw }
if #history > 30 then
    local old = table.remove(history, 1)
    nodeSetPosition(ghost, old[1], old[2], old[3])
    nodeSetQuaternion(ghost, old[4], old[5], old[6], old[7])
end

2.28.26. nodeSetRotation

nodeSetRotation(node, x, y, z)

Sets the node’s rotation relative to its parent as Euler angles in degrees, replacing whatever it had: the node is turned about its Y (yaw) first, then tilted about its X (pitch), then rolled about its Z. Positive angles turn counter-clockwise looking down the axis toward the origin, so nodeSetRotation(plane, 90, 0, 0) tips a floor plane up to face +Z.

Since: 3.00. See also: nodeRotate, nodeSetQuaternion, nodeLookAt

Example
-- A monitor screen standing on a stand, facing the camera at +Z.
local monitor = nodeNew()
nodeSetMesh(monitor, meshPlane(2.0, 1.5), screen)
nodeSetPosition(monitor, -3, 2.1, 1.06)
nodeSetRotation(monitor, 90, 0, 0)
-- A ramp tilted 25 degrees about Z.
local ramp = nodeNew()
nodeSetMesh(ramp, meshBox(6, 0.2, 3), asphalt)
nodeSetRotation(ramp, 0, 0, 25)

2.28.27. nodeSetScale

nodeSetScale(node, scale)
nodeSetScale(node, x, y, z)

Scales the node and everything under it, uniformly with one factor or per axis with three. Loaded models are often in centimeters or meters; scale the instance root once to fit your scene and place things under it in the model’s own units. Sprites and text on the node are scaled too, on top of their height.

Since: 3.00. See also: nodeGetScale, modelInstance

Example
-- The fox is modeled in centimeters:  a hundredth brings it to meters.
local fox = modelInstance(foxModel)
nodeSetParent(fox, player)
nodeSetScale(fox, 0.01)
nodeSetRotation(fox, 0, 90, 0)
-- A flattened sphere for a puddle.
local puddle = nodeNew()
nodeSetMesh(puddle, meshSphere(0.5, 24), water)
nodeSetScale(puddle, 1.5, 0.05, 1.2)

2.28.28. nodeSetShadow

nodeSetShadow(node, casts)

Whether the node’s mesh is drawn into shadow maps; true for every new node. Turn it off for the mesh round a light (a bulb, a flame) so it does not shadow its own light, and for anything that glows. The node still draws and still receives shadows from others. It applies to the node only, not its children.

Example
-- A bulb inside its shade:  the glass casts nothing, the shade does.
local shade = nodeNew(stand)
nodeSetMesh(shade, meshCone(0.45, 0.5, 24), brass)
nodeSetPosition(shade, 0, 0.9, 0)
local bulbMesh = nodeNew(stand)
nodeSetMesh(bulbMesh, meshSphere(0.08, 12), glow)
nodeSetPosition(bulbMesh, 0, 0.8, 0)
nodeSetShadow(bulbMesh, false)
local bulb = lightNew(LIGHT_POINT)
nodeSetParent(bulb, bulbMesh)
lightSetShadow(bulb, true)

2.28.29. nodeSetSprite

nodeSetSprite(node, sprite)
nodeSetSprite(node, sprite, height)
nodeSetSprite(node, sprite, height, lit)
nodeSetSprite(node, nil)
nodeSetSprite(node)

Shows a loaded sprite on the node: a quad height world units tall (default 1) and as wide as the picture’s aspect makes it, blended by the picture’s alpha, drawn from both sides, and lit by the scene unless lit is false. Every frame of an animated sprite is uploaded and the first shows; nodeSetSpriteFrame picks another. The quad becomes the node’s mesh with a private material, replacing any mesh, sprite, or text it had; nil or no second argument takes the picture off and leaves the node empty. It aborts the script when the 3D renderer is unavailable.

Parameters:

  • sprite — a handle from spriteLoad, or nil to clear.

  • height — the quad’s height in world units, default 1; the node’s scale multiplies it.

  • lit — true (default) shades the picture with the scene’s lights and shadows; false shows it as is.

Example
-- A crate icon floating over the fox, turning to face the player.
local icon = nodeNew()
nodeSetParent(icon, fox)
nodeSetPosition(icon, 0, 150, 0)
nodeSetScale(icon, 50)
nodeSetSprite(icon, spriteLoad("crate.png"), 0.5)
nodeSetBillboard(icon, BILLBOARD_Y)
-- An unlit glow that reads the same in shadow.
local flare = nodeNew(torchTip)
nodeSetSprite(flare, spriteLoad("flare.png"), 0.3, false)
nodeSetBillboard(flare, BILLBOARD_ALL)

2.28.30. nodeSetSpriteFrame

nodeSetSpriteFrame(node, frame)

Which frame of the node’s animated sprite shows, counted from 0. The node’s sprite does not advance on its own; drive it from onOverlayUpdate. A node without a sprite, or a frame it does not have, aborts the script; text and a still sprite have only frame 0.

Since: 3.00. See also: nodeSetSprite, spriteLoad

Example
-- A campfire sprite cycling its frames at ten a second.
local fire = nodeNew()
nodeSetPosition(fire, 2, 0.4, -1)
nodeSetSprite(fire, spriteLoad("campfire.gif"), 0.8, false)
nodeSetBillboard(fire, BILLBOARD_Y)

function onOverlayUpdate()
    nodeSetSpriteFrame(fire, math.floor(os.clock() * 10) % fireFrames)
    return OVERLAY_UPDATED
end

2.28.31. nodeSetText

nodeSetText(node, text)
nodeSetText(node, text, height)
nodeSetText(node, nil)
nodeSetText(node)

Shows a line of text on the node, rendered in the selected font (fontSelect) at the current quality (fontQuality) in the foreground color (colorForeground), on a quad height world units tall (default 1) and as wide as the rendered text makes it. It is unlit, blended, and drawn from both sides: name tags, signs, a score over a table. Like a sprite it becomes the node’s mesh, replacing any mesh, sprite, or text there; call again to change the text, nil or no second argument to take it off. With no font selected, or without the 3D renderer, it aborts the script.

Example
-- A fixed sign by the lamp, and a score that updates when it changes.
fontSelect(signFont)
colorForeground(255, 240, 200)
local sign = nodeNew()
nodeSetPosition(sign, 4.2, 1.2, -1.2)
nodeSetRotation(sign, 0, -30, 0)
nodeSetText(sign, "LAMP", 0.5)

function setScore(points)
    nodeSetText(scoreboard, string.format("%06d", points), 0.4)
end

2.28.32. nodeSetVisible

nodeSetVisible(node, visible)

Hides or shows the node and everything under it; a child’s own flag still applies when its parent is shown again. Hidden meshes are not drawn and hidden lights stop shining. Use it to keep a marker or a spare prop ready without deleting and rebuilding it.

Since: 3.00. See also: nodeSetMesh, nodeDelete

Example
-- A marker that appears where the ball last hit the paddle.
local mark = nodeNew()
nodeSetMesh(mark, meshSphere(0.08, 12), markLook)
nodeSetVisible(mark, false)

function onCollision(a, b, x, y, z)
    if (a == ball and b == paddle) or (a == paddle and b == ball) then
        nodeSetPosition(mark, x, y, z)
        nodeSetVisible(mark, true)
    end
end

2.29. Overlay

The overlay is a 32-bit RGBA surface composited over the video every frame; all 2D drawing lands on it. Its coordinates are the overlay resolution set by overlaySetResolution, which defaults to half the video’s width and height, and are scaled to the window at display time. Draw from onOverlayUpdate (or from singeMain in the Threaded model) and return OVERLAY_UPDATED when something changed. The overlay* primitives draw one-pixel outlines in the current foreground color and silently clip whatever falls outside the surface. overlayPrint is the exception: it takes character-cell coordinates and copies the built-in console font as is, ignoring the color settings.

2.29.1. overlayBanner

overlayBanner(text [, height])

Hypseus extension. Shows a short message over the picture for about thirty drawn frames and then takes it away again. height is where it sits, as a percent down the picture, from 1 to 95; the default is 47, which is Hypseus’s own, and a number outside that range is replaced by the default rather than refused.

A message longer than 60 characters is ignored, exactly as Hypseus ignores it. The banner is drawn by the same shipped document the subtitles use (Singe/subtitle.rml, styled by Singe/subtitle.rcss), so it looks like a subtitle and is styled with them; while it is up it takes the place of any subtitle, and the subtitle comes back when it times out. The text is drawn as text, so <, > and & reach the screen as themselves.

Parameters:

  • text — string; up to 60 characters.

  • height — optional number; 1 to 95, a percent down the picture. Default 47.

Returns: nothing.

Since: 3.00, as a Hypseus Singe extension. See also: srtLoad, Subtitles, overlayPrint

Example
-- Tell the player what just happened without building a HUD for it.
overlayBanner("Extra life!", 20)

2.29.2. overlayBox

overlayBox(x1, y1, x2, y2)

Draws the outline of the axis-aligned rectangle with opposite corners (x1, y1) and (x2, y2), as four one-pixel lines in the foreground color. Both corners are inclusive and may be given in any order. There is no filled variant; fill the whole overlay with overlayClear on a background color, or an area with a stretched sprite.

Since: 2.00 See also: overlayLine, colorForeground, overlayClear

Example
-- Frame the overlay in red and outline each platform block.
function onOverlayUpdate()
    overlayClear()
    colorForeground(255, 0, 0, 255)
    overlayBox(0, 0, overlayGetWidth() - 1, overlayGetHeight() - 1)
    colorForeground(90, 90, 110, 255)
    for _, b in ipairs(blocks) do
        overlayBox(b.x - b.w / 2, b.y - b.h / 2, b.x + b.w / 2, b.y + b.h / 2)
    end
    return OVERLAY_UPDATED
end

2.29.3. overlayCircle

overlayCircle(x, y, radius)

Draws a one-pixel circle outline in the foreground color, centered on (x, y), using the midpoint algorithm. A radius of 0 or less draws nothing. Coordinates and radius are integers in overlay units; fractions are truncated.

Parameters:

  • x, y — center in overlay coordinates.

  • radius — radius in overlay units.

Since: 2.00 See also: overlayEllipse, overlayPlot, colorForeground

Example
-- A gun-sight crosshair that turns red while the player is hit.
function onOverlayUpdate()
    if hitTimer > 0 then
        colorForeground(255, 0, 0, 255)
        hitTimer = hitTimer - 1
    else
        colorForeground(255, 255, 255, 255)
    end
    overlayCircle(aimX, aimY, 8)
    overlayLine(aimX - 12, aimY, aimX + 12, aimY)
    overlayLine(aimX, aimY - 12, aimX, aimY + 12)
    return OVERLAY_UPDATED
end

2.29.4. overlayClear

overlayClear()

Fills the whole overlay with the current background color. When the color is the same as the last clear’s, only what was drawn since is filled again, so clearing an overlay that holds a few lines of text costs next to nothing whatever its size. The background starts as transparent black, so with no colorBackground call this erases the overlay back to invisible and the video shows through. A partly opaque background dims the video; a fully opaque one hides it. Most games call it first thing in onOverlayUpdate. Any arguments are ignored.

Since: 1.x See also: colorBackground, onOverlayUpdate

Example
-- Dim the paused video to half brightness behind the service menu.
function onOverlayUpdate()
    colorBackground(0, 0, 0, 127)
    overlayClear()
    spriteDraw(serviceTitle, (overlayGetWidth() - spriteGetWidth(serviceTitle)) / 2, 25)
    return OVERLAY_UPDATED
end

2.29.5. overlayEllipse

overlayEllipse(x1, y1, x2, y2)

Draws a one-pixel ellipse outline in the foreground color, inscribed in the axis-aligned rectangle with opposite corners (x1, y1) and (x2, y2). The corners may be given in any order. A rectangle of equal width and height gives a circle, so this is also the way to draw a circle from its bounding box rather than its center.

Since: 2.00 See also: overlayCircle, overlayBox

Example
-- Highlight the selected cabinet with an oval that fits its panel.
function onOverlayUpdate()
    spriteDraw(cabinetSprite, CABINET_X, CABINET_Y)
    if selected == CABINET then
        colorForeground(255, 220, 0, 255)
        overlayEllipse(CABINET_X - 6, CABINET_Y - 6, CABINET_X + CABINET_W + 6, CABINET_Y + CABINET_H + 6)
    end
    return OVERLAY_UPDATED
end

2.29.6. overlayGetFontHeight

result = overlayGetFontHeight()

Returns the height in pixels of one character cell of the built-in console font, which is what overlayPrint counts in. The console font is a single embedded image of 256 glyphs loaded once before any script runs, so this never changes while the program is running. Any arguments are ignored.

Returns: integer height of one cell in pixels.

Example
-- How many rows of console text fit, whatever the overlay size is.
ROWS = overlayGetHeight() // overlayGetFontHeight()
overlayPrint(0, ROWS - 1, "along the bottom")

2.29.7. overlayGetFontWidth

result = overlayGetFontWidth()

Returns the width in pixels of one character cell of the built-in console font, which is what overlayPrint counts in. Use it with overlayGetWidth to work out how many columns fit, or to place console text against something drawn in pixels. Divide with // rather than /: Lua’s ordinary division gives a fractional number, and a cell position must be whole. Any arguments are ignored.

Returns: integer width of one cell in pixels.

Example
-- Center a line of console text without hard-coding the number of columns.
local columns = overlayGetWidth() // overlayGetFontWidth()
local text    = "GAME OVER"

overlayPrint((columns - #text) // 2, 10, text)

2.29.8. overlayGetHeight

result = overlayGetHeight()

Returns the height of the overlay surface in overlay units: the value last given to overlaySetResolution, or half the video height before any call. Read it at startup, after setting the resolution, to lay out positions in terms of the actual drawing area. Any arguments are ignored.

Returns: integer height.

Since: 1.x See also: overlayGetWidth, overlaySetResolution

Example
-- Anchor the text panel to the bottom margin whatever the overlay size is.
overlaySetResolution(discGetWidth(), discGetHeight())
TEXT_Y = 200
TEXT_H = overlayGetHeight() - MARGIN_Y - TEXT_Y
TEXT_LINE_LIMIT = math.floor(TEXT_H / LINE_HEIGHT)

2.29.9. overlayGetWidth

result = overlayGetWidth()

Returns the width of the overlay surface in overlay units: the value last given to overlaySetResolution, or half the video width before any call. Use it to right-align or center elements instead of hard-coding a width. Any arguments are ignored.

Returns: integer width.

Since: 1.x See also: overlayGetHeight, overlaySetResolution

Example
-- Right-align the marquee and center the title, independent of resolution.
function onOverlayUpdate()
    local marqueeX = overlayGetWidth() - MARGIN_X - spriteGetWidth(marqueeSprite)
    spriteDraw(marqueeSprite, marqueeX, MARGIN_Y)
    spriteDraw(titleSprite, (overlayGetWidth() - spriteGetWidth(titleSprite)) / 2, 25)
    return OVERLAY_UPDATED
end

2.29.10. overlayLine

overlayLine(x1, y1, x2, y2)

Draws a one-pixel Bresenham line in the foreground color from (x1, y1) to (x2, y2), both endpoints included. Pixels outside the overlay are dropped, so endpoints may lie off the surface. Coordinates are truncated to integers.

Since: 2.00 See also: overlayPlot, overlayBox, colorForeground

Example
-- Draw the laser from the gun to the aim point, and a simple aim reticle.
function onOverlayUpdate()
    overlayClear()
    if firing then
        colorForeground(255, 64, 64, 255)
        overlayLine(GUN_X, GUN_Y, aimX, aimY)
    end
    colorForeground(255, 255, 255, 255)
    overlayCircle(aimX, aimY, 6)
    return OVERLAY_UPDATED
end

2.29.11. overlayPlot

overlayPlot(x, y)

Sets one overlay pixel to the foreground color. A point outside the surface is ignored. Each call locks and unlocks the overlay, so plotting thousands of points per frame from Lua is slow; use a sprite for anything with structure and keep this for stars, sparks, and debugging marks.

Since: 2.00 See also: overlayLine, colorForeground

Example
-- A slowly twinkling star field behind the title.
function onOverlayUpdate()
    overlayClear()
    for _, star in ipairs(stars) do
        local shade = 128 + math.floor(127 * math.sin(frameCount * star.speed))
        colorForeground(shade, shade, shade, 255)
        overlayPlot(star.x, star.y)
    end
    frameCount = frameCount + 1
    return OVERLAY_UPDATED
end

2.29.12. overlayPrint

overlayPrint(column, row, text)

Prints a string with the engine’s built-in fixed-width console font. Unlike every other drawing call, the position is a character cell: the engine multiplies column and row by the glyph width and height, so (0, 0) is the top-left cell and (1, 0) is one glyph to the right. Glyphs are copied from the font image as they are; the current foreground and background colors are not applied, and only the font’s own background is transparent. Each byte of the string selects one of the font’s 256 glyphs, so the text is treated as bytes, not UTF-8. Characters that would run past the right edge of the overlay are dropped, and text starting beyond the edge draws nothing.

Parameters:

  • column, row — character cell, 0 at the top left.

  • text — the string to print.

Notes: The console font is meant for diagnostics and service screens. Use fontPrint or fontToSprite for colored or proportional text. The size of a cell in pixels is overlayGetFontWidth by overlayGetFontHeight, so overlayGetWidth() // overlayGetFontWidth() is how many columns fit.

Since: 1.x See also: fontPrint, overlayClear, colorBackground

Example
-- Diagnostics in the corner while a download completes.
function onOverlayUpdate()
    colorBackground(0, 0, 0, 127)
    overlayClear()
    overlayPrint(1, 1, "FRAME " .. discGetFrame())
    overlayPrint(1, 2, download.url .. " " .. tostring(download.finished))
    if download.finished then
        overlayPrint(1, 3, download.result)
    end
    return OVERLAY_UPDATED
end

2.29.13. overlaySetMonochrome

overlaySetMonochrome(enabled)

Hypseus extension. Shows the overlay in gray: before each upload the engine converts a copy of it to luma with the BT.601 weights, keeping the alpha channel as it is (Hypseus thresholds it). The overlay’s own pixels stay in color, so nothing the script reads back changes, and drawing goes on as usual. Pair it with vldpSetMonochrome for a black and white mode. A non-boolean argument aborts the script.

Parameters:

  • enabled — boolean.

Since: 3.00, as a Hypseus Singe extension. See also: vldpSetMonochrome, overlayClear

Example
-- One setting drives both the disc and the overlay.
function applyChroma(color)
    vldpSetMonochrome(not color)
    overlaySetMonochrome(not color)
end

2.29.14. overlaySetResolution

overlaySetResolution(width, height)

Replaces the overlay with a new surface of the given size and discards everything drawn so far. From then on every overlay coordinate, sprite position, and overlayGetWidth or overlayGetHeight result is in the new space, which the engine scales to the window at display time. Call it once during startup, before drawing; the default is half the video resolution in each dimension. A width or height of 0 or less ends the script with an error. Higher resolutions give finer placement and sharper text for more compositing work per frame; the disc’s native size from discGetWidth and discGetHeight is the common choice.

Parameters:

  • width — new overlay width in pixels, greater than 0.

  • height — new overlay height in pixels, greater than 0.

Example
-- Match the disc, then lay the menu out in that coordinate space.
overlaySetResolution(discGetWidth(), discGetHeight())
MARGIN_X  = 16
MARGIN_Y  = 16
MARQUEE_W = 200
MARQUEE_X = overlayGetWidth() - MARGIN_X - MARQUEE_W
CABINET_H = overlayGetHeight() - MARGIN_Y - CABINET_Y

2.29.15. setOverlayFullAlpha

setOverlayFullAlpha()

Hypseus extension, accepted and ignored. Hypseus blits its overlay with the alpha channel thresholded at 128, so a half-transparent pixel is either fully opaque or gone, and this asks it to upload the surface as it stands and blend properly instead. Singe’s overlay has always been full RGBA with real per-pixel alpha, so what this asks for is already in force.

Returns: nothing.

Since: 3.00

2.29.16. setOverlayLinearScale

setOverlayLinearScale(enabled)

Hypseus extension. Chooses how the overlay is filtered on its way to the window. With true, the default and what a reload restores, it is sampled linearly, so a low resolution overlay softens rather than blocking up; with false the nearest pixel is taken, which keeps pixel art, one-pixel outlines and small text crisp. Linear is the default because it is how every Singe release has drawn the overlay; Hypseus defaults to the nearest pixel instead, so a game moved from Hypseus that never calls this will look slightly softer until it does. Nothing about the drawing changes, only the final scale from the overlay resolution to the window, so everything on the overlay — the primitives, fonts, sprites and the 3D layer — goes through the one filter together, and the disc picture behind it is untouched. The setting survives overlaySetResolution, which replaces the overlay. A non-boolean argument aborts the script.

Parameters:

  • enabled — boolean.

Since: 3.00, as a Hypseus Singe extension. See also: overlaySetResolution, spriteQuality

Example
-- A 320x240 overlay on a 4K screen; the painted title smooth, the game's pixel art crisp.
overlaySetResolution(320, 240)

function showTitle()
    setOverlayLinearScale(true)
    mode = "title"
end

function startGame()
    setOverlayLinearScale(false)
    mode = "play"
end

2.29.17. setOverlayOnTop

loaded, id = setOverlayOnTop(enabled)

Hypseus extension. Chooses whether the overlay and the GUIs drawn over the picture are above the bezel artwork or below it. Only artwork drawn in front of the picture (--bezelflip) is ever above them, so with the artwork behind — which is the default — this changes nothing. false is the setting a game starts with, and Hypseus’s own default. It is remembered until the script reloads.

The setting is only recorded while artwork is loaded; without it the call does nothing and answers false and "0", exactly as Hypseus does. A non-boolean argument aborts the script.

Parameters:

  • enabled — boolean; true puts the overlay and the GUIs above the artwork.

Returns: boolean, whether artwork is loaded, and its identifier as a string ("0" when none is).

Since: 3.00, as a Hypseus Singe extension. See also: mainBezelLoaded, guiDrawScreen, Bezels

Example
-- The cabinet frame overlaps the picture, but the score line has to stay readable.
if mainBezelLoaded() then
    setOverlayOnTop(true)
end

2.29.18. setOverlayOpacity

setOverlayOpacity(alpha)

Hypseus extension. How solid the whole overlay is, from 0 (invisible) to 255 (as the game drew it). It multiplies whatever alpha the overlay’s own pixels already carry, so a half transparent sprite stays half as solid as the rest; it does not change the overlay’s contents, and nothing has to be redrawn.

The level is clamped to 0 to 255 rather than refused, and a script starts at 255. It is remembered until the script reloads, and it survives a change of overlay resolution.

The GUIs, the 3D scene and the bezel artwork are drawn separately and are not affected.

Parameters:

  • alpha — number; 0 to 255.

Returns: nothing.

Since: 3.00, as a Hypseus Singe extension. See also: setOverlayLinearScale, overlaySetResolution

Example
-- Fade the whole heads-up display out over half a second.
local fade = 255
function onOverlayUpdate()
    fade = math.max(0, fade - 8)
    setOverlayOpacity(fade)
    return OVERLAY_UPDATED
end

2.30. Physics

World-level calls: the ray query, gravity, the 2D mode, pausing and debug drawing. Physics is initialized with the engine, so there is nothing to enable before the first bodyNew; the world steps sixty times a second from the wall clock, after animations and before the scene renders. Positions and distances are in world units and gravity in units per second squared. See Physics in Game Development for how bodies, nodes and the frame fit together.

2.30.1. physicsRaycast

node, hx, hy, hz, nx, ny, nz = physicsRaycast(x, y, z, dx, dy, dz)
node, hx, hy, hz, nx, ny, nz = physicsRaycast(x, y, z, dx, dy, dz, maxDistance)
node, hx, hy, hz, nx, ny, nz = physicsRaycast(x, y, z, dx, dy, dz, maxDistance, ignoredNodes)

Finds the first body along a ray from (x, y, z) in the direction (dx, dy, dz), within maxDistance world units. The direction is normalized, so any length works, but a zero direction hits nothing. Triggers and players are hit like any other body; a player is reported by its node. With sceneUnproject supplying two points along the mouse, this is picking; straight down from a point, it is a height probe.

Parameters:

  • x, y, z — the ray’s start in world space.

  • dx, dy, dz — its direction; only the direction matters.

  • maxDistance — how far to look; default 1000, and 0 or less, or nil, means the default.

  • ignoredNodes — optional list of up to 4096 non-negative node handles excluded from this query. Exclusion uses the exact node returned by a ray, so include child body nodes when needed. Bodies keep their enabled state and contacts. A ray starting inside an ignored body can hit the next body normally. An empty list, or nil, preserves the unfiltered query; stale handles have no effect.

Returns: The body’s node, the hit point, and the surface normal there, or a single nil when nothing is hit.

Since: 3.00. See also: sceneUnproject, bodyApplyImpulse, lineDraw

Example
-- Drop the marker onto whatever level ground is under the cursor.
function onOverlayUpdate()
    local mx, my = mouseGetPosition(0)
    local ox, oy, oz = sceneUnproject(mx, my, 0)
    local fx, fy, fz = sceneUnproject(mx, my, 10)
    local hit, hx, hy, hz, nx, ny, nz = physicsRaycast(ox, oy, oz, fx - ox, fy - oy, fz - oz, 60)
    nodeSetVisible(marker, hit ~= nil and ny > 0.7)
    if hit then
        nodeSetPosition(marker, hx, hy + 0.05, hz)
    end
    return OVERLAY_NOT_UPDATED
end
Example
-- A shot from the player's chest.  The ray starts inside the player's own body and passes
-- the shield the player carries, so both are left out;  nothing about either body changes.
function fire()
    local px, py, pz = nodeGetPosition(player)
    local hit, hx, hy, hz = physicsRaycast(px, py + 1.4, pz, aimX, aimY, aimZ, 80, { player, shield })
    nodeSetVisible(spark, hit ~= nil)
    if hit then
        nodeSetPosition(spark, hx, hy, hz)
    end
end

2.30.2. physicsSet2D

physicsSet2D(planar)

With true, bodies made from now on move only in X and Y and turn only about Z: a 2D game’s world, usually in overlay coordinates with gravity pointing +Y so things fall down the screen. Bodies already made keep their freedom, so call it before any bodyNew; false returns to full 3D for bodies made afterward. Players are different: while the mode is on, every player, whenever it was made, runs along X with its Z held at 0 and playerMove takes a single value. The 2D world works without a GPU, the Raspberry Pi 3 included.

Since: 3.00. See also: physicsSetGravity, bodyNew, playerMove

Example
-- A platformer world in overlay pixels: gravity down the screen, a floor and walls.
physicsSet2D(true)
physicsSetGravity(0, 900, 0)
local width, height = overlayGetWidth(), overlayGetHeight()
floor = nodeNew()
nodeSetPosition(floor, width / 2, height - 10, 0)
bodyNew(floor, BODY_STATIC, SHAPE_BOX, width, 20, 50)
leftWall = nodeNew()
nodeSetPosition(leftWall, -10, height / 2, 0)
bodyNew(leftWall, BODY_STATIC, SHAPE_BOX, 20, height, 50)

2.30.3. physicsSetDebug

physicsSetDebug(mask)

Draws what the simulation holds as lines over the scene each frame, for as long as the mask is set: DEBUG_SHAPES for every moving body’s shape in wireframe (soft bodies included, and enabled players in yellow), DEBUG_CONSTRAINTS for joints, ragdoll joints and vehicle constraints with their limits, DEBUG_CONTACTS for a red cross where bodies met this step, and DEBUG_VELOCITIES for a line along each moving body’s velocity. Add the flags together; DEBUG_ALL is all four. Static bodies' shapes stay off unless DEBUG_STATIC is added, because a level mesh is a lot of lines. DEBUG_NONE turns it off, and nothing is drawn or costs while it is off.

Notes: A build of Singe made without Jolt’s debug renderer prints a message to the console and draws nothing.

Since: 3.00. See also: lineDraw, navDraw, physicsSetEnabled

Example
-- Toggle the physics overlay with a debug key; static shapes too, since the level is small.
function onInputPressed(switch)
    if switch == SWITCH_BUTTON3 then
        showPhysics = not showPhysics
        if showPhysics then
            physicsSetDebug(DEBUG_ALL + DEBUG_STATIC)
        else
            physicsSetDebug(DEBUG_NONE)
        end
    end
end

2.30.4. physicsSetEnabled

physicsSetEnabled(enabled)

Pauses the simulation with false and resumes it with true. While paused no step runs: dynamic bodies hold still and keep their velocities, kinematic bodies stop following their nodes, players stop moving, and no onCollision or onTrigger fires. Time does not accumulate while paused, so resuming does not replay the missed steps. The game’s own pause does the same without this call; use it for a menu, a cutscene or a freeze-frame that leaves the rest of the game running.

Since: 3.00. See also: physicsSetGravity, bodyIsResting

Example
-- Freeze the world while the inventory is open.
function openInventory()
    inventoryOpen = true
    physicsSetEnabled(false)
end

function closeInventory()
    inventoryOpen = false
    physicsSetEnabled(true)
end

2.30.5. physicsSetGravity

physicsSetGravity(x, y, z)

Sets the acceleration every dynamic body and player feels, in world units per second squared along each world axis. The default is 0, -9.81, 0, Earth’s gravity in meters; 0, 0, 0 is space, and a 2D game in overlay pixels wants something like 0, 900, 0 since overlay Y runs down the screen. The direction opposite to gravity is "up" for players: the way they stand, jump and climb steps.

A change of gravity wakes every body, soft bodies included, so a crate that came to rest falls when gravity turns sideways, and cloth blows when a wind made of gravity changes. Setting the same gravity again wakes nothing.

Since: 3.00. See also: bodyNew, physicsSet2D, playerSetGravityScale

Example
-- The moon level: a sixth of Earth's pull, and a longer jump to match.
function startLevel(name)
    if name == "moon" then
        physicsSetGravity(0, -1.62, 0)
        jumpSpeed = 3.0
    else
        physicsSetGravity(0, -9.81, 0)
        jumpSpeed = 4.5
    end
end

2.31. Player

A player is a character controller on a node: where a body goes where forces send it, a player goes where the script says, walking floors, climbing steps, sliding along walls, riding platforms and shoving light bodies aside. Players are addressed by their node, and a node carries a body or a player, not both. Sizes and speeds are in world units (meters in a 3D scene, overlay pixels in a 2D world) and the controller’s tolerances scale with the shape, so a 30 pixel capsule behaves like a 0.3 meter one. The player drives its node’s position each step and leaves the rotation to the script. Every call here ends the script when the node has no player. See Physics in Game Development, Players.

2.31.1. playerNew

playerNew(node, radius, height)
playerNew(node, SHAPE_CAPSULE, radius, height)
playerNew(node, SHAPE_CYLINDER, radius, height)
playerNew(node, SHAPE_SPHERE, radius, 0)
playerNew(node, SHAPE_BOX, width, height, depth)
playerNew(node, SHAPE_HULL)

Puts a player on the node, where the node is in the world right now: a capsule of that radius and total height, or any convex bodyNew shape with its sizes, scaled by the node’s world scale. The shape stands on the node’s origin, so the node is the feet. It starts with a mass of 70 kilograms, a push of 300 newtons, a slope limit of 45 degrees, a step height of 0.3 scaled by the shape, gravity scale 1 and the default swimming rates. Replaces any body or player the node had. Ends the script for SHAPE_MESH (a player needs a convex shape; use SHAPE_HULL), when physics is not available on this machine, or when the player cannot be made (a hull with too little mesh, or sixteen players already).

Parameters:

  • radius, height — a capsule, radius and total height along up, caps included.

  • SHAPE_* — a shape constant followed by its bodyNew sizes; SHAPE_HULL takes none and wraps the node’s mesh and everything under it.

Notes: A call with exactly three arguments is always a capsule, so a sphere needs a fourth argument (any number) after its radius to be read as SHAPE_SPHERE.

Since: 3.00. See also: playerMove, playerDelete, bodyNew, nodeSetParent

Example
-- The hero: a capsule with the Fox model hanging off the node, feet on the ground.
hero = nodeNew()
nodeSetPosition(hero, 0, 0.05, 0)
playerNew(hero, 0.3, 1.0)
playerSetStep(hero, 0.35)
fox = modelInstance(modelLoad(DIR .. "Models/Fox.glb"))
nodeSetParent(fox, hero)
nodeSetScale(fox, 0.01)
animationPlay(fox, "Walk", true)
-- A robot is a box; it turns square corners and cannot roll.
robot = nodeNew()
playerNew(robot, SHAPE_BOX, 0.8, 1.6, 0.6)

2.31.2. playerDelete

playerDelete(node)

Removes the player; the node and whatever hangs under it stay where they are. Deleting the node removes its player too, and so does giving the node a body with bodyNew. Ends the script when the node has no player.

Since: 3.00. See also: playerNew, playerSetEnabled

Example
-- The hero climbs into the car: the controller goes, the model rides along.
function boardCar()
    playerDelete(hero)
    nodeSetParent(hero, car)
    nodeSetPosition(hero, 0, 0.4, 0)
    driving = true
end

2.31.3. playerMove

playerMove(node, vx, vz)
playerMove(node, vx, vy, vz)
playerMove(node, vx)

Tells the player the velocity it wants this frame, in world units per second. On the ground or in the air the two horizontal values are used as given, on top of whatever platform it stands on; the vertical part comes from gravity, the ground and playerJump, and vy is ignored. When the player is swimming all three values steer it, and the water eases its velocity toward them at the drag from playerSetSwim, sinking at the sink speed when vy is 0. In a 2D world a single vx runs along X and any vz is ignored. Call it every frame from onOverlayUpdate: the request is consumed by that frame’s steps, and a frame without one stands still.

Parameters:

  • vx, vz — the horizontal velocity wanted, world units per second (2D: overlay pixels along X).

  • vy — the vertical velocity wanted while swimming; positive is up.

Example
-- Walk with the left stick, swim up while the button is held, face the way of travel.
function onOverlayUpdate()
    local vx = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_X) / 32767 * 3
    local vz = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_Y) / 32767 * 3
    if playerIsSwimming(hero) then
        playerMove(hero, vx, surfacing and 1.5 or 0, vz)
    else
        playerMove(hero, vx, vz)
    end
    nodeSetRotation(hero, 0, math.deg(math.atan(-vz, vx)), 0)
    return OVERLAY_NOT_UPDATED
end

2.31.4. playerIsSwimming

swimming = playerIsSwimming(node)

Whether the player was in water at the last step: the middle of its shape below the surface of a bodySetWater volume. While swimming, playerMove steers in three axes, gravity gives way to the sink speed, and the water’s current carries the player.

Returns: Boolean.

Since: 3.00. See also: playerSetSwim, bodySetWater, playerMove

Example
-- Switch the animation when the hero goes in.
function onOverlayUpdate()
    local swimming = playerIsSwimming(hero)
    if swimming ~= wasSwimming then
        animationPlay(fox, swimming and "Swim" or "Walk", true)
        wasSwimming = swimming
    end
    return OVERLAY_NOT_UPDATED
end

2.31.5. playerJump

jumped = playerJump(node, speed)

Asks the player to leave the ground at that upward speed, in world units per second, at the next step. It is granted only when there is walkable ground underfoot right now, so holding a button down does not bounce the player and a jump in mid-air does nothing. A negative speed is treated as 0. The player keeps its horizontal velocity through the jump and playerMove still steers it in the air.

Returns: true when the jump was granted.

Example
-- Jump on the action button, with a sound only when it actually happened.
function onInputPressed(switch)
    if switch == SWITCH_BUTTON1 then
        if playerJump(hero, 4.5) then
            soundPlay(jumpSound)
        end
    end
end

2.31.6. playerSetSwim

playerSetSwim(node, sinkSpeed, drag)

Sets how the player behaves in water: how fast it sinks, in world units per second, when playerMove asks for no vertical movement (default 0.3), and how quickly the water pulls its velocity toward what playerMove asks, as a rate per second (default 2, so most of the difference is gone within a second; 0 never changes velocity). Both are clamped to at least 0. A heavy diver sinks fast with a high drag; a cork sinks not at all.

Parameters:

  • sinkSpeed — the drift downward with no vertical input, units per second.

  • drag — the rate the water pulls velocity toward the request, per second.

Since: 3.00. See also: playerIsSwimming, playerMove, bodySetWater

Example
-- The suit of armor drags the hero down; take it off to float.
function wearArmor(on)
    armored = on
    if on then
        playerSetSwim(hero, 1.2, 4)
    else
        playerSetSwim(hero, 0.3, 2)
    end
end

2.31.7. playerSetVelocity

playerSetVelocity(node, x, y, z)

Sets the player’s whole velocity, in world units per second along each world axis, and drops any playerMove request made this frame. The vertical part is what lasts: an upward speed lifts the player off the ground and it falls back under gravity, which is a launch pad or a bounce. The horizontal part holds only until the next step, when it is replaced by what playerMove asks (nothing, when it is not called), because a player has no horizontal momentum of its own. A knock-back or a dash is therefore an upward kick here plus a playerMove velocity fed over the following frames.

Since: 3.00. See also: playerGetVelocity, playerMove, playerJump

Example
-- A hit from the ogre throws the hero up and, over the next frames, away from it.
function onCollision(a, b, x, y, z, speed)
    if (a == hero and b == ogre) or (a == ogre and b == hero) then
        local hx, hy, hz = nodeGetPosition(hero)
        local ox, oy, oz = nodeGetPosition(ogre)
        local dx, dz = hx - ox, hz - oz
        local len = math.sqrt(dx * dx + dz * dz)
        playerSetVelocity(hero, 0, 3, 0)
        knockX, knockZ, knockFrames = dx / len * 6, dz / len * 6, 20
        health = health - 10
    end
end

2.31.8. playerGetVelocity

x, y, z = playerGetVelocity(node)

The player’s velocity after the last step, in world units per second along each world axis, including what the ground it rides on gave it. Read the vertical part to tell rising from falling, or the whole thing for a landing thud.

Returns: Three numbers.

Since: 3.00. See also: playerSetVelocity, playerIsOnGround

Example
-- Fall damage from the speed the hero hit the ground at.
function onOverlayUpdate()
    local _, vy = playerGetVelocity(hero)
    local onGround = playerIsOnGround(hero)
    if onGround and not wasOnGround and lastVy < -8 then
        health = health - math.floor((-lastVy - 8) * 5)
    end
    wasOnGround = onGround
    lastVy = vy
    return OVERLAY_NOT_UPDATED
end

2.31.9. playerIsOnGround

onGround = playerIsOnGround(node)

Whether the player is standing on walkable ground as of the last step: a surface no steeper than playerSetSlope. In the air or on a slope too steep to climb it is false. This is the same test playerJump makes.

Returns: Boolean.

Since: 3.00. See also: playerGetGround, playerJump, playerSetSlope

Example
-- Coyote time: a jump is still allowed for a few frames after walking off an edge.
function onOverlayUpdate()
    if playerIsOnGround(hero) then
        framesSinceGround = 0
    else
        framesSinceGround = framesSinceGround + 1
    end
    if jumpPressed and framesSinceGround < 6 then
        playerSetVelocity(hero, vx, 4.5, vz)
    end
    return OVERLAY_NOT_UPDATED
end

2.31.10. playerGetGround

ground, nx, ny, nz = playerGetGround(node)

What the player is standing on and the ground’s surface normal there. The node is the body underfoot, walkable or not; it is nil in the air, and the normal is then 0, 1, 0. Use the node to tell a moving platform, ice or a pressure plate from the floor, and the normal to lean a model into a slope.

Returns: The node stood on or nil, then the normal.

Since: 3.00. See also: playerIsOnGround, bodySetFriction

Example
-- Footsteps sound different on the wooden bridge, and the plate opens the gate.
function onOverlayUpdate()
    local ground = playerGetGround(hero)
    if ground == bridge then
        footstep = woodStep
    elseif ground == plate then
        openGate()
    else
        footstep = stoneStep
    end
    return OVERLAY_NOT_UPDATED
end

2.31.11. playerSetStep

playerSetStep(node, height)

The tallest step the player climbs without jumping, in world units; anything higher is a wall it slides along. The default is 0.3 for a shape whose smallest half-size is 0.3 (a capsule of radius 0.3), scaling with the shape, so a 30 pixel player in a 2D world starts at 30 pixels. The same distance is how far down the player sticks to the floor over the lip of a step, so a bigger step also keeps it glued down slopes. Negative values are clamped to 0.

Since: 3.00. See also: playerSetSlope, playerNew

Example
-- Stairs in this level rise 0.35 a tread; make sure the hero takes them.
playerNew(hero, 0.3, 1.0)
playerSetStep(hero, 0.4)
-- The 2D platformer's ledges are 26 pixels.
playerNew(runner, 16, 48)
playerSetStep(runner, 26)

2.31.12. playerSetSlope

playerSetSlope(node, degrees)

The steepest slope the player walks up, in degrees from level; steeper ground does not count as standing, so the player slides down it and cannot jump from it. The default is 45, and the value is clamped between 0 and 89. A low value makes hills into obstacles, a high one lets the player climb almost anything short of a wall.

Since: 3.00. See also: playerSetStep, playerIsOnGround

Example
-- The mountain goat climbs where the hero slides.
playerNew(goat, 0.25, 0.8)
playerSetSlope(goat, 70)
playerNew(hero, 0.3, 1.0)
playerSetSlope(hero, 40)

2.31.13. playerSetMass

playerSetMass(node, kilograms)

The player’s mass, used when it shoves dynamic bodies and as its weight on any it stands on. The default is 70 kilograms; values below 0.001 are raised to that. Mass has no effect on how the player falls or walks, only on the shoving, so pair it with playerSetPush.

Since: 3.00. See also: playerSetPush, bodySetMass

Example
-- The troll barges through what the hero has to walk around.
troll = nodeNew()
nodeSetPosition(troll, 6, 0, -3)
playerNew(troll, 0.6, 2.4)
playerSetMass(troll, 400)
playerSetPush(troll, 2000)
playerSetStep(troll, 0.8)

2.31.14. playerSetPush

playerSetPush(node, strength)

How hard the player shoves dynamic bodies it walks into, in newtons. The default 300 moves crates and balls but not cabinets; 0 walks around everything as if it were static. Negative values are clamped to 0. A body’s own bodySetMass decides what a given strength can move.

Since: 3.00. See also: playerSetMass, bodySetMass

Example
-- The strength potion lets the hero move the boulder for ten seconds.
function drinkStrength()
    playerSetPush(hero, 3000)
    strengthUntil = frames + 600
end
function onOverlayUpdate()
    if strengthUntil and frames > strengthUntil then
        playerSetPush(hero, 300)
        strengthUntil = nil
    end
    return OVERLAY_NOT_UPDATED
end

2.31.15. playerSetGravityScale

playerSetGravityScale(node, scale)

Multiplies the world’s gravity for this player alone: 1 (the default) falls like everything else, 0 floats where it is (a ladder, a zero-gravity room, a flying mount), more falls faster for a heavy feel, and less makes a floaty jump. It does not change what playerJump does at takeoff, only how quickly the player comes back down. While swimming the water’s sink speed takes gravity’s place.

Since: 3.00. See also: physicsSetGravity, playerJump, playerSetSwim

Example
-- On the ladder the hero climbs with the stick instead of falling.
function onTrigger(trigger, other, entered)
    if trigger == ladder and other == hero then
        onLadder = entered
        playerSetGravityScale(hero, entered and 0 or 1)
    end
end

2.31.16. playerSetPosition

playerSetPosition(node, x, y, z)

Teleports the player to a world position, touching nothing on the way, and stops it dead. The node moves with it and keeps its rotation. Use it for spawning, respawning and level transitions; moving the node with nodeSetPosition instead leaves the player where it was and the node is pulled back at the next step.

Since: 3.00. See also: playerSetVelocity, nodeSetPosition

Example
-- Back to the last checkpoint after a fall into the pit.
function onTrigger(trigger, other, entered)
    if trigger == pit and other == hero and entered then
        lives = lives - 1
        playerSetPosition(hero, checkpointX, checkpointY, checkpointZ)
    end
end

2.31.17. playerSetEnabled

playerSetEnabled(node, enabled)

With false the player leaves the simulation: its body is removed from the world, so it does not move, fall, drive its node or block anything, onTrigger reports it leaving every trigger it stood in, and it is left out of the debug drawing. true puts the body back and picks it up again from wherever the node is. Disable a player while a ragdoll, a cutscene or a vehicle owns the character.

Since: 3.00. See also: playerDelete, ragdollNew, bodySetEnabled

Example
-- A hard hit hands the hero's skeleton to the ragdoll.
function onCollision(a, b, x, y, z, speed)
    if (a == hero or b == hero) and speed > 6 then
        playerSetEnabled(hero, false)
        ragdollActivate(fox)
    end
end

2.32. Ragdoll

A skinned model’s skeleton handed to physics (see Physics, Ragdolls). A ragdoll is addressed by the node given to ragdollNew, usually a model instance’s root, and a node without a ragdoll terminates the script in every call after ragdollNew. Bones are named by their joint nodes, the names nodeFind sees, compared without regard to case; distances are world units, angles degrees, impulses newton seconds and motor strength newton meters. Up to eight ragdolls at once, of up to 48 bones each.

2.32.1. ragdollNew

ragdollNew(node)

Looks at the node and under it for the first skinned mesh and builds a ragdoll recipe from its skeleton: every joint that has a child joint becomes a bone, a capsule running from the joint toward its children, jointed to the nearest bone above it by a swing-twist joint limited to 45 degrees of swing and 30 of twist. Joints with no child joint, such as fingertips and the tip of a tail, ride along with their parent bone and cannot be named in the other calls. Nothing is simulated yet: the model keeps animating until ragdollActivate. Calling it again on the same node discards the old ragdoll first. Ends the script when physics is unavailable, when no skinned mesh with bones is under the node, or when eight ragdolls already exist.

Since: 3.00. See also: ragdollActivate, ragdollSetJoint, modelInstance

Example
-- A guard who runs at the player; the ragdoll is ready before the tackle.
local guard = nodeNew()
nodeSetPosition(guard, -1, 0.05, -1)
playerNew(guard, 0.3, 0.9)
local guardFox = modelInstance(foxModel)
nodeSetParent(guardFox, guard)
nodeSetScale(guardFox, 0.01)
nodeSetRotation(guardFox, 0, 90, 0)
animationPlay(guardFox, "Run", true)
ragdollNew(guardFox)                          -- Recipe only; still running

2.32.2. ragdollDelete

ragdollDelete(node)

Removes the ragdoll: its bodies and joints if it is active, then the recipe. The joint nodes stay where physics left them, so the model lies as it fell until an animation moves it, and the node is free for a new ragdollNew. A node without a ragdoll terminates the script.

Since: 3.00. See also: ragdollNew, ragdollDeactivate, nodeDelete

Example
function onOverlayUpdate()
    for i = #fallen, 1, -1 do
        local body = fallen[i]
        body.restingFrames = ragdollIsResting(body.node) and body.restingFrames + 1 or 0
        if body.restingFrames > 300 then
            ragdollDelete(body.node)              -- Still for five seconds:  clean it up
            nodeDelete(body.node)
            table.remove(fallen, i)
        end
    end
    return OVERLAY_NOT_UPDATED
end

2.32.3. ragdollSetJoint

ragdollSetJoint(node, jointName, radius, swingDegrees, twistDegrees)

Tunes one bone’s recipe. The values are read when the bodies are made, so call it before ragdollActivate; a ragdoll that is already active keeps its bodies until it is deactivated and activated again. The radius 0 asks for the automatic capsule, 0.22 of the bone’s length and never thinner than 0.02 units. The swing is the half-angle of the cone the bone may move through relative to its parent, the twist how far it may turn about its own axis; both are clamped to 0 through 179. Only bones can be named, not the leaf joints; the name is matched without regard to case, and a name with no bone ends the script.

Parameters:

  • node — the ragdoll’s node.

  • jointName — the joint node’s name, as in the model.

  • radius — the capsule’s radius in world units, or 0 for automatic.

  • swingDegrees — how far the bone may swing from its parent; default 45.

  • twistDegrees — how far it may twist about its own axis; default 30.

Since: 3.00. See also: ragdollNew, ragdollActivate, nodeFind

Example
ragdollNew(fox)
ragdollSetJoint(fox, "b_Neck_04", 0, 30, 20)          -- A stiffer neck
ragdollSetJoint(fox, "b_Tail01_012", 0.03, 80, 60)    -- A whippy tail
for _, leg in ipairs({ "b_LeftLeg01_015", "b_RightLeg01_019" }) do
    ragdollSetJoint(fox, leg, 0, 60, 15)              -- Hips swing wide, barely twist
end
ragdollActivate(fox)

2.32.4. ragdollActivate

ragdollActivate(node)

Hands the skeleton to physics from its current pose: every animation layer on the node stops, a dynamic capsule is made for each bone where its joint stands right now, the swing-twist joints are made between them, and from then on each physics step drives the joint nodes from the bodies, so the skinned mesh follows. The bones collide with the world and with each other, except each bone with its parent. The pose at this moment is what ragdollSetStrength pulls toward. A ragdoll that is already active is left as it is. Ends the script when a bone’s body cannot be made.

Example
local crashed = false

function onCollision(a, b, x, y, z, speed)
    if not crashed and (a == guard or b == guard) and speed > 1.5 then
        crashed = true
        playerSetEnabled(guard, false)        -- The controller lets go
        ragdollActivate(guardFox)             -- Physics takes the skeleton from here
        ragdollApplyImpulse(guardFox, "b_Spine02_03", 40, 30, 0)
    end
end

2.32.5. ragdollDeactivate

ragdollDeactivate(node)

Removes the bodies and joints and hands the skeleton back. The joint nodes keep the pose the ragdoll left them in, and nothing moves them until an animation plays; an animationPlay with a fade blends up from that pose, so a downed character can get to its feet. The recipe stays, so ragdollActivate can take over again later from wherever the animation has moved the skeleton. Does nothing to a ragdoll that is not active.

Since: 3.00. See also: ragdollActivate, animationPlay

Example
-- Once the body has settled, the hero gets up over half a second.
function onOverlayUpdate()
    if downed and ragdollIsResting(hero) then
        downed = false
        ragdollDeactivate(hero)
        animationPlay(hero, "GetUp", false, 1, 0.5)
        playerSetEnabled(heroController, true)
    end
    return OVERLAY_NOT_UPDATED
end

2.32.6. ragdollSetStrength

ragdollSetStrength(node, strength)

Powers every joint with a motor pulling toward the pose the ragdoll was activated in, limited to that many newton meters; 0 (default) turns the motors off and the body goes limp. The motors are springs at 4 Hz, critically damped. It can be set before activation or while the ragdoll is moving, and takes effect at the next step. It does not stand a body up, since nothing pushes off the floor: a few tens of newton meters turn a fall into a stagger and let a downed character pull its limbs in.

Since: 3.00. See also: ragdollActivate, ragdollIsResting

Example
-- Knocked down limp; a moment later the fighter tenses and curls up.
ragdollActivate(fighter)
ragdollSetStrength(fighter, 0)
downFrames = 0

function onOverlayUpdate()
    downFrames = downFrames + 1
    if downFrames == 60 then
        ragdollSetStrength(fighter, 60)
    end
    return OVERLAY_NOT_UPDATED
end

2.32.7. ragdollApplyImpulse

hit = ragdollApplyImpulse(node, jointName, x, y, z)

Adds an impulse in newton seconds, along the world axes, to the body of the bone that starts at the named joint: the punch, the shot, the explosion. The ragdoll must be active, so call ragdollActivate first and then shove. Returns false, and does nothing, when the ragdoll is not active or when no bone has that name (leaf joints are not bones); the name is matched without regard to case.

Parameters:

  • node — the ragdoll’s node.

  • jointName — the joint node’s name, as in the model.

  • x, y, z — the impulse in newton seconds, world axes.

Returns: True when the bone was found and the ragdoll was active.

Since: 3.00. See also: ragdollActivate, bodyApplyImpulse, nodeFind

Example
-- A hit from the shooter's position:  the impulse points away from the gun.
function shoot(target, gunX, gunY, gunZ, boneName)
    local tx, ty, tz = nodeGetWorldPosition(target)
    local dx         = tx - gunX
    local dz         = tz - gunZ
    local length     = math.sqrt(dx * dx + dz * dz)
    if not ragdollIsActive(target) then
        ragdollActivate(target)
    end
    ragdollApplyImpulse(target, boneName, dx / length * 30, 10, dz / length * 30)
end

2.32.8. ragdollIsActive

active = ragdollIsActive(node)

Whether physics is driving the skeleton right now: true from ragdollActivate until ragdollDeactivate or ragdollDelete. A node without a ragdoll terminates the script.

Returns: True or false.

Since: 3.00. See also: ragdollActivate, ragdollIsResting

Example
-- The health bar hangs over the model only while it is on its feet.
function onOverlayUpdate()
    overlayClear()
    for _, enemy in ipairs(enemies) do
        if not ragdollIsActive(enemy.node) then
            local x, y, z = nodeGetWorldPosition(enemy.node)
            local sx, sy  = sceneProject(x, y + 1.2, z)
            drawHealthBar(sx, sy, enemy.health)
        end
    end
    return OVERLAY_UPDATED
end

2.32.9. ragdollIsResting

resting = ragdollIsResting(node)

Whether every bone’s body has gone to sleep, which physics does once a body has been still for a moment. false while the ragdoll is not active, so it cannot be used to tell an idle model from a settled one; check ragdollIsActive too.

Returns: True or false.

Since: 3.00. See also: ragdollIsActive, ragdollDeactivate

Example
-- The round ends once the loser has stopped moving.
function onOverlayUpdate()
    if roundOver and ragdollIsResting(loser) then
        restingFrames = restingFrames + 1
        if restingFrames == 90 then
            showResults()
        end
    end
    return OVERLAY_NOT_UPDATED
end

2.33. Save

Anything the game should still know next time it starts: high scores, the player’s options, how far they got. One table per game, kept as JSON in the game’s own data directory (see singeGetDataPath), so a packed .game stays read only and two games never tread on each other.

Keys are yours. Values may be numbers, strings, booleans, or tables of those, nested as deep as you like — a whole high score table goes in as one value. A function, or a handle to something the engine owns, does not: neither means anything on the next run, and saving one is an error rather than a surprise later.

What you set is what is saved, and what you get back is yours. Tables are copied on the way in and on the way out, so changing a table you read back changes nothing until you save it again, and changing one you saved does not reach into the save afterwards. Keeping a preview the player then cancels is therefore just a matter of not saving it.

Writing happens once at the end of any frame that changed something, however many keys you set in it, and again when the game shuts down — including anything set inside onShutdown. For a cabinet that may lose power at any moment, saveFlush writes immediately. The file is written beside the old one and renamed over it, so losing power during a write leaves the previous save rather than half of a new one.

Whole numbers come back as whole numbers. JSON has only one kind of number and Lua has two, so a score saved as 100 would otherwise return as 100.0 and print with a decimal point.

2.33.1. saveClear

saveClear()

Forgets everything and writes the empty save out. For a service menu’s "reset high scores".

Parameters:

  • None.

Returns: nothing.

Since: 3.00.

2.33.2. saveDelete

saveDelete(key)

Removes one key. Deleting a key that was never there is not an error.

Parameters:

  • key — the key to remove.

Returns: nothing.

Since: 3.00.

2.33.3. saveFlush

saveFlush()

Writes the save out now rather than at the end of the frame. Use it after something you would hate to lose — a new high score on a cabinet that is switched off at the wall.

Parameters:

  • None.

Returns: nothing.

Since: 3.00. See also: saveSet

2.33.4. saveGet

value = saveGet(key [, default])

What was saved under that key. When nothing was, the default comes back, or nil when there is no default — which is how a first run is told apart from a later one.

Parameters:

  • key — the key to read.

  • default — optional; what to answer when the key is not there.

Returns: the saved value, the default, or nil.

Since: 3.00. See also: saveSet

Example
-- Count the runs, and remember the ten best scores.
local runs = saveGet("runs", 0) + 1
saveSet("runs", runs)

local best = saveGet("highScores", {})
best[#best + 1] = { name = initials, score = score }
table.sort(best, function(a, b) return a.score > b.score end)
while #best > 10 do table.remove(best) end
saveSet("highScores", best)
saveFlush()

2.33.5. saveGetAll

everything = saveGetAll()

A copy of the whole save, for reading: dumping it while you are debugging, or walking keys whose names the game does not know in advance. Changing what comes back changes nothing — saveSetAll is what writes a whole table.

Parameters:

  • None.

Returns: a table; empty when nothing has been saved.

Since: 3.00. See also: saveSetAll, saveGet

Example
-- What is in there?  inspect is bundled for exactly this.
debugPrint(require("inspect")(saveGetAll()))

2.33.6. saveSet

saveSet(key, value)

Keeps a value until the game is uninstalled. The write happens at the end of the frame, so setting twenty keys in a loop writes one file.

Parameters:

  • key — the key to write.

  • value — a number, a string, a boolean, or a table of those.

Returns: nothing.

Since: 3.00. See also: saveGet, saveFlush

2.33.7. saveSetAll

saveSetAll(everything)

Replaces the whole save with this table, in one step. Keys that were there and are not in the table you give are gone.

Moving an old save to a new layout is why it exists. Doing it with saveClear and a loop of saveSet leaves a moment where the save is empty, and a machine switched off in that moment loses everything; this has no such moment, because the file is written once at the end of the frame from the finished table.

Parameters:

  • everything — table; what the save should now contain. The same values saveSet takes.

Returns: nothing.

Since: 3.00. See also: saveGetAll, saveClear

Example
-- Version 1 kept one score in two keys; version 2 keeps a table of them.
if saveGet("version", 1) < 2 then
    local old = saveGetAll()
    saveSetAll({
        version = 2,
        scores  = { { name = old.hiName, score = old.hiScore } },
        runs    = old.runs,
    })
    saveFlush()
end

2.34. Scene

The scene is the 3D layer drawn between the disc video and the overlay; nodes put in the front layer with nodeSetLayer are drawn after the overlay instead. It is off until sceneEnable(true), is sized like the overlay, and clears to sceneSetBackground every frame. The sceneSet* calls set the whole layer’s look: ambient light, sky, fog, exposure and tone curve, bloom, antialiasing and shadow quality; colors are integers from 0 to 255 and distances are world units. sceneProject and sceneUnproject bridge world space and overlay coordinates, and sceneGetStats reports last frame’s work. See 3D Scenes.

2.34.1. sceneEnable

sceneEnable(enabled)

Turns the 3D layer on or off. Nodes, meshes and materials can be built before it is on and survive it being turned off; only drawing stops. Ends the script when turning it on with no usable GPU (see 3D Scenes), so a game with a 2D fallback asks singeCapabilities().SCENE first. The display refreshes on the next frame either way.

Since: 3.00. See also: sceneSetBackground, sceneSetAntialias

Example
-- Fall back to the plain overlay when 3D is unavailable.
has3d = singeCapabilities().SCENE
if has3d then
    sceneEnable(true)
    buildArena()
else
    debugPrint("No 3D here; using the 2D attract mode.")
end

function onPause()
    sceneEnable(false)
end

2.34.2. sceneGetSize

width, height = sceneGetSize()

The layer’s size, which is the overlay’s resolution: the space sceneProject and sceneUnproject work in, and the size the scene is rendered at. Change it with overlaySetResolution. Before the layer has been sized both values are 0.

Returns: Two integers, the width and height in overlay coordinates.

Since: 3.00. See also: overlaySetResolution, sceneUnproject

Example
-- A crosshair at the center of the view, and the thing under it.
function onOverlayUpdate()
    local width, height = sceneGetSize()
    local cx = width / 2
    local cy = height / 2
    local ox, oy, oz = sceneUnproject(cx, cy, 0)
    local fx, fy, fz = sceneUnproject(cx, cy, 50)
    target = physicsRaycast(ox, oy, oz, fx - ox, fy - oy, fz - oz)
    fontPrint(cx - 4, cy - 8, "+")
    return OVERLAY_UPDATED
end

2.34.3. sceneGetStats

total, drawn, calls, textureKB = sceneGetStats()

Last frame’s numbers from the window’s camera: meshes collected for drawing, how many of them were inside the camera’s view, the draw calls they became after instancing, and the texture memory the scene holds in kilobytes. For tuning: a scene with hundreds of drawn but a handful of calls is sharing its meshes well, and a textureKB that will not fit a Raspberry Pi’s memory wants KTX2 textures. Rendered views do not count.

Returns: Four integers.

Since: 3.00. See also: sceneEnable, modelInstance, materialSetTexture

Example
-- A debug readout in the corner while tuning the level.
function onOverlayUpdate()
    if showStats then
        local total, drawn, calls, textureKB = sceneGetStats()
        fontPrint(10, 10, string.format("%d meshes, %d in view, %d calls, %d MB textures", total, drawn, calls, math.floor(textureKB / 1024)))
    end
    return OVERLAY_UPDATED
end

2.34.4. sceneMeasure

sceneMeasure(on)
ms = sceneMeasure(false)

Times the 3D scene. sceneMeasure(true) starts: every frame after it waits for the GPU to finish the scene and adds that time up, so what is measured is the work rather than the display’s pacing. sceneMeasure(false) stops and returns the milliseconds a frame averaged, or nil when no frame was drawn. The wait costs frame rate, so time a few seconds, not a whole game.

Returns: nothing when starting; a number or nil when stopping.

Since: 3.00. See also: singeSaveTier, sceneGetStats

Example
-- Two seconds of the title screen tell whether the full effects fit.
sceneMeasure(true)
-- ... two seconds later:
local ms = sceneMeasure(false)

if ms and (ms > 8) then
	sceneSetBloom(1.0, 0.0)
end

2.34.5. sceneProbeGui

gui, x, y = sceneProbeGui(sx, sy)

Which GUI is on the surface under an overlay point, and where on it: a ray from the camera through the point, using the camera of the last rendered frame, against the triangles of every visible node whose material shows a GUI (materialSetGui), taking the nearest hit’s texture coordinates as the place on the GUI. Returns the GUI handle and the pixel in that GUI’s own coordinates (0, 0 at its top left, guiGetWidth, guiGetHeight at its bottom right), or nil alone when the point is off every such surface, the scene is off, or nothing has rendered yet. The engine asks the same question when the mouse or a light gun points at the scene while a GUI that takes input is on a surface and nothing drawn flat is under the pointer, so clicks on a monitor in the scene need no script; the call is for a game that wants the answer itself, for a laser sight, a hover effect or a test.

Parameters:

  • sx, sy — the point, in overlay coordinates (a mouse or light gun position).

Returns: An integer and two integers, or nil.

Example
-- A light gun's dot glows where it lands on the cockpit's screen.
function onMouseMoved(x, y)
    local g, px, py = sceneProbeGui(x, y)
    if g == screenGui then
        guiSetValue(g, screenPage, "dot", string.format("%d,%d", px, py))
    end
end

2.34.6. sceneProject

x, y, depth, inFront = sceneProject(wx, wy, wz)

Where a world point falls in overlay coordinates, using the camera of the last rendered frame. depth is 0 at the near plane and 1 at the far plane, for sorting labels or fading them with distance. inFront is false when the point is behind the camera, and x and y are then meaningless; before the first frame has rendered there is nothing to project against, and every value comes back 0 with inFront false. Points in front but outside the view come back with coordinates off the overlay’s edges, so check them against sceneGetSize before drawing. The usual use is a name tag or health bar drawn with fontPrint or spriteDraw above a 3D object.

Parameters:

  • wx, wy, wz — the world point, in world units.

Returns: Two numbers, a number, and a boolean.

Example
-- A name and health bar floating above each character.
function onOverlayUpdate()
    for _, enemy in ipairs(enemies) do
        local x, y, depth, visible = sceneProject(nodeGetWorldPosition(enemy.node))
        if visible then
            fontPrint(x - 30, y - 80, enemy.name)
            overlayBox(x - 30, y - 60, x - 30 + enemy.health * 0.6, y - 54)
        end
    end
    return OVERLAY_UPDATED
end

2.34.7. sceneUnproject

x, y, z = sceneUnproject(sx, sy, distance)

The world point distance units along the ray through an overlay pixel, using the camera of the last rendered frame. Two distances give a ray for picking with physicsRaycast; one places an object "where the player clicked". Before the first frame has been drawn it returns the origin.

Parameters:

  • sx, sy — the overlay pixel, in overlay coordinates.

  • distance — how far along the ray, in world units; 0 is the near plane.

Returns: Three numbers, the world point.

Since: 3.00. See also: sceneProject, mouseGetPosition, physicsRaycast

Example
-- Drop a marker on whatever the player clicked, or 8 units out if nothing.
function onMouseDown(button)
    local mx, my = mouseGetPosition(0)
    local ox, oy, oz = sceneUnproject(mx, my, 0)
    local fx, fy, fz = sceneUnproject(mx, my, 100)
    local hit, hx, hy, hz = physicsRaycast(ox, oy, oz, fx - ox, fy - oy, fz - oz)
    if hit then
        nodeSetPosition(marker, hx, hy, hz)
    else
        nodeSetPosition(marker, sceneUnproject(mx, my, 8))
    end
end

2.34.8. sceneSetAmbient

sceneSetAmbient(r, g, b)

Light from everywhere, 0 to 255 per channel, treated as sRGB; the default is a dim gray of 26, 26, 26. It lifts the sides that no light reaches so they are not black, and materialSetOcclusionMap darkens it in crevices. When a sky is set and sceneSetEnvironment is on, the sky’s light replaces this value.

Since: 3.00. See also: lightNew, sceneSetEnvironment, sceneSetSky

Example
-- A moonlit yard:  a faint blue everywhere, one cold directional moon.
sceneSetAmbient(20, 25, 45)
moon = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(moon, -5, 10, 3)
nodeLookAt(moon, 0, 0, 0)
lightSetColor(moon, 170, 190, 255)
lightSetIntensity(moon, 0.4)

2.34.9. sceneSetAntialias

sceneSetAntialias(antialias)

Turns 4x multisampling on or off; it is on by default wherever the GPU offers it for the layer’s formats, and silently absent where it does not. Turning it off buys speed on a Raspberry Pi. The render targets are rebuilt at once, so call it during setup rather than every frame.

Since: 3.00. See also: sceneEnable, sceneSetShadowSize

Example
-- A quality setting from the game's options screen.
function applyQuality(level)
    if level == "low" then
        sceneSetAntialias(false)
        sceneSetShadowSize(512)
        sceneSetShadowCascades(2)
    else
        sceneSetAntialias(true)
        sceneSetShadowSize(2048)
        sceneSetShadowCascades(3)
    end
end

2.34.10. sceneSetBackground

sceneSetBackground(r, g, b)
sceneSetBackground(r, g, b, a)

The color the layer clears to each frame, 0 to 255 per channel. a is 255 when omitted, an opaque backdrop; below 255 lets the video show through, and 0 (the usual choice for a game with a disc) makes the background fully transparent. Until it is called the layer clears to black and transparent. A sky from sceneSetSky is drawn over the background, so the video no longer shows through while one is set.

Parameters:

  • r, g, b — the clear color.

  • a — the clear alpha; 255 when omitted.

Since: 3.00. See also: sceneEnable, sceneSetSky, sceneSetFog

Example
-- The disc shows behind the 3D cockpit; a solid night sky for the menu.
function showCockpit()
    sceneSetBackground(0, 0, 0, 0)
    discPlay()
end

function showMenu()
    discPause()
    sceneSetBackground(10, 12, 30)
end

2.34.11. sceneSetBloom

sceneSetBloom(threshold, strength)

A glow around everything brighter than threshold, taken from the scene’s linear light before exposure and the tone curve (where 1 is white), and added back at strength. The defaults are a threshold of 1 and a strength of 0, no bloom; 0.2 to 0.4 is subtle, 1 is a haze. The glow is blurred over a chain of half-size passes, so it costs little, and only the window’s camera gets it: rendered views skip it. Negative values are clamped to 0.

Parameters:

  • threshold — the linear brightness above which a pixel glows; 1 is white before the tone curve.

  • strength — how much of the glow is added back; 0 for none.

Example
-- Neon and headlights glow; the pavement does not.
sceneSetBloom(1.0, 0.35)
neonLook = materialNew()
materialSetColor(neonLook, 255, 40, 120)
materialSetEmissive(neonLook, 255, 40, 120)
nodeSetMesh(sign, meshBox(2, 0.3, 0.05), neonLook)

2.34.12. sceneSetEnvironment

sceneSetEnvironment(lit)

Whether the sky set by sceneSetSky lights the scene: its diffuse light from every direction in place of sceneSetAmbient, and its reflections on metals and glossy surfaces, sharp on a mirror and blurred as roughness rises. On by default, so a sky lights the scene as soon as it is set; false keeps the sky as a backdrop only and the flat ambient returns. It has no effect without a sky.

Example
-- A painted backdrop that must not tint the chrome.
sceneSetSky(DIR .. "Skies/matteBackdrop.png")
sceneSetEnvironment(false)
sceneSetAmbient(40, 40, 45)

2.34.13. sceneSetExposure

sceneSetExposure(stops)

Brightens or darkens the whole scene in photographic stops, -10 to 10 (values outside are clamped): +1 doubles the light, -1 halves it. The default is 0. It is applied after bloom and before the tone curve, so a bright scene at +2 compresses toward white rather than clipping, and a cave and a beach can share the same lights. Animate it for a slow adjustment when walking from indoors to daylight.

Example
-- Eyes adjusting:  ease the exposure toward the area's target each frame.
targetStops  = 0
currentStops = 0

function onEnterArea(area)
    targetStops = area.indoors and 1.5 or -0.5
end

function onOverlayUpdate()
    currentStops = currentStops + (targetStops - currentStops) * 0.05
    sceneSetExposure(currentStops)
    return OVERLAY_UPDATED
end

2.34.14. sceneSetFog

sceneSetFog(r, g, b, near, far)
sceneSetFog()

Distance fog: clear up to near units from the camera, fully the fog color at far and beyond, on meshes (unlit ones too) and particles alike; additive particles fade out instead of going gray. With no arguments, or a far no greater than near, there is no fog. The sky is not fogged, so pick a color close to its horizon, or to the background when there is no sky. Any other number of arguments ends the script.

Parameters:

  • r, g, b — the fog color, 0 to 255.

  • near — the distance where fog begins, in world units from the camera.

  • far — the distance where nothing but fog remains.

Example
-- Morning haze over the hills that burns off as the level goes on.
sceneSetSky(DIR .. "Skies/dawn.hdr")
sceneSetFog(190, 200, 215, 40, 160)

function onOverlayUpdate()
    if levelTime > 60 then
        sceneSetFog()
    end
    return OVERLAY_UPDATED
end

2.34.15. sceneSetShadowCascades

sceneSetShadowCascades(count)

How many maps a directional light’s shadow is split into along the view, 1 to 4 (values outside are clamped; the default is 3). Each cascade covers a slice of the camera’s view out to sceneSetShadowDistance, the nearest slice the smallest, so shadows near the camera are sharp however large the level. 1 fits one map to the whole scene, which is right for small scenes, and is always used with an orthographic camera. Each cascade is one more shadow pass for every casting directional light; 2 is a fair choice on a Raspberry Pi.

Example
-- A large outdoor level:  sharp shadows near the player, reaching far.
sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 30, 40, 20)
nodeLookAt(sun, 0, 0, 0)
lightSetShadow(sun, true)
sceneSetShadowCascades(4)
sceneSetShadowDistance(120)
sceneSetShadowSize(2048)

2.34.16. sceneSetShadowDistance

sceneSetShadowDistance(distance)

How far from the camera cascaded shadows reach, in world units; the default is 60 and values below 1 are clamped to 1. Beyond it a directional light casts no shadow. Shorter distances make every cascade sharper, since the same maps cover less ground, so set it to about as far as the player can make out a shadow. It only matters with more than one cascade under a perspective camera.

Since: 3.00. See also: sceneSetShadowCascades, sceneSetShadowSize

Example
-- Shadows only need to reach the far wall of the arena.
sceneSetShadowCascades(2)
sceneSetShadowDistance(35)
sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 10, 20, 8)
nodeLookAt(sun, 0, 0, 0)
lightSetShadow(sun, true)

2.34.17. sceneSetShadowSize

sceneSetShadowSize(size)

Texels per side of every shadow map, cascade and cube face, 256 to 4096 (values outside are clamped; the default is 1024). Larger is sharper and slower, in memory as well as time, since every casting light has its own maps at this size. 2048 suits a desktop, 512 a Raspberry Pi. The maps are rebuilt on the next frame.

Example
-- Size the shadow maps to the machine.
if singeGetPlatform() == "raspberrypi" then
    sceneSetShadowSize(512)
else
    sceneSetShadowSize(2048)
end

2.34.18. sceneSetSky

sceneSetSky(file)
sceneSetSky(nil)
sceneSetSky()

Wraps the scene in an equirectangular panorama: a Radiance .hdr (as HDRI sites ship, keeping its range), or a PNG, JPEG or other image SDL_image reads, decoded from sRGB. The name is game relative like spriteLoad. The sky is drawn behind everything in place of the background color (so the video no longer shows through) and lights the scene unless sceneSetEnvironment(false). Its center faces -Z and its top is up. It is resampled into a cube of up to 1024 texels a face, so a 2048 by 1024 image is plenty and larger ones take a moment to prepare on a Raspberry Pi. With no argument, or nil, the sky is removed. Ends the script when the file cannot be read or 3D is unavailable.

Example
-- An overcast sky for the docks level, with fog matched to its horizon.
sceneEnable(true)
sceneSetSky(DIR .. "Skies/overcastHarbor.hdr")
sceneSetSkyIntensity(0.8)
sceneSetFog(190, 200, 215, 25, 90)

function onLevelEnd()
    sceneSetSky()
    sceneSetBackground(0, 0, 0, 0)
end

2.34.19. sceneSetSkyIntensity

sceneSetSkyIntensity(scale)

Brightness of the sky and of the light it casts, 1 as loaded; negative values are clamped to 0. Useful to dim a PNG sky that was too bright, to make an .hdr sky the scene’s main light, or to fade the sky in and out. It multiplies the sky itself, unlike sceneSetExposure, which scales everything.

Example
-- Dusk:  the sky and its light dim over ten seconds.
sceneSetSky(DIR .. "Skies/sunset.hdr")
duskStart = singeGetTicks()

function onOverlayUpdate()
    local t = math.min((singeGetTicks() - duskStart) / 10000, 1)
    sceneSetSkyIntensity(1 - 0.8 * t)
    return OVERLAY_UPDATED
end

2.34.20. sceneSetTonemap

sceneSetTonemap(curve)

The curve that maps the scene’s linear light to the screen, applied after exposure. TONEMAP_NEUTRAL (the default) keeps colors faithful and compresses only the brightest light; TONEMAP_ACES is the filmic curve with more contrast and a warmer roll-off; TONEMAP_NONE clips at white. Video materials, unlit surfaces and the sky pass through the same curve, so a game whose disc must look exactly as filmed wants TONEMAP_NONE with an exposure of 0. Any other value ends the script.

Since: 3.00. See also: sceneSetExposure, sceneSetBloom

Example
-- A filmic look for the cutscene, faithful color for play.
function onCutsceneStart()
    sceneSetTonemap(TONEMAP_ACES)
    sceneSetExposure(0.5)
end

function onCutsceneEnd()
    sceneSetTonemap(TONEMAP_NEUTRAL)
    sceneSetExposure(0)
end

2.35. Script

These functions let a Singe script hand control to another Singe script: the mechanism behind the built-in Menu.singe launcher. Game developers should not reach for these; build your game as a single script and let the menu system handle chaining. They are documented here for completeness and for anyone maintaining the menu itself.

Both calls take a table shaped like a GAMES[] entry in games.dat and queue it for the engine’s script runner. The new configuration starts from the running one, so command line options such as the data directory and tracing carry over, but the disc, video and container never do: each entry brings its own. The current script ends at the end of the frame, onShutdown fires, and the queued script starts with a fresh Lua state (see Engine Callbacks). The new script’s data directory follows the same rule as a command line launch (see singeGetDataPath); when it cannot be created the calling script is aborted.

2.35.1. scriptExecute

scriptExecute(config)

Replaces the running script with the one the table describes. The current script stops at the end of this frame and onShutdown runs; control never comes back to it, and when the new script quits the engine moves on to whatever else is queued or exits. String keys the engine knows are SCRIPT, CONTAINER, VIDEO, STRETCH, NO_MOUSE, RESOLUTION_X, RESOLUTION_Y, SINDEN_GUN, AUDIO_TRACK, AUDIO_DELAY, LEGACY_SPRITE_ARGS, CANVAS_X and CANVAS_Y; other keys are ignored and non-string keys are skipped. A SCRIPT, CONTAINER, or VIDEO that is not a string aborts the script, and so does a non-table argument.

Parameters:

  • config — a table of games.dat fields, at minimum SCRIPT or CONTAINER.

Since: 2.00 See also: scriptPush, singeQuit

Example
-- A launcher that never returns to itself.
function onInputPressed(what)
    if what == SWITCH_START1 then
        scriptExecute({
            SCRIPT = DIR .. "../MyGame/MyGame.singe",
            VIDEO  = DIR .. "../MyGame/MyGame.mp4",
        })
    end
end

2.35.2. scriptPush

scriptPush(config)

Starts the script the table describes and queues the current configuration behind it, so when the new script quits the current script runs again from the top. Nothing is kept in place: the current script’s onShutdown runs now, its Lua state is discarded, and the later run is a fresh start, which is why Menu.singe saves its selection to a file before pushing. The table takes the same keys as scriptExecute.

Parameters:

  • config — a table of games.dat fields, as for scriptExecute.

Since: 2.00 See also: scriptExecute, singeQuit, onShutdown

Example
-- Menu.singe: start the selected game and come back afterward.
function onInputPressed(what)
    if what == SWITCH_START1 or what == SWITCH_BUTTON1 then
        SHUTDOWN_FROM_PUSH = true
        scriptPush(GAME_LIST[GAME_SELECTED])
    end
end

2.36. Singe

Functions in the singe* namespace control the engine itself: the window, screenshots, the pause system, quitting and reloading, the audio delay used for lip sync, and a few paths and flags that come from the command line and games.dat. Nothing here takes a handle. Pause behavior is described in Pausing and the audio delay values in Audio Sync.

2.36.1. allowSocketCall

allowed = allowSocketCall()

Hypseus extension, always false in Singe. Hypseus answers whether the user let it send data to a stats server, which its -noserversend turns off; the sending itself is commented out there. Singe sends nothing anywhere, so nothing is permitted and the answer never changes. It exists so a game that asks does not stop on a missing function.

Returns: a boolean, always false.

Since: 3.00

2.36.2. getUserString

id = getUserString()

Hypseus extension, always an empty string. Despite the name it is not a string the user set: Hypseus answers the machine install ID it sends with network statistics, taken from the Windows MachineGuid or the Linux machine ID. Singe sends nothing anywhere and will not hand a game a fingerprint of the machine it is running on.

Returns: a string, always empty.

Since: 3.00 See also: allowSocketCall

2.36.3. singeDisablePauseKey

singeDisablePauseKey()

Gives the pause key to the script, exactly as singeSetPauseKeyEnabled(false) does. It is a function defined in Framework.singe, kept so older games run unchanged.

Notes: Legacy alias.

New code should call singeSetPauseKeyEnabled with false.

Since: 1.18 (RDG) See also: singeSetPauseKeyEnabled, singeEnablePauseKey

Example
-- Older game code; the modern spelling is singeSetPauseKeyEnabled(false).
singeDisablePauseKey()

function onInputPressed(what)
    if what == SWITCH_PAUSE then
        togglePauseMenu()
    end
end

2.36.4. singeEnablePauseKey

singeEnablePauseKey()

Returns the pause key to the engine, exactly as singeSetPauseKeyEnabled(true) does. It is a function defined in Framework.singe, kept so older games run unchanged.

Notes: Legacy alias.

New code should call singeSetPauseKeyEnabled with true.

Since: 1.18 (RDG) See also: singeSetPauseKeyEnabled, singeDisablePauseKey

Example
-- Older game code; the modern spelling is singeSetPauseKeyEnabled(true).
function pauseMenuClose()
    singeSetPauseFlag(false)
    singeEnablePauseKey()
end

2.36.5. utilFileMove

ok = utilFileMove(from, to)

Moves the file from to to, replacing whatever is there in one step: at every moment to is either the file it was or the whole new one, never missing and never half written, which os.rename does not promise on Windows and writing over a file in place promises nowhere. from is put on the disk first. When the two are on different disks the file is copied beside to under a temporary name, every write checked, and takes the name only once the copy is whole. For putting a download or a freshly written file in the place of one that works. Both are paths on disk, as io.open takes them.

Parameters:

  • from — string, the file to move.

  • to — string, where it goes.

Returns: true, or false when it could not be done: to is then as it was and from is still there.

Since: 3.00. See also: utilFilePart, utilSha256File

Example
-- Write the new settings beside the old ones, then swap them in.
local path = singeGetDataPath() .. "settings.json"
local part = utilFilePart(path)
local file = io.open(part, "wb")
file:write(text)
file:close()
if not utilFileMove(part, path) then
    debugPrint("The settings could not be kept.")
end

2.36.6. utilFilePart

name = utilFilePart(path)

The name to write a file under before utilFileMove puts it at path: path followed by a number that belongs to this running Singe and .part. Two Singes writing the same file at once, the same game started twice, say, then each write a file of their own instead of into one between them, and the last to finish is the one kept. Asking also removes what a Singe that stopped part way left behind for the same path, so nothing piles up.

Parameters:

  • path — string, where the finished file will go.

Returns: The name to write under, a string. It is the same every time this Singe asks about the same path.

Since: 3.00. See also: utilFileMove

Example
-- Keep the best lap's ghost, without a half-written file ever taking its place.
local path = singeGetDataPath() .. "ghost.dat"
local part = utilFilePart(path)
local file = io.open(part, "wb")
if file and file:write(ghostData) and file:close() then
    utilFileMove(part, path)
end

2.36.7. utilSha256

digest = utilSha256(data)

SHA-256 of a string, as 64 lowercase hex characters. Binary-safe, so it works on the bytes of a file as readily as on text.

For deciding whether the bytes you have are the bytes you were promised: a downloaded game against the digest its catalogue entry carries, or a server’s public key against a pin. The bundled md5 module is still there for a checksum, but a digest used to decide whether to trust something has to be one that is still worth trusting.

Parameters:

  • data — a string of bytes. Empty aborts the script.

Returns: string, 64 lowercase hex characters.

Since: 3.00.

Example
-- Refuse a download that did not arrive intact.
local file = io.open("game.part", "rb")
local bytes = file:read("*a")
file:close()
if utilSha256(bytes) ~= expected then
    os.remove("game.part")
end

2.36.8. utilSha256File

digest = utilSha256File(path)

SHA-256 of a file’s contents, as utilSha256 gives it for a string, read a block at a time so the file is never held in memory whole: a game can be several gigabytes. path is a path on disk, as io.open takes it.

Parameters:

  • path — string, the file to read.

Returns: string, 64 lowercase hex characters, or nil when the file cannot be read.

Since: 3.00. See also: utilSha256, utilFileMove

Example
-- Refuse a download that did not arrive intact, however large it is.
if utilSha256File("game.part") ~= expected then
    os.remove("game.part")
end

2.36.9. singeCapabilities

capabilities = singeCapabilities()

What this machine can run. The table has one entry per capability name a games.dat REQUIRES list can use (SCENE, GUI, SHADOWS, POST, SKIN, MORPH), each true or false, and tier: the machine’s measured performance class from 0 (no 3D) to 3 (a desktop GPU), or nil before the menu has measured it. A game asks so it can do without something rather than be refused for it.

Returns: a table.

Since: 3.00. See also: singeHasGpu, singeSaveTier, sceneMeasure

Example
-- Shadows where the machine has them, a plain sun where it does not.
local machine = singeCapabilities()

lightSetShadow(sun, machine.SHADOWS)
if (machine.tier or 0) < 2 then
	sceneSetBloom(1.0, 0.0)
end

2.36.10. singeGetAudioCalibration

milliseconds = singeGetAudioCalibration()

Returns the per-machine audio delay in effect, in milliseconds: the value the menu’s calibration screen saved to machine.cfg in the data root, or one set since by singeSetAudioCalibration. Zero when the machine has never been calibrated. It applies to every game on the machine, on top of the per-game delay from singeGetAudioDelay.

Returns: integer milliseconds.

Example
-- Menu.singe: start the calibration screen from the saved value.
function calibrationBegin()
    CALIBRATING  = true
    CAL_ORIGINAL = singeGetAudioCalibration()
    CAL_VALUE    = CAL_ORIGINAL
    CAL_LATENCY  = singeGetAudioLatency()
    CAL_BEAT     = singeGetTicks() - CAL_PERIOD
end

2.36.11. singeGetAudioDelay

milliseconds = singeGetAudioDelay()

Returns the per-game audio delay in effect, in milliseconds, whether it came from --audiodelay, the AUDIO_DELAY key of the game’s games.dat entry, or singeSetAudioDelay. Zero when none has been set. It is added to the machine calibration and the measured device latency when the engine decides when to show each video frame.

Returns: integer milliseconds.

Example
-- Service menu: show the current sync offset next to its slider.
function drawSyncSetting(y)
    local delay = singeGetAudioDelay()
    fontPrint(40, y, string.format("A/V offset: %+d ms", delay))
end

2.36.12. singeGetAudioLatency

milliseconds = singeGetAudioLatency()

Returns the audio device queue the engine measured when it opened the mixer, in milliseconds: the time between handing samples to the mixer and their reaching the device, before any calibration or per-game delay. The engine already compensates for it; a calibration screen needs it to schedule its click and flash, and it is worth printing in a diagnostic view.

Returns: integer milliseconds.

Example
-- Menu.singe: the flash follows the click by the device queue plus the candidate.
function calibrationUpdate()
    local now = singeGetTicks()
    local gap = CAL_LATENCY + CAL_VALUE
    if now - CAL_BEAT >= CAL_PERIOD then
        CAL_BEAT     = now
        CAL_CLICK_AT = now + math.max(0, -gap)
        CAL_FLASH_AT = now + math.max(0, gap)
    end
end

2.36.13. singeGetDataPath

path = singeGetDataPath()

Returns the directory Singe writes to for this game, with a trailing path separator so a file name can be appended directly. It is a subdirectory of the --datadir base named for the game (for a packed game, the database’s name and then the script’s directory inside it); without --datadir the base is data in the game directory. Screenshots, video indexes and trace.txt go there, and so should save games, high scores and settings; Singe 2.x wrote them beside the game, which may be read only.

Returns: string path ending in a separator.

Since: 2.00 See also: singeGetScriptPath, singeScreenshot

Example
-- Menu.singe keeps its last selection between runs.
CONFIG_FILE = singeGetDataPath() .. "menu.dat"

function saveConfig()
    local cfg = io.open(CONFIG_FILE, "w")
    if cfg then
        cfg:write("GAME_SELECTED = " .. GAME_SELECTED .. "\n")
        cfg:close()
    else
        debugPrint("Unable to write " .. CONFIG_FILE)
    end
end

2.36.14. singeGetGameId

id = singeGetGameId()

The GAME_ID from this game’s games.dat entry, or nil when it has none. It is the id the online service knows the game by, and the key a leaderboard is kept under.

The format is a UUID, in the canonical 36-character form — eight hex digits, three groups of four, then twelve, separated by hyphens:

GAME_ID = "6f1e7b62-0a4e-4d9c-9b2f-1c7a5e3d8a10"

Nothing else is accepted. The id is a path segment in the service’s URLs, so one containing a slash or a question mark would publish and then never be reachable, and two ids differing only in case would be two games to the database and one game to anybody reading them. Comparison is case-insensitive and storage is lowercase, so an id typed in capitals is the same game.

Any UUID will do — generate one however you like, or let publish.lua print one. A game without one can be played but not ranked: there would be nothing stable to key a board on, and an id invented at run time would make a different board every time the files moved.

One .game, one id. A .game whose games.dat has several entries — a collection, or one game in two languages — is one download, and every entry in it carries the same GAME_ID. The online service lists each entry as a game of its own, and will not take a .game whose entries disagree about their id or leave it out of one. Their scores still keep apart: see Online high scores.

Returns: string, or nil.

Since: 3.00. See also: Online high scores, games.dat

Example
-- Only offer the leaderboard when this game has an identity to rank under.
if singeGetGameId() then
    showLeaderboardButton()
end

2.36.15. singeGetHeight

height = singeGetHeight()

Returns the height of the Singe window in screen pixels, not overlay units, as the window is at the moment of the call. Use overlayGetHeight for drawing; this is for a settings screen that reports the display, or for deciding how much detail a scene can afford.

Returns: integer pixels.

Since: 1.x See also: singeGetWidth, overlayGetHeight

Example
-- Report the display in the service menu.
function drawDisplayInfo(y)
    fontPrint(40, y, string.format("Window %dx%d, overlay %dx%d", singeGetWidth(), singeGetHeight(), overlayGetWidth(), overlayGetHeight()))
end

2.36.16. singeGetPauseFlag

paused = singeGetPauseFlag()

Returns the engine’s pause flag: true while the game is paused by the pause key or by singeSetPauseFlag. This is separate from whether the disc is on a paused frame (discGetState); read it to know whether a pause was deliberately requested. While the pause key holds the game frozen no callback runs, so from inside a callback the flag can only be seen as true after the script’s own singeSetPauseFlag(true).

Returns: boolean.

Since: 1.x (RDG) See also: singeSetPauseFlag, singeSetPauseKeyEnabled

Example
-- Timers stand still while the game's own pause is up.
function onOverlayUpdate()
    if not singeGetPauseFlag() then
        elapsed = elapsed + 1
        updateEnemies()
    end
    drawFrame()
    return OVERLAY_UPDATED
end

2.36.17. singeGetScriptPath

path = singeGetScriptPath()

Returns the path of the running script file as the engine resolved it. Framework.singe derives the global DIR, the script’s directory with its trailing separator, from this value, and DIR is what most games use to build asset paths.

Returns: string path.

Since: 1.15 (RDG) See also: singeGetDataPath

Example
-- Framework.singe derives DIR this way; games then load relative to it.
DIR = singeGetScriptPath():match("(.*[/\\])") or "./"
titleSprite = spriteLoad(DIR .. "images/title.png")

2.36.18. singeGetSystemInfo

info = singeGetSystemInfo()

Everything the trace header knows about this machine and this run, in one table. It is meant for a service screen and for bug reports: the answer to "what was it running on" without asking the player to find a log.

Returns: a table with these fields, all strings except the four sizes:

  • version — the engine version, as SINGE_VERSION_STRING.

  • os — the operating system name and release, and the architecture.

  • cpu — the processor, its core count and the memory in megabytes.

  • renderer — the name of SDL’s 2D renderer in use.

  • gpu — the SDL_GPU driver behind the 3D scene, or a note that 3D is unavailable.

  • decoder — which hardware video decoders the build will try, in words.

  • audio — the audio formats compiled in, comma separated.

  • soundFont — the SoundFont MIDI playback is using, or why there is none.

  • midi — the MIDI ports open, or a note that none have been asked for.

  • dataPath — this game’s data directory.

  • dataRoot — the data directory the engine was given, one above dataPath, which every game on the machine writes under.

  • platform — the platform part of the release name, such as Linux-x86_64: which release this executable is, and the one to ask the service for.

  • executable — the absolute path of the running executable.

  • windowWidth, windowHeight — integers, the window in pixels.

  • canvasWidth, canvasHeight — integers, the canvas in pixels.

Since: 3.00. See also: singeGetDataPath, The Service Tools

Example
-- A one-key diagnostic screen.
local info = singeGetSystemInfo()
fontPrint(10, 10, "Singe " .. info.version .. " on " .. info.os)
fontPrint(10, 30, info.cpu)
fontPrint(10, 50, info.renderer .. " / " .. info.gpu)

2.36.19. singeGetTicks

milliseconds = singeGetTicks()

Returns the wall clock in milliseconds since the engine started. It is the clock for timers, debounces and animation, and it keeps running while the game is frozen by the pause key, so a timer that must not count paused time should read singeGetPauseFlag or measure from the moment of thawing. Lua’s os.clock() normally measures processor time, which stalls while the engine idles; Singe replaces it with wall seconds since the engine started, so existing games that used it as a wall clock keep working.

Returns: integer milliseconds.

Since: 3.00 See also: singeGetPauseFlag, debugPrint

Example
-- Blink the "insert coin" prompt twice a second.
function drawAttractPrompt()
    local phase = (singeGetTicks() // 250) % 2
    if phase == 0 then
        fontPrint(120, 200, "INSERT COIN")
    end
end

2.36.20. singeGetWidth

width = singeGetWidth()

Returns the width of the Singe window in screen pixels, the counterpart of singeGetHeight. Overlay drawing uses overlayGetWidth instead.

Returns: integer pixels.

Since: 1.x See also: singeGetHeight, overlayGetWidth

Example
-- Pick a texture budget from the window size.
local pixels = singeGetWidth() * singeGetHeight()
if pixels > 1920 * 1080 then
    textureSet = "high"
else
    textureSet = "low"
end

2.36.21. singeHasGpu

present = singeHasGpu()

Whether the GPU device came up. Everything drawn through it is unavailable without one: the 3D scene, 3D particles, and every GUI document. 2D particles are drawn with the overlay and need no device. Ask this before asking for any of them, because guiNew and the scene calls end the script rather than answering false — there is no way to try and recover.

A machine can lack one because it has no Vulkan, Direct3D 12 or Metal driver at all, or because --nogpu was given. The bundled menu calls this at startup and picks a renderer from the answer (see The two renderers).

Returns: boolean, true when a GPU device is present.

Example
-- A game with a 3D title screen and a flat one to fall back on.
if singeHasGpu() then
    buildSceneTitle()
else
    buildSpriteTitle()
end

2.36.22. singeIsRecording

recording = singeIsRecording()

Whether a recording is running, or has been asked for and starts with the next frame drawn. See singeRecordStart.

Returns: boolean.

Since: 3.00 See also: singeRecordStart, singeRecordStop

Example
-- A red dot in the corner of the game's own pause screen while it is being recorded.
if singeIsRecording() then
    overlayCircle(overlayGetWidth() - 12, 12, 5)
end

2.36.23. singePack

result = singePack(directory, database)

Packs the game in directory into the single-file database database, exactly as singe --pack does from the command line, and returns true when it succeeded. The directory has to be a game’s own folder: one that contains no Singe/ support folder, no launcher, and nothing else the packer refuses, and the reasons for a refusal are printed to the console as they are for the command line. This is what lets an authoring tool release a game without leaving the engine.

Parameters:

  • directory — the game’s folder, as the packer takes it.

  • database — the .game file to write, replaced if it exists.

Returns: true on success, false otherwise.

Since: 3.00 See also: Single-File Games

Example
-- Release the game beside its folder and report.
if singePack(singeGetDataPath() .. "CoinRun", singeGetDataPath() .. "CoinRun.game") then
    debugPrint("packed")
end

2.36.24. singeQuit

singeQuit()

Ends the running script at the end of this frame: the game loop stops, onShutdown runs, and the engine moves on to the next queued script or exits when there is none. A game launched from the menu with scriptPush therefore returns to the menu, which restarts from the top. In the threaded model returning from singeMain calls this for you. The switch mapped to INPUT_QUIT in controls.cfg and closing the window end the script the same way. Do not call it from onShutdown, which is already the exit path.

Since: 1.x (RDG) See also: onShutdown, singeReload, scriptPush

Example
function onInputPressed(what)
    if what == SWITCH_QUIT then
        singeQuit()
    elseif what == SWITCH_START1 and gameOver then
        startGame()
    end
end

2.36.25. singeRelaunch

result = singeRelaunch(path)

Ends the engine as singeQuit does and, once everything has been torn down, starts the executable at path in this one’s place with the same arguments. This is how the menu’s Engine Update tool moves a cabinet onto a newer Singe it has put beside the running one: the new file is made executable and started, and on Windows, which will not replace a running image, it is started beside this one under its own name. The file must already exist; the call answers false without doing anything when it does not. Nothing is unpacked or copied here: the new Singe unpacks its own support files on its first run.

When path is not the running executable, the running one is set aside beside itself as old-<name> just before the new one starts, a name no launcher looks for. If the new one cannot be started, the old one is put back under its own name and the file that would not start is renamed failed-<name>, so the launcher still finds a Singe that works.

Parameters:

  • path — the executable to start.

Returns: true when the relaunch has been arranged, false when the file is not there.

Since: 3.00 See also: singeQuit, singeGetSystemInfo

Example
-- A newer Singe has been downloaded and checked;  hand over to it.
local folder = singeGetSystemInfo().executable:match("^(.*[/\\])")
singeRelaunch(folder .. "Singe-v3.01-Linux-x86_64")

2.36.26. singeRecordStart

singeRecordStart([name])

Starts recording the game, picture and sound together, to an MP4 in the game’s data directory (see singeGetDataPath), from the next frame drawn. Without a name, files are named singe000.mp4 upward, as screenshots are; with one the recording goes to that file, .mp4 added when the name has no extension, replacing any file of that name, and a name with a directory in it aborts the script. A call while a recording is running is ignored. The switch mapped to INPUT_RECORD in controls.cfg, F10 by default, starts and stops the same recordings.

The picture is the whole window as it is shown, letterbox included, at the window’s size, exactly what a screenshot takes; the sound is the finished mix, music, effects and video soundtracks together. Both are encoded on a thread of their own, so the game pays for copying each frame back from the GPU and little else. The picture is H.264 where the machine has a hardware encoder Singe can use — VA-API on Linux, VideoToolbox on macOS, Media Foundation on Windows, V4L2 on the ARM boards that have one — and MPEG-4 from FFmpeg’s own encoder everywhere else; the sound is AAC. The trace names the encoder when the recording starts, and counts any frames dropped when it stops.

In play the recording runs at 60 frames a second on the real clock. A frame that comes while the encoder is still busy is dropped from the recording rather than making the game wait, and the sound is moved later by the audio device’s queue, so the two match as they did on the screen. Under --deterministic the recording runs at one frame per clock step instead, and the engine waits for the encoder rather than dropping anything; started by --record, a deterministic run also mixes its sound into memory a step at a time, so the recording is exact frame by frame and sample by sample.

Parameters:

  • name — optional string; a file name, not a path.

Returns: nothing.

Example
-- The attract mode records its own trailer:  one loop of it, then stop.
function attractBegin()
    singeRecordStart("trailer")
end

function attractEnd()
    singeRecordStop()
end

2.36.27. singeRecordStop

singeRecordStop()

Finishes the recording at the next frame drawn: what is still waiting is encoded and the file is closed, so it plays from start to end. Ignored when nothing is recording. A recording still running when the game ends is finished the same way.

Returns: nothing.

Since: 3.00 See also: singeRecordStart, singeIsRecording

Example
-- Record one round of the game:  from the first coin to game over.
function onGameOver()
    singeRecordStop()
end

2.36.28. singeReload

singeReload()

Runs the game again from its script at the end of this frame, as F5 and a changed file do under --reload; this call works without the option. Every sound stops, the Lua state is discarded without calling onShutdown, everything the script loaded is freed, the scene, physics (its debug drawing included), particles and navigation are reset, the overlay returns to its default resolution, and the sound effect volume, mouse mode, mouse capture, keyboard mode, pause key, sound listener and pause flag return to their defaults. Keys and buttons held through the reload are ignored until released, as at a fresh start, and the disc is parked on its first frame, paused, with the default audio track selected, as at startup. The engine itself (the window, the controllers, the mice) stays as it is. It suits a debug menu’s restart item or a level editor reloading what it just saved.

Since: 3.00. See also: singeQuit

Example
-- Editor: save the level, then restart the game on it.
function onKeyPressed(keysym, scancode)
    if scancode == SCANCODE.F9.value then
        saveLevel(singeGetDataPath() .. "level.lua")
        singeReload()
    end
end

2.36.29. singeSaveGeometry

singeSaveGeometry()

Keeps the picture’s current scale, shift and rotation for this machine. They go into machine.cfg in the data root, beside the audio delay, and the engine applies them to every game it starts afterwards, from the menu or from the command line, and across singeReload. An option actually typed on the command line wins: --scalefactor overrides the saved scale, --shiftx or --shifty the saved shift, --rotate the saved rotation. The file is written whole, so the audio delay is kept as it stands.

This is a cabinet setting, not a game setting: it is how a monitor is squared up once rather than once per game. The Display tool in the bundled menu is exactly this call behind button 1.

Returns: nothing.

Example
-- The operator is happy with the picture:  keep it for the cabinet.
function onInputPressed(input)
    if input == SWITCH_BUTTON1 then
        singeSaveGeometry()
    end
end

2.36.30. singeSaveTier

singeSaveTier(tier)

Keeps this machine’s performance class, 0 to 3, in machine.cfg beside the audio delay and the geometry, where singeCapabilities reports it and the menu compares it with each game’s TIER. The bundled menu measures the tier itself, from how long its 3D backdrop takes to draw (sceneMeasure), and saves it only when it changes; nothing asks the player.

Returns: nothing.

Since: 3.00. See also: singeCapabilities, singeSaveGeometry

Example
-- A machine with no 3D at all is tier 0.
if not singeHasGpu() then
	singeSaveTier(0)
end

2.36.31. singeScreenshot

singeScreenshot()
singeScreenshot(name)

Requests a screenshot of the whole window, letterbox included, taken after the next frame is drawn and saved as a PNG in the game’s data directory (see singeGetDataPath). Without a name, files are named singe000.png upward; each script run scans from zero for the first free name and later shots continue past the last one saved. With a name the shot goes to that file, .png added when the name has no extension, replacing any file of that name; a name with a directory in it aborts the script. Naming the shot is for scripts that produce pictures on purpose, such as the ones that illustrate a book’s tutorials, so a rerun replaces the picture rather than adding one. The call forces a redraw so the shot is taken even while the display is idle. The switch mapped to INPUT_SCREENSHOT in controls.cfg does the same thing.

Since: 1.x See also: singeGetDataPath

Example
-- A test script captures a few frames as it flies through the scene.
function onOverlayUpdate()
    frames = frames + 1
    if frames == 40 or frames == 85 or frames == 130 then
        singeScreenshot()
    end
    if frames == 180 then
        singeQuit()
    end
end

2.36.32. singeSetAudioCalibration

singeSetAudioCalibration(milliseconds)

Sets the per-machine audio delay, applies it at once, and writes it to machine.cfg in the data root so every game on the machine picks it up. The menu’s calibration screen calls it; a game with its own service menu may too. The value is positive when the audio is heard later than the device reports; the engine delays video presentation by that much. Values outside -1000 to 1000 abort the script. If machine.cfg cannot be written the value still applies for this run and a message goes to the console.

Parameters:

  • milliseconds — integer, -1000 to 1000, positive when the audio is late.

Example
-- Menu.singe: keep or discard the calibration the player dialed in.
function calibrationEnd(save)
    if save then
        singeSetAudioCalibration(CAL_VALUE)
    end
    CALIBRATING = false
end

2.36.33. singeSetAudioDelay

singeSetAudioDelay(milliseconds)

Sets the per-game audio delay for this run: how much later (positive) or earlier (negative) the audio is heard than the engine can measure, so that video presentation shifts to match. It applies to the disc and to every video the script plays, on top of the machine calibration. Nothing is saved; a game offering the adjustment in a service menu stores the value with its other settings and calls this again at startup. Values outside -1000 to 1000 abort the script.

Parameters:

  • milliseconds — integer, -1000 to 1000, positive when the audio is late.

Example
-- Service menu: nudge the offset and remember it.
function onInputPressed(what)
    if what == SWITCH_LEFT then
        settings.audioDelay = math.max(-1000, settings.audioDelay - 10)
    elseif what == SWITCH_RIGHT then
        settings.audioDelay = math.min(1000, settings.audioDelay + 10)
    end
    singeSetAudioDelay(settings.audioDelay)
    saveSettings()
end

2.36.34. singeSetGameName

singeSetGameName(title)

Sets the title of the Singe window. Call it once at startup with the game’s display name; nothing else uses the value. The argument must be a string or a number.

Parameters:

  • title — the window title.

Since: 1.15 (RDG) See also: singeVersion

Example
singeSetGameName("Asteroid Patrol")
keyboardSetMode(MODE_NORMAL)
hudFont = fontLoad(DIR .. "fonts/FreeSansBold.ttf", 18)

2.36.35. singeSetPauseFlag

singeSetPauseFlag(paused)

Sets the engine’s pause flag from the script. true pauses the disc if it is playing, every loaded video, and every sound effect channel, remembering which were running; false resumes exactly those. Unlike the pause key, this does not freeze the script: callbacks keep firing so the script can draw its pause menu and decide when to clear the flag. Games that manage their own pause should also take the pause key with singeSetPauseKeyEnabled(false), because the engine’s key toggles the same flag and would otherwise fight the script. A non-boolean argument aborts the script.

Parameters:

  • paused — boolean.

Since: 1.x (RDG) See also: singeGetPauseFlag, singeSetPauseKeyEnabled

Example
singeSetPauseKeyEnabled(false)

function onInputPressed(what)
    if what == SWITCH_PAUSE then
        menuOpen = not menuOpen
        singeSetPauseFlag(menuOpen)
    elseif menuOpen and what == SWITCH_QUIT then
        singeQuit()
    end
end

2.36.36. singeSetPauseKeyEnabled

singeSetPauseKeyEnabled(enabled)

Chooses who owns the pause key mapped to INPUT_PAUSE in controls.cfg. While enabled (the default, restored on every reload) the engine owns it: pressing the key freezes the game completely (see Pausing), and in MODE_NORMAL the script never receives SWITCH_PAUSE. While disabled the engine ignores the key and SWITCH_PAUSE reaches onInputPressed and onInputReleased like any other switch, so the game can run its own pause with singeSetPauseFlag. A non-boolean argument aborts the script.

Parameters:

  • enabled — boolean.

Example
-- The engine may pause during play, but not while the player enters initials.
function beginInitials()
    singeSetPauseKeyEnabled(false)
    keyboardSetMode(MODE_FULL)
end

function endInitials()
    keyboardSetMode(MODE_NORMAL)
    singeSetPauseKeyEnabled(true)
end

2.36.37. singeSetQuitKeyEnabled

singeSetQuitKeyEnabled(enabled)

Hypseus extension. Chooses whether the engine quits on the switch mapped to INPUT_QUIT in controls.cfg, from the keyboard or a controller. While enabled (the default, restored on every reload) pressing it ends the game. While disabled the engine ignores it, so a game can confirm or save first; the script receives SWITCH_QUIT through onInputPressed and onInputReleased either way, and singeQuit still ends the game. The window’s close button always quits. Framework.singe defines keyboardCatchQuit(catch), Hypseus Singe’s name for the same setting with the opposite sense. A non-boolean argument aborts the script.

Parameters:

  • enabled — boolean.

Since: 3.00, as a Hypseus Singe extension. See also: keyboardCatchQuit, singeSetPauseKeyEnabled, singeQuit

Example
-- Ask before leaving a game in progress.
singeSetQuitKeyEnabled(false)

function onInputPressed(what)
    if what == SWITCH_QUIT then
        if confirmQuit() then
            singeQuit()
        end
    end
end

2.36.38. singeVersion

version = singeVersion()

Returns the engine version as a number, major plus minor as a fraction, so 3.00 comes back as 3. Compare it with < and >= to refuse an engine that is too old or to branch around features; SINGE_VERSION_MAJOR, SINGE_VERSION_MINOR and SINGE_VERSION_STRING are also set as globals for scripts that want the parts or the text.

Returns: number.

Since: 1.x (RDG) See also: singeSetGameName

Example
if singeVersion() < 3 then
    error("This game needs Singe 3.00 or newer, found " .. SINGE_VERSION_STRING)
end

2.36.39. singeWantsCrosshairs

wanted = singeWantsCrosshairs()

Returns true unless Singe was started with --nocrosshair. Draw the software targeting reticle only when it returns true; players with light guns that put their own reticle on screen turn the software one off with that option. The value does not change during a run, so read it once.

Returns: boolean.

Since: 2.00 See also: mouseGetPosition, onMouseMoved

Example
drawCrosshair = singeWantsCrosshairs()

function onOverlayUpdate()
    overlayClear()
    drawTargets()
    if drawCrosshair then
        spriteDraw(reticle, cursorX, cursorY, true)
    end
    return OVERLAY_UPDATED
end

2.37. Soft

Cloth, pressure bodies and ropes: meshes whose vertices are simulated as particles (see Physics, Soft bodies). A soft body is addressed by its node, and a node without one terminates the script in every call after softNew. Positions are world units, mass kilograms, and the stiffness values run 0 to 1. The engine rewrites the node’s mesh from the particles after every step, and the simulation ends by itself when the node is deleted or given a different mesh. Up to 16 soft bodies at once, with up to 32 pins each.

2.37.1. softNew

softNew(node, SOFT_CLOTH)
softNew(node, SOFT_BODY)
softNew(node, SOFT_ROPE, x, y, z, segments, radius)

For SOFT_CLOTH and SOFT_BODY the node’s mesh, of three vertices or more, becomes the particles: vertices at the same position (within 0.0001 units) are welded into one, placed where the node’s transform puts them in the world, and the triangles give the stretch, shear and bend constraints. Cloth collides on both faces and is what an open sheet wants; a body is a closed mesh that softSetPressure can inflate. For SOFT_ROPE the node needs no mesh: segments + 1 particles run in a line from the node’s world position to the world point, the node is given a new six-sided tube mesh of that radius round them (keeping whatever material it had), and the particles collide as spheres of that radius, where cloth and body particles are spheres of radius 0.03. Every kind starts with stretch 0.9, bend 0.2, mass 1 kilogram, damping 0.1 and pressure 0. A soft body already on the node is removed before the new one is made, so a call that fails leaves the node with none; a rope’s tube mesh goes with it, which is why a rope’s node cannot become cloth or a body (the call fails for want of a mesh). Ends the script when physics is unavailable, the kind is unknown, the argument count does not fit the kind, the mesh is missing, a rope has no segments or no radius, or 16 soft bodies already exist.

Parameters:

  • node — the node carrying the mesh (cloth, body), or the rope’s starting point.

  • x, y, z — the rope’s far end, in world units.

  • segments — how many links the rope has, 1 or more; a dozen is plenty.

  • radius — the rope’s radius, in world units; also the size its particles collide with.

Notes: A mesh shared by several nodes is rewritten for all of them, so give a soft body a mesh of its own. Skinned meshes cannot be soft.

Example
-- A flag hanging from the pole:  an upright grid, pinned down its left edge.
local flag = nodeNew()
nodeSetMesh(flag, meshPlane(1.6, 1.0, 16, 10), cloth)
nodeSetPosition(flag, -4.16, 2.4, 0)
nodeSetRotation(flag, 90, 0, 0)
softNew(flag, SOFT_CLOTH)
softSetStiffness(flag, 0.95, 0.1)
softSetMass(flag, 0.5)
for _, y in ipairs({ 1.9, 2.15, 2.4, 2.65, 2.9 }) do
    softPin(flag, -4.96, y, 0)                -- Along the pole
end

2.37.2. softDelete

softDelete(node)

Ends the simulation and frees its body. The node keeps its mesh in the shape it was last written, so a dropped sheet stays draped over the crate and a rope keeps its tube; the original mesh shape is not restored. A node without a soft body terminates the script.

Since: 3.00. See also: softNew, nodeDelete

Example
-- Once the sheet has settled over the statue, freeze it and stop paying for it.
function onOverlayUpdate()
    if covering then
        settleFrames = settleFrames + 1
        if settleFrames > 240 then
            softDelete(sheet)                 -- The drape stays as it is
            covering = false
        end
    end
    return OVERLAY_NOT_UPDATED
end

2.37.3. softPin

softPin(node, x, y, z)
softPin(node, x, y, z, otherNode)

Finds the particle nearest the world point, wherever the particles are right now, and fixes it. On its own the particle is held where it is; with otherNode it is moved to that node’s world position before every step, so a rope hangs from a crane that swings and a cape follows the shoulders. The point need not lie on the mesh, since the nearest particle wins, and pinning the same particle again only changes what it follows. Past 32 pins the call does nothing.

Parameters:

  • node — the soft body’s node.

  • x, y, z — a world point; the particle nearest it is pinned.

  • otherNode — a node for the particle to follow from now on.

Since: 3.00. See also: softUnpin, softNew, nodeGetWorldPosition

Example
-- A rope from the crane's hook out and down, swinging with the crane.
local crane = nodeNew()
nodeSetPosition(crane, 4, 4, -1)
local rope = nodeNew()
nodeSetPosition(rope, 4, 4, -1)
softNew(rope, SOFT_ROPE, 6.5, 4, -1, 16, 0.04)
nodeSetMaterial(rope, hemp)
softSetMass(rope, 1.5)
softPin(rope, 4, 4, -1, crane)               -- The top end rides the hook

2.37.4. softUnpin

softUnpin(node, x, y, z)

Frees the pinned particle nearest the world point. Nothing happens when that particle is not pinned. The body is remade around the current shape, which also stops every particle dead, so a flag let go of starts falling from rest.

Since: 3.00. See also: softPin

Example
-- The banner's corner tears loose when the wind gust hits.
function onOverlayUpdate()
    gustFrames = gustFrames + 1
    if gustFrames == 200 then
        softUnpin(banner, 3.0, 4.5, 0)
        soundPlay(ripSound)
    end
    return OVERLAY_NOT_UPDATED
end

2.37.5. softSetStiffness

softSetStiffness(node, stretch, bend)

How much the material resists being stretched (and, for cloth, sheared) and being folded, 0 to 1; values outside are clamped. 1 is rigid, 0 the loosest the solver allows. Defaults 0.9 and 0.2. The body is remade around the current shape: the rest lengths become the lengths of this moment, and every particle stops, so set the material up before the cloth starts to move. A rope has only stretch.

Parameters:

  • node — the soft body’s node.

  • stretch — resistance to stretching, 0 to 1; default 0.9.

  • bend — resistance to folding, 0 to 1; default 0.2.

Since: 3.00. See also: softSetMass, softSetDamping

Example
-- Silk, canvas and a rubber sheet from the same grid.
local silk = clothNode(silkMaterial)
softNew(silk, SOFT_CLOTH)
softSetStiffness(silk, 0.7, 0.02)
local canvas = clothNode(canvasMaterial)
softNew(canvas, SOFT_CLOTH)
softSetStiffness(canvas, 1.0, 0.4)
local rubber = clothNode(rubberMaterial)
softNew(rubber, SOFT_CLOTH)
softSetStiffness(rubber, 0.3, 0.1)

2.37.6. softSetPressure

softSetPressure(node, pressure)

Inflates a SOFT_BODY: 0 (default) is a deflated bag and a few units a firm balloon; a negative value becomes 0. It changes the live body without remaking it and wakes it, so a balloon can be pumped up or let down while it bounces. Cloth and rope have no volume to inflate.

Since: 3.00. See also: softNew, softSetStiffness, meshSphere

Example
softNew(balloon, SOFT_BODY)                  -- A meshSphere of 0.5
softSetMass(balloon, 0.6)
softSetPressure(balloon, 8)                  -- A firm balloon

function onOverlayUpdate()
    if punctured then
        pressure = math.max(pressure - 0.1, 0)
        softSetPressure(balloon, pressure)   -- Hissing down over a couple of seconds
    end
    return OVERLAY_NOT_UPDATED
end

2.37.7. softSetMass

softSetMass(node, kilograms)

The whole body’s mass, shared evenly between its particles; default 1, kept at 0.001 or more. Pinned particles weigh nothing regardless. The body is remade around the current shape and every particle stops, so set it up front.

Since: 3.00. See also: softSetStiffness, softSetDamping

Example
-- A sheet pinned by four corners catches a crate dropped onto it.
local sheet = nodeNew()
nodeSetMesh(sheet, meshPlane(3, 3, 20, 20), linen)
nodeSetPosition(sheet, 0, 1.6, 0)
softNew(sheet, SOFT_CLOTH)
softSetStiffness(sheet, 1.0, 0.05)
softSetMass(sheet, 4)                        -- Heavy enough not to flutter
for _, c in ipairs({ { -1.5, -1.5 }, { 1.5, -1.5 }, { -1.5, 1.5 }, { 1.5, 1.5 } }) do
    softPin(sheet, c[1], 1.6, c[2])
end

2.37.8. softSetDamping

softSetDamping(node, damping)

How quickly the particles' motion dies away, 0 upward; default 0.1, and a negative value becomes 0. Higher values calm a flag that will not stop rippling or a rope that swings forever. The body is remade around the current shape and every particle stops.

Since: 3.00. See also: softSetMass, softSetStiffness

Example
-- A curtain in still air settles fast; the same curtain by the open window keeps moving.
local curtain = nodeNew()
nodeSetMesh(curtain, meshPlane(1.2, 2.4, 12, 24), velvet)
nodeSetPosition(curtain, 2, 2.4, -3)
nodeSetRotation(curtain, 90, 0, 0)
softNew(curtain, SOFT_CLOTH)
softSetDamping(curtain, windowOpen and 0.05 or 0.4)
for x = -0.6, 0.6, 0.1 do
    softPin(curtain, 2 + x, 3.6, -3)
end

2.38. Sound

Sound effects are audio clips (WAV is the safe choice) loaded into memory and mixed through SDL_mixer, separate from the disc’s own audio and from the audio of video* assets. soundLoad returns a sound handle that identifies the clip’s data; soundPlay starts that clip on one of sixteen mixer channels and returns the channel number, 0 through 15, which is what soundPause, soundResume, soundStop, soundIsPlaying and every soundSet* call take. One clip can play on several channels at once, and a channel number is reused as soon as the channel is free, so keep the two kinds of number apart. A master effects volume (soundSetVolume, 0 to 63) scales every channel. A playing channel can also sit in the 3D scene, following a node or fixed at a point in world units, where it is panned and faded by its distance from the listener (see 3D Scenes); for 2D games soundSetPan pans a channel without a scene.

2.38.1. soundFullStop

soundFullStop()

Stops every effect channel at once, paused ones included, and frees them for reuse. No clip is unloaded; the handles from soundLoad stay valid. Every channel that was playing or paused reports through onSoundCompleted, exactly as it does after soundStop. Call it on a scene change or before a cutscene rather than tracking every channel you started.

Since: 1.16 See also: soundStop, onSoundCompleted

Example
function enterAttractMode()
    soundFullStop()
    ambientChannel = -1
    engineChannel  = -1
    discPlay()
end

2.38.2. soundGetPosition

x, y, z, gain = soundGetPosition(channel)

Reports where a positioned channel sits relative to the listener, as a direction of unit length in the listener’s frame (x positive to the right, y positive up, z positive behind the listener), and the volume factor its distance currently gives it, 0 to 1. The values are refreshed once per frame from the listener and the channel’s node or point. A channel that has not been placed in the scene since it started returns 0, 0, 0, 1. Meant for radar-style indicators and for checking a mix from a test script; a channel outside 0 to 15 aborts the script.

Returns: three numbers for the direction and one for the distance gain.

Since: 3.00. See also: soundSetNode, soundSetPosition, soundSetRange

Example
-- Point an arrow on the HUD toward the nearest audible enemy.
function onOverlayUpdate()
    overlayClear()
    local x, y, z, gain = soundGetPosition(growlChannel)
    if gain > 0 then
        local angle = math.atan(x, -z)
        drawThreatArrow(angle, gain)
    end
    return OVERLAY_UPDATED
end

2.38.3. soundGetVolume

volume = soundGetVolume()

Returns the master effects volume, 0 through 63. At startup it reflects the effects volume from the command line, so a game that shows a volume setting should read it rather than assume the maximum.

Returns: integer, 0 to 63.

Since: 1.16 See also: soundSetVolume

Example
-- Duck the effects while the narrator speaks, then put them back.
function narratorBegin()
    savedVolume = soundGetVolume()
    soundSetVolume(math.floor(savedVolume / 3))
    narratorChannel = soundPlay(narratorClip)
end

2.38.4. soundIsPlaying

playing = soundIsPlaying(channel)

Tests whether a channel is playing right now. A paused channel reports false, as does a channel whose clip has finished. A channel outside 0 to 15 aborts the script; a channel that has merely gone quiet does not.

Returns: boolean.

Since: 1.16 (RDG) See also: soundPlay, soundPause

Example
-- Do not restart the alarm while it is still sounding.
function raiseAlarm()
    if alarmChannel < 0 or not soundIsPlaying(alarmChannel) then
        alarmChannel = soundPlay(alarmClip)
    end
end

2.38.5. soundLoad

id = soundLoad(filename)

Loads an audio clip into memory and returns its handle. The path goes through the game’s virtual file system, so it works the same from a loose directory and from a packed game. Load clips once at startup, not inside a callback that fires every frame. A file that cannot be opened or decoded aborts the script.

Returns: integer sound handle. This is a data handle, not a channel number.

Since: 1.x See also: soundPlay, soundUnload

Example
-- Clip handles, loaded once and unloaded in onShutdown.
shotClip    = soundLoad(DIR .. "sounds/shot.wav")
missClip    = soundLoad(DIR .. "sounds/miss.wav")
coinClip    = soundLoad(DIR .. "sounds/coin.wav")
ambientClip = soundLoad(DIR .. "sounds/wind.wav")

2.38.6. soundLoadData

id = soundLoadData(data)

Hypseus extension. Builds a sound from bytes held in a Lua string instead of from a file. Every format soundLoad reads is read here, and the handle it returns is used with the rest of the sound family in exactly the same way.

The string may hold zero bytes; its length, not its first zero, decides how much is read. The bytes are decoded during the call and the string is not kept, so it may be discarded afterwards. Bytes that are not audio, or an empty string, terminate the script, as an unreadable file does in soundLoad.

Use it for audio a game generates, unpacks or decrypts for itself. Audio the virtual file system can reach by name — including audio inside a packed .game — is better loaded with soundLoad, which does not hold the whole file in a Lua string.

Parameters:

  • data — string of bytes.

Returns: number, the sound handle.

Since: 3.00, as a Hypseus Singe extension. See also: soundLoad, spriteLoadData, soundPlay

Example
-- A sound effect the game unpacks from its own archive.
local bytes = myArchive:extract("beep.wav")
local beep  = soundLoadData(bytes)
soundPlay(beep)

2.38.7. soundPause

wasPlaying = soundPause(channel)

Pauses a channel in place; soundResume continues it from the same point. A paused channel still counts as busy, so soundPlay will not hand it out to another clip, and soundIsPlaying reports false for it. Pausing a channel that is not playing does nothing. A channel outside 0 to 15 aborts the script.

Returns: boolean, true when the channel was playing at the moment of the call.

Since: 1.16 (RDG) See also: soundResume, soundIsPlaying

Example
-- Hold the engine noise while the radio message plays.
function radioBegin(messageClip)
    engineWasRunning = soundPause(engineChannel)
    radioChannel     = soundPlay(messageClip)
end

2.38.8. soundPlay

channel = soundPlay(id)
channel = soundPlay(id, loops)
channel = soundPlay(id, loops, volume)

Starts a loaded clip on the first free channel and returns that channel’s number. A channel counts as free when it is neither playing nor paused. The new channel starts at the master volume (or at volume under it), centered, with no scene position and the default range, whatever the channel’s previous use set. When all sixteen channels are busy nothing plays and -1 (SOUND_ERROR_INVALID) comes back; a game that fires many overlapping sounds should check for it. A handle that is not loaded aborts the script.

Parameters:

  • id — sound handle from soundLoad.

  • loops — 0 (the default) plays the clip once, a positive count repeats it that many more times, -1 loops it until it is stopped. Anything below -1 aborts the script.

  • volume — the channel’s own volume, 0 through 63, under the master; the default is 63, the clip as loud as the master allows. Outside that range aborts the script. soundSetChannelVolume changes it while the clip plays.

Returns: integer channel number, 0 to 15, or -1 when no channel is free.

Since: 1.x; volume since 3.00. See also: soundLoad, soundStop, soundSetChannelVolume, soundSetNode

Example
function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        local channel = soundPlay(shotClip)
        if channel < 0 then
            debugPrint("All sound channels busy; shot dropped")
        end
    elseif what == SWITCH_COIN1 then
        soundPlay(coinClip)
        credits = credits + 1
    end
end

2.38.9. soundResume

wasPaused = soundResume(channel)

Continues a channel that soundPause stopped, from where it left off. Resuming a channel that is not paused does nothing. A channel outside 0 to 15 aborts the script.

Returns: boolean, true when the channel was paused at the moment of the call.

Since: 1.16 (RDG) See also: soundPause

Example
function onSoundCompleted(channel)
    if channel == radioChannel then
        radioChannel = -1
        if engineWasRunning then
            soundResume(engineChannel)
        end
    end
end

2.38.10. soundSetChannelVolume

soundSetChannelVolume(channel, volume)

Sets one channel’s own volume, on top of the master from soundSetVolume: the channel plays at the master times this, times its distance fade when it is in the scene. Every channel starts at full when soundPlay takes it, unless soundPlay was given a volume, so a quiet footstep and a loud shot can share one master. Values outside 0 to 63 abort the script, and so does a channel outside 0 to 15.

Parameters:

  • channel — channel number from soundPlay.

  • volume — integer, 0 (silent) through 63 (as loud as the master).

Since: 3.00 See also: soundPlay, soundSetVolume

Example
-- An engine that gets louder with the throttle:  one looping clip, its channel's volume
-- following the pedal every frame.
engine = soundPlay(engineClip, -1, 20)

function onOverlayUpdate()
    soundSetChannelVolume(engine, math.floor(20 + throttle * 43))
end

2.38.11. soundSetListener

soundSetListener(node)
soundSetListener()

Chooses the node that positioned channels are heard from, facing the way it faces. With no argument, or nil, the listener is the scene camera, which is right for a first-person or fixed-camera game; a third-person game usually prefers the player’s node so that sounds pan around the character rather than the camera. A node that is later deleted drops the listener back to the camera. A node handle that does not exist aborts the script.

Since: 3.00. See also: soundSetNode, soundSetPosition, cameraSet

Example
-- Chase camera, but hear the world from the car.
local car = modelInstance(carModel)
local chaseCamera = nodeNew(car)
nodeSetPosition(chaseCamera, 0, 2, 6)
cameraSet(chaseCamera)
soundSetListener(car)

2.38.12. soundSetNode

soundSetNode(channel, node)
soundSetNode(channel)

Attaches a playing channel to a scene node so it is heard from wherever the node is each frame: the channel is panned toward the node’s direction from the listener and faded by its distance according to soundSetRange. Calling it with no node, or nil, takes the channel back out of the scene at full master volume. A channel whose node is deleted drops back to plain playback on its own. The attachment lasts until the channel is stopped or reused by soundPlay. A channel outside 0 to 15, or a node that does not exist, aborts the script.

Example
-- Each brazier crackles from where it stands.
for i, brazier in ipairs(braziers) do
    local channel = soundPlay(crackleClip, -1)
    if channel >= 0 then
        soundSetNode(channel, brazier)
        soundSetRange(channel, 1.5, 14)
    end
end

2.38.13. soundSetPan

soundSetPan(channel, pan)

Pans a channel across the stereo pair for games without a scene: -1 is fully left, 1 fully right, 0 centered, and values outside that range are clamped. Moving away from center reduces the far speaker only; at pan = 0.5 the left speaker plays at half gain and the right at full. The call takes the channel out of the scene if soundSetNode or soundSetPosition had placed it there. A channel outside 0 to 15 aborts the script.

Since: 3.00. See also: soundPlay, soundSetNode

Example
-- Pan a passing car by where it is on the overlay.
function carPassBy(x)
    local channel = soundPlay(carClip)
    if channel >= 0 then
        soundSetPan(channel, (x / overlayGetWidth()) * 2 - 1)
    end
end

2.38.14. soundSetPosition

soundSetPosition(channel, x, y, z)

Places a playing channel at a fixed point in the scene, in world units, replacing any node it was following. It is then panned and faded from the listener like a node-attached channel. Suits a sound that stays put, such as a waterfall or a ringing telephone; a moving source is easier with soundSetNode. A channel outside 0 to 15 aborts the script.

Since: 3.00. See also: soundSetNode, soundSetRange, soundGetPosition

Example
-- The waterfall never moves, so no node is needed.
waterfallChannel = soundPlay(waterfallClip, -1)
if waterfallChannel >= 0 then
    soundSetPosition(waterfallChannel, 42, 3, -18)
    soundSetRange(waterfallChannel, 6, 80)
end

2.38.15. soundSetRange

soundSetRange(channel, near, far)

Sets how a positioned channel fades with distance from the listener. Within near it plays at full volume; beyond that its gain is near divided by the distance; over the last fifth of far it also fades linearly, reaching silence at far. Defaults are 1 and 30 world units, restored whenever soundPlay reuses the channel. A whisper wants a small far, a waterfall a large one.

Parameters:

  • channel — channel number from soundPlay.

  • near — distance within which the channel is at full volume, greater than 0.

  • far — distance at which it is silent, greater than near. Any other pair aborts the script.

Example
-- A guard's footsteps are only audible nearby; the siren carries.
local steps = soundPlay(footstepClip, -1)
soundSetNode(steps, guard)
soundSetRange(steps, 0.5, 8)
local siren = soundPlay(sirenClip, -1)
soundSetNode(siren, tower)
soundSetRange(siren, 10, 200)

2.38.16. soundSetVolume

soundSetVolume(volume)

Sets the master effects volume and applies it at once to every channel, playing or paused. Each channel’s own volume from soundSetChannelVolume and, for positioned channels, the distance fade stay on top of it. Values outside 0 to 63 abort the script.

Parameters:

  • volume — integer, 0 (silent) through 63 (loudest).

Since: 1.16 See also: soundGetVolume, soundSetChannelVolume

Example
-- Service menu volume slider driven by the left and right switches.
function onInputPressed(what)
    local volume = soundGetVolume()
    if what == SWITCH_LEFT then
        soundSetVolume(math.max(0, volume - 4))
    elseif what == SWITCH_RIGHT then
        soundSetVolume(math.min(63, volume + 4))
    end
    soundPlay(clickClip)
end

2.38.17. soundStop

wasPlaying = soundStop(channel)

Halts a channel immediately, whether playing or paused, and frees it for reuse. The channel reports through onSoundCompleted just as it does when the clip finishes on its own, so a script that chains sounds from that callback should check whether it stopped the channel itself. The next soundPlay may hand the same number out again, so discard the number on the Lua side. A channel outside 0 to 15 aborts the script.

Returns: boolean, true when the channel was playing at the moment of the call. A paused channel returns false but is still stopped.

Since: 1.x (RDG) See also: soundFullStop, onSoundCompleted

Example
function playerDied()
    if engineChannel >= 0 then
        soundStop(engineChannel)
        engineChannel = -1
    end
    soundPlay(explosionClip)
    lives = lives - 1
end

2.38.18. soundUnload

soundUnload(id)

Frees a loaded clip and invalidates its handle. The mixer keeps the clip’s data alive until every channel still playing it has stopped, so unloading does not cut a playing channel short. Any later use of the handle, including another soundUnload, aborts the script. The usual place for it is onShutdown.

Parameters:

  • id — sound handle from soundLoad, not a channel number.

Since: 2.00 See also: soundLoad, onShutdown

Example
function onShutdown()
    soundUnload(shotClip)
    soundUnload(missClip)
    soundUnload(coinClip)
    soundUnload(ambientClip)
    fontUnload(hudFont)
end

2.39. Sprite

Sprites are 2D bitmaps loaded from disk with spriteLoad, or rendered from text with fontToSprite, and drawn onto the overlay in overlay coordinates. Every sprite* call takes the integer handle as its first argument (Singe 2.10 put it last; see Migrating from Singe 2.10), and a handle that has been unloaded ends the script with an error. Any format SDL_image reads is accepted; an animated GIF or WEBP with two or more frames loads as an animation that sits on frame 0, stopped and non-looping, until spritePlay and spriteLoop say otherwise. Color 0 is drawn transparent, as in Hypseus: palette index 0, or pure black, and that includes opaque black in an image with an alpha channel, whose alpha is honored as well. To keep a picture’s opaque black, load it after drawTransparent(true). Release every sprite with spriteUnload, usually from onShutdown.

Sprite sheets. Hypseus Singe extends the family with sprite sheets: spriteLoadFrames slices a single row strip of equal frames into an animation that is not playing, and spriteDrawFrame draws one chosen frame (1-based) without touching playback. A sheet is otherwise an ordinary animation, so spriteSetFrame (0-based), spritePlay, spriteDraw, nodeSetSprite and emitterSetTexture all accept it, and spriteFrameWidth and spriteFrameHeight report the unscaled size of one frame. The entries marked "Hypseus extension" exist so games written for Hypseus Singe run unchanged.

2.39.1. drawTransparent

drawTransparent(boolean)

Hypseus extension. Decides whether color 0 is drawn transparent on the sprites loaded, and the text rendered, after it. false, the default, keys color 0 as Hypseus does: palette index 0, or pure black, and that includes opaque black in a picture that has an alpha channel, so black lettering or a black outline disappears. true draws them by their alpha channel alone, so opaque black stays black. Sprites already loaded keep the setting they were loaded with, and every script starts at false.

Returns: nothing.

Since: 3.00

Example
-- The logo's lettering is opaque black:  load it by its alpha alone, then go back
-- to the usual key for the game's own art.
drawTransparent(true)
logo = spriteLoad("art/logo.png")
drawTransparent(false)

2.39.2. spriteBlend

spriteBlend(boolean, sprite)

Hypseus extension, accepted and ignored. It is a workaround for that engine: Hypseus loads sprites with SDL’s blend mode off, and this turns it back on for one sprite. Singe draws every sprite with its alpha channel already, so blending is never off to begin with. The sprite handle is still checked, so a bad one is still an error. To add a sprite’s light or multiply by it instead, see spriteSetBlend.

Returns: nothing.

Since: 3.00

2.39.3. spriteDraw

spriteDraw(id, x, y)
spriteDraw(id, x, y, centered)
spriteDraw(id, x, y, x2, y2)
spriteDraw(id, x, y, x2, y2, centered)

Blits the sprite onto the overlay as currently rotated and scaled. Call it from onOverlayUpdate. The first two forms draw at the size spriteGetWidth and spriteGetHeight report, with (x, y) as the top-left corner; the last two stretch that image into the rectangle from (x, y) to (x2, y2) inclusive, always with nearest-neighbor sampling whatever spriteQuality says. If the sprite is a playing animation, the draw first advances it by the real time elapsed since the previous draw (or since spritePlay), stepping through as many frames as that time covers, and shows each frame for at least 10 ms even when the file asks for less. When the last frame passes, playback wraps to frame 0 if spriteLoop is set, otherwise it stays on the last frame and stops. Parts that fall outside the overlay are clipped.

Parameters:

  • id — sprite handle from spriteLoad or fontToSprite.

  • x, y — anchor in overlay coordinates; fractions are truncated.

  • x2, y2 — opposite corner of the target rectangle, inclusive, for the stretched forms.

  • centered — boolean. When true, the image (or the stretched rectangle) is shifted so that (x, y) is its center instead of its top-left corner.

Notes: A playing animation that is not drawn for a while catches up on its next draw; call spritePause if it should hold its frame instead. Use the centered form for rotated sprites, since rotation changes the bounding box and a top-left anchor appears to drift.

Since: 1.x. Centered and stretched-centered forms added in 2.10. See also: spriteLoad, spriteRotate, spriteGetWidth, videoDraw

Example
-- Cabinet art at natural size, the attract still squeezed into its box,
-- and a cursor anchored on its center.
function onOverlayUpdate()
    overlayClear()
    spriteDraw(cabinetSprite, CABINET_X, CABINET_Y)
    spriteDraw(attractStill, THUMB_X, THUMB_Y, THUMB_X + THUMB_W - 1, THUMB_Y + THUMB_H - 1)
    spriteDraw(cursorSprite, cursorX, cursorY, true)
    return OVERLAY_UPDATED
end

2.39.4. spriteDrawFrame

spriteDrawFrame(id, x, y, frame)
spriteDrawFrame(id, x, y, frame, scale)
spriteDrawFrame(id, x, y, frame, scaleX, scaleY)

Hypseus extension. Blits one frame of a sprite sheet (or of any animation) onto the overlay with (x, y) as its top-left corner, without changing which frame the sprite is parked on or whether it is playing. Frames are numbered from 1, as Hypseus counts them; a frame outside 1 to the frame count draws frame 1. A still image draws itself and ignores frame. A mirror set by spriteFlip applies. The sprite’s own rotation and scale from spriteRotate and spriteScale are ignored: the first form draws the frame at its natural size, the others multiply the frame’s width by scaleX (or scale) and its height by scaleY (or scale) with nearest-neighbor sampling. Call it from onOverlayUpdate.

Parameters:

  • id — sprite handle from spriteLoadFrames or spriteLoad.

  • x, y — top-left corner in overlay coordinates; fractions are truncated.

  • frame — frame number, 1 to the frame count; fractions are truncated.

  • scale, scaleX, scaleY — size multipliers, 1 for natural size.

Notes: spriteSetFrame counts frames from 0; spriteDrawFrame counts from 1.

Since: 3.00, as a Hypseus Singe extension. See also: spriteLoadFrames, spriteDraw, spriteSetFrame, spriteFrameWidth

Example
-- A ten frame digit strip draws the score, one digit per frame.
digits = spriteLoadFrames(10, DIR .. "digits.png")

function drawScore(x, y, score)
    local text = tostring(score)
    for i = 1, #text do
        spriteDrawFrame(digits, x + (i - 1) * spriteFrameWidth(digits), y, tonumber(text:sub(i, i)) + 1)
    end
end

2.39.5. spriteDrawGrid

spriteDrawGrid(id, x, y, sourceX, sourceY, width, height)
spriteDrawGrid(id, x, y, sourceX, sourceY, width, height, x2, y2)

Hypseus extension. Draws one rectangle out of a sprite with its top left corner at x, y: at its own size, or, given x2 and y2, stretched to fill the box out to that corner, the way spriteDraw stretches a whole sprite. It is the only call that takes a source rectangle: spriteDraw takes the whole sprite and spriteDrawFrame takes a whole frame of a sheet, while this takes any rectangle at all. That is how a game cuts a tile, a digit, or a letter out of one image without loading it many times over.

The stretched form is Singe’s own, and it is what a road-racing game is built on. Each row of the screen below the horizon is a slice of road at some distance, so the game cuts one row out of a picture of the road’s cross-section and stretches it to the road’s width at that distance, centered where the bends have carried it. A hundred-odd calls a frame draw the whole road, curves and hills included, and nothing is rebuilt. The same form draws a sprite partly hidden behind the crest of a hill: cut its top part out and stretch it to what is left showing. spriteScale can do neither, since it rebuilds the whole picture each time the size changes.

The rectangle is in the sprite’s own pixels and must lie inside it; a rectangle that does not, or one with no width or height, terminates the script naming the sprite’s size, and so does an x2 with no y2. A stretch whose box has no width or height, because x2 is left of x or y2 above y, draws nothing. The stretch picks the nearest pixel rather than blending, which keeps a one-pixel row’s colors exactly as drawn. The sprite drawn from is the sprite as it is currently drawn, so a spriteRotate or a spriteScale changes what the coordinates mean.

Under LEGACY_SPRITE_ARGS the handle is third, spriteDrawGrid(x, y, spr, sourceX, sourceY, width, height), which is where Hypseus puts it, and x2, y2 follow on the end as they do here.

Parameters:

  • id — number; a sprite handle.

  • x, y — numbers; where the rectangle’s top left corner lands, in overlay coordinates.

  • sourceX, sourceY — numbers; the rectangle’s top left corner in the sprite.

  • width, height — numbers; its size, at least 1.

  • x2, y2 — numbers, optional together; the bottom right corner of the box to stretch it into, inclusive.

Returns: nothing.

Since: 3.00, as a Hypseus Singe extension; the stretched form is new in 3.00 and Singe’s own. See also: spriteDraw, spriteDrawFrame

Example
-- A number drawn from one strip of ten digits, each 16 by 24.
local function drawNumber(sheet, x, y, value)
    local text = tostring(value)
    for i = 1, #text do
        local digit = tonumber(text:sub(i, i))
        spriteDrawGrid(sheet, x + (i - 1) * 16, y, digit * 16, 0, 16, 24)
    end
end
Example
-- A straight road to the horizon, one screen row at a time.  road.png is 256 pixels across and two
-- rows deep:  a light cross-section of road and a dark one, which alternate down the road to show
-- it moving.  Row y of the screen is the ground EYE * FOCAL / (y - HORIZON) away.
local EYE     = 60
local FOCAL   = 160
local HORIZON = 110
local HALF    = 100

local function drawRoad(road, traveled)
    for y = HORIZON + 1, 239 do
        local z     = EYE * FOCAL / (y - HORIZON)
        local half  = HALF * FOCAL / z
        local light = math.floor((z + traveled) / 60) % 2
        spriteDrawGrid(road, 160 - half, y, 0, light, 256, 1, 160 + half, y)
    end
end

2.39.6. spriteDrawRotatedFrame

spriteDrawRotatedFrame(id, x, y)
spriteDrawRotatedFrame(id, x, y, scale)
spriteDrawRotatedFrame(id, x, y, scaleX, scaleY)

Hypseus extension. Draws the frame spriteRotateFrame last turned, centered on x, y. This is the pair to that call and the reason both exist: spriteDrawFrame deliberately ignores a sprite’s rotation and scale, so a game that wants one frame of a sheet turned uses these two instead.

Given a scale, the turned frame is stretched by it as it is drawn — on top of whatever scale it was turned with — and the result is still centered on x, y. scaleX alone scales both axes.

Drawing before any spriteRotateFrame terminates the script, since there is no turned frame to draw.

Under LEGACY_SPRITE_ARGS the handle is last, as Hypseus writes it.

Parameters:

  • id — number; a sprite handle.

  • x, y — numbers; the center of the drawn frame, in overlay coordinates.

  • scale or scaleX, scaleY — optional numbers; a further scale at draw time.

Returns: nothing.

Since: 3.00, as a Hypseus Singe extension. See also: spriteRotateFrame, spriteDrawFrame

Example
-- A compass needle:  one frame of the sheet, pointing where the player is going.
spriteRotateFrame(needle, heading, 1)
spriteDrawRotatedFrame(needle, 320, 240)

2.39.7. spriteFlip

spriteFlip(id, horizontal, vertical)

Mirrors the sprite left to right, top to bottom, or both, until it is called again with false, false. The mirror applies to every draw of the sprite: spriteDraw, each frame from spriteDrawFrame, and the turned frame from spriteDrawRotatedFrame. It is applied after the rotation and scale from spriteRotate and spriteScale, so a turned sprite is mirrored as it appears on screen, and a turned frame is simply mirrored the other way rather than turned again. The mirrored image is rebuilt only when the flags change; a frame drawn by spriteDrawFrame is mirrored once and kept until another frame is asked for. spriteDrawGrid ignores the mirror, since its rectangle is cut from the unmirrored image.

A character that walks both ways needs only art that faces one way: flip the sprite when it turns round.

Parameters:

  • id — sprite handle.

  • horizontal — true mirrors left to right.

  • vertical — true mirrors top to bottom.

Returns: nothing.

Example
-- The hero's sheet faces right; facing left is the same frames, mirrored.
function onOverlayUpdate()
    overlayClear()
    spriteFlip(hero, heroVx < 0, false)
    spriteDrawFrame(hero, heroX, heroY, walkFrame)
    return OVERLAY_UPDATED
end

2.39.8. spriteFrameHeight

height = spriteFrameHeight(id)

Hypseus extension. Returns the height of one frame of the sprite before any scaling or rotation: the strip’s height for a spriteLoadFrames sheet, a frame’s height for an animation, and the image’s height for a still (Hypseus reports the drawn surface here). spriteGetHeight reports the size as drawn instead.

Returns: integer.

Since: 3.00, as a Hypseus Singe extension. See also: spriteFrameWidth, spriteGetHeight, spriteLoadFrames

Example
-- Center a frame on a point.
function drawCentered(sheet, frame, x, y)
    spriteDrawFrame(sheet, x - spriteFrameWidth(sheet) / 2, y - spriteFrameHeight(sheet) / 2, frame)
end

2.39.9. spriteFrameWidth

width = spriteFrameWidth(id)

Hypseus extension. Returns the width of one frame of the sprite before any scaling or rotation: the strip’s width divided by the frame count for a spriteLoadFrames sheet, a frame’s width for an animation, and the image’s width for a still (Hypseus reports 0 there). spriteGetWidth reports the size as drawn instead.

Returns: integer.

Since: 3.00, as a Hypseus Singe extension. See also: spriteFrameHeight, spriteGetWidth, spriteLoadFrames

Example
-- Lay the frames of a strip out side by side.
function drawStrip(sheet, count, x, y)
    for frame = 1, count do
        spriteDrawFrame(sheet, x + (frame - 1) * spriteFrameWidth(sheet), y, frame)
    end
end

2.39.10. spriteGetFrame

result = spriteGetFrame(id)

Returns the zero-based index of the frame the sprite currently shows. Still images and animations that have not advanced report 0. Frames advance only inside spriteDraw, so the value changes between draws, not between arbitrary calls. Use it to line up sound or game logic with a particular frame of an animation.

Returns: integer frame index, 0 for a still image.

Since: 2.10 See also: spriteSetFrame, spriteIsPlaying, spriteDraw

Example
-- Fire the gunshot on the frame where the muzzle flash appears.
function onOverlayUpdate()
    spriteDraw(muzzleFlash, gunX, gunY, true)
    local frame = spriteGetFrame(muzzleFlash)
    if frame == FLASH_FRAME and frame ~= lastFlashFrame then
        soundPlay(gunshot)
    end
    lastFlashFrame = frame
    return OVERLAY_UPDATED
end

2.39.11. spriteGetFrames

count = spriteGetFrames(id)

Hypseus extension. How many frames a sprite has: the frame count of a sheet loaded by spriteLoadFrames or of an animated GIF or WEBP, and 0 for a still image. It is the count spriteSetFrame's zero based frame number runs up to, and one more than the largest it will take.

Parameters:

  • id — number; a sprite handle.

Returns: number; 0 for a still image.

Since: 3.00, as a Hypseus Singe extension. See also: spriteLoadFrames, spriteGetFrame, spriteSetFrame

Example
-- Step to the next frame, whatever the sheet turned out to be.
local frames = spriteGetFrames(walk)
if frames > 0 then
    spriteSetFrame(walk, (spriteGetFrame(walk) + 1) % frames)
end

2.39.12. spriteGetHeight

result = spriteGetHeight(id)

Returns the height of the sprite as it would be drawn right now, in overlay coordinates. Scaling and rotation applied with spriteScale, spriteRotate, or spriteRotateAndScale are included, so a rotated sprite reports the height of its rotated bounding box, not of the source image. For an animation the current frame is measured. The stretched forms of spriteDraw do not affect the value.

Returns: integer height.

Since: 2.00 See also: spriteGetWidth, spriteScale, spriteRotate

Example
-- Stack pre-rendered description lines, spaced by the height of the text sprites.
function onOverlayUpdate()
    local y = TEXT_Y
    for _, line in ipairs(descriptionLines) do
        spriteDraw(line, TEXT_X, y)
        y = y + spriteGetHeight(line) + 1
    end
    return OVERLAY_UPDATED
end

2.39.13. spriteGetWidth

result = spriteGetWidth(id)

Returns the width of the sprite as it would be drawn right now, in overlay coordinates, including any scaling and rotation currently applied. For an animation the current frame is measured. Together with spriteGetHeight this is the usual way to center a sprite in a box or to measure text rendered by fontToSprite.

Returns: integer width.

Since: 2.00 See also: spriteGetHeight, spriteScale, fontToSprite

Example
-- Center the cabinet image inside its panel, and the title across the overlay.
function onOverlayUpdate()
    local x = CABINET_X + (CABINET_W - spriteGetWidth(cabinetSprite)) * 0.5
    local y = CABINET_Y + (CABINET_H - spriteGetHeight(cabinetSprite)) * 0.5
    spriteDraw(cabinetSprite, x, y)
    spriteDraw(titleSprite, (overlayGetWidth() - spriteGetWidth(titleSprite)) / 2, 25)
    return OVERLAY_UPDATED
end

2.39.14. spriteIsPlaying

result = spriteIsPlaying(id)

Reports whether the sprite’s animation is currently advancing. A freshly loaded sprite reports false; spritePlay turns it on, and spritePause or the end of a non-looping animation turns it off. Poll it to find out when a one-shot animation has finished.

Returns: boolean, true while the animation is playing.

Notes: spritePlay and spritePause do not check for animation data, so a still image reports whatever those calls last set.

Since: 2.10 See also: spritePlay, spritePause, spriteLoop

Example
-- Hold the menu until the one-shot logo animation has finished.
function onOverlayUpdate()
    overlayClear()
    spriteDraw(logoReveal, overlayGetWidth() / 2, overlayGetHeight() / 2, true)
    if not spriteIsPlaying(logoReveal) then
        drawMenu()
    end
    return OVERLAY_UPDATED
end

2.39.15. spriteLoad

result = spriteLoad(filename)
result = spriteLoad(filename, width, height)

Loads an image and returns an integer handle for the other sprite* calls. The name goes through the engine’s virtual file system, so it may live loose on disk or inside a packed game; it is resolved relative to the directory Singe was started in, so prepend DIR for files shipped with your game. Every format in Video, Audio, and Container Formats is read. An animated GIF or WEBP with two or more frames loads as an animation, parked on frame 0, not playing and not looping; every other file, including a single-frame GIF, loads as a still image. An image with more than 8 bits per channel, or floating point pixels, is converted to 8-bit RGBA on load and treated as one from then on. Pixels with a raw value of 0 in the file’s own pixel format become transparent. Loading is synchronous, and a file that cannot be opened or decoded ends the script with the loader’s error message rather than returning nil.

The optional size is for a vector picture — an SVG — which has no size of its own worth having: the picture is rasterized to fit that box, keeping its own proportions, rather than rasterized at the file’s size and scaled up. Ask spriteGetWidth and spriteGetHeight what it came out as, because fitting a square drawing into a wide box leaves the width unused. Every other format ignores the size.

Parameters:

  • filename — string; the image to load.

  • width — optional number; the width to fit an SVG into, 1 or more.

  • height — optional number; the height to fit an SVG into, 1 or more. Both must be given together.

Returns: integer sprite handle.

Notes: Animations do not start by themselves. Call spriteLoop(id, true) and spritePlay(id) after loading if the animation should run and repeat.

Since: 1.x. Animated GIF/WEBP support added in 2.10; the vector size in 3.00. See also: spriteUnload, spritePlay, spriteLoop, fontToSprite

Example
-- Load the menu art once at startup; the attract loop is an animated WEBP.
cabinetSprite = spriteLoad(DIR .. "cabinet.png")
marqueeSprite = spriteLoad(DIR .. "marquee.png")
attractLoop   = spriteLoad(DIR .. "attract.webp")
spriteQuality(attractLoop, RENDER_SMOOTH)
spriteLoop(attractLoop, true)
spritePlay(attractLoop)

2.39.16. spriteLoadData

id = spriteLoadData(data)

Hypseus extension. Builds a sprite from an image held in a Lua string instead of from a file. Every format spriteLoad reads is read here, animated GIF and WEBP included, and an animation loaded this way behaves exactly as one loaded from a file.

The string may hold zero bytes; its length, not its first zero, decides how much is read. The image is decoded during the call and the string is not kept. Bytes that are not an image, or an empty string, terminate the script, as an unreadable file does in spriteLoad.

Use it for artwork a game generates, unpacks or decrypts for itself. Artwork the virtual file system can reach by name — including artwork inside a packed .game — is better loaded with spriteLoad, which does not hold the whole file in a Lua string.

Parameters:

  • data — string of bytes.

Returns: number, the sprite handle.

Since: 3.00, as a Hypseus Singe extension. See also: spriteLoad, soundLoadData

Example
-- An image the game keeps inside its own data file.
local bytes = myArchive:extract("logo.png")
local logo  = spriteLoadData(bytes)
spriteDraw(logo, 10, 10)

2.39.17. spriteLoadFrames

result = spriteLoadFrames(count, filename)

Hypseus extension. Loads an image holding count equal frames in a single row and returns a sprite handle. The frame width is the image width divided by count (integer division; leftover columns on the right are dropped) and the frame height is the image height. The sheet becomes an ordinary animation parked on frame 0, not playing and not looping, so spriteDraw shows the current frame rather than the whole strip (as Hypseus draws it), and spriteDrawFrame picks any frame directly. The name goes through the virtual file system like spriteLoad, and pixels with a raw value of 0 become transparent in every frame. A count outside 2 to 512, an image narrower than count pixels, or a file that cannot be read ends the script with an error.

Parameters:

  • count — number of frames across the image, 2 to 512.

  • filename — the strip image.

Returns: integer sprite handle.

Since: 3.00, as a Hypseus Singe extension. See also: spriteDrawFrame, spriteFrameWidth, spriteLoad, spriteUnload

Example
-- A five frame car strip; frame 3 is the car pointing straight ahead.
carSprite = spriteLoadFrames(5, DIR .. "car.png")
carWidth  = spriteFrameWidth(carSprite)

function onOverlayUpdate()
    overlayClear()
    spriteDrawFrame(carSprite, (overlayGetWidth() - carWidth) / 2, CAR_Y, carFrame)
    return OVERLAY_UPDATED
end

2.39.18. spriteLoop

spriteLoop(id, loop)

Sets whether the animation restarts from frame 0 after its last frame or stops there. New sprites do not loop. The setting is consulted each time spriteDraw steps past the last frame, so it can be changed while the animation runs. Setting it on a sprite that has already stopped does not restart playback; call spritePlay for that. The argument must be a Lua boolean.

Parameters:

  • id — sprite handle.

  • loop — boolean. true wraps to frame 0; false (the default) stops on the last frame and spriteIsPlaying starts returning false.

Since: 2.10 See also: spritePlay, spriteIsPlaying, spriteSetFrame

Example
-- The torch flickers forever; the explosion plays once per hit.
torchFlame = spriteLoad(DIR .. "torch.gif")
explosion  = spriteLoad(DIR .. "explosion.gif")
spriteLoop(torchFlame, true)
spriteLoop(explosion, false)
spritePlay(torchFlame)

2.39.19. spriteNew

id = spriteNew(width, height)

Makes a blank sprite, every pixel transparent, for spriteSetPixels to fill: a picture the script makes itself rather than loads. Each side is 1 to 4096 pixels; anything else ends the script. The sprite is a still and does everything any other still does: it draws, turns, scales, stretches, and tints, and it can be a material’s texture.

Parameters:

  • width, height — numbers; its size in pixels.

Returns: number, the sprite handle.

Since: 3.00 See also: spriteSetPixels, spriteLoadData

Example
local minimap = spriteNew(64, 64)

2.39.20. spritePause

spritePause(id)

Stops the animation on its current frame. The frame keeps being drawn by spriteDraw, and the time spent paused is not counted when spritePlay resumes, so the frame does not skip ahead. Pausing a sprite that is not playing changes nothing.

Since: 2.10 See also: spritePlay, spriteIsPlaying

Example
-- Freeze the enemy mid-stride while the hit flash plays.
function onOverlayUpdate()
    if playerHit and spriteIsPlaying(enemyWalk) then
        spritePause(enemyWalk)
    end
    spriteDraw(enemyWalk, enemyX, enemyY, true)
    return OVERLAY_UPDATED
end

2.39.21. spritePlay

spritePlay(id)

Starts or resumes the animation from its current frame, timing the first step from the moment of the call. A sprite that is already playing is left alone, so the frame timer is not reset. A new sprite must be started with this call; loading alone does not animate it.

Notes: A non-looping animation that has reached its last frame stays on that frame when played again. To replay it, call spriteSetFrame(id, 0) first.

Since: 2.10 See also: spritePause, spriteSetFrame, spriteLoop

Example
-- Restart the one-shot explosion at the point of impact.
function onCollision(a, b, x, y, z, speed)
    if speed > IMPACT_SPEED then
        blastX = x
        blastY = y
        spriteSetFrame(explosion, 0)
        spritePlay(explosion)
        soundPlay(boom)
    end
end

2.39.22. spriteQuality

spriteQuality(id, mode)

Chooses the sampling used when the sprite is rebuilt for rotation or scaling. RENDER_PIXELATED keeps hard pixel edges, RENDER_SMOOTH interpolates. New sprites are pixelated. The setting only matters while a rotation or a scale other than 1.0 is in effect; an untransformed sprite is drawn straight from its source image, and the stretched forms of spriteDraw always use nearest-neighbor sampling. Changing the mode rebuilds the transformed image at once, so set it once after loading rather than every frame.

Parameters:

  • id — sprite handle.

  • mode — RENDER_PIXELATED (0) or RENDER_SMOOTH (1). Any nonzero number selects smooth.

Example
-- Photographic marquee art should interpolate; pixel art must stay crisp.
marqueeSprite = spriteLoad(DIR .. "marquee.jpg")
playerSprite  = spriteLoad(DIR .. "player.png")
spriteQuality(marqueeSprite, RENDER_SMOOTH)
spriteQuality(playerSprite, RENDER_PIXELATED)
spriteScale(marqueeSprite, 0.5)
spriteScale(playerSprite, 3)

2.39.23. spriteResetColorKey

spriteResetColorKey(id, enabled)

Hypseus extension. Accepted for compatibility and does nothing. In Hypseus the flag re-applies the transparent color to the copies spriteRotate and spriteScale produce, which would otherwise draw their background opaque; Singe’s transformed copies carry the transparency in their alpha channel, so there is nothing to re-key. A bad handle or a non-boolean argument aborts the script, as for every other sprite call.

Parameters:

  • id — sprite handle.

  • enabled — boolean, ignored.

Since: 3.00, as a Hypseus Singe extension. See also: spriteRotate, spriteScale, spriteLoad

Example
-- Hypseus game code; harmless in Singe.
badge = spriteLoad(DIR .. "badge.png")
spriteResetColorKey(badge, true)

2.39.24. spriteRotate

spriteRotate(id, degrees)

Rotates the sprite clockwise about its center. The angle is reduced modulo 360 and may be fractional or negative. The current scale is kept. The rotated image is rebuilt only when the angle actually changes, so repeating the same angle every frame costs nothing, while a new angle every frame rebuilds every frame. Rotation enlarges the bounding box, so spriteGetWidth and spriteGetHeight change and the centered form of spriteDraw is the one to use.

Example
-- Crates from a 2D physics scene, drawn at the angle of their bodies.
function onOverlayUpdate()
    overlayClear()
    for _, crate in ipairs(crates) do
        local x, y = nodeGetPosition(crate)
        local _, _, angle = nodeGetRotation(crate)
        spriteRotate(crateSprite, angle)
        spriteDraw(crateSprite, x, y, true)
    end
    return OVERLAY_UPDATED
end

2.39.25. spriteRotateAndScale

spriteRotateAndScale(id, degrees, scale)
spriteRotateAndScale(id, degrees, scaleX, scaleY)

Sets rotation and scale together. The result is the same as spriteRotate followed by spriteScale, but the transformed image is rebuilt once instead of twice, and not at all when nothing changed. Scale factors should be greater than 0; a negative one is taken without its sign, and one that would leave no pixels, zero included, leaves one instead.

Parameters:

  • id — sprite handle.

  • degrees — clockwise rotation, reduced modulo 360.

  • scale — uniform factor, 1.0 for natural size.

  • scaleX, scaleY — separate horizontal and vertical factors.

Since: 2.10 See also: spriteRotate, spriteScale, spriteQuality

Example
-- A coin that spins and shrinks as it flies toward the score counter.
function onOverlayUpdate()
    if coinFlying then
        coinT = math.min(coinT + 0.02, 1)
        spriteRotateAndScale(coinSprite, coinT * 720, 1 - coinT * 0.75)
        spriteDraw(coinSprite, coinX + (SCORE_X - coinX) * coinT, coinY + (SCORE_Y - coinY) * coinT, true)
        coinFlying = coinT < 1
    end
    return OVERLAY_UPDATED
end

2.39.26. spriteRotateFrame

spriteRotateFrame(id, degrees, frame)

Hypseus extension. Takes one frame out of a sprite sheet, turns it clockwise by degrees and scales it by the sprite’s own spriteScale, and keeps the result for spriteDrawRotatedFrame. The sprite’s own drawn surface is untouched, so spriteDraw and spriteDrawFrame go on showing what they showed.

Frames are numbered from 1, as spriteDrawFrame numbers them (and unlike spriteGetFrame and spriteSetFrame, which count from 0); a frame outside the sheet is frame 1 rather than an error. A still image turns its whole picture.

Turning is not free: the frame is redrawn pixel by pixel each time, so turn it when the angle changes rather than every frame. The angle is taken modulo 360, and spriteQuality decides whether the turned edges are smoothed.

Under LEGACY_SPRITE_ARGS the handle is last, spriteRotateFrame(degrees, frame, spr), as Hypseus writes it.

Parameters:

  • id — number; a sprite handle.

  • degrees — number; clockwise.

  • frame — number; 1 to the frame count.

Returns: nothing.

Since: 3.00, as a Hypseus Singe extension. See also: spriteDrawRotatedFrame, spriteRotate, spriteScale

Example
-- A ship sprite whose hull is frame 1 and whose thrust is frame 2.
spriteRotateFrame(ship, angle, thrusting and 2 or 1)
spriteDrawRotatedFrame(ship, shipX, shipY)

2.39.27. spriteScale

spriteScale(id, scale)
spriteScale(id, scaleX, scaleY)

Scales the sprite about its center, uniformly or per axis, keeping the current rotation. Factors must be greater than 0; 1.0 is natural size, and a factor of exactly 1.0 on both axes with no rotation draws the source image directly. The scaled image is rebuilt only when a factor changes, using the sampling chosen by spriteQuality. Prefer the stretched form of spriteDraw when the target size changes every frame, since it does not rebuild anything.

Parameters:

  • id — sprite handle.

  • scale — uniform factor.

  • scaleX, scaleY — separate horizontal and vertical factors.

Example
-- Enlarge the highlighted menu entry; the rebuild happens only when the selection moves.
function onOverlayUpdate()
    for i, label in ipairs(menuLabels) do
        if i == selected then
            spriteScale(label, 1.25)
        else
            spriteScale(label, 1)
        end
        spriteDraw(label, MENU_X, MENU_Y + i * LINE_HEIGHT, true)
    end
    return OVERLAY_UPDATED
end

2.39.28. spriteSetAlpha

spriteSetAlpha(id, alpha)

Multiplies every pixel’s alpha by alpha / 255 on every draw of the sprite, in every form: spriteDraw, spriteDrawFrame, spriteDrawGrid, and spriteDrawRotatedFrame, turned or not. 255, the default, draws it as it is and 0 not at all, so a logo fades in and out with no second image. Out-of-range values are clamped.

Parameters:

  • id — number; a sprite handle.

  • alpha — number; 0 to 255.

Returns: nothing.

Since: 3.00 See also: spriteSetBlend, spriteSetTint

Example
-- The title fades in over two seconds.
spriteSetAlpha(title, math.floor(255 * math.min(1, elapsed / 2)))
spriteDraw(title, 120, 80)

2.39.29. spriteSetBlend

spriteSetBlend(id, SPRITE_ALPHA | SPRITE_ADD | SPRITE_MULTIPLY)

How every draw of the sprite lays it over what is already on the overlay. SPRITE_ALPHA, the default, draws it over by its alpha. SPRITE_ADD adds its color, scaled by its alpha, to what is there, so it can only brighten: glows, light, sparks, and the shadebobs of the old demos, where a ball drawn over itself again and again burns to white. SPRITE_MULTIPLY darkens what is there by its color, for shadows and tinted glass.

Added and multiplied pixels keep the overlay’s own alpha, so they show only where something is already drawn on the overlay: over a transparent overlay, above a video or the 3D scene, they change nothing. Draw something opaque first, or use emitterSetBlend with PARTICLE_ADD, which adds over everything. Anything other than the three constants ends the script.

Parameters:

  • id — number; a sprite handle.

  • blend — SPRITE_ALPHA, SPRITE_ADD, or SPRITE_MULTIPLY.

Returns: nothing.

Since: 3.00 See also: spriteSetAlpha, spriteSetTint, emitterSetBlend

Example
-- Shadebobs:  a soft white ball added along a path, never cleared, so the trail builds to white.
spriteSetBlend(ball, SPRITE_ADD)
spriteSetAlpha(ball, 40)
for i = 0, 15 do
    local a = t * 2 + i * 0.4
    spriteDraw(ball, 320 + math.cos(a) * 200, 240 + math.sin(a * 1.3) * 150, true)
end

2.39.30. spriteSetFrame

spriteSetFrame(id, frame)

Jumps an animation to the given frame and restarts that frame’s delay timer, so the frame is shown for its full duration before the next one. Playback state is not changed: a paused sprite stays paused on the new frame and a playing one continues from it. The call is ignored for still images, for frames outside 0 to the last frame, and when the sprite already shows that frame.

Notes: Frames are numbered from 0 here; spriteDrawFrame, the Hypseus extension, numbers them from 1.

Since: 2.10 See also: spriteGetFrame, spritePlay, spriteDrawFrame

Example
-- Show the door in the state the game logic says it is in.
function onOverlayUpdate()
    if doorOpen then
        spriteSetFrame(doorSprite, DOOR_OPEN_FRAME)
    else
        spriteSetFrame(doorSprite, DOOR_CLOSED_FRAME)
    end
    spriteDraw(doorSprite, DOOR_X, DOOR_Y)
    return OVERLAY_UPDATED
end

2.39.31. spriteSetPixels

spriteSetPixels(id, pixels)
spriteSetPixels(id, pixels, palette)

Replaces every pixel of a still sprite from a string, a row at a time from the top. Without a palette the string is four bytes a pixel, red, green, blue, and alpha. With one it is a byte a pixel, each the number of a color in the palette, which is 256 colors of three bytes (red, green, and blue, all opaque) or four (with alpha). A string of the wrong length, a palette of the wrong length, or an animated sprite ends the script.

It is how a script draws a picture a pixel at a time, fast enough to do every frame: the plasmas, tunnels, fire, and water of the old demos, a minimap, or a heightmap being edited. Building the string is the script’s work, so keep the picture small and stretch it when it is drawn: a Lua loop fills a 320 by 240 picture in a few milliseconds on a desktop. Palette mode is the old way to animate cheaply: set the same pixels again with the palette turned round one color, and everything shifts color with nothing recomputed. A sprite that is turned or scaled is turned and scaled again with its new pixels; a material that shows the sprite does not see the change until materialSetTexture is called with the sprite again, which uploads it afresh.

A loaded picture can be given new pixels too; it is the size it loaded at.

Parameters:

  • id — number; a still sprite.

  • pixels — string; width * height * 4 bytes, or width * height with a palette.

  • palette — optional string; 768 or 1024 bytes.

Returns: nothing.

Since: 3.00 See also: spriteNew, materialSetTexture

Example
-- Fire:  each pixel the average of the ones under it, cooling as it rises, through a palette from
-- black through red and yellow to white.  Stretched over the bottom of the screen every frame.
local W      = 160
local H      = 60
local fire   = spriteNew(W, H)
local heat   = {}
local color  = {}
for i = 0, 255 do
    color[#color + 1] = string.char(math.min(255, i * 3), math.max(0, math.min(255, i * 3 - 255)), math.max(0, i * 3 - 510))
end
local palette = table.concat(color)
for i = 0, W * (H + 1) - 1 do
    heat[i] = 0
end

function onOverlayUpdate()
    for x = 0, W - 1 do
        heat[H * W + x] = math.random(0, 255)
    end
    local rows = {}
    for y = 0, H - 1 do
        local row = {}
        for x = 0, W - 1 do
            local below = (y + 1) * W
            local v = (heat[below + (x - 1) % W] + heat[below + x] + heat[below + (x + 1) % W] + heat[y * W + x]) // 4
            heat[y * W + x] = math.max(0, v - 1)
            row[x + 1] = heat[y * W + x]
        end
        rows[y + 1] = string.char(table.unpack(row))
    end
    spriteSetPixels(fire, table.concat(rows), palette)
    overlayClear()
    spriteDraw(fire, 0, 240, 639, 479)
    return OVERLAY_UPDATED
end

2.39.32. spriteSetTint

spriteSetTint(id, r, g, b)

Multiplies every pixel’s color by r, g, b / 255 on every draw of the sprite, in every form. A white sprite draws in any color, and any sprite can be darkened or shifted toward a color, with no second image: one white ball becomes a rainbow of them, and a one-pixel white sprite stretched with spriteDraw becomes a filled rectangle of any color. 255, 255, 255, the default, draws it as it is. Out-of-range values are clamped.

Parameters:

  • id — number; a sprite handle.

  • r, g, b — numbers; 0 to 255.

Returns: nothing.

Since: 3.00 See also: spriteSetAlpha, spriteSetBlend

Example
-- A ring of balls, each its own color, from one white picture.
for i = 1, 12 do
    local hue = i / 12
    spriteSetTint(ball, 128 + 127 * math.sin(hue * 6.28), 128 + 127 * math.sin(hue * 6.28 + 2.1), 128 + 127 * math.sin(hue * 6.28 + 4.2))
    spriteDraw(ball, 320 + math.cos(hue * 6.28) * 150, 240 + math.sin(hue * 6.28) * 150, true)
end
spriteSetTint(ball, 255, 255, 255)

2.39.33. spriteUnload

spriteUnload(id)

Frees the sprite: the source image, the transformed copy if one exists, and all animation frames. The handle is invalid afterward and any further use ends the script with an error. Sprites made by fontToSprite are released the same way. Sprites still loaded when the game ends are freed by the engine, but games that create sprites during play (text re-rendered as scores change, for instance) must unload the old ones or memory grows without bound.

Since: 2.00 See also: spriteLoad, fontToSprite, onShutdown

Example
-- Re-render the score only when it changes, releasing the previous sprite.
function updateScoreSprite()
    if scoreSprite ~= nil then
        spriteUnload(scoreSprite)
    end
    scoreSprite = fontToSprite("SCORE " .. score)
end

function onShutdown()
    spriteUnload(scoreSprite)
    spriteUnload(cabinetSprite)
end

2.40. Subtitle

SubRip subtitles over the disc picture. A game loads a .srt with srtLoad, switches it on with srtEnable, and the engine puts each cue up and takes it down again as the disc reaches it. See Subtitles for the file format, the timing and how to restyle them.

The subtitles and overlayBanner share one shipped document, Singe/subtitle.rml, styled by Singe/subtitle.rcss; a game that wants another look ships its own subtitle.rml beside its script, and Singe uses that instead (see Subtitles). Both are drawn over the picture, above the overlay and below the screen space GUIs, and they take no mouse input.

2.40.1. srtClear

srtClear()

Hypseus extension. Takes whatever is on screen off at once — a cue or a banner — and leaves the loaded cues and the enabled state alone. The cue that was showing stays off until the disc reaches the next one; nothing has to be reloaded and nothing has to be switched back on.

Parameters: none.

Returns: nothing.

Since: 3.00, as a Hypseus Singe extension. See also: srtEnable, overlayBanner

Example
-- A cutscene ends early; drop the line that was still up.
srtClear()

2.40.2. srtEnable

srtEnable(enabled)

Hypseus extension. Whether the loaded cues are shown as the disc plays. Switching it off takes any cue that is showing off with it; switching it on again puts up whatever cue covers the frame the disc is on. A script starts with subtitles off, so a game that loads them must switch them on.

A non-boolean argument terminates the script.

Parameters:

  • enabled — boolean.

Returns: nothing.

Since: 3.00, as a Hypseus Singe extension. See also: srtLoad, srtClear

Example
srtEnable(SETTINGS.subtitles)

2.40.3. srtLoad

loaded = srtLoad(filename)

Hypseus extension. Reads a SubRip file through the virtual file system and turns its timestamps into disc frames at the disc’s own frame rate. Loading replaces whatever was loaded before; srtEnable then shows it.

It answers false, having loaded nothing, when the file cannot be read, when it holds no cue that parses, or when there is no disc to time it against — so a malformed file is a false, not a crash. A warning naming the file is printed in every one of those cases. Cues that do not parse inside an otherwise good file are skipped, as Hypseus skips them.

Because the timestamps become frame numbers when the file is loaded, and the frame number is what the engine matches, a cue is found again wherever the disc is sent: a search, a skip or a step lands on the right line at once.

Parameters:

  • filename — string; a path the virtual file system can reach.

Returns: boolean, whether any cue was loaded.

Since: 3.00, as a Hypseus Singe extension. See also: srtEnable, srtPosition, Subtitles

Example
if srtLoad("subs/" .. language .. ".srt") then
    srtEnable(true)
end

2.40.4. srtLoadTrack

loaded = srtLoadTrack(track)

The same as srtLoad, except that the subtitles come from inside the disc’s own container rather than from a .srt file beside it. Everything after loading is identical: the cues become disc frame numbers at the disc’s frame rate, so they are found again after any seek, and srtEnable, srtPosition and srtClear work the same.

The whole file is walked once to collect the track, decoding no pictures, so a long disc takes a moment — do it while something else is on screen rather than between two frames of gameplay.

A track that holds pictures rather than words (VobSub or PGS) cannot be read: it answers false, as an unreadable .srt does, and leaves the subtitles cleared. So does a track number that names nothing, and so does a game with no disc.

Parameters:

  • track — number; 0 to discGetSubtitleTracks() - 1.

Returns: true when at least one cue was read.

Since: 3.00. See also: srtLoad, discGetSubtitleTracks, srtEnable

Example
-- Subtitles the rip carried, with a .srt beside the game as the fallback.
if discGetSubtitleTracks() > 0 then
    srtLoadTrack(0)
else
    srtLoad(DIR .. "subtitles.srt")
end
srtEnable(true)

2.40.5. srtPosition

srtPosition(percent)

Hypseus extension. Where a subtitle sits, as a percent down the picture, from 1 to 95. The default is 80. A number outside that range is ignored, as Hypseus ignores it, rather than being clamped or refused.

The height applies to the cue on screen straight away and to every cue after it. overlayBanner carries its own height and is not affected.

Parameters:

  • percent — number; 1 to 95.

Returns: nothing.

Since: 3.00, as a Hypseus Singe extension. See also: srtLoad, Subtitles

Example
-- Keep the lines clear of the scoreboard along the bottom.
srtPosition(70)

2.41. Online High Scores

A game posts a score in one line:

scoreSubmit(playerScore)

Everything else was set up once, in the menu: which service, which account, and what name the player appears under (see Online: accounts, games and scores). A game needs only a GAME_ID in its games.dat entry — a UUID, which is what the board is kept under. See singeGetGameId for the format.

Call What it does

scoreBegin()

Say a play is starting. Optional, and worth calling: see below.

scoreSubmit(value [, board [, meta]])

Queue a score. Returns false if the cabinet is not signed in or the game has no GAME_ID.

scoreLowestWins([board])

Say a board ranks the lowest score first. Call it before the board’s first score.

scoreBoard(onDone [, board])

Fetch the board. onDone(ok, result) with result.top (a list of {name, value}), result.standing (this player’s value, rank and the number of players), and result.order, "highest" or "lowest", the way the board ranks. A cabinet that is not signed in can fetch it too: see below.

scorePlayerName()

The name this cabinet posts under, or nil if none has been chosen.

scoreSignedIn()

Whether this cabinet is signed in to an online account.

scoreWaiting()

How many scores are queued and not yet sent.

scoreUpdate()

Once a frame, from onOverlayUpdate. Nothing progresses without it.

scoreGameId()

The game’s GAME_ID from its games.dat entry, or nil when it has none. A game without one can be played but not ranked.

A score is queued, not sent. It is written to disk and handed to the service when there is a connection, because a cabinet is often offline and a game must never stall on the wire to show its own board. A queued score survives the machine being switched off.

Anyone can read a board. A cabinet that is not signed in still fetches the board of a game the service offers to everyone, with no standing because there is no player to stand anywhere, so a game can show what it would be posting to and ask the player to sign in. scoreSignedIn() tells the two apart: a cabinet that is signed in but has not chosen a name also has no scorePlayerName(), and asking it to sign in would be wrong. A game the service keeps for particular accounts has no board for a cabinet that is not signed in to one of them; the fetch fails as it would for a game the service does not know. Posting always needs an account.

A game can have more than one board. Pass a board name to keep each play mode apart — a time attack separate from a points total, easy separate from hard — and read it back with the same name. Boards are kept apart by the script that is running as well: without a name, a score goes on the board named for the script, its file name without the extension, so Collection/Raid.singe posts to raid; with one, the script’s name comes first, so scoreSubmit(points, "hard") from that script posts to raid.hard. Every title in a .game carries the same GAME_ID, and this is what keeps the games of a collection on boards of their own even when two of them name their modes alike, while one game listed twice (in two languages, say: two games.dat entries, one script) keeps a single set. Board names are lower case and hold letters, digits, -, _ and .; anything else becomes -. The whole name is at most 32 characters, and the script’s part is shortened first so the mode’s name survives.

A board can rank the lowest score first. Strokes, deaths, seconds: some games count what a player wants less of. Call scoreLowestWins with the board’s name, as scoreSubmit takes it, before the board’s first score, and every score sent to that board and every fetch of it go that way. A board’s first score fixes its direction for good, so no board is ever ranked both ways: a score sent the other way afterwards is refused, and the queue drops it rather than try it again. On a board like this zero is a score, and so is a number below zero, a round under par.

Example
-- A golf game:  the fewest strokes win, and par is a board of its own.
scoreLowestWins("strokes")
scoreLowestWins("par")

function roundOver(strokes, coursePar)
    scoreSubmit(strokes, "strokes")
    scoreSubmit(strokes - coursePar, "par")    -- -2 is two under
end

The name on a board is a handle, never an address. It is chosen in the Online Account tool, kept apart from the account, and is the only thing about a player that other players see. Three to twenty characters of letters, digits, hyphens and underscores, starting and ending with a letter or digit — no spaces, no dots, and no @, so a handle cannot even look like an email address. Case is ignored for uniqueness, so Ann and ANN are one name.

A handle is chosen once. Renaming freely would mean a leaderboard’s history is not really anyone’s, so a player cannot change one afterwards, and an email address cannot be changed at all.

A handle nobody should claim (admin, staff), or one with words that have no place on a screen in a public room, is refused when it is chosen. A score is refused until a name has been chosen, because a score with nobody’s name on it is not on a board in any useful sense.

What a score means. The cabinet is the player’s machine, so a submitted score is a claim — nothing the client can do makes it more than that, and signing it with a secret shipped in the client would only look like security. So nothing here pretends to verify one, and a game should not be written as though something else will.

scoreBegin() is worth calling for the one thing that is not a claim. Call it when a play starts; the score that follows carries how long the play took, as timed at the other end rather than on this machine. That number has not been through the player’s machine, which is what makes it worth having.

Nothing is rejected on it, so calling it costs a game one line and can never turn a legitimate score away. A cabinet that is offline when a play starts simply records no time, which is honest rather than broken.

Example
function startLevel()
    scoreBegin()          -- the timing starts now, at the other end
    ...
end
Example
-- At the end of a game, post the score and then show where it landed.
function gameOver(points)
    scoreSubmit(points)
    scoreBoard(function(ok, board)
        if not ok then
            showMessage("Not signed in; score kept for later.")
            return
        end
        for place, row in ipairs(board.top) do
            showLine(place .. ". " .. row.name .. "  " .. row.value)
        end
    end)
end

function onOverlayUpdate()
    scoreUpdate()
    return OVERLAY_UPDATED
end

2.42. Stats

The developer’s overlay, in the top left corner: how long the frame took and its worst over the last two seconds, the frame rate, Lua’s memory, how many sprites, sounds and timers are alive, how many of the scene’s nodes were drawn and in how many batches, how much texture memory it is holding, and what the disc is doing.

It is drawn with SDL’s own debug font, so it needs no font file, no asset and no GUI document, and it appears even on a machine where the 3D device never came up. It is drawn after singeScreenshot takes its picture, so it never lands in a screenshot.

Leave it off in a shipped game. Nothing stops you putting it behind a key in your own service menu.

2.42.1. statsEnable

statsEnable(enabled)

Shows or hides the overlay. While it is shown the picture is redrawn every frame, so the numbers keep moving even when nothing else on screen does.

Parameters:

  • enabled — boolean.

Returns: nothing.

Since: 3.00. See also: statsIsEnabled

Example
-- A developer key, behind a flag so the shipped game has no such key.
function onInputPressed(key)
    if DEVELOPER and key == SWITCH_SERVICE then
        statsEnable(not statsIsEnabled())
    end
end

2.42.2. statsIsEnabled

shown = statsIsEnabled()

Whether the overlay is on.

Parameters:

  • None.

Returns: true or false.

Since: 3.00.

2.43. Terrain

Heightmap ground made with meshHeightmap, which turns a grayscale image into a mesh one vertex per pixel; terrainGetHeight reads that mesh back through the node carrying it. Positions and heights are in world units, and the node’s position and scale are taken into account. See Terrain in 3D Scenes.

2.43.1. terrainGetHeight

height = terrainGetHeight(node, x, z)

The world height of the heightmap mesh on node at world x, z, interpolated between the nearest four samples, or nil beyond its edges or when the node’s mesh is not a heightmap. The node’s world position and scale count; its rotation is ignored, since terrains lie flat. Use it for placing trees, spawning things on the ground, or a camera that follows the surface, without the cost of a ray cast. Ends the script for a node handle that is not valid.

Parameters:

  • node — the node whose mesh came from meshHeightmap.

  • x, z — the world position to sample.

Returns: A number, or nil off the terrain.

Since: 3.00. See also: meshHeightmap, physicsRaycast, nodeSetPosition

Example
-- Trees on the hills, and a camera that never dips below the ground.
for i = 1, 40 do
    local x = math.random(-50, 50)
    local z = math.random(-50, 50)
    local tree = modelInstance(treeModel)
    nodeSetPosition(tree, x, terrainGetHeight(hills, x, z) or 0, z)
end

function onOverlayUpdate()
    local cx, cy, cz = nodeGetWorldPosition(camera)
    local ground = terrainGetHeight(hills, cx, cz)
    if ground and cy < ground + 1.5 then
        nodeSetPosition(camera, cx, ground + 1.5, cz)
    end
    return OVERLAY_UPDATED
end

2.44. Timer

Something to happen later, without counting frames yourself. Timers run on the engine’s clock, which is the virtual one under --deterministic, so a timed game repeats exactly between runs. They fire with the rest of the frame’s callbacks, on the same thread as everything else — there is nothing to lock and nothing that can fire while your script is halfway through something.

A timer that has fallen behind — a long load, a breakpoint — fires once when the game catches up rather than firing the twenty times it missed.

Everything is forgotten when the script reloads, so a timer from the last run never fires into the next one.

2.44.1. timerAfter

id = timerAfter(milliseconds, function)

Calls the function once, later. The function is given the timer’s own id, so one function can serve several timers.

Parameters:

  • milliseconds — number; zero or less fires on the next frame.

  • function — called as function(id).

Returns: a number; the timer’s id.

Since: 3.00. See also: timerCancel, timerEvery

Example
-- Let the explosion finish before the game over screen.
soundPlay(bang)
timerAfter(1500, function()
    showGameOver()
end)

2.44.2. timerCancel

timerCancel(id)

Stops a timer. Canceling one that has already fired is not an error, so nothing has to check first.

Parameters:

  • id — number; from timerAfter or timerEvery.

Returns: nothing.

Since: 3.00.

2.44.3. timerEvery

id = timerEvery(milliseconds, function)

Calls the function over and over until it is canceled.

Parameters:

  • milliseconds — number; how long between calls.

  • function — called as function(id).

Returns: a number; the timer’s id.

Since: 3.00. See also: timerCancel

Example
-- Tick the countdown once a second, and stop it when it runs out.
local left = 30
local clock
clock = timerEvery(1000, function()
    left = left - 1
    if left <= 0 then
        timerCancel(clock)
        outOfTime()
    end
end)

2.44.4. timerIsActive

running = timerIsActive(id)

Whether the timer will fire again: true for a repeating one until it is canceled, false for a one shot that has already gone off.

Parameters:

  • id — number.

Returns: true or false.

Since: 3.00.

2.45. Tween

Moving a number from one value to another over time, on a curve. Fades, slides, camera moves, a health bar draining, a menu sliding in — all the same thing.

tweenValue hands you the number and lets you decide what it means. That is deliberate: the engine has nodes, sprites, GUI elements, materials and lights, and a tween that knew about each of them would be five sets of calls to keep in step. One that hands over a number is none, and it works on things the engine has never heard of.

The easings are the usual ones. EASE_LINEAR is no curve at all; EASE_QUAD_*, EASE_CUBIC_*, EASE_SINE_* and EASE_EXPO_* run from gentle to sharp; EASE_BACK_* overshoots and comes back; EASE_ELASTIC_* springs; EASE_BOUNCE_* drops and bounces. Each comes in _IN (slow at the start), _OUT (slow at the end) and _IN_OUT (both).

2.45.1. tweenCancel

tweenCancel(id)

Stops a tween where it is. Neither function is called again, and the value stays wherever it had reached.

Parameters:

  • id — number; from tweenValue.

Returns: nothing.

Since: 3.00.

2.45.2. tweenIsActive

running = tweenIsActive(id)

Whether the tween is still running.

Parameters:

  • id — number.

Returns: true or false.

Since: 3.00.

2.45.3. tweenValue

id = tweenValue(from, to, milliseconds, easing, onUpdate [, onDone])

Moves a number from from to to over milliseconds, calling onUpdate(value, progress) every frame — progress runs 0 to 1 and ignores the curve — and onDone() once at the end. The last onUpdate always lands exactly on to, so nothing finishes a pixel short.

Parameters:

  • from, to — numbers.

  • milliseconds — number; zero or less arrives on the next frame.

  • easing — one of the EASE_ values.

  • onUpdate — called as function(value, progress).

  • onDone — optional; called with no arguments when it finishes.

Returns: a number; the tween’s id.

Since: 3.00. See also: tweenCancel

Example
-- Slide the title in and fade the overlay up at the same time.
tweenValue(-200, 40, 600, EASE_BACK_OUT, function(x)
    titleX = x
end)

tweenValue(0, 255, 600, EASE_SINE_OUT, function(alpha)
    setOverlayOpacity(math.floor(alpha))
end, function()
    startAttractLoop()
end)

2.46. Vehicle

Cars, motorcycles, tanks and boats built on a chassis body (see Physics, Vehicles and Water). A vehicle has no handle of its own: it is addressed by its chassis node, which must already carry a BODY_DYNAMIC body from bodyNew, and a node without a vehicle terminates the script in every call after vehicleNew. The chassis faces -Z with Y up; distances are world units, forces newtons, torques newton meters and engine speeds revolutions a minute. Every tuning call marks the vehicle for a rebuild at the next physics step, around the wheel positions recorded when the wheels were added. Up to 16 vehicles at once, each with up to 16 wheels.

2.46.1. vehicleNew

vehicleNew(node, kind)

Turns the dynamic body on node into the chassis of a vehicle. A car, motorcycle or tank needs at least two wheels from vehicleAddWheel before the next physics step builds it; a boat has no wheels and is pushed by a propeller that only works under a surface made with bodySetWater. The new vehicle starts from the defaults: a 500 Nm engine peaking at 6000 rpm and idling at 1000, Jolt’s five-speed automatic gearbox, 35 degrees of steering lock, 1500 Nm brakes and a 4000 Nm hand brake, 1.5 Hz suspension at 0.5 damping and no anti-roll bars. Calling it again on the same node discards the old vehicle and its wheels first. Ends the script for an unknown kind, a node whose body is not dynamic, a wheeled kind in a 2D world, or when 16 vehicles already exist.

Parameters:

  • node — the chassis node, carrying a BODY_DYNAMIC body.

  • kind — VEHICLE_CAR (any number of axles), VEHICLE_MOTORCYCLE (two wheels in line, leaning through turns), VEHICLE_TANK (wheels on two tracks, turning on the spot) or VEHICLE_BOAT (a buoyant hull with a propeller and a rudder).

Example
local car = nodeNew()
nodeSetMesh(car, meshBox(1.8, 0.5, 4.0), paint)
nodeSetPosition(car, 0, 0.9, 0)
bodyNew(car, BODY_DYNAMIC, SHAPE_BOX, 1.8, 0.5, 4.0)
bodySetMass(car, 1500)
vehicleNew(car, VEHICLE_CAR)
for _, p in ipairs({ { -0.95, -0.2, -1.4 }, { 0.95, -0.2, -1.4 }, { -0.95, -0.2, 1.4 }, { 0.95, -0.2, 1.4 } }) do
    local hub = nodeNew()
    nodeSetParent(hub, car)
    nodeSetPosition(hub, p[1], p[2], p[3])
    vehicleAddWheel(car, hub, 0.35, 0.25, 0.4)
end

2.46.2. vehicleDelete

vehicleDelete(node)

Removes the vehicle from its chassis: the wheel constraint, the driver input and all the tuning. The body stays an ordinary dynamic body, so a wreck keeps sliding and tumbling, and the wheel nodes stay where the last step posed them; nothing moves them again unless the script does. A node without a vehicle terminates the script.

Since: 3.00. See also: vehicleNew, bodyDelete

Example
function onCollision(a, b, x, y, z, speed)
    if (a == car or b == car) and speed > 25 and not wrecked then
        wrecked = true
        vehicleDelete(car)                    -- The chassis tumbles on as a body
        soundPlay(crashSound)
        emitterStart(smoke)
    end
end

2.46.3. vehicleAddWheel

index = vehicleAddWheel(node, wheelNode, radius, width, suspension)

Adds a wheel to the vehicle where wheelNode stands relative to the chassis when the vehicle is next built. The suspension hangs the wheel suspension units below that point when unloaded and compresses to half that. From then on the engine writes the wheel node’s world transform after every step, with X as the axle and Y up, so the visible tire belongs on a child node: a meshCylinder turned 90 degrees about Z. Wheels ahead of the average wheel position along the nose count as front wheels: they steer by default and carry no hand brake. A tank sorts its wheels onto the left or right track by which side of the chassis they sit on and needs at least one on each side. Values below 0.001 are raised to it. Ends the script at the 17th wheel.

Parameters:

  • node — the chassis node.

  • wheelNode — the node the wheel hangs from; its position relative to the chassis is the attachment point, and the engine poses it from now on.

  • radius — the wheel’s radius, in world units.

  • width — the wheel’s width, in world units.

  • suspension — the suspension’s length at full extension, in world units; it compresses to half.

Returns: The wheel’s index, from 0, for vehicleSetWheel, vehicleIsWheelOnGround and vehicleGetWheelSlip.

Notes: A vehicle is only built once it has two wheels, and a car or motorcycle also needs a driven wheel; until then it sits as a plain body and the drive calls do nothing.

Since: 3.00. See also: vehicleSetWheel, vehicleSetSuspension, nodeFind

Example
-- The truck model carries empty nodes named for its wheels.
local truck  = modelInstance(truckModel)
local wheels = {}
nodeSetPosition(truck, 0, 1.2, -8)
bodyNew(truck, BODY_DYNAMIC, SHAPE_BOX, 2.4, 1.4, 6.0)
bodySetMass(truck, 4000)
vehicleNew(truck, VEHICLE_CAR)
for i, name in ipairs({ "wheelFL", "wheelFR", "wheelRL", "wheelRR" }) do
    wheels[i] = vehicleAddWheel(truck, nodeFind(name, truck), 0.5, 0.35, 0.45)
end

2.46.4. vehicleSetThrust

vehicleSetThrust(node, maxForce, x, y, z)

Sets a boat’s propeller: the force it pushes with at full throttle, default 2000 newtons, and the point in the hull’s frame it pushes at, default 0, -0.2, 1, just below the deck at the stern. The push is along the hull’s nose and only happens while that point is under a water surface; the same point decides whether the rudder and the brake act. A negative force becomes 0. Wheeled kinds store the values and ignore them.

Parameters:

  • node — the hull node.

  • maxForce — the push at full throttle, in newtons.

  • x, y, z — where the propeller sits, in the hull’s frame; the stern is +Z.

Since: 3.00. See also: vehicleSetRudder, bodySetWater, bodySetBuoyancy

Example
local raft = nodeNew()
nodeSetMesh(raft, meshBox(1.6, 0.3, 2.4), wood)
nodeSetPosition(raft, 1, 0.3, 4)
bodyNew(raft, BODY_DYNAMIC, SHAPE_BOX, 1.6, 0.3, 2.4)
bodySetMass(raft, 120)
bodySetBuoyancy(raft, 3.0)                    -- Rides high on the pool
vehicleNew(raft, VEHICLE_BOAT)
vehicleSetThrust(raft, 600, 0, -0.1, 1.2)     -- An outboard hung off the stern
vehicleSetRudder(raft, 300)

2.46.5. vehicleSetWheel

vehicleSetWheel(node, index, steered, driven)

Says whether one wheel turns with the steering input and whether the engine drives it, replacing the defaults for that wheel: front wheels steer, and every wheel drives except a motorcycle’s front one. Driven wheels pair up across the chassis into differentials, one per axle, and the engine’s torque is shared equally between the axles; a driven wheel with no partner is an axle of its own. A tank ignores both flags, since its tracks drive every wheel and turn the hull. Takes effect at the next step’s rebuild. Ends the script for an index the vehicle has no wheel for.

Parameters:

  • node — the chassis node.

  • index — the wheel’s index from vehicleAddWheel.

  • steered — true for the wheel to turn up to vehicleSetSteering at full lock.

  • driven — true for the engine to turn it.

Example
-- A rear-wheel drive sports car:  the front wheels only steer.
vehicleSetWheel(car, wheels[1], true, false)
vehicleSetWheel(car, wheels[2], true, false)
vehicleSetWheel(car, wheels[3], false, true)
vehicleSetWheel(car, wheels[4], false, true)
if fourWheelSteer then
    vehicleSetWheel(car, wheels[3], true, true)
    vehicleSetWheel(car, wheels[4], true, true)
end

2.46.6. vehicleSetEngine

vehicleSetEngine(node, maxTorque, maxRpm)
vehicleSetEngine(node, maxTorque, maxRpm, minRpm)

Sets the engine: peak torque in newton meters, the redline and the idle speed in revolutions a minute. Defaults are 500, 6000 and 1000, and the idle is 1000 again when it is left out. The torque is kept at 1 or more, the redline at 100 or more and the idle between 1 and the redline. A boat has no engine and ignores the call. Takes effect at the next step’s rebuild.

Parameters:

  • node — the chassis node.

  • maxTorque — peak torque, in newton meters.

  • maxRpm — the redline, in revolutions a minute.

  • minRpm — the idle speed, in revolutions a minute; default 1000.

Since: 3.00. See also: vehicleSetGears, vehicleGetRpm

Example
vehicleSetEngine(tank, 1500, 4000, 800)       -- A diesel:  torque low down
vehicleSetEngine(bike, 150, 9000, 1200)       -- A screamer

function onOverlayUpdate()
    local rpm = vehicleGetRpm(bike)
    overlayClear()
    fontPrint(20, 20, string.format("%5.0f rpm", rpm))
    if rpm > 8500 then
        spriteDraw(shiftLight, 200, 20)       -- Time to change up
    end
    return OVERLAY_UPDATED
end

2.46.7. vehicleSetGears

vehicleSetGears(node, { ratio, ... })
vehicleSetGears(node, { ratio, ... }, reverseRatio)
vehicleSetGears(node, { ratio, ... }, reverseRatio, automatic)

Sets the gearbox: one to eight forward ratios, first gear first, the reverse ratio (default 2.9, given as a positive number) and whether the box shifts by itself (default true). A vehicle that never gets this call runs Jolt’s five-speed, 2.66, 1.78, 1.3, 1.0 and 0.74, with the same reverse. With automatic false the box no longer shifts on its own, and there is no call to shift it from script. A boat has no gearbox and ignores the call. Takes effect at the next step’s rebuild. Ends the script when the table is empty or holds more than eight ratios.

Parameters:

  • node — the chassis node.

  • { ratio, …​ } — forward gear ratios, engine turns per gearbox turn, first gear first; one to eight of them.

  • reverseRatio — the reverse gear’s ratio; default 2.9.

  • automatic — true (default) for the box to shift by itself.

Since: 3.00. See also: vehicleGetGear, vehicleSetEngine

Example
-- A close-ratio six-speed for the race car, a tall three-speed for the bus.
vehicleSetGears(raceCar, { 3.2, 2.3, 1.8, 1.4, 1.1, 0.9 }, 3.0)
vehicleSetGears(bus, { 2.4, 1.3, 0.8 })

function onOverlayUpdate()
    overlayClear()
    fontPrint(20, 20, string.format("Gear %d  %.0f rpm", vehicleGetGear(raceCar), vehicleGetRpm(raceCar)))
    return OVERLAY_UPDATED
end

2.46.8. vehicleSetRudder

vehicleSetRudder(node, maxTorque)

Sets a boat’s rudder: the torque about the hull’s up axis at full steering input, default 800 newton meters. The rudder bites with speed, a fifth of the torque at rest and all of it from 3 world units a second, and it turns the other way while the boat moves astern. It only acts while the propeller point is under water. A negative torque becomes 0; wheeled kinds ignore the call.

Since: 3.00. See also: vehicleSetThrust, vehicleDrive

Example
vehicleNew(patrolBoat, VEHICLE_BOAT)
vehicleSetThrust(patrolBoat, 4000, 0, -0.4, 3.5)
vehicleSetRudder(patrolBoat, 2500)            -- Heavy hull, big rudder

function onOverlayUpdate()
    local helm = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_X) / 32767
    local gas  = controllerGetAxis(0, GAMEPAD_AXIS_RIGHT_TRIGGER) / 32767
    vehicleDrive(patrolBoat, gas, helm, 0)
    return OVERLAY_NOT_UPDATED
end

2.46.9. vehicleSetSuspension

vehicleSetSuspension(node, frequency, damping)

Sets every wheel’s spring: its natural frequency in hertz (default 1.5, kept at 0.1 or more; stiffer is higher) and its damping ratio (default 0.5; 0 bounces, 1 settles without overshoot). Takes effect at the next step’s rebuild, on every wheel at once; there is no per-wheel spring. A boat has no suspension and ignores the call.

Parameters:

  • node — the chassis node.

  • frequency — the spring’s natural frequency, in hertz.

  • damping — the damping ratio, 0 upward.

Since: 3.00. See also: vehicleAddWheel, vehicleSetAntiRoll

Example
-- The buggy floats over the dunes; the race car barely moves on its springs.
vehicleSetSuspension(buggy, 1.0, 0.3)
vehicleSetSuspension(raceCar, 3.0, 0.7)
if surface == "gravel" then
    vehicleSetSuspension(raceCar, 2.0, 0.5)
end

2.46.10. vehicleSetSteering

vehicleSetSteering(node, maxDegrees)

Sets how far the steered wheels turn at full lock, in degrees; default 35, clamped to 0 through 89. A steering input of -1 or 1 from vehicleDrive reaches this angle, and smaller inputs a proportion of it. Takes effect at the next step’s rebuild. A tank turns by its tracks and a boat by its rudder, so both ignore the call.

Since: 3.00. See also: vehicleSetWheel, vehicleDrive

Example
-- The go-kart turns on a dime; the truck needs a wide arc.
vehicleSetSteering(kart, 45)
vehicleSetSteering(truck, 25)
vehicleSetSteering(bus, 20)
if difficulty == "arcade" then
    vehicleSetSteering(truck, 35)             -- Forgiving handling
end

2.46.11. vehicleSetBrakes

vehicleSetBrakes(node, brakeTorque, handBrakeTorque)

Sets the brake torque every wheel can apply at full pedal, default 1500 newton meters, and the hand brake torque on the rear wheels, default 4000; the front wheels, those ahead of the average wheel position, have no hand brake. Negative values become 0. A tank brakes its tracks with Jolt’s track defaults and ignores the call, and a boat brakes by dragging against its own velocity, so it ignores the call too. Takes effect at the next step’s rebuild.

Parameters:

  • node — the chassis node.

  • brakeTorque — foot brake torque on every wheel, in newton meters.

  • handBrakeTorque — hand brake torque on the rear wheels, in newton meters.

Since: 3.00. See also: vehicleDrive, vehicleGetWheelSlip

Example
vehicleSetBrakes(car, 2200, 6000)             -- Race pads and a drift-ready hand brake

function onOverlayUpdate()
    local brake     = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_TRIGGER) / 32767
    local handBrake = controllerGetButton(0, GAMEPAD_0.BUTTON_B.value) and 1 or 0
    vehicleDrive(car, throttle(), steering(), brake, handBrake)
    return OVERLAY_NOT_UPDATED
end

2.46.12. vehicleSetAntiRoll

vehicleSetAntiRoll(node, stiffness)

Adds an anti-roll bar across each axle, in newtons a meter; 0 (default) fits none and a negative value becomes 0. A bar joins the two driven wheels of an axle, so an axle whose wheels do not drive gets no bar, and a motorcycle has none. A few hundred keeps a car flat in corners; too much lifts the inside wheels. A tank ignores the call. Takes effect at the next step’s rebuild.

Since: 3.00. See also: vehicleSetSuspension, vehicleSetWheel

Example
local car = nodeNew()
nodeSetMesh(car, meshBox(1.8, 0.5, 4.0), paint)
nodeSetPosition(car, 0, 0.9, 0)
bodyNew(car, BODY_DYNAMIC, SHAPE_BOX, 1.8, 0.5, 4.0)
bodySetMass(car, 1500)
vehicleNew(car, VEHICLE_CAR)
addFourWheels(car)
vehicleSetEngine(car, 600, 6500, 1000)
vehicleSetAntiRoll(car, 800)                  -- Stays flat through the chicane

2.46.13. vehicleDrive

vehicleDrive(node, forward, right)
vehicleDrive(node, forward, right, brake)
vehicleDrive(node, forward, right, brake, handBrake)

Sets the driver’s input, which holds until the next call, so call it every frame from onOverlayUpdate. Throttle and steering run -1 to 1, brake and hand brake 0 to 1; values outside are clamped and inputs left out are 0. A car or motorcycle gets all four as Jolt’s driver input, a negative throttle reversing through the reverse gear. A tank takes forward as its throttle and right slows the inside track; with no throttle the tracks run against each other so the hull pivots on the spot, and the hand brake is ignored. A boat takes forward as the propeller’s throttle, right as the rudder and brake as a drag against the hull’s velocity, ignores the hand brake, and does nothing at all while the propeller is out of the water. Any non-zero input wakes a chassis that has gone to sleep.

Parameters:

  • node — the chassis node.

  • forward — throttle, -1 to 1; negative reverses.

  • right — steering, -1 (left) to 1 (right).

  • brake — foot brake, 0 to 1; default 0.

  • handBrake — hand brake, 0 to 1; default 0.

Example
function onOverlayUpdate()
    local stick     = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_X)
    local steer     = (math.abs(stick) > SINGE_DEAD_ZONE) and stick / 32767 or 0
    local gas       = controllerGetAxis(0, GAMEPAD_AXIS_RIGHT_TRIGGER) / 32767
    local brake     = controllerGetAxis(0, GAMEPAD_AXIS_LEFT_TRIGGER) / 32767
    local handBrake = controllerGetButton(0, GAMEPAD_0.BUTTON_B.value) and 1 or 0
    if controllerGetButton(0, GAMEPAD_0.BUTTON_A.value) then
        gas = -gas                             -- Reverse while A is held
    end
    vehicleDrive(car, gas, steer, brake, handBrake)
    return OVERLAY_NOT_UPDATED
end

2.46.14. vehicleGetSpeed

speed = vehicleGetSpeed(node)

The chassis body’s velocity along its nose, in world units a second, negative while it moves astern; sideways motion in a drift does not count. Works for every kind, boats included, from the moment vehicleNew is called.

Returns: A number.

Since: 3.00. See also: vehicleGetRpm, vehicleGetGear, bodyGetVelocity

Example
function onOverlayUpdate()
    local speed = vehicleGetSpeed(car)
    overlayClear()
    fontPrint(20, 20, string.format("%3.0f km/h", math.abs(speed) * 3.6))
    if speed < -1 then
        spriteDraw(reversingLamp, 300, 20)
    end
    return OVERLAY_UPDATED
end

2.46.15. vehicleGetRpm

rpm = vehicleGetRpm(node)

The engine’s speed in revolutions a minute, between the idle and the redline from vehicleSetEngine, for a rev counter or the pitch of an engine loop. 0 for a boat, which has no engine, and for a vehicle that has not been built yet because it lacks wheels.

Returns: A number.

Since: 3.00. See also: vehicleSetEngine, vehicleGetGear

Example
-- A rev counter bar that turns red past 6000.
function onOverlayUpdate()
    local rpm = vehicleGetRpm(car)
    overlayClear()
    if rpm > 6000 then
        colorForeground(255, 40, 40)
    else
        colorForeground(60, 220, 60)
    end
    overlayBox(20, 20, 20 + math.floor(rpm / 6500 * 200), 32)
    return OVERLAY_UPDATED
end

2.46.16. vehicleGetGear

gear = vehicleGetGear(node)

The gear the box has engaged: 0 in neutral, -1 in reverse, 1 upward for the forward gears in the order vehicleSetGears gave them. 0 for a boat and for a vehicle that has not been built yet.

Returns: An integer.

Since: 3.00. See also: vehicleSetGears, vehicleGetRpm

Example
local lastGear = 0

function onOverlayUpdate()
    local gear = vehicleGetGear(car)
    if gear ~= lastGear then
        soundPlay(gearChange)
        lastGear = gear
    end
    overlayClear()
    fontPrint(20, 20, (gear == -1) and "R" or ((gear == 0) and "N" or tostring(gear)))
    return OVERLAY_UPDATED
end

2.46.17. vehicleIsWheelOnGround

touching = vehicleIsWheelOnGround(node, index)

Whether that wheel’s suspension cast found anything to press against this step. false for an index the vehicle has no wheel for and for a vehicle that has not been built yet; no error is raised for either.

Returns: True or false.

Since: 3.00. See also: vehicleAddWheel, vehicleGetWheelSlip

Example
-- Airborne when no wheel touches; a landing after a jump shakes the camera.
function onOverlayUpdate()
    local airborne = true
    for i = 0, 3 do
        airborne = airborne and not vehicleIsWheelOnGround(car, i)
    end
    if wasAirborne and not airborne then
        cameraShake = 12
    end
    wasAirborne = airborne
    return OVERLAY_NOT_UPDATED
end

2.46.18. vehicleGetWheelSlip

slip = vehicleGetWheelSlip(node, index)

How much the wheel spins or skids along its rolling direction, 0 gripping to 1 spinning or locked, for tire squeal, smoke and skid marks. Always 0 for a tank’s wheels, for an index the vehicle has no wheel for, and for a vehicle that has not been built yet.

Returns: A number.

Since: 3.00. See also: vehicleIsWheelOnGround, vehicleGetSpeed

Example
function onOverlayUpdate()
    local slip = math.max(vehicleGetWheelSlip(car, 2), vehicleGetWheelSlip(car, 3))
    if slip > 0.4 and vehicleIsWheelOnGround(car, 2) then
        emitterStart(tireSmoke)
        if not soundIsPlaying(squealChannel) then
            squealChannel = soundPlay(squeal)
        end
    else
        emitterStop(tireSmoke)
    end
    return OVERLAY_NOT_UPDATED
end

2.47. View

A view is a second camera rendered to a texture every frame, for a monitor, a mirror or a portal in the scene: viewNew makes one and returns an integer handle, viewSetCamera points it at a node, and materialSetView shows it on a material. Up to four exist at once; each renders the whole scene again at its own size, in overlay-independent pixels, with the main camera’s projection, the frame’s shadows (a directional light’s cascades included: each point takes the finest cascade that covers it) and no bloom, so keep them few and small. Every view turns billboards (nodeSetBillboard) to its own camera and sorts blended draws back to front from it, so a view whose camera looks from elsewhere still sees billboards face on and transparent objects in the right order. A bad handle ends the script. See 3D Scenes.

2.47.1. viewDelete

viewDelete(view)

Frees the view and its textures, and stops the extra render pass it cost. Materials showing it go back to their own texture. The handle is invalid afterwards and ends the script if used again; since only four views exist at once, delete the ones a level no longer needs.

Since: 3.00. See also: viewNew, materialSetView

Example
-- The security room's monitors only render while the player is in it.
function onEnterSecurityRoom()
    feed = viewNew(512, 384)
    viewSetCamera(feed, hallwayCamera)
    materialSetView(monitorLook, feed)
end

function onLeaveSecurityRoom()
    viewDelete(feed)
    feed = nil
end

2.47.2. viewNew

view = viewNew(width, height)

Makes a camera rendered to a width by height texture every frame (each clamped to 1 to 4096), from the default view until viewSetCamera names a node, and returns the view handle for materialSetView. The view uses the projection from cameraSetPerspective or cameraSetOrthographic at its own aspect ratio. The scene renders once more per view, so 512 by 384 is plenty for a monitor and a Raspberry Pi wants smaller. Ends the script when 3D is unavailable or four views are already in use.

Parameters:

  • width — the texture’s width in pixels.

  • height — the texture’s height in pixels.

Returns: The view handle, an integer.

Since: 3.00. See also: viewSetCamera, materialSetView, viewDelete

Example
-- A security monitor showing a camera behind the player.
eye = nodeNew()
nodeSetPosition(eye, 0, 2.2, -5)
nodeLookAt(eye, 0, 0.6, 0)
feed = viewNew(512, 384)
viewSetCamera(feed, eye)
screen = materialNew()
materialSetView(screen, feed)
materialSetUnlit(screen, true)
nodeSetMesh(monitor, meshPlane(2, 1.5), screen)
nodeSetRotation(monitor, 90, 0, 0)

2.47.3. viewSetCamera

viewSetCamera(view, node)
viewSetCamera(view, nil)
viewSetCamera(view)

The node the view looks from, down its own -Z like the main camera, so its parents' movement counts. With nil or no second argument the view goes back to the default view from (0, 0, 5) looking at the origin. Parent the node to a car for a rear-view mirror, or reflect the main camera’s position about a wall for a mirror in it. Ends the script for a node handle that is not valid.

Since: 3.00. See also: viewNew, cameraSet, nodeLookAt

Example
-- The lobby monitor cycles through three security cameras.
cameras = { lobbyCamera, garageCamera, roofCamera }
current = 1

function onOverlayUpdate()
    if singeGetTicks() - lastSwitch > 4000 then
        current    = current % #cameras + 1
        lastSwitch = singeGetTicks()
        viewSetCamera(feed, cameras[current])
    end
    return OVERLAY_UPDATED
end

2.48. Video

The video* family handles additional video clips on top of the disc: a character talking in a corner, a pre-rendered animation at a story beat, several concurrent cues. Any number of videos can be loaded with videoLoad, and each returns an opaque integer handle that every other video* function takes as its first argument; a handle that has been unloaded terminates the script. Videos are drawn onto the overlay with videoDraw in overlay coordinates and composite like sprites, and a video advances only while it is being drawn (or used as a material through materialSetVideo). Each video has its own audio track selection and stereo volume, independent of the disc. Like sprites, videos must be drawn from onOverlayUpdate and eventually freed with videoUnload; the drawing rules are in Overlay.

2.48.1. videoDraw

videoDraw(id, x, y, x2, y2)
videoDraw(id, x, y, centered)

Advances a video to the frame its clock calls for and draws that frame on the overlay. The clock follows the video’s audio when it has any and wall time otherwise, so a call may advance zero, one or several frames; a video that reaches its end loops back to frame 0. The five argument form stretches the frame into the rectangle from (x, y) to (x2, y2) inclusive, always with nearest-neighbor sampling and ignoring videoScale, videoRotate and videoQuality. The four argument form draws the frame at its native size transformed by videoScale and videoRotate, anchored at its top left corner or, when centered is true, at its center; the transformed frame is rebuilt only when the frame or the transform changes, and rotated corners are transparent. If the decoder has not produced a frame yet nothing is drawn.

A frame that is not scaled or turned by videoScale or videoRotate, drawn on the overlay where nothing has been drawn since an overlayClear to a transparent color — a background video drawn first, say — is drawn by the GPU instead, under the overlay, and costs next to nothing; anything drawn afterwards still goes over it. It is then scaled to the screen the way the overlay is, rather than nearest-neighbor into the overlay first. Everywhere else the frame is copied into the overlay on the CPU, which on a small machine costs several milliseconds a frame, so draw a video before anything that goes over it rather than after.

Parameters:

  • id — video handle from videoLoad.

  • x, y — anchor in overlay coordinates.

  • x2, y2 — opposite corner of the destination rectangle, inclusive.

  • centered — boolean. true places the center of the drawn frame at (x, y), false its top left corner. Use true for rotated videos.

Notes: A video that is not drawn does not advance, so pausing is implicit while a clip is hidden. Draw from onOverlayUpdate only.

Since: 2.00. The scaled/rotated form with centered flag added in 2.10. See also: videoLoad, videoScale, videoRotate, spriteDraw

Example
-- Attract clip in a fixed box, looping over its own start and end frames.
function onOverlayUpdate()
    overlayClear()
    videoDraw(attractVideo, VIDEO_X, VIDEO_Y, VIDEO_X + VIDEO_W - 1, VIDEO_Y + VIDEO_H - 1)
    if videoGetFrame(attractVideo) > ATTRACT_END then
        videoSeek(attractVideo, ATTRACT_START)
    end
    return OVERLAY_UPDATED
end

2.48.2. videoGetAudioTrack

track = videoGetAudioTrack(id)

Returns the zero based index of the audio track a loaded video is playing. videoLoad selects the track named by --audio or the AUDIO_TRACK entry in games.dat (default 0) when the file has that many tracks; a video with no audio at all reports -1.

Returns: integer track index.

Example
-- Show which dub the cutscene is using in the options overlay.
function drawAudioOption()
    local track = videoGetAudioTrack(cutscene)
    local label = "None"
    if track >= 0 then
        label = videoGetLanguageDescription(videoGetLanguage(cutscene, track))
    end
    overlayPrint(OPTION_X, OPTION_Y, "Cutscene audio: " .. label)
end

2.48.3. videoGetAudioTracks

count = videoGetAudioTracks(id)

Returns how many audio streams a loaded video contains. A silent clip reports 0; guard loops and modulo arithmetic against that.

Returns: integer count, 0 or more.

Example
-- Only offer the language menu when the cutscene actually has choices.
cutscene = videoLoad("videos/briefing.mkv")
if videoGetAudioTracks(cutscene) > 1 then
    buildLanguageMenu(cutscene)
else
    languageMenuEnabled = false
end

2.48.4. videoGetFrame

frame = videoGetFrame(id)

Returns the frame a loaded video is positioned on, zero based. The position only changes while the video plays and is drawn, and it wraps to 0 when the clip loops. Compare it with your own start and end markers to loop a section, or with videoGetFrameCount to detect the end of a one-shot clip.

Returns: integer frame number.

Since: 2.00 See also: videoSeek, videoGetFrameCount, videoDraw

Example
-- Return control to the player when the briefing has played through once.
function onOverlayUpdate()
    if briefingRunning then
        videoDraw(briefing, 0, 0, false)
        if videoGetFrame(briefing) >= videoGetFrameCount(briefing) - 1 then
            briefingRunning = false
            videoPause(briefing)
        end
    end
    return OVERLAY_UPDATED
end

2.48.5. videoGetFrameCount

count = videoGetFrameCount(id)

Returns the total number of frames in a loaded video, as counted from the file’s frame table when it was indexed. Frames run from 0 to count - 1. Use it for progress bars, for wrapping a loop, or for detecting when a one-shot clip is almost done.

Returns: integer frame count.

Since: 2.00 See also: videoGetFrame, videoSeek, videoIsPlaying

Example
-- Progress line under a loading clip:  an outline frame and a fill that grows.
function drawProgress()
    local total = videoGetFrameCount(loadingClip)
    local done  = videoGetFrame(loadingClip) / (total - 1)
    colorForeground(255, 255, 255, 255)
    overlayBox(BAR_X - 1, BAR_Y - 1, BAR_X + BAR_W + 1, BAR_Y + 1)
    overlayLine(BAR_X, BAR_Y, BAR_X + BAR_W * done, BAR_Y)
end

2.48.6. videoGetHeight

height = videoGetHeight(id)

Returns the height of a loaded video’s frames in pixels, the native size of the file rather than the size it is drawn at. Combine it with videoScale to fit a clip into a box while keeping its aspect ratio.

Returns: integer height in pixels.

Since: 2.00 See also: videoGetWidth, videoScale

Example
-- Fit the clip into a 320x240 window without distorting it.
local fitX = 320 / videoGetWidth(clip)
local fitY = 240 / videoGetHeight(clip)
local fit  = math.min(fitX, fitY)
videoScale(clip, fit)

2.48.7. videoGetLanguage

code = videoGetLanguage(id, track)

Returns the language tag stored in the file for one audio track of a loaded video. The tag is a three letter ISO 639 code such as "eng" or "jpn"; a track without a three letter tag returns "unk". A track outside 0 to videoGetAudioTracks(id) - 1 terminates the script.

Parameters:

  • id — video handle.

  • track — zero based audio track index.

Returns: string language code.

Example
-- Match the cutscene's dub to the language chosen for the disc.
local wanted = discGetLanguage(discGetAudioTrack())
for track = 0, videoGetAudioTracks(cutscene) - 1 do
    if videoGetLanguage(cutscene, track) == wanted then
        videoSetAudioTrack(cutscene, track)
        break
    end
end

2.48.8. videoGetLanguageDescription

name = videoGetLanguageDescription(code)

Looks up the English name of a language code. Unlike the other video* functions it takes no handle; it is a pure table lookup that accepts ISO 639-1 two letter codes and ISO 639-2 three letter codes (both the T and B forms), compared without regard to case. Unrecognized codes, including the "unk" returned for untagged tracks, give "Unknown". Framework.singe aliases it as discGetLanguageDescription for symmetry with the disc API.

Parameters:

  • code — language code such as "en", "eng" or "jpn".

Returns: string language name, or "Unknown".

Since: 2.10 See also: videoGetLanguage, discGetLanguage

Example
-- Build a language-select menu from a video's tracks.
options = {}
for track = 0, videoGetAudioTracks(cutscene) - 1 do
    local code = videoGetLanguage(cutscene, track)
    local name = videoGetLanguageDescription(code)
    table.insert(options, { track = track, label = name })
end

2.48.9. videoGetVolume

left, right = videoGetVolume(id)
volume = videoGetVolume()

Returns the stereo volume of a loaded video as two percentages. A freshly loaded video is at the --volume_nonvldp level on both channels (default 100). Note that two values come back, left first.

Called with no argument it is a Hypseus extension answering the laserdisc’s own volume instead, as a single number on Hypseus’s 0 to 64 scale rather than as a percentage. Its games double that for musicSetVolume, whose range is 0 to 128. The level follows --volume_vldp.

Returns: two integers, left and right, each 0 to 100; or with no argument one integer, 0 to 64.

Since: 2.00, the no-argument disc form 3.00 See also: videoSetVolume, videoLoad

Example
-- Duck the cutscene while a voice line plays, then restore it.
function playVoiceOver(sound)
    savedLeft, savedRight = videoGetVolume(cutscene)
    videoSetVolume(cutscene, savedLeft / 4, savedRight / 4)
    soundPlay(sound)
    duckingCutscene = true
end

2.48.10. videoGetWidth

width = videoGetWidth(id)

Returns the width of a loaded video’s frames in pixels, the native size of the file rather than the size it is drawn at.

Returns: integer width in pixels.

Since: 2.00 See also: videoGetHeight, videoScale

Example
-- Center a clip drawn at native size at the top of the overlay.
local x = (overlayGetWidth() - videoGetWidth(clip)) / 2
function onOverlayUpdate()
    videoDraw(clip, x, 16, false)
    return OVERLAY_UPDATED
end

2.48.11. videoIsPlaying

playing = videoIsPlaying(id)

Reports whether a loaded video is in the playing state, that is, whether videoPlay has been called since the last videoPause. A playing video still only advances while it is drawn. Videos start paused after videoLoad.

Returns: boolean.

Since: 2.00 See also: videoPlay, videoPause, videoGetFrame

Example
-- One key toggles the picture-in-picture clip.
function onInputPressed(what)
    if what == SWITCH_BUTTON2 then
        if videoIsPlaying(pipVideo) then
            videoPause(pipVideo)
        else
            videoPlay(pipVideo)
        end
    end
end

2.48.12. videoLoad

id = videoLoad(filename)

Opens a video file and returns its handle. Any container and codec the bundled FFmpeg can decode is accepted. The engine builds or reads a frame index in a data directory named for the video’s location under Singe’s data root, so the first load of a large file can take a moment; failing to create that directory terminates the script. The video starts paused on frame 0, with its audio track set from --audio or the AUDIO_TRACK entry in games.dat (default 0) when the file has that many tracks, and both channels at the --volume_nonvldp level. Frames are decoded to RGB so they can be drawn on the overlay.

Parameters:

  • filename — path to the video file, relative to the game directory or inside a packed game.

Returns: integer video handle.

Since: 2.00 See also: videoPlay, videoDraw, videoUnload

Example
-- Load the attract clip for the selected game and cue its loop start.
function loadGameAssets()
    attractVideo = videoLoad(GAME_LIST[GAME_SELECTED].ATTRACT)
    if GAME_LIST[GAME_SELECTED].AUDIO_TRACK then
        videoSetAudioTrack(attractVideo, GAME_LIST[GAME_SELECTED].AUDIO_TRACK)
    end
    videoPlay(attractVideo)
    videoSeek(attractVideo, GAME_LIST[GAME_SELECTED].ATTRACT_START)
end

2.48.13. videoPause

videoPause(id)

Pauses a loaded video. Its clock stops, its audio track pauses, and videoDraw keeps drawing the frame it stopped on. Pausing a video that is already paused is harmless.

Since: 2.00 See also: videoPlay, videoIsPlaying

Example
-- Freeze the attract clip while the calibration screen is up.
function calibrationBegin()
    calibrating = true
    if attractVideo then
        videoPause(attractVideo)
    end
end

2.48.14. videoPlay

videoPlay(id)

Starts or resumes a loaded video from its current frame. The clock is restarted at that frame, so a video resumed after a long pause continues where it stopped rather than jumping ahead, and the audio track resumes with it. The video only advances while it is drawn with videoDraw or used as a material.

Since: 2.00 See also: videoPause, videoSeek, videoDraw

Example
-- Start the briefing over the paused disc.
function startBriefing()
    discPause()
    videoSeek(briefing, 0)
    videoPlay(briefing)
    briefingRunning = true
end

2.48.15. videoQuality

videoQuality(id, smooth)

Selects the filtering used when the four argument form of videoDraw scales or rotates the video. Any nonzero value selects RENDER_SMOOTH (bilinear), zero selects RENDER_PIXELATED (nearest-neighbor), the default. A change marks the transformed frame for rebuilding on the next draw. It has no effect on the stretched five argument form, which always uses nearest-neighbor, nor on an untransformed video.

Parameters:

  • id — video handle.

  • smooth — RENDER_PIXELATED (0) or RENDER_SMOOTH (1).

Since: 2.10 See also: videoScale, videoRotate, videoDraw

Example
-- A photographic clip shrunk into a corner looks better filtered.
pipVideo = videoLoad("videos/copilot.mkv")
videoScale(pipVideo, 0.4)
videoQuality(pipVideo, RENDER_SMOOTH)
videoPlay(pipVideo)

2.48.16. videoRotate

videoRotate(id, degrees)

Sets the rotation the four argument form of videoDraw applies, in degrees clockwise, using the same convention as spriteRotate. The angle is reduced modulo 360 and keeps its sign, so 450 and 90 are the same and -90 rotates a quarter turn counterclockwise. The scale set by videoScale is kept. Rotation is applied about the frame’s center, so draw rotated videos with centered set to true. A changed angle marks the transformed frame for rebuilding on the next draw.

Parameters:

  • id — video handle.

  • degrees — rotation in degrees, clockwise.

Since: 2.10 See also: videoRotateAndScale, videoScale, videoDraw

Example
-- Spin the radar feed slowly while it plays.
function onOverlayUpdate()
    radarAngle = radarAngle + 0.5
    videoRotate(radarVideo, radarAngle)
    videoDraw(radarVideo, RADAR_CENTER_X, RADAR_CENTER_Y, true)
    return OVERLAY_UPDATED
end

2.48.17. videoRotateAndScale

videoRotateAndScale(id, degrees, scale)
videoRotateAndScale(id, degrees, scaleX, scaleY)

Sets rotation and scale in one call, with the same rules as videoRotate and videoScale: degrees clockwise reduced modulo 360, and scale factors that must be greater than 0. Use it when both change every frame so the transformed frame is rebuilt once rather than twice.

Parameters:

  • id — video handle.

  • degrees — rotation in degrees, clockwise.

  • scale — uniform scale factor, 1.0 for native size.

  • scaleX, scaleY — separate horizontal and vertical factors.

Since: 2.10 See also: videoRotate, videoScale, videoDraw

Example
-- A clip tumbles and shrinks away as it is dismissed.
function onOverlayUpdate()
    if dismissing then
        dismissTime = dismissTime + 1
        videoRotateAndScale(popupVideo, dismissTime * 6, 1.0 - dismissTime / 60)
        videoDraw(popupVideo, POPUP_CENTER_X, POPUP_CENTER_Y, true)
    end
    return OVERLAY_UPDATED
end

2.48.18. videoScale

videoScale(id, scale)
videoScale(id, scaleX, scaleY)

Sets the scale the four argument form of videoDraw applies, as a factor of the native size; 1.0 is unscaled. The rotation set by videoRotate is kept. A changed scale marks the transformed frame for rebuilding on the next draw. Factors of 0 or less cannot be rendered and abort the engine on the next videoDraw, so clamp animated scales above zero. The stretched five argument form of videoDraw ignores this setting.

Parameters:

  • id — video handle.

  • scale — uniform scale factor, greater than 0.

  • scaleX, scaleY — separate horizontal and vertical factors, each greater than 0.

Example
-- Show the cutscene at a quarter of its size in the corner while play continues.
pipVideo = videoLoad("videos/copilot.mkv")
videoScale(pipVideo, 0.25)
videoPlay(pipVideo)
function onOverlayUpdate()
    videoDraw(pipVideo, PIP_X, PIP_Y, false)
    return OVERLAY_UPDATED
end

2.48.19. videoSeek

videoSeek(id, frame)

Positions a loaded video on frame and restarts its clock there. The play or pause state is unchanged: a playing video continues from the new frame at its next draw, a paused one shows it. The frame number wraps modulo the frame count, so -1 is the last frame and a value past the end lands back inside the clip.

Parameters:

  • id — video handle.

  • frame — target frame, zero based.

Since: 2.00 See also: videoGetFrame, videoGetFrameCount, videoPlay

Example
-- Loop the attract clip between the two markers from games.dat.
function onOverlayUpdate()
    videoDraw(attractVideo, VIDEO_X, VIDEO_Y, VIDEO_X + VIDEO_W - 1, VIDEO_Y + VIDEO_H - 1)
    if videoGetFrame(attractVideo) > GAME_LIST[GAME_SELECTED].ATTRACT_END then
        videoSeek(attractVideo, GAME_LIST[GAME_SELECTED].ATTRACT_START)
    end
    return OVERLAY_UPDATED
end

2.48.20. videoSetAudioTrack

videoSetAudioTrack(id, track)

Switches a loaded video to another of its audio tracks. Queued audio from the old track is dropped and playback realigns, so the change is heard almost immediately. Selecting the track already in use is a no-op. A track outside 0 to videoGetAudioTracks(id) - 1 terminates the script, which for a silent clip means any value at all.

Parameters:

  • id — video handle.

  • track — zero based audio track index.

Example
-- The menu stores a per-game audio track for its attract clip.
attractVideo = videoLoad(GAME_LIST[GAME_SELECTED].ATTRACT)
local wanted = GAME_LIST[GAME_SELECTED].AUDIO_TRACK
if wanted and wanted < videoGetAudioTracks(attractVideo) then
    videoSetAudioTrack(attractVideo, wanted)
end
videoPlay(attractVideo)

2.48.21. videoSetVolume

videoSetVolume(id, left, right)
videoSetVolume(volume)

Sets the stereo volume of a loaded video as percentages. Values are clamped to 0 through 100 without complaint. The setting is remembered even for a silent clip and is reported back by videoGetVolume.

Called with one argument it is a Hypseus extension setting the laserdisc’s own volume instead, on Hypseus’s 0 to 64 scale rather than as a percentage: the twin of the bare videoGetVolume(). A level outside 0 to 64 is ignored rather than fatal, which is what Hypseus does with one.

Parameters:

  • id — video handle.

  • left, right — channel volumes, 0 (silent) to 100 (full).

  • volume — the laserdisc’s volume, 0 (silent) to 64 (full).

Since: 2.00 See also: videoGetVolume, discAudio

Example
-- Fade the cutscene audio out in under half a second as control returns.
function onOverlayUpdate()
    if fadingOut then
        fadeLevel = fadeLevel - 4
        videoSetVolume(cutscene, fadeLevel, fadeLevel)
        if fadeLevel <= 0 then
            fadingOut = false
            videoPause(cutscene)
        end
    end
    return OVERLAY_UPDATED
end

2.48.22. videoUnload

videoUnload(id)

Stops the decoder and releases everything a loaded video holds: decoder, audio track, cached frames and the transformed surface. The handle is invalid afterward and passing it to any video* function terminates the script, so clear the variable that held it. Videos still loaded when the script ends are released by the engine.

Parameters:

  • id — video handle.

Since: 2.00 See also: videoLoad, videoPause

Example
-- Drop the selected game's assets before loading the next one.
function unloadGameAssets()
    if attractVideo then
        videoUnload(attractVideo)
        attractVideo = nil
    end
end

2.49. VLDP

The vldp* namespace predates Singe 2.00 and exists to keep older scripts running. vldpGetHeight and vldpGetWidth are the same bindings as discGetHeight and discGetWidth, vldpSetVerbose does nothing, and vldpGetPixel is the one member with no modern equivalent: it reads a pixel of the current disc frame at overlay coordinates and is still the standard way to do hit detection against pre-recorded video. Without a disc it returns black (see Games Without a Disc).

Legacy. Prefer discGetHeight and discGetWidth in new code. vldpGetPixel remains current.

Hypseus Singe added eleven more members, kept under this prefix so its games run unchanged: vldpFocusArea and vldpResetFocus crop the disc picture, vldpGetScale and vldpSetScale report and change the display scale factor, vldpGetRotate and vldpSetRotate do the same for the presentation rotation, vldpGetYUVPixel reads raw samples, and vldpFlash, vldpSetBlend, vldpSetLuma and vldpSetMonochrome change how the picture itself looks. Each is marked "Hypseus extension" below. The scale and the rotation are two of the inputs to The Video Rectangle.

The four picture controls work on the decoded frame, on its luma and chroma planes, before it reaches the screen: vldpSetBlend and vldpSetLuma are applied one after the other as each frame is uploaded, vldpSetMonochrome replaces the chroma, and vldpFlash replaces the picture outright for one frame. They cost a pass over the luma plane per frame while they are on and nothing at all while they are off, they leave vldpGetPixel and vldpGetYUVPixel reading the picture as it was decoded, and with a frame file they follow the playback from segment to segment. All four go back to off when the script reloads (except monochrome, which goes back to whatever --monochrome asked for) and none of them touches a video drawn with videoDraw.

2.49.1. vldpFlash

vldpFlash()

Hypseus extension. Puts one white picture on the disc, the way a real laserdisc player flashes when it is searched. It goes up at once and the next disc update takes it off again, so it lasts one drawn frame whether the disc is playing, paused or stopped.

The white is the value Hypseus flashes, 90 percent luma with neutral chroma, not pure white, which is what a video signal’s white actually is. The overlay, the GUIs and the bezel artwork are drawn over it as usual, so a heads-up display stays readable through the flash.

Without a disc, or on a disc whose first frame has not been decoded yet, the call does nothing.

Parameters: none.

Returns: nothing.

Since: 3.00, as a Hypseus Singe extension. See also: discSearch, vldpSetLuma

Example
-- Punctuate a hit.
vldpFlash()

2.49.2. vldpFocusArea

vldpFocusArea(x, y, width, height)
vldpFocusArea()

Hypseus extension. Shows only a rectangle of the disc frame, given in disc pixels, stretched into the space the whole frame normally fills, with the renderer’s usual smooth scaling; the aspect follows whatever width and height give. The rectangle is held inside the frame, and one that lies entirely outside it aborts the script. With no arguments the whole frame is shown again (Hypseus ignores that call and uses vldpResetFocus; Singe accepts both). The focus is a display effect only: vldpGetPixel, vldpGetYUVPixel, the mouse mapping and the disc on a 3D material all keep unfocused coordinates, so hit detection on a zoomed picture must be scaled by the caller. Without a disc the call does nothing. Reset when the script reloads.

Parameters:

  • x, y — top-left corner in disc pixels.

  • width, height — size of the rectangle in disc pixels.

Since: 3.00, as a Hypseus Singe extension. See also: vldpResetFocus, vldpGetWidth, vldpGetPixel

Example
-- Zoom into the middle 80% of the picture during the chase.
local w, h = vldpGetWidth(), vldpGetHeight()
vldpFocusArea(w * 0.1, h * 0.1, w * 0.8, h * 0.8)

function onChaseEnded()
    vldpFocusArea()
end

2.49.3. vldpGetHeight

height = vldpGetHeight()

Returns the height of the disc’s video in pixels, or the canvas height without a disc. This is the same binding as discGetHeight registered under its pre-2.00 name.

Returns: integer height in pixels.

Notes:

Legacy alias. Use discGetHeight in new code.

Since: 1.x See also: discGetHeight, vldpGetWidth

Example
-- A 1.x script sizing its overlay from the disc.
overlaySetResolution(vldpGetWidth(), vldpGetHeight())
centerX = vldpGetWidth() / 2
centerY = vldpGetHeight() / 2

2.49.4. vldpGetPixel

r, g, b = vldpGetPixel(x, y)

Reads the color of one pixel of the disc frame currently on screen. The coordinates are overlay coordinates: the engine divides them by the overlay-to-video scale and truncates, so you pass the same numbers you draw with. Returns 0, 0, 0 when there is no disc, when no frame has been decoded yet, or when the scaled coordinates fall outside the video. Games that use it typically tag targets in the source footage with a distinctive color and test the pixel under the crosshair on a trigger pull instead of authoring hit boxes for every frame.

Parameters:

  • x, y — overlay coordinates; fractional values are accepted.

Returns: three integers, red, green and blue, each 0 to 255.

Example
-- Light gun hit check:  targets are painted pure magenta on enemy frames.
function onInputPressed(what)
    if what == SWITCH_BUTTON3 then
        local x, y = mouseGetPosition(0)
        local r, g, b = vldpGetPixel(x, y)
        if r > 200 and g < 50 and b > 200 then
            scoreHit()
        else
            scoreMiss()
        end
    end
end

2.49.5. vldpGetRotate

degrees = vldpGetRotate()

Hypseus extension. Returns the presentation rotation in degrees clockwise: the --rotate option, or whatever vldpSetRotate last set, and 0 when neither has. Only 0, 90, 180 and 270 are ever returned, because those are the only angles Singe turns to.

Returns: integer, 0, 90, 180 or 270.

Since: 3.00, as a Hypseus Singe extension. See also: vldpSetRotate, vldpGetScale

Example
-- A portrait cabinet wants its score panel down the long side.
if vldpGetRotate() == 90 or vldpGetRotate() == 270 then
    layoutPanel(PANEL_TALL)
else
    layoutPanel(PANEL_WIDE)
end

2.49.6. vldpGetScale

scale = vldpGetScale()

Hypseus extension. Returns the display scale factor as a percentage: the --scalefactor option, or whatever vldpSetScale last applied, and 100 when neither has been given. Hypseus games divide 100 by it to size their overlay geometry to the shrunken picture. It has nothing to do with vldpFocusArea or the overlay resolution.

Returns: integer, 25 to 100.

Since: 3.00, as a Hypseus Singe extension. See also: vldpSetScale, vldpFocusArea, overlayGetWidth

Example
-- Hypseus game code:  the gun sights scale with the picture.
if vldpGetScale ~= nil then
    gunScale = 100 / vldpGetScale()
else
    gunScale = 1
end

2.49.7. vldpGetShift

x, y = vldpGetShift()

The picture’s offset within the window as percentages, the --shiftx and --shifty options or whatever vldpSetShift last applied, and 0, 0 when neither has been given. At the extreme a shift fills exactly the room --scalefactor left, so 100 with the scale at 100 moves nothing.

Returns: two integers, each -100 to 100.

Since: 3.00. See also: vldpSetShift, vldpGetScale

Example
-- Report where the operator has put the picture.
local x, y = vldpGetShift()
fontPrint(10, 10, string.format("shift %d, %d", x, y))

2.49.8. vldpGetWidth

width = vldpGetWidth()

Returns the width of the disc’s video in pixels, or the canvas width without a disc. This is the same binding as discGetWidth registered under its pre-2.00 name.

Returns: integer width in pixels.

Notes:

Legacy alias. Use discGetWidth in new code.

Since: 1.x See also: discGetWidth, vldpGetHeight

Example
-- A 1.x script sizing its overlay from the disc.
overlaySetResolution(vldpGetWidth(), vldpGetHeight())
centerX = vldpGetWidth() / 2
centerY = vldpGetHeight() / 2

2.49.9. vldpGetYUVPixel

y, u, v = vldpGetYUVPixel(x, y)

Hypseus extension. Reads the raw samples of one pixel of the disc frame currently shown, before any color conversion: the luma and the two chroma samples, each 0 to 255, with chroma at the 4:2:0 resolution of the decoded picture (neutral is 128). The coordinates are overlay coordinates, scaled and truncated exactly as vldpGetPixel does. Returns -1, -1, -1 when there is no disc, when no frame has been decoded yet, or when the scaled coordinates fall outside the video. Unaffected by vldpFocusArea and vldpSetMonochrome. Cheaper than vldpGetPixel when only the brightness matters.

Parameters:

  • x, y — overlay coordinates; fractional values are accepted.

Returns: three integers, Y, U and V, each 0 to 255, or -1, -1, -1.

Since: 3.00, as a Hypseus Singe extension. See also: vldpGetPixel, discGetFrame

Example
-- The road is dark; anything bright under the car is an obstacle.
function carHitsSomething()
    local y = vldpGetYUVPixel(carX + carWidth / 2, carY + carHeight)
    return y >= 120
end

2.49.10. vldpResetFocus

vldpResetFocus()

Hypseus extension. Shows the whole disc frame again after vldpFocusArea, exactly as vldpFocusArea() with no arguments does. Hypseus’s own name for the reset, kept so its games run unchanged.

Since: 3.00, as a Hypseus Singe extension. See also: vldpFocusArea

Example
function onChaseEnded()
    vldpResetFocus()
end

2.49.11. vldpSetBlend

vldpSetBlend(enabled)

Hypseus extension. Smooths the disc picture down its rows: each luma sample becomes the average of itself and the samples immediately above and below it. This is Hypseus’s own three tap blend filter, and it exists to take the hard edges off an interlaced transfer without softening the picture sideways.

The chroma planes are left alone, so the smoothing changes the brightness detail and not the color. Turning it off puts the picture back exactly as it was decoded.

Without a disc the call does nothing but is still remembered, so it takes effect if a disc is loaded later. A non-boolean argument terminates the script.

Parameters:

  • enabled — boolean.

Returns: nothing.

Since: 3.00, as a Hypseus Singe extension. See also: vldpSetLuma, vldpSetMonochrome

Example
-- A service screen switch for a noisy transfer.
vldpSetBlend(SETTINGS.softenVideo)

2.49.12. vldpSetLuma

vldpSetLuma(enabled [, level])

Hypseus extension. Brightens or darkens the disc picture. level runs from 0 to 8 and 4, the default, changes nothing: the distance from 4 is added to every luma sample in eighths, so 0 halves the brightness, 8 raises it by half, and the steps between are even. A level outside 0 to 8 terminates the script.

Since only the luma is changed, the color stays where it is: raising the level brightens the picture without washing the color out, which is what a real player’s picture control does and what a color multiplier would not. Turning it off, or asking for level 4, puts the picture back exactly as it was decoded.

vldpSetLuma(true) with no level therefore does nothing visible, which is Hypseus’s behavior as well.

Without a disc the call does nothing but is still remembered, so it takes effect if a disc is loaded later.

Parameters:

  • enabled — boolean.

  • level — optional number; 0 to 8, 4 being neutral. Default 4.

Returns: nothing.

Since: 3.00, as a Hypseus Singe extension. See also: vldpSetBlend, vldpSetMonochrome, vldpFlash

Example
-- A night scene the player cannot see; let them lift it.
vldpSetLuma(true, 6)

2.49.13. vldpSetMonochrome

vldpSetMonochrome(enabled)

Hypseus extension. Shows the disc in luma only: the chroma planes are replaced by neutral samples when each frame is uploaded, so a paused disc changes at once. With a frame file the setting follows the playback from segment to segment. vldpGetPixel and vldpGetYUVPixel keep returning the color samples, and extra videos drawn with videoDraw are unaffected. Pair it with overlaySetMonochrome for a black and white mode. Without a disc the call does nothing; reset when the script reloads. A non-boolean argument aborts the script.

Parameters:

  • enabled — boolean.

Since: 3.00, as a Hypseus Singe extension. See also: overlaySetMonochrome, vldpGetPixel

Example
-- A dip switch picks color or black and white.
vldpSetMonochrome(not dipChroma)
overlaySetMonochrome(not dipChroma)

2.49.14. vldpSetRotate

applied = vldpSetRotate(degrees)

Hypseus extension. Turns the whole presentation clockwise: the disc, the overlay, the GUIs, the 3D scene and the particles all turn together, and mouse and light gun positions are turned back so a click still lands where it is drawn. A quarter turn swaps the shape of the presented area, so a portrait window is filled rather than letterboxed into a strip.

Hypseus accepts any angle from 0 to 359; Singe takes only 0, 90, 180 and 270, and answers false for anything else instead of ending the script. An arbitrary angle would leave the mouse mapping and the Sinden border without a sensible meaning, and no game in the Hypseus library asks for one.

The rotation costs one screen sized render target and one extra blit per frame while it is not zero, and nothing at all while it is. Reset to the --rotate value when the script reloads.

Parameters:

  • degrees — integer, 0, 90, 180 or 270.

Returns: boolean, true when the rotation was applied.

Since: 3.00, as a Hypseus Singe extension. See also: vldpGetRotate, vldpSetScale

Example
-- A vertical shooter section on a pivoting monitor.
if not vldpSetRotate(90) then
    debugPrint("This build will not turn the screen.")
end

2.49.15. vldpSetScale

applied = vldpSetScale(percent)

Hypseus extension. Shrinks the picture about its center to percent of the window, the running equivalent of --scalefactor, and rebuilds the video rectangle so the disc, the overlay, the GUIs, the 3D scene, the particles, any Sinden border and the mouse mapping all follow it. Values outside 25 to 100 answer false and change nothing, rather than ending the script.

Changes are limited to one every 15 milliseconds, as Hypseus limits its own held-key zoom; a call inside that window answers false, so a script driving the scale from a held key should keep calling until it takes. Reset to the --scalefactor value when the script reloads.

Parameters:

  • percent — integer, 25 to 100.

Returns: boolean, true when the scale was applied.

Since: 3.00, as a Hypseus Singe extension. See also: vldpGetScale, vldpSetRotate

Example
-- Zoom out a step each time the player presses the adjust key.
function onInputPressed(input)
    if input == SWITCH_BUTTON3 then
        vldpSetScale(vldpGetScale() - 5)
    end
end

2.49.16. vldpSetShift

vldpSetShift(x, y)

Moves the picture within the window, the running equivalent of --shiftx and --shifty, and rebuilds the video rectangle so the disc, the overlay, the GUIs, the 3D scene, the particles, any Sinden border and the mouse mapping all follow it. The values are percentages of the room --scalefactor left, so with the scale at 100 there is nowhere to move to. A value outside -100 to 100 ends the script, unlike vldpSetScale, which answers false.

Parameters:

  • x — integer, -100 to 100.

  • y — integer, -100 to 100.

Returns: nothing.

Since: 3.00. See also: vldpGetShift, vldpSetScale, singeSaveGeometry

Example
-- Nudge the picture left each time the operator presses the key.
function onInputPressed(input)
    if input == SWITCH_LEFT then
        local x, y = vldpGetShift()
        vldpSetShift(math.max(-100, x - 1), y)
    end
end

2.49.17. vldpSetVerbose

vldpSetVerbose(...)

Does nothing. It once toggled logging in the original video player; the call accepts any arguments, logs a trace line and returns. Engine and script tracing are now command line options (--program and --trace).

Notes:

Unimplemented. Retained for backward compatibility only. Use --trace on the command line to log API calls.

Since: 1.x See also: debugPrint, discGetState

Example
-- Ported 1.x startup code.  The call is ignored; run Singe with --trace instead.
vldpSetVerbose(true)
overlaySetResolution(discGetWidth(), discGetHeight())
discSearch(TITLE_FRAME)

2.50. Voice

The pieces a voice chat is built from, without the network: Opus to make a voice small enough to send and back again, a processor that cleans a microphone up before it is sent, and a jitter buffer to play what arrives late and out of order in the right order. Sending the packets and finding the other players are a game’s own business, or a later version of Singe’s.

Samples are strings of 16-bit values, two bytes each, little endian, as micRead gives them; with two channels they alternate left and right. A frame is a fixed slice of time: 20 milliseconds, 960 samples at 48000, is the usual one for a voice.

Every object here is a handle. voiceFree releases one; all of them are released when the game ends.

A microphone, cleaned, encoded, and decoded again
micOpen()
local processor = voiceProcessorNew()
local encoder   = opusEncoderNew()
local decoder   = opusDecoderNew()
local pending   = ""

function onOverlayUpdate()
	pending = pending .. micRead()
	while #pending >= 960 * 2 do
		local frame = pending:sub(1, 960 * 2)
		pending = pending:sub(960 * 2 + 1)
		local cleaned, voiced = voiceProcess(processor, frame)
		if voiced then
			local packet = opusEncode(encoder, cleaned)    -- this is what you send
			local heard  = opusDecode(decoder, packet)     -- and this is what the other end plays
		end
	end
	return OVERLAY_UPDATED
end

2.50.1. jitterGet

packet, status = jitterGet(jitter [, span])

The packet due to be played now, and the buffer moved on by one step. Call it once a frame’s worth of time, whatever arrived.

Parameters:

  • span — number, the samples to take; the step unless given.

Returns: the packet, or nil, and a status: "ok", "missing" (nothing is due: hand nil to opusDecode to cover the gap), or "insertion" (the buffer is growing to absorb late packets: play a little silence).

Since: 3.00.

2.50.2. jitterNew

jitter = jitterNew([step])

A jitter buffer: packets go in by their timestamp as they arrive, and come out in order, one step at a time, a little behind so a late one still makes it.

Parameters:

  • step — number, the samples each jitterGet moves on; 960 unless given.

Returns: the jitter buffer’s handle.

Since: 3.00.

2.50.3. jitterPut

jitterPut(jitter, packet, timestamp [, span])

A packet that arrived. The buffer keeps its own copy.

Parameters:

  • packet — string, 1 to 4000 bytes.

  • timestamp — number, where the packet starts, in samples: the sender counts them, 0, 960, 1920, and so on.

  • span — number, the samples the packet covers; the step unless given.

Since: 3.00.

2.50.4. opusDecode

samples = opusDecode(decoder, packet | nil)

A packet back to samples. nil for a packet that never arrived asks Opus to cover the gap with something plausible, as long as the last packet.

Returns: the samples.

Since: 3.00.

2.50.5. opusDecoderNew

decoder = opusDecoderNew([rate [, channels]])

Parameters:

  • rate — number: 8000, 12000, 16000, 24000, or 48000; 48000 unless given.

  • channels — number, 1 or 2; 1 unless given.

Returns: the decoder’s handle.

Since: 3.00.

2.50.6. opusEncode

packet = opusEncode(encoder, samples)

One frame of samples as one packet. A frame is 2.5, 5, 10, 20, 40, or 60 milliseconds of samples; anything else is refused.

Returns: the packet, a string.

Since: 3.00.

2.50.7. opusEncoderNew

encoder = opusEncoderNew([rate [, channels [, application]]])

Parameters:

  • rate — number: 8000, 12000, 16000, 24000, or 48000; 48000 unless given.

  • channels — number, 1 or 2; 1 unless given.

  • application — string: "voip" for speech, tuned for being understood; "audio" for music; "lowdelay" for the least delay at some cost in quality. "voip" unless given.

Returns: the encoder’s handle.

Since: 3.00.

2.50.8. opusEncoderSet

opusEncoderSet(encoder, bitrate [, complexity])

Parameters:

  • bitrate — number, bits a second; 0 leaves it as it is. A voice is clear at 16000 to 24000.

  • complexity — number, 0 to 10: how much work to spend for quality.

Since: 3.00.

2.50.9. voiceFree

voiceFree(handle)

Releases an Opus encoder or decoder, a voice processor, or a jitter buffer.

Since: 3.00.

2.50.10. voiceProcess

cleaned, voiced = voiceProcess(processor, mic [, speaker])

One frame of the microphone, cleaned: the echo of what the speakers were playing taken out, background noise suppressed, and the level evened out.

Parameters:

  • mic — string, one frame of samples from the microphone.

  • speaker — string, the same frame of what the speakers played, if anything: the voices of the other players, say. The echo of it is what is taken out.

Returns: the cleaned frame, and true when it sounds like a voice — the way to send nothing while nobody is talking.

Since: 3.00.

2.50.11. voiceProcessorNew

processor = voiceProcessorNew([frame [, rate [, tailMs]]])

Parameters:

  • frame — number, samples a call; 960 unless given.

  • rate — number; 48000 unless given.

  • tailMs — number, the longest echo to cancel, in milliseconds: how long a sound rings around the room. 200 unless given. From 1 to 2000.

Returns: the processor’s handle.

Since: 3.00.

2.51. Framework Helpers

Framework.singe defines five small helpers of its own, global like the rest of the API, which games written for earlier versions use. New code may prefer lume and inspect, from the included libraries.

Function What it does

utilDeepCopy(value)

A copy of value all the way down: a table is copied key by key, its keys, values, and metatable copied in turn; anything else comes back as it is.

utilDump(value)

value as text to print. A table becomes { ["key"] = value,}, nested tables in braces of their own; anything else goes through tostring. For a table worth reading, require("inspect") does better.

utilGetTableSize(t)

How many keys t holds, every one of them, not just the sequence #t measures.

utilOffsetTable(source, offset)

A deep copy of a table shaped like SCANCODE, { NAME = { name = NAME, value = N } }, with offset added to every value.

utilTrim(s)

s without the whitespace at either end.

2.52. Engine Callbacks

These are functions the script defines and Singe calls when the matching event happens; all are optional, and an undefined one is skipped. Input callbacks fire as events are read, onOverlayUpdate runs at most once every 15 milliseconds, and none of them runs while the pause key holds the game frozen (see Pausing). An error inside a callback ends the game with a traceback. In the threaded model singeMain takes the place of most per-frame logic (see Threaded): the other callbacks still fire, but Framework.singe installs its own onOverlayUpdate to drive the singeMain coroutine, so a threaded game defines singeMain, onShutdown and whichever input callbacks it wants.

2.52.1. onControllerMoved

function onControllerMoved(axis, value, which)
end

Called for every axis motion event from a connected controller, including motion inside the dead zone, so a stick under a thumb fires many times a second. Directions past SINGE_DEAD_ZONE also act as switches when controls.cfg maps them, so a game that only needs digital steering can map GAMEPAD_0.AXIS_LEFT_X_L and GAMEPAD_0.AXIS_LEFT_X_R and ignore this callback. The value is stored for controllerGetAxis before the callback runs.

Parameters:

  • axis — 0 through 5, matching the GAMEPAD_AXIS_* constants.

  • value — raw position, -32768 to 32767; triggers rest at 0.

  • which — controller index, 0 through 3, the index controllerGetAxis and the GAMEPAD_N tables use.

Example
-- Analog steering from the first controller's left stick only.
function onControllerMoved(axis, value, which)
    if which ~= 0 or axis ~= GAMEPAD_AXIS_LEFT_X then
        return
    end
    if math.abs(value) < SINGE_DEAD_ZONE then
        steering = 0
    else
        steering = value / 32768
    end
end

2.52.2. onInputPressed / onInputReleased

function onInputPressed(what)
end

function onInputReleased(what)
end

Called when a logical input goes down or up. What arrives depends on the keyboard mode. In MODE_NORMAL, what is a SWITCH_* value: keys, controller buttons, axis directions past the dead zone, mouse buttons and the mouse wheel all arrive this way, translated through controls.cfg, each press once with no key repeat, and inputs mapped to no switch are ignored. SWITCH_PAUSE arrives only after singeSetPauseKeyEnabled(false); otherwise the engine freezes the game on that key and the script never sees it. In MODE_FULL, what is the keysym of the key (the character value, not the scancode), repeats are delivered, and controller and mouse buttons pass 0; every event also reaches onKeyPressed and onKeyReleased, which carry the scancode or button code. When the pause key freezes the game every switch the script holds is released through onInputReleased first, and on thawing whatever is still physically down is pressed again, so a game never sees a stale button. Presses within the first second after the script starts, or after the window regains focus, are treated as held over from before and swallowed together with their release. One switch arrives from no control at all: SWITCH_MOUSE_DISCONNECT is raised by the engine when a mouse or light gun is unplugged, once as a press and immediately once as a release, so a gun game can notice its gun going (see Mice, Guns, and Who Chooses).

Example
function onInputPressed(what)
    if what == SWITCH_COIN1 then
        credits = credits + 1
        soundPlay(coinClip)
    elseif what == SWITCH_START1 and credits > 0 then
        startGame()
    elseif what == SWITCH_BUTTON3 then
        fireShot(cursorX, cursorY)
    elseif what == SWITCH_QUIT then
        singeQuit()
    end
end

function onInputReleased(what)
    if what == SWITCH_BUTTON1 then
        thrusting = false
    end
end

2.52.3. onKeyPressed / onKeyReleased

function onKeyPressed(keysym, scancode)
end

function onKeyReleased(keysym, scancode)
end

Called in MODE_FULL only, for every key going down or up, with both the logical keysym (the character the key produces on the current layout) and the physical scancode (the key’s position, compared against the SCANCODE table). Held keys repeat in this mode, which is what text entry wants. Controller and mouse buttons come through as well, with keysym 0 and their GAMEPAD_N or MOUSE_N code as scancode. For text use keysym; for key-as-button controls use scancode so the binding is the same on every layout. Keyboard mappings of the engine’s own switches do not act in this mode, so a game in MODE_FULL must provide its own way out.

2.52.4. onTextInput

function onTextInput(text)
end

Called in MODE_FULL only, with the text a key press produced — a character or a few, in UTF-8 — after the keyboard’s shift state and layout have been applied, so a capital, a quote, or a letter from a non-English layout arrives as the person typed it. onKeyPressed gives the same press as its unshifted keysym and scancode and is the one to use for keys that are commands; this is the one to use for keys that are text. A GUI with a focused text field takes the text first, and the script hears nothing of it.

Since: 3.00. See also: onKeyPressed, keyboardSetMode

Example
-- High score initials: letters as text; Return and Backspace by position.
function onTextInput(text)
    if text:match("^%a$") and #initials < 3 then
        initials = initials .. text:upper()
    end
end

function onKeyPressed(keysym, scancode)
    if scancode == SCANCODE.RETURN.value then
        finishInitials()
    elseif scancode == SCANCODE.BACKSPACE.value then
        initials = initials:sub(1, -2)
    end
end

2.52.5. onMidiMessage

function onMidiMessage(status, data1, data2, bytes)
end

Called for every message that arrives on the MIDI input port midiOpenInput opened, once per message, with the rest of the frame’s input. The three numbers are the message as a device sends it: status carries the kind in its high four bits and the channel in its low four, counting from 0, so a note on the first channel arrives as 0x90. bytes is the whole message as a string, which is what a system exclusive message needs and what a message longer than three bytes has to be read from.

Messages that arrive while no port is open are not queued; nothing is delivered from before the port was opened.

Parameters:

  • status — number; the status byte, 0x80 to 0xFF.

  • data1 — number; the first data byte, or 0 when the message has none.

  • data2 — number; the second data byte, or 0 when the message has none.

  • bytes — string; the whole message, however long it is.

Since: 3.00. See also: midiOpenInput, midiSend

Example
-- A MIDI keyboard plays the game:  middle C and up are the four fire buttons.
local MIDI_NOTE_ON = 0x90

function onMidiMessage(status, data1, data2, bytes)
    -- The kind is the top four bits; the channel in the bottom four is ignored here.
    if (status & 0xF0) == MIDI_NOTE_ON and data2 > 0 then
        local button = data1 - 60
        if button >= 0 and button <= 3 then
            fire(button)
        end
    end
end

2.52.6. onMouseMoved

function onMouseMoved(x, y, xRelative, yRelative, which)
end

Called for every mouse motion event, with the position and the motion since the previous event in overlay coordinates. In MOUSE_SINGLE mode the window’s pointer position is converted to overlay coordinates and which is always 0. In MOUSE_MANY mode each device’s relative motion is integrated into its own position, clamped to the video area, and which is the device index; an absolute device such as a tablet reports its mapped position with xRelative and yRelative of 0. The position is stored for mouseGetPosition before the callback runs, so a game may ignore this callback and poll instead. Drawing must still wait for onOverlayUpdate: keep the latest position in globals here and draw the cursor there.

Parameters:

  • x, y — position in overlay coordinates.

  • xRelative, yRelative — motion since the previous event, in overlay coordinates.

  • which — mouse index, 0 through 3.

Example
cursorX = overlayGetWidth() // 2
cursorY = overlayGetHeight() // 2

function onMouseMoved(x, y, xRelative, yRelative, which)
    cursorX = x
    cursorY = y
end

function onOverlayUpdate()
    overlayClear()
    spriteDraw(reticle, cursorX, cursorY, true)
    return OVERLAY_UPDATED
end

2.52.7. onCollision

function onCollision(nodeA, nodeB, x, y, z, speed)
end

Called once for each new contact between two bodies after a physics step, never again for a pair that stays in touch. A crate landing, a ball hitting the cabinet, the player’s car clipping a wall. Contacts with triggers report through onTrigger instead. The events of a step are delivered together after it, before the frame is drawn.

Parameters:

  • nodeA, nodeB — the two bodies' nodes.

  • x, y, z — where they touched, in world units.

  • speed — how fast they met, in world units per second.

Since: 3.00. See also: onTrigger, bodyNew

Example
-- Hard landings make noise where they happen.
function onCollision(nodeA, nodeB, x, y, z, speed)
    if speed > 4 and (nodeA == crate or nodeB == crate) then
        local channel = soundPlay(thudClip)
        if channel >= 0 then
            soundSetPosition(channel, x, y, z)
        end
    end
end

2.52.8. onTrigger

function onTrigger(trigger, other, entered)
end

Called when a body enters or leaves a trigger made with bodySetTrigger, once on the way in and once on the way out, whatever the shapes involved (a mesh or compound shape touching in several places still counts as one body). Triggers never push anything, so this is the way to notice a body crossing a doorway, reaching a checkpoint or falling into a kill volume.

Parameters:

  • trigger — the trigger body’s node.

  • other — the node that entered or left it.

  • entered — true on the way in, false on the way out.

Since: 3.00. See also: bodySetTrigger, onCollision

Example
function onTrigger(trigger, other, entered)
    if trigger == finishLine and other == playerCar and entered then
        lap = lap + 1
        soundPlay(lapClip)
    elseif trigger == pit and entered then
        respawn(other)
    end
end

2.52.9. onNavArrived

function onNavArrived(agent)
end

Called when a navigation agent reaches the target navAgentMoveTo gave it, once per arrival, after the navigation update of the frame. Send the agent somewhere else, or play its idle animation. A script that would rather poll can call navAgentIsArrived instead.

Parameters:

  • agent — the handle from navAgentNew.

Since: 3.00. See also: navAgentMoveTo, navAgentIsArrived

Example
-- Patrol between waypoints forever.
function onNavArrived(agent)
    local guard = guards[agent]
    if guard then
        guard.waypoint = guard.waypoint % #guard.route + 1
        local next = guard.route[guard.waypoint]
        navAgentMoveTo(agent, next.x, next.y, next.z)
    end
end

2.52.10. onOverlayUpdate

function onOverlayUpdate()
    return OVERLAY_UPDATED
end

The one callback where drawing is allowed. Singe calls it at most once every 15 milliseconds while the game is not frozen, counted from when the previous call began, so the time the script itself takes falls inside those 15 milliseconds rather than being added to them; any overlay*, spriteDraw, videoDraw, fontPrint or similar call made elsewhere will not appear on screen and may corrupt the overlay. Return OVERLAY_UPDATED (1) when the overlay changed so that Singe composites it over the video again, or OVERLAY_NOT_UPDATED (0) when nothing changed so the previous composite is reused; returning nothing counts as OVERLAY_NOT_UPDATED. The display is redrawn regardless whenever a new video frame arrives or a 3D scene is enabled, so the return value is an optimization for static screens. After it returns the engine clears the values behind keyboardGetLastDown and keyboardGetLastUp. In the threaded model Framework.singe defines this function itself to resume singeMain and always returns OVERLAY_UPDATED; do not define it as well.

Returns: OVERLAY_UPDATED or OVERLAY_NOT_UPDATED.

Example
function onOverlayUpdate()
    if not hudDirty then
        return OVERLAY_NOT_UPDATED
    end
    overlayClear()
    fontPrint(20, 20, "SCORE " .. score)
    fontPrint(20, 44, "LIVES " .. lives)
    spriteDraw(reticle, cursorX, cursorY, true)
    hudDirty = false
    return OVERLAY_UPDATED
end

2.52.11. onShutdown

function onShutdown()
end

Called once when the script ends, whether by singeQuit, the quit switch, the window closing, scriptExecute or scriptPush, after the last frame and before the Lua state is discarded. It is not called by singeReload. Save settings and free the sprites, sounds, fonts and videos the script loaded here; the engine stops every sound and frees whatever is left afterward, so a missed handle is not a leak, but explicit unloading keeps the shutdown order under the script’s control. Do not call singeQuit from here.

Example
function onShutdown()
    saveHighScores()
    spriteUnload(reticle)
    fontUnload(hudFont)
    soundUnload(shotClip)
    soundUnload(coinClip)
end

2.52.12. onSoundCompleted

function onSoundCompleted(channel)
end

Called with the channel number each time a channel stops: when its clip ends, when the last loop finishes, and when soundStop or soundFullStop halts it, so a script that chains sounds from here should know which channels it stopped itself. The mixer notes the stop on its own thread and the engine delivers the callback on the game thread between frames; while the pause key holds the game frozen the notices wait, and they are dropped when a script ends or reloads. Up to 64 completions are queued between frames; more than that in one frame are lost.

Parameters:

  • channel — the channel number the soundPlay call returned.

Example
-- Play the music playlist in order, forever.
function onSoundCompleted(channel)
    if channel == musicChannel and not musicStopped then
        track = track % #playlist + 1
        musicChannel = soundPlay(playlist[track])
    end
end

2.52.13. singeMain

function singeMain()
    while true do
        singeYield()
    end
end

The threaded model’s entry point. When a script defines it, Framework.singe wraps it in a coroutine and installs an onOverlayUpdate that resumes the coroutine once per frame, so the function runs as a straight line of game logic that calls singeYield() (an alias of coroutine.yield) wherever it wants to let a frame pass. Everything drawn before a yield lands on that frame’s overlay. Returning from singeMain calls singeQuit; an error inside it ends the game with a traceback. The input, sound, physics and navigation callbacks still fire between resumes, so a threaded game may mix them with polling.

Example
function singeMain()
    showTitle()
    while credits == 0 do
        singeYield()
    end
    for level = 1, #levels do
        playLevel(levels[level])
        if lives == 0 then
            break
        end
    end
    showGameOver()
end

2.53. Hypseus Compatibility

Everything in this section exists so that a game written for Hypseus Singe runs unchanged. None of it is recommended for a new game. Prefer the Singe call each entry names: it is the one that will keep gaining features, and it does not carry another engine’s scales, argument orders or fixed answers.

Hypseus Singe registers a few names in its engine that Singe answers from Singe/Framework.singe instead, so that a game written for Hypseus runs unchanged. Each one is defined only when the engine does not already provide it, so a future engine implementation wins. keyboardCatchQuit is documented under Keyboard; setOverlayLinearScale and setOverlayOnTop are real engine calls under Overlay; mainBezelLoaded and the seven scoreBezel calls are real engine calls under Bezel; getFValue, ratioGetX and ratioGetY are real engine calls under Command Line; joyMouseEnable is a real engine call under Joystick; allowSocketCall and getUserString are real engine calls under Singe, and drawTransparent under Sprite; and the whole music family is now a set of real engine calls under Music. The six spriteAnim names below are plain aliases set after the legacy sprite wrapping, so they take whichever argument order the rest of the sprite family is taking: Hypseus’s own (handle last) under LEGACY_SPRITE_ARGS, and Singe 3.00’s (handle first) without it.

Function Provided by Framework.singe as

setOverlaySize(preset [, width, height])

overlaySetResolution with a chosen size: 1 is the disc’s video size, 3 is 360x240, 4 is the size given (ignored when it is missing, as in Hypseus) and anything else, 2 included, is half the disc on both axes. Without a disc discGetWidth and discGetHeight report the canvas, which is what a disc-less game draws into.

setOverlayResolution(width, height)

An alias of overlaySetResolution. Hypseus registers one function under both names.

rewriteStatus()

Stub returning false. In Hypseus it reports whether asset paths are being rewritten for an -espath install; Singe’s virtual file system finds a game’s files where they were installed, so nothing is rewritten and the game keeps its own asset directory.

hypseusGetHeight()

An alias of singeGetHeight.

hypseusGetWidth()

An alias of singeGetWidth.

takeScreenshot()

An alias of singeScreenshot. Hypseus refuses a second screenshot within five seconds; Singe has no such throttle.

mouseHowManyReal()

An alias of mouseHowMany. Hypseus counts real mice apart from the ones it derives from a gamepad; Singe has no derived mice, so its count is already the real one.

spriteAnimGetFrame(spr)

An alias of spriteGetFrame.

spriteAnimIsPlaying(spr)

An alias of spriteIsPlaying.

spriteAnimLoop(loop, spr)

An alias of spriteLoop.

spriteAnimPause(spr)

An alias of spritePause.

spriteAnimPlay(spr)

An alias of spritePlay.

spriteAnimSetFrame(frame, spr)

An alias of spriteSetFrame.

2.54. Unimplemented and Legacy

A handful of API functions are retained for script-level compatibility, and those marked No-op do nothing. They are safe to call; they simply log a trace message and return. Prefer the listed replacements for new code.

Function Status Replacement

discChangeSpeed

No-op

 — (was for variable-speed playback on real LD hardware)

discSearchBlanking

No-op

 — (was screen-blanking during seek on real LD hardware)

discSkipBlanking

No-op

 — (same reason)

discSetFPS

No-op

Framerate is read from the video file.

vldpGetHeight

Works

discGetHeight

vldpGetWidth

Works

discGetWidth

vldpSetVerbose

No-op

 — 

colorBackground(r,g,b)

Works

Prefer the 4-argument form, colorBackground(r, g, b, a).

colorForeground(r,g,b)

Works

Prefer the 4-argument form, colorForeground(r, g, b, a).

daphneGetWidth / daphneGetHeight / daphneScreenshot

Aliases in Framework.singe

Prefer the singe* equivalents.

discPauseAtFrame

Works (alias)

discSearch.

In addition, Framework.singe rebinds random = { new = math.random } so that pre-2.00 scripts using random.new() still work. New code should use math.random directly.