SDL Version of crisp-game-lib-portable

This is a repo containing sdl ports of the crisp games library which is a Minimal C-lang library for creating classic arcade-like mini-games running on devices and browsers. Re-implemented version of crisp-game-lib for smaller devices. You can play sample games in your browser.

10/05/2025: an updated playdate version is available in release section

see src/cglpSDL1 for SDL 1 Port

• keyboard or mouse only
• Sound support
• Extra added games
• Sections inside the menu's
• Ability to have more than 16 games in the menu
• Ability to switch between dark color mode enabled or not
• Overlays like small glow effects, pixel grid or crt effect saved per game
• HiScore saving
• Funkey version is based on this version

see src/cglpSDL2 for SDL 2 Port

• keyboard, mouse or gamepads support using Gamecontroller Api
• Sound support
• Extra added games
• Sections inside the menu's
• Ability to have more than 16 games in the menu
• Ability to switch between dark color mode enabled or not
• Ability to switch between dark color mode enabled or not
• Overlays like small glow effects, pixel grid or crt effect saved per game
• HiScore saving
• Works on many chinese emulation handhelds if you crosscompile (rg35xx sp, rg35xx plus, trimui smart pro, rgb30, ..)

see src/cglpSDL3 for SDL 3 Port

• keyboard, mouse or gamepads support using Gamepad Api
• Sound support
• Extra added games
• Sections inside the menu's
• Ability to have more than 16 games in the menu
• Ability to switch between dark color mode enabled or not
• Ability to switch between dark color mode enabled or not
• Overlays like small glow effects, pixel grid or crt effect saved per game
• HiScore saving

Prebuild versions of the SDL2 and SDL3 port are available in the release Section.

Controls:

• Keyboard Controls: X, C, S, D, G, ESC, PageUp, PageDown and arrow keys
• Game Pad (XBox) Controls: A, B, X, Y, Start, Back, LB, RB and Joystick or dpad

Commandline parameters:

Usage: CglpSDL3.exe [-w <WIDTH>] [-h <HEIGHT>] [-f] [-ns] [-a] [-fps] [-nd] [-g <GAMENAME>] [-ms] [-cgl] [-nsd] [CGL file]

Commands:

• -f: Run fullscreen windowed (desktop resolution)
• -w XXX: use window width XXX
• -h YYY: use window height YYY
• -ns: no sound
• -a: use accelerated renderer (by default software renderer is used)
• -fps: show fps
• -nd: no fps delay (run as fast as possible)
• -list: List game names to be used with -g option
• -g <GAMENAME>: run game only
• -ms: Make screenshot of every game
• -cgl: create fake .cgl rom files which can be used as a parameter to launch the games
• -nsd: No scaled drawing (scales the view, instead of drawing scaled, is faster but disables overlays, glow etc)
• CGL file: Pass a .cgl file to launch a game directly

Windows Prebuild Versions

Windows versions will run fine on any recent os and SDL2 library is baked in, what will not work is running the x64 versions on a 32bit os but 32bit versions are available for download as well

Mac Prebuild Versions and gatekeeper

Macos prebuild binaries are now available as well for different os and architecture versions and contain the sdl2 lib in the binary. Generally speaking binaries build on older versions of macos will run fine on a newer macos if you keep using same architecture but not the other way around. I personally tested the mac os intel builds (not arm ones) on mac os sequoia 15.2 i did not test the arm versions. However due to apple requiring signed and notarized binaries, macos will probably prevent you from running the app bundle directly and display a message like in the screenshot below

If this happens you need to go to system settings in the privacy and security section and scroll all the way down, there will be an entry there where you can unblock it as you can see in screenshot below

once you click allow it will show a new dialog where you choose to open the binary, but you may have to provide the administrator password.

once you have done this a single time it won't ask about this again.

(Ubuntu) Linux Prebuild Versions

Linux prebuild versions are only available for ubuntu flavor os'es and contain sdl2 in the binary already so you don't need to deal with apt normally. However since there are only ubuntu runners on github i can not provide binaries for other os'es and the prebuild ones for ubuntu might not work on other os'es. You will just have to build them manually then from source which is not that hard. (More info below). Generally speaking binaries build on older versions of an os will run fine on a newer os but not the other way around. I did not test the Arm versions of the binaries

Target devices

• M5StickC PLUS
• M5Stack BASIC
• Playdate (Download crisp-games.pdx.zip and sideload a game.)
• Adafruit PyBadge
• Arduboy
• ESP32-2432S028R
• ESPboy
• Funkey
• RG Nano
• SDL 1, 2 or 3 supported device

Sample game codes and reference

