Capitolo 1. Informazioni su Singe

Singe (Scott’s Increasingly Nifty Game Engine, «il motore di gioco sempre più ingegnoso di Scott», e chiamato così dal drago di Dragon’s Lair) è un sistema di scripting basato su Lua che permette di realizzare rapidamente prototipi di nuovi giochi laserdisc, o di creare giochi del tutto nuovi. Il linguaggio è facile da imparare, molto potente e veloce. Tutte le funzionalità che servono per sviluppare il tuo gioco sono disponibili attraverso una semplice interfaccia di programmazione (API).

Singe offre numerose funzionalità a chi sviluppa giochi. Alcune delle più interessanti sono:

  • Scene 3D con modelli, animazione, illuminazione e ombre

  • Fisica, compresi giunti, ragdoll, corpi morbidi e veicoli

  • Menu, schermate di opzioni e HUD costruiti come pagine web

  • Decodifica video hardware, anche su macchine piccole

  • Punteggi record online, e un catalogo di giochi da scaricare e aggiornare

  • Giochi impacchettati in un solo file

  • Linguaggio di programmazione orientato agli oggetti

  • Sprite animati

  • Supporto per i font TrueType

  • Spazio colore a 32 bit con trasparenza

  • Audio stereo multicanale con suoni sovrapposti, e MIDI

  • Supporto per dispositivi di input analogici e digitali, comprese le pistole ottiche

  • Ampio supporto per formati video e audio

Singe funziona su Windows, macOS e Linux, con processori ARM oltre che Intel e AMD: portatili Windows su ARM, il Raspberry Pi e console portatili come la R36S.

Per chi gioca, Singe permette di godersi molti giochi nuovi e non emulati con qualsiasi front-end, o con il sistema di menu incluso.

Dalla prima uscita di Singe, nel lontano 2006, ne sono state pubblicate diverse revisioni, sia ufficiali sia non ufficiali. Nel 2020 è uscito Singe 2.00. Era una riscrittura completa, da zero, che aggiungeva numerose funzionalità restando compatibile con i giochi 1.xx esistenti. Singe 3.00 aggiunge il 3D, la fisica, le interfacce utente e molto altro, e continua a far girare i giochi venuti prima. Al momento della stesura di questo manuale, l’ultima versione è la 3.00b1.

Capitolo 2. Installazione e aggiornamento

2.1. Installare Singe

Per installare Singe, scarica l’eseguibile adatto al tuo sistema. Mettilo da solo in una cartella nuova e avvialo. Al primo avvio, Singe crea tutte le cartelle e tutti i file di supporto che servono. A questo punto sei pronto per installare qualche gioco. Su un PC Windows con processore ARM, prendi la versione Windows-aarch64: anche la versione Windows-x86_64 ci funziona, emulata, ma più lentamente.

2.2. Aggiornare Singe

Per aggiornare Singe a una versione più recente, metti il nuovo eseguibile nella cartella di installazione accanto a quello vecchio e avvialo una volta con --refresh. La cartella di supporto già presente viene messa da parte come old-Singe-<version>, con il nome della versione che l’ha scritta, e al suo posto viene scritta una cartella Singe/ nuova. Non si cancella niente: la cartella messa da parte è tua, da tenere o da togliere, e un secondo --refresh mette da parte la propria come old-Singe-<version>-1 invece di scrivere sopra la prima.

Il vecchio eseguibile può restare dov’è. Menu.sh (o Menu.bat) avvia il Singe più recente che trova accanto a sé, e una beta conta come più vecchia della versione definitiva con lo stesso numero, quindi Singe-v3.00b2 cede il posto a Singe-v3.00 appena questa arriva. Lo strumento Engine Update del menu fa tutto questo per te; vedi Gli strumenti di servizio.

Non avviare un nuovo eseguibile di Singe con un insieme di file di supporto non aggiornati. Quando passi a una nuova versione, aggiorna sempre la cartella Singe/.

2.3. Cose da sapere

Non toccare la cartella Singe/. I file in questa cartella appartengono a Singe e possono essere aggiornati o cancellati in qualsiasi momento.

Capitolo 3. Giocare

3.1. Installare i giochi

Un gioco è un singolo file .game oppure una cartella. Copialo nella stessa cartella in cui hai messo l’eseguibile di Singe. Il sistema di menu incluso lo trova da solo e lo aggiunge al menu.

3.2. Struttura della cartella dei giochi

Un’installazione di Singe è una cartella dei giochi che contiene la cartella di supporto Singe creata dal motore al primo avvio, una cartella per ogni gioco, gli eventuali file .game impacchettati e una cartella data per tutto ciò che i giochi e il motore scrivono. Di solito anche l’eseguibile sta lì, ma non è obbligatorio: --gamedir indica la cartella dei giochi da qualsiasi posizione, e il Menu.sh (o Menu.bat) che il motore scrive lì avvia poi l’eseguibile con il suo percorso completo. Altrimenti il launcher cerca accanto a sé i file il cui nome comincia con Singe e avvia il migliore, nello spirito dei launcher che scrive BatMaker, così un aggiornamento che cambia la versione nel nome dell’eseguibile non lascia un launcher che punta a un file che non c’è più.

Il migliore vuol dire prima l’architettura di questa macchina e poi la versione. La piattaforma nel nome viene confrontata con quella che riporta il sistema, perché una build più recente per un’altra architettura non può girare affatto, e la stessa cartella dei giochi su una condivisione di rete può essere letta tanto da un Pi quanto da un PC. Il launcher fa questo calcolo ogni volta che parte, invece di sentirselo dire una volta per tutte, così la stessa cartella va bene per ogni macchina che la apre. Su un Mac una build universale conta come nativa. Tra le build che questa macchina può far girare vince la più recente: Singe-v3.10 batte Singe-v3.09, e una beta perde contro la versione definitiva a cui prepara la strada, quindi Singe-v3.00b2 perde contro Singe-v3.00. Una build per un’altra architettura viene avviata comunque quando è l’unica presente, perché una vera lamentela del motore è meglio di sentirsi dire che non è stato trovato niente, e lo stesso vale per un nome che il launcher non riesce proprio a leggere.

Singe/                    File di supporto estratti dal motore
    Framework.singe       Caricato da ogni gioco (con dofile)
    Menu.singe            Il menu dei giochi incluso
    Tools.singe           Gli strumenti di servizio del menu (vedi Gli strumenti di servizio)
    MenuDocument.singe    Il menu disegnato come documento GUI
    MenuOverlay.singe     Il menu disegnato nell'overlay, per una macchina senza GPU
    Backdrop.singe        L'introduzione del menu e la griglia dietro, disegnate dal vivo
    menuBackground.mkv    Lo stesso sfondo registrato, per una macchina senza GPU
    menuIntro.flac        Il suo suono, che sfuma mentre il menu prende lo schermo
    Menu.rml              Il documento RmlUi del renderer a documento
    menu.rcss             Il suo foglio di stile, sopra gui.rcss
    gui.rcss              Il tema GUI fornito con Singe
    controls.cfg.example  Esempio da copiare per le assegnazioni dei comandi
    click.wav             Usato dai test del ritardo audio e del suono del menu
    Manual.pdf            Questo manuale
    Manual-fr.pdf         Questo manuale in francese
    Manual-it.pdf         Questo manuale in italiano
    Manual-de.pdf         Questo manuale in tedesco
    Manual-es.pdf         Questo manuale in spagnolo
    COPYING               La GNU General Public License, versione 3
    LICENSES              Avvisi di terze parti e riconoscimenti delle risorse
Collection/               Una cartella di giochi
    games.dat             Le voci di menu dei giochi di questa cartella
    AsteroidPatrol.singe  Uno script
    frame_AsteroidPatrol.txt  Il suo framefile (o un video con lo stesso nome di base)
    sprite_*.png, sound_*.wav, font_*.ttf
MyGame.game               Un gioco impacchettato in un solo file (vedi Giochi in un solo file)
data/
    machine.cfg           Il ritardo audio e la geometria dell'immagine di questa macchina
    Collection/           Indici, trace.txt, screenshot e salvataggi di quei giochi

Dove Singe cerca i file di uno script, e dove uno script può scrivere, è faccenda di chi scrive lo script; il Riferimento di Singe tratta entrambe le cose in Impacchettare il tuo gioco.

3.3. Il menu incluso

Menu.sh (o Menu.bat) avvia Singe/Menu.singe, il menu incluso: un documento RmlUi, Singe/Menu.rml con lo stile di Singe/menu.rcss, disegnato sopra uno sfondo 3D dal vivo (vedi GUI). Il menu funziona senza disco; una macchina senza GPU riproduce invece Singe/menuBackground.mkv, una registrazione dello stesso sfondo, dietro una pagina più semplice disegnata sull’overlay. Legge il games.dat della cartella di ogni gioco e di ogni file .game che ha accanto ed elenca tutti i giochi che trova, in ordine di titolo, lungo il lato sinistro dello schermo. Accanto all’elenco ci sono la grafica del cabinato del gioco selezionato, il suo marquee e la sua clip della modalità attract, con sotto l’anno, il genere, la piattaforma, lo sviluppatore, l’editore, i riconoscimenti della conversione e la descrizione, e una riga di suggerimenti sui tasti lungo il bordo inferiore.

Su e giù spostano la selezione di un gioco alla volta, sinistra e destra di una pagina alla volta; in entrambi i casi da un capo dell’elenco si passa all’altro. Start o un qualsiasi pulsante d’azione avvia il gioco selezionato, e il tasto assegnato a INPUT_SERVICE (di base il tasto 9) apre gli strumenti di servizio (vedi Gli strumenti di servizio). Con un mouse, un clic su una riga seleziona quel gioco e un secondo clic sulla stessa riga lo avvia; la rotella del mouse fa scorrere una descrizione troppo lunga per il suo riquadro. Se imposti --quitchord, tenendo premuti quei pulsanti esci da un gioco tornando al menu, e dal menu tornando al tuo sistema (vedi Console portatili e macchine piccole). Il menu conserva la sua selezione in menu.dat nella sua cartella dei dati, così torna sullo stesso gioco quando ne esci o al successivo avvio di Singe. Quel file è un frammento di Lua che il menu legge all’avvio e riscrive alla chiusura: GAME_SELECTED è il gioco che stava mostrando, SHOW_INTRO è false quando torna da un gioco, così non ti sorbisci l’introduzione due volte, e MENU_OVERLAY sceglie un renderer (vedi I due renderer).

Non tutte le macchine fanno girare tutti i giochi. Un gioco 3D su una macchina senza 3D, o un gioco pesante su una piccola, fallirebbe o andrebbe a passo di lumaca, quindi il menu te lo dice prima. Quando selezioni un gioco che questa macchina non può far girare, la riga sotto i suoi dettagli dice che cosa gli serve («Needs 3D, and this machine has none.»), e avviarlo ripete soltanto quel messaggio invece di fallire a metà strada. Un gioco che chiede più macchina di questa riceve «It may run slowly.» e parte lo stesso. Non viene nascosto niente. Il menu calcola quanto è veloce questa macchina la prima volta che riproduce la sua introduzione, cronometrando il proprio sfondo, e conserva la risposta in machine.cfg; non ti chiede mai di lanciare un benchmark. I giochi dicono che cosa gli serve nel loro games.dat (REQUIRES e TIER), e lo strumento Get Games segna il catalogo allo stesso modo.

Un documento GUI viene disegnato attraverso il dispositivo GPU che usa la scena 3D, quindi su una macchina che non ne ha uno non c’è nessun documento da costruire. Il menu se ne occupa da solo: all’avvio Singe/Menu.singe interroga singeHasGpu e carica uno dei due renderer.

