emulators

package
v0.7.1 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: AGPL-3.0 Imports: 33 Imported by: 0

Documentation

Overview

Package emulators is the list of standalone emulators WittyPlay knows, and what installs one. A standalone emulator is a desktop program, not a libretro core: PCSX2, Dolphin, RPCS3 and the like. It never runs in the module's own process or the game runner. It runs in a container (sandbox/docker), and only when an administrator has turned the Docker backend on.

The list is built in. Each download is pinned to a SHA-256, and an entry whose hash nobody has checked yet says "TODO" and is refused at install time. Nothing here ever downloads a BIOS, firmware, keys or games: the person running the server brings those.

Index

Constants

View Source
const (
	DisplayX11      = "x11"
	DisplayWayland  = "wayland"
	DisplayHeadless = "headless"
)

How a program shows its picture.

View Source
const (
	// StreamPipe: FFmpeg inside the container captures the display and the sound and sends RTP
	// to WittyPlay, which hands it to the same WebRTC session a libretro game has.
	StreamPipe = "pipe"
	// StreamKasmVNC: the container's KasmVNC, reached only through WittyPlay's authenticated
	// proxy. The fallback, for a program whose setup needs a desktop: a mouse, its own menus.
	StreamKasmVNC = "kasmvnc"
)

How its picture reaches a browser.

View Source
const (
	ArchiveZip      = "zip"
	ArchiveTarGz    = "tar.gz"
	ArchiveTarXz    = "tar.xz"
	ArchiveAppImage = "appimage"
	Archive7z       = "7z"
	// ArchiveDMG is a Mac disk image, opened read-only with the Mac's own hdiutil and copied out
	// under the same rules as any archive. Only a Mac has one.
	ArchiveDMG = "dmg"
)

Archive kinds.

View Source
const (
	DefaultMaxDownload = 1 << 30 // 1 GiB downloaded
	DefaultMaxUnpacked = 4 << 30 // 4 GiB unpacked

)

Limits on what one install may take. An emulator's AppImage is a few hundred megabytes at most; anything far past that is a mistake or an attack.

View Source
const (
	PhaseDownloading = "downloading"
	PhaseVerifying   = "verifying"
	PhaseUnpacking   = "unpacking"
	PhaseDone        = "done"
)

Phases of an install.

View Source
const (
	ScopeAdmin = "admin"
	ScopeUser  = "user"
	ScopeGame  = "game"
)

Scopes of a setting, and of a write.

View Source
const (
	KindToggle = "toggle"
	KindNumber = "number"
	KindText   = "text"
	KindChoice = "choice"
	KindMap    = "map"
)

Kinds of setting.

View Source
const ArchUniversal = "universal"

ArchUniversal is a Mac build that runs natively on both kinds of processor.

View Source
const CustomPrefix = "custom-"

