wittyplayfile

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: 9 Imported by: 0

Documentation

Overview

Package wittyplayfile reads and writes .wittyplay files: a small, open JSON format that says how games are pictured in WittyPlay (box art fitted or filled, or drawn in a cartridge or case, which case, and what goes on its label), for everything, per console and per game. The format's open specification is docs/specs/wittyplay-file.md (CC0) with its JSON Schema beside it.

A reader keeps what it doesn't know: unknown fields, at any level, are carried through a read and a write unchanged, so a file made by a newer program loses nothing passing through an older one.

Index

Constants

View Source
const (
	// Version is the one version this reader understands; a file says it in its "wittyplay" field.
	Version = 1
	// Ext is the file extension, MediaType its registered-style media type.
	Ext       = ".wittyplay"
	MediaType = "application/vnd.wittyplay+json"
	// MaxSize is the largest file read, in bytes.
	MaxSize = 64 << 10
	// Limits on what one file holds.
	MaxGames    = 2000
	MaxConsoles = 200
	MaxName     = 200
	MaxText     = 1000
)

The format's identity.

View Source
const (
	PictureFitted = "fitted" // the whole box art, over a blurred, dimmed copy of itself
	PictureFilled = "filled" // the box art fills the tile, cropped to it
	PictureCase   = "case"   // drawn in a cartridge, disc case or the like
)

Picture values: how the art is shown.

View Source
const (
	LabelBoxArt = "boxart"
	LabelTitle  = "title"
)

Label values: what goes on a case's label.

View Source
const CaseAuto = "auto"

CaseAuto lets the console decide the case.

Variables

View Source
var (
	ErrTooBig = fmt.Errorf("a .wittyplay file is at most %d KB", MaxSize>>10)
	ErrNewer  = errors.New("this .wittyplay file was made for a newer version of the format")
)

Errors a caller can tell apart.

View Source
var CaseStyles = []string{}/* 195 elements not displayed */

CaseStyles are the case drawings this version names. A file may name another (a newer program's); a reader that doesn't know it draws the console's own.

View Source
var Media = []string{
	"cart-8bit", "cart-early", "cart-16bit", "cart-mega", "cart-64", "cart-pocket", "cart-advance", "card", "hucard",
	"cd", "gd", "dvd", "bluray", "minidisc", "umd", "floppy35", "floppy525", "tape", "arcade", "digital", "other",
}

Media are the kinds of medium games came on, each with its own case styles (docs/specs/wittyplay-file.md, "Media"): a look's "cases" chooses a style per medium.

Functions

func KnownCase

func KnownCase(id string) bool

KnownCase says the case style is one this version draws.

Types

type Doc

type Doc struct {
	Version     int             `json:"wittyplay"`
	Name        string          `json:"name,omitempty"`
	Description string          `json:"description,omitempty"`
	Generator   string          `json:"generator,omitempty"`
	Default     *Look           `json:"default,omitempty"`
	Consoles    map[string]Look `json:"consoles,omitempty"`
	Games       []Game          `json:"games,omitempty"`
	Extra       Extra           `json:"-"`
}

Doc is a whole file.

func Parse

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

Parse reads and checks a file's bytes.

func Read

func Read(r io.Reader) (*Doc, error)

Read reads one file from r, refusing anything over MaxSize.

func (*Doc) Encode

func (d *Doc) Encode() ([]byte, error)

Encode writes the document as a file: indented, ending in a new line.

func (*Doc) For

func (d *Doc) For(item int64, console, file, title string) Look

For is the look a document gives one game: its default, then its console's, then each entry that matches, a later entry over an earlier one. A file name or title is matched without regard to case.

func (Doc) MarshalJSON

func (d Doc) MarshalJSON() ([]byte, error)

MarshalJSON writes the document with "wittyplay" first, so a person opening it sees what it is.

func (*Doc) Validate

func (d *Doc) Validate() error

Validate checks a document against the format's rules.

type Extra

type Extra map[string]json.RawMessage

Extra holds the fields a reader didn't know, as they were.

type Game

type Game struct {
	Match Match `json:"match"`
	Look
}

Game is one game's look.

func (Game) MarshalJSON

func (g Game) MarshalJSON() ([]byte, error)

func (*Game) UnmarshalJSON

func (g *Game) UnmarshalJSON(b []byte) error

type Look

type Look struct {
	Picture string `json:"picture,omitempty"`
	Case    string `json:"case,omitempty"`
	Label   string `json:"label,omitempty"`
	// Cases is a case style per kind of medium (Media), for every game of that medium the look covers.
	Cases map[string]string `json:"cases,omitempty"`
	Extra Extra             `json:"-"`
}

Look is how pictures are shown at one level. Every field is optional: an empty one is decided by the level above.

func (Look) Empty

func (l Look) Empty() bool

Empty says nothing is set.

func (Look) MarshalJSON

func (l Look) MarshalJSON() ([]byte, error)

func (Look) Over

func (l Look) Over(under Look) Look

Over is l with every field it leaves empty taken from under.

func (*Look) UnmarshalJSON

func (l *Look) UnmarshalJSON(b []byte) error

type Match

type Match struct {
	Item    int64  `json:"item,omitempty"`
	File    string `json:"file,omitempty"`
	Title   string `json:"title,omitempty"`
	Console string `json:"console,omitempty"`
	Extra   Extra  `json:"-"`
}

Match says which game an entry is for. Item is a server's own id, meaningful only on the server that wrote it; File a ROM's file name; Title and Console a game's name on a console.

func (Match) MarshalJSON

func (m Match) MarshalJSON() ([]byte, error)

func (Match) Matches

func (m Match) Matches(item int64, console, file, title string) bool

Matches says the entry is for this game: every field it gives agrees.

func (*Match) UnmarshalJSON

func (m *Match) UnmarshalJSON(b []byte) error

Jump to

Keyboard shortcuts

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