BMAD-METHOD/BETA-V3/docs/technical-preferences-py-game-dev-sample.md

# A Python Game Dev's Sacred Scrolls & Silly Scribbles

Alright, listen up, code-conjurers and pixel-pushers! This ain't your grandma's quilting bee instructions (unless grandma was a hardcore roguelike dev, in which case, kudos, G-Ma!). These are my hard-won, battle-tested, and occasionally batty preferences for wrangling Python into making glorious 2D games and text adventures that would make Zork feel under-described. If you're working with me, or if you're an AI trying to read my mind (good luck, it's a procedurally generated dungeon in there), this is the sacred text.

## Core Philosophy: Keep it Simple, Stupid (KISS)... But Not _Too_ Stupid

- **Game Loop:** The heart of the beast! I like a classic `while running:` loop. Predictable. Reliable. Like my need for coffee.
  - Input handling first, then update game state (`tick` or `update` method, if you please), then render. Don't cross the streams, Egon! It gets messy.
- **Modularity:** My kingdom for a good module! Break things down. If a file scrolls more than my character in a JRPG, it's too long. Think small, reusable pieces. It makes debugging less of a "Where's Waldo, but Waldo is a one-character typo."
- **Pythonic Principles:** We're writing Python, not C-in-disguise. List comprehensions? Yes, please. Generators? You bet your `yield`! Decorators? If they make sense and don't obscure things like a ninja in a dark room.

## Tech & Libraries: The Tools of the Trade (and some personal fetishes)

- **Primary Language:** Python (Duh. If you thought otherwise, you've `SyntaxError`-ed in life.)
  - **Version:** Latest stable 3.x. I'm not living in the `past-thon`.
- **Game Library: Pygame**
  - **My Stance:** Old reliable. It's not the flashiest, but it gets the job done, like a trusty +1 sword.
  - **Why:** It's simple enough to get going, flexible enough for weird stuff, and the community has seen it all. Plus, `blit` is just fun to say. Blit. Blit. Blit.
  - **Key Pygame Bits I Love:**
    - `pygame.Surface`: My canvas, my world! Treat it with respect.
    - `pygame.Rect`: For when you absolutely, positively have to know if two squares are bumping uglies. Indispensable for collision, clicking, etc.
    - `pygame.sprite.Sprite` and `pygame.sprite.Group`: Good for organizing game entities. Keeps things from becoming a `tuple` soup.
    - `pygame.event.get()`: The lifeblood of interactivity. Gotta catch 'em all (events, not Pokémon... unless that's the game).
- **Text Rendering (for MUDs / Dwarf Fortress-esque UIs):**
  - Pygame's `font.Font` and `render()` are fine for basic stuff. For more complex console-like UIs, I might even consider `curses` in a separate thread if I'm feeling particularly masochistic, or a dedicated text UI library if Pygame's offerings feel too... `flat`.
  - Monospaced fonts are king here. Readability over flashiness, always.

## Game Structure & Patterns: My Blueprint for Not Going Insane

- **State Machines:** For player states, game states (menu, playing, game over), enemy AI... if it has states, it needs a state machine. Keeps the `if/elif/else` pyramids from reaching for the sky.
- **Entity-Component-System (ECS):** For bigger projects, I'm ECS-curious. It can be overkill for small games, but when you have entities with a grab-bag of different properties and behaviors, it's a lifesaver. Keeps your inheritance hierarchies from looking like a family tree from a fantasy novel.
  - If not full ECS, then at least component-based design. Mixins are my friends.
- **Asset Management:**
  - Organize your sprites, sounds, and fonts into clear subdirectories (`assets/sprites`, `assets/sfx`, etc.). It's not rocket science, it's just good `cents`.
  - Loading: Load what you need, when you need it. A loading screen is better than a game that stutters like a nervous bard.
- **Configuration Files:** JSON or TOML for game settings, enemy stats, level data. Don't hardcode values unless you enjoy pain. And if you do, maybe see someone about that. My config files are often `key` to my success.

## Coding Style & Conventions (The "It's My Way or the Highway... to a Buggy Mess")

- **Naming:**
  - `snake_case` for variables and functions. It's Python, not a camel beauty pageant.
  - `PascalCase` for classes. Classy.
  - Constants in `UPPER_SNAKE_CASE`. Because some things should SHOUT their immutability.
- **Comments:** Explain the _why_, not the _what_. If your code is so clever it needs a novel to explain it, it's probably _too_ clever. Or, as I say, "Clear code is no `stranger` to documentation."
- **Error Handling:** `try-except` blocks are your friends. Don't let your game crash harder than a goblin raiding party after too much ale. Graceful failure is an art form.
- **Logging:** For debugging, `print()` is fine for quick checks, but for anything serious, the `logging` module. It helps you `see Sharp` when things go wrong.

## Testing: Yes, Even for Games (Especially for Games!)

- **Unit Tests:** For core logic, utility functions, anything that can be tested in isolation. Test your math, test your state changes. It's not `pytest`ful to skip this.
- **Playtesting:** The most important kind. If it's not fun, or if it breaks when your cat walks on the keyboard, it's not ready. My cat is my QA department's lead `purrgrammer`.

## Version Control: Git Gud or Git Lost

- **Git:** Use it. Love it. Commit often. Write meaningful commit messages (not just "stuff" or "lol fixed it").
- **Branching:** `main` or `master` for stable releases. `develop` for ongoing work. Feature branches for new, potentially game-breaking ideas.

## Parting Wisdom (aka. More Puns)

- Don't be afraid to refactor. Your first idea is rarely your `best_fit`.
- Remember, the most important algorithm in game development is the "make it fun" algorithm.
- And if you get stuck, take a break. Go for a walk. Sometimes the best solutions come when you're not `StaringContemplativelyAtScreen`.

Now go forth and `pygame.display.flip()` some pixels!