group 8

Treasure Adventure (game-dev-btl3)

A cozy, classic-style 2D platformer. Run and jump across islands, collect coins, pop boxes for powerups, and avoid enemies on your way to the boss. Includes a starting screen, pause menu, HUD, music, and sound effects.

Features

• Parallax-style background and ambient animations
• Tilemap loader via TMX (assets/maps/pirate.tmx)
• Player movement, jumping, collisions, damage & invincibility frames
• Enemies and a boss with collision handling and scoring
• Collectibles: coins and star powerups
• Projectiles system scaffolded
• Starting screen with PLAY/OPTION/ABOUT/EXIT
• Pause menu with score and mute controls
• Game over screen with restart prompt

Play Now (no technical background required)

• Works on Windows, macOS, or Linux.
• You need Python (free) installed one time.

Windows (easiest):

1. Download and install Python from the official site: Download Python
   • During install, tick “Add Python to PATH”.
2. Open the game folder (the one that contains main.py).
3. Double‑click main.py.
   • If a console flashes and closes, continue with steps 4–6:
4. Right‑click the folder background → “Open in Terminal/PowerShell”.
5. Paste the following and press Enter after each line:

   python -m pip install --upgrade pip
   pip install pygame pytmx
   python main.py

macOS/Linux:

1. Install Python from python.org, or use your package manager.
2. Open Terminal in the game folder and run:

   python3 -m pip install --upgrade pip
   pip3 install pygame pytmx
   python3 main.py

On first launch you will see the Starting Screen. Press ENTER/SPACE or click PLAY. During gameplay you can click the pause button at the top‑right to open the pause panel.

How to Play (for everyone)

• Goal: Reach the end, collect coins, and defeat the boss for a high score.
• Move: Left/Right Arrow
• Jump: Space
• Pause: Click the pause button (top‑right)
• Start: On the first screen, press ENTER/SPACE or click PLAY
• Options: From the start or pause menu, you can mute/unmute music

Tips:

• Hitting special boxes can spawn a star powerup.
• Stars make you temporarily invincible and change your color.
• Landing on enemies can defeat them; colliding from the side hurts you.

Controls

• Left/Right Arrow: move
• Space: jump
• Mouse: interact with UI (Start screen buttons, Pause menu)

Starting Screen:

• ENTER/SPACE: start game
• PLAY/OPTION/ABOUT/EXIT: click with mouse

Pause Menu:

• Click the pause button (top-right) to open/close
• Toggle music mute from within the pause panel

Configuration (optional)

All core settings live in core/setting.py:

• SCREEN_WIDTH, SCREEN_HEIGHT, FPS
• Player physics: PLAYER_SPEED, PLAYER_JUMP_FORCE, GRAVITY, PLAYER_FRICTION …
• Audio: AUDIO_ENABLED, MUSIC_VOLUME, SFX_VOLUME, WALK_VOLUME

Project Structure (high level)

assets/            # sprites, audio, fonts, maps
core/              # settings, background renderer
enemies/           # enemy and boss logic
entities/          # base entity types
graphic/           # image utils (scaling, loading)
items/             # item logic (e.g., coins, stars)
map/               # TMX map loader & camera
objects/           # blocks, boxes, interactables
player/            # player character
projectiles/       # projectile classes
ui/                # HUD and menus
main.py            # entrypoint
game_manager.py    # main loop, world orchestration

Key runtime classes:

• GameManager (game_manager.py): game loop, scene state, audio, groups
• MapManager (map/map_manager.py): loads TMX, camera offset, draws map
• Player (player/player.py): movement, collisions, animation, health
• HUD & StartingScreen (ui/hud.py, ui/menu.py): UI layers

Adding Content

• Maps: replace or edit assets/maps/pirate.tmx in Tiled. Collision layers named like "Tile Layer 1"/"ground"/"platform" are treated as solid.
• Enemies/Boxes/Coins: see the sprite groups created in GameManager.__init__ and reset_level(); add more instances there.
• Audio: drop files in assets/audio/ and register them in GameManager.play_sfx or background music setup.

Troubleshooting

• The window opens then closes immediately
  • Open a terminal in the game folder and run the commands in “Play Now” above. This will install any missing pieces and show helpful error messages if something goes wrong.
• “pygame not found” or “pytmx not found”
  • Install them: pip install pygame pytmx (or pip3 on macOS/Linux).
• No sound or mixer errors
  • In the options/pause menu, make sure music isn’t muted.
  • On Windows, you can try launching from a terminal after running: set SDL_AUDIODRIVER=directsound.
• Stuck on the starting screen
  • Press ENTER/SPACE or click the PLAY button. Make sure the game window is focused (clicked).
• Game seems frozen after clicking the pause button
  • Click the pause button again or the Continue button in the pause overlay.

Development (for technical users)

Requirements

• Python 3.8+ (tested on 3.10+)
• Dependencies: pygame, pytmx

Install and run (recommended inside a virtual environment):

python -m venv .venv
.venv\Scripts\activate   # Windows PowerShell
# source .venv/bin/activate  # macOS/Linux
python -m pip install --upgrade pip
pip install pygame pytmx
python main.py

Tips

• Keep frame-rate stable: the loop uses FPS and passes dt seconds to updates.
• Camera follows the player horizontally with MapManager.update_camera.
• Tile size is 32 px (TILE_SIZE) for placement and collisions.

Credits & License

• Code and gameplay assembled for educational purposes.
• Pixel art and UI assets included under their respective creators’ terms: https://pixelfrog-assets.itch.io/treasure-hunters