# /games — Playable Web Games

A curated collection of small, fun, instantly playable browser games built following the **Game Designer** principles:

- Gameplay first
- Smallest fun MVP → iterate
- Self-contained (no build step required for most)
- Responsive (keyboard + touch + mouse)
- Client-authoritative where safe, server only when needed
- Beautiful but simple visuals
- Documented sources for assets, inspiration, and learning

## Philosophy

Every game here is meant to be:

1. **Immediately understandable** — open and play in <5 seconds
2. **Competitive & replayable** — chase high scores, beat friends
3. **Creative** — not another literal clone
4. **Easy to study** — clean code + explanations

## How to Add a New Game

1. Create `games/your-game-slug/`
2. Put a single `index.html` (or `game.html`) that is fully playable standalone
3. Add a nice card entry to the root `index.html`
4. Write `README.md` with:
   - Core loop description
   - Controls
   - Design decisions & why
   - Asset sources (with links + licenses)
   - Ideas for future expansions

## Current Games

See `index.html` for the visual gallery.

## Testing the Games

We have two layers of tests:

### 1. Fast Smoke Tests (no browser required)
```bash
cd games
python -m pytest tests/test_smoke.py -q
```

These check:
- All game folders and `index.html` exist
- Every game has a `<canvas>`
- Gallery links to all games
- Basic JS game loop patterns exist
- Bug reporting section is present

### 2. Full E2E Tests (Playwright + real browser)
```bash
pip install -r tests/requirements.txt
python -m playwright install chromium

python -m pytest tests/ -q
```

See `tests/README.md` for details, common issues, and how to write gameplay-specific tests (Sugar Glide flight, Peek Duel shooting, etc.).

## Adding a New Game

When you add a game:
1. Create the folder + `index.html` + `README.md`
2. Add a card to the main `index.html`
3. **Add at least a smoke test** in `tests/test_smoke.py`
4. (Optional but recommended) Add real browser E2E tests

This is the best way to prevent the bugs you've been seeing.

---

## Asset Guidelines (for all future games)

**Preferred sources (all royalty-free or permissive):**

| Type       | Recommended Sources                          | License Notes                  |
|------------|----------------------------------------------|--------------------------------|
| Sounds     | Kenney.nl (Audio packs), Freesound (CC0)     | CC0 preferred                  |
| Sprites    | Kenney.nl, OpenGameArt (CC0)                 | CC0                            |
| Textures   | Pixabay, Kenney "Texture" packs, procedural  | No attribution required        |
| Music      | Pixabay Audio, ccMixter (check license), or Web Audio synthesis | Prefer generated/synthesized |
| Backgrounds| Pixabay illustrations + canvas filters       | Royalty free                   |

**Always document** the exact source + license in the game's README.

**For this project preference**: Use **procedural + synthesized audio** + **simple geometric + emoji/vector art** first. Only add external assets when they meaningfully improve feel. Keep file sizes tiny.

---

## Workspace Commands

```bash
# From the games directory or parent
cd /syncthing/forthehahas.com/games

# Preview
python3 -m http.server 8080
# or npx serve .
```

All games should work by simply opening the `index.html` file directly in a browser too.

---

*Last updated: 2026-09-12*