Skip to content

overview.md

Latest commit

 

History

History
138 lines (104 loc) · 5.47 KB

overview.md

File metadata and controls

138 lines (104 loc) · 5.47 KB
Raw

Overview

CynMeith is a Python-first board-game engine for experimenting with custom rules. It helps you test original turn-based board-game ideas without rewriting board state, turn flow, and move history every time.

Its purpose is not to be the fastest way to implement standard chess. It is to let you prototype original rule systems on a clean, programmable engine.

Primary Goal

The main goal is to help creative users test original board-game ideas quickly:

  • custom movement rules
  • custom turn structures
  • irregular side effects after moves
  • square and hexagonal boards, unusual sizes and setups
  • fast iteration in code, not engine-level performance work

The Shape of the Engine

Everything follows from one decision: the engine is stateless.

  • GameState is an immutable value holding everything mutable about a game: the board, the turn state, the phase, the resources, the ply count.
  • Engine is a pure function of that value: legal_moves(state), apply(state, move) -> new state, outcome(state). Applying a move never touches the input state.
  • GameSession is a small convenience wrapper for interactive play; its only "mutability" is a list of past states, which is why undo/redo needs no code.

Around that core sit three supporting ideas:

  • Geometry as a strategy. SquareGrid and HexGrid implement one Geometry contract (cells, neighbors, distance, lines, areas). Piece movement asks the geometry instead of doing coordinate math, so pieces can be board-shape agnostic.
  • Pieces as data. A piece on the board is a PieceState (kind + side + attrs). Its behavior is a PieceDef looked up by kind — usually built from movement combinators like leaper(...) and rider(...) rather than written by hand.
  • Stateless rule components. Turn, phase, resource, win, and scoring rules hold no game data; the values they produce live inside GameState, so one rule object serves any number of concurrent games.

Core Workflow

  1. Describe the game in one GameDef (geometry, pieces, starting position, rules).
  2. Call GameDef.new_session() to get an interactive GameSession (pass a custom setup for puzzles).
  3. Ask session.legal_moves(...) / session.can_move(...), then session.move(start, end).
  4. Let move payloads and Effect values handle irregular behavior.
  5. Use session.undo() / session.redo() freely.

For AI search, skip the session: take GameDef.engine() and work with GameState values directly — engine.apply(state, move) returns a new state you can fork, hash, and discard at will.

Who This Is For

CynMeith is a good fit if you:

  • can write small Python functions
  • want to prototype custom board-game rules, not just replay standard chess
  • prefer explicit code over a purely visual editor
  • want undo/redo, serialization, and reusable engine primitives while experimenting
  • want to try hexagonal variants without re-deriving hex math

It is a weaker fit if you:

  • want a no-code game editor
  • want a polished end-user app more than a Python package
  • want a tournament-grade chess engine or heavily optimized search backend

What CynMeith Is

At its core, CynMeith gives you:

  • a single GameDef that describes geometry, pieces, and rules, with new_session() to play and engine() for pure-function access
  • square and hex geometries with O(1) spatial math (SquareGrid, HexGrid)
  • declarative pieces (PieceDef + leaper/rider/stepper/compose/filtered)
  • a pure side-effect system for irregular moves (Remove, Relocate, Promote, Place)
  • turn control (FreeTurn, QuotaTurn) and first-class hooks for win conditions, phases, resources, and scoring
  • a royal-safety family for chess-like games (check, checkmate, stalemate)
  • free undo/redo and JSON/FEN serialization, both consequences of immutability
  • Tk sample applications for chess, xiangqi, and Exist

What CynMeith Is Not

Right now, CynMeith is not:

  • a complete board-game authoring application
  • a DSL-driven game-definition system
  • a built-in AI/search engine (it is deliberately search-friendly, but ships no searcher)
  • a rules database for many historical games

Design Stance

CynMeith deliberately keeps the engine programmable. It should stay good at:

  • deterministic, immutable game state
  • composable rule logic
  • debuggable Python extension points

Design-first authoring tools such as a web, desktop, or mobile app should sit on top of this engine rather than distort it into a visual tool before the rules model is ready.

Current Limits

  • game authoring is still code-driven
  • sides are player indexes (0, 1, ...); the engine supports N players structurally, but most built-in win conditions default their winners with two-player logic
  • graph-shaped boards (arbitrary adjacency) have a designed seam but no implementation yet
  • no built-in AI search — you bring your own Minimax/MCTS on top of the pure engine

Recommended Way To Use CynMeith

  1. Start with a tiny ruleset.
  2. Build pieces from combinators; write a custom generator only when a combinator cannot express the movement.
  3. Add game-wide restrictions as legality filters, irregular consequences as effects.
  4. Use QuotaTurn() unless your game truly needs something stranger.
  5. Only build UI after the core rules feel stable.

Next

For the minimum Python subset needed to extend the engine, read Python Enough for CynMeith. To go from a blank slate to a playable prototype, use Your First Custom Game.