ipc

package
v0.7.2 Latest Latest
Warning

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

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

Documentation

Overview

Package ipc is the protocol between the server and a game runner process: length-prefixed messages over the runner's stdin and stdout.

A runner is wittyplay-game-runner, or any other program that speaks this protocol, such as WittyRetroArch. Talking over pipes is what keeps a GPL runner a separate program from the AGPL-licensed server, so this package is the whole of what they share. docs/GAMING.md has the licensing reasons.

The server treats everything a runner says as hostile. A core may have been taken over by a bad ROM, so every message has a size limit, read here before any memory is set aside.

Index

Constants

View Source
const (
	MsgReady   byte = 1  // JSON: Ready
	MsgVideo   byte = 2  // VideoHeader + tightly packed rows
	MsgDupe    byte = 3  // the previous frame again
	MsgAudio   byte = 4  // s16le stereo
	MsgState   byte = 5  // u32 request id + save state (empty: the core has none)
	MsgSaveRAM byte = 6  // battery save
	MsgEvent   byte = 7  // JSON: Event
	MsgError   byte = 8  // text, then the host exits
	MsgTiming  byte = 9  // FrameTimingSize bytes: when the next picture was made. Optional
	MsgProbe   byte = 20 // JSON: Probe, the answer to CmdProbe
)

Messages from the host.

View Source
const (
	CmdLoad      byte = 64 // JSON: Load
	CmdSaveRAM   byte = 65 // battery save to restore; sent before the first unpause
	CmdState     byte = 66 // a save state to restore
	CmdInput     byte = 67 // InputSize bytes
	CmdSaveState byte = 68 // u32 request id
	CmdReset     byte = 69
	CmdPause     byte = 70 // one byte: 1 paused, 0 running
	CmdQuit      byte = 71 // one byte: 1 sends a save state first; battery save is always sent
	CmdDisc      byte = 72 // one byte: the disc to change to, from 0
	CmdPointer   byte = 73 // PointerSize bytes: a touch screen or mouse
	CmdTouches   byte = 74 // TouchesMark, a count, then TouchSize bytes a finger: every finger on a touch screen
	CmdMotion    byte = 75 // MotionSize bytes: one player's accelerometer and gyroscope
	CmdDevice    byte = 80 // DeviceSize bytes: plug a kind of controller into a port
	CmdControl   byte = 96 // JSON: Control; how the game runs
	CmdOption    byte = 97 // JSON: OptionSet; a core option, only ever one the core offered
	CmdCheats    byte = 98 // JSON: []Cheat; the whole list, replacing what was there
	CmdProbe     byte = 90 // JSON: Load. Test-loads the core, answers MsgProbe and exits
)

Commands to the host.

View Source
const (
	MaxVideoFrame = 4096 * 2304 * 4
	MaxAudio      = 1 << 20
	MaxJSON       = 1 << 20
	MaxBlob       = 512 << 20
	MaxDimension  = 4096
)

Size limits. MaxVideoFrame is far above what a console produces (4K at four bytes a pixel), and MaxBlob holds the largest save states.

View Source
const (
	MaxStateSlot = 99
	SlotUndo     = 100
	SlotPrevAuto = 101
)

Save slots: 0 is automatic and 1 to MaxStateSlot belong to a person. The other two are kept for mistakes: what was running before the last load, and the automatic save that starting over would have replaced.

View Source
const (
	MaxOptionKey   = 128
	MaxOptionValue = 128
)

Limits on what's said about a core's options.

View Source
const (
	SpeedMin       = 0.1
	SpeedMax       = 16.0
	FrameSkipAuto  = -1
	FrameSkipMax   = 8
	RunAheadMax    = 3
	RunAheadAuto   = -1 // from a setting: whatever suits this core. A runner is never sent it.
	RewindBytesMax = 512 << 20
	AdvanceMax     = 60
)

Limits a runner holds to whatever it's told.

View Source
const (
	InputSize        = 11
	InputSizeFull    = 13
	InputSizeStamped = 17
)

InputSize is the size of a CmdInput payload: port, buttons, then the left and right sticks' X and Y. A browser sends the same bytes. InputSizeFull adds how far the L2 and R2 triggers are held, 0 to 255, for clients that can tell. InputSizeStamped adds a u32 that names this state, so that the picture it first affects can be found.

