FoP Project — Maze Runner (Maze Runner / Git Containment)

• Course: Fundamentals of Programming (INHN0002) — Heilbronn — WS 25/26
• Project: FoP Project — Maze Runner
• Tech: Java + libGDX (2D / Top-Down / Desktop: LWJGL3)

Demo Video

Watch the gameplay demo here: https://youtu.be/0t6_lOOpR9g

---

Table of Contents

1. Overview
2. Story & Theme
3. How to Run
4. How to Play (Controls, Objectives, Rules)
5. Requirement Mapping (Minimal Requirements)
6. Additional Features (Beyond Minimal Requirements)
7. Map Specifications (properties / tmx)
8. Project Structure & Design
9. Assets & Credits
10. Troubleshooting
11. Code Entry Points (for Reviewers)

---

Overview

Maze Runner is a 2D top-down game in which the player explores a maze, collects a key (Keycard), avoids dangers such as traps, enemies, and various gimmicks, and aims to reach the exit.

This project was implemented to integrate object-oriented design concepts taught in the course—such as responsibility separation, inheritance, delegation, and abstraction—into a complete game project.

The game includes:

• Main Menu / Level Selection / Settings (Key Remapping) / Pause (Esc)
• HUD (Lives, Key Status, Destination Arrow)
• Maze loading from properties files (course-specified x,y=value format)
• Intelligent enemy movement (AI pathfinding)
• Extended features (Endless Mode, Save & Load, Achievements, Skill Tree, Developer Console, Local Leaderboard)

This README is structured in the order Launch → Controls → Requirement Mapping → Design → UML, so reviewers can evaluate the project efficiently.

---

Story & Theme

The title displayed on the title screen is “Git Containment.” The game takes place in a research facility that has been sealed due to an unknown contamination (referred to in-game as the “GIT Virus”). The interior has transformed into a maze.

The player explores the facility, collects fragments of a cure, avoids hazards, and attempts to escape.

• Victory / defeat messages are shown via EndScreen
• Background music and sound effects are selected to enhance exploration and tension

---

How to Run

Requirements

• Java JDK (JDK 8 compatible recommended)
• Gradle Wrapper included (gradlew, gradlew.bat)

Desktop Execution (LWJGL3)

From the project root:

./gradlew lwjgl3:run

On Windows:

gradlew.bat lwjgl3:run

Entry Points

• lwjgl3/.../Lwjgl3Launcher.java – Desktop launcher
• core/.../Main.java – libGDX Game class managing Screens

---

How to Play (Controls, Objectives, Rules)

Objective

1. Obtain the Key (Keycard) inside the maze
2. Locate the Exit on the outer boundary
3. Escape before running out of lives

Controls (Default)

Default key bindings are defined in GamePreferences.DEFAULT_KEYS.

• Move: Arrow Keys
• Sprint: Shift + Move
• Attack: Space
• Reload: R
• Interact: E
• Console: T
• Shoot: Left Mouse Button
• Zoom: = (Zoom In) / - (Zoom Out)
• Slots: 1–4

Key bindings can be remapped in the Settings screen and are saved and applied on the next launch.

Core Rules

• Walls cannot be passed
• Contact with traps or enemies causes damage (life reduction)
• HUD always displays lives, key possession, and destination arrow
• Esc opens the Pause menu (gameplay stops)

---

Requirement Mapping (Minimal Requirements)

This section maps assignment requirements to concrete implementations for easier grading.

1) Maze Files (properties loading)

