ntduck/introspection

a hopefully-non-cliché, RPG-inspired small game project made with C++ and SDL2.

introspection

an engineless RPG.

Table of content

0. About
1. Demo
2. Installation
   1. Windows
   2. Debian-based Linux
   3. Arch-based Linux
3. Features
4. Tech stack
5. Programming techniques
6. Class hierarchy
7. Acknowledgements
8. References
9. License
10. Support

About

This repository contains the source code for a university project from the University of Engineering and Technology (VNU-UET). The project was completed as part of the Advanced Programming (2324II_INT2215_25) course, instructed by Nguyễn Việt Anh and Hoàng Thị Ngọc Trang. The project was taken independently by student Nguyễn Tư Đức (ID: 23021534).

Demo

demo-12-5-2024-compressed.mp4

Installation

Windows

Prerequisites:

• A configured C++ compiler, preferably MinGW or MinGW-w64
• Brain (optional)
• Compatible hardware

Configuration:

None required.

Clone the repository:

git clone https://github.com/NTDuck/8964 
cd 8964

Build the project:

mingw32-make
mingw32-make run

Troubleshooting:

Compile-time and runtime errors are unlikely to occur.

Debian-based Linux distributions

Prerequisites:

sudo apt-get update
sudo apt-get install g++ make libsdl2-dev libsdl2-image-dev libsdl2-ttf-dev libsdl2-mixer-dev zlib1g-dev

Configuration:

None required.

Clone the repository:

Same as Windows.

Build the project:

make
chmod +x ./build/8964
make run

Troubleshooting:

Linux builds, due to unknown reasons, are more prone to runtime segmentation faults.

Arch-based Linux distributions

Prerequisites:

sudo pacman -Syu
sudo pacman -S gcc make sdl2 sdl2_image sdl2_ttf sdl2_mixer zlib

Configuration:

None required.

Clone the repository:

Same as Windows.

Build the project:

make
chmod +x ./build/8964
make run

Troubleshooting:

Linux builds, due to unknown reasons, are more prone to runtime segmentation faults.

Others:

Official os-specific releases are not available, and compatibility layers (e.g. wine) are not tested.

Features

System

• ESC, when held, exits the game
• F1, while in-game, returns to the menu
• F4, while in-game, reloads the current level
• F5, while in-game, toggles between camera angles
• F6 toggles grayscale

Player

• Movement: press W (up), A (left), S (down), and D (right) keys for navigation
• Sprint: holding down Shift increases the player's speed
• Interaction: press E to interact with certain objects and engage with in-game dialogues
• Melee attack: press Space to execute a melee attack
• Ranged attack: press 1, 2, 3, 4, and 5 to launch unique sets of projectiles

Entities

• Non-interactables do not offer any form of interaction
• Interactables, as the name suggests, can be interacted
• Teleporter entities, upon being trampled, immediately teleport the player to a different location
• Hostile entities, within a specified range, pursue and attempt to attack the player
• Surge projectiles are tile-bound projectiles

Components

Encompass common graphical elements such as Buttons, Progress bars, and Dialogue boxes. Offer interactivity through mouse and/or keyboard inputs.

Interfaces

Encapsulate all operations within a game state, therefore facilitating modular design and fostering adherence to SoC.

Levels

• level-prelude

• level-prologue-movement

• level-prologue-combat

• level-suffering-empty-0

• level-suffering-1-0

• level-suffering-1-1

• level-suffering-2-0

• level-suffering-2-1

• level-suffering-3-0

• level-suffering-3-1

• level-suffering-3-2

• level-status-quo-0

• level-status-quo-1

• level-status-quo-2

• level-status-quo-3

• level-status-quo-4

• level-roundtable-empty

• level-roundtable-first-proposal

• level-roundtable-second-proposal

• level-roundtable-final-proposal

• level-interlude

• level-white-space

Tech Stack

Language: C++ 17

Dependencies:

