1. About Singe
Singe (Scott’s Increasingly Nifty Game Engine, and named after the dragon in Dragon’s Lair) is a Lua-based scripting system that allows for rapid prototyping of new laserdisc games, or the creation of entirely new games. The language is easy to learn, very powerful, and fast. All the features needed to develop your own game are made available through a simple application programming interface (API).
Singe provides numerous features to the game developer. Some of the more interesting ones are:
-
3D scenes with models, animation, lighting, and shadows
-
Physics, including joints, ragdolls, soft bodies, and vehicles
-
Menus, option screens, and HUDs built like web pages
-
Hardware video decoding, even on small machines
-
Online high scores, and a catalogue of games to download and update
-
Games packed into a single file
-
Object-oriented programming language
-
Animated sprites
-
TrueType font support
-
32-bit color space with transparency
-
Multi-channel, overlapping, stereo sound, and MIDI
-
Analog and digital input device support, including light guns
-
Wide support for video and audio formats
Singe runs on Windows, macOS, and Linux, on ARM processors as well as Intel and AMD ones: Windows on ARM laptops, the Raspberry Pi, and handhelds like the R36S.
For players, Singe allows many unemulated and new games to be enjoyed using any desired front end or via the included menu system.
Since the original release of Singe back in 2006, several revisions have been released, both officially and unofficially. In 2020, Singe 2.00 was released. This was a total rewrite from the ground up, adding numerous features while staying compatible with existing 1.xx games. Singe 3.00 adds 3D, physics, user interfaces, and much more, while still running the games that came before it. As of the writing of this manual, the latest release is 3.00b1.
2. Installation and Upgrading
2.1. Installing Singe
To install Singe, simply download the appropriate binary for your system. Place
it in a new folder by itself and run it. On the first run, Singe will create
all the necessary directories and support files needed. You are now ready to
install some games. On a Windows PC with an ARM processor, take the Windows-aarch64 build: the
Windows-x86_64 one runs there too, emulated, but more slowly.
2.2. Upgrading Singe
To upgrade Singe to a newer version, place the new binary in the installation
folder beside the old one and run it once with --refresh. The support folder
that is there is set aside as old-Singe-<version>, named for the version that
wrote it, and a fresh Singe/ folder is written in its place. Nothing is
deleted: the folder that was set aside is yours to keep or remove, and a second
--refresh sets its own aside as old-Singe-<version>-1 rather than writing
over the first.
The old binary can stay where it is. Menu.sh (or Menu.bat) runs the newest
Singe it finds beside itself, and a beta counts as older than the release of the
same number, so Singe-v3.00b2 gives way to Singe-v3.00 the moment it
arrives. The menu’s Engine Update tool does all of this for you; see
The Service Tools.
Do not run a new Singe binary against an out-of-date set of support
files. Always refresh the Singe/ directory when upgrading.
|
2.3. Things to Know
Do not touch the Singe/ folder. Files in this folder belong to Singe and may
be updated or deleted at any time.
3. Playing Games
3.1. Installing Games
A game is either a single .game file or a directory. Copy it into the same
folder where you placed the Singe binary. The included menu system will
automatically detect it and add it to the menu.
3.2. Game Directory Layout
A Singe installation is a game directory containing the Singe support
directory the engine creates on first run, one directory per game, any
packed .game files, and a data directory for everything the games and
the engine write. The executable usually sits there too, but need not:
--gamedir names the game directory from anywhere, and the Menu.sh (or
Menu.bat) the engine writes there then runs the executable by its full
path. Otherwise the launcher searches beside itself for the files whose
names begin with Singe and runs the best of them, in the spirit of the
launchers BatMaker writes, so an upgrade that changes the executable’s
version in its name does not leave a launcher pointing at a file that is no
longer there.
Best means this machine’s architecture first and the version after it. The
platform in the name is compared against what the system reports, because a
newer build for another architecture cannot run at all, and one game directory
on a share can be read by a Pi and a PC alike. The launcher works this out when
it runs rather than being told once, so the same directory is right for every
machine that opens it. On a Mac a universal build counts as native. Among the
builds this machine can run, the newest wins: Singe-v3.10 beats
Singe-v3.09, and a beta loses to the release it leads up to, so
Singe-v3.00b2 loses to Singe-v3.00. A build for another architecture is
still run when it is the only one there, since a real complaint from the engine
beats being told nothing was found, and so is a name the launcher cannot read
at all.
Singe/ Support files extracted by the engine
Framework.singe Loaded by every game (dofile it)
Menu.singe The bundled game menu
Tools.singe The menu's service tools (see The Service Tools)
MenuDocument.singe The menu drawn as a GUI document
MenuOverlay.singe The menu drawn into the overlay, for a machine with no GPU
Backdrop.singe The menu's intro and the grid behind it, drawn live
menuBackground.mkv The same backdrop recorded, for a machine with no GPU
menuIntro.flac Its sound, which fades out as the menu takes the screen
Menu.rml The document renderer's RmlUi document
menu.rcss Its style sheet, on top of gui.rcss
gui.rcss The shipped GUI theme
controls.cfg.example Template for input mappings
click.wav Used by the menu's audio delay and sound tests
Manual.pdf This manual
Manual-fr.pdf This manual in French
Manual-it.pdf This manual in Italian
Manual-de.pdf This manual in German
Manual-es.pdf This manual in Spanish
COPYING The GNU General Public License, version 3
LICENSES Third-party notices and asset credits
Collection/ A directory of games
games.dat Menu entries for the games in this directory
AsteroidPatrol.singe A script
frame_AsteroidPatrol.txt Its framefile (or a video with the same base name)
sprite_*.png, sound_*.wav, font_*.ttf
MyGame.game A game packed into one file (see Single-File Games)
data/
machine.cfg This machine's audio delay and picture geometry
Collection/ Indexes, trace.txt, screenshots, saves for those games
Where Singe looks for a script’s files, and where a script may write, is a matter for whoever writes the script; the Singe Reference covers both under Packaging Your Game.
3.3. The Bundled Menu
Menu.sh (or Menu.bat) starts Singe/Menu.singe, the bundled menu: an
RmlUi document, Singe/Menu.rml styled by Singe/menu.rcss, drawn over a
live 3D backdrop (see GUI). The menu runs without a
disc; a machine with no GPU plays Singe/menuBackground.mkv, a recording of
the same backdrop, behind a simpler page drawn on the overlay instead. It reads the games.dat of every game
directory and .game file beside it and lists every game it finds, sorted by
title, down the left of the screen. Beside the list are the selected game’s
cabinet art, its marquee and its attract clip, with the year, genre,
platform, developer, publisher, port credits and description underneath and
a line of key hints along the bottom.
Up and down move the selection one game at a time and left and right move it
a page at a time; both wrap from either end of the list to the other. Start
or any action button launches the selected game, and the key mapped to
INPUT_SERVICE (the 9 key by default) opens the service tools (see
The Service Tools). With a mouse, a
click on a row selects that game and a second click on the same row launches
it; the mouse wheel scrolls a description too long for its panel. If you set
--quitchord, holding those buttons quits a game back to the menu, and quits
the menu back to your system (see Handhelds and Small Machines). The menu keeps its selection
in menu.dat in its data directory, so it comes back to the same game when
one quits or when Singe is next started. That file is a Lua fragment the menu
reads at startup and rewrites at shutdown: GAME_SELECTED is the game it was
showing, SHOW_INTRO is false when it is returning from a game so the intro
is not sat through twice, and MENU_OVERLAY chooses a renderer (see
The two renderers).
Not every machine runs every game. A 3D game on a box with no 3D, or a heavy
game on a small one, would fail or crawl, so the menu tells you first. When you
select a game this machine cannot run, the line under its details says what it
needs ("Needs 3D, and this machine has none."), and starting it just repeats
that instead of failing part way in. A game that wants more machine than this
one gets "It may run slowly." and starts anyway. Nothing is hidden. The menu
works out how fast this machine is the first time its intro plays, by timing
its own backdrop, and keeps the answer in machine.cfg; it never asks you to
run a benchmark. Games say what they need in their games.dat
(REQUIRES and TIER), and the Get Games tool marks
the catalogue the same way.
3.3.1. The Two Renderers
A GUI document is drawn through the GPU device the 3D scene uses, so on a
machine without one there is no document to build. The menu handles that
itself: Singe/Menu.singe asks singeHasGpu at startup and
loads one of two renderers.
Singe/MenuDocument.singe-
The RmlUi document described above, for a machine with a GPU device. It also draws the intro and the grid behind the menu as one continuous 3D scene, so the disc is not used for either.
Singe/MenuOverlay.singe-
Sprites and
fontPrintstraight into the overlay, the look Singe 2 had. It needs nothing beyond the overlay every game already draws into.
Both draw the same menu, take the same keys and run the same service tools;
Singe/Menu.singe holds everything that is not drawing — the game list, the
selection, launching a game — so there is one menu rather than two. The
overlay renderer shows one game at a time instead of a list, since it has no
panel to scroll, and it clips a description too long for its column rather
than scrolling it.
To see the overlay renderer on a machine that does have a GPU, put
MENU_OVERLAY = true in menu.dat in the menu’s data directory; the menu
writes the line back out, so it survives. That is how the overlay path is
tested, and how a cabinet builder who prefers the old look gets it.
3.3.2. Online: Accounts, Games, and Scores
The bundled menu can sign the cabinet in to a master service (by default
master.singeengine.com), which does three things: it holds the account, it
offers a catalogue of games to download and update, and it keeps high score
boards.
Two service tools cover it. Online Account signs in, creates an account,
recovers a password, and sets the server address — it is where an operator
running their own service points the cabinet. A new account is not usable until
the code the service emails is typed into the tool; a forgotten password is
replaced the same way, with the emailed code and a new password. A password
being set is typed twice, under password and confirm. Get Games lists everything the
service offers, marks what is installed here, and downloads, updates or removes
it. A download that holds several games — a collection, or one game in two
languages — puts every one of them in the list under its own name, saying which
download it comes in, and fetching or removing any of them fetches or removes the
lot, since they are one file. What is offered depends on the account: a service
can keep a game for particular accounts, so two cabinets signed in to different
accounts may see different lists. The menu itself says when a newer version of an installed game exists: the
game wears an update mark in the list, the line under its details names the
version, and button 3 on that page fetches it, so a cabinet need not open a
service tool to stay current. Nothing about this machine is kept anywhere: the
menu reads the version out of each game’s own games.dat and asks about its own
list, so a game copied in by hand is known as well as one downloaded here. A
cabinet with no games at all still opens the menu, which says how to fetch some,
and whatever Get Games downloads or removes is in the list as soon as the service
tools close. A list longer than the screen scrolls with the selection rather than running
off the bottom, with … showing there is more either way. A game that stops being offered keeps working and is shown as "installed,
no longer offered": all that stops is being given an update, because a player
who has a game has it. A download is checked against the digest the catalogue published before it
replaces anything, so a transfer that arrives wrong fails rather than installing
a game that will not run.
The account belongs to the machine, not to a game: the token is kept in
master.dat in the data root, so a game posting a score uses the same sign-in
the menu made. The password is never kept, and the file is scrambled, so the
token and the account’s address cannot be read out of it at a glance; an edited
file reads as signed out. The machine has to be able to read it back unattended,
so treat master.dat like a key to the account all the same: copied to another
machine, it signs that machine in. Posting a score needs that account, but reading a board does not:
a cabinet that is not signed in still shows a game’s online board, where the
game shows one, for any game the service offers to everyone. See Online high scores for the game’s side, and
Singe/Net.singe for the asynchronous HTTP client underneath — nothing here
blocks a frame, because Lua in Singe is cooperative and a large download would
otherwise look like a hang.
Singe checks the server’s certificate against two lists at once: the one it
ships with and the one your machine keeps. Either one vouching for the server
is enough, so an old copy of Singe can still reach the update that replaces it
as long as your system keeps its own list current. Running your own service
with a certificate from your own authority? Put that authority’s certificate in
cacerts.local.pem in the data folder. Singe never writes that file, so it
survives updates. If a connection is refused, the message says which lists were
checked, and a certificate that is "not yet valid" almost always means the
machine’s clock is wrong.
3.3.3. The Service Tools
The key mapped to INPUT_SERVICE opens a list of tools over the game list.
Up and down choose one and button 1 opens it; button 2 backs out of a tool to
the list, and the service key again leaves the tools altogether. Everything
lives in Singe/Tools.singe, which the engine extracts beside Menu.singe.
Nothing there draws: a tool builds a list of rows and hands it to the menu,
which is why every tool runs on both renderers (see
The two renderers). Nothing here needs a game to be running,
and nothing changes a game’s own files.
- Audio Delay
-
The downstream audio delay, measured against a click and a flash. See Calibrating from the menu for what it is doing and why it works.
- Input Test
-
Every controller, mouse and gun the engine can see, live: the last switch the game would have received and how many have arrived, each pad’s name with its six axes and the buttons held down, and each mouse’s name and position. This is the screen that answers "the button does nothing" — either the switch arrives and the game ignores it, or it never arrives at all.
- System Information
-
The engine’s version, the operating system, the processor and memory, the renderer and the 3D device, which video decoders are in play, the audio formats built in, the SoundFont, the MIDI state, the window, canvas and overlay sizes, and the data directory. A photograph of this page answers most of a bug report.
- Light Gun
-
Targets in the center and at each corner of the overlay, over whatever the disc is showing. Button 1 marks where the gun actually pointed, keeping the last twelve shots; start clears them. A gun that is square on the picture puts its crosses on the targets, and one that is not shows which way it is out.
- Sound Test
-
Button 1 plays the click through the left speaker, then the right, then both, which is the whole of a crossed-wires check. It also lists the disc’s own audio tracks, and left and right switch between them.
- Display
-
The picture’s size, position and rotation, changed live with the arrows, buttons 3 and 4, and coin 1, over a test pattern: a 16 by 12 grid to square the picture up with, an eight step grayscale wedge to set brightness by, and two frames one pixel apart at the very edge — a monitor that overscans eats the outer one first. Button 1 keeps the values for this machine, in the same
machine.cfgthe audio delay uses, so they apply to every game rather than being set once per game. Start puts everything back. - Disc Test
-
Twelve seeks spread over the whole disc, each timed. A rip whose keyframes are far apart seeks slowly, and the only symptom in a game is that everything feels heavy; this measures it directly and reports the worst of the twelve. A seek that has not landed in three seconds is counted as that.
- Saved Data
-
What each game has kept, found by looking through the data root rather than by being told, with the size of each. Button 3 — not button 1, which is "choose" everywhere else — throws away the selected game’s save. Clearing a high score table without deleting the game is the usual reason.
- Engine Update
-
A newer Singe, when the service has one for this machine. A beta is versioned
3.00b2, the second beta of 3.00, and comes before 3.00 itself, so a cabinet running a beta is offered the release the day it is published. Shows what is running and what is offered, and button 1 fetches it, checks it against the digest the service published, puts it beside the running Singe under the release’s own name, sets the old one aside asold-<name>, and restarts into it. Setting the old one aside can be refused, by a folder this user cannot write or by a scanner holding the file; Singe says so and carries on, since the launcher runs the newest Singe in the folder either way. If the new Singe will not start, the old one goes back under its own name and the new one is kept asfailed-<name>, which the launcher does not run. The new Singe starts with--refresh, so the support folder is rewritten by the version that now owns it and the old one is kept asold-Singe-<version>; a file an older Singe shipped and this one does not cannot linger to confuse a game. Nothing happens until that button. Button 3 asks the service again. The menu looks once a day on its own and says so in a line under the game’s details;no_update_check = trueinsettings.cfgstops the daily look, and the tool still works by hand. - Online Account
-
Signing this cabinet in to the master service, creating an account, recovering a password, and setting the server address. See Online: accounts, games and scores.
- Get Games
-
The catalogue: what the service offers, what is installed here, and downloading, updating or removing it.
- MIDI Ports
-
The input and output ports this machine has, which of them Singe has opened, and the last few messages that arrived. Button 1 sends a note, button 3 looks for ports again after something has been plugged in. Nothing is opened until this tool asks, so a cabinet that never touches MIDI never pays for it.
- Frame Statistics
-
Turns the developer’s overlay on and off. It stays on into the game, in the top left corner. See statsEnable.
4. Controls
By default, Singe maps controllers as if they were Xbox gamepads. If your controller is not recognized or you wish to change the default mappings as they appear to Singe, you can use the free SDL2 Gamepad Tool from http://generalarcade.com/gamepadtool/.
4.1. controls.cfg
In addition to configuring your controller, you can remap all the input options
for Singe as a whole or for any individual game by using controls.cfg files.
When determining how inputs are mapped, Singe reads configuration settings in
the following order, and a later file replaces an earlier one input by input
(see Where Configuration Files Are Read From):
-
The defaults from inside Singe.
-
controls.cfgfrom the game’s main script directory: what the game’s author shipped. -
controls.cfgfrom the directory Singe was started in: the machine’s own (theSingedirectory holds acontrols.cfg.exampletemplate you can copy). -
controls.cfgfrom the directory above the game’s data directory. -
controls.cfgfrom the game’s data directory: yours, for that one game.
You do not have to specify every option in a custom controls.cfg file. Feel
free to just provide the entries you want changed.
After installing Singe, you can find a sample input configuration file at
<InstallDir>/Singe/controls.cfg.example. To see the available configuration
options available to be used in this file, read through
<InstallDir>/Singe/Framework.singe.
--keymapfile names one file to read instead of making that search, which is
useful to a front end that wants no doubt about which mappings a game got.
Each INPUT_ entry is a list, and any one thing in it works the switch. A list
inside that list is a chord: two to four keys or buttons held together, which
works the switch when the last of them goes down and lets go when any of them
comes up. A handheld with no Escape key quits on Select and Start together
this way:
INPUT_QUIT = { SCANCODE.ESCAPE, { GAMEPAD_0.BUTTON_BACK, GAMEPAD_0.BUTTON_START } }
Each key or button in a chord keeps its own meaning too, so pressing Select and Start to quit this way also drops a coin and presses Start on the way out.
If you want a way to quit that always works, use --quitchord instead. When
you press one of its buttons, Singe waits a quarter of a second for the rest
before doing anything else, so quitting does not drop a coin or press Start. A
game can turn its own quit key off, but it cannot turn off --quitchord.
4.2. Every Device Is a Gamepad
Singe has one family of controller, GAMEPAD_0 through GAMEPAD_3, and every
device it opens is in it. SDL calls a device a gamepad only when it has a
mapping for it, and an arcade encoder board, a spinner, a wheel or a flight
stick often has none. Rather than carry a second kind of device with its own
names, Singe writes a mapping for such a device itself and then opens it as an
ordinary gamepad, so it reaches controls.cfg, controllerGetAxis,
controllerGetButton and every INPUT_* switch exactly as a recognized pad
does.
The mapping Singe writes is a straight-through one: the device’s axes in order
become the left stick, the right stick and then the two triggers; its buttons
in order become BUTTON_A, BUTTON_B, BUTTON_X, BUTTON_Y, BUTTON_BACK,
BUTTON_GUIDE, BUTTON_START, BUTTON_LEFT_STICK, BUTTON_RIGHT_STICK,
BUTTON_LEFT_BUMPER and BUTTON_RIGHT_BUMPER; and its first hat becomes the
D-pad. A device with no hat spends its next four buttons on the D-pad instead.
A device with more controls than the gamepad model can name loses the
extras — more than six axes, more than fifteen buttons, or a second hat — and a device whose buttons are not wired in that order will have them in the
wrong places. That is the price of one family instead of two, and it is
straightforward to correct: --program traces the mapping it wrote, in SDL’s
own format, so you can paste it into a gamecontrollerdb.txt, rearrange it and
have it used instead.
--mapjoysticks=false turns the writing off, in which case a device SDL does
not recognize is not opened at all, exactly as in earlier releases.
4.3. gamecontrollerdb.txt
SDL ships with a large database of controller mappings, and the community keeps
a larger one — gamecontrollerdb.txt, from
https://github.com/mdqinc/SDL_GameControllerDB. Singe looks for that file in
the same four places it looks for controls.cfg, in the same order (see
Where Configuration Files Are Read From):
-
the game’s main script directory;
-
the directory Singe was started in;
-
the directory above the game’s data directory;
-
the game’s data directory.
Every file found is loaded, in that order, so the machine’s file wins over one
a game ships, a file in the game’s data directory wins over both, and all of
them win over SDL’s own database. Only a device that none of them names gets
the mapping Singe writes for it: that one is the last resort, never a rival to
your files. --program reports how many mappings each file added.
The files also beat SDL_GAMECONTROLLERCONFIG, the environment variable SDL
takes mappings from, which some handheld systems set for their built-in pad.
ArkOS’s mapping for the R36S, for instance, leaves Select and Start out, so no
game sees them; a line in gamecontrollerdb.txt for the same pad puts them
back. SDL reads the variable once, when Singe starts, so this holds for the
files the first game finds. A game started later from the menu still reads its
own, but a pad the variable names keeps the variable’s mapping.
A line of that file looks like this, and is exactly what the trace prints for a device Singe mapped itself:
ff00d87a475300004900000000007603,Arcade Encoder,platform:Linux,a:b0,b:b1,x:b2,y:b3,back:b4,guide:b5,start:b6,leftx:a0,lefty:a1,dpup:h0.1,dpright:h0.2,dpdown:h0.4,dpleft:h0.8,
4.4. Dead Zones and Triggers
DEAD_ZONE in controls.cfg is how far an axis must move before it counts as
a pressed switch, in the raw units SDL reports: 32767 at full deflection, so
the default of 15000 is a little under half way. It covers every axis of
every pad, the two analog triggers included, and a script reads it as
SINGE_DEAD_ZONE.
Two settings narrow that down.
DEAD_ZONES is a list of { axis, dead zone } pairs for one axis at a time,
in those same raw units, for a stiff stick or a worn trigger that should not
move everything else:
DEAD_ZONES = {
{ GAMEPAD_0.AXIS_LEFT_X, 8000 },
{ GAMEPAD_1.AXIS_LEFT_TRIGGER, 30000 },
}
The axis may be written as the axis itself or as either of its two directions
(GAMEPAD_0.AXIS_LEFT_X, AXIS_LEFT_X_L and AXIS_LEFT_X_R all name the same
axis). Anything not listed keeps DEAD_ZONE.
TRIGGER_THRESHOLD is how far an analog trigger must travel before it counts
as a button, as a percent of full travel, which is the unit Hypseus’s
-trigger-threshold uses and whose default there is 99.5. It applies to both
triggers of all four pads. Singe’s default is 0, meaning the triggers stay on
DEAD_ZONE, so nothing changes for anyone who does not ask; a script reads the
result in raw units as SINGE_TRIGGER_THRESHOLD. The two units convert
directly: a percent is 32767 / 100 raw units, so Singe’s DEAD_ZONE of
15000 is 45.8 percent and Hypseus’s 99.5 percent is 32603 raw units.
--trigger_threshold sets the same number from the command line and wins over
controls.cfg; DEAD_ZONES wins over both, being the most specific.
4.5. Driving the Mouse with a Stick
A light gun game on a cabinet with a stick and no mouse is unplayable unless
the stick can move the cursor. --joymouse makes it do so: the left stick of
gamepad slot 0 moves the pointer the game sees, through the same
onMouseMoved a real mouse reaches, and the cursor is held inside the picture.
--js_range is the speed, 1 to 20 with 5 the default, measured in video
pixels a frame at full deflection, so 5 crosses a 720 pixel picture in about
two seconds. The axis obeys its own dead zone, so a drifting stick does not
creep.
It is off by default, which is where Singe differs from Hypseus: the shipped
controls.cfg already binds that stick to INPUT_UP, INPUT_DOWN,
INPUT_LEFT and INPUT_RIGHT, and having it drive the cursor as well without
being asked would surprise every existing game. --joymouse=false is
Hypseus’s -nojoymouse, and a script turns it on and off with joyMouseEnable
and reads it with joyMouseIsEnabled. A reload puts it back where the command
line left it.
4.6. Mice, Guns, and Who Chooses
mouseSetMode(MOUSE_MANY) is a game’s decision to tell up to four mice apart,
which a two-gun cabinet needs and which a game that never makes the call cannot
be given. --manymouse is the user’s decision and outranks it: the mode is on
from the start and mouseSetMode(MOUSE_SINGLE) no longer switches it off.
--absolutes_only keeps only the devices that report an absolute position,
which is what a real light gun does and an ordinary mouse does not, so a
cabinet with two guns and a desk mouse plugged in is not confused by the mouse.
Be aware of how it decides: ManyMouse, the backend Singe uses to tell mice
apart, offers no way to ask a device what kind it is, so a device counts as
absolute once it has reported an absolute position and not before. A gun does
that with its first movement; until then it is silent, and a relative-only
device stays silent for good. The option is therefore a filter by observed
behavior rather than by device class, and on a machine where no device ever
reports an absolute position it silences every mouse.
SWITCH_MOUSE_DISCONNECT is a switch like any other, except that no key or
button produces it: the engine raises it when a mouse or a light gun is
unplugged, once as a press and once as a release, so a gun game can say so on
screen instead of appearing to have died. It is Hypseus’s switch of the same
name. controls.cfg leaves it bound to nothing; bind a key to it as well if
you want to see what a game does without pulling a cable.
4.7. Hotkeys
Alt-Enter switches between full screen and a window while the game runs, as
it does in Hypseus. The game never sees the key. A window that started in
exclusive full screen (--fullscreen) returns to it in the display mode it was
given; one that started windowed gets a borderless window covering the desktop.
Nothing else has to change with it: the renderer presents a logical size in
video coordinates and scales that to whatever the window now is, the video
rectangle is built in those same coordinates, and the rotation target is the
size of the picture rather than of the window, so the picture, the overlay, the
GUIs and the mouse mapping all follow by themselves.
The other switches a user can press — quit, pause, screenshot, recording, the
console and the mouse capture toggle — are ordinary controls.cfg mappings and
are described with the INPUT_* names in the sample file.
4.8. Recording Video
F10 starts recording the game, picture and sound together, and F10 again
stops it. Each recording is a new singeNNN.mp4 in the game’s data directory,
beside the screenshots, and plays in anything that plays an MP4. The picture is
the whole window as you see it, letterbox included, and the sound is everything
the game plays: music, sound effects, and the video’s own soundtrack.
Where the machine has a hardware video encoder Singe uses it, so recording costs
the game very little: H.264 through VA-API on Linux, VideoToolbox on macOS, Media
Foundation on Windows, and V4L2 on the ARM boards that have one. Anywhere else it
records MPEG-4 instead, which plays everywhere but makes bigger files. The
Recording line in the trace says which it used. A machine too slow to keep up
drops frames from the recording rather than slowing the game down, and the trace
says how many when the recording stops.
To record a whole run instead, start Singe with --record=FILENAME. Add
--deterministic and Singe records every frame and the exact sound that goes
with it, however long each frame takes to make, without playing anything through
the speakers. That is how to make a perfect video of a demo or an attract mode:
it usually runs faster than real time on a desktop.
5. Settings and Options
Almost everything you can put on the command line can also go in a settings file. Set things up once and every game uses them.
5.1. The Settings File
Almost everything on the command line can also be written down once, in a
settings.cfg file, so a cabinet does not need a launcher script carrying the
same dozen options for every game. It is Lua, like controls.cfg, and Singe
looks for it in exactly the same four places, in this order:
-
settings.cfgfrom the game’s main script directory. -
settings.cfgfrom the directory Singe was started in (theSingedirectory holds asettings.cfg.exampletemplate you can copy). -
settings.cfgfrom the directory above the game’s data directory. -
settings.cfgfrom the game’s data directory.
Each place is read once, and a later file wins key by key, so a machine-wide file can set the display and the volumes while a file in one game’s data directory turns off that game’s crosshair. You do not have to write every key in a file; write the ones you want changed.
Every key is the long name of a command line option with the leading dashes removed, so there is no second vocabulary to learn:
-- The cabinet's own settings.cfg
screen = 2 -- the second monitor
fullscreen = true
volume_vldp = 80
haptic = 0 -- this cabinet has no rumble
idleexit = 900 -- hand the screen back after fifteen quiet minutes
startsilent = true
An option that takes no value on the command line takes true or false here
(yes, no, on, off, 1 and 0 are accepted too). Setting one to false
is the same as leaving it out. An option that takes a value takes the same value
it would on the command line, as a number or a string.
One option, --deterministic, takes a value or leaves it out, and its key does
the same: deterministic = true uses the default step, deterministic = 20
names one, and deterministic = false leaves the option off.
5.2. Where Configuration Files Are Read From
controls.cfg, settings.cfg and gamecontrollerdb.txt are all looked for in
the same four places, in the same order, and a file read later wins over one
read earlier:
-
The game’s main script directory, which for a packed game is inside its
.gamefile. This is what the game’s author shipped, so it is read first: it sets the game’s defaults and nothing more. -
The directory Singe was started in. The machine’s own files, such as a handheld’s button layout, go here, and they win over what a game ships. A file only replaces what it names, so to take a game’s binding off a button, name that input:
INPUT_TEST_MODE = { SCANCODE.F2 }in the machine’scontrols.cfgleaves test mode on the keyboard only, whatever button a game put it on. -
The directory above the game’s data directory, for files shared by every game using that data directory.
-
The game’s data directory. Your own files for one game, which win over everything else.
With --datadir=. the data directory is the game’s own directory, in
which case the file there is read once, as the game’s. --keymapfile replaces
the whole search for controls.cfg with one named file.
5.3. What Wins
-
The built in default.
-
The settings file.
-
The game’s
games.datentry, for the handful of settings it carries (see games.dat). -
machine.cfg, for the audio delay and the picture geometry the service tools save (see The Service Tools). -
The command line, which always wins.
A settings file is a set of defaults, in other words, not something you typed:
if a games.dat entry gives a game a resolution or a Sinden border, that entry
still describes the game better than a machine-wide file does. Anything actually
typed on the command line beats both. machine.cfg sits just under the command
line because somebody adjusted the picture while looking at this monitor, which
is better evidence than any file written elsewhere; the audio delay is the
exception to the ordering entirely, being added to the game’s delay rather than
replacing it.
Options that name the game (--framefile, --disc, --entry), name a
directory (--gamedir, --datadir), or have to act before the file could be
found (--help, --apiversion, --noconsole, --pack, --patch,
--unpack), or are for one run only (--record, --refresh) cannot be set
in a settings file. A key that is not an option, one
of those, or a value the option will not take is an error naming the file and
the key, so a typo is never silently ignored:
settings.cfg: volume_vldpp is not an option. settings.cfg: datadir cannot be set here; it belongs on the command line. settings.cfg: Display scale must be between 25 and 100 percent.
With --program or --trace, the header at the top of trace.txt lists every
setting that was applied, so there is never a question about which file a
running game was given.
5.4. Command Line Options
Singe [OPTIONS] gameName
The game name is the only required argument. It may be a .singe script, a
directory containing a script of the same name (MyGame finds
MyGame/MyGame.singe), or a packed game (MyGame.game runs the first
entry of the games.dat inside it, --entry=N another). A script or directory
launched this way also runs with its games.dat entry when one names it (see
games.dat), so a game plays the same from the command line as from
the menu. For a laserdisc game (--disc) with no
--framefile, Singe looks for a video next to the script with the same base
name and any extension FFmpeg can demux, then for a .txt framefile.
The options are grouped by what they do.
5.4.1. The Game and Its Files
Which game runs, where it and its data live, and what it is played on.
| Option | Purpose |
|---|---|
|
World size for a game without a disc, default 720x480. Ignored when there is a disc. |
|
Directory for everything Singe writes: video indexes, |
|
Play a laserdisc video: the one named by |
|
Run the Nth entry of the |
|
Video file or framefile to use instead of the one found next to the script. |
|
The directory holding the games, the packed |
|
Print the frame ranges of every segment of a framefile, for debugging. |
5.4.2. Display
The window and how the picture fills it.
| Option | Purpose |
|---|---|
|
Force the aspect ratio used to pick a window size ( |
|
Exclusive full screen at the desktop resolution. |
|
Borderless window covering the desktop. |
|
Smooth the overlay as the window scales it ( |
|
Skip the splash screens. |
|
Turn the whole presentation clockwise by |
|
Open the window on display |
|
Stretch the video to fill the window instead of keeping its aspect ratio. |
|
Window width. The height is taken from the matching entry of the built in resolution table when omitted. A size larger than the display — asked for here or by a game’s |
|
Window height. |
5.4.3. Picture Placement, Bezels and Guns
For a cabinet: where the picture sits, the artwork around it, and the border a Sinden gun tracks. See Setting Up a Cabinet.
| Option | Purpose |
|---|---|
|
Draw cabinet artwork around the picture. The file is looked for in the |
|
The folder holding the artwork |
|
Draw the bezel artwork in front of the picture instead of behind it, which is what Hypseus does with its own bezels; the artwork’s transparency is then the hole the game shows through. Without it the artwork is behind everything and the picture covers its cutout. A script chooses whether the overlay and the GUIs stay above the artwork with |
|
Shrink the picture about its center to |
|
Move the picture horizontally inside the room |
|
Move the picture vertically inside the room |
|
Where the Sinden border sits: |
|
Draw the border a Sinden light gun tracks and map mouse and light gun positions into the picture inside it: the black ring, when one is given, runs along the edge of the video, the white ring sits inside it, and the game is drawn in the middle. |
5.4.4. Sound
| Option | Purpose |
|---|---|
|
Play |
|
Default audio track (zero based) for videos with several, such as multi-language releases. |
|
Compensate for audio that is heard |
|
Mute all audio. |
|
The SoundFont ( |
|
Start muted and stay muted until the first input of any kind, then play at the configured volumes. For an attract cabinet in a quiet room. |
|
Sound effect and extra video volume, |
|
Laserdisc volume, |
5.4.5. Input
See Controls.
| Option | Purpose |
|---|---|
|
Keep only the mice that report an absolute position, which is what a real light gun does and an ordinary mouse does not. ManyMouse cannot be asked what a device is, so a device counts as absolute once it has reported an absolute position and not before; see Mice, Guns, and Who Chooses. Hypseus writes it |
|
Which physical pad fills which gamepad slot, as enumeration positions counting from |
|
The strongest rumble step a game may use, |
|
Let the left stick of gamepad slot |
|
How fast that stick drives it, |
|
Read the control mappings from this file instead of searching the four places for |
|
Tell up to four mice apart whatever the game asks for, which a two-gun cabinet needs from a game that never calls |
|
Write a gamepad mapping for a device SDL does not recognize, so an arcade encoder, a spinner, a wheel or a flight stick is opened as |
|
Ask the game not to draw its own crosshair. Exposed to scripts as |
|
Ignore every gamepad, the counterpart of |
|
Disable mouse and light gun input entirely. |
|
Buttons on the first gamepad that quit when held together, whatever the game maps and even when it has turned its quit key off: the way out on a handheld with no keyboard. A game quits back to the menu it was started from, and the menu quits Singe. Two to four of SDL’s gamepad button names joined by |
|
How far an analog trigger must travel before it counts as a button, as a percent of full travel — Hypseus’s unit, whose own default is |
|
The horizontal scale a light gun game reads with |
|
The same for |
5.4.6. Video Decoding and Performance
Mostly for small machines; see Handhelds and Small Machines.
| Option | Purpose |
|---|---|
|
What an interlaced picture gets: |
|
Start with the disc picture in gray. The overlay, the GUIs and the 3D scene keep their color; a script does the same with |
|
How much the 3D scene draws: |
|
Decode video in software even when the platform offers a hardware decoder (VA-API or VDPAU on Linux, the V4L2 decoder on the Pi, D3D11VA on Windows, VideoToolbox on macOS). Use it to rule the hardware path in or out when a video misbehaves; the program trace says which decoder is in use. |
|
Hand hardware decoded video frames straight to the GPU instead of copying them through the CPU: Rockchip’s MPP decoder and VA-API on Linux, drawn with OpenGL ES. It saves most of the cost of full screen video on a small machine. Singe falls back to copying by itself when the driver will not take a frame, or when a game reads or changes the picture’s pixels, and the program trace says which it is doing; |
5.4.7. Cabinets and Front Ends
| Option | Purpose |
|---|---|
|
Print one machine readable line describing this build to standard output and exit, for front ends. See The Version Line. Nothing else is printed. |
|
One number handed from the launcher to the game, which reads it with |
|
Show the option summary and exit. |
|
Quit after |
|
Never ask the service whether a newer Singe exists. The menu otherwise looks once a day and shows what it found under the game’s details; the Engine Update tool still works by hand. Default: off, so the daily look happens. |
|
Print nothing (and open no console window on Windows). |
|
Set the |
5.4.8. Making and Testing Games
See When Something Goes Wrong for the traces.
| Option | Purpose |
|---|---|
|
Connect the game to a debugger listening at |
|
For testing only: ignore real time and run the whole engine on a virtual clock that moves |
|
Pack the game in |
|
Replace files in the packed game from the directory or patch database named after the options, then exit. |
|
With |
|
Trace engine activity to the console and to |
|
Record the whole run, picture and sound, to an MP4 at |
|
Watch the game’s loose script files and run the game again from scratch when one changes; |
|
Trace every Lua API call, with the script line that made it, to the console and to |
|
Write the packed game’s files into the directory named after the options, then exit. A database whose stored names would land outside that directory is refused. |
Options may be given as -x 640, -x640, or --xresolution=640. Numeric
values are validated; a bad value prints the usage text and exits. Newer options
have no short letter; the alphabet ran out, and a letter picked at random would
help nobody.
Anything here except the options that name the game, name a directory, or must act before a file can be found may also be set in a settings file, so a cabinet does not need a launcher script for every game. See The Settings File.
5.5. The Version Line
--apiversion prints one line and exits with status 0:
singe version=3.00 protocol=1
This is a contract for front ends and will not change shape:
-
The line ends with a newline and is the only thing written to standard output. Nothing else is printed, whatever else is on the command line.
-
The first field is always
singe. -
Every field after it is
key=value, separated by one space, with no spaces inside a field. -
versionis the release, the same number the banner shows. -
protocolis the version of this line’s format. It becomes2only if the rules above ever have to change. -
Later releases may add fields. A reader must ignore keys it does not know rather than treating them as an error.
6. Setting Up a Cabinet
Arcade cabinets need a few things a desktop does not: moving the picture away
from edges the monitor hides, turning it for a sideways screen, artwork around
it, a border for a Sinden light gun, and a scoreboard. You only need this
chapter if you are building a cabinet. Set these once in the cabinet’s
settings.cfg, or use the Display tool in the menu (see
The Service Tools) to adjust the picture while you look at it.
6.1. The Video Rectangle
Everything a game shows — the disc, the overlay, the GUIs, the 3D scene and the particles — is drawn into one rectangle, and a handful of options decide where that rectangle is. They apply in this order:
-
The window, or the bezel’s cutout. The rectangle starts as the whole window. Singe works in the video’s own coordinates and lets the window letterbox them (
--stretchfills instead), so nothing here depends on the window’s size. When--bezelloaded artwork that declares a cutout, the rectangle starts as that hole instead and everything below places the picture inside it; see Bezels. -
--scalefactor. The rectangle shrinks to that percentage of what it started as, about its own center. -
--shiftxand--shifty. The rectangle then moves inside the room the scale left,-100hard against one side and100hard against the other, which is what Hypseus’s own-shiftxand-shiftymean. Two consequences follow from that and are worth knowing: the picture can never be pushed off the screen, and at--scalefactor=100there is no room and a shift does nothing at all. To move the picture on a badly mounted panel, reduce the scale first:--scalefactor=90 --shiftx=-100puts the shrunken picture hard against the left. -
--sindengun. The border is applied last, to whatever the shift and the scale left. The black ring takes the rectangle’s edge, the white ring sits inside it, and the game goes inside both, so a border is still a border however the picture was placed. A scale small enough to leave no room for the game squeezes the two rings rather than swallowing it. With bezel artwork loaded the border goes to the window’s edge instead and leaves the picture the size it already was;--sindenedgedecides it either way.
--rotate is not part of that order. The frame is drawn unrotated and the
finished picture is turned clockwise as a whole, so a shift moves the picture
along the video’s own axes and turns with it. A quarter turn also swaps the
shape of the presented area, so a portrait window is filled rather than
letterboxed into a strip.
Mouse and light gun positions travel the same path backwards: the rotation
comes off first, and the position then maps into the rectangle, so a click
lands where the player sees it under any combination of these options.
vldpGetScale, vldpSetScale, vldpGetRotate and vldpSetRotate let a
script move the scale and the rotation while the game runs; the shift is a
display setting and has no script call. None of them is a games.dat key:
like --scalefactor, they describe the player’s screen, not the game.
6.2. Bezels
A bezel is the artwork around an arcade cabinet’s screen. Singe draws one from a single image file, with the game’s picture in a hole cut out of it, and can show an arcade scoreboard in the space that leaves. Three options control it, and they follow Hypseus’s own convention so a cabinet’s command line moves across unchanged.
--bezel cabinet.png names the artwork. It is looked for in this order:
-
bezels/cabinet.pngin the game directory — inside a packed.game, its own copy, so a game can carry its bezel with it; -
bezels/cabinet.pngin the data directory, where a user’s own artwork can live without touching a read-only game directory.
--bezeldir art/cabinets replaces the bezels folder with the one it names,
relative to the game directory or absolute, and then only that folder is
searched. Any format SDL_image reads will do (.png is the sensible choice,
because transparency matters). Artwork the option names and Singe cannot find
ends the program rather than running without it.
The artwork is drawn over the whole window, whatever shape either of them is, so it stretches with the window exactly as the picture does. Give it the aspect ratio you expect to play at.
6.2.1. The Cutout
Beside the image, and named after it, a sidecar file says where the picture
goes: bezels/cabinet.png is described by bezels/cabinet.cfg. It is a Lua
file, as controls.cfg is, and sets one table in the artwork’s own pixels:
-- The hole in cabinet.png the picture is drawn in, in the artwork's own pixels.
CUTOUT = { x = 200, y = 120, width = 800, height = 500 }
All four fields are required and the rectangle must lie inside the artwork; a sidecar that will not run, or that names a rectangle outside the image, ends the program with a message. Because the numbers are the artwork’s own, they stay right at any window size: the image and the hole are scaled together.
With a cutout, the picture is drawn in that hole — stretched to it, so the hole
decides the shape of the picture — and --scalefactor, --shiftx and
--shifty then work inside it, shrinking and nudging the picture in the hole.
With no sidecar the picture keeps the whole window, exactly as it does with no
bezel, and those three options place it as they always have. See
The Video Rectangle.
The hole itself should be transparent in the image. Singe draws the artwork
behind the picture by default, so an opaque middle would simply be covered, but
--bezelflip puts the artwork in front and then only its transparency lets the
game through.
6.2.2. Draw Order
Without --bezelflip the artwork is the first thing in the frame: the picture,
the overlay, the GUIs, the 3D scene and the particles all draw over it. With
--bezelflip the artwork draws in front of the picture instead, which is the
order Hypseus uses for its own bezels, so a frame with soft or shaped edges
overlaps the picture properly.
A script decides what happens to the overlay in that case:
setOverlayOnTop(true) draws the overlay and the GUIs above
the artwork, and false (the default, and Hypseus’s) leaves the artwork on top
of them. With the artwork behind the picture the setting changes nothing,
because everything is already above it.
mainBezelLoaded() tells a script whether artwork is loaded
and gives it the artwork’s identifier, the same number Hypseus reports, so a
game written for a particular bezel can recognize it.
Screen space GUIs and the score panel always draw above the artwork, since the point of them is to sit on it.
6.2.3. The Sinden Border
A Sinden light gun watches the screen for a bright border. With bezel artwork
loaded that border belongs at the edge of the window, not around the picture,
because the gun’s camera sees the whole screen, so that is where --sindengun
puts it as soon as a bezel is loaded. There it is drawn as two rings, after
everything else, so the artwork between the border and the picture stays visible
and nothing paints over the white ring. With no bezel the border goes around the
picture, as it always has, and shrinks it.
--sindenedge video or --sindenedge window overrides that choice in either
direction: a gun cabinet whose artwork is only a thin frame may still want the
border around the picture, and a cabinet with no artwork at all may want it at
the screen’s edge.
6.2.4. The Score Panel
Sixteen of the Hypseus Singe games can drive an arcade scoreboard: credits, and
a score and a life count for each of two players. In Singe that scoreboard is
the RmlUi document Singe/scoreBezel.rml, styled by Singe/scoreBezel.rcss,
both written beside the other support files. Like everything in the Singe
folder they are written afresh at every start, so editing them changes nothing
for long: a game that wants another look ships its own copies, scoreBezel.rml
beside its script linking a style sheet of its own, and Singe uses those
instead. The shipped style is a seven segment look: every readout shows its
digits dimly lit behind the live value, the way a real display does.
The panel is off until a game asks for it with
scoreBezelEnable(true), which is how Hypseus ships as
well, so a game that never asks behaves exactly as before and draws its own
scoreboard with sprites. scoreBezelGetState() is the
question every such game asks first.
Where it goes is decided for you: the panel takes the deeper of the bands the
picture leaves above and below it — the room a bezel’s cutout usually leaves — centered on the picture, and lies along the bottom of the picture when neither
band is deep enough to hold it. It is drawn as a screen space GUI, so a game may
put its own GUIs on the artwork beside it with
guiDrawScreen.
Hypseus’s scoreBezelEnable takes a second argument choosing among its five
scoreboard backends. Singe has one, so the argument is accepted and ignored.
7. Handhelds and Small Machines
Singe runs on the Raspberry Pi and on inexpensive ARM handhelds like the R36S. The same games work there as on a desktop, but a small machine needs a little help to run them well.
7.1. What a Small Machine Needs
Sprites, text, sound, and video work everywhere. The 3D scene and the menu’s fancy look need a graphics chip with Vulkan or OpenGL ES 3.1.
-
A Raspberry Pi 4 or later has both, so everything works. A Pi 3 only has OpenGL ES 2.0, which is not enough for 3D. It still runs 2D games.
-
Most handhelds, the R36S included, have a Mali graphics chip with OpenGL ES 3.1, so 3D works there too.
-
On a machine without either, the menu uses a simpler look that does not need them.
The first time you run a 3D game, Singe builds its shaders, which can take a
few seconds on a small machine. They are saved in the Singe folder inside the
data directory, so this only happens once.
7.2. Settings for a Small Machine
Put these in the settings.cfg beside the Singe binary so every game uses
them:
scenequality = "low"-
Draws the 3D scene at half size, without antialiasing or bloom. 3D looks a little softer, but runs much faster. Video, sprites, and menus are not affected.
zerocopy = true-
This is already the default. Video goes from the hardware decoder straight to the graphics chip without the CPU copying it. This is what lets a handheld play laserdisc video at full speed. Only turn it off if a video misbehaves and you want to rule it out.
quitchord = "back+start"-
Handhelds do not have an Escape key. Holding Select and Start quits the game back to the menu, and quits the menu back to your system, no matter how the game is set up.
7.3. The R36S and ArkOS
The R36S and similar handhelds running ArkOS use the Linux aarch64 build of
Singe. Put the Singe binary, its Singe folder, Menu.sh, and your games in
one folder, such as /roms/singe. Run Menu.sh once so Singe can create its
support files.
To start Singe from the Ports menu, add a script like the one below to
/roms/ports. These handhelds are slow to speed up their processor and
graphics chip, so the script sets them to full speed while Singe runs and puts
them back when it exits.
#!/bin/bash
# /roms/ports/Singe.sh: Singe in the Ports menu.
SINGE_DIR=/roms/singe
[ "$(id -u)" -eq 0 ] && ESUDO="" || ESUDO="sudo"
GOVERNORS=()
for g in /sys/devices/system/cpu/cpufreq/policy*/scaling_governor /sys/class/devfreq/*/governor; do
[ -f "$g" ] || continue
GOVERNORS+=("$g:$(cat "$g")")
echo performance | $ESUDO tee "$g" > /dev/null 2>&1
done
restore() {
for entry in "${GOVERNORS[@]}"; do
echo "${entry##*:}" | $ESUDO tee "${entry%:*}" > /dev/null 2>&1
done
}
trap restore EXIT
cd "$SINGE_DIR" || exit 1
./Menu.sh "$@"
ArkOS does not tell games about the Select and Start buttons, so the quit chord
will not work until you add this gamecontrollerdb.txt beside the Singe binary
(see gamecontrollerdb.txt):
1900bb3e4b4800000011000000010000,GO-Super Gamepad,a:b0,b:b1,x:b2,y:b3,back:b12,start:b13,leftshoulder:b4,rightshoulder:b5,dpup:b8,dpdown:b9,dpleft:b10,dpright:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7,platform:Linux,
If a button does not do what you expect, run Singe once with --program and
press it. The trace shows the name of each button you press, or its number if
the mapping above does not include it.
Finally, add a controls.cfg beside the Singe binary. This one puts coin and
start on Select and Start, and keeps a game’s test and service menus off the
face buttons, where some games put them.
INPUT_1P_COIN = { SCANCODE.MAIN_5, SCANCODE.C, GAMEPAD_0.BUTTON_BACK }
INPUT_1P_START = { SCANCODE.MAIN_1, GAMEPAD_0.BUTTON_START }
INPUT_PAUSE = { SCANCODE.P }
INPUT_SCREENSHOT = { SCANCODE.F12, SCANCODE.F11 }
INPUT_SERVICE = { SCANCODE.MAIN_9 }
INPUT_TEST_MODE = { SCANCODE.F2 }
This file wins over the one a game includes (see Where Configuration Files Are Read From). Pause and screenshot are moved to the keyboard because Singe normally puts them on Start and Select.
8. When Something Goes Wrong
8.1. The Trace
Run Singe with --program (or -p) to see what it is doing. Everything is
printed to the console and saved to trace.txt in the game’s data directory.
If you report a problem, include trace.txt from a run with --program.
--trace (or -t) also logs every Lua call a game makes, which is mostly
useful when writing a game.
If Singe crashes on Linux or macOS, it writes where it crashed to the console
and to trace.txt.
trace.txt only has Singe’s own messages. Messages from the sound system, the
video decoder, and the graphics driver only go to the console. When those might
be the problem, save the console too. On Linux:
./Menu.sh --program &> singe.log
8.2. Reading the Perf Lines
With --program, every five seconds the trace says where the time went, as
averages per trip round the frame loop:
Perf: 58.9 frames/s shown, 353 loops; per loop 13.1 ms (worst 82.3): disc 1.1, script 0.1, scene 0.0, gui 0.4, overlay 0.0, compose 0.0, present 11.4, other 0.1 Perf script: per loop 0.1 ms of Lua and 0.0 in engine calls it made; 0.0 in engine calls altogether: overlayClear 0.01 (0.8 calls), discGetFrame 0.00 (0.8 calls) Video 3 perf: 23.8 frames/s decoded; per frame 0.5 ms, of which read back 0.0, convert 0.0
-
disc— advancing the laserdisc video and putting its frame on the GPU. -
script— the game’sonOverlayUpdate, which thePerf scriptline splits into the Lua itself and the engine calls it made, costliest calls first. -
scene— drawing the 3D scene. -
gui— laying out and drawing the GUI documents. -
overlay— sending what changed on the overlay to the GPU. -
compose— only with--perfsync: the GPU drawing the picture, the overlay and the GUIs together. -
present— showing the frame, which includes waiting for the screen’s next refresh. -
other— everything else: input, sound, physics and the rest.
A video’s own line says how fast it decodes and how much of each frame went on copying it back from the hardware decoder and converting its colors; zero for both means its frames go to the GPU without being copied.
The GPU works behind the CPU, so without --perfsync its time lands wherever
the CPU next has to wait for it, which is usually present. A large present
at the display’s full rate is only the wait for the refresh; a large present
below it means the GPU is busy. --perfsync makes each stage wait for the GPU
before the next starts, so scene, gui, overlay and compose include
their GPU time and present is left with the wait for the refresh. The frame
rate drops while it is on, because the CPU and the GPU no longer work at the
same time; read the stages against each other, not against the frame rate.
8.3. A Button Does Nothing
Open the Input Test tool in the menu (see The Service Tools)
and press the button. If the tool sees it, the game is ignoring it, so check the
game’s controls.cfg. If the tool does not see it, check your own
controls.cfg, or your controller’s mapping in gamecontrollerdb.txt.
Running with --program shows every button as you press it.
8.4. Sound and Picture Are Out of Sync
Some televisions, receivers, and wireless speakers delay the sound. Use the Audio Delay tool in the menu to measure the delay. Singe remembers it for every game. See Audio Sync for details.
For choppy or stuttering sound, see the Frequently Asked Questions.
9. Frequently Asked Questions
Why is it named Singe?
Singe is the name of the dragon in Dragon’s Lair. As Singe (the program) began as an add-on to Daphne (the princess in Dragon’s Lair) the Dragon’s Lair theme was kept.
What is the difference between Daphne, Singe, Hypseus, and Singe 3.xx?
Daphne is an actual laserdisc game emulator that can run a handful of classic laser games. Daphne/Singe (Singe 1.xx) is the original version of Singe that was an add-on for the Daphne emulator — originally shipped as a game DLL for Daphne, then later combined into a single binary with the Daphne emulation features removed. Hypseus-Singe is an enhanced fork of Daphne with Singe 1.xx and some Singe 2.xx support. Singe 2.xx is an all-new, built-from-scratch upgrade of the original Singe, and Singe 3.xx builds on it with 3D, physics, and much more. In short, if you want accuracy, use Daphne or Hypseus if they support emulating the desired game. If it is a Singe game, use Singe, or try Hypseus.
Why should we not call it an "emulator"?
Emulators use the real software or ROMs from the original game and pretend to be the machine they were originally intended to run on. From the game’s perspective, it is business as usual. Singe, on the other hand, requires that every game be re-implemented (ported) to run on Singe. The end result may be very similar, but how it works is entirely different.
Can I run Singe 1.xx and 2.xx games on Singe 3.xx?
Yes, probably. Almost everything from Singe 1.xx has been converted and enhanced for newer versions of Singe, and most Singe 2.xx games run as they are. Games that use the older sprite functions may need a small change; see Migrating from Singe 2.10.
Do I need a laserdisc game to use Singe?
No. Games do not need a disc at all. They can use sprites, video, 3D, and anything else Singe offers. See Games Without a Disc.
Why does the game I just installed not show in the menu?
Whoever packaged the game failed to include a proper games.dat file.
Why is HD video slow?
It should not be any more. Singe now uses your video card to decode video when
your system supports it, even on the Raspberry Pi and many handhelds. If HD
video is still slow, your system may not have hardware video decoding, and
then high definition video requires a lot of CPU. Running with --program
shows which decoder Singe is using.
Why does my audio stutter on Windows?
Users have discovered that most Singe audio and stuttering problems are related to their installed audio driver — especially Realtek-based devices. Try updating your sound drivers or switching to the generic Windows HD Audio driver. Disable surround sound — use stereo, not 5.1 or 7.1. If your drivers do not allow you to use stereo, you can use Virtual Audio Cable to fix this:
-
Install VB-CABLE (https://vb-audio.com/Cable/).
-
Go to Windows sound settings (right-click sound on the taskbar, then Sounds, then Playback).
-
Right-click the Cable Input device and choose Set as default device. (You will lose your current sound output temporarily.)
-
Go to the Recording tab.
-
Right-click Cable Output, then Properties, then Listen, and finally Enable Listen to This Device. In the drop-down list, choose your actual listening device.
-
You should have sound again. Load up Singe and your audio will be working and lag-free.
Does 3D work on a Raspberry Pi or a handheld?
On a Raspberry Pi 4 or later, yes. They have both a Vulkan driver and OpenGL ES 3.1, and Singe uses whichever it finds. The Pi 3 has only OpenGL ES 2.0, which cannot express the scene’s skinning or morph targets, so it runs 2D games (2D physics included) exactly as before and refuses the first 3D call. The Pi 4 is the minimum for any game that uses the 3D Scenes chapter. The same applies to the cheap handhelds: a Mali-G31 or G610 has the ES 3.1 the scene needs, whether or not it has Vulkan. See Handhelds and Small Machines.
Why does my audio stutter on the Raspberry Pi?
The Raspberry Pi OS now uses Pipewire as the default audio backend. Switching to PulseAudio seems to fix the issue:
-
Run
sudo raspi-configfrom a terminal window. -
Select Advanced Options.
-
Select Audio Config.
-
Select PulseAudio.
-
Press Tab, select Ok, and let it reboot.
10. Making Games
This manual is about running Singe: installing it, installing games, setting up a cabinet, and the menu. Making games is covered in two more books, which are an optional download from the same place as Singe rather than part of it, since together they are larger than the engine.
-
The Singe Reference covers everything a game can do: the programming model, the game directory, packing a game into one file, and every function the engine offers, with its arguments, its return values, and an example.
-
Learn to Program with Singe teaches programming from nothing, in thirty-one lessons, to somebody who has never written code. It comes with the scripts and the small art kit the lessons use.
The download holds the two books as PDF and HTML, the lesson files, and the
license. All three books are written in English, French, Italian, German, and
Spanish, and the download comes in each: pick the one in your language. This
manual’s translations are already in the Singe folder beside it. Forge, the authoring tool that makes a game from a description rather
than from code, is a separate project with its own download and its own book.