Initial commit

README.md

@@ -0,0 +1,100 @@
+# First Person Maze
+
+A native Rust / Bevy game. Collect every pellet in the maze while avoiding four
+ghosts. Power pellets let you catch ghosts for bonus points. You have three lives.
+
+## Play
+
+Run `first_person_maze.exe` on Windows or `./first_person_maze` on Linux from a
+release package. Keep `assets/` next to the executable. A graphical desktop and
+working GPU drivers are required.
+
+| Input | Action |
+| --- | --- |
+| W / A / S / D | Move / strafe |
+| Mouse or left / right arrows | Look / turn |
+| Enter | Start / activate menu selection |
+| Escape | Pause / resume / leave settings |
+| Arrow keys | Navigate menus / adjust settings |
+| F3 | Toggle performance HUD |
+| Gamepad sticks | Move / look |
+| Gamepad D-pad / south button | Navigate / activate |
+| Gamepad Start | Pause / resume |
+
+Losing focus pauses the game. Settings include resolution, fullscreen, volume,
+mouse sensitivity, keyboard-only camera, head bob, 30/60 FPS and low graphics.
+ARM64 defaults to low graphics and 30 FPS; other architectures default to 60 FPS.
+
+Settings save to `%APPDATA%/first_person_maze/settings.ron` on Windows, or
+`$XDG_CONFIG_HOME/first_person_maze/settings.ron` on Linux (default:
+`~/.config/first_person_maze/settings.ron`). Delete this file to restore defaults.
+
+## Build
+
+Requires Rust 1.95 or newer. Keep `Cargo.lock` and build with `--locked`.
+
+Windows requires the MSVC Rust toolchain, Visual Studio C++ Build Tools and a
+Windows SDK. Linux requires native development libraries; on Debian / Ubuntu:
+
+```sh
+sudo apt install build-essential pkg-config libasound2-dev libudev-dev \
+  libx11-dev libxi-dev libxrandr-dev libxcursor-dev libxinerama-dev \
+  libxkbcommon-dev libwayland-dev libvulkan-dev
+```
+
+```sh
+cargo build --release --locked
+cargo run --release --locked
+```
+
+When building from a network share, use a local build directory. In PowerShell:
+
+```powershell
+$env:CARGO_TARGET_DIR = "$env:LOCALAPPDATA/first_person_maze/target"
+```
+
+Linux also needs a Vulkan loader and GPU driver at runtime. For Raspberry Pi,
+use a 64-bit desktop OS and a working V3DV driver; build natively on the device.
+Linux, ARM64 and physical gamepads have not been validated in this cleanup.
+
+## Package
+
+From PowerShell on Windows:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File tools/package.ps1
+```
+
+From a POSIX shell on Linux:
+
+```sh
+sh tools/package.sh
+```
+
+An optional target triple can be supplied as the first argument. Cross builds
+require the corresponding Rust target, linker and native target libraries.
+`CARGO_TARGET_DIR` is supported by both scripts.
+
+Packages are written to `release/<target>/first_person_maze/` and contain only
+the executable, this README and runtime audio. Each packaging run replaces the
+previous package for that target. Distribute the folder as an archive. Windows
+players may need the Microsoft Visual C++ runtime; Linux players need the
+system libraries matching the build environment.
+
+## Audio and maintenance
+
+Seven synthesized WAV effects are included. To regenerate them, run
+`python tools/generate_audio.py` (Python is only needed for regeneration).
+Add your own licensed `assets/audio/music.wav` to enable looping background music.
+Geometry and the default font are generated or embedded. Missing audio is skipped.
+
+Before packaging:
+
+```sh
+cargo fmt --check
+cargo clippy --locked --all-targets -- -D warnings
+cargo build --release --locked
+```
+
+Manually verify start, movement, pellet collection, ghost contact, pause/resume,
+settings, restart and result screens on each supported platform before release.