Game categories and tags

Explore and recommendations use gameinfo.categories on each game: hierarchical tag ids such as goal>align, mechanics>capture, board>connect>hex, and components>pyramids. Set them on the static gameinfo object in each src/games/<uid>.ts file. See gameinfo metadata and Explore on the front client.

Player-facing labels (i18n)

Tag labels in the UI (short tags, full breadcrumb names, tooltips) live in gameslib, not in front apfront.json:

Key Purpose
categories.<tagId>.tag Compact label in tables and chips
categories.<tagId>.full Full hierarchical name (filters, pickers)
categories.<tagId>.description Tooltip / title text

English source: locales/en/apgames.json → object categories, keyed by the same tag id strings used in gameinfo.categories (including > segments, e.g. board>connect>hex).

When you add a new tag id, add all three strings under categories.<id> in English in the same PR. Managed locales (de, fr, it, es-US) get machine translation via locale-src/ sidecars on develop CI; other community folders under locales/ (for example pt, ms, zh-Hans) may contain only the categories subtree until more of apgames.json is translated.

Front loads these keys from the apgames i18next namespace (useTranslation("apgames"), keys like categories.${tagId}.tag). See Internationalization for the broader locale pipeline.

Do not run automated i18n pruning on dynamic categories.* paths — keys are resolved at runtime from catalog tag ids.

The games listed under each tag are generated at docs build time from the registry (npm run gen-docs-catalog). Edit this file (categories.prose.md) for narrative sections; do not hand-edit docs/categories.md.

Goals (goal>…)

Win-condition families (what determines who wins). One game may map to multiple goals in authoring; production tags use the goal> prefix.

Concept Meaning
Align Create a particular configuration (often N-in-a-row or a shape)
Annihilate Destroy all opposing pieces
Area control Control more area than the opponent
Breakthrough Reach the opposing home row or space
Connect Connect edges or regions
Cripple Destroy a critical subset of pieces
Evacuate Remove your pieces from the board
Immobilize Leave the opponent unable to move
Majority Hold more pieces than the opponent
Royal capture Capture a specific piece
Royal escape Move a specific piece to safety or off the board
Score (race) Be first to a score threshold
Score (at EOG) Highest score when the game ends
Set collection Collect sets of pieces or symbols
Unify Join all your pieces into one group

Mechanics (mechanics>…)

How play proceeds — movement, capture, randomness, and similar. Tags describe mechanisms, not goals.

Examples used in the catalog:

Mechanic Meaning
Asymmetry Goals or rules differ by side (metadata, not a single move type)
Bear off Remove your own pieces from the board
Block Block cells or paths
Capture Remove opposing (sometimes own) pieces
Convert Change piece ownership during play
Co-opt Place or move opposing pieces
Differentiate Piece types with distinct rules
Displace Moves cause consequential movement of other pieces
Enclose Enclose areas or groups
Hidden information Opponents' pieces or resources are concealed
Manage economy Shared bank of resources outside the board
Move Move existing pieces (general, group, or sowing)
Merge/Split Combine or split stacks beyond basic stacking
Network building Build a network on the board
Place Place new pieces
Programmed actions Pre-programmed moves (e.g. Robo Battle Pigs)
Randomize Random setup or random outcomes during play
Set collection Collect configurations as a mechanic
Share Shared pieces between players
Simultaneous Simultaneous action in at least one phase
Stack Stack manipulation is central

Board (board>…)

Playing surface — connectivity, shape, dynamic growth, mancala boards, or no fixed board.

Concept Meaning
None No fixed board (e.g. free placement)
Dynamic Board grows or changes during play
3D Three-dimensional layout
Mancala Traditional mancala-style pits
Cell / connectivity Square, hex, rect, snubsquare, linear, pent, or other cell connection
Shape Overall board shape (rect, hex, tri, circle, …)

Most rect-grid games share board>connect>rect; hex games use board>connect>hex, and so on.

Components (components>…)

Physical or logical piece sets the game expects.

Component Meaning
Decktet Decktet deck
Dice Dice-driven
Looney pyramids Icehouse / Looney pyramids
Piecepack Piecepack set
Polyominoes Polyomino pieces
Shibumi Shibumi set
Simple Uniform coloured pieces (most abstract games)
Simple: paper & pencil Paper-and-pencil style
Other specialized Custom or multi-type components

Families (family>…)