• SDL2 2.28.3, SDL_image 2.6.3, SDL_ttf 2.20.2, SDL_mixer 2.6.3
• JSON for Modern C++ 3.11.2
• pugixml 1.14
• zlib 1.3 (with Microsoft Github's precompiled zlib.dll)

Third-party tools:

• Tiled 1.10.2 for level generation
• KRMisha's Makefile for cross-platform compilation
• Sprite Sheet Packer for spritesheet concatenation

Compiler: MinGW GCC 13.2.0 (64-bit)

Build system: GNU Make 4.4.1

Version control: Git 2.40.0.windows.1

Programming techniques:

Design patterns

Uses OOP with CRTP and Explicit Template Instantiation.

Data Structures

• Custom hash functors and operator overloading
• LRU Cache using double-ended queue and hashmap

Algorithms

• Texture manipulation, grayscale conversion
• Zlib decompression
• Base64 decoding
• Hexadecimal to RGB conversion
• A* search algorithm, Dijkstra pathfinding algorithm, Greedy Best-First-Search algorithm (both reverted from A*)

Data Serialization

• Supports manipulation & retrieval of JSON/XML data formats (in-memory & from files)

Misc

• Uses SFINAE and Parameter pack
• Uses preprocessor directives, macros, and templates extensively
• Uses a manual garbage collection system
• Supports distribution & retrieval of custom events
• Supports frame-independent animation
• Supports IDE-independent, cross-platform compilation

Class Hierarchy

warning: outdated

Acknowledgements

We would like to credit certain assets used in this project. Licenses, if any, should be included in the links below.

Tilesets

• 1-bit Pulp-compliant Tileset
• Minimalistic Tileset Assets
• OMORI Game Assets
• Hana Caraka Base Character
• Hooded Protagonist
• Satyr
• Chick-Boy Animation Pack
• Plague Crow
• Dark Samurai (Prestige Inkshadow Yasuo)
• Red Hood
• Nightborne Warrior (Kassadin)

Fonts

• Omori
• Phorssa

BGM & SFX

• OMORI OST
• Dearly Departed
• Persistent repetition of phrases
• Wilhelm Scream SFX
• Shoe on Wet Ground SFX, Heavy Clump on Gravel SFX
• Numerous BGM & SFX from OMORI
• Lucky Star PS2 Bonus Disc

We would also like to recognize reknowned games from which certain concepts and mechanics in this project drew inspiration, which include but are not limited to Elden Ring, Omori, Undertale, and The Coffin of Andy and Leyley.

References

• Cross-platform SDL2 installation & configuration
• C++ documentation
• SDL2 tutorial
• SDL2 documentation
• Stackoverflow

License

This project is licensed under the BSD-3-Clause license.

Support

For support, please email [email protected].

---

from the ground they come
and to it
they return

introspection's Issues

Textures invalidated on SDL_WINDOWEVENT_SIZE_CHANGED, Windows only

IngameMapHandler::mTexture and IngameDialogueBox::BMPFont::mTexture get invalidated i.e. "blacked out" when their classes' respective onWindowChange() gets called. This only seems to appear when compiled on Windows, as this has not been observed on Linux distributions.

This has been patched by including reinitialization of such textures in their respective onWindowChange() method, at the cost of performance (reinitialzing IngameMapHandler::mTexture is an expensive process that could cause significant lag, since multithreading has not been implemented). This patch has been, via preprocessor directives, implemented only on Windows.

Large level size causes undefined behaviour

For a level that is too large, for example level assets/.tiled/.tmx/level-tutorial-concat-flawed.tmx (200 x 50 tiles, 32 x 32 px each), certain undebuggable undefined behaviours occur: the screen is always filled with a black or white color, nothing renders. Occurs on all operating systems.

Temporary fix: compartmentalize any large levels into smaller levels that should not exceed 100 tiles in size.

Level texture appears fragmented

IngameMapHandler::mTexture, on full-screen view (i.e. IngameViewHandler::View::kFullScreen), has tiles that are not "clamped" i.e. non-invisible "borders" are evident around each tile, especially those representing in-game walls. This adversely affects how the game looks.