DasTetris/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt   # pygame
.venv/bin/python das_tetris_gui.py                                    # run the game
.venv/bin/python -m unittest discover -s tests -v                     # all tests (headless, SDL dummy driver)
.venv/bin/python -m unittest tests.test_game.TetrisGameTest.test_clear_lines_scoring   # single test
.venv/bin/pyinstaller das_tetris_gui.spec    # build executable into dist/ (local spec, git-ignored; equivalent: pyinstaller --onefile das_tetris_gui.py)

Smoke-run headless: SDL_VIDEODRIVER=dummy timeout -s KILL 5 .venv/bin/python das_tetris_gui.py. Use SIGKILL: SDL turns SIGTERM into pygame.QUIT, which opens the "exit?" dialog and waits forever.

Architecture

• das_tetris_gui.py – entry point. TetrisGame (field, falling piece, scoring, speed, input), TetrisRenderer (pygame drawing), show_question_dialogue (modal Yes/No loop that runs its own event loop), main() loop at 60 FPS.
• tetris_config.py – load_config() overwrites module-level globals (KEY_CONFIG, COLORS, BLOCK_TYPE, STORE_WIDTH, BLOCK_SIZE, HIGH_SCORE_INC_SPEED, …). The game module calls it at import time and copies most globals into its own names, but reads cfg.HIGH_SCORE_INC_SPEED live. The hard-coded BlockType enum in this file is only the source for store_config(); at runtime BLOCK_TYPE is rebuilt dynamically from JSON.
• Serializer.py – EnumSerializer: JSON ⇄ Python with __type__ tags (PygameKey stored by name, tuple/list/set, EnumClass, EnumInstance). Used for config.json; block files are read with plain json.

Config files (configs/)

• config.json, blocks.json, blocks_ADD.json – local/working configs. If one is missing, <name>_000.json (committed defaults) is used. Paths are resolved next to the script, or next to the executable when frozen.
• Blocks from blocks.json (ALL_BLOCKS.members) and blocks_ADD.json (ADDITIONAL_BLOCKS.members, optional) are merged; a later key overrides an earlier one. Each block: name, color [r,g,b], min_score (block appears only once score reaches it; at least one must be 0), shapes – list of rotations (clockwise), each a 0/1 matrix drawn from the top-left.
• Field cells store index in list(BLOCK_TYPE) + 1, so block order matters for rendering. Blocks with identical values become Enum aliases and disappear from list(BLOCK_TYPE).
• high_score_inc_speed (optional, default false): fall_speed is the drop interval in seconds, so true makes the game slower above 5000/10000/15000 points, false makes it faster.
• tetris_config.store_config() overwrites config.json/blocks.json from the hard-coded values – do not call it casually.

Misc

• other/ (git-ignored) holds early prototypes and translations of other Tetris implementations; not used by the game.
• PyInstaller spec bundles no data files: the built executable needs a configs/ folder beside it.