CardDoom is a minimalist 3D engine implemented using the Raycasting technique (similar to the classic Wolfenstein 3D), designed to run on a NodeMCU (ESP8266) microcontroller utilizing a 128x64 OLED display (I2C).
The project serves as a high-performance demonstration of 3D graphics on resource-constrained hardware. It is built upon the Arduino framework and uses optimized trigonometric look-up tables (fixed-point math) for rapid frame rendering.
The engine uses five digital pins for core movement and action. Since the code utilizes INPUT_PULLUP, buttons must be connected between the specified pin and GND (Ground).
| Game Action | Code Pin (digitalRead) |
NodeMCU GPIO | D-Pin | Function |
|---|---|---|---|---|
| Forward | 2 | GPIO2 | D4 | Moves player forward |
| Backward | 3 | GPIO3 | RX | Moves player backward |
| Turn Left | 4 | GPIO4 | D2 | Turns camera left |
| Turn Right | 5 | GPIO5 | D1 | Turns camera right |
| Fire / Action | 6 | GPIO6 | SD_CLK | Triggers the weapon animation |
The map is defined as a 10x10 array (M[]).
- 1: Represents a Wall.
- 0: Represents a Free Space (Path).
The player starts near the center of the free space and navigates a labyrinthine structure.
| 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 |
|---|---|---|---|---|---|---|---|---|---|
| 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 |
| 1 | 0 | 1 | 1 | 0 | 0 | 1 | 1 | 0 | 1 |
| 1 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 1 |
| 1 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 1 |
| 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 |
| 1 | 0 | 1 | 0 | 1 | 1 | 0 | 1 | 0 | 1 |
| 1 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 1 |
| 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 |
| 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 |
This project uses a custom version of the SSD1306 display library.
- Origin: The library is based on the original
SSD1306Wirefrom ThingPulse. - Modification: The core code was refactored and tailored specifically for CardDoom's performance needs, reducing its size significantly (from approximately 1MB down to 200KB) without changing the display functionality essential for the project.
The repository includes a Python script, map_cardoom_3d_view.py, that provides a separate 3D visualization of the map structure as a model. This script helps developers understand the labyrinth's layout.
To run the visualization tool, you must install the required Python libraries:
pip install matplotlib numpyThe CardDoom project uses two distinct licenses.
MIT License
The main CardDoom engine code is licensed under the permissive MIT License. This grants users the freedom to use, copy, modify, and distribute the code, provided the original copyright and license notice are retained.
Sliz Open Source License (SOSL) Version 1.0, 2025
This custom license applies only to the modified SSD1306 library files.
Key Terms of SOSL:
- Attribution (Section 2): Any use, copying, or modification of the library must include clear attribution to Sliz®.
- Derivative Work Restriction: While the library is open-source (Section 1), you are prohibited from taking the custom library, modifying its core purpose or attribution, and claiming it as your own independent custom product. You may use the library as is, or modified within another open-source project, but must always acknowledge its origin from Sliz®.
- Legal Enforcement (Section 4): Failure to comply with the attribution requirement and other terms will result in legal action by Sliz®.
In short: You can use and modify the custom SSD1306 library within CardDoom or other open-source projects, but you cannot copy the custom code, rename it, and distribute it as a different, original custom library without explicit permission.