• ✅ Reads assets/maps/*.properties using the x,y=value format

  • Loader: MapLoader.load(String fileString)

• ✅ All .properties files in maps/ are listed and selectable in the menu

  • LevelsScreen.populateCustomMapList()

2) Graphics (2D Top-Down / Sprites)

• ✅ 2D top-down rendering using libGDX

  • GameScreen, LevelWorld, GameObject.render(...)

3) Walls / Entry / Exit Identification

• ✅ Walls, entry, and exit are handled as separate objects and visually distinct

  • Examples: Wall, Exit, generated by map type values

4) Character (4-direction movement / Sprint / Lives)

• ✅ Four-direction movement

• ✅ Sprint with Shift

• ✅ Life (HP) system with HUD display

  • Input/Movement: PlayerInputProcessor, Player
  • Display: HUD

5) Obstacles (Trap / Enemy / Third Obstacle)

• ✅ Trap (static): Trap
• ✅ Enemy (dynamic): Zombie
• ✅ Intelligent enemy movement (wall avoidance / pathfinding): GridPathfinder (A*)
• ✅ Additional gimmicks (e.g., Portal implemented as map objects)
• also having guns and ammo for far range attack**

f the assignment strictly requires the third obstacle to reduce life on contact, ensure the README and implementation match exactly.

6) Keys (Exit unlocked by key)

• ✅ Exit condition checks key possession: ExitSystem (player.hasKey())

7) HUD (Lives / Key / Exit Direction)

• ✅ Lives: heart display (HUD)

• ✅ Key possession: keycard UI (HUD)

• ✅ Destination arrow: ExitPointerSystem

  • Points to key before pickup, exit after pickup

8) Menu / Pause (Esc)

• ✅ Startup menu: MainMenuScreen
• ✅ Pause menu via Esc: handled in GameScreen
• ✅ Resume / Load Map / Exit via menu transitions

9) Custom Key Bindings (Save & Load)

• ✅ Remappable in Settings
• ✅ Loaded on startup: GamePreferences
• Saved to: assets/config/keybinds.properties

10) Viewport / Camera / Zoom

• ✅ Follow camera: GameCamera
• ✅ Screen resize support via resize(...) and camera update
• ✅ Zoom in/out via key bindings

11) Music & Sounds

• ✅ Audio system: SoundSystem

• ✅ Supports BGM (menu / gameplay) and SFX

  • Events such as life lost, key collected, victory, and game over

---

Additional Features (Beyond Minimal Requirements)

**---

Fog of War (Limited Visibility)

• System: FogOfWarSystem
• Effect: Limits visible area around the player
• Behavior: Visibility updates dynamically as the player moves
• Purpose: Increases tension and encourages careful exploration

---

HUD Design and Player Guidance

• UI: HUD

• Lives display: Heart-based life indicators

• Key status: Key possession shown at all times

• Navigation aid: ExitPointerSystem

  • Points to the key before collection
  • Points to the exit after the key is obtained

• Design goal: Always provide orientation without revealing the full maze

---

Player Combat Abilities

• Player entity: Player
• Input handling: PlayerInputProcessor

Ranged Combat

• Weapons: Gun, Shotgun, IceGun
• Projectiles: Bullet
• Features: Reloading, weapon switching, mouse-based aiming

Melee Combat

• Weapon: Sword / club-style close-range weapon
• Behavior: Instant damage on contact
• Design intent: High-risk, high-reward alternative to ranged combat

---

Damage Feedback and Visual Effects

• Visual feedback: Temporary color change on player sprite when damaged
• Audio feedback: Damage sound effects
• State handling: Short invulnerability window after taking damage
• Purpose: Clearly communicate damage and prevent confusion during combat

---

UI Screens and Loading Flow

• Main menu: MainMenuScreen
• Gameplay screen: GameScreen
• Pause menu: Triggered via ESC
• Settings screen: SettingsScreen
• Loading / transition screens: LevelIntroScreen
• End states: EndScreen (Victory / Game Over)
• Design goal: Clear separation of game states and safe transitions

---

Audio System

• Manager: SoundSystem

• Background music:

  • Main menu
  • Gameplay
  • Pause

• Sound effects:

  • Damage taken
  • Item pickups
  • Weapon usage
  • Victory / defeat

• Purpose: Gameplay feedback and atmosphere enhancement

---

Endless / Procedural Mode

• Screen: EndlessGameScreen

• Config: assets/maps/endless.properties

• Generation: MazeGenerator

• Features:

  • Procedural maze generation from a seed
  • Gradual difficulty scaling over time

• Purpose: Replayability and leaderboard-based challenge

---

Achievements (External File + Events)

• Definitions: assets/config/achievements.properties
• Manager: AchievementManager
• Display: AchievementScreen
• Triggering: Event-driven achievement unlocking
• Purpose: Encourage exploration and long-term goals

---

Developer Console (Runtime Commands)

• UI: DevConsole

• Command handling: com.console.CommandManager

• Features:

  • Runtime command execution
  • Debugging and state inspection

• Theme: Git-style command interface aligned with game concept

---

Skill Tree and Player Progression

• Manager: SkillManager

• UI: SkillScreen

• Progression:

  • XP-based leveling
  • Permanent upgrades

• Purpose: Long-term character development beyond a single run

---

Local Leaderboard

• Display: LeaderboardScreen
• Score source: Endless / Survival mode
• Storage: GamePreferences (local preferences)
• Purpose: Track high scores and encourage replayability

---

Save / Load System

• Manager: GameSaveManager

• Data model: GameSaveData

• Storage format: JSON serialization

• Saved state:

  • Player stats
  • Current level
  • Progress and inventory

• Purpose: Allow session persistence and safe recovery

Environmental Puzzle: Paper Notes and Power Activation

• Collectible item: Paper

• Behavior:

  • Papers can be picked up inside the maze
  • Each paper contains partial hints or encrypted information

• Puzzle mechanic:

  • The player must collect and interpret the papers
  • Clues lead to discovering a hidden code
  • The correct code is required to restore electricity in the facility

• Environmental effect:

  • Activating electricity lights up dark areas
  • Improves visibility and reveals previously hidden paths

• Purpose:

  • Encourage exploration beyond direct navigation
  • Add narrative-driven puzzle solving
  • Integrate world interaction beyond combat and movement

This puzzle mechanic is optional for progression in some levels and reinforces the game’s investigation and containment theme.

Save / Load (Serialization)

• GameSaveManager, GameSaveData
• JSON-based full game state saving (player, level, progress)

Endless / Procedural Mode

• EndlessGameScreen
• Config: assets/maps/endless.properties
• Generation: MazeGenerator

Achievements (External File + Events)

• Definitions: assets/config/achievements.properties
• Manager: AchievementManager
• Display: AchievementScreen

Developer Console (Runtime Commands)

• UI: DevConsole
• Command handling: com.console.CommandManager
• Git-style commands for debugging and navigation

Local Leaderboard

• Display: LeaderboardScreen
• Score shown on: EndScreen
• Storage: GamePreferences (Preferences)

Skill Tree / Progression

• Manager: SkillManager
• UI: SkillScreen

**There are lots more beyond requirements feature **Please enjoy finding it!!!

Map Specifications (properties / tmx)

A) properties (Assignment-specified format)

• Example: 5,6=3
• Coordinate system: bottom-left (0,0), +x right, +y up

value	object
0	Wall
1	Entry
2	Exit
3	Trap
4	Enemy
5	Key
also, having other object, these are just example

Loader: MapLoader.load(String fileString)

B) TMX (Tiled)

• Loader: MapLoader.loadFromTMX(...)
• Level intro: LevelIntroScreen

---

Project Structure & Design

Modules

• core/: Game logic, UI, systems
• lwjgl3/: Desktop launcher (LWJGL3)

Main Packages (by Responsibility)

core/src/main/java/com/GitLost/MazeRunner/:

• ui/: Screens, HUD, Menus, Settings, Overlays
• systems/: Per-frame game logic (camera, collision, exit, pickup, combat, fog, etc.)
• objects/: Static & dynamic maze objects (walls, exits, traps, bullets, weapons, pickups, gimmicks)
• entities/: Player and enemies
• map/: Map loading and coordinates
• game/: Settings, difficulty, save, achievements, skills, inventory
• path/: Pathfinding (A*)
• com.console/: Developer console commands

Design Highlights

• Clear separation between Screens (UI) and Systems (game logic)
• Maze state managed by LevelWorld, updated by systems
• Maze elements centered around GameObject to avoid duplication

---

Assets & Credits

Clearly list all used assets and licenses when submitting.

• Graphics: (Author / Website / URL / License)
• Music: (Author / Website / URL / License)
• SFX: (Author / Website / URL / License)
• Fonts: (Author / Website / URL / License)

---

Troubleshooting

1) Gradle / JDK Issues

• Ensure the IDE’s Gradle JVM points to a correct JDK (see assignment instructions)

2) Startup Issues on Windows / Linux

• Remove -XstartOnFirstThread from run configuration if present

3) Map Not Loading

• Ensure files are under assets/maps/
• Check x,y=value format
• Verify encoding and line endings

---

Code Entry Points (for Reviewers)

• Startup & screen flow: Main
• Normal gameplay: GameScreen
• Endless mode: EndlessGameScreen
• Map loading: MapLoader
• World generation: LevelWorldFactory
• Exit logic: ExitSystem
• Input: PlayerInputProcessor
• Enemy AI / pathfinding: Zombie, GridPathfinder
• HUD: HUD, ExitPointerSystem
• Save system: GameSaveManager
• Achievements: AchievementManager
• Skills: SkillManager
• Console: DevConsole, CommandManager

---

-- Thank you for reviewing our project

(End of document)

---