• Sample game codes
• Reference
  • Functions and variables
  • Structs and macros
  • 2d vector functions (macros)

How to write your own game

1. Copy game_Template.c to game[your game name].c

2. Comment out other games in menuGameList.c and add void addGame[your game name](); and addGame[your game name]()

   ...(snip)...
   void addGameReflector();
   void addGame[your game name]();
   
   void addGames() {
     /*addGameThunder();
     ...(snip)...
     addGameReflector();*/
     addGame[your game name]();
   }
   

3. Write your own game in game[your game name].c and rename void addGame_Template() { to void addGame[your game name]() {

4. Build for browser and debug

5. Once the game is complete, revert other games that were commented out in menuGameList.c and build it for other devices

Build for [target device]

M5StickCPlus, M5Stack, PyBadge

1. Install LovyanGFX library

2. Create cglp[target device]/ directory (e.g. cglpM5StickCPlus/)

3. Copy cglp[target device].ino, ./src/lib/* and ./src/games/* files to the directory

   • cglpM5StickCPlus.ino
   • cglpM5Stack.ino (ported by OBONO)
   • cglpPyBadge.ino

4. Verify and upload cglp[target device].ino with Arduino IDE

Playdate

1. Copy ./src/cglpPlaydate directory

2. Create cglpPlaydate/build directory

3. Move to cglpPlaydate/build directory and cmake ..

4. Open crisp-game-lib-portable.sln with Visual Studio

5. Build the solution (see Building for the Simulator using Visual Studio)

6. See also Building for the Playdate using NMake

Arduboy

Note: Some features are limited due to device resource limitations.

• crisp-game-lib-arduboy (ported by OBONO)

ESP32-2432S028R

• cglp-dentaroUI (ported by dentaro)

ESPboy

• cglpESPboy (ported by ESPboy)

Funkey or RG-Nano

• cglpFunkey (ported by Joyrider3774)

Any Device supporting SDL1, SDL2 or SDL3

1. (Cross)compile using provided Makefile by running make -f ./src/cglpSDL2/Makefile or make -f ./src/cglpSDL1/Makefile in rootfolder of this repo or use the CMake with the provided src/cglpSDL2/CMakelists or src/cglpSDL3/CMakelists file

2. Checkout binary --help for information on commandline parameters

• SDL2 & 3 port supports game controllers SDL1 port only keyboard

• ported by Joyrider3774

Browser

1. Install Emscripten

2. Run dev npm script to start the dev server and watch js files

3. Run dev_c npm script to watch c files and build wasm files

How to operate

Back to the game selection menu

• Hold down the A button and press the B button (M5StickCPlus, M5Stack)
• Press the SELECT button (PyBadge)
• Press A, B, Up and Right buttons simultaneously (Playdate)
• Press the X key while holding down the up and down arrow keys (Browser)
• Press ESC on SDL Ports

Toggle sound on/off

• Press the B button (M5StickCPlus)
• Press the C Button (M5Stack)
• Press the START button (PyBadge)
• Press the Z key while holding down the up and down arrow keys (Browser)

Key assignment on SDL Ports

• (A) X key, (B) C key, (left/right/up/down) arrow keys

Key assignment on browser

• (A) X key, (B) Z key, (left/right/up/down) arrow keys

How to port the library to other devices

The source codes for library and games are written device-independent. Besides, you need to implement device-dependent code for the following functions:

• Device initialization function (e.g. setup() in Arduino) that calls initGame()

• Frame update function (e.g. loop() in Arduino) that calls setButtonState() and updateFrame()

  • The state of the button press must be notified to the library with the setButtonState()

• Drawing and audio processing functions that are defined in machineDependent.h

  • md_getAudioTime() function should return the audio timer value in seconds
  • md_playTone(float freq, float duration, float when) function should play a tone with freq frequency, duration length (in seconds) and staring from when seconds on the audio timer
  • md_drawCharacter(unsigned char grid[CHARACTER_HEIGHT][CHARACTER_WIDTH][3], float x, float y, int hash) function should draw the pixel art defined by grid[y][x][r, g, b] at position (x, y). Since hash will be the same for the same pixel art, you can cache pixel art images using hash as an index and avoid redrawing the same image

Sample device-dependent codes are cglpM5StickCPlus.ino and cglpPyBadge.ino.

Porting games from crisp-game-lib using an AI chatbot

You can use an AI chatbot to port game source code for crisp-game-lib to crisp-game-lib-portable. By providing the prompt and set of files to the chatbot, you can obtain the code ported to the C language. I have tried this using Claude 3 Opus, but it is expected to work to some extent with other LLMs as well. The ported code is not perfect, so it needs to be manually checked and corrected.