tsprite

Convert Sprites to Windows escape sequences, optimized for Conhost games

Features

• Outputs transparent, cursor dependent sprites
• Ample customization such as filters, character distribution, character sets (supporting unicode)
• Various optimizations / parameters for Conhost usage
• Two ways to use
  • C99 single header library for use in programs
  • CMD Tool for use in scripts or the prompt

Usage

This tool is NOT created for displaying detailed terminal art. There are many awesome tools out there that do that. Rather, this is aimed at converting small to medium sized sprites into sequences optimized for use in Conhost games, specifically Batch Script games. Printing to console repeatedly is a bottleneck in Batch Script, especially those relying on high performance such as simulations, which is exacerbated by slow VT100 sequence processing in Conhost. Therefore, this tool outputs sprites in the shortest possible sequences, with a variety of options to adjust the output.

Important : this is Windows 10+ only, for use in Conhost or Windows Terminal. List of supported image types at the top of here.

Examples

Animated Sprite + Overlay Animation

Multiple Animated Sprites + Movement

Static Sprite + Various Filters

How to Use Library

1. Download dependencies stb_image.h and stb_image_resize2.h. Include in the same directory as lib_tsprite.h.

2. Include lib_tsprite.h in your project. Like other single header libraries, define TSPRITE_IMPLEMENTATION before you include this file in one C file to create the implementation.

3. See samurai in examples

How to Use CMD Tool

1. Download above dependencies, lib_tsprite.h, and argparse. Include all .c and .h files in same directory as tsprite.c.
2. Compile tsprite.c and link together with args.c. You can use cmake, but it is also easy via the commandline. For example, with MSVC, it can be as simple as

cl tsprite.c args.c

3. See google in examples

Optimizations

• Reuse previous colour sequences if within threshold
• Aggressive transparency sequences removal, including trailing transparency
• Squash empty lines / transparent areas into single sequence
• Convert Truecolour sequences to colour index sequences if within threshold
• Two different sequence output modes suited for different use cases
• Two different display modes suited for different use cases
• Argument in cursor position sequences omitted if 1

Tool Docs

The tool is a lighter version of lib_tsprite. For list of options and descriptions, run

tsprite --help

The options and defaults are directly correlated from the library, so see below table if you need more detailed descriptions. For non-mandatory arguments, the default values for their field are also from the below table. The output is displayed from stdout. This means you can use redirect / pipe it to whatever file / console / command you need.

Library Docs

Function

enum tpaint_error tpaint_get_sequence(char const* file, struct tsprite_param* param)

file is the image you want to use. param is the list of options, or NULL if you want all defaults.

Parameters

You do not have to include all the parameters. In C99, you can specify individual members; the unspecified ones will be the default values. For example:

struct tsprite_param param = {
    .scale_x = 17,
    .scale_y = 24
};

Parameters	Description	Type	Default
adj_x	Width of output sprite	int	Entire Width
adj_y	Height of output sprite	int	Entire Height
area	Area of image to convert in the form &(struct tsprite_rect) { x, y, w, h }	Read desc	Entire image
filter	Filters image. Function pointer that filters image. Predefined are filter_greyscale, filter_invert, filter_sepia, filter_none. Custom filter requires a function of type void (*filter)(struct tsprite_col*), where the first param is the current colour	Read desc	filter_none()
str_len	Length of character set	int	1
str_set	Character set; set of characters to make up image	char const**	{ " " }
str_func	Function that determines where to put characters. Can be char_bright (brighter colours will get higher set characters), char_rand (random), and char_first (first character of set), or you can pass in your own function in the form char const* (*str_func)(struct tsprite_col, int, char const**), where the first param is the current colour, and the next are str_len and str_set	Read desc	char_first()
use_cursor_seq	If set to true, uses cursor movement sequences which is generally smaller for sprites with lots of transparency. If false, uses save cursor position sequences, which is smaller for sprites with little transparency, but will overwrite the save cursor if said sequences are being used	bool	false
disp	Type of colouring to use. One of TSPRITE_DISP_BKG (colour background) or TSPRITE_DISP_CHAR (colour characters)	Read desc	TSPRITE_DISP_BKG
col_threshold	If the distance between colours is <= this value, the colours are equal. Uses the formula here. Range is 0 to 765	float	0
equiv_threshold	Only used if equiv_type set to TSPRITE_EQUIV_THRESHOLD. If the distance between a current colour and a preset (colour index) colour is <= this value, the colours are equal. Uses the formula here. Range is 0 to 765	float	0
equiv_type	Determines mode of replacing Truecolour sequences with colour index sequences. Please note that these preset colours can be set via GUI, registry, escape sequences, ect, so tsprite assumes the default preset colours. Can be TSPRITE_EQUIV_NONE (never replace), TSPRITE_EQUIV_ALL (always replace), TSPRITE_EQUIV_THRESHOLD (replace based on equiv_type)	Read desc	TSPRITE_EQUIV_NONE
ret_str	If not NULL, puts the dynamically allocated sequence string to the pointer	char const**	NULL
ret_file	If not NULL, writes sequence to the file	char const*	NULL
append_file	Append to file if true	bool	false

Error Handling

tsprite_get_sequence() will return one of these errors.

Error	Meaning
TSPRITE_ERROR_NONE	No errors, all good!
TSPRITE_ERROR_IMAGE	Image failed to load
TSPRITE_ERROR_RESIZE	Image could not be resized
TSPRITE_ERROR_MEMORY	Cannot allocate memory for sequence
TSPRITE_ERROR_COORD	area was not in bounds
TSPRITE_ERROR_FILE	File to write cannot be opened