cli-arcade 2026.0.0__py3-none-any.whl

game_classes/game_base.py

@@ -0,0 +1,121 @@
+import curses
+import time
+from game_classes.tools import get_terminal_size
+
+class GameBase:
+  def __init__(self, stdscr, player_name, tick, color=curses.COLOR_GREEN):
+    self.stdscr = stdscr
+    self.player_name = player_name
+    self.tick = tick
+    self.color = color
+    self.high_scores = self.highscores.load()
+    self.width, self.height = get_terminal_size(stdscr)
+    self.over = False
+    self.paused = False
+
+  def init_scores(self, list=[['score', 0]]):
+    self.new_highs = {}
+    self.scores = {}
+    for metric, initial in list:
+      self.new_highs[metric] = False
+      self.scores[metric] = initial
+		
+  def update_player_name(self, name):
+    self.player_name = name
+        
+  def handle_new_highs(self, metric):
+    self.new_highs[metric] = True
+        
+  def check_and_set_scores(self, metric='score'):
+    updated = False
+    try:
+      if self.scores[metric] > self.high_scores[metric].get('value', 0):
+        self.high_scores[metric]['value'] = int(self.scores[metric])
+        self.high_scores[metric]['player'] = getattr(self, 'player_name', 'Player')
+        updated = True
+        self.handle_new_highs(metric)
+    except Exception as e:
+      updated = False
+    return updated
+
+  def update_high_scores(self):
+    """Update the `high_scores` dict if current player exceeds any metric and save."""
+    updated = False
+    try:
+      for metric in self.scores:
+        updated |= self.check_and_set_scores(metric)
+    except Exception:
+      updated = False
+    if updated:
+      try:
+        self.highscores.save(self.high_scores)
+      except Exception:
+        pass
+    return updated
+  
+  def step(self, now):
+    pass
+
+  def movement(self, ch):
+    pass
+
+  def events(self, ch):
+    if ch != -1:
+      if ch == 27:
+        return True
+      if not getattr(self, 'over', False):
+        # toggle pause on Backspace
+        if ch in (curses.KEY_BACKSPACE, 127, 8):
+          self.paused = not getattr(self, 'paused', False)
+        # movement only when not paused
+        elif not getattr(self, 'paused', False):
+          self.movement(ch)
+    return False
+  
+  def draw_game_status(self, msg):
+    try:
+      py = max(0, min(self.height, self.height // 2))
+      px = max(0, (self.width - len(msg)) // 2)
+      self.stdscr.addstr(py, px, msg, curses.color_pair(curses.COLOR_RED) | curses.A_BOLD)
+    except Exception:
+      pass
+
+  def pre_draw(self):
+    self.stdscr.clear()
+    try:
+      for i, line in enumerate(self.title):
+        try:
+          self.stdscr.addstr(i, 0, line, curses.color_pair(self.color) | curses.A_BOLD)
+        except Exception:
+          pass
+    except Exception:
+      pass
+
+  def draw(self):
+    pass
+
+  def post_draw(self):
+    # overlay: game-over takes precedence over paused
+    if getattr(self, 'over', False):
+      self.draw_game_status('GAME OVER')
+    elif getattr(self, 'paused', False):
+      self.draw_game_status('PAUSED')
+    self.stdscr.refresh()
+
+  def run(self):
+    last = time.time()
+    while True:
+      now = time.time()
+      if self.events(self.stdscr.getch()):
+        break
+      if now - last > self.tick and not getattr(self, 'over', False) and not getattr(self, 'paused', False):
+        self.step(now)
+        last = now
+      self.pre_draw()
+      self.draw()
+      self.post_draw()
+      try:
+        self.update_high_scores()
+      except Exception:
+        pass
+      time.sleep(0.01)

game_classes/highscores.py

@@ -0,0 +1,108 @@
+import json
+import os
+import shutil
+import warnings
+
+try:
+    import appdirs
+except Exception:
+    appdirs = None
+
+
+class HighScores:
+    """Per-game highscores stored in a user-writable location.
+
+    Constructor is backward-compatible: `HighScores(game, default)` works.
+    If legacy highscores exist under the project `games/<game>/highscores.json`,
+    they will be migrated to the user data directory on first use.
+    """
+
+    def __init__(self, game, default=None, appname='cli-games', appauthor=None):
+        if default is None:
+            default = {'score': {'player': 'Player', 'value': 0}}
+        # copy default to avoid shared mutable state
+        try:
+            self.default = {k: v.copy() for k, v in default.items()}
+        except Exception:
+            self.default = dict(default)
+
+        self.game = game
+        self.appname = appname
+        self.appauthor = appauthor
+
+        # determine user-writable base
+        base = None
+        if appdirs is not None:
+            try:
+                base = appdirs.user_data_dir(self.appname, self.appauthor)
+            except Exception:
+                base = None
+
+        if not base:
+            home = os.path.expanduser('~') or os.getcwd()
+            base = os.path.join(home, f'.{self.appname}')
+
+        self.dir = os.path.abspath(os.path.join(base, 'games', game))
+        self.path = os.path.join(self.dir, 'highscores.json')
+
+        # attempt migration from project-root location if present
+        try:
+            proj_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
+            legacy = os.path.join(proj_root, 'games', game, 'highscores.json')
+            if os.path.exists(legacy) and not os.path.exists(self.path):
+                try:
+                    os.makedirs(os.path.dirname(self.path), exist_ok=True)
+                    shutil.copy2(legacy, self.path)
+                except Exception as e:
+                    warnings.warn(f"Failed to migrate legacy highscores for {game}: {e}")
+        except Exception:
+            pass
+
+    def _path(self):
+        return self.path
+
+    def load(self):
+        path = self._path()
+        try:
+            if os.path.exists(path):
+                with open(path, 'r', encoding='utf-8') as f:
+                    data = json.load(f)
+                    if isinstance(data, dict):
+                        for k, v in self.default.items():
+                            if k not in data or not isinstance(data[k], dict):
+                                data[k] = v.copy()
+                            else:
+                                data[k]['player'] = data[k].get('player', v.get('player'))
+                                data[k]['value'] = data[k].get('value', v.get('value'))
+                        return data
+        except Exception as e:
+            warnings.warn(f"HighScores.load() failed for {path}: {e}")
+
+        try:
+            return {k: v.copy() for k, v in self.default.items()}
+        except Exception:
+            return dict(self.default)
+
+    def save(self, data):
+        path = self._path()
+        try:
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+        except Exception as e:
+            warnings.warn(f"HighScores.save() failed to create dir: {e}")
+            return False
+
+        try:
+            tmp = path + '.tmp'
+            with open(tmp, 'w', encoding='utf-8') as f:
+                json.dump(data, f, ensure_ascii=False, indent=2)
+            os.replace(tmp, path)
+            return True
+        except Exception as e:
+            warnings.warn(f"HighScores.save() write failed for {path}: {e}")
+            try:
+                with open(path, 'w', encoding='utf-8') as f:
+                    json.dump(data, f, ensure_ascii=False, indent=2)
+                return True
+            except Exception as e2:
+                warnings.warn(f"HighScores.save() fallback write failed for {path}: {e2}")
+                return False

game_classes/menu.py

@@ -0,0 +1,68 @@
+import curses
+from game_classes.tools import is_enter_key
+
+class Menu:
+    def __init__(self, game):
+        self.game = game
+
+    def prompt_name(self, prompt_y, prompt_x, max_len=12):
+        name = ''
+        while True:
+            try:
+                self.game.stdscr.addstr(prompt_y, prompt_x, ' ' * (max_len + 20))
+                self.game.stdscr.addstr(prompt_y, prompt_x, f'Enter name (max {max_len}): {name}')
+                self.game.stdscr.refresh()
+            except Exception:
+                pass
+            ch = self.game.stdscr.getch()
+            if is_enter_key(ch):  # Enter
+                return name.strip() or 'Player'
+            elif ch in (27,):
+                return False
+            elif ch in (curses.KEY_BACKSPACE, 127, 8):
+                name = name[:-1]
+            elif 32 <= ch <= 126 and len(name) < max_len:
+                name += chr(ch)
+            else:
+                # ignore other keys
+                pass
+
+    def display(self):
+        self.game.stdscr.clear()
+        h, w = self.game.stdscr.getmaxyx()
+        # draw title art left-aligned where it appears in-game (above the board)
+        title_height = len(self.game.title)
+        for i, line in enumerate(self.game.title):
+            try:
+                self.game.stdscr.addstr(i, 0, line, curses.color_pair(self.game.color) | curses.A_BOLD)
+            except Exception:
+                pass
+
+        # instructions centered under the title block
+        instr_y = title_height + 1
+        try:
+            title_width = max((len(l) for l in self.game.title), default=0)
+            instrs = ['Press ENTER to Start Game', 'Press ESC to Quit']
+            for idx, instr in enumerate(instrs):
+                x = max(0, (title_width - len(instr)) // 2)
+                self.game.stdscr.addstr(instr_y + idx, x, instr)
+        except Exception:
+            pass
+        self.game.stdscr.refresh()
+        while True:
+            ch = self.game.stdscr.getch()
+            # if ch in (ord('s'), ord('S')) or ch == curses.KEY_DOWN:
+            if is_enter_key(ch):
+                # prompt for name before starting, centered over the title block
+                prompt_y = title_height + 3
+                title_width = max((len(l) for l in self.game.title), default=0)
+                max_len = 50
+                prompt_prefix = f'Enter name (max {max_len}): '
+                prompt_len = len(prompt_prefix) + max_len
+                prompt_x = max(0, (title_width - prompt_len) // 2)
+                name = self.prompt_name(prompt_y, prompt_x, max_len=max_len)
+                if name is False:
+                    return False
+                return name
+            elif ch == 27:
+                return False

game_classes/tools.py

@@ -0,0 +1,155 @@
+import curses
+import os
+import shutil
+
+def verify_terminal_size(game_name, min_cols=70, min_rows=20):
+    try:
+        size = shutil.get_terminal_size()
+        cols, rows = size.columns, size.lines
+    except Exception:
+        try:
+            cols, rows = os.get_terminal_size().columns, os.get_terminal_size().lines
+        except Exception:
+            cols, rows = 0, 0
+    if cols < min_cols or rows < min_rows:
+        print(f"  [ACTION] Terminal size is too small to run {game_name}.")
+        if cols < min_cols:
+          print(f"  [ACTION] Actual Colums: {cols} Required Colums: {min_cols}")
+        if rows < min_rows:
+          print(f"  [ACTION] Actual Rows: {rows} Required Rows: {min_rows}")
+        raise SystemExit(1)
+
+def get_terminal_size(stdscr):
+    try:
+      rows, cols = stdscr.getmaxyx()
+    except Exception:
+      try:
+        cols, rows = shutil.get_terminal_size()
+      except Exception:
+        cols, rows = 24, 80
+    return max(20, cols - 2), max(6, rows - 1)
+
+def init_curses(stdscr):
+  curses.curs_set(0)
+  stdscr.nodelay(True)
+  stdscr.timeout(50)
+  # enable keypad mode so special keys (e.g. numpad Enter) map to curses.KEY_ENTER
+  try:
+      stdscr.keypad(True)
+  except Exception:
+      pass
+  # init colors
+  curses.start_color()
+  curses.use_default_colors()
+  # try to normalize key colors (0..1000 scale). Must run before init_pair.
+  if curses.can_change_color() and curses.COLORS >= 8:
+      try:
+          curses.init_color(curses.COLOR_MAGENTA, 1000, 0, 1000)
+          curses.init_color(curses.COLOR_YELLOW, 1000, 1000, 0)
+          curses.init_color(curses.COLOR_WHITE, 1000, 1000, 1000)
+          curses.init_color(curses.COLOR_CYAN, 0, 1000, 1000)
+          curses.init_color(curses.COLOR_BLUE, 0, 0, 1000)
+          curses.init_color(curses.COLOR_GREEN, 0, 800, 0)
+          curses.init_color(curses.COLOR_RED, 1000, 0, 0)
+          curses.init_color(curses.COLOR_BLACK, 0, 0, 0)
+      except Exception:
+          pass
+  for i in range(1,8):
+      curses.init_pair(i, i, -1)
+  # set an explicit default attribute so unstyled text uses white
+  try:
+      stdscr.bkgd(' ', curses.color_pair(curses.COLOR_WHITE))
+  except Exception:
+      try:
+          stdscr.bkgd(' ', curses.color_pair(7))
+      except Exception:
+          pass
+
+def clamp(v, a, b):
+	return max(a, min(b, v))
+
+def is_enter_key(ch):
+    try:
+        enter_vals = {10, 13, getattr(curses, 'KEY_ENTER', -1), 343, 459}
+    except Exception:
+        enter_vals = {10, 13}
+    return ch in enter_vals
+
+
+def _supports_unicode():
+    """Decide whether to use Unicode glyphs.
+
+    Rules:
+    - Honor `CLI_GAMES_FORCE_ASCII` (1/true/yes) -> False
+    - On classic Windows PowerShell/conhost (no modern terminal env vars) prefer ASCII
+    - If encodings are explicitly ASCII -> False
+    - Otherwise prefer Unicode (True)
+    """
+    try:
+        if os.environ.get('CLI_GAMES_FORCE_ASCII', '').lower() in ('1', 'true', 'yes'):
+            return False
+
+        # On Windows, many older/conhost-based shells lack glyph fonts.
+        # If we're on Windows and don't detect a modern terminal emulator,
+        # prefer ASCII to avoid boxed question-mark glyphs.
+        if os.name == 'nt':
+            env = os.environ
+            modern_term_markers = (
+                'WT_SESSION',  # Windows Terminal
+                'WT_PROFILE_ID',
+                'TERM_PROGRAM',
+                'ANSICON',
+                'ConEmuPID',
+                'TERM',
+            )
+            modern = any(k in env for k in modern_term_markers)
+            term = env.get('TERM', '').lower()
+            if 'xterm' in term or 'vt' in term:
+                modern = True
+            if not modern:
+                return False
+
+        import sys
+        import locale
+        encs = [getattr(sys.stdout, 'encoding', None), locale.getpreferredencoding(False)]
+        for enc in encs:
+            if not enc:
+                continue
+            low = enc.lower()
+            if 'ascii' in low or low in ('us-ascii', '646'):
+                return False
+
+        return True
+    except Exception:
+        return True
+
+
+_UNICODE = _supports_unicode()
+
+GLYPHS_UNICODE = {
+    'VBAR': '│',
+    'BLOCK': '█',
+    'CIRCLE_FILLED': '◉',
+    'CIRCLE': '◌',
+    'THUMB': '█',
+}
+GLYPHS_ASCII = {
+    'VBAR': '|',
+    'BLOCK': '#',
+    'CIRCLE_FILLED': 'O',
+    'CIRCLE': 'O',
+    'THUMB': '#',
+}
+
+
+def glyph(name, fallback='*'):
+    """Return a glyph string for `name`, using unicode when available.
+
+    Known names: 'VBAR', 'BLOCK', 'CIRCLE_FILLED', 'CIRCLE', 'THUMB'
+    """
+    try:
+        if _UNICODE:
+            return GLYPHS_UNICODE.get(name, GLYPHS_UNICODE.get('CIRCLE_FILLED', fallback))
+        return GLYPHS_ASCII.get(name, GLYPHS_ASCII.get('CIRCLE_FILLED', fallback))
+    except Exception:
+        return fallback

games/__init__.py

@@ -0,0 +1 @@
+"""games package"""

games/byte_bouncer/__init__.py

@@ -0,0 +1 @@
+"""byte_bouncer game package"""

games/byte_bouncer/game.py

@@ -0,0 +1,208 @@
+import curses
+import os
+import random
+import sys
+
+try:
+  this_dir = os.path.dirname(__file__)
+  project_root = os.path.abspath(os.path.join(this_dir, '..', '..'))
+  if project_root not in sys.path:
+    sys.path.insert(0, project_root)
+except Exception:
+  project_root = None
+
+from game_classes.highscores import HighScores
+from game_classes.game_base import GameBase
+from game_classes.menu import Menu
+from game_classes.tools import glyph, verify_terminal_size, init_curses, clamp
+
+TITLE = [
+     '  ____  _  _  ____  ____    ____   __   _  _  __ _   ___  ____  ____  ',
+    r' (  _ \( \/ )(_  _)(  __)  (  _ \ /  \ / )( \(  ( \ / __)(  __)(  _ \ ',
+    r'  ) _ ( )  /   )(   ) _)    ) _ ((  O )) \/ (/    /( (__  ) _)  )   / ',
+    r' (____/(__/   (__) (____)  (____/ \__/ \____/\_)__) \___)(____)(__\_) '
+]
+
+class Game(GameBase):
+    def __init__(self, stdscr, player_name='Player'):
+      self.title = TITLE
+      self.highscores = HighScores('byte_bouncer', {
+          'score': {'player': 'Player', 'value': 0},
+          'level': {'player': 'Player', 'value': 1},
+      })
+      super().__init__(stdscr, player_name, 0.12, curses.COLOR_GREEN)
+      self.init_scores([['score', 0], ['level', 1]])
+
+      # game state
+      self.count = 0
+      # multiple balls support: list of dicts with x,y,vx,vy
+      self.balls = [
+        { 'x': self.width // 2, 'y': self.height // 2, 'vx': random.choice([-1,1]), 'vy': -1 }
+      ]
+      self.paddle_w = 30
+      self.paddle_x = self.width // 2 - self.paddle_w // 2
+
+    def draw_info(self):
+      info_x = 2
+      info_y = len(self.title)
+      try:
+        # draw high scores below title
+        new_score = ' ***NEW High Score!' if self.new_highs.get('score', False) else ''
+        new_level = ' ***NEW High Level!' if self.new_highs.get('level', False) else ''
+        self.stdscr.addstr(info_y + 1 , info_x, f'High Score: {int(self.high_scores["score"]["value"]):,} ({self.high_scores["score"]["player"]}){new_score}', curses.color_pair(curses.COLOR_GREEN))
+        self.stdscr.addstr(info_y + 2 , info_x, f'High Level: {int(self.high_scores["level"]["value"]):,} ({self.high_scores["level"]["player"]}){new_level}', curses.color_pair(curses.COLOR_BLUE))
+
+        # draw game info below title
+        self.stdscr.addstr(info_y + 4, info_x, f'Player: {self.player_name}')
+        self.stdscr.addstr(info_y + 5, info_x, f'Score: {int(self.scores["score"]):,}', curses.color_pair(curses.COLOR_GREEN))
+        self.stdscr.addstr(info_y + 6, info_x, f'Level: {int(self.scores["level"]):,}', curses.color_pair(curses.COLOR_BLUE))
+
+        self.stdscr.addstr(info_y + 8 , info_x, '← | a     : Left')
+        self.stdscr.addstr(info_y + 9 , info_x, '→ | d     : Right')
+        self.stdscr.addstr(info_y + 10, info_x, 'Backspace : Pause')
+        self.stdscr.addstr(info_y + 11, info_x, 'ESC       : Quit')
+      except Exception:
+        pass
+
+    def draw(self):
+      self.draw_info()
+      # draw balls
+      try:
+        for idx, b in enumerate(self.balls):
+          try:
+            if idx == 0:
+              attr = curses.color_pair(curses.COLOR_MAGENTA) | curses.A_BOLD
+            else:
+              attr = curses.color_pair(curses.COLOR_YELLOW) | curses.A_BOLD
+            self.stdscr.addch(int(b['y']), 1 + int(b['x']), glyph('CIRCLE_FILLED', 'O'), attr)
+          except Exception:
+            pass
+      except Exception:
+        pass
+      # draw paddle
+      for i in range(self.paddle_w):
+        x = clamp(self.paddle_x + i, 0, self.width - 1)
+        try:
+          self.stdscr.addch(self.height, x + 1, '=', curses.color_pair(curses.COLOR_GREEN) | curses.A_BOLD)
+        except Exception:
+          pass
+
+    def step(self, now):
+      # move each ball and handle collisions
+      for i, b in enumerate(self.balls[:]):
+        b['x'] += b['vx']
+        b['y'] += b['vy']
+        # collisions with walls
+        if b['x'] < 0:
+          b['x'] = 0
+          b['vx'] *= -1
+        elif b['x'] >= self.width:
+          b['x'] = self.width - 1
+          b['vx'] *= -1
+        if b['y'] < 0:
+          b['y'] = 0
+          b['vy'] *= -1
+        # bottom: check paddle
+        if b['y'] >= self.height:
+          if self.paddle_x <= b['x'] < self.paddle_x + self.paddle_w:
+            # bounce
+            b['y'] = self.height - 1
+            b['vy'] *= -1
+            # normalize horizontal velocity to magnitude 1
+            if b['vx'] < 0:
+              b['vx'] = -1
+            elif b['vx'] > 0:
+              b['vx'] = 1
+            else:
+              b['vx'] = random.choice([-1, 1])
+            self.scores['score'] += 10 * self.scores['level'] * len(self.balls)
+            self.count += 1
+            # increase level every 5 successful bounces
+            if self.count % 5 == 0:
+              self.scores['level'] += 1
+              # spawn new ball near center top area
+              nb = {
+                'x': random.randint(2, max(2, self.width-3)),
+                'y': random.randint(2, max(2, self.height - self.height//3)),
+                'vx': random.choice([-1,1]),
+                'vy': -1
+              }
+              self.balls.append(nb)
+          elif b['x'] == self.paddle_x - 1 and b['vx'] > 0:
+            # edge bounce left
+            b['y'] = self.height - 1
+            b['vy'] *= -1
+            b['vx'] *= -1
+            self.scores['score'] += 10 * self.scores['level'] * len(self.balls) * 2
+            self.count += 1
+            # increase level every 5 successful bounces
+            if self.count % 5 == 0:
+              self.scores['level'] += 1
+              # spawn new ball near center top area
+              nb = {
+                'x': random.randint(2, max(2, self.width-3)),
+                'y': random.randint(2, max(2, self.height - self.height//3)),
+                'vx': random.choice([-1,1]),
+                'vy': -1
+              }
+              self.balls.append(nb)
+          elif b['x'] == self.paddle_x + self.paddle_w and b['vx'] < 0:
+            # edge bounce right
+            b['y'] = self.height - 1
+            b['vy'] *= -1
+            b['vx'] *= -1
+            self.scores['score'] += 10 * self.scores['level'] * len(self.balls) * 2
+            self.count += 1
+            # increase level every 5 successful bounces
+            if self.count % 5 == 0:
+              self.scores['level'] += 1
+              # spawn new ball near center top aread
+              nb = {
+                'x': random.randint(2, max(2, self.width-3)),
+                'y': random.randint(2, max(2, self.height - self.height//3)),
+                'vx': random.choice([-1,1]),
+                'vy': -1
+              }
+              self.balls.append(nb)
+          else:
+            b['y'] = self.height + 1
+            # if primary ball misses -> game over
+            if i == 0:
+              self.over = True
+              return
+            # otherwise remove the extra ball (it contributes to score normally)
+            try:
+              # find and remove by identity (safer if list has changed)
+              self.balls.pop(i)
+            except Exception:
+              try:
+                self.balls.remove(b)
+              except Exception:
+                pass
+
+    def movement(self, ch):
+      if ch in (curses.KEY_LEFT, ord('a')):
+        self.paddle_x = int(clamp(self.paddle_x - 2, 0, self.width - self.paddle_w))
+      elif ch in (curses.KEY_RIGHT, ord('d')):
+        self.paddle_x = int(clamp(self.paddle_x + 2, 0, self.width - self.paddle_w))
+
+def main(stdscr):
+  verify_terminal_size('Byte Bouncer')
+  init_curses(stdscr)
+  while True:
+    game = Game(stdscr)
+    menu = Menu(game)
+    start = menu.display()
+    if not start:
+      break
+    game.update_player_name(start)
+    game.run()
+
+if __name__ == '__main__':
+    try:
+        curses.wrapper(main)
+    except KeyboardInterrupt:
+        try:
+            curses.endwin()
+        except Exception:
+            pass

games/star_ship/__init__.py

@@ -0,0 +1 @@
+"""star_ship game package"""