README
¶
go-gameid
A Go library for identifying video game ROM and disc images. Detects console types from file extensions and headers, then extracts game metadata (IDs, titles, regions) from various retro gaming formats. Supports Game Boy, GBA, NES, SNES, N64, Genesis, GameCube, PlayStation, PS2, PSP, Saturn, Sega CD, and Neo Geo CD.
Installation
go get github.com/ZaparooProject/go-gameid
Usage
import "github.com/ZaparooProject/go-gameid"
// Auto-detect console and identify
result, err := gameid.Identify("game.gba", nil)
// With database for title lookups
db, _ := gameid.LoadDatabase("games.gob.gz")
result, err := gameid.Identify("game.iso", db)
// Specify console explicitly
result, err := gameid.IdentifyWithConsole("game.bin", gameid.ConsolePSX, db)
CLI
# Build
make gameid
# Run
./cmd/gameid/gameid -i game.gba -json
./cmd/gameid/gameid -i game.iso -c PSX -db games.gob.gz
Acknowledgements
This project is a Go port of GameID by Niema Moshiri. The original Python implementation and game database are the foundation of this work.
Test data files in testdata/ are from the 240p Test Suite by Artemio Urbina, licensed under GPL-3.0.
License
GPL-3.0-or-later. See LICENSE for details.
Documentation
¶
Overview ¶
Package gameid provides game identification for various video game consoles. It can detect the console type from file extensions and headers, then extract game metadata from ROM/disc images.
Index ¶
- Constants
- Variables
- func DetectConsole(path string) (identifier.Console, error)
- func DetectConsoleFromExtension(path string) (identifier.Console, error)
- func IsCartridgeBased(console Console) bool
- func IsDiscBased(console Console) bool
- func SupportedConsoles() []string
- type Console
- type GameDatabase
- func (db *GameDatabase) GetIDPrefixes(console identifier.Console) []string
- func (db *GameDatabase) Lookup(console identifier.Console, key any) (map[string]string, bool)
- func (db *GameDatabase) LookupByString(console identifier.Console, key string) (map[string]string, bool)
- func (db *GameDatabase) SaveDatabase(path string) error
- type Result
- func Identify(path string, db *GameDatabase) (*Result, error)
- func IdentifyFromArchive(arc archive.Archive, internalPath string, console Console, db *GameDatabase) (*Result, error)
- func IdentifyFromReader(reader interface{ ... }, size int64, console Console, database *GameDatabase) (*Result, error)
- func IdentifyWithConsole(path string, console Console, db *GameDatabase) (*Result, error)
Constants ¶
const ( ConsoleGB = identifier.ConsoleGB ConsoleGBC = identifier.ConsoleGBC ConsoleGBA = identifier.ConsoleGBA ConsoleGC = identifier.ConsoleGC ConsoleGenesis = identifier.ConsoleGenesis ConsoleN64 = identifier.ConsoleN64 ConsoleNeoGeoCD = identifier.ConsoleNeoGeoCD ConsoleNES = identifier.ConsoleNES ConsolePSP = identifier.ConsolePSP ConsolePSX = identifier.ConsolePSX ConsolePS2 = identifier.ConsolePS2 ConsoleSaturn = identifier.ConsoleSaturn ConsoleSegaCD = identifier.ConsoleSegaCD ConsoleSNES = identifier.ConsoleSNES )
Re-export console constants for convenience.
Variables ¶
var AllConsoles = identifier.AllConsoles
AllConsoles is a list of all supported consoles.
Functions ¶
func DetectConsole ¶
func DetectConsole(path string) (identifier.Console, error)
DetectConsole attempts to detect the console type for a given file. Returns the detected console or an error if detection fails.
func DetectConsoleFromExtension ¶
func DetectConsoleFromExtension(path string) (identifier.Console, error)
DetectConsoleFromExtension detects the console type based purely on file extension. Unlike DetectConsole, this does not read file headers or check file existence. It returns an error for ambiguous extensions (like .bin, .iso) that require header analysis.
func IsCartridgeBased ¶
IsCartridgeBased returns true if the console uses cartridge-based media.
func IsDiscBased ¶
IsDiscBased returns true if the console uses disc-based media.
func SupportedConsoles ¶
func SupportedConsoles() []string
SupportedConsoles returns a list of all supported console names.
Types ¶
type Console ¶
type Console = identifier.Console
Console is an alias for identifier.Console for convenience.
func ParseConsole ¶
ParseConsole parses a console name string into a Console type. It is case-insensitive and accepts various common names.
type GameDatabase ¶
type GameDatabase struct {
// Console-specific databases
// Key format varies by console (see identifier package)
GB map[gbKey]map[string]string
GBA map[string]map[string]string
GC map[string]map[string]string
Genesis map[string]map[string]string
N64 map[string]map[string]string
NES map[int]map[string]string
PSP map[string]map[string]string
PSX map[string]map[string]string
PS2 map[string]map[string]string
Saturn map[string]map[string]string
SegaCD map[string]map[string]string
SNES map[snesKey]map[string]string
NeoGeoCD map[neogeoCDKey]map[string]string
// ID prefixes for disc-based consoles
IDPrefixes map[identifier.Console][]string
}
GameDatabase holds the game metadata database.
func LoadDatabase ¶
func LoadDatabase(path string) (*GameDatabase, error)
LoadDatabase loads a database from a gob.gz file.
func LoadDatabaseFromReader ¶
func LoadDatabaseFromReader(r io.Reader) (*GameDatabase, error)
LoadDatabaseFromReader loads a database from a gzip-compressed gob reader.
func (*GameDatabase) GetIDPrefixes ¶
func (db *GameDatabase) GetIDPrefixes(console identifier.Console) []string
GetIDPrefixes returns the ID prefixes for disc-based consoles.
func (*GameDatabase) Lookup ¶
func (db *GameDatabase) Lookup(console identifier.Console, key any) (map[string]string, bool)
Lookup retrieves metadata for a game by console and key.
func (*GameDatabase) LookupByString ¶
func (db *GameDatabase) LookupByString(console identifier.Console, key string) (map[string]string, bool)
LookupByString retrieves metadata using a string key.
func (*GameDatabase) SaveDatabase ¶
func (db *GameDatabase) SaveDatabase(path string) error
SaveDatabase saves the database to a gob.gz file.
type Result ¶
type Result = identifier.Result
Result is an alias for identifier.Result for convenience.
func Identify ¶
func Identify(path string, db *GameDatabase) (*Result, error)
Identify detects the console type and identifies the game at the given path. It returns the identification result or an error if identification fails. If db is nil, no database lookup is performed.
Archive paths are supported in two forms:
- Explicit: /path/to/archive.zip/internal/path/game.gba
- Auto-detect: /path/to/archive.zip (finds first game file by extension)
Supported archive formats: ZIP, 7z, RAR. Only cartridge-based games (GB, GBC, GBA, NES, SNES, N64, Genesis) are supported in archives.
func IdentifyFromArchive ¶
func IdentifyFromArchive( arc archive.Archive, internalPath string, console Console, db *GameDatabase, ) (*Result, error)
IdentifyFromArchive identifies a game from an already-opened archive. This is useful when you need to control archive lifecycle or identify multiple files.
func IdentifyFromReader ¶
func IdentifyFromReader(
reader interface {
ReadAt([]byte, int64) (int, error)
},
size int64,
console Console,
database *GameDatabase,
) (*Result, error)
IdentifyFromReader identifies a game from an io.ReaderAt. This is useful when the file is already open or when reading from non-file sources. size is the total size of the data.
func IdentifyWithConsole ¶
func IdentifyWithConsole(path string, console Console, db *GameDatabase) (*Result, error)
IdentifyWithConsole identifies the game at the given path using the specified console type. This is useful when the console is already known or when auto-detection fails.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package archive provides support for reading game files from archives.
|
Package archive provides support for reading game files from archives. |
|
Package chd provides parsing for CHD (Compressed Hunks of Data) disc images.
|
Package chd provides parsing for CHD (Compressed Hunks of Data) disc images. |
|
cmd
|
|
|
dbgen
command
Command dbgen downloads GameDB TSV files and generates the Go game database.
|
Command dbgen downloads GameDB TSV files and generates the Go game database. |
|
gameid
command
Command gameid identifies video game files and returns metadata.
|
Command gameid identifies video game files and returns metadata. |
|
Package identifier provides console-specific game identification logic.
|
Package identifier provides console-specific game identification logic. |
|
internal
|
|
|
binary
Package binary provides utilities for reading binary data from ROM and disc images.
|
Package binary provides utilities for reading binary data from ROM and disc images. |
|
Package iso9660 provides parsing for ISO9660 disc images.
|
Package iso9660 provides parsing for ISO9660 disc images. |