CHGame 0.3.0
Libraries for the CHGame handheld
Loading...
Searching...
No Matches
CHGame API reference

The reference for every library the CHGame board package installs. CHGame is a small open colour handheld: a WCH CH32X035 RISC-V microcontroller (48 MHz, 62 KB flash, 20 KB SRAM), a 128x128 ST7735S colour LCD, a microSD slot, eight buttons, a piezo speaker, a status LED and USB-C. It is programmed from the Arduino IDE or arduino-cli, like an Arduboy.

The libraries

Library Header What it is for
CHGame CHGame.h Start here. Everything a game needs: buttons and frame pacing, the house palette, drawing helpers and the 3x5 font, outlined lettering, effects maths, particles, sound and music, saving to flash, number formatting, and the debug protocol the simulator drives a game through. Includes CHGfx.
CHGfx CHGfx.h The screen: a 16-colour framebuffer sent to the panel by DMA at up to 119 fps, sprites, shapes, text and fonts, partial updates and full-colour streaming.
CHSd SdSpi.h, Fat.h Reading files from the microSD card (FAT16/FAT32, read-only).
SPI, Wire, EEPROM SPI.h, Wire.h, EEPROM.h The standard Arduino libraries, ported to the chip.

A first sketch

#include <CHGame.h>
void setup() {
chgame.boot(); // buttons; START held 3 s goes back to the menu
gfx_begin(GFX_DIV2, GFX_12BPP); // the panel: 128x128, 16 colours on screen
pal::init(); // the house colours (INK, WHITE, FELT, GOLD ...)
chgame.setFrameRate(60);
}
void loop() {
if (!chgame.nextFrame()) return; // 60 times a second
chgame.pollButtons();
// ... game logic: chgame.pressed(LEFT_BUTTON), chgame.justPressed(A_BUTTON) ...
pal::tick();
gfx_wait(); // the last frame has gone out: draw the next
pal::commit();
gfx_clear(FELT);
text35x2s(10, 9, "HELLO", WHITE);
gfx_flushAsync(); // sent by DMA while the next frame's logic runs
}
CHGame.h
The one include for a CHGame sketch.
CHGame::nextFrame
bool nextFrame()
Whether it is time for the next frame.
CHGame::pollButtons
void pollButtons()
Take this frame's snapshot of the buttons.
CHGame::boot
void boot()
Set up the button pins (inputs with pull-ups) and take a first reading.
CHGame::setFrameRate
void setFrameRate(uint8_t fps)
Set the frame rate nextFrame() paces to.
text35x2s
void text35x2s(int x, int y, const char *str, uint8_t c, uint8_t shade=0)
text35x2() over its own shade a pixel down and right.
chgame
CHGame chgame
The one instance: chgame.boot(), chgame.pressed() ...
WHITE
@ WHITE
1: white (0xFFF).
Definition Palette.h:43
FELT
@ FELT
3: the table felt; re-dyed by pal::setTheme().
Definition Palette.h:45
GFX_DIV2
@ GFX_DIV2
HCLK/2 = 24 MHz: the fastest the chip can clock SPI, and the default.
Definition CHGfx.h:232
GFX_12BPP
@ GFX_12BPP
ST7735 COLMOD 0x03, RGB444, 1.5 bytes/px -> 119 fps.
Definition CHGfx.h:220
gfx_clear
void gfx_clear(uint8_t c)
Fills the clip rectangle (normally the whole screen) with one colour.
gfx_flushAsync
void gfx_flushAsync(void)
Starts sending the whole framebuffer and returns at once; the DMA interrupt does the rest.
gfx_wait
void gfx_wait(void)
Waits until the flush in flight, if any, has finished.
gfx_begin
static void gfx_begin(uint8_t spiDiv=GFX_DIV2, uint8_t colorMode=GFX_16BPP)
Starts the panel: pins, SPI1, DMA, a hardware reset and the ST7735 initialisation,...
Definition CHGfx.h:308
pal::tick
void tick()
Advance the colour cycling and any flash by one tick.
pal::commit
void commit()
Work out the final colours and hand them to CHGfx if any changed.
pal::init
void init(const uint16_t *base=HOUSE)
Load a set of colours and commit them at once.

examples/Hello adds a sound effect and a counter saved in flash. The twenty casino games under File > Examples > CHGame > Games are complete programs built on the same loop.

Finding your way

  • Topics (above) lists each library's parts: for CHGame, the buttons, the palette, drawing, sound, saving and so on, each with an overview and every call it offers.
  • Classes, Namespaces and Files index the same things by name: the chgame object is a CHGame, the palette calls are in pal::, sound in audio::, saving in save::.
  • Examples has the Hello sketch and CHGfx's examples.
  • The search box (top right) finds any function, constant or type.

Coming from the Arduboy?

The CHGame library is modelled on Arduboy2: one global object with the same button names (A_BUTTON, UP_BUTTON ...), nextFrame(), pollButtons(), pressed(), justPressed() and everyXFrames(). The differences: the screen is 128x128 in 16 colours chosen from 4096, drawing is CHGfx's gfx_* calls, and a frame is sent with gfx_flushAsync() instead of display(). Getting started maps Arduboy2 calls to CHGame's one by one.

More