Singe/MenuDocument.singe

Il documento RmlUi descritto sopra, per una macchina con un dispositivo GPU. Disegna anche l’introduzione e la griglia dietro il menu come un’unica scena 3D continua, così il disco non serve per nessuna delle due.

Singe/MenuOverlay.singe

Sprite e fontPrint direttamente nell’overlay, l’aspetto che aveva Singe 2. Non gli serve niente oltre all’overlay in cui ogni gioco disegna già.

Entrambi disegnano lo stesso menu, accettano gli stessi tasti ed eseguono gli stessi strumenti di servizio; Singe/Menu.singe contiene tutto ciò che non è disegno — l’elenco dei giochi, la selezione, l’avvio di un gioco — così il menu è uno solo e non due. Il renderer dell’overlay mostra un gioco alla volta invece di un elenco, perché non ha un riquadro da far scorrere, e taglia una descrizione troppo lunga per la sua colonna invece di farla scorrere.

Per vedere il renderer dell’overlay su una macchina che una GPU ce l’ha, metti MENU_OVERLAY = true in menu.dat nella cartella dei dati del menu; il menu riscrive la riga, quindi resta. È così che si collauda il percorso dell’overlay, ed è così che chi costruisce un cabinato e preferisce il vecchio aspetto lo ottiene.

3.3.2. Online: account, giochi e punteggi

Il menu incluso può far accedere il cabinato a un servizio master (di base master.singeengine.com), che fa tre cose: custodisce l’account, offre un catalogo di giochi da scaricare e aggiornare, e tiene le classifiche dei punteggi record.

Se ne occupano due strumenti di servizio. Online Account accede, crea un account, recupera una password e imposta l’indirizzo del server — è lì che un gestore con un proprio servizio indirizza il cabinato. Un nuovo account non si può usare finché non si digita nello strumento il codice arrivato per email; una password dimenticata si sostituisce allo stesso modo, con il codice ricevuto e una nuova password. Una password che viene impostata si digita due volte, sotto password e confirm. Get Games elenca tutto ciò che il servizio offre, segna quello che è installato qui, e lo scarica, lo aggiorna o lo rimuove. Un download che contiene più giochi — una raccolta, o un gioco in due lingue — li mette tutti nell’elenco, ciascuno con il proprio nome e con l’indicazione del download di cui fa parte, e prenderne o rimuoverne uno qualsiasi prende o rimuove tutto il gruppo, dato che sono un unico file. Quello che viene offerto dipende dall’account: un servizio può riservare un gioco a determinati account, quindi due cabinati connessi con account diversi possono vedere elenchi diversi. È il menu stesso a dire quando esiste una versione più recente di un gioco installato: il gioco porta il segno update nell’elenco, la riga sotto i suoi dettagli indica la versione, e il pulsante 3 su quella pagina la scarica, così un cabinato non ha bisogno di aprire uno strumento di servizio per restare aggiornato. Niente di questa macchina viene conservato da nessuna parte: il menu legge la versione dal games.dat di ciascun gioco e chiede notizie del proprio elenco, quindi un gioco copiato a mano è noto quanto uno scaricato qui. Un cabinato senza alcun gioco apre comunque il menu, che spiega come procurarsene qualcuno, e tutto quello che Get Games scarica o rimuove compare nell’elenco appena si chiudono gli strumenti di servizio. Un elenco più lungo dello schermo scorre con la selezione invece di uscire dal fondo, e …​ indica che c’è dell’altro in una direzione o nell’altra. Un gioco che non viene più offerto continua a funzionare e appare come «installed, no longer offered»: smette soltanto di ricevere aggiornamenti, perché un giocatore che ha un gioco ce l’ha. Un download viene controllato rispetto all’impronta pubblicata dal catalogo prima di sostituire qualsiasi cosa, così un trasferimento arrivato male fallisce invece di installare un gioco che non partirà.

L’account appartiene alla macchina, non a un gioco: il token è conservato in master.dat nella radice dei dati, quindi un gioco che invia un punteggio usa lo stesso accesso fatto dal menu. La password non viene mai conservata, e il file è offuscato, così il token e l’indirizzo dell’account non si leggono a colpo d’occhio; un file modificato risulta disconnesso. La macchina deve poterlo rileggere senza nessuno davanti, quindi tratta comunque master.dat come una chiave dell’account: copiato su un’altra macchina, fa accedere quella macchina. Per inviare un punteggio serve quell’account, ma per leggere una classifica no: un cabinato non connesso mostra comunque la classifica online di un gioco, dove il gioco ne mostra una, per qualsiasi gioco che il servizio offre a tutti. Vedi Punteggi record online per la parte del gioco, e Singe/Net.singe per il client HTTP asincrono che sta sotto — qui niente blocca un fotogramma, perché in Singe Lua è cooperativo e altrimenti un download grande sembrerebbe un blocco.

Singe controlla il certificato del server rispetto a due elenchi insieme: quello che porta con sé e quello che tiene la tua macchina. Basta che uno dei due garantisca per il server, così una vecchia copia di Singe riesce comunque a raggiungere l’aggiornamento che la sostituisce, purché il tuo sistema tenga aggiornato il proprio elenco. Hai un tuo servizio con un certificato emesso da una tua autorità di certificazione? Metti il certificato di quell’autorità in cacerts.local.pem nella cartella dei dati. Singe non scrive mai quel file, quindi sopravvive agli aggiornamenti. Se una connessione viene rifiutata, il messaggio dice quali elenchi sono stati controllati, e un certificato «not yet valid» vuol dire quasi sempre che l’orologio della macchina è sbagliato.

3.3.3. Gli strumenti di servizio

Il tasto assegnato a INPUT_SERVICE apre un elenco di strumenti sopra l’elenco dei giochi. Su e giù ne scelgono uno e il pulsante 1 lo apre; il pulsante 2 esce da uno strumento e torna all’elenco, e premendo di nuovo il tasto di servizio si esce del tutto dagli strumenti. Tutto si trova in Singe/Tools.singe, che il motore estrae accanto a Menu.singe. Lì dentro niente disegna: uno strumento costruisce un elenco di righe e lo passa al menu, ed è per questo che ogni strumento funziona con entrambi i renderer (vedi I due renderer). Niente qui ha bisogno che un gioco sia in esecuzione, e niente modifica i file di un gioco.

Audio Delay

Il ritardo audio a valle, misurato con un clic e un lampo. Vedi Calibrare dal menu per che cosa fa e perché funziona.

Input Test

Ogni controller, mouse e pistola che il motore vede, dal vivo: l’ultimo interruttore che il gioco avrebbe ricevuto e quanti ne sono arrivati, il nome di ogni controller con i suoi sei assi e i pulsanti tenuti premuti, e il nome e la posizione di ogni mouse. È la schermata che risponde a «il pulsante non fa niente» — o l’interruttore arriva e il gioco lo ignora, o non arriva proprio.

System Information

La versione del motore, il sistema operativo, il processore e la memoria, il renderer e il dispositivo 3D, quali decoder video sono in uso, i formati audio integrati, il SoundFont, lo stato del MIDI, le dimensioni della finestra, del canvas e dell’overlay, e la cartella dei dati. Una foto di questa pagina risponde a quasi tutta una segnalazione di bug.

Light Gun

Bersagli al centro e in ogni angolo dell’overlay, sopra qualsiasi cosa il disco stia mostrando. Il pulsante 1 segna dove la pistola ha puntato davvero, e tiene gli ultimi dodici colpi; Start li cancella. Una pistola ben allineata con l’immagine mette le sue croci sui bersagli, e una che non lo è mostra da che parte sbaglia.

Sound Test

Il pulsante 1 suona il clic dall’altoparlante sinistro, poi dal destro, poi da entrambi, ed è tutto il controllo dei fili invertiti. Elenca anche le tracce audio del disco, e sinistra e destra passano dall’una all’altra.

Display

Le dimensioni, la posizione e la rotazione dell’immagine, modificate dal vivo con le frecce, i pulsanti 3 e 4 e il gettone 1, sopra un’immagine di prova: una griglia 16 per 12 per mettere in squadra l’immagine, una scala di grigi a otto gradini su cui regolare la luminosità, e due cornici a un pixel di distanza proprio sul bordo — un monitor in overscan si mangia prima quella esterna. Il pulsante 1 conserva i valori per questa macchina, nello stesso machine.cfg che usa il ritardo audio, così valgono per ogni gioco invece di essere impostati una volta per gioco. Start rimette tutto com’era.

Disc Test

Dodici salti sparsi su tutto il disco, ciascuno cronometrato. Un rip con i fotogrammi chiave molto distanti salta lentamente, e l’unico sintomo in un gioco è che tutto sembra pesante; questo strumento lo misura direttamente e riporta il peggiore dei dodici. Un salto che non è arrivato a destinazione in tre secondi conta come tre secondi.

Saved Data

Quello che ogni gioco ha conservato, trovato cercando nella radice dei dati invece che sentendoselo dire, con le dimensioni di ciascuno. Il pulsante 3 — non il pulsante 1, che ovunque altrove vuol dire «scegli» — butta via il salvataggio del gioco selezionato. Il motivo più comune è azzerare una tabella dei punteggi record senza cancellare il gioco.

Engine Update

Un Singe più recente, quando il servizio ne ha uno per questa macchina. Una beta ha come versione 3.00b2, la seconda beta della 3.00, e viene prima della 3.00 vera e propria, quindi a un cabinato che fa girare una beta viene offerta la versione definitiva il giorno stesso in cui è pubblicata. Mostra che cosa è in esecuzione e che cosa viene offerto, e il pulsante 1 lo scarica, lo controlla rispetto all’impronta pubblicata dal servizio, lo mette accanto al Singe in esecuzione con il nome proprio della versione, mette da parte quello vecchio come old-<name> e si riavvia con quello nuovo. La messa da parte del vecchio può essere rifiutata, da una cartella in cui questo utente non può scrivere o da uno scanner che tiene occupato il file; Singe lo dice e va avanti, perché il launcher avvia comunque il Singe più recente nella cartella. Se il nuovo Singe non parte, quello vecchio torna al suo nome e quello nuovo viene conservato come failed-<name>, che il launcher non avvia. Il nuovo Singe parte con --refresh, così la cartella di supporto viene riscritta dalla versione che ora ne è proprietaria e quella vecchia viene conservata come old-Singe-<version>; un file che un Singe precedente forniva e questo no non può restare in giro a confondere un gioco. Non succede niente finché non premi quel pulsante. Il pulsante 3 interroga di nuovo il servizio. Il menu controlla da solo una volta al giorno e lo dice in una riga sotto i dettagli del gioco; no_update_check = true in settings.cfg ferma il controllo quotidiano, e lo strumento funziona comunque a mano.

Online Account

L’accesso di questo cabinato al servizio master, la creazione di un account, il recupero di una password e l’impostazione dell’indirizzo del server. Vedi Online: account, giochi e punteggi.

Get Games

Il catalogo: che cosa offre il servizio, che cosa è installato qui, e lo scaricamento, l’aggiornamento o la rimozione.

MIDI Ports

Le porte di ingresso e di uscita di questa macchina, quali di queste Singe ha aperto, e gli ultimi messaggi arrivati. Il pulsante 1 invia una nota, il pulsante 3 cerca di nuovo le porte dopo che è stato collegato qualcosa. Niente viene aperto finché questo strumento non lo chiede, così un cabinato che non tocca mai il MIDI non ne paga mai il prezzo.

Frame Statistics

Accende e spegne l’overlay dello sviluppatore. Resta acceso anche nel gioco, nell’angolo in alto a sinistra. Vedi statsEnable.

