⚓ $\color{rgba(30, 62, 247)}{\textsf{Ship Story}}$

A 3D pirate naval game built on a custom OpenGL rendering engine, featuring physics simulation, spatial audio, particle effects, and a fully ECS-driven game world.

Watch full game demo here!

---

🎮 About the Game

Ship Story is a 3D action game where you captain a pirate ship across three progressively challenging levels:

Level	Objective
Level 1	Navigate treacherous waters — avoid rocks and obstacles
Level 2	Naval combat — fight enemy ships
Level 3	Treasure hunt — collect gold coins before time runs out
End Scene	Cinematic outro with a victory sequence

The game features a menu, story, loading, game-over, and coin-count state, all driven by a JSON-based scene configuration system.

quick-demo.mp4

---

🏗️ Engine Architecture

The project is built on a custom C++ rendering engine with the following subsystems:

Entity-Component-System (ECS)

• Entities are generic containers with a local transform and an optional parent.
• Components attach data and behaviour: Camera, MeshRenderer, Light, RigidBody, Collider, Player, Enemy, Health, AudioSource, AudioListener, Cannon, Projectile, Buoyancy, Spawner, AutoPilot, DamageFlash, Breadcrumb, Movement, ShipController, ThirdPersonCameraController, and more.
• Systems process components each frame: ForwardRenderer, PhysicsSystem, BuoyancySystem, CombatSystem, ProjectileSystem, SpawnerSystem, HealthSystem, AudioSystem, TrajectorySystem, AutoPilotSystem, MovementSystem, FreeCameraControllerSystem, ThirdPersonCameraSystem, and ShipControllerSystem.

Forward Renderer

• Opaque → Sky Sphere → Transparent (depth-sorted back-to-front) render order.
• Sky sphere rendering with the sky always appearing at max depth.
• Post-processing via framebuffers (vignette, chromatic aberration, and custom effects).
• Minimap rendered as a secondary camera pass with a circular, radial HUD overlay including enemy/objective trackers.
• Debug overlay for physics collision shapes (F3).

Materials & Shaders

Material Type	Description
TintedMaterial	Solid color with a tint uniform
TexturedMaterial	Albedo texture with UV transform
LitMaterial	PBR-inspired lighting with albedo, specular, roughness, AO, and emission maps

Custom GLSL shaders: lit, textured, tinted, water, particle, portal, ocean-depth, ui, fullscreen, and multiple post-process shaders.

Physics & Water

• ReactPhysics3D for rigid body simulation and collision detection.
• Buoyancy system simulates waterline physics using a configurable water-height function.

Audio

• miniaudio for low-latency audio playback.
• Separate musicGroup and sfxGroup with independent mute controls (F2 / F1).
• SFX registry loaded from assets/audio/sfx_registry.json.
• 3D positional audio via AudioListener and AudioSource components.

Asset Pipeline

• All scenes, meshes, textures, materials, and samplers are defined in JSONC config files.
• Assimp for loading 3D model files (.obj, .fbx, .gltf, etc.).
• Async asset loading queue with a dedicated loading screen for large levels.

---

📂 Git LFS

This repository uses Git Large File Storage (LFS) to manage large binary assets. The following file types are tracked via LFS:

Extension	Asset Type
.fbx, .obj, .gltf, .glb, .blend	3D models
.bin	Binary mesh/buffer data
.png, .jpg, .jpeg	Textures & images
.wav	Audio files

Cloning with LFS

Make sure git-lfs is installed before cloning, otherwise the binary files will be replaced with small pointer files and the game won't load any assets.

# Install Git LFS (once per machine)
# Ubuntu/Debian
sudo apt install git-lfs

# macOS (Homebrew)
brew install git-lfs

# Then activate it
git lfs install

# Now clone normally — LFS files are fetched automatically
git clone <repo-url>

If you already cloned without LFS, pull the missing files with:

git lfs pull

---

🛠️ Building

Prerequisites

Tool	Minimum Version
CMake	3.0
C++ Compiler	C++17 (GCC 9+, Clang 5+, MSVC 2017+)
OpenGL	4.x capable GPU driver

Linux only: Also requires libgl-dev (or equivalent) — the build system auto-links OpenGL::GL.

Build Steps

# 1. Configure
cmake -B build -S .

# 2. Compile
cmake --build build --parallel

# The executable lands at:
#   bin/GAME_APPLICATION        (Linux/macOS)
#   bin/GAME_APPLICATION.exe    (Windows)

Alternatively, open the project folder in VS Code with the CMake Tools extension and click Build.

Cross-compiling for Windows (MinGW)

cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=mingw-toolchain.cmake
cmake --build build --parallel

---

▶️ Running

# Default config (starts at the main menu)
./bin/GAME_APPLICATION

# Specify a custom config file
./bin/GAME_APPLICATION -c='config/app.jsonc'

Remove .exe on Linux/macOS.

---

🎮 Controls

Key	Action
W / A / S / D	Sail the ship
Mouse	Aim / look around
Left Click	Fire cannons
M	Toggle minimap
Escape	Return to menu
F1	Toggle SFX mute
F2	Toggle music mute
F3	Toggle physics debug overlay

---

📦 Dependencies

All dependencies are vendored (no external package manager needed):

Library	Purpose
GLFW	Window creation & input handling
GLAD2	OpenGL function loader
GLM	GLSL-compatible math (vectors, matrices, quaternions)
Dear ImGui	HUD, minimap, debug UI
Assimp	3D model loading
ReactPhysics3D	Rigid body physics & collision
miniaudio	Cross-platform audio playback
nlohmann/json	JSONC config parsing
flags	CLI argument parsing

---

📚 Resources

• Learn OpenGL
• The Book of Shaders