https://github.com/jgabaut/sprites4curses

Small C library to deal with simple sprites in ncurses, with a raylib extension to reuse assets. Includes python scripts to convert png sprites to a char representation.
https://github.com/jgabaut/sprites4curses

converter ncurses raylib roguelikedev sprites spritesheet

Last synced: 6 months ago
JSON representation

Small C library to deal with simple sprites in ncurses, with a raylib extension to reuse assets. Includes python scripts to convert png sprites to a char representation.

• Host: GitHub
• URL: https://github.com/jgabaut/sprites4curses
• Owner: jgabaut
• License: gpl-3.0
• Created: 2023-02-23T15:30:53.000Z (over 3 years ago)
• Default Branch: master
• Last Pushed: 2026-01-11T02:17:16.000Z (6 months ago)
• Last Synced: 2026-01-11T07:08:38.434Z (6 months ago)
• Topics: converter, ncurses, raylib, roguelikedev, sprites, spritesheet
• Language: C
• Homepage:
• Size: 1.91 MB
• Stars: 2
• Watchers: 1
• Forks: 0
• Open Issues: 7
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE
  • Code of conduct: .github/CODE_OF_CONDUCT.md
  • Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

          
# sprites4curses

  A library of scripts and C functions to deal with sprites in ncurses.

  It also offers a seamless transition into raylib API, by providing wrapper functions to reuse assets on both graphic modes. Link to raylib repo: [link](https://github.com/raysan5/raylib)

## Table of Contents

+ [s4c.h](#s4c)

+ [s4c-animate](#s4c_animate)

  + [Prerequisites](#prerequisites_animate)

  + [A note about napms()](#napms_note)

  + [Raylib extension](#raylib_ext)

  + [Terminal capabilities](#terminal_capabilities)

  + [demo_animate.c](#demo_animate_c)

+ [s4c-gui](#s4c_gui)

+ [palette.gpl](#palette_gpl)

## s4c.h 

  This is a C library offering some `ncurses/raylib` API extensions.

  The main module is `s4c-animate`, supporting both `ncurses` and `raylib` separately.

  There's also an early stage module `s4c-gui`, supporting only `ncurses`.

## s4c-animate 

  This is a C library offering some functions to display an animation read from a formatted text file. It's rather small.

  You can look at the `demo_animate.c` program to see how you can request the animation after setup.

  Some APIs which rely on reading a file are compatible with `s4c-file` specs, see `s4c-scripts/s4c/core/sprites.py` or `s4c-scripts/s4c/core/sheet_converter.py` for info about the basic file format.

### Prerequisites 

  To use the python scripts you need to install Pillow, using `pip`:

#### `pip install Pillow`

  To produce the `Makefile` needed to compile `./demo_animate`, you will need:

  - `automake`

  - `autoconf`

  - `make`

  - `python`, to generate `./s4c-animate/palette.h` and `./s4c-animate/palette.c` from `./palette.gpl`

  To use the Raylib extension, you need to have installed `raylib`. Refer to lib docs for help: [link](https://github.com/raysan5/raylib#build-and-installation).

  - More info at [this section](#raylib_ext).

### A note about napms() 

  Some of the older APIs for `ncurses` extension come with a caveat: they are not interrupt-handler safe.

  This is due to the usage of `napms()` to wait for the requested frametime.

  If SIGINT is received by your program while waiting on a frame time, a crash will occur.

  A refactor for those APIs to avoid the active sleep could lift this limitation.

  In the meantime, you can use

  ```c

  s4c_display_sprite_at_coords(char sprites[][S4C_MAXROWS][S4C_MAXCOLS], int sprite_index, WINDOW* w, int num_frames, int frameheight, int framewidth, int startX, int startY);

  ```

  (actually a macro, defined depending on the presence of `S4C_UNCHECKED` definition), as an interrupt-safe way of doing animation.

### Raylib extension 

  To produce the Raylib `./demo_animate`, run:

  - `./configure --enable-animate-raylib=yes && make rebuild`

  In case you want to include `s4c.h` as Raylib extension in a C file, you should define these macros to make sure the included declarations work as expected:

  - `S4C_HAS_ANIMATE`

  - `S4C_RAYLIB_EXTENSION`

### Terminal capabilities 

  Since it needs support from terminal capabilities, it may return some errors if your terminal doesn't offer the needed options.

  At the moment your solution is to change terminal or help investigate your issues by forcing the check to pass, I may add an unsafe option to do this in a later version.

  You can find a doxyfile to generate documentation in `documentation`.

### demo_animate.c 

  This is a demo program showing how to use the s4c-animate module library functions. Check out its source code after running it!

  - To run the C demo program, do:

    **The demo is meant to run with the provided file, since a different-sized animation would require little tweaks to the code.**

    `autoreconf; automake --add-missing; autoreconf; automake --add-missing`

    `autoreconf; ./configure`

    `make; ./demo_animate demofile.txt`

  - To be fancy you can use process substitution in bash to give the python output (`demofile.txt`, from `sprites.py` and `sample-sprits`) directly as an argument:

    `make; ./demo_animate <( python sprites.py  )

## s4c-gui 

  This is a C library offering a small collection of curses-based UI elements.

  It's still in an early stage, but it has a minimal workable interface. It's not that big.

## palette.gpl 

  This is a GIMP palette file.

  It's used by the library to initialise the color pairs for curses to display the sprites.

  It's also useful in the first place for exporting PNG with the correct color alignment.

  You can also use it to generate a C implementation file for you color palette.

  Info on how to use it are in the [palette-README.md](./palette-README.md) file.