Capitolo 4. Comandi

Di base, Singe tratta i controller come se fossero controller Xbox. Se il tuo controller non viene riconosciuto, o vuoi cambiare le assegnazioni predefinite con cui Singe lo vede, puoi usare lo SDL2 Gamepad Tool gratuito, da http://generalarcade.com/gamepadtool/.

4.1. controls.cfg

Oltre a configurare il controller, con i file controls.cfg puoi riassegnare tutti gli input di Singe, per Singe nel suo insieme o per un singolo gioco. Per stabilire come sono assegnati gli input, Singe legge le impostazioni di configurazione nell’ordine seguente, e un file successivo sostituisce uno precedente input per input (vedi Da dove vengono letti i file di configurazione):

  1. I valori predefiniti interni a Singe.

  2. controls.cfg dalla cartella dello script principale del gioco: quello fornito dall’autore del gioco.

  3. controls.cfg dalla cartella da cui è stato avviato Singe: quello della macchina (la cartella Singe contiene un esempio, controls.cfg.example, che puoi copiare).

  4. controls.cfg dalla cartella sopra la cartella dei dati del gioco.

  5. controls.cfg dalla cartella dei dati del gioco: il tuo, per quel solo gioco.

Non devi specificare ogni opzione in un file controls.cfg personalizzato. Metti pure soltanto le voci che vuoi cambiare.

Dopo aver installato Singe, trovi un file di esempio per la configurazione degli input in <InstallDir>/Singe/controls.cfg.example. Per vedere le opzioni di configurazione che puoi usare in questo file, leggi <InstallDir>/Singe/Framework.singe.

--keymapfile indica un unico file da leggere al posto di quella ricerca, cosa utile a un front-end che non vuole dubbi su quali assegnazioni abbia ricevuto un gioco.

Ogni voce INPUT_ è un elenco, e una qualsiasi delle cose che contiene aziona l’interruttore. Un elenco dentro quell’elenco è una combinazione: da due a quattro tasti o pulsanti tenuti premuti insieme, che aziona l’interruttore quando viene premuto l’ultimo e lo rilascia quando uno qualsiasi viene sollevato. Così una console portatile senza il tasto Esc esce con Select e Start insieme:

INPUT_QUIT = { SCANCODE.ESCAPE, { GAMEPAD_0.BUTTON_BACK, GAMEPAD_0.BUTTON_START } }

Ogni tasto o pulsante di una combinazione conserva anche il proprio significato, quindi premere Select e Start per uscire in questo modo inserisce anche un gettone e preme Start mentre esci.

Se vuoi un modo di uscire che funzioni sempre, usa invece --quitchord. Quando premi uno dei suoi pulsanti, Singe aspetta gli altri per un quarto di secondo prima di fare qualsiasi altra cosa, così uscire non inserisce un gettone e non preme Start. Un gioco può disattivare il proprio tasto di uscita, ma non può disattivare --quitchord.

4.2. Ogni dispositivo è un controller

Singe ha una sola famiglia di controller, da GAMEPAD_0 a GAMEPAD_3, e ogni dispositivo che apre ne fa parte. SDL considera controller un dispositivo solo quando ha un’assegnazione per esso, e una scheda encoder arcade, uno spinner, un volante o una cloche spesso non ne hanno. Invece di portarsi dietro un secondo tipo di dispositivo con nomi propri, Singe scrive da sé un’assegnazione per un dispositivo del genere e poi lo apre come un normale controller, così arriva a controls.cfg, controllerGetAxis, controllerGetButton e a ogni interruttore INPUT_* esattamente come un controller riconosciuto.

L’assegnazione che scrive Singe è diretta: gli assi del dispositivo, in ordine, diventano la levetta sinistra, la levetta destra e poi i due grilletti; i suoi pulsanti, in ordine, diventano BUTTON_A, BUTTON_B, BUTTON_X, BUTTON_Y, BUTTON_BACK, BUTTON_GUIDE, BUTTON_START, BUTTON_LEFT_STICK, BUTTON_RIGHT_STICK, BUTTON_LEFT_BUMPER e BUTTON_RIGHT_BUMPER; e il suo primo hat diventa la croce direzionale. Un dispositivo senza hat usa invece i quattro pulsanti successivi per la croce direzionale. Un dispositivo con più comandi di quanti il modello di controller ne sappia nominare perde quelli in più — più di sei assi, più di quindici pulsanti, o un secondo hat — e un dispositivo i cui pulsanti non sono cablati in quell’ordine li avrà nei posti sbagliati. È il prezzo di una famiglia sola invece di due, e si corregge facilmente: --program scrive nella traccia l’assegnazione che ha creato, nel formato di SDL, così puoi incollarla in un gamecontrollerdb.txt, riordinarla e farla usare al suo posto.

--mapjoysticks=false disattiva questa scrittura, e in quel caso un dispositivo che SDL non riconosce non viene aperto affatto, esattamente come nelle versioni precedenti.

4.3. gamecontrollerdb.txt

SDL include un grande database di assegnazioni per controller, e la comunità ne tiene uno ancora più grande — gamecontrollerdb.txt, da https://github.com/mdqinc/SDL_GameControllerDB. Singe cerca quel file negli stessi quattro posti in cui cerca controls.cfg, nello stesso ordine (vedi Da dove vengono letti i file di configurazione):

  1. la cartella dello script principale del gioco;

  2. la cartella da cui è stato avviato Singe;

  3. la cartella sopra la cartella dei dati del gioco;

  4. la cartella dei dati del gioco.

Ogni file trovato viene caricato, in quell’ordine, quindi il file della macchina vince su quello fornito da un gioco, un file nella cartella dei dati del gioco vince su entrambi, e tutti vincono sul database di SDL. Solo un dispositivo che nessuno di loro nomina riceve l’assegnazione che Singe scrive per lui: quella è l’ultima risorsa, mai una rivale dei tuoi file. --program riporta quante assegnazioni ha aggiunto ciascun file.

I file vincono anche su SDL_GAMECONTROLLERCONFIG, la variabile d’ambiente da cui SDL prende le assegnazioni, che alcuni sistemi per console portatili impostano per il loro controller integrato. L’assegnazione di ArkOS per la R36S, per esempio, lascia fuori Select e Start, così nessun gioco li vede; una riga in gamecontrollerdb.txt per lo stesso controller li rimette. SDL legge la variabile una sola volta, all’avvio di Singe, quindi questo vale per i file che trova il primo gioco. Un gioco avviato più tardi dal menu legge comunque i propri, ma un controller nominato dalla variabile conserva l’assegnazione della variabile.

Una riga di quel file è fatta così, ed è esattamente quello che la traccia stampa per un dispositivo che Singe ha assegnato da sé:

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. Zone morte e grilletti

DEAD_ZONE in controls.cfg è quanto deve muoversi un asse prima di contare come interruttore premuto, nelle unità grezze che riporta SDL: 32767 a fondo corsa, quindi il valore predefinito di 15000 è poco meno di metà. Vale per ogni asse di ogni controller, compresi i due grilletti analogici, e uno script lo legge come SINGE_DEAD_ZONE.

Due impostazioni lo restringono.

DEAD_ZONES è un elenco di coppie { axis, dead zone }, un asse alla volta, nelle stesse unità grezze, per una levetta dura o un grilletto consumato che non deve spostare tutto il resto:

DEAD_ZONES = {
	{ GAMEPAD_0.AXIS_LEFT_X, 8000 },
	{ GAMEPAD_1.AXIS_LEFT_TRIGGER, 30000 },
}

L’asse si può scrivere come l’asse stesso o come una delle sue due direzioni (GAMEPAD_0.AXIS_LEFT_X, AXIS_LEFT_X_L e AXIS_LEFT_X_R indicano tutti lo stesso asse). Tutto quello che non è elencato tiene DEAD_ZONE.

TRIGGER_THRESHOLD è quanto deve scorrere un grilletto analogico prima di contare come pulsante, espresso come percentuale della corsa completa, che è l’unità usata dal -trigger-threshold di Hypseus, dove il valore predefinito è 99.5. Vale per entrambi i grilletti di tutti e quattro i controller. Il valore predefinito di Singe è 0, che vuol dire che i grilletti restano su DEAD_ZONE, così per chi non lo chiede non cambia niente; uno script legge il risultato in unità grezze come SINGE_TRIGGER_THRESHOLD. Le due unità si convertono direttamente: un punto percentuale vale 32767 / 100 unità grezze, quindi il DEAD_ZONE di Singe pari a 15000 è il 45.8 per cento e il 99.5 per cento di Hypseus corrisponde a 32603 unità grezze. --trigger_threshold imposta lo stesso numero dalla riga di comando e vince su controls.cfg; DEAD_ZONES vince su entrambi, perché è il più specifico.

4.5. Guidare il mouse con una levetta

Un gioco con pistola ottica su un cabinato con una levetta e senza mouse è ingiocabile, a meno che la levetta non possa muovere il cursore. --joymouse fa proprio questo: la levetta sinistra del controller nello slot 0 muove il puntatore che vede il gioco, attraverso lo stesso onMouseMoved a cui arriva un mouse vero, e il cursore viene tenuto dentro l’immagine. --js_range è la velocità, da 1 a 20 con 5 come valore predefinito, misurata in pixel video per fotogramma a fondo corsa, quindi con 5 si attraversa un’immagine di 720 pixel in circa due secondi. L’asse rispetta la propria zona morta, così una levetta che deriva non fa scivolare il cursore.

Di base è spento, ed è qui che Singe si distingue da Hypseus: il controls.cfg fornito lega già quella levetta a INPUT_UP, INPUT_DOWN, INPUT_LEFT e INPUT_RIGHT, e fargli guidare anche il cursore senza che nessuno lo chieda sorprenderebbe ogni gioco esistente. --joymouse=false è il -nojoymouse di Hypseus, e uno script lo accende e lo spegne con joyMouseEnable e lo legge con joyMouseIsEnabled. Un ricaricamento lo riporta dove l’aveva lasciato la riga di comando.

4.6. Mouse, pistole e chi sceglie

mouseSetMode(MOUSE_MANY) è la decisione di un gioco di distinguere fino a quattro mouse, cosa di cui ha bisogno un cabinato a due pistole e che non si può dare a un gioco che non fa mai quella chiamata. --manymouse è la decisione dell’utente e ha la precedenza: la modalità è attiva fin dall’inizio e mouseSetMode(MOUSE_SINGLE) non la spegne più.

--absolutes_only tiene solo i dispositivi che riportano una posizione assoluta, cosa che una vera pistola ottica fa e un mouse normale no, così un cabinato con due pistole e un mouse da scrivania collegato non si confonde per colpa del mouse. Tieni presente come decide: ManyMouse, il backend che Singe usa per distinguere i mouse, non offre alcun modo di chiedere a un dispositivo di che tipo sia, quindi un dispositivo conta come assoluto da quando ha riportato una posizione assoluta, e non prima. Una pistola lo fa al primo movimento; fino ad allora resta muta, e un dispositivo solo relativo resta muto per sempre. L’opzione è quindi un filtro basato sul comportamento osservato più che sulla classe del dispositivo, e su una macchina dove nessun dispositivo riporta mai una posizione assoluta zittisce tutti i mouse.

SWITCH_MOUSE_DISCONNECT è un interruttore come tutti gli altri, tranne che non lo produce nessun tasto o pulsante: il motore lo genera quando si scollega un mouse o una pistola ottica, una volta come pressione e una volta come rilascio, così un gioco con pistola può dirlo sullo schermo invece di sembrare morto. È l’interruttore omonimo di Hypseus. controls.cfg non lo lega a niente; legagli anche un tasto se vuoi vedere che cosa fa un gioco senza staccare un cavo.