View Source
const (
	PointerSize = 6
	PointerMark = 0xFF
)

PointerSize is the size of a pointer message. Its first byte, PointerMark, can't begin a pad message, so a client sends both down the same channel. Then come flags, X and Y. X and Y run from -32767 to 32767 across the picture, the way libretro counts them.

View Source
const (
	TouchesMark = 0xFE
	TouchSize   = 6
	MaxTouches  = 10
)

Touches: several fingers at once. TouchesMark, a count up to MaxTouches, then for each finger an id of the client's choosing, flags (bit 0: pressed), X and Y as a pointer has them.

View Source
const (
	MotionMark = 0xE1
	MotionSize = 14
)

Motion: MotionMark, the player, then the accelerometer's X, Y and Z in 1/4096 g and the gyroscope's X, Y and Z in 1/16 of a degree a second, each an i16. Axes are a device's own, held as the console's controller: X to the right, Y up, Z towards the player.

View Source
const DeviceSize = 5

DeviceSize is the size of a CmdDevice payload: port, then a u32 device type.

View Source
const DisplayPaceLimit = 0.01

DisplayPaceLimit is how far a screen's rate may be from a game's for the game to keep to the screen: 1% changes the pitch of its sound by less than anyone hears.

View Source
const FrameTimingSize = 32

FrameTimingSize is the encoded size of a FrameTiming.

View Source
const TestCore = "builtin:test"

TestCore is the Load.Core value for the built-in test core.

View Source
const Version = "1"

Version names this protocol, as the capability "ipc" in WittyPlay's manifest. The server's streaming half and a downloaded runner are compiled apart, so the server refuses a runner whose manifest names any other. The messages themselves have no version to read: raise this, and the manifest with it, whenever one changes or a new one is added.

View Source
const VideoHeaderSize = 5

VideoHeaderSize is the encoded size of a VideoHeader.

Variables

This section is empty.

Functions

func InputStamp added in v0.3.3

func InputStamp(p []byte) uint32

InputStamp reads the number of a stamped state, which is 0 when it has none.

func ParseInput

func ParseInput(p []byte) (port int, buttons uint16, lx, ly, rx, ry int16, ok bool)

ParseInput reads one player's state.

func ParseMotion added in v0.3.5

func ParseMotion(p []byte) (port int, accel, gyro [3]float32, ok bool)

ParseMotion reads one player's motion, in the units libretro's cores take: metres a second squared and radians a second, as RetroArch passes on a phone's sensors.

func ParsePointer added in v0.3.3

func ParsePointer(p []byte) (x, y int16, pressed, ok bool)

ParsePointer reads a touch screen or mouse state.

func ParseTriggers added in v0.3.3

func ParseTriggers(p []byte) (l2, r2 uint8)

ParseTriggers reads the analog triggers of a state, which are 0 when it has none.

func Write

func Write(w io.Writer, t byte, parts ...[]byte) error

Write sends one message. Small messages go out in a single write.

Types

type Cheat added in v0.3.3

type Cheat struct {
	Code    string `json:"code"`
	Enabled bool   `json:"enabled"`
}

Cheat is one code as a core's cheat interface takes it.

type Control added in v0.3.3

type Control struct {
	Speed         *float64 `json:"speed,omitempty"`         // 1 is normal; SpeedMin to SpeedMax
	FrameSkip     *int     `json:"frameSkip,omitempty"`     // FrameSkipAuto, 0 for none, or how many to skip after each shown
	RewindBytes   *int64   `json:"rewindBytes,omitempty"`   // memory rewind may use; 0 turns it off
	RewindSeconds *int     `json:"rewindSeconds,omitempty"` // how far back to keep
	Rewinding     *bool    `json:"rewinding,omitempty"`     // going backwards now
	RunAhead      *int     `json:"runAhead,omitempty"`      // frames; 0 to RunAheadMax
	Advance       *int     `json:"advance,omitempty"`       // frames to run while paused
	// EarlyInput lets a new press start the next frame straight away, rather than waiting for
	// its turn. It's on unless this says otherwise.
	NoEarlyInput *bool `json:"noEarlyInput,omitempty"`
	// QuietAhead: run-ahead wasn't anyone's choice, so turning itself off isn't worth a message.
	QuietAhead *bool `json:"quietAhead,omitempty"`
	// ShiftMs moves when frames start, once, by this many milliseconds, to land them just
	// before a viewer's display wants them. Later is positive.
	ShiftMs *float64 `json:"shiftMs,omitempty"`
	// DisplayHz is the refresh rate of the screen the game is shown on. When it's within
	// DisplayPaceLimit of the game's own rate, frames come at the screen's rate instead, so
	// that none is dropped or shown twice. 0 goes back to the game's own.
	DisplayHz *float64 `json:"displayHz,omitempty"`
}

