wittyplay

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 30, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

README

WittyPlay

Plays console games in a browser, from a server. Each game runs in its own sandboxed process through a libretro core, and its picture and sound stream to the browser over WebRTC, with fallbacks for networks and browsers where that can't work.

WittyPlay is developed as part of WittyMediaServer. docs/GAMING.md there explains the design, docs/GAMING-API.md is the API for clients, and docs/WITTYRETROARCH.md covers licensing.

What's in here

Package What it does
wittyplay The consoles: extensions, recommended cores and their licences, sorting a file into a console, and each controller as data. No dependencies
ipc The protocol between a server and a game runner, over pipes
host, cmd/wittyplay-host The runner: a separate program that runs one game
libretro The libretro frontend inside the runner, with no cgo
hostsandbox What the runner does to box itself in before it loads a core
testcore A tiny game written in Go, so everything can be tested with no third-party code
stream Server side: starts runners, encodes with FFmpeg, serves WebRTC and WebSocket viewers
cores Finds cores on the machine and installs them on request
web/ The browser half: the player, controllers, remapping and the touch editor (React)

Playing a game from Go

m := stream.NewManager(stream.Config{Runner: "wittyplay-host", FFmpeg: "ffmpeg"})
s, err := m.Start(stream.Options{
    UserID: 1, ItemID: 7, Title: "My game",
    Core: "/path/to/some_libretro.so", ROM: "/path/to/game", SystemDir: "/path/to/bios", SaveDir: "/path/to/saves",
})
// Give the browser's WebRTC offer to s.Answer, or hand a request to s.ServeWS.

Licences

WittyPlay is Apache-2.0. Cores, RetroArch, ROMs and BIOS files are not part of it, and are never bundled. A core is a separate file with its own licence, loaded only by the separate runner. cores.Install only offers cores whose licences allow it, so non-commercial ones are never offered. Bring your own games.

Testing

go test ./...

Set WMS_TEST_FFMPEG to an FFmpeg program if it isn't on your PATH. The streaming tests run the real runner with the test core, a real FFmpeg and a real WebRTC peer, and are skipped without FFmpeg.

To build the runner for FreeBSD without cgo:

GOOS=freebsd CGO_ENABLED=0 go build -gcflags="github.com/ebitengine/purego/internal/fakecgo=-std" ./cmd/wittyplay-host

Documentation

Overview

Package wittyplay knows the consoles a game library can hold and how to tell which console a file belongs to. It has no dependencies, so the server's scanner can use it without pulling in anything that runs or streams a game.

The sub-packages do the rest: stream (sessions, on the server), host and libretro (the separate process that runs a game), cores (installing them).

Index

Constants

View Source
const (
	RetroB = iota
	RetroY
	RetroSelect
	RetroStart
	RetroUp
	RetroDown
	RetroLeft
	RetroRight
	RetroA
	RetroX
	RetroL
	RetroR
	RetroL2
	RetroR2
	RetroL3
	RetroR3
)

RetroPad buttons. libretro speaks one controller, so a console only needs its own names for these, and which of them it has. On the pad itself, bottom is B, right is A, left is Y and top is X.

View Source
const (
	Landscape = "landscape"
	Portrait  = "portrait"
)

Orientations a touch layout can be for.

View Source
const (
	KindGamepad  = "gamepad"
	KindKeyboard = "keyboard"
	KindTouch    = "touch"
)

Control kinds a person can save.

View Source
const Auto = "auto"

Auto is the Library console value for one folder of many consoles.

View Source
const DPadKey = "dpad"

DPadKey is the D-pad's key in a touch layout.

View Source
const MaxControlSize = 16 << 10

MaxControlSize bounds one saved layout; the largest real one is under 2 KB.

View Source
const TestConsole = "wittytest"

TestConsole is the console of the built-in test core, shown only when testing.

Variables