4.7. Tasti rapidi

Alt-Enter passa dallo schermo intero a una finestra e viceversa mentre il gioco è in esecuzione, come fa in Hypseus. Il gioco non vede mai quel tasto. Una finestra partita a schermo intero esclusivo (--fullscreen) ci torna nella modalità video che le era stata data; una partita in finestra ottiene una finestra senza bordi che copre il desktop. Non deve cambiare nient’altro: il renderer presenta una dimensione logica in coordinate video e la scala a qualunque dimensione abbia ora la finestra, il rettangolo video è costruito in quelle stesse coordinate, e il render target della rotazione ha le dimensioni dell’immagine e non della finestra, quindi l’immagine, l’overlay, le GUI e la mappatura del mouse seguono tutti da soli.

Gli altri interruttori che un utente può premere — uscita, pausa, screenshot, registrazione, la console e l’attivazione della cattura del mouse — sono normali assegnazioni di controls.cfg e sono descritti insieme ai nomi INPUT_* nel file di esempio.

4.8. Registrare video

F10 comincia a registrare il gioco, immagine e suono insieme, e un altro F10 ferma la registrazione. Ogni registrazione è un nuovo singeNNN.mp4 nella cartella dei dati del gioco, accanto agli screenshot, e si riproduce con qualsiasi cosa riproduca un MP4. L’immagine è l’intera finestra come la vedi, bande nere comprese, e il suono è tutto quello che il gioco riproduce: musica, effetti sonori e la colonna sonora del video stesso.

Dove la macchina ha un encoder video hardware, Singe lo usa, così la registrazione costa pochissimo al gioco: H.264 tramite VA-API su Linux, VideoToolbox su macOS, Media Foundation su Windows e V4L2 sulle schede ARM che ne hanno uno. Altrove registra invece in MPEG-4, che si riproduce ovunque ma produce file più grandi. La riga Recording nella traccia dice quale ha usato. Una macchina troppo lenta per stare al passo scarta fotogrammi dalla registrazione invece di rallentare il gioco, e la traccia dice quanti quando la registrazione si ferma.

Per registrare invece un’intera sessione, avvia Singe con --record=FILENAME. Aggiungi --deterministic e Singe registra ogni fotogramma e il suono esatto che lo accompagna, per quanto tempo serva a produrre ciascun fotogramma, senza riprodurre niente dagli altoparlanti. È così che si fa un video perfetto di una demo o di una modalità attract: su un computer desktop di solito va più veloce del tempo reale.

Capitolo 5. Impostazioni e opzioni

Quasi tutto quello che puoi mettere sulla riga di comando può andare anche in un file delle impostazioni. Prepari tutto una volta e ogni gioco lo usa.

5.1. Il file delle impostazioni

Quasi tutto quello che va sulla riga di comando si può anche scrivere una volta per tutte in un file settings.cfg, così un cabinato non ha bisogno di uno script di avvio che si porti dietro la stessa dozzina di opzioni per ogni gioco. È Lua, come controls.cfg, e Singe lo cerca esattamente negli stessi quattro posti, in quest’ordine:

  1. settings.cfg dalla cartella dello script principale del gioco.

  2. settings.cfg dalla cartella da cui è stato avviato Singe (la cartella Singe contiene un esempio, settings.cfg.example, che puoi copiare).

  3. settings.cfg dalla cartella sopra la cartella dei dati del gioco.

  4. settings.cfg dalla cartella dei dati del gioco.

Ogni posto viene letto una volta, e un file successivo vince chiave per chiave, così un file valido per tutta la macchina può impostare lo schermo e i volumi mentre un file nella cartella dei dati di un gioco spegne il mirino di quel gioco. Non devi scrivere ogni chiave in un file; scrivi quelle che vuoi cambiare.

Ogni chiave è il nome lungo di un’opzione da riga di comando senza i trattini iniziali, quindi non c’è un secondo vocabolario da imparare:

-- Il settings.cfg del cabinato
screen      = 2       -- il secondo monitor
fullscreen  = true
volume_vldp = 80
haptic      = 0       -- questo cabinato non ha la vibrazione
idleexit    = 900     -- restituisci lo schermo dopo quindici minuti di quiete
startsilent = true

Un’opzione che sulla riga di comando non prende alcun valore qui prende true o false (sono accettati anche yes, no, on, off, 1 e 0). Impostarla a false equivale a non metterla. Un’opzione che prende un valore prende lo stesso valore che prenderebbe sulla riga di comando, come numero o come stringa.

Un’opzione, --deterministic, può prendere un valore oppure no, e la sua chiave fa lo stesso: deterministic = true usa il passo predefinito, deterministic = 20 ne indica uno, e deterministic = false lascia l’opzione disattivata.

5.2. Da dove vengono letti i file di configurazione

controls.cfg, settings.cfg e gamecontrollerdb.txt vengono cercati tutti negli stessi quattro posti, nello stesso ordine, e un file letto dopo vince su uno letto prima:

  1. La cartella dello script principale del gioco, che per un gioco impacchettato sta dentro il suo file .game. È quello che ha fornito l’autore del gioco, quindi viene letto per primo: imposta i valori predefiniti del gioco e niente di più.

  2. La cartella da cui è stato avviato Singe. I file della macchina, come la disposizione dei pulsanti di una console portatile, vanno qui, e vincono su quelli forniti da un gioco. Un file sostituisce solo quello che nomina, quindi per togliere a un pulsante l’assegnazione di un gioco, nomina quell’input: INPUT_TEST_MODE = { SCANCODE.F2 } nel controls.cfg della macchina lascia la modalità test solo sulla tastiera, su qualunque pulsante l’avesse messa un gioco.

  3. La cartella sopra la cartella dei dati del gioco, per i file condivisi da tutti i giochi che usano quella cartella dei dati.

  4. La cartella dei dati del gioco. I tuoi file per un gioco, che vincono su tutto il resto.

Con --datadir=. la cartella dei dati è la cartella del gioco stesso, e in quel caso il file che si trova lì viene letto una volta sola, come quello del gioco. --keymapfile sostituisce l’intera ricerca di controls.cfg con un unico file indicato.

5.3. Chi vince

  1. Il valore predefinito interno.

  2. Il file delle impostazioni.

  3. La voce del gioco in games.dat, per le poche impostazioni che contiene (vedi games.dat).

  4. machine.cfg, per il ritardo audio e la geometria dell’immagine che salvano gli strumenti di servizio (vedi Gli strumenti di servizio).

  5. La riga di comando, che vince sempre.

Un file delle impostazioni, in altre parole, è un insieme di valori predefiniti, non qualcosa che hai digitato: se una voce di games.dat dà a un gioco una risoluzione o un bordo Sinden, quella voce descrive comunque il gioco meglio di un file valido per tutta la macchina. Qualsiasi cosa digitata davvero sulla riga di comando batte entrambi. machine.cfg sta subito sotto la riga di comando perché qualcuno ha regolato l’immagine guardando proprio questo monitor, il che è una prova migliore di qualsiasi file scritto altrove; il ritardo audio fa del tutto eccezione a quest’ordine, perché si somma al ritardo del gioco invece di sostituirlo.

Le opzioni che indicano il gioco (--framefile, --disc, --entry), indicano una cartella (--gamedir, --datadir), devono agire prima che il file si possa trovare (--help, --apiversion, --noconsole, --pack, --patch, --unpack) o valgono per un solo avvio (--record, --refresh) non si possono impostare in un file delle impostazioni. Una chiave che non è un’opzione, che è una di quelle, o un valore che l’opzione non accetta sono un errore che nomina il file e la chiave, così un errore di battitura non viene mai ignorato in silenzio:

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.

Con --program o --trace, l’intestazione in cima a trace.txt elenca ogni impostazione applicata, così non c’è mai il dubbio su quale file abbia ricevuto un gioco in esecuzione.

5.4. Opzioni da riga di comando

Singe [OPTIONS] gameName

Il nome del gioco è l’unico argomento obbligatorio. Può essere uno script .singe, una cartella che contiene uno script con lo stesso nome (MyGame trova MyGame/MyGame.singe) o un gioco impacchettato (MyGame.game avvia la prima voce del games.dat che contiene, --entry=N un’altra). Uno script o una cartella avviati in questo modo girano anche con la loro voce di games.dat, quando ce n’è una che li nomina (vedi games.dat), così un gioco si gioca dalla riga di comando come dal menu. Per un gioco laserdisc (--disc) senza --framefile, Singe cerca accanto allo script un video con lo stesso nome di base e una qualsiasi estensione che FFmpeg sappia demultiplexare, e poi un framefile .txt.

Le opzioni sono raggruppate secondo quello che fanno.

5.4.1. Il gioco e i suoi file

Quale gioco parte, dove stanno lui e i suoi dati, e su che cosa si gioca.

Opzione Scopo

-C, --canvas=WxH

Dimensioni del mondo per un gioco senza disco, di base 720x480. Viene ignorata quando c’è un disco.

-d, --datadir=PATHNAME

Cartella per tutto quello che Singe scrive: indici dei video, trace.txt, screenshot, salvataggi, il menu.dat del menu. Al suo interno viene creata una sottocartella con il nome della cartella del gioco (per un gioco impacchettato, una con il nome del database e poi una con il nome della cartella dello script che contiene). Di base è data nella cartella dei giochi. Singe 2.x scriveva invece accanto al gioco; le cartelle dei giochi possono essere di sola lettura, quindi lì non si scrive più niente.

-D, --disc

Riproduce un video laserdisc: quello indicato da --framefile, o il video trovato accanto allo script. Implicita con --framefile. Senza questa opzione, un video accanto allo script viene segnalato e ignorato.

-E, --entry=N

Avvia l’N-esima voce del games.dat dentro un file .game (di base 1). Vedi Giochi in un solo file.

-v, --framefile=FILENAME

File video o framefile da usare al posto di quello trovato accanto allo script.

-G, --gamedir=PATHNAME

La cartella che contiene i giochi, i file .game impacchettati e la cartella di supporto Singe, quando l’eseguibile sta da un’altra parte. Diventa la cartella di lavoro, quindi il nome del gioco, un --datadir relativo e i nomi per l’impacchettamento partono tutti da lì; i percorsi assoluti funzionano così come sono. Di base è la cartella corrente.

-c, --showcalculated

Stampa gli intervalli di fotogrammi di ogni segmento di un framefile, per il debug.

5.4.2. Visualizzazione

La finestra e come l’immagine la riempie.

Opzione Scopo

-a, --aspect=N:D

Forza le proporzioni usate per scegliere le dimensioni della finestra (4:3, 16:9, 16:10).

-f, --fullscreen

Schermo intero esclusivo alla risoluzione del desktop.

-w, --fullscreen_window

Finestra senza bordi che copre il desktop.

--linearscale=BOOLEAN

Smussa l’overlay mentre la finestra lo scala (true) o prende il pixel più vicino (false, che mantiene nitida la pixel art). Accetta true, false, yes, no, on, off, 1 o 0. Uno script lo cambia durante l’esecuzione con setOverlayLinearScale. Predefinito: true, che è come ha sempre disegnato ogni versione di Singe; il predefinito di Hypseus è l’opposto.

-k, --nologos

Salta le schermate iniziali.

-r, --rotate=DEGREES

Ruota l’intera presentazione in senso orario di 0, 90, 180 o 270 gradi, per un cabinato con il pannello montato di lato. Il video, l’overlay, le GUI, la scena 3D e le particelle ruotano tutti insieme, un quarto di giro scambia la forma dell’immagine così da riempire una finestra verticale, e le posizioni del mouse e della pistola ottica vengono ruotate all’indietro così un clic arriva ancora dove è disegnato. Sono accettati solo i quattro angoli retti. Uno script può cambiarla con vldpSetRotate.