Control changes how a game runs. Only what is present changes.

type DeviceType added in v0.3.3

type DeviceType struct {
	ID   uint32 `json:"id"`
	Name string `json:"name"`
}

DeviceType is one kind of controller.

type Event

type Event struct {
	Type     string  `json:"type"` // rumble | message | geometry | rotation | log | shutdown | avinfo | options | stats | statefail | frame | trace | disc
	Port     int     `json:"port,omitempty"`
	Effect   int     `json:"effect,omitempty"`
	Strength int     `json:"strength,omitempty"`
	Text     string  `json:"text,omitempty"`
	Level    int     `json:"level,omitempty"`
	Width    int     `json:"width,omitempty"`
	Height   int     `json:"height,omitempty"`
	Aspect   float64 `json:"aspect,omitempty"`
	Turns    int     `json:"turns,omitempty"`
	FPS      float64 `json:"fps,omitempty"`
	Rate     float64 `json:"rate,omitempty"`
	Index    int     `json:"index,omitempty"`
	Count    int     `json:"count,omitempty"`
	// For "motion": whether the game wants this player's accelerometer and gyroscope now, and
	// how often; Offered says the core can read motion at all. For "led": the light's State.
	Accel   bool `json:"accel,omitempty"`
	Gyro    bool `json:"gyro,omitempty"`
	Hz      int  `json:"hz,omitempty"`
	Offered bool `json:"offered,omitempty"`
	State   int  `json:"state,omitempty"`
	// Options is every option the core offers, for "options".
	Options []Option `json:"options,omitempty"`
	// Stats comes once a second while a game runs, for "stats".
	Stats *RunStats `json:"stats,omitempty"`
}

Event is something a player should be told about.

type FrameTiming added in v0.3.3

type FrameTiming struct {
	Seq      uint32 // counts frames from the start of the game
	InputSeq uint32 // the newest numbered input this frame could have seen
	InputAt  int64  // when that input reached the runner
	RunStart int64  // when the core began this frame
	RunEnd   int64  // when the picture was ready
}

FrameTiming says when a picture was made, as Unix nanoseconds on the machine's clock. A runner sends it just before the picture it describes. It's for measuring and nothing else, so a runner may leave it out, and nothing depends on a value being sensible.

func ParseFrameTiming added in v0.3.3

func ParseFrameTiming(p []byte) (FrameTiming, bool)

ParseFrameTiming reads a MsgTiming payload.

func (FrameTiming) Append added in v0.3.3

func (t FrameTiming) Append(b []byte) []byte

Append adds the timing to b.

type Load

type Load struct {
	Core    string            `json:"core"`
	ROM     string            `json:"rom"`
	System  string            `json:"system"`
	Save    string            `json:"save"`
	Options map[string]string `json:"options,omitempty"`
	Trace   bool              `json:"trace,omitempty"` // send everything the core says as log events; for wittyplay-check
	// PreferDevices names the controller to plug in, by words in its name, best first.
	PreferDevices []string `json:"preferDevices,omitempty"`
	// Probe asks only which options the core offers: the runner sends them and exits
	// without a game. ROM is empty then.
	Probe  bool   `json:"probe,omitempty"`
	Assets string `json:"assets,omitempty"` // support files of its own, if it has any
	// Stamp draws each frame's number and the newest input it saw into the picture, for
	// measuring a whole path by looking at what arrives. Only wittyplay-probe asks for it.
	Stamp bool `json:"stamp,omitempty"`
}

