ipc

package
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: 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-host, 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 Apache-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
)

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
)

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 InputSize = 11

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.

View Source
const TestCore = "builtin:test"

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

View Source
const VideoHeaderSize = 5

VideoHeaderSize is the encoded size of a VideoHeader.

Variables

This section is empty.

Functions

func ParseInput

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

ParseInput reads one player's state.

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 Event

type Event struct {
	Type     string  `json:"type"` // rumble | message | geometry | rotation | log | shutdown | avinfo
	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"`
}

Event is something a player should be told about.

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"`
}

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 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"`
}

Ready says a game has loaded.

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