--screen=N

Apre la finestra sullo schermo N, contando da 1 come li conta Hypseus. Un numero più grande del numero di schermi elenca gli schermi presenti ed esce. Predefinito: lo schermo principale.

-u, --stretch

Allunga il video per riempire la finestra invece di mantenerne le proporzioni.

-x, --xresolution=VALUE

Larghezza della finestra. Se l’altezza manca, viene presa dalla voce corrispondente della tabella delle risoluzioni interna. Una dimensione più grande dello schermo — chiesta qui o dal games.dat di un gioco — viene ridotta per starci, mantenendone la forma, e la traccia lo dice. Quando si gira senza schermo, con SDL_VIDEODRIVER=offscreen, non c’è nessuno schermo a cui adattarsi, e la finestra mantiene le dimensioni richieste.

-y, --yresolution=VALUE

Altezza della finestra.

5.4.3. Posizione dell’immagine, bezel e pistole

Per un cabinato: dove sta l’immagine, la grafica intorno, e il bordo che segue una pistola Sinden. Vedi Preparare un cabinato.

Opzione Scopo

-B, --bezel=FILENAME

Disegna la grafica del cabinato intorno all’immagine. Il file viene cercato nella cartella bezels della cartella dei giochi (un gioco impacchettato può portarsi il proprio) e poi nella cartella bezels della cartella dei dati; --bezeldir indica una cartella diversa. Va bene qualsiasi formato che SDL_image sappia leggere, e la trasparenza viene mantenuta. Un file di accompagnamento accanto dice dove va l’immagine al suo interno; se manca, l’immagine tiene tutta la finestra e la collocano --shiftx, --shifty e --scalefactor. Una grafica che non si trova chiude il programma. Vedi Bezel.

-I, --bezeldir=PATHNAME

La cartella che contiene la grafica di --bezel, al posto di bezels. Relativa alla cartella dei giochi, o assoluta. Viene cercata solo quella cartella. Vedi Bezel.

-F, --bezelflip

Disegna la grafica del bezel davanti all’immagine invece che dietro, come fa Hypseus con i propri bezel; la trasparenza della grafica diventa allora il buco attraverso cui si vede il gioco. Senza questa opzione la grafica sta dietro a tutto e l’immagine ne copre il ritaglio. Uno script sceglie con setOverlayOnTop se l’overlay e le GUI restano sopra la grafica. Vedi Bezel.

-b, --scalefactor=PERCENT

Rimpicciolisce l’immagine attorno al suo centro fino al PERCENT (da 25 a 100) della finestra, per gli schermi che perdono i bordi per l’overscan. Le posizioni del mouse e della pistola ottica seguono l’immagine rimpicciolita. Uno script può cambiarlo mentre il gioco gira con vldpSetScale. Si combina con --shiftx, --shifty, --rotate e --sindengun; vedi Il rettangolo video.

-X, --shiftx=PERCENT

Sposta l’immagine in orizzontale dentro lo spazio lasciato da --scalefactor, da -100 (tutta a sinistra) a 100 (tutta a destra), 0 al centro. Come in Hypseus, lo spostamento è una percentuale di quello spazio e nient’altro, quindi con --scalefactor=100 non c’è spazio e lo spostamento non fa niente: prima riduci la scala. Vedi Il rettangolo video.

-Y, --shifty=PERCENT

Sposta l’immagine in verticale dentro lo spazio lasciato da --scalefactor, da -100 (tutta in alto) a 100 (tutta in basso), 0 al centro. Alla scala piena non fa niente, per lo stesso motivo. Vedi Il rettangolo video.

-S, --sindenedge=WHERE

Dove sta il bordo Sinden: video lo disegna intorno all’immagine, window sul margine dello schermo. Senza l’opzione decide il bezel: una grafica intorno all’immagine mette il bordo sul margine della finestra, perché la telecamera della pistola vede tutto lo schermo, e senza grafica il bordo va intorno all’immagine come ha sempre fatto. Sul margine della finestra i due anelli vengono disegnati come anelli, per ultimi, così la grafica tra loro e l’immagine resta visibile. Vedi Bezel.

-g, --sindengun='PARAMS'

Disegna il bordo che segue una pistola ottica Sinden e mappa le posizioni del mouse e della pistola ottica nell’immagine al suo interno: l’anello nero, quando c’è, corre lungo il margine del video, l’anello bianco sta al suo interno, e il gioco viene disegnato in mezzo. PARAMS è un unico elenco di numeri tra virgolette: WW (larghezza del bordo bianco in pixel video); WW WB (larghezza del bianco, poi un bordo nero al suo esterno); RW GW BW WW (un colore e una larghezza personalizzati per il bordo); RW GW BW WW WB (lo stesso più una larghezza del nero); oppure RW GW BW WW RB GB BB WB (colori e larghezze personalizzati per entrambi). Un bordo che non lascia spazio al gioco (il doppio delle larghezze del bianco e del nero insieme che raggiunge il lato più corto del video), o una larghezza negativa, chiude il programma con un messaggio. Gli anelli vengono disegnati intorno a quello che hanno lasciato --shiftx, --shifty e --scalefactor, così un bordo resta un bordo comunque sia collocata l’immagine; vedi Il rettangolo video.

5.4.4. Suono

Opzione Scopo

--altaudio=SUFFIX

Riproduce <base><SUFFIX>.ogg accanto al video del disco invece dell’audio che contiene, per un’edizione le cui altre lingue arrivano come file separati: --altaudio=-es accanto a game.m2v riproduce game-es.ogg. Tutti i segmenti di un framefile cambiano insieme. Un file che non c’è lascia in riproduzione l’audio del gioco e stampa un avviso. La chiave AUDIO_SUFFIX in games.dat fa lo stesso per un solo gioco, e uno script lo cambia durante l’esecuzione con discAudioSuffix. Predefinito: nessuno.

-o, --audio=TRACK

Traccia audio predefinita (contando da zero) per i video che ne hanno più di una, come le edizioni multilingue.

-A, --audiodelay=MS

Compensa un audio che si sente MS millisecondi più tardi di quanto il motore possa misurare (negativo quando si sente in anticipo), da -1000 a 1000. Vedi Sincronizzazione dell’audio.

-s, --nosound

Silenzia tutto l’audio.

--soundfont=FILE

Il SoundFont (.sf2) con cui vengono sintetizzati i file MIDI. Singe non ne fornisce nessuno, perché uno buono pesa decine di megabyte per un formato che quasi nessun gioco usa. Senza questa opzione cerca Singe/soundfont.sf2 — così un gioco impacchettato può portarsi il proprio — e poi nei posti in cui una distribuzione ne installa uno. La riga SoundFont: dell’intestazione della traccia dice quale è stato usato, o che non ne è stato trovato nessuno. Vedi MIDI. Predefinito: la ricerca.

--startsilent

Parte in silenzio e resta in silenzio fino al primo input di qualsiasi tipo, poi suona ai volumi configurati. Per un cabinato in modalità attract in una sala tranquilla. --nosound ha la precedenza. Predefinito: disattivato.

-e, --volume_nonvldp=PERCENT

Volume degli effetti sonori e dei video aggiuntivi, da 0 a 100.

-l, --volume_vldp=PERCENT

Volume del laserdisc, da 0 a 100.

5.4.5. Input

Vedi Comandi.

Opzione Scopo

--absolutes_only

Tiene solo i mouse che riportano una posizione assoluta, cosa che una vera pistola ottica fa e un mouse normale no. A ManyMouse non si può chiedere che cosa sia un dispositivo, quindi un dispositivo conta come assoluto da quando ha riportato una posizione assoluta, e non prima; vedi Mouse, pistole e chi sceglie. Hypseus la scrive -absolutes-only; qui il nome usa un trattino basso perché una chiave del file delle impostazioni deve essere un nome Lua. Predefinito: disattivato.

--gamepad_reorder=DIGITS

Quale controller fisico occupa quale slot dei controller, come posizioni di enumerazione contate da 0, una per ogni slot in ordine: --gamepad_reorder=10 fa del secondo controller trovato il giocatore uno e del primo il giocatore due. Si scrive con cifre semplici (3210) o separate da virgole o spazi, come lo scrive Hypseus; una posizione ripetuta viene rifiutata. Le posizioni non nominate riempiono gli slot rimasti, nell’ordine in cui SDL le ha trovate, e una posizione senza un controller dietro lascia vuoto il suo slot. Predefinito: l’ordine di SDL.

--haptic=STEP

Il livello di vibrazione più forte che un gioco può usare, da 0 a 4. 0 spegne del tutto la vibrazione, e un numero più basso attenua un gioco che chiede di più: controllerDoRumble non vibra mai più forte di così. Predefinito: 4, cioè ogni livello che un gioco chiede.

--joymouse=BOOLEAN

Lascia che la levetta sinistra del controller nello slot 0 guidi il cursore del mouse, per un gioco con pistola ottica su un cabinato senza mouse. --joymouse=false è il -nojoymouse di Hypseus, e uno script lo imposta con joyMouseEnable(). Vedi Guidare il mouse con una levetta. Predefinito: false, mentre in Hypseus è attivo — il controls.cfg fornito lega già quella levetta alle quattro direzioni.

--js_range=SPEED

Quanto velocemente quella levetta lo guida, da 1 a 20, in pixel video per fotogramma a fondo corsa. Predefinito: 5, come in Hypseus.

--keymapfile=FILENAME

Legge le assegnazioni dei comandi da questo file invece di cercare controls.cfg nei quattro posti, così un front-end può essere certo di quali assegnazioni abbia ricevuto un gioco. I valori predefiniti interni valgono comunque sotto di esso, quindi anche un file parziale funziona, e un file che non c’è chiude il programma. Predefinito: la ricerca nei quattro posti, descritta in Comandi.

--manymouse

Distingue fino a quattro mouse qualunque cosa chieda il gioco, cosa di cui un cabinato a due pistole ha bisogno da un gioco che non chiama mai da sé mouseSetMode(MOUSE_MANY). La scelta dell’utente ha la precedenza su quella del gioco: mouseSetMode(MOUSE_SINGLE) non la spegne più. Predefinito: disattivato, e decide il gioco.

--mapjoysticks=BOOLEAN

Scrive un’assegnazione da controller per un dispositivo che SDL non riconosce, così un encoder arcade, uno spinner, un volante o una cloche viene aperto come uno tra GAMEPAD_0 e GAMEPAD_3, come qualsiasi altra cosa. false lascia chiuso un dispositivo del genere, come facevano le versioni precedenti. Vedi Ogni dispositivo è un controller. Predefinito: true.

-n, --nocrosshair

Chiede al gioco di non disegnare il proprio mirino. Esposta agli script come singeWantsCrosshairs().

--nogamepad

Ignora tutti i controller, l’equivalente di --nomouse. Non ne viene aperto nessuno e nessun evento dei controller arriva al gioco, così un encoder arcade bloccato non può premere niente. Predefinito: disattivato.

-m, --nomouse

Disattiva del tutto l’input del mouse e della pistola ottica.

--quitchord=BUTTONS

