https://github.com/slizr/cardoom
Use this pocket shooter game in your Arduino projects!
https://github.com/slizr/cardoom
250 arduino card cardoom cpp doom esp esp8266 github kb mcu node nodemcu release sliz slizr total version
Last synced: about 1 month ago
JSON representation
Use this pocket shooter game in your Arduino projects!
- Host: GitHub
- URL: https://github.com/slizr/cardoom
- Owner: SlizR
- License: mit
- Created: 2025-12-13T10:54:56.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-12-13T14:33:50.000Z (5 months ago)
- Last Synced: 2025-12-15T02:11:17.614Z (5 months ago)
- Topics: 250, arduino, card, cardoom, cpp, doom, esp, esp8266, github, kb, mcu, node, nodemcu, release, sliz, slizr, total, version
- Language: C
- Homepage:
- Size: 67.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## CardDoom: Raycasting Engine on ESP8266
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).
### Project Overview
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.
### Hardware Connection and Controls
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 |
### Game Map
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 |
### Custom Display Library: `SSD1306Wire.h`
This project uses a custom version of the SSD1306 display library.
* **Origin:** The library is based on the original `SSD1306Wire` from **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.
### Map Visualization Tool
The repository includes a Python script, [`map_cardoom_3d_view.py`](https://www.google.com/search?q=%5Bhttps://github.com/SlizR/Cardoom/blob/main/map_cardoom_3d_view.py%5D\(https://github.com/SlizR/Cardoom/blob/main/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:
```bash
pip install matplotlib numpy
```
### Licensing
The CardDoom project uses two distinct licenses.
#### 1\. CardDoom Project (Main Code)
**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.
#### 2\. Custom `SSD1306` Library
**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.