Load is what a runner needs to start a game. Core TestCore is the built-in test core and any other value is a shared library path.

type Option added in v0.3.3

type Option struct {
	Key      string   `json:"key"`
	Label    string   `json:"label"`
	Info     string   `json:"info,omitempty"`
	Category string   `json:"category,omitempty"`
	Choices  []string `json:"choices"`
	Labels   []string `json:"labels,omitempty"` // the name of each choice, when it has one
	Default  string   `json:"default,omitempty"`
	Value    string   `json:"value"`
	Hidden   bool     `json:"hidden,omitempty"` // the core says it doesn't apply just now
}

Option is one setting a core offers. The first choice is the core's default.

type OptionSet added in v0.3.3

type OptionSet struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

OptionSet changes one option. A runner ignores a key the core didn't offer or a value it didn't list, so this can't reach anything else.

type PortDevices added in v0.3.3

type PortDevices struct {
	Port    int          `json:"port"`
	Types   []DeviceType `json:"types"`
	Current uint32       `json:"current"`
}

PortDevices lists what can be plugged into one port.

type Probe added in v0.3.3

type Probe struct {
	Name         string   `json:"name"`
	Version      string   `json:"version"`
	Extensions   []string `json:"extensions"`
	NeedFullPath bool     `json:"needFullPath,omitempty"`
	BlockExtract bool     `json:"blockExtract,omitempty"`
	NoGame       bool     `json:"noGame,omitempty"`   // it can run with no game
	HWRender     bool     `json:"hwRender,omitempty"` // it already asked for a graphics card
	Options      int      `json:"options,omitempty"`  // how many settings it offered
}

Probe is what a core says about itself when test-loaded. It comes from code nobody has vouched for, so the server cleans it before showing it to anyone.

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

Reader reads messages; the returned payload is valid until the next call.

func NewReader

func NewReader(r io.Reader) *Reader

func (*Reader) Next

func (r *Reader) Next() (t byte, payload []byte, err error)

Next reads one message. An unknown type or an oversized message is an error, and the connection is finished then.

type Ready

type Ready struct {
	Name       string  `json:"name"`
	Version    string  `json:"version"`
	Width      int     `json:"width"`
	Height     int     `json:"height"`
	Aspect     float64 `json:"aspect"`
	FPS        float64 `json:"fps"`
	SampleRate float64 `json:"sampleRate"`
	Disc       int     `json:"disc,omitempty"`     // the disc in the drive, from 0
	Discs      int     `json:"discs,omitempty"`    // how many the game has; 0 or 1 is nothing to choose
	Renderer   string  `json:"renderer,omitempty"` // the graphics card, for a game drawn on one
	// Devices: the kinds of controller this core offers, when it offers a choice.
	Devices []PortDevices `json:"devices,omitempty"`
}

Ready says a game has loaded.

type RunStats added in v0.3.3

type RunStats struct {
	Ran          int   `json:"ran"`                    // frames the game ran
	Shown        int   `json:"shown"`                  // of those, how many were sent
	Skipped      int   `json:"skipped"`                // left out to keep up or on request
	RewindBytes  int64 `json:"rewindBytes,omitempty"`  // memory rewind holds
	RewindFrames int   `json:"rewindFrames,omitempty"` // steps back it holds
}

RunStats says what a runner did over the last second.

type Touch added in v0.3.5

type Touch struct {
	ID      byte
	Pressed bool
	X, Y    int16
}

Touch is one finger.

func ParseTouches added in v0.3.5

func ParseTouches(p []byte) ([]Touch, bool)

ParseTouches reads every finger on a touch screen. The list may be empty: nothing touching.

type VideoHeader

type VideoHeader struct {
	Width, Height int
	Format        int
}

VideoHeader starts a MsgVideo payload.

func ParseVideo

func ParseVideo(p []byte) (VideoHeader, []byte, error)

ParseVideo checks a MsgVideo payload: the sizes must add up exactly, so what goes on to FFmpeg is always a whole frame of the size it was told to expect.

func (VideoHeader) Append

func (h VideoHeader) Append(b []byte) []byte

Append adds the header to b.

Jump to

Keyboard shortcuts

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