Pulsanti del primo controller che fanno uscire quando sono tenuti premuti insieme, qualunque cosa assegni il gioco e anche quando ha disattivato il proprio tasto di uscita: la via d’uscita su una console portatile senza tastiera. Un gioco esce tornando al menu da cui è stato avviato, e il menu chiude Singe. Da due a quattro nomi di pulsanti dei controller di SDL uniti da +, come back+start (Select e Start); i nomi sono a, b, x, y, back, guide, start, leftstick, rightstick, leftshoulder, rightshoulder, dpup, dpdown, dpleft e dpright, come li dà l’assegnazione del controller, e --program scrive nella traccia il nome di ogni pulsante premuto. La pressione di uno dei pulsanti della combinazione aspetta gli altri per un quarto di secondo prima di fare quello che fa normalmente, così Start non avvia un gioco dal menu mentre stai cercando di uscirne. Va nel settings.cfg della macchina. Predefinito: nessuno.

--trigger_threshold=PERCENT

Quanto deve scorrere un grilletto analogico prima di contare come pulsante, come percentuale della corsa completa — l’unità di Hypseus, il cui predefinito è 99.5. 0 lascia i grilletti su DEAD_ZONE, che è quello che Singe ha sempre dato loro. Vince su TRIGGER_THRESHOLD in controls.cfg; DEAD_ZONES vince su entrambi. Da 0 a 100; vedi Zone morte e grilletti. Predefinito: 0.

--xratio=FACTOR

La scala orizzontale che un gioco con pistola ottica legge con ratioGetX() per allungare le proprie coordinate della pistola su uno schermo la cui forma non corrisponde al video. Singe non ci fa niente; i conti li fa il gioco, esattamente come in Hypseus. Da 0 a 100, con due decimali come li tiene Hypseus. Predefinito: 0, che ogni gioco che lo legge tratta come 1.

--yratio=FACTOR

Lo stesso per ratioGetY(). Predefinito: 0.

5.4.6. Decodifica video e prestazioni

Soprattutto per le macchine piccole; vedi Console portatili e macchine piccole.

Opzione Scopo

--deinterlace=MODE

Che cosa riceve un’immagine interlacciata: auto (il predefinito) deinterlaccia solo i fotogrammi che il file segna come interlacciati, on deinterlaccia ogni fotogramma, per un file con i flag sbagliati, e off non tocca mai l’immagine. Un laserdisc conteneva semiquadri interlacciati, e un rip che li ha conservati mostra l’effetto pettine su uno schermo progressivo; un rip deinterlacciato al momento della sua creazione non ha bisogno di niente qui. Per ogni immagine che entra ne esce una, quindi i numeri dei fotogrammi non si spostano mai. Predefinito: auto.

--monochrome

Parte con l’immagine del disco in grigio. L’overlay, le GUI e la scena 3D mantengono il loro colore; uno script fa lo stesso con vldpSetMonochrome, e lo annulla. Predefinito: disattivato.

--scenequality=LEVEL

Quanto disegna la scena 3D: high, tutto quello che un gioco chiede, o low per una GPU piccola — una console portatile o un vecchio Raspberry Pi — che disegna la scena a metà risoluzione in ogni direzione e lascia perdere antialiasing e bloom qualunque cosa chieda il gioco. L’immagine 3D è più morbida e le cose luminose non hanno alone, ma va molto più veloce dove il limite era la GPU; il disco, l’overlay e le GUI non vengono toccati. Va nel settings.cfg della macchina piuttosto che sulla riga di comando di un gioco, perché descrive la macchina. Predefinito: high.

-H, --softwarevideo

Decodifica il video in software anche quando la piattaforma offre un decoder hardware (VA-API o VDPAU su Linux, il decoder V4L2 sul Pi, D3D11VA su Windows, VideoToolbox su macOS). Usalo per escludere o chiamare in causa il percorso hardware quando un video si comporta male; la traccia del programma dice quale decoder è in uso.

--zerocopy=BOOLEAN

Passa i fotogrammi video decodificati in hardware direttamente alla GPU invece di copiarli attraverso la CPU: il decoder MPP di Rockchip e VA-API su Linux, disegnati con OpenGL ES. Risparmia gran parte del costo del video a schermo intero su una macchina piccola. Singe torna da solo alla copia quando il driver non accetta un fotogramma, o quando un gioco legge o modifica i pixel dell’immagine, e la traccia del programma dice che cosa sta facendo; false lo fa copiare fin dall’inizio, per escludere o chiamare in causa questo percorso. Predefinito: true.

5.4.7. Cabinati e front-end

Opzione Scopo

--apiversion

Stampa sullo standard output una riga leggibile da una macchina che descrive questa build ed esce, per i front-end. Vedi La riga della versione. Non viene stampato nient’altro.

--fvalue=NUMBER

Un numero passato dal launcher al gioco, che lo legge con getFValue(). Singe non ci fa niente. Da 0 a 100000, con tre decimali come li tiene Hypseus. Predefinito: 0.

-h, --help

Mostra il riepilogo delle opzioni ed esce.

--idleexit=SECONDS

Esce dopo SECONDS senza input di alcun tipo — nessun tasto, nessun pulsante, nessun asse dei controller, nessun mouse. Per un cabinato in modalità attract che deve restituire lo schermo. 0 non esce mai. Da 0 a 86400. Predefinito: 0.

--no_update_check

Non chiede mai al servizio se esiste un Singe più recente. Altrimenti il menu controlla una volta al giorno e mostra quello che ha trovato sotto i dettagli del gioco; lo strumento Engine Update funziona comunque a mano. Predefinito: disattivato, quindi il controllo quotidiano avviene.

-z, --noconsole

Non stampa niente (e su Windows non apre nessuna finestra della console).

--refresh

Mette da parte la cartella di supporto Singe come old-Singe-<version>, con il nome della versione che l’ha scritta, e ne scrive una nuova. Serve per gli aggiornamenti: un file che una versione precedente forniva e questa no resta nella cartella messa da parte invece di stare in quella in uso. Non si cancella niente, e un secondo avvio mette da parte la propria come old-Singe-<version>-1. Lo strumento Engine Update lo passa al Singe con cui si riavvia.

5.4.8. Creare e collaudare giochi

Per le tracce vedi Quando qualcosa va storto.

Opzione Scopo

--debug[=HOST:PORT]

Collega il gioco a un debugger in ascolto su HOST:PORT, di solito ZeroBrane Studio, che può allora fermarlo ai breakpoint, eseguirlo passo passo e mostrare che cosa c’è nelle sue variabili; vedi Fare il debug in ZeroBrane Studio. HOST è localhost se non indicato e PORT è 8172. Se nessuno è in ascolto, il gioco si gioca come al solito dopo che il tentativo ha rinunciato, entro due secondi. Predefinito: disattivato.

--deterministic[=MS]

Solo per i test: ignora il tempo reale e fa girare l’intero motore su un orologio virtuale che avanza di MS millisecondi a ogni fotogramma, così lo stesso numero di fotogramma vuol dire sempre lo stesso istante. Anche il disco segue l’orologio virtuale, con i suoi fotogrammi che durano il tempo che valgono, e i generatori casuali ricevono come seme lo stesso numero, così un’esecuzione si ripete identica fino al pixel. Il valore è facoltativo ed è sia il passo sia il seme, da 1 a 1000. Predefinito quando l’opzione è data senza valore: 15, la durata di un fotogramma che deriva dalla frequenza del motore. In questa modalità il ritmo non ha senso, e nemmeno il suono, a meno che non ci sia anche --record, nel qual caso viene generato al passo con l’immagine; vedi Modalità di test deterministica. Predefinito: disattivato.

-P, --pack=DIRECTORY

Impacchetta il gioco in DIRECTORY nel database indicato dopo le opzioni, poi esce. Vedi Giochi in un solo file.

-T, --patch=GAME.game

Sostituisce dei file nel gioco impacchettato prendendoli dalla cartella o dal database di patch indicato dopo le opzioni, poi esce.

--perfsync

Con --program, aspetta che la GPU finisca ogni fase di un fotogramma prima di cronometrare la successiva, così le righe perf dicono a quale fase appartiene il tempo della GPU invece di lasciarlo tutto in present. Mentre è attiva tutto gira più lento, quindi serve per misurare, non per giocare; vedi Leggere le righe perf. Predefinito: disattivato.

-p, --program

Scrive nella traccia l’attività del motore, sulla console e in trace.txt nella cartella dei dati. Il file si apre con un’intestazione che descrive la macchina; vedi L’intestazione della traccia. Ogni cinque secondi dice anche dove è finito il tempo del fotogramma; vedi Leggere le righe perf.

--record=FILENAME

Registra l’intera esecuzione, immagine e suono, in un MP4 in FILENAME, dal primo fotogramma finché Singe non esce. Con --deterministic ogni fotogramma viene conservato e il suono viene generato un passo alla volta insieme all’immagine, così i due corrispondono esattamente e mentre gira non si sente niente. Vedi Registrare video. Predefinito: disattivato.

-R, --reload

Sorveglia i file di script sciolti del gioco e lo riavvia da zero quando uno cambia; F5 fa lo stesso a richiesta. Uno script che non si compila resta sorvegliato, così salvare la correzione lo ricarica. Per quando lavori a un gioco; vedi Ricaricare mentre lavori.

-t, --trace

Scrive nella traccia ogni chiamata all’API Lua, con la riga dello script che l’ha fatta, sulla console e in trace.txt. Il file si apre con un’intestazione che descrive la macchina; vedi L’intestazione della traccia.

-U, --unpack=GAME.game

Scrive i file del gioco impacchettato nella cartella indicata dopo le opzioni, poi esce. Un database i cui nomi memorizzati finirebbero fuori da quella cartella viene rifiutato.

Le opzioni si possono dare come -x 640, -x640 o --xresolution=640. I valori numerici vengono controllati; un valore sbagliato stampa il testo d’uso ed esce. Le opzioni più recenti non hanno una lettera breve; l’alfabeto è finito, e una lettera presa a caso non aiuterebbe nessuno.

Tutto ciò che è qui, tranne le opzioni che indicano il gioco, indicano una cartella o devono agire prima che si possa trovare un file, si può impostare anche in un file delle impostazioni, così un cabinato non ha bisogno di uno script di avvio per ogni gioco. Vedi Il file delle impostazioni.

5.5. La riga della versione

--apiversion stampa una riga ed esce con stato 0:

singe version=3.00 protocol=1

È un contratto per i front-end e la sua forma non cambierà:

  • La riga termina con un a capo ed è l’unica cosa scritta sullo standard output. Non viene stampato nient’altro, qualunque altra cosa ci sia sulla riga di comando.

  • Il primo campo è sempre singe.

  • Ogni campo successivo è key=value, separato da un solo spazio, senza spazi all’interno di un campo.

  • version è la versione pubblicata, lo stesso numero che mostra il banner.

  • protocol è la versione del formato di questa riga. Diventa 2 solo se le regole qui sopra dovessero mai cambiare.

  • Le versioni future potranno aggiungere campi. Chi legge deve ignorare le chiavi che non conosce invece di trattarle come un errore.

Capitolo 6. Preparare un cabinato

I cabinati hanno bisogno di alcune cose che a un computer da scrivania non servono: allontanare l’immagine dai bordi che il monitor nasconde, ruotarla per uno schermo montato di lato, una grafica intorno, un bordo per una pistola ottica Sinden e un tabellone segnapunti. Questo capitolo ti serve solo se stai costruendo un cabinato. Imposta queste cose una volta per tutte nel settings.cfg del cabinato, oppure usa lo strumento Display del menu (vedi Gli strumenti di servizio) per regolare l’immagine mentre la guardi.

6.1. Il rettangolo video