View Source
var Consoles = []Console{
	{ID: "nes", Name: "Nintendo Entertainment System", Short: "NES", Extensions: []string{".nes", ".fds", ".unf", ".unif"},
		Aliases: []string{"nes", "famicom", "nintendoentertainmentsystem", "nintendonintendoentertainmentsystem", "fc", "famicomdisksystem", "fds"},
		Cores:   []Core{{"fceumm", "FCEUmm", "GPL-2.0"}, {"nestopia", "Nestopia UE", "GPL-2.0"}, {"mesen", "Mesen", "GPL-3.0"}},
		BIOS:    []BIOS{{"disksys.rom", "Famicom Disk System games", false}}},
	{ID: "snes", Name: "Super Nintendo", Short: "SNES", Extensions: []string{".sfc", ".smc", ".fig", ".swc", ".bs", ".gd3", ".gd7", ".dx2", ".bsx"},
		Aliases: []string{"snes", "sfc", "supernintendo", "superfamicom", "supernes", "nintendosupernintendoentertainmentsystem", "supernintendoentertainmentsystem"},
		Cores:   []Core{{"mednafen_supafaust", "Beetle Supafaust", "GPL-2.0-or-later"}, {"bsnes2014_performance", "bsnes 2014 Performance", "GPL-3.0"}, {"mesen-s", "Mesen-S", "GPL-3.0"}}},
	{ID: "gb", Name: "Game Boy and Game Boy Color", Short: "Game Boy", Extensions: []string{".gb", ".gbc", ".dmg", ".cgb", ".sgb"},
		Aliases: []string{"gb", "gbc", "gameboy", "gameboycolor", "gameboycolour", "nintendogameboy", "nintendogameboycolor"},
		Cores:   []Core{{"gambatte", "Gambatte", "GPL-2.0"}, {"sameboy", "SameBoy", "MIT"}, {"mgba", "mGBA", "MPL-2.0"}}},
	{ID: "gba", Name: "Game Boy Advance", Short: "GBA", Extensions: []string{".gba"},
		Aliases: []string{"gba", "gameboyadvance", "nintendogameboyadvance"},
		Cores:   []Core{{"mgba", "mGBA", "MPL-2.0"}, {"vba_next", "VBA Next", "GPL-2.0"}},
		BIOS:    []BIOS{{"gba_bios.bin", "better accuracy; games run without it", false}}},
	{ID: "md", Name: "Sega Mega Drive / Genesis", Short: "Mega Drive", Extensions: []string{".md", ".gen", ".smd", ".68k", ".sgd"}, Shared: []string{".bin"},
		Aliases: []string{"md", "genesis", "megadrive", "segagenesis", "segamegadrive", "segamegadrivegenesis"},
		Cores:   []Core{{"blastem", "BlastEm", "GPL-3.0"}, {"clownmdemu", "ClownMDEmu", "AGPL-3.0"}}},
	{ID: "sms", Name: "Sega Master System", Short: "Master System", Extensions: []string{".sms"},
		Aliases: []string{"sms", "mastersystem", "segamastersystem", "segamastersystemmarkiii", "markiii"},
		Cores:   []Core{{"gearsystem", "Gearsystem", "GPL-3.0"}, {"smsplus", "SMS Plus GX", "GPL-2.0"}}},
	{ID: "gg", Name: "Sega Game Gear", Short: "Game Gear", Extensions: []string{".gg"},
		Aliases: []string{"gg", "gamegear", "segagamegear"},
		Cores:   []Core{{"gearsystem", "Gearsystem", "GPL-3.0"}, {"smsplus", "SMS Plus GX", "GPL-2.0"}}},
	{ID: "ps1", Name: "Sony PlayStation", Short: "PlayStation", Extensions: []string{".pbp"}, Shared: []string{".cue", ".chd", ".m3u", ".iso", ".img", ".toc", ".ccd", ".bin"},
		Aliases: []string{"ps1", "psx", "psone", "playstation", "playstation1", "sonyplaystation"},
		Cores:   []Core{{"pcsx_rearmed", "PCSX ReARMed", "GPL-2.0"}, {"mednafen_psx", "Beetle PSX", "GPL-2.0"}},
		BIOS:    []BIOS{{"scph5501.bin", "US consoles; PCSX ReARMed runs most games without one", false}, {"scph5500.bin", "Japanese consoles", false}, {"scph5502.bin", "European consoles", false}}},
	{ID: "pce", Name: "PC Engine / TurboGrafx-16", Short: "PC Engine", Extensions: []string{".pce"}, Shared: []string{".cue", ".chd", ".ccd", ".toc", ".m3u"},
		Aliases: []string{"pce", "pcengine", "turbografx16", "turbografx", "tg16", "necpcenginetg16", "pcenginecd"},
		Cores:   []Core{{"mednafen_pce_fast", "Beetle PCE Fast", "GPL-2.0"}},
		BIOS:    []BIOS{{"syscard3.pce", "CD games", false}}},
	{ID: "a2600", Name: "Atari 2600", Short: "Atari 2600", Extensions: []string{".a26"}, Shared: []string{".bin"},
		Aliases: []string{"a2600", "atari2600", "2600", "atari"},
		Cores:   []Core{{"stella2014", "Stella 2014", "GPL-2.0"}, {"stella", "Stella", "GPL-2.0"}}},
	{ID: "a7800", Name: "Atari 7800", Short: "Atari 7800", Extensions: []string{".a78"}, Shared: []string{".bin"},
		Aliases: []string{"a7800", "atari7800", "7800"},
		Cores:   []Core{{"prosystem", "ProSystem", "GPL-2.0"}},
		BIOS:    []BIOS{{"7800 BIOS (U).rom", "the Atari start-up screen; optional", false}}},
	{ID: "lynx", Name: "Atari Lynx", Short: "Lynx", Extensions: []string{".lnx", ".lyx"},
		Aliases: []string{"lynx", "atarilynx"},
		Cores:   []Core{{"handy", "Handy", "Zlib"}},
		BIOS:    []BIOS{{"lynxboot.img", "most games need it", false}}},
	{ID: "ws", Name: "WonderSwan and WonderSwan Color", Short: "WonderSwan", Extensions: []string{".ws", ".wsc", ".pc2"},
		Aliases: []string{"ws", "wsc", "wonderswan", "wonderswancolor", "bandaiwonderswan"},
		Cores:   []Core{{"mednafen_wswan", "Beetle WonderSwan", "GPL-2.0"}}},
	{ID: "ngp", Name: "Neo Geo Pocket and Color", Short: "Neo Geo Pocket", Extensions: []string{".ngp", ".ngc", ".ngpc", ".npc"},
		Aliases: []string{"ngp", "ngpc", "neogeopocket", "neogeopocketcolor", "snkneogeopocket"},
		Cores:   []Core{{"mednafen_ngp", "Beetle NeoPop", "GPL-2.0"}}},
	{ID: "vb", Name: "Virtual Boy", Short: "Virtual Boy", Extensions: []string{".vb", ".vboy"},
		Aliases: []string{"vb", "virtualboy", "nintendovirtualboy"},
		Cores:   []Core{{"mednafen_vb", "Beetle VB", "GPL-2.0"}}},
	{ID: "n64", Name: "Nintendo 64", Short: "N64", Extensions: []string{".n64", ".z64", ".v64"},
		Aliases: []string{"n64", "nintendo64"}, Unavailable: needsGPU},
	{ID: "nds", Name: "Nintendo DS", Short: "DS", Extensions: []string{".nds"},
		Aliases: []string{"nds", "ds", "nintendods"}, Unavailable: "Nintendo DS games need a touch screen, which isn't passed through yet."},
	{ID: "psp", Name: "PlayStation Portable", Short: "PSP", Extensions: []string{".cso"}, Shared: []string{".iso", ".pbp", ".chd"},
		Aliases: []string{"psp", "playstationportable", "sonyplaystationportable"}, Unavailable: needsGPU},
	{ID: "dc", Name: "Sega Dreamcast", Short: "Dreamcast", Extensions: []string{".gdi", ".cdi"}, Shared: []string{".chd", ".cue", ".m3u"},
		Aliases: []string{"dc", "dreamcast", "segadreamcast"}, Unavailable: needsGPU},
	{ID: TestConsole, Name: "WittyPlay test console", Short: "Test", Extensions: []string{".wittytest"},
		Aliases: []string{"wittytest"}, Hidden: true},
}

