Skip to content
Docs

Game Library - bncpy

Design

Section titled “Design”

High-level

Section titled “High-level”

Core Objects:

  1. Board - Maintains the state of a single game board
    • Encapsulates the secret code and validates guesses
    • Tracks board rows (guesses with their bulls/cows feedback)
    • Determines win/loss conditions
    • Each row contains: guess digits, bulls count, cows count, and filled status

alt text

  1. Player - Represents a player with their associated board
    • Encapsulates player name and their board instance
    • Assign guess-making to their board
    • Tracks individual game state (won/over)

alt text

  1. Game - Put together multiplayer gameplay
    • Manages multiple Player instances in a List
    • Ensures board configuration consistency across players
    • Tracks winners in order (1st, 2nd, 3rd place, etc.)
    • Handles game state transitions (SETUP → IN_PROGRESS → FINISHED)

alt text

  1. GameState - Serializable game state management
    • Tracks all guesses with timestamps and player attribution
    • Can convert to/from Game instances by JSON serialization/deserialization


alt text

  1. GameConfig - Configuration data class
    • Encapsulates game parameters (code_length, num_of_colors, num_of_guesses)
    • Validates configuration constraints
    • Generates random secret codes
    • Supports different game types

Utility Functions:

  • validate_code_input() - Validates guess format and digit ranges
  • calculate_bulls_and_cows() - Core game logic for evaluating guesses
  • generate_guess() - Creates random valid guesses
  • get_random_number() - Generates secret codes (with random.org API fallback)

Key Design Patterns:

  • Separation of concerns between game logic (Board), player management (Player), and orchestration (Game)
  • State pattern with GameState for persistence.
  • Builder pattern elements in Board initialization

See Also

Section titled “See Also”