games

type Adapter interface {
	Game() Game

	PaletteResolver

	// CursorPalette returns the palette for the cursors GAF, or nil when the
	// game uses the global palette (the caller then falls back to it).
	CursorPalette() *gaf.Palette

	// UnitSounds resolves a unit's sound-event map for its FBI sound
	// category: TA-style event keys (select1, ok1, arrived1, …) to .wav
	// stems. Returns nil when the category resolves to nothing.
	UnitSounds(category string) map[string]string

	// Tilesets lists the map editor's terrain groups: TA's fixed world list,
	// TA:K's kingdoms from sidedata.
	Tilesets() []Tileset

	// MapTerrainGroup names the terrain group a map belongs to when the
	// game tracks it outside the map file itself — TA:K reads the kingdom=
	// affinity from the sibling .ota. "" when the game has no such notion
	// (TA's planet lives in the .ota planet= the caller already parses).
	MapTerrainGroup(mapPath string) string

	// BuildOptions lists the unit names (lower-case, ordered as the game's
	// menus order them) a builder unit can construct, resolved from the
	// game's canbuild data plus any download-menu add-ons. Empty for
	// non-builders.
	BuildOptions(unit string) []string
}

type Game interface {
	// ID is the kbot context identifier ("totala", "takingdoms").
	ID() string
	// Name is the human-readable title.
	Name() string
	// NewAdapter binds the game's rules to one mounted install. Adapters
	// cache parsed game data (sidedata, sound tables) for their lifetime,
	// so sessions should hold one adapter, not re-create them per request.
	NewAdapter(fs VFS) Adapter
}

type PaletteResolver interface {
	// TexturePalette returns the palette for a 3DO model texture GAF (by VFS path).
	TexturePalette(gafPath string) *gaf.Palette
	// ModelColorPalette returns the palette for a 3DO model's colour-keyed
	// primitives (by object/model name).
	ModelColorPalette(object string) color.Palette
	// FeaturePalette returns the palette for a feature / anim sprite GAF.
	FeaturePalette(gafName string) *gaf.Palette
	// TerrainPalette returns the palette for a map's terrain + baked minimap
	// (by map VFS path).
	TerrainPalette(mapPath string) color.Palette
	// TextureRenderOptions returns how 3DO model textures resolve
	// transparency, given the resolved palette. TA renders unit textures
	// fully opaque (palette[TI] is a real colour); TA:Kingdoms texture
	// atlases reserve a transparent key colour which must be punched out.
	TextureRenderOptions(pal *gaf.Palette) gaf.RenderOptions
	// TextureSidePrefix returns the side name-prefix (lowercase, e.g. "ara")
	// for a 3DO model name, or "" when sides don't apply.
	TextureSidePrefix(object string) string
	// TexturePaletteForSide returns the texture palette for an explicit side
	// prefix (the ?side= a client passes with a texture fetch), or nil when
	// the side is unknown / sides don't apply.
	TexturePaletteForSide(side string) *gaf.Palette
}

type Tileset struct {
	Slug           string `json:"slug"`
	Label          string `json:"label"`
	DefaultTileset string `json:"defaultTileset"`
}

type VFS interface {
	ReadFile(path string) ([]byte, error)
	Exists(path string) bool
	List() []string
}

type WeaponResolver func(ref string) (ta.Weapon, bool)