Consoles is every console, in the order the add-library flow lists them.

View Source
var ManifestJSON []byte

ManifestJSON is this module's manifest (docs/MODULES.md, "The manifest").

Functions

func ByExtension

func ByExtension(ext string) string

ByExtension is the one console that uses an extension, or "" for none or several.

func CleanControl

func CleanControl(consoleID, kind string, data json.RawMessage) (json.RawMessage, error)

CleanControl checks a layout someone wants to save, and returns it in the one form the server stores. It comes from a client, so nothing about it is taken on trust.

func DefaultGamepad

func DefaultGamepad() map[int]Binding

DefaultGamepad maps by position, which is how libretro expects pads to be laid out.

func DefaultKeyboard

func DefaultKeyboard() map[int]string

DefaultKeyboard uses KeyboardEvent.code names.

func DefaultRemote

func DefaultRemote() map[int]string

DefaultRemote is for a TV remote playing a game, using KeyboardEvent.key names. A remote has few buttons, so Back opens the game's menu, which can also press Start and Select, and a game needing more wants a gamepad.

func Detect

func Detect(relPath string) string

Detect sorts a file into a console, for a library holding many. The folders between the library's root and the file come first, nearest first, since they are what the owner chose; after that, an extension only one console uses. It returns "" when nothing is sure.

