{"id":15053082,"url":"https://github.com/esotericpig/ekoscape","last_synced_at":"2026-04-02T02:37:37.486Z","repository":{"id":251026967,"uuid":"834103580","full_name":"esotericpig/EkoScape","owner":"esotericpig","description":"🎮🤖🧿 Simple 3D step-based game in SDL2 \u0026 C++, like a 3D Pac-Man.","archived":false,"fork":false,"pushed_at":"2024-10-24T03:09:27.000Z","size":458,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-24T20:10:16.406Z","etag":null,"topics":["3d","3d-game","cplusplus","cpp","grid-based-movement","opengl","opengl-game","sdl","sdl2","sdl2-game","sdl2-image","sdl2-mixer"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/esotericpig.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-26T12:29:14.000Z","updated_at":"2024-10-24T03:09:31.000Z","dependencies_parsed_at":"2024-09-14T19:45:09.897Z","dependency_job_id":"963b98c4-f52c-41ac-8a91-d52426e8f68c","html_url":"https://github.com/esotericpig/EkoScape","commit_stats":{"total_commits":231,"total_committers":1,"mean_commits":231.0,"dds":0.0,"last_synced_commit":"13260f225754a7670fc8a47fe85076e320909b18"},"previous_names":["esotericpig/ekoscape"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esotericpig%2FEkoScape","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esotericpig%2FEkoScape/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esotericpig%2FEkoScape/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esotericpig%2FEkoScape/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/esotericpig","download_url":"https://codeload.github.com/esotericpig/EkoScape/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243523031,"owners_count":20304516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","3d-game","cplusplus","cpp","grid-based-movement","opengl","opengl-game","sdl","sdl2","sdl2-game","sdl2-image","sdl2-mixer"],"created_at":"2024-09-24T21:37:49.729Z","updated_at":"2025-12-29T12:55:57.520Z","avatar_url":"https://github.com/esotericpig.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EkoScape #\n\n[![EkoShot](https://github.com/user-attachments/assets/51fa9a49-e7b5-4543-b68d-e827af763cd2)](https://esotericpig.itch.io/ekoscape)\n\n[![itch.io](https://img.shields.io/badge/play-itch.io-fa5c5c)](https://esotericpig.itch.io/ekoscape)\n[![Source Code](https://img.shields.io/badge/source-github-211f1f.svg)](https://github.com/esotericpig/EkoScape)\n[![License](https://img.shields.io/github/license/esotericpig/EkoScape.svg)](LICENSE)\n\nEkoScape is a simple 3D step-based game where you run through a maze rescuing your fellow alien *Ekos*, like a 3D Pac-Man, with robot enemies, fruit, and portals. The maps are simple text files that you can edit!\n\n## Playing ##\n\nYou can play in your Web browser or download the game on [itch.io](https://esotericpig.itch.io/ekoscape).\n\nIf you choose to download, simply run it in the same folder containing the `assets` folder, or you can install \u0026 run the game from the official [itch app](https://itch.io/app) where the game has been tested to work in sandbox mode (if you're concerned about security).\n\nYou can edit the Map files in [assets/maps/](assets/maps/) or make your own! See [assets/maps/README.md](assets/maps/README.md) for more details, which also includes how to submit your Map files for the next version.\n\n### System Requirements ###\n\nWeb:\n- WebGL 2.0+ (OpenGL ES 3.0+)\n- It's recommended to turn on hardware/graphics acceleration in your browser's settings.\n\nDesktop:\n- OpenGL 2.1+\n  - Use Mesa if you have a lower version.\n- Linux x86_64 (AppImage)\n  - Might need [FUSE](https://github.com/AppImage/AppImageKit/wiki/FUSE) for running the AppImage -- usually already installed.\n- macOS arm64 or x86_64\n  - Because this game is free and signing costs money, it's currently unsigned, so you'll need to manually override the security warning when running:\n    - https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unknown-developer-mh40616/mac\n- Windows x64\n\n### Additional System Notes ###\n\n- Linux:\n  - A Desktop Entry file is provided if you wish to integrate it with your DE (Desktop Environment). Open the provided file, `io.github.esotericpig.ekoscape.desktop`, in a text editor to read more details or [read online here](https://github.com/esotericpig/EkoScape/blob/main/res/io.github.esotericpig.ekoscape.desktop).\n\n## Code History ##\n\nEkoScape is a remake of an old game I made back in 2004 (with minor edits in later years) using my friend's 3D step-based engine: The Dantares Engine by Ryan Witmer. You can find the original code in [relics/](relics/).\n\nBack then, I made it for Windows only. In 2024, I re-wrote the code for it in SDL2 (multi-platform) using modern C++20. However, it still uses The Dantares Engine and legacy OpenGL 2.1+, as homage to the original game and engine.\n\nIn the beginning, I rewrote the original code for fun in a couple of days. Having enjoyed the process, I decided to flesh it out into multiple, generic files, while adding a menu and a lot of extra stuff (such as portals, fruit, and multiple grids), which took over a month.\n\nThe code is a bit over-engineered, but I designed it so that I could use parts of it in other projects. I did make a simple ECS (Entity-Component-System) for it, but because the game is quite simple and the ECS code produced more files/lines of code, I decided to just stick with the original class-based structure.\n\nInitially, `src/cybel` was named `src/core`, but I decided to make it into its own Game Engine (kind of). I then put it in its own namespace, called `cybel`. Because of this, I simply use `using namespace cybel` inside of the `ekoscape` namespace, as I didn't like putting `cybel::` everywhere.\n\n**Update 2025-02:** I updated the game to work on the Web using Emscripten. I had to add OpenGL ES 3.0 (WebGL 2.0) support to the Renderer class and to Dantares (made a new Dantares2 class to preserve the \"original\").\n\n## Contents ##\n\n- [Hacking](#hacking)\n  - [Setup](#setup)\n  - [IDEs](#ides)\n  - [Configuring Build](#configuring-build)\n  - [Building](#building)\n  - [Running](#running)\n  - [Checking Code Quality](#checking-code-quality)\n  - [Building Linux AppImage](#building-linux-appimage)\n  - [Packaging Up](#packaging-up)\n  - [Miscellaneous](#miscellaneous)\n- [Hacking for Web](#hacking-for-web)\n  - [OpenGL ES for Desktop](#opengl-es-for-desktop)\n  - [Setup for Web](#setup-for-web)\n  - [CMake for Web](#cmake-for-web)\n  - [Misc. for Web](#misc-for-web)\n- [Releasing](#releasing)\n  - [Maps README](#maps-readme)\n  - [New Release](#new-release)\n  - [Publishing](#publishing)\n- [Credits](#credits)\n- [License](#license)\n\n## Hacking ##\n\n### Setup ###\n\nThis project uses [CMake](https://cmake.org/download/), [Ninja](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages), and [vcpkg](https://learn.microsoft.com/en-us/vcpkg/get_started/get-started). Please install these for your system.\n\n- For quickly getting started, see the [GitHub Workflows](.github/workflows/) or the top of [CMakeLists.txt](CMakeLists.txt).\n- If you have Ruby installed, there is also a script -- [scripts/dev.rb](scripts/dev.rb) -- for rapid development.\n\n### IDEs ###\n\nOptional stuff for IDEs.\n\n- **CLion**\n  - CMake Profiles are included.\n  - The env var `VCPKG_ROOT` is defaulted to `./vcpkg` so that you can just make a symlink to the actual path in the top of this project's folder, or instead, you'll need to edit the profiles (Settings =\u003e Build, Execution, Deployment =\u003e CMake) to change the env var appropriately: `VCPKG_ROOT=/path/to/vcpkg`.\n\n### Configuring Build ###\n\nPlatform-specific notes:\n- On **Linux**, OpenGL/GLEW/GLU are only façades in `vcpkg`, so you need to install them manually. Also, you might need additional system dependencies if it builds SDL2 from source.\n  - On Ubuntu, you can simply look at the [Linux GH Workflow](.github/workflows/linux.yml).\n  - https://github.com/libsdl-org/SDL/blob/SDL2/docs/README-linux.md\n  - https://github.com/AppImage/AppImageKit/wiki/FUSE\n- On **macOS**, you need to install GLEW manually:\n  - `brew install glew`\n\nThe following command will be very slow the first time you run it, as `vcpkg` downloads the dependencies. Also, it downloads \u0026 extracts additional [Assets](https://github.com/esotericpig/EkoScape/releases/tag/v1.99) to the `assets/` dir (only if `assets/images/EkoScape.png` doesn't exist).\n\n```bash\ncmake --preset default\n```\n\nOptionally, for various params, see the [GH Workflows](.github/workflows/) or the [vcpkg docs](https://learn.microsoft.com/en-us/vcpkg/users/triplets).\n\nExamples:\n\n```bash\n# Linux\ncmake --preset default \\\n      -DVCPKG_TARGET_TRIPLET=\"x64-linux\" \\\n      -DVCPKG_BUILD_TYPE=release \\\n      -DEKO_LINUXDEPLOY_ARCH=\"x86_64\" \\\n      -DEKO_PKG_SUFFIX=\"-x86_64\"\n\n# macOS\ncmake --preset default \\\n      -DBUILD_SHARED_LIBS=OFF \\\n      -DCMAKE_OSX_ARCHITECTURES=arm64 \\\n      -DVCPKG_OSX_ARCHITECTURES=arm64 \\\n      -DVCPKG_TARGET_TRIPLET=\"arm64-osx\" \\\n      -DVCPKG_CRT_LINKAGE=static \\\n      -DVCPKG_LIBRARY_LINKAGE=static \\\n      -DVCPKG_BUILD_TYPE=release \\\n      -DEKO_PKG_SUFFIX=\"-arm64\"\n\n# Windows (PowerShell)\ncmake --preset default `\n      -DBUILD_SHARED_LIBS=OFF `\n      -DVCPKG_TARGET_TRIPLET=\"x64-windows-static\" `\n      -DVCPKG_CRT_LINKAGE=static `\n      -DVCPKG_LIBRARY_LINKAGE=static `\n      -DVCPKG_BUILD_TYPE=release `\n      -DEKO_PKG_SUFFIX=\"-x64\"\n```\n\nTo see the list of `vcpkg` Triplets, you can use the unofficial-official hack:\n\n```bash\nvcpkg install sdl2 --triplet=\"\"\n```\n\n### Building ###\n\nBuild for Release or Debug:\n\n```bash\ncmake --build --preset default --config Release\ncmake --build --preset default --config Debug\n```\n\nBy default, Ninja uses the maximum number of parallel jobs for your system (which can cause your computer to run like crazy). Instead, you can use the `-j` option to use less jobs in parallel:\n\n```bash\ncmake --build --preset default --config Release -j 1\ncmake --build --preset default --config Release -j 5\n```\n\n### Running ###\n\nRun from the top-level directory (for the `assets/` folder):\n\n```bash\ncmake --build --preset default --config Release --target run\ncmake --build --preset default --config Debug --target run\n```\n\nOr run directly:\n\n```bash\n./bin/Release/EkoScape\n./bin/Debug/EkoScape\n```\n\n### Checking Code Quality ###\n\nMust have `cppcheck` installed.\n\n```bash\ncmake --build --preset default --config Release --target check\n```\n\n### Building Linux AppImage ###\n\nThis automatically downloads [linuxdeploy](https://github.com/linuxdeploy/linuxdeploy/releases/tag/continuous) to `build/downloads/` if it doesn't exist. The config is ignored and always uses the Release config.\n\n```bash\ncmake --build --preset default --config Release --target appimage\n\n# Test running it:\n./build/AppImage/EkoScape-x86_64.AppImage\n```\n\nIf your platform is not `x86_64`, you'll need to change which `linuxdeploy` to use. See the ones available [here](https://github.com/linuxdeploy/linuxdeploy/releases/tag/continuous).\n\n```bash\nrm -r build\n\n# aarch64, armhf, i386, static-x86_64, x86_64\ncmake --preset default -DEKO_LINUXDEPLOY_ARCH=aarch64\n\ncmake --build --preset default --config Release --target appimage\n```\n\n### Packaging Up ###\n\nWhen configuring, optionally add a suffix for the filename:\n\n```bash\ncmake --preset default -DEKO_PKG_SUFFIX=\"-x64\"\n```\n\nNow run the target `package`. It uses `--install` \u0026 **CPack** to package up the files.\n\n```bash\ncmake --build --preset default --config Release --target package\n```\n\n### Miscellaneous ###\n\n- Press the `R` key to refresh the graphics/maps. It also un-weirds the graphics.\n- Press the `F3` key to toggle the FPS in the top left corner. The game is capped at 60 FPS.\n- Press `Ctrl+F6` to toggle freezing the screen for screenshots.\n- There are various optional scripts in the [scripts/](scripts/) folder for development.\n\n## Hacking for Web ##\n\n### OpenGL ES for Desktop ###\n\nFor rapid testing of OpenGL ES without using the Web (slower compile/link time), simply edit the `default` preset in [CMakePresets.json](CMakePresets.json) to use GLES:\n\n```json\n{\n  \"EKO_RENDERER\": \"GLES\"\n}\n```\n\nOr, pass it in when configuring CMake using `-DEKO_RENDERER=GLES`.\n\nNow you can test OpenGL ES in the Desktop version instead.\n\n### Setup for Web ###\n\nInstall [Emscripten](https://emscripten.org/docs/getting_started/downloads.html).\n\nOn Linux/macOS, I don't recommend adding `source ./emsdk_env.sh` to your Bash/Zsh RC file because it outputs a bunch of noise every time you open a terminal. I just make sure to call it before I need it by using an alias:\n\n```bash\nalias ems_src='source \"$HOME/Code/clones/emsdk/emsdk_env.sh\"'\n```\n\nOn Windows, you need to run `emsdk_env.bat` instead.\n\nYou should now have an `EMSDK` env var, and the below file should exist, which is used in [CMakePresets.json](CMakePresets.json):\n\n```bash\nls \"$EMSDK/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake\"\n```\n\n### CMake for Web ###\n\nNow just use the CMake preset `web`, and everything should just work like normal. This preset uses separate `build_web` \u0026 `bin_web` folders than the `default` preset so that you can test both the Desktop \u0026 Web versions without having to rebuild everything when switching between them.\n\n```bash\n# Configure for Web.\ncmake --preset web\n\n# Build for Web.\ncmake --build --preset web --config Release\n# - Use 1 job instead.\ncmake --build --preset web --config Release -j 1\n\n# Run for Web [starts a server using `emrun` (Python3)].\ncmake --build --preset web --config Release --target run\n# - Or, run directly.\nemrun --no-browser bin_web/Release\n```\n\n### Misc. for Web ###\n\nBoth [scripts/dev.rb](scripts/dev.rb) and [scripts/artifacts.rb](scripts/artifacts.rb) have Web options, if you use those scripts.\n\n## Releasing ##\n\n### Maps README ###\n\nInstall the Python app [gh-md-to-html](https://github.com/phseiff/github-flavored-markdown-to-html):\n\n```bash\npip install gh-md-to-html\n```\n\nConvert the README to HTML:\n\n```bash\ncd assets/maps\ngh-md-to-html -t file -w '' -i '' -c '' -e '' -b 933px -n README2 README.md\n```\n\nDiff, merge, commit, and push.\n\n### New Release ###\n\nOptional: To update dependencies, update your `vcpkg` clone and then run `vcpkg x-update-baseline` in this project's folder. Clean any build folders and then test building \u0026 playing the game.\n\nBump the version in the following places:\n- [CMakeLists.txt](CMakeLists.txt)\n- [src/ekoscape_game.h](src/ekoscape_game.h)\n- [res/io.github.esotericpig.ekoscape.metainfo.xml](res/io.github.esotericpig.ekoscape.metainfo.xml)\n\nWith the [GitHub CLI](https://cli.github.com) (`gh`), create a new release. Make sure to change the versions appropriately (at the end):\n\n```bash\ngh release create --draft --notes \"$(git --no-pager log \"$(git describe --tags --abbrev=0)\"..HEAD --pretty=format:'- %B')\" --title v2.x v2.x\n```\n\n### Publishing ###\n\nSee [scripts/artifacts.rb](scripts/artifacts.rb) for all of your publishing needs.\n\n- On Linux, to test the Windows icon in the exe, you can use `wine explorer .` and then check it out.\n\nExample workflow:\n\n```bash\n# Use `-n` to only perform a dry-run.\n# Use `-c \u003cchannel\u003e` to filter which artifacts/channels to use (fuzzy search).\n\n# Download GitHub artifacts to `pkgs/`.\n./scripts/artifacts.rb -g\n\n# Extract (decompress) artifacts to `pkgs/`.\n./scripts/artifacts.rb -x\n\n# Validate artifact folders for itch.io.\n./scripts/artifacts.rb -v -c lin\n./scripts/artifacts.rb -v -c mac\n./scripts/artifacts.rb -v -c win\n./scripts/artifacts.rb -v -c web\n\n# Publish artifact folders to itch.io.\n./scripts/artifacts.rb -I -c lin\n./scripts/artifacts.rb -I -c mac\n./scripts/artifacts.rb -I -c win\n./scripts/artifacts.rb -I -c web\n\n# Check status of itch.io builds.\n./scripts/artifacts.rb -s\n```\n\n## Credits ##\n\n- [The Dantares Engine](third_party/Dantares/) by [Ryan Witmer](https://phasercat.com)\n- [Monogram font](https://datagoblin.itch.io/monogram) by datagoblin\n- [Star textures](https://kronbits.itch.io/particle-pack) by Kronbits\n- [Piskel](https://www.piskelapp.com) for pixel editing.\n\n## License ##\n\nDue to The Dantares Engine being licensed under GPL, I also had to license this game under GPL. However, I might extract my Cybel Engine out (doesn't depend on The Dantares Engine) and place it under a more permissive license (like LGPL or MIT), but probably no one cares to use it anyway.\n\n[GNU GPL v3+](LICENSE)\n\n\u003e EkoScape (\u003chttps://github.com/esotericpig/EkoScape\u003e)  \n\u003e Copyright (c) 2004, 2024-2025 Bradley Whited  \n\u003e \n\u003e EkoScape is free software: you can redistribute it and/or modify  \n\u003e it under the terms of the GNU General Public License as published by  \n\u003e the Free Software Foundation, either version 3 of the License, or  \n\u003e (at your option) any later version.  \n\u003e \n\u003e EkoScape is distributed in the hope that it will be useful,  \n\u003e but WITHOUT ANY WARRANTY; without even the implied warranty of  \n\u003e MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the  \n\u003e GNU General Public License for more details.  \n\u003e \n\u003e You should have received a copy of the GNU General Public License  \n\u003e along with EkoScape.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesotericpig%2Fekoscape","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesotericpig%2Fekoscape","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesotericpig%2Fekoscape/lists"}