CustomPrefix starts the id of a console an administrator added themselves (WittyPlay's custom consoles). Before GameCube, Wii, Wii U, PS3, Xbox and Switch were consoles of WittyPlay's own, an administrator added custom-gamecube and the like for an emulator to play; the server moves those to the real consoles, and until it has, an emulator still plays them.

View Source
const MaxOwn = 32

MaxOwn bounds how many own programs a server keeps.

View Source
const OwnPrefix = "own-"

OwnPrefix starts the id of an administrator's own emulator.

View Source
const Placeholder = "TODO"

Placeholder is what a hash or a digest says when nobody has checked the file yet.

View Source
const SourceManual = "manual"

SourceManual marks an install the administrator made themselves.

Variables

View Source
var (
	ErrPlaceholder   = errors.New("nobody has checked this emulator's download yet (its hash is a placeholder), so it can't be installed; a developer can allow it for testing")
	ErrNonCommercial = errors.New("this emulator's licence forbids commercial use, so WittyPlay doesn't offer it for download")
	ErrNoArtifact    = errors.New("there's no download of this emulator for this platform; its container image may still run it")
	ErrHash          = errors.New("the download doesn't match the hash it was pinned to")
	ErrTooLarge      = errors.New("the download is larger than any emulator's should be")
	ErrBusy          = errors.New("this emulator is already being installed")
	ErrXZ            = errors.New("tar.xz archives can't be opened by this version")
	ErrNotInstalled  = errors.New("that emulator isn't installed")
)

Errors a caller shows to people.

View Source
var DefaultHosts = []string{
	"github.com",
	"objects.githubusercontent.com",
	"release-assets.githubusercontent.com",
	"pcsx2.net",
	"dl.dolphin-emu.org",
	"www.duckstation.org",
	"www.ppsspp.org",
	"xemu.app",
	"cemu.info",
	"rpcs3.net",
	"melonds.kuribo64.net",
}

DefaultHosts are where an emulator may be downloaded from: GitHub's release assets, and the projects' own sites. A redirect anywhere else is refused, as cores' downloads are.

View Source
var ErrHost = errors.New("that address isn't an approved download host")

ErrHost is a download address on no list.

View Source
var ErrManual = errors.New("this emulator is never downloaded: install it yourself from its own project and add it in Settings, Standalone emulators")

ErrManual: this emulator is installed by hand only.

Functions

func CheckURL

func CheckURL(raw string, hosts []string) error

CheckURL says whether an address may be fetched: https, no credentials, on a host listed. What it says never repeats a login or a query.

func CleanURLError

func CleanURLError(err error) error

CleanURLError takes the login and query out of the address in an error from net/http, which quotes the whole address it was asked for.

func EditINI

func EditINI(old []byte, edits []INIEdit) []byte

EditINI sets keys in an INI file's text and leaves everything else as it was: comments, other keys, their order. A section or key that isn't there is added. It's configfile's INI editor; an edit that one refuses (a key with "=" in it, a value with a line break) is left out.

func GeneratedVersion

func GeneratedVersion(id string) string

GeneratedVersion is the upstream version an emulator's generated schema was read from.

func OwnID

func OwnID(name string) string

OwnID makes an id from a name.

func SafeURL

func SafeURL(raw string) string

SafeURL is an address as it may be logged or shown: no login, no query, no fragment. What can't be parsed is left out altogether.

func SaveOwn

func SaveOwn(path string, list []Own) error

SaveOwn keeps the own programs in a file.

func Sensitive

func Sensitive(names ...string) bool

Sensitive says whether a setting, named by the parts of its path in its file (and its group), is one that must never be offered: see sensitiveWords.

func SetOwn

func SetOwn(list []Own)

SetOwn makes these the administrator's own programs, which Find and ForSystem then know.

func SettingKey

func SettingKey(prefix string, p []string, taken map[string]bool) string

SettingKey makes a setting's key from where its value sits in its file: a plain name of letters, digits and dots, under 48 characters, not one already taken (which it then takes).

func SettingLabel

func SettingLabel(key string) string

SettingLabel makes a label from a key as an emulator names it: "wideScreenHack" is "Wide screen hack", "upscale_multiplier" "Upscale multiplier", "EFBAccessEnable" "EFB access enable". Words in capitals stay so.

func URLHost

func URLHost(raw string) string

URLHost is an address's host alone, for a log.

Types

type Applied

type Applied struct {
	Env  []string
	Args []string
	// Files are the INI edits from INI targets, by file: section, key, value.
	Files map[string][]INIEdit
	// Edits are the edits from file targets, by file, in that file's format. A file may have
	// both INI edits and edits here when its format is INI.
	Edits map[string]FileEdits
}

Applied is what a set of values comes to for one start of an emulator.

func Plan

func Plan(list []Setting, eff Values) Applied

Plan works out what the effective values mean for a start. It writes nothing.

func (Applied) WriteFiles

func (a Applied) WriteFiles(dir string) error

WriteFiles makes the edits under dir, the emulator's settings folder on this machine, each file in its own format.

The emulator can write to that folder too, and an emulator is treated as something that may have been taken over: it could leave a link there pointing anywhere. So every read and write goes through os.Root, which refuses to follow anything out of dir.

type Apply

type Apply struct {
	INI *INITarget `json:"ini,omitempty"`
	// File is a value in one of the emulator's settings files in any format configfile
	// knows: INI, TOML, YAML, XML or JSON.
	File *FileTarget `json:"file,omitempty"`
	// Env is a variable's name. It may not be one the sandbox sets.
	Env string `json:"env,omitempty"`
	// Args are added before the game's path; "{value}" in one is replaced by the value. For a
	// toggle they're added only when it's on.
	Args []string `json:"args,omitempty"`
}

Apply is where a value goes. Exactly one of its parts is set.

type Artifact

type Artifact struct {
	OS     string `json:"os"`
	Arch   string `json:"arch"`
	URL    string `json:"url"`
	SHA256 string `json:"sha256"`
	// Size is the file's size in bytes, when the list knows it. A download of any other size
	// is refused before it is hashed.
	Size    int64  `json:"size,omitempty"`
	Archive string `json:"archive"`
	// Entry is the program to run, inside what the archive unpacks to.
	Entry string `json:"entry"`
	// Args is the command line on this platform, without the program, when it differs from the
	// emulator's own Args: {game} is the game's file, {config} the folder its settings files are
	// in (ConfigDir), {bios} the BIOS folder and {settings} where the settings' own arguments go.
	// Without {game} the game goes last.
	Args []string `json:"args,omitempty"`
	// ConfigDir is where, inside the person's own folder for this emulator, this build keeps the
	// files its settings name: "config" when empty. Some builds take a folder on their command
	// line ({config}); others follow HOME or XDG_CONFIG_HOME, which point inside that folder.
	ConfigDir string `json:"configDir,omitempty"`
	// Portable: this build keeps its settings and data beside its own program, whatever it's
	// told, so each person gets a copy of it in their own folder to run (RPCS3 on Windows).
	Portable bool `json:"portable,omitempty"`
	// Rosetta: an Intel-only Mac build, which an Apple silicon Mac runs through Rosetta 2.
	Rosetta bool `json:"rosetta,omitempty"`
}

Artifact is one download of an emulator, for one platform.

func (Artifact) Placeholder

func (a Artifact) Placeholder() bool

Placeholder says nobody has checked this file's hash.

func (*Artifact) SettingsDir

func (a *Artifact) SettingsDir() string

SettingsDir is where this build's settings files are, inside the person's own folder.

type BiosFile

type BiosFile struct {
	Name string `json:"name"`
	Note string `json:"note,omitempty"`
}

BiosFile is firmware an emulator looks for. WittyPlay never downloads one.

type Choice

type Choice struct {
	Value string `json:"value"`
	Label string `json:"label"`
}

Choice is one value a setting may take, and what a page calls it.

type Emulator

type Emulator struct {
	ID      string   `json:"id"`
	Name    string   `json:"name"`
	Systems []string `json:"systems"`
	License string   `json:"license"`
	// LicenseURL is where the licence's text is, for the page that shows it before an install.
	LicenseURL string `json:"licenseUrl,omitempty"`
	Upstream   string `json:"upstream"`
	Version    string `json:"version"`
	// Requires is the least a machine needs to run it at all. A machine with less is told so
	// instead of being left to crawl.
	Requires Requires `json:"requires,omitzero"`
	// Players is how many controllers it takes; 0 means one.
	Players int `json:"players,omitempty"`
	// Bios names the firmware it looks for in the person's BIOS folder. Names may hold * and ?.
	Bios []BiosFile `json:"bios,omitempty"`
	// Settings are what a page offers for this emulator, and how each is given to it: settings.go.
	Settings []Setting `json:"settings,omitempty"`
	// NonCommercial: its licence forbids commercial use. WittyPlay never offers those for
	// download, as with cores; an administrator can still build an image of their own.
	NonCommercial bool `json:"nonCommercial,omitempty"`
	// Experimental: its own authors call it early work. Pages say so beside it.
	Experimental bool       `json:"experimental,omitempty"`
	Artifacts    []Artifact `json:"artifacts"`
	Display      string     `json:"display"`
	Stream       string     `json:"stream"`
	// Args come before the game's path on the program's command line.
	Args []string `json:"args,omitempty"`
	// NeedsBios: it won't start a game without firmware of the person's own.
	NeedsBios bool  `json:"needsBios,omitempty"`
	Image     Image `json:"image"`
	// Seed are firmware files the emulator writes to (xemu's hard disk image): each is copied
	// from the BIOS folder into the person's own folder the first time, as the BIOS folder is
	// given read-only.
	Seed []string `json:"seed,omitempty"`
	// Place are firmware and keys the emulator looks for inside its own data folder rather than
	// in a BIOS folder: each is copied there from the server's BIOS folder before a start, when
	// the owner has put it there. Nothing is ever fetched.
	Place []Placement `json:"place,omitempty"`
	// Manual: never downloaded; an administrator installs it and adds it (manual.go).
	Manual *Manual `json:"manual,omitempty"`
	// Own: an administrator's own program (own.go), never in the built-in list. Like is the
	// emulator in the list it's a build of, whose settings it takes.
	Own  bool   `json:"own,omitempty"`
	Like string `json:"like,omitempty"`
}

Emulator is one standalone emulator.

func Find

func Find(id string) *Emulator

Find returns an emulator from the built-in list, or an administrator's own program, or nil.

func ForSystem

func ForSystem(system string) []Emulator

ForSystem lists the emulators that can play a console.

func (*Emulator) Base

func (e *Emulator) Base() string

Base is the id whose settings and controller set-up apply: an own program's Like, or its own.

func (*Emulator) For

func (e *Emulator) For(goos, goarch string) *Artifact

For returns the artifact for a platform, or nil. A Mac build for both processors fits either; an Intel-only one fits Apple silicon through Rosetta 2, when there's nothing native.

func (*Emulator) Here

func (e *Emulator) Here() *Artifact

Here returns the artifact for this machine, or nil.

func (*Emulator) ManualArtifact

func (e *Emulator) ManualArtifact(goos string) *Artifact

ManualArtifact is what a download's artifact would say, for an emulator added by hand on goos: its command line, its settings folder and whether it's portable.

func (*Emulator) Placements

func (e *Emulator) Placements(goos string) []Placement

Placements are the keys and firmware to copy for goos: the emulator's own, then a manual install's for that system. Each is relative to the person's own folder for the emulator.

func (*Emulator) Plays

func (e *Emulator) Plays(console string) bool

Plays says whether an emulator plays a console's games, by the console's id.

type FileEdits

type FileEdits struct {
	Format string
	Edits  []configfile.Edit
}

FileEdits are the edits to one settings file.

type FileTarget

type FileTarget struct {
	File   string `json:"file"`   // relative to the settings folder, with forward slashes
	Format string `json:"format"` // ini, toml, yaml, xml or json
	// Path names the value in the file: see configfile.Apply.
	Path []string `json:"path"`
	// Values translates a setting's value to what the file says, as INITarget's does.
	Values map[string]string `json:"values,omitempty"`
	// Type is how the file holds the value where its format tells types apart (TOML, YAML,
	// JSON): bool, int, float or string. Without one it's worked out from the setting: a
	// toggle a bool, a number by its step, a choice by what its value reads as.
	Type string `json:"type,omitempty"`
}

FileTarget is a value in a settings file under the emulator's settings folder.

type INIEdit

type INIEdit struct{ Section, Key, Value string }

INIEdit sets one key.

type INITarget

type INITarget struct {
	File    string `json:"file"` // relative to the settings folder, with forward slashes
	Section string `json:"section"`
	Key     string `json:"key"`
	// Values translates a setting's value to what the file says. Without one the value is
	// written as it is.
	Values map[string]string `json:"values,omitempty"`
}

INITarget is a key in an INI file under the emulator's settings folder.

type Identified

type Identified struct {
	Program string `json:"program"` // the program to run
	Dir     string `json:"dir"`     // the folder it's run from, given read-only
	Entry   string `json:"entry"`   // the program, relative to Dir
	Version string `json:"version,omitempty"`
	// How says what showed it's the emulator, for the log: "bundle identifier", "file name", or
	// "file name and a file beside it".
	How string `json:"how,omitempty"`
}

Identified is a program that was checked to be the emulator.

func Detect

func Detect(e *Emulator, drop, goos string) (Identified, bool)

Detect looks in drop (a folder of the module's own an administrator puts it in: the only way in for a server in a container), then, on this system, where people install it, and answers the first that is it. goos is the system it will run on.

func Identify

func Identify(e *Emulator, p string) (Identified, error)

Identify checks a path is this emulator, on this system: a Mac app bundle (or the program inside one) whose bundle identifier is the emulator's, or a program whose name is. It says in words what's wrong when it isn't.

func IdentifyFor

func IdentifyFor(e *Emulator, p, goos string) (Identified, error)

IdentifyFor is Identify for the system the emulator will run on, which for a container is Linux whatever the server runs on: a Linux AppImage on a Mac's disk, for Docker Desktop.

type Image

type Image struct {
	Ref    string `json:"ref"`
	Digest string `json:"digest"` // sha256:..., or Placeholder
}

Image is the container image an emulator runs in.

func (Image) Pinned

func (i Image) Pinned() string

Pinned is the reference with its digest, which is what gets pulled, or "" when there's no digest to pin to yet.

type Installed

type Installed struct {
	ID          string `json:"id"`
	Version     string `json:"version"`
	Dir         string `json:"dir"`   // <dataDir>/emulators/<id>/<version>
	Entry       string `json:"entry"` // the program, relative to Dir
	SHA256      string `json:"sha256"`
	Source      string `json:"source"`
	InstalledAt int64  `json:"installedAt"`
	// Unverified: it was installed with placeholders allowed, and its hash was only recorded.
	Unverified bool `json:"unverified,omitempty"`
}

Installed is an emulator on this machine.

type Installer

type Installer struct {
	DataDir string
	Client  *http.Client
	Hosts   []string // DefaultHosts if nil
	// AllowPlaceholders installs an entry whose hash says TODO, recording what it got. For
	// developers checking a new entry, never for a server people use.
	AllowPlaceholders bool
	// OnProgress hears how far an install has got. Optional; called from the installing goroutine.
	OnProgress   func(id string, p Progress)
	MaxDownload  int64 // DefaultMaxDownload if 0
	MaxUnpacked  int64 // DefaultMaxUnpacked if 0
	GOOS, GOARCH string
	// Platform, if set, says where emulators run, which isn't always where this program does:
	// a Docker daemon in a virtual machine runs Linux programs whatever the server's own system
	// is. It's asked at each install.
	Platform func() (goos, goarch string)
	// contains filtered or unexported fields
}

Installer installs emulators under DataDir/emulators.

func (*Installer) Artifact

func (in *Installer) Artifact(e *Emulator) *Artifact

Artifact is the download of e for where emulators run, or nil.

func (*Installer) Get

func (in *Installer) Get(id string) *Installed

Get returns one installed emulator, or nil.

func (*Installer) Install

func (in *Installer) Install(ctx context.Context, e *Emulator) (*Installed, error)

Install downloads one emulator from the list, checks its hash before anything is unpacked, unpacks it into a staging folder, and moves that into place in one step.

func (*Installer) List

func (in *Installer) List() ([]Installed, error)

List returns what's installed, by id.

func (*Installer) LoadManualFile

func (in *Installer) LoadManualFile(goos string) []error

LoadManualFile registers what the file names, and says what it couldn't.

func (*Installer) ManualFile

func (in *Installer) ManualFile() string

ManualFile is where an administrator can name their emulators' programs without a page, for a server with no screen or in a container: {"ryujinx": "/opt/ryujinx/Ryujinx"}. It's read when the module starts.

func (*Installer) RegisterManual

func (in *Installer) RegisterManual(e *Emulator, id Identified) (*Installed, error)

RegisterManual records an emulator the administrator installed, as it was identified.

func (*Installer) Root

func (in *Installer) Root() string

Root is the folder everything goes in.

func (*Installer) Uninstall

func (in *Installer) Uninstall(id string) error

Uninstall removes an emulator and everything under its folder. Saves and settings aren't there: they're in each person's own folder.

type Manifest

type Manifest struct {
	Schema    int        `json:"schema"`
	Note      string     `json:"note,omitempty"`
	Emulators []Emulator `json:"emulators"`
}

Manifest is the whole list.

func Builtin

func Builtin() (*Manifest, error)

Builtin is the list that comes with this version. A test holds it valid, so an error here is a build that shouldn't have been released.

func Parse

func Parse(b []byte) (*Manifest, error)

Parse reads a manifest and checks it.

func (*Manifest) Placeholders

func (m *Manifest) Placeholders() []string

Placeholders lists what in the list still says TODO, for a report.

func (*Manifest) Validate

func (m *Manifest) Validate() error

Validate checks every entry: names, platforms, hosts, hashes and digests. A hash or digest may be Placeholder, and nothing else that isn't one.

type Manual

type Manual struct {
	// Download is the project's own page, shown to the administrator. Never fetched.
	Download string `json:"download"`
	// Programs are the program's file names on each system (GOOS), as path.Match patterns:
	// "Ryujinx.exe", "ryujinx-*.AppImage".
	Programs map[string][]string `json:"programs"`
	// BundleIDs are a Mac app's CFBundleIdentifier, any of which proves it.
	BundleIDs []string `json:"bundleIds,omitempty"`
	// Look are where people install it, per system, tried in order by Detect. ~ is the home
	// folder; $NAME a variable of the module's environment.
	Look map[string][]string `json:"look,omitempty"`
	// VersionFrom is a regular expression whose first group is the version, matched against the
	// program's file name (a Linux AppImage's name carries it).
	VersionFrom string `json:"versionFrom,omitempty"`
	// Notes are things to say beside it: the state of what it plays.
	Notes string `json:"notes,omitempty"`
	// Beside are files one of which sits beside the program (inside a Mac app, beside its
	// program) when the name and the bundle identifier aren't enough to tell it apart.
	Beside []string `json:"beside,omitempty"`
	// Args, ConfigDir and Portable are, per system, what an artifact says for a download:
	// its command line, where its settings files are in the person's own folder, and whether
	// it keeps its data beside its program (each person then runs a copy of their own).
	Args      map[string][]string `json:"args,omitempty"`
	ConfigDir map[string]string   `json:"configDir,omitempty"`
	Portable  []string            `json:"portable,omitempty"`
	// Place are, per system, the keys and firmware it looks for in its own data folder, copied
	// there from the server's BIOS folder before a start.
	Place map[string][]Placement `json:"place,omitempty"`
}

Manual says how to recognise an emulator installed by hand.

type Own

type Own struct {
	ID      string   `json:"id"`
	Name    string   `json:"name"`
	Systems []string `json:"systems"`
	// Program is the program's full path on this server.
	Program string `json:"program"`
	// Args is its command line, with {game}, {config}, {bios} and {settings} as in the list.
	Args []string `json:"args,omitempty"`
	// ConfigDir is where its settings files end up inside each person's folder for it.
	ConfigDir string `json:"configDir,omitempty"`
	// Like says it's a build of an emulator in the list (an rpcs3 from FreeBSD's packages), so
	// that emulator's settings and controller set-up apply to it.
	Like  string `json:"like,omitempty"`
	Added int64  `json:"added"`
}

Own is what an administrator says about their program.

func CheckOwn

func CheckOwn(o Own, consoleOK func(string) bool) (Own, error)

CheckOwn holds an own program to what can safely be run: a real program file the server can see, a name, consoles by WittyPlay's ids, and a command line with no line breaks.

func LoadOwn

func LoadOwn(path string) ([]Own, error)

LoadOwn reads the own programs kept in a file; a missing file is none.

func OwnList

func OwnList() []Own

OwnList is the administrator's own programs.

func (Own) Emulator

func (o Own) Emulator() Emulator

Emulator is an own program as a list entry: no downloads, nothing to pin, its own command line as this machine's one artifact, and the settings of the emulator it's like.

func (Own) Installed

func (o Own) Installed() Installed

Installed is an own program as the installer records one: its folder and its file.

type Placement

type Placement struct {
	From string `json:"from"` // in the BIOS folder: a file, or a folder whose contents are copied
	To   string `json:"to"`   // relative to the person's own folder for the emulator
	Note string `json:"note,omitempty"`
}

Placement is one file or folder from the BIOS folder, and where it goes in the person's own folder for the emulator.

type Progress

type Progress struct {
	Phase string // downloading | verifying | unpacking | done
	Got   int64
	Total int64 // -1: not known
	// Resumed is how much of the download was kept from an earlier try.
	Resumed int64
}

Progress is how far an install has got.

type Requires

type Requires struct {
	MemoryMB int64   `json:"memoryMB,omitempty"`
	CPUs     float64 `json:"cpus,omitempty"`
	GPU      bool    `json:"gpu,omitempty"` // unplayably slow without a graphics card passed through
}

Requires is the least an emulator needs.

type SchemaFile

type SchemaFile struct {
	Emulator string    `json:"emulator"`
	Version  string    `json:"version"` // the upstream tag the settings were read from
	Source   string    `json:"source,omitempty"`
	Settings []Setting `json:"settings"`
}

SchemaFile is what a generated schema file holds.

type ScopeError

type ScopeError struct{ Label string }

ScopeError is someone setting what only an administrator may.

func (*ScopeError) Error

func (e *ScopeError) Error() string

type Setting

type Setting struct {
	Key     string   `json:"key"`
	Kind    string   `json:"kind"`
	Label   string   `json:"label"`
	Help    string   `json:"help,omitempty"`
	Default any      `json:"default"`
	Min     float64  `json:"min,omitempty"`
	Max     float64  `json:"max,omitempty"`
	Step    float64  `json:"step,omitempty"`
	Choices []Choice `json:"choices,omitempty"`
	// Scope is who may set it: "admin", or "user" for each person (and each of their games).
	Scope string `json:"scope"`
	// MapOf and MapKeys describe a map's values and the keys it may have.
	MapOf   string   `json:"mapOf,omitempty"`
	MapKeys []Choice `json:"mapKeys,omitempty"`
	// Fixed: it's written as its default every time and never offered: where the sandbox
	// puts the BIOS folder, say.
	Fixed bool `json:"fixed,omitempty"`
	// Apply is how the value reaches the emulator. A setting without one is used by WittyPlay
	// itself (the stream's size, the keys).
	Apply *Apply `json:"apply,omitempty"`
	// Group is the heading a page lists it under: the emulator's own section, in words.
	Group string `json:"group,omitempty"`
	// Advanced settings are ones few people need (debugging, odd hardware): a page may tuck
	// them away.
	Advanced bool `json:"advanced,omitempty"`
}

Setting describes one setting.

func Discover

func Discover(format string, data []byte, known []Setting) []Setting

Discover finds the options in a person's real settings file that no setting in known describes, so an option a newer emulator added still appears on the page. Each comes back as a setting for the person (scope user), its kind read from the value the file has now (which is also its default), labelled from its key and grouped by its section; one that names a path, an address or anything else that reaches outside the sandbox is fixed, never offered.

The file the options are written back to is the one of known's that is in this format and shares the most values with data; with none, nothing is found.

func FullSchema

func FullSchema(curated []Setting, id string) []Setting

FullSchema lays the manifest's own settings for an emulator over its generated ones. A curated setting wins over a generated one with the same key, and over one that writes the same value in the same file: the curated one was written with care (friendlier choices, the sandbox's own paths), the generated one only says the option exists.

func GeneratedSettings

func GeneratedSettings(id string) []Setting

GeneratedSettings is every setting read from an emulator's own source, or nil when there's no schema for it. The list is the caller's own copy.

func Offered

func Offered(list []Setting) []Setting

Offered is a list without its fixed settings: what a page shows.

func (Setting) Clean

func (s Setting) Clean(v any) (any, error)

Clean checks one value against its setting and returns it in the form it's kept in: a bool, a float64, a string, or a map of those.

type Store

type Store struct {
	Path string // "" keeps them in memory only
	// contains filtered or unexported fields
}

Store keeps every layer of every emulator's settings in one file.

func (*Store) ForgetUser

func (st *Store) ForgetUser(user int64) error

ForgetUser drops one account's settings, when the server says the account has gone. Settings outlive an uninstall, as saves do, so that installing the emulator again finds them.

func (*Store) Layers

func (st *Store) Layers(emulator string, user, game int64) (admin, own, forGame Values)

Layers returns one emulator's values for an account and, when game isn't 0, one game.

func (*Store) Set

func (st *Store) Set(emulator, scope string, user, game int64, vals Values) error

Set merges cleaned values into one layer and saves. A nil value clears its key.

type Values

type Values map[string]any

Values are settings' values by key.

func CleanValues

func CleanValues(list []Setting, scope string, in Values) (Values, error)

CleanValues checks a write to one layer. A nil value clears a key. Only an administrator's layer may hold a setting whose scope is admin.

func Effective

func Effective(list []Setting, admin, user, game Values) Values

Effective layers values over the defaults: admin, then user, then game. A value that no longer fits its setting (the list changed) is passed over, and a layer below the administrator's never changes an admin-only setting, whatever a file says.

Directories

Path Synopsis
Package configfile reads and edits the settings files emulators keep, in their own formats: INI, TOML, YAML, XML and JSON.
Package configfile reads and edits the settings files emulators keep, in their own formats: INI, TOML, YAML, XML and JSON.
Package inputmap writes the keyboard bindings each standalone emulator needs so that the keys WittyPlay injects for a player's pad (see sandbox/docker/inputagent's KeyMap) press that player's buttons.
Package inputmap writes the keyboard bindings each standalone emulator needs so that the keys WittyPlay injects for a player's pad (see sandbox/docker/inputagent's KeyMap) press that player's buttons.

Jump to

Keyboard shortcuts

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