func IsNonCommercial

func IsNonCommercial(id string) bool

IsNonCommercial says whether a core's licence forbids commercial use, as far as this table knows.

func ValidLibraryConsole

func ValidLibraryConsole(id string, testing bool) bool

ValidLibraryConsole says whether a library may be set to this console.

Types

type BIOS

type BIOS struct {
	File     string `json:"file"`
	For      string `json:"for"`
	Required bool   `json:"required"`
}

BIOS is a file a core may want, named so people can supply their own. Nothing here ever downloads or links to one.

type Binding

type Binding struct {
	Button *int `json:"b,omitempty"`
	Axis   *int `json:"a,omitempty"`
	Dir    int  `json:"d,omitempty"`
}

Binding is what presses a RetroPad button on a gamepad: a button, or one direction of an axis. Numbers are those of the W3C standard gamepad, which native clients translate to and from their platform's names (docs/GAMING-API.md).

type Console

type Console struct {
	ID    string `json:"id"`
	Name  string `json:"name"`
	Short string `json:"short"`
	// Extensions only this console uses; a file with one can be sorted by
	// extension alone.
	Extensions []string `json:"extensions"`
	// Shared extensions are valid here, but other consoles use them too, so
	// they need a console library or a folder name to be sure.
	Shared []string `json:"shared,omitempty"`
	// Aliases are folder names that mean this console, written without spaces or
	// punctuation (see normalise).
	Aliases []string `json:"-"`
	Cores   []Core   `json:"cores"`
	BIOS    []BIOS   `json:"bios,omitempty"`
	// Unavailable, when set, says why games for this console can be listed but
	// not played yet.
	Unavailable string `json:"unavailable,omitempty"`
	// Hidden consoles are for testing and never shown to people.
	Hidden bool `json:"-"`
}

Console is one console a library can hold.

func ByID

func ByID(id string) *Console

ByID finds a console.

func (*Console) Accepts

func (c *Console) Accepts(ext string) bool

Accepts reports whether a file extension (lower case, with the dot) belongs to this console, by itself or as a shared one.

type Control

type Control struct {
	Key   string `json:"key"`
	ID    int    `json:"id"` // the RetroPad button; -1 for the D-pad as a whole
	Label string `json:"label"`
	Kind  string `json:"kind"` // dpad | face | shoulder | meta
}