Historical or rules lineage — orthogonal to goal>, mechanic>, and board>. A game keeps its existing tags; family tags group titles for Explore and recommendations when users care about “what game is this like?” rather than “how does it play?”

Family Meaning
Draughts Draughts / checkers lineage (leap capture, promotion, related variants). Not every game that mentions “checkers” in copy.
Mancala Traditional pit-and-sow games and close modern descendants. Not the same as mechanic>move>sow or board>mancala alone — e.g. stack-sowing on a rect grid without mancala lineage stays untagged.
Gomoku Gomoku / Renju / Connect6 lineage and close in-a-row placement relatives (including shared InARowBase implementations where lineage applies). Not every goal>arrange game.
Tafl Viking tafl / Hnefatafl family: king vs attackers, escape vs capture. Not every asymmetric royal-escape game.

Each catalog game should have at most one family> tag.

Generated tag index

Tags below are taken from gameinfo.categories on each game class. Explore labels come from apgames categories.* i18n.

goal tags

mechanic tags

board tags

components tags

family tags

other tags

Generated games by tag

board>3d (Board: 3D)

board>connect>hex (Connect: Hex)

board>connect>linear (Connect: Linear)

board>connect>other (Connect: Other)

board>connect>pent (Connect: Pent)

board>connect>rect (Connect: Rect)

board>connect>snub (Connect: Snub)

board>dynamic (Board: Dynamic)

board>mancala (Board: Mancala)

board>none (Board: None)

board>other (Board: Other)

board>shape>circle (Shape: Circle)

board>shape>hex (Shape: Hex)

board>shape>oct (Shape: Oct)

board>shape>other (Shape: Other)

board>shape>pent (Shape: Pent)

board>shape>rect (Shape: Rect)

board>shape>tri (Shape: Tri)

components>chess (C: Chess)

components>decktet (C: Decktet)

components>dice (C: Dice)

components>dominoes (C: Dominoes)

components>piecepack (C: Piecepack)

components>poly (C: Polyominoes)

components>pyramids (C: Looney Pyramids)

components>shibumi (C: Shibumi)

components>simple (C: Simple)

components>simple>1c (C: Simple, 1 colour)

components>simple>1per (C: Simple, 1 per)

components>simple>2c (C: Simple, 2 colours)

components>simple>2per (C: Simple, 2 per)

components>simple>3c (C: Simple, 3 colours)

components>simple>4c (C: Simple, 4 colours)

components>simple>5c (C: Simple, 5 colours)

components>simple>7c (C: Simple, 7 colours)

components>simple>pnp (C: Simple, P&P)

components>special (C: Special)

family>draughts (F: Draughts)

family>gomoku (F: Gomoku)

family>mancala (F: Mancala)

family>tafl (F: Tafl)

goal>annihilate (G: Annihilate)

goal>area (G: Area Control)

goal>arrange (G: Arrange)

goal>breakthrough (G: Breakthrough)

goal>connect (G: Connect)

goal>cripple (G: Cripple)

goal>evacuate (G: Evacuate)

goal>immobilize (G: Immobilize)

goal>isolate (G: Isolate)

goal>majority (G: Majority)

goal>royal-capture (G: Royal Capture)

goal>royal-escape (G: Royal Escape)

goal>score>eog (G: Score (EOG))

goal>score>race (G: Score (Race))

goal>set (G: Set Collection)

goal>unify (G: Unify)

goal>vigil (G: Vigil)

mechanic>asymmetry (M: Asymmetry)

mechanic>bearoff (M: Bear off)

mechanic>block (M: Block)

mechanic>capture (M: Capture)

mechanic>convert (M: Convert)

mechanic>coopt (M: Co-Opt)

mechanic>differentiate (M: Differentiate)

mechanic>displace (M: Displace)

mechanic>economy (M: Manage Economy)

mechanic>enclose (M: Enclose)

mechanic>hidden (M: Hidden)

mechanic>merge (M: Merge/Split)

mechanic>move (M: Move)

mechanic>move>group (M: Move (Group))

mechanic>move>sow (M: Move (Sow))

mechanic>network (M: Network)

mechanic>place (M: Place)

mechanic>program (M: Program)

mechanic>random>play (M: Random (Play))

mechanic>random>setup (M: Random (Setup))

mechanic>set (M: Set Collection)

mechanic>share (M: Share)

mechanic>simultaneous (M: Simultaneous)

mechanic>stack (M: Stack)

other>2+players (O: 2+Players)

other>traditional (O: Traditional)