Tutto quello che un gioco mostra — il disco, l’overlay, le GUI, la scena 3D e le particelle — viene disegnato in un unico rettangolo, e una manciata di opzioni decide dove sta quel rettangolo. Si applicano in quest’ordine:

  1. La finestra, o il ritaglio del bezel. Il rettangolo parte come l’intera finestra. Singe lavora nelle coordinate proprie del video e lascia che la finestra le adatti con le bande nere (--stretch invece riempie), quindi niente qui dipende dalle dimensioni della finestra. Quando --bezel ha caricato una grafica che dichiara un ritaglio, il rettangolo parte invece da quel buco e tutto quello che segue colloca l’immagine al suo interno; vedi Bezel.

  2. --scalefactor. Il rettangolo si riduce a quella percentuale di quello che era all’inizio, attorno al proprio centro.

  3. --shiftx e --shifty. Poi il rettangolo si sposta dentro lo spazio lasciato dalla scala, -100 tutto contro un lato e 100 tutto contro l’altro, che è quello che significano -shiftx e -shifty di Hypseus. Ne seguono due conseguenze che vale la pena conoscere: l’immagine non può mai essere spinta fuori dallo schermo, e con --scalefactor=100 non c’è spazio e uno spostamento non fa proprio niente. Per spostare l’immagine su un pannello montato male, prima riduci la scala: --scalefactor=90 --shiftx=-100 mette l’immagine rimpicciolita tutta contro il lato sinistro.

  4. --sindengun. Il bordo viene applicato per ultimo, a quello che hanno lasciato lo spostamento e la scala. L’anello nero prende il margine del rettangolo, l’anello bianco sta al suo interno, e il gioco va dentro entrambi, così un bordo resta un bordo comunque sia stata collocata l’immagine. Una scala abbastanza piccola da non lasciare spazio al gioco schiaccia i due anelli invece di inghiottirlo. Con una grafica del bezel caricata il bordo va invece sul margine della finestra e lascia l’immagine delle dimensioni che aveva già; in un caso o nell’altro decide --sindenedge.

--rotate non fa parte di quell’ordine. Il fotogramma viene disegnato senza rotazione e l’immagine finita viene ruotata in senso orario tutta insieme, quindi uno spostamento muove l’immagine lungo gli assi propri del video e ruota con essa. Un quarto di giro scambia anche la forma dell’area presentata, così una finestra verticale viene riempita invece di ridursi a una striscia tra bande nere.

Le posizioni del mouse e della pistola ottica fanno la stessa strada al contrario: prima si toglie la rotazione, poi la posizione viene mappata nel rettangolo, così un clic arriva dove lo vede il giocatore con qualsiasi combinazione di queste opzioni. vldpGetScale, vldpSetScale, vldpGetRotate e vldpSetRotate permettono a uno script di cambiare la scala e la rotazione mentre il gioco gira; lo spostamento è un’impostazione dello schermo e non ha una chiamata per gli script. Nessuna di queste è una chiave di games.dat: come --scalefactor, descrivono lo schermo del giocatore, non il gioco.

6.2. Bezel

Un bezel (cornice decorativa) è la grafica intorno allo schermo di un cabinato. Singe ne disegna uno a partire da un unico file immagine, con l’immagine del gioco in un buco ritagliato al suo interno, e nello spazio che resta può mostrare un tabellone segnapunti da sala giochi. Lo controllano tre opzioni, che seguono la convenzione di Hypseus, così la riga di comando di un cabinato si trasferisce senza modifiche.

--bezel cabinet.png indica la grafica. Viene cercata in quest’ordine:

  1. bezels/cabinet.png nella cartella dei giochi — dentro un .game impacchettato, la sua copia, così un gioco può portarsi dietro il proprio bezel;

  2. bezels/cabinet.png nella cartella dei dati, dove la grafica di un utente può stare senza toccare una cartella dei giochi di sola lettura.

--bezeldir art/cabinets sostituisce la cartella bezels con quella che indica, relativa alla cartella dei giochi o assoluta, e allora viene cercata solo quella cartella. Va bene qualsiasi formato che SDL_image sappia leggere (.png è la scelta sensata, perché la trasparenza conta). Una grafica indicata dall’opzione che Singe non riesce a trovare chiude il programma, invece di farlo girare senza.

La grafica viene disegnata su tutta la finestra, qualunque forma abbiano l’una e l’altra, quindi si allunga con la finestra esattamente come l’immagine. Dalle le proporzioni con cui pensi di giocare.

6.2.1. Il ritaglio

Accanto all’immagine, e con il suo stesso nome, un file di accompagnamento dice dove va l’immagine del gioco: bezels/cabinet.png è descritto da bezels/cabinet.cfg. È un file Lua, come controls.cfg, e imposta una tabella nei pixel propri della grafica:

-- Il buco in cabinet.png in cui si disegna l'immagine, nei pixel propri della grafica.
CUTOUT = { x = 200, y = 120, width = 800, height = 500 }

Tutti e quattro i campi sono obbligatori e il rettangolo deve stare dentro la grafica; un file di accompagnamento che non si esegue, o che indica un rettangolo fuori dall’immagine, chiude il programma con un messaggio. Siccome i numeri sono quelli propri della grafica, restano giusti a qualsiasi dimensione della finestra: l’immagine e il buco vengono scalati insieme.

Con un ritaglio, l’immagine viene disegnata in quel buco — allungata per riempirlo, quindi è il buco a decidere la forma dell’immagine — e --scalefactor, --shiftx e --shifty lavorano poi al suo interno, rimpicciolendo e spostando di poco l’immagine nel buco. Senza file di accompagnamento l’immagine tiene tutta la finestra, esattamente come senza bezel, e quelle tre opzioni la collocano come hanno sempre fatto. Vedi Il rettangolo video.

Il buco stesso dovrebbe essere trasparente nell’immagine. Di base Singe disegna la grafica dietro l’immagine del gioco, quindi un centro opaco verrebbe semplicemente coperto, ma --bezelflip mette la grafica davanti, e allora solo la sua trasparenza lascia passare il gioco.

6.2.2. Ordine di disegno

Senza --bezelflip la grafica è la prima cosa del fotogramma: l’immagine, l’overlay, le GUI, la scena 3D e le particelle si disegnano tutti sopra di essa. Con --bezelflip la grafica si disegna invece davanti all’immagine, che è l’ordine che Hypseus usa per i propri bezel, così una cornice con bordi sfumati o sagomati si sovrappone correttamente all’immagine.

In quel caso è uno script a decidere che cosa succede all’overlay: setOverlayOnTop(true) disegna l’overlay e le GUI sopra la grafica, e false (il predefinito, anche in Hypseus) lascia la grafica sopra di loro. Con la grafica dietro l’immagine l’impostazione non cambia niente, perché tutto sta già sopra. mainBezelLoaded() dice a uno script se è caricata una grafica e gli dà l’identificatore della grafica, lo stesso numero che riporta Hypseus, così un gioco scritto per un bezel particolare può riconoscerlo.

Le GUI nello spazio dello schermo e il pannello dei punteggi si disegnano sempre sopra la grafica, dato che il loro scopo è proprio starci sopra.

6.2.3. Il bordo Sinden

Una pistola ottica Sinden cerca sullo schermo un bordo luminoso. Con una grafica del bezel caricata, quel bordo va sul margine della finestra, non intorno all’immagine, perché la telecamera della pistola vede tutto lo schermo, ed è lì che --sindengun lo mette appena viene caricato un bezel. Lì viene disegnato come due anelli, dopo tutto il resto, così la grafica tra il bordo e l’immagine resta visibile e niente dipinge sopra l’anello bianco. Senza bezel il bordo va intorno all’immagine, come ha sempre fatto, e la rimpicciolisce.

--sindenedge video o --sindenedge window scavalca quella scelta in un senso o nell’altro: un cabinato con pistola la cui grafica è solo una cornice sottile può volere comunque il bordo intorno all’immagine, e un cabinato senza alcuna grafica può volerlo sul margine dello schermo.

6.2.4. Il pannello dei punteggi

Sedici dei giochi Singe di Hypseus possono pilotare un tabellone segnapunti da sala giochi: i crediti, e un punteggio e un conteggio delle vite per ciascuno dei due giocatori. In Singe quel tabellone segnapunti è il documento RmlUi Singe/scoreBezel.rml, con lo stile di Singe/scoreBezel.rcss, entrambi scritti accanto agli altri file di supporto. Come tutto ciò che sta nella cartella Singe, vengono riscritti da capo a ogni avvio, quindi modificarli non cambia nulla a lungo: un gioco che vuole un altro aspetto distribuisce le proprie copie, scoreBezel.rml accanto al suo script con il collegamento a un foglio di stile tutto suo, e Singe usa quelle. Lo stile fornito imita i display a sette segmenti: ogni indicatore mostra le sue cifre debolmente illuminate dietro il valore attuale, come fa un display vero.

Il pannello è spento finché un gioco non lo chiede con scoreBezelEnable(true), ed è così che viene distribuito anche Hypseus, quindi un gioco che non lo chiede mai si comporta esattamente come prima e disegna il proprio tabellone segnapunti con gli sprite. scoreBezelGetState() è la domanda che ognuno di questi giochi fa per prima.

Dove va viene deciso per te: il pannello occupa la più alta delle due fasce che l’immagine lascia sopra e sotto di sé — lo spazio che di solito lascia il ritaglio di un bezel — centrato sull’immagine, e si stende lungo il fondo dell’immagine quando nessuna delle due fasce è abbastanza alta da contenerlo. Viene disegnato come una GUI nello spazio dello schermo, quindi un gioco può mettere le proprie GUI sulla grafica accanto a esso con guiDrawScreen.

Lo scoreBezelEnable di Hypseus prende un secondo argomento che sceglie tra i suoi cinque backend per il tabellone segnapunti. Singe ne ha uno solo, quindi l’argomento viene accettato e ignorato.

Capitolo 7. Console portatili e macchine piccole

Singe gira sul Raspberry Pi e su console portatili ARM economiche come la R36S. Lì funzionano gli stessi giochi che su un computer da scrivania, ma una macchina piccola ha bisogno di un piccolo aiuto per farli girare bene.

7.1. Che cosa serve a una macchina piccola

Sprite, testo, suono e video funzionano ovunque. La scena 3D e l’aspetto elegante del menu hanno bisogno di un chip grafico con Vulkan o OpenGL ES 3.1.

  • Un Raspberry Pi 4 o successivo li ha entrambi, quindi funziona tutto. Un Pi 3 ha solo OpenGL ES 2.0, che non basta per il 3D. Fa comunque girare i giochi 2D.

  • La maggior parte delle console portatili, R36S compresa, ha un chip grafico Mali con OpenGL ES 3.1, quindi anche lì il 3D funziona.

  • Su una macchina che non ha né l’uno né l’altro, il menu usa un aspetto più semplice che non ne ha bisogno.

La prima volta che avvii un gioco 3D, Singe costruisce i suoi shader, e su una macchina piccola può volerci qualche secondo. Vengono salvati nella cartella Singe dentro la cartella dei dati, quindi succede una volta sola.

7.2. Impostazioni per una macchina piccola

Metti queste righe nel settings.cfg accanto all’eseguibile di Singe, così le usano tutti i giochi:

scenequality = "low"

Disegna la scena 3D a metà dimensione, senza antialiasing né bloom. Il 3D appare un po' più morbido, ma gira molto più veloce. Video, sprite e menu non ne risentono.

zerocopy = true

È già il valore predefinito. Il video va dal decoder hardware direttamente al chip grafico senza che la CPU lo copi. È questo che permette a una console portatile di riprodurre video laserdisc alla massima velocità. Disattivalo solo se un video si comporta male e vuoi escludere questa causa.

quitchord = "back+start"

Le console portatili non hanno il tasto Esc. Tenendo premuti Select e Start si esce dal gioco tornando al menu, e dal menu tornando al tuo sistema, comunque sia configurato il gioco.

7.3. La R36S e ArkOS

La R36S e le console portatili simili con ArkOS usano la build Linux aarch64 di Singe. Metti l’eseguibile di Singe, la sua cartella Singe, Menu.sh e i tuoi giochi in un’unica cartella, per esempio /roms/singe. Avvia Menu.sh una volta, così Singe può creare i suoi file di supporto.

Per avviare Singe dal menu Ports, aggiungi a /roms/ports uno script come quello qui sotto. Queste console portatili sono lente ad accelerare il processore e il chip grafico, quindi lo script li porta alla massima velocità mentre Singe gira e li rimette com’erano quando esce.

#!/bin/bash
# /roms/ports/Singe.sh:  Singe nel menu Ports.
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 non comunica ai giochi i pulsanti Select e Start, quindi la combinazione di uscita non funzionerà finché non aggiungi questo gamecontrollerdb.txt accanto all’eseguibile di Singe (vedi 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,

Se un pulsante non fa quello che ti aspetti, avvia Singe una volta con --program e premilo. La traccia mostra il nome di ogni pulsante che premi, o il suo numero se l’assegnazione qui sopra non lo comprende.

Infine, aggiungi un controls.cfg accanto all’eseguibile di Singe. Questo mette il gettone e l’avvio su Select e Start, e tiene i menu di test e di servizio di un gioco lontani dai pulsanti frontali, dove alcuni giochi li mettono.

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 }

Questo file vince su quello incluso in un gioco (vedi Da dove vengono letti i file di configurazione). La pausa e lo screenshot vengono spostati sulla tastiera perché di solito Singe li mette su Start e Select.

Capitolo 8. Quando qualcosa va storto

8.1. La traccia

Avvia Singe con --program (o -p) per vedere che cosa sta facendo. Tutto viene stampato sulla console e salvato in trace.txt nella cartella dei dati del gioco. Se segnali un problema, allega il trace.txt di un’esecuzione con --program. --trace (o -t) registra anche ogni chiamata Lua che fa un gioco, cosa utile soprattutto quando scrivi un gioco.

Se Singe va in crash su Linux o macOS, scrive sulla console e in trace.txt il punto in cui si è bloccato.

trace.txt contiene solo i messaggi di Singe. I messaggi del sistema audio, del decoder video e del driver grafico vanno solo sulla console. Quando il problema potrebbe essere lì, salva anche la console. Su Linux:

./Menu.sh --program &> singe.log

8.2. Leggere le righe perf

Con --program, ogni cinque secondi la traccia dice dove è finito il tempo, come medie per ogni giro del ciclo dei fotogrammi:

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 — l’avanzamento del video laserdisc e il caricamento del suo fotogramma sulla GPU.

  • script — la funzione onOverlayUpdate del gioco, che la riga Perf script divide tra il Lua vero e proprio e le chiamate al motore che ha fatto, a partire dalle più costose.

  • scene — il disegno della scena 3D.

  • gui — l’impaginazione e il disegno dei documenti GUI.

  • overlay — l’invio alla GPU di quello che è cambiato sull’overlay.

  • compose — solo con --perfsync: la GPU che disegna insieme l’immagine, l’overlay e le GUI.

  • present — la visualizzazione del fotogramma, che comprende l’attesa del prossimo aggiornamento dello schermo.

  • other — tutto il resto: input, suono, fisica e così via.

La riga propria di un video dice quanto velocemente si decodifica e quanto di ogni fotogramma se n’è andato per ricopiarlo dal decoder hardware e convertirne i colori; zero per entrambi vuol dire che i suoi fotogrammi vanno alla GPU senza essere copiati.

La GPU lavora in ritardo rispetto alla CPU, quindi senza --perfsync il suo tempo finisce dovunque la CPU debba aspettarla la volta successiva, che di solito è present. Un present grande alla frequenza piena dello schermo è solo l’attesa dell’aggiornamento; un present grande al di sotto di essa vuol dire che la GPU è occupata. --perfsync fa aspettare la GPU a ogni fase prima che cominci la successiva, quindi scene, gui, overlay e compose comprendono il loro tempo di GPU e a present resta l’attesa dell’aggiornamento. Mentre è attiva la frequenza dei fotogrammi cala, perché la CPU e la GPU non lavorano più nello stesso momento; confronta le fasi tra loro, non con la frequenza dei fotogrammi.

8.3. Un pulsante non fa niente

Apri lo strumento Input Test nel menu (vedi Gli strumenti di servizio) e premi il pulsante. Se lo strumento lo vede, è il gioco a ignorarlo, quindi controlla il controls.cfg del gioco. Se lo strumento non lo vede, controlla il tuo controls.cfg, o l’assegnazione del tuo controller in gamecontrollerdb.txt. Avviando con --program vedi ogni pulsante mentre lo premi.

8.4. Suono e immagine non sono sincronizzati

Alcuni televisori, amplificatori e altoparlanti senza fili ritardano il suono. Usa lo strumento Audio Delay del menu per misurare il ritardo. Singe lo ricorda per tutti i giochi. Per i dettagli vedi Sincronizzazione dell’audio.

Per un suono a scatti o che balbetta, vedi le Domande frequenti.

Capitolo 9. Domande frequenti

Perché si chiama Singe?

Singe è il nome del drago di Dragon’s Lair. Siccome Singe (il programma) è nato come aggiunta a Daphne (la principessa di Dragon’s Lair), si è mantenuto il tema di Dragon’s Lair.

Che differenza c’è tra Daphne, Singe, Hypseus e Singe 3.xx?

Daphne è un vero emulatore di giochi laserdisc, che può far girare una manciata di classici giochi laser. Daphne/Singe (Singe 1.xx) è la versione originale di Singe, che era un’aggiunta per l’emulatore Daphne — distribuita all’inizio come DLL di gioco per Daphne, e poi riunita in un unico eseguibile senza le funzioni di emulazione di Daphne. Hypseus-Singe è un fork migliorato di Daphne con il supporto per Singe 1.xx e in parte per Singe 2.xx. Singe 2.xx è un aggiornamento del Singe originale, del tutto nuovo e costruito da zero, e Singe 3.xx ci aggiunge sopra il 3D, la fisica e molto altro. In breve, se vuoi la fedeltà, usa Daphne o Hypseus, se sono in grado di emulare il gioco che ti interessa. Se è un gioco Singe, usa Singe, o prova Hypseus.

Perché non dovremmo chiamarlo «emulatore»?

Gli emulatori usano il software vero o le ROM del gioco originale e fingono di essere la macchina su cui il gioco doveva girare in origine. Dal punto di vista del gioco, è tutto come al solito. Singe, invece, richiede che ogni gioco venga reimplementato (convertito) per girare su Singe. Il risultato finale può essere molto simile, ma il funzionamento è completamente diverso.

Posso far girare i giochi per Singe 1.xx e 2.xx su Singe 3.xx?

Sì, probabilmente. Quasi tutto quello che c’era per Singe 1.xx è stato convertito e migliorato per le versioni più recenti di Singe, e la maggior parte dei giochi per Singe 2.xx gira così com’è. I giochi che usano le vecchie funzioni degli sprite possono avere bisogno di una piccola modifica; vedi Migrazione da Singe 2.10.

Mi serve un gioco laserdisc per usare Singe?

No. I giochi non hanno affatto bisogno di un disco. Possono usare sprite, video, 3D e qualsiasi altra cosa offra Singe. Vedi Giochi senza disco.

Perché il gioco che ho appena installato non compare nel menu?

Chi ha preparato il pacchetto del gioco non ha incluso un file games.dat come si deve.

Perché il video HD è lento?

Non dovrebbe esserlo più. Ora Singe usa la scheda video per decodificare il video quando il tuo sistema lo permette, anche sul Raspberry Pi e su molte console portatili. Se il video HD è ancora lento, il tuo sistema potrebbe non avere la decodifica video hardware, e allora il video ad alta definizione richiede molta CPU. Avviando con --program vedi quale decoder sta usando Singe.

Perché l’audio balbetta su Windows?

Gli utenti hanno scoperto che la maggior parte dei problemi di audio e di scatti di Singe dipende dal driver audio installato — soprattutto con i dispositivi basati su Realtek. Prova ad aggiornare i driver audio o a passare al driver generico Windows HD Audio. Disattiva l’audio surround — usa lo stereo, non il 5.1 o il 7.1. Se i tuoi driver non ti permettono di usare lo stereo, puoi risolvere con Virtual Audio Cable:

  1. Installa VB-CABLE (https://vb-audio.com/Cable/).

  2. Apri le impostazioni audio di Windows (clic destro sull’icona dell’audio nella barra delle applicazioni, poi Suoni, poi Riproduzione).

  3. Clic destro sul dispositivo Cable Input e scegli Imposta come dispositivo predefinito. (Perderai temporaneamente l’uscita audio attuale.)

  4. Vai alla scheda Registrazione.

  5. Clic destro su Cable Output, poi Proprietà, poi Ascolto, e infine attiva Ascolta questo dispositivo. Nell’elenco a discesa, scegli il dispositivo con cui ascolti davvero.

  6. Dovresti avere di nuovo l’audio. Avvia Singe e l’audio funzionerà, senza ritardi.

Il 3D funziona su un Raspberry Pi o su una console portatile?

Su un Raspberry Pi 4 o successivo, sì. Hanno sia un driver Vulkan sia OpenGL ES 3.1, e Singe usa quello che trova. Il Pi 3 ha solo OpenGL ES 2.0, che non sa esprimere lo skinning o i morph target della scena, quindi fa girare i giochi 2D (fisica 2D compresa) esattamente come prima e rifiuta la prima chiamata 3D. Il Pi 4 è il minimo per qualsiasi gioco che usi il capitolo Scene 3D. Lo stesso vale per le console portatili economiche: un Mali-G31 o un G610 ha l’ES 3.1 che serve alla scena, che abbia Vulkan oppure no. Vedi Console portatili e macchine piccole.

Perché l’audio balbetta sul Raspberry Pi?

Raspberry Pi OS ora usa Pipewire come backend audio predefinito. Passare a PulseAudio sembra risolvere il problema:

  1. Esegui sudo raspi-config da una finestra del terminale.

  2. Seleziona Advanced Options.

  3. Seleziona Audio Config.

  4. Seleziona PulseAudio.

  5. Premi Tab, seleziona Ok e lascia che si riavvii.

Capitolo 10. Creare giochi

Questo manuale parla di come far girare Singe: installarlo, installare i giochi, preparare un cabinato e il menu. La creazione di giochi è trattata in altri due libri, che sono un download facoltativo dallo stesso posto da cui scarichi Singe invece di farne parte, perché insieme sono più grandi del motore.

  • Il Riferimento di Singe tratta tutto quello che un gioco può fare: il modello di programmazione, la cartella del gioco, l’impacchettamento di un gioco in un solo file, e ogni funzione che il motore offre, con i suoi argomenti, i valori restituiti e un esempio.

  • Impara a programmare con Singe insegna a programmare partendo da zero, in trentuno lezioni, a chi non ha mai scritto codice. Viene con gli script e il piccolo kit grafico che usano le lezioni.

Il download contiene i due libri in PDF e in HTML, i file delle lezioni e la licenza. Tutti e tre i libri sono scritti in inglese, francese, italiano, tedesco e spagnolo, e il download esiste in ciascuna lingua: scegli quello nella tua. Le traduzioni di questo manuale sono già nella cartella Singe, accanto a esso. Forge, lo strumento di creazione che fa un gioco a partire da una descrizione invece che dal codice, è un progetto separato con il proprio download e il proprio libro.