Control is something on a controller. Key is what layouts are stored under.

func Controls

func Controls(consoleID string) []Control

Controls lists a console's on-screen controls.

type Core

type Core struct {
	ID      string `json:"id"` // the file name without _libretro and its extension
	Name    string `json:"name"`
	License string `json:"license"`
}

Core is a libretro core we can point at. Licences are from the core-info files libretro publishes under the MIT licence. Non-commercial cores are never in this table, so they are never offered for download.

func CoreLicense

func CoreLicense(id string) (Core, bool)

CoreLicense looks up a core we know about, for showing beside one an administrator placed in the folder themselves.

type PadButton

type PadButton struct {
	ID    int    `json:"id"`
	Label string `json:"label"`
}

PadButton is one button of a console's controller.

type PadLayout

type PadLayout struct {
	Face     []PadButton `json:"face"` // main buttons, left to right
	Shoulder []PadButton `json:"shoulder,omitempty"`
	Meta     []PadButton `json:"meta"` // Select, Start and their relatives
	Sticks   bool        `json:"sticks,omitempty"`
}

PadLayout says what a console's controller has.

func Pad

func Pad(consoleID string) PadLayout

Pad is a console's controller; anything not listed gets a whole RetroPad.

type Placement

type Placement struct {
	X       float64 `json:"x"`
	Y       float64 `json:"y"`
	Size    float64 `json:"size"`
	Opacity float64 `json:"opacity"`
	Hidden  bool    `json:"hidden,omitempty"`
}

Placement is where a touch control sits. Positions are fractions of the play area; size is a fraction of its shorter side, so a button stays thumb-sized on any screen.

type TouchLayout

type TouchLayout map[string]Placement

TouchLayout is a whole on-screen controller, by Control.Key.

func DefaultTouch

func DefaultTouch(consoleID, orientation string) TouchLayout

DefaultTouch is a console's on-screen controller as it starts out.

Directories

Path Synopsis
cmd
wittyplay-host command
Command wittyplay-host runs one game for WittyMediaServer: it loads a libretro core, or the built-in test core, and speaks the ipc protocol on stdin and stdout.
Command wittyplay-host runs one game for WittyMediaServer: it loads a libretro core, or the built-in test core, and speaks the ipc protocol on stdin and stdout.
Package cores finds libretro cores on this machine and installs them on an administrator's request.
Package cores finds libretro cores on this machine and installs them on an administrator's request.
Package engine is what the host needs from something that runs a game: a libretro core in production, a small built-in core in tests.
Package engine is what the host needs from something that runs a game: a libretro core in production, a small built-in core in tests.
Package host is the program that runs one game: it reads commands on one stream, writes frames on another and paces the engine at its own frame rate.
Package host is the program that runs one game: it reads commands on one stream, writes frames on another and paces the engine at its own frame rate.
Package hostsandbox is what the host does to itself before it loads a core.
Package hostsandbox is what the host does to itself before it loads a core.
Package ipc is the protocol between the server and a game runner process: length-prefixed messages over the runner's stdin and stdout.
Package ipc is the protocol between the server and a game runner process: length-prefixed messages over the runner's stdin and stdout.
Package libretro is a small libretro frontend: it loads a core (a shared library the user installed), runs it one frame at a time and hands back raw video and audio.
Package libretro is a small libretro frontend: it loads a core (a shared library the user installed), runs it one frame at a time and hands back raw video and audio.
Package stream runs game sessions on the server: it starts a runner process, reads its raw frames, encodes them with FFmpeg and sends them to viewers over WebRTC or a WebSocket.
Package stream runs game sessions on the server: it starts a runner process, reads its raw frames, encodes them with FFmpeg and sends them to viewers over WebRTC or a WebSocket.
Package testcore is a tiny game written in Go: a square you move around a coloured field, a tone while a button is held, and a counter kept in save memory.
Package testcore is a tiny game written in Go: a square you move around a coloured field, a tone while a button is held, and a counter kept in save memory.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL