The Tool

Because the tool does so much more, i felt it needed more than just the tool help to explain it all, also I have fixed some bugs since its initial release, therefore we will need to keep a record of the current versions.

Current Version

Version 1.2

Removed -b binary output
Fixed The Frame number sequences now correct as repeated sprites are not counted.
Fixed The 4-bit sprite bits indicating the first and last 128 bytes
Added -n no comments in the asm output file
Added -r switch which adds x y output frame center offsets relative to the x,y center of the sprite default=0,0
Modified The text asm output allowing for negative numbers for the frame offsets offsets
Added 4-bit data into the frames output

Documentation

-h prints out the help file but this is more comprehensive

Path to the input folder

The -p switch allows you to set an input folder where your source image or images are located

Command line: -p path To Folder

Path to the output folder

The -o switch allows you to set an out folder where the exported files will be put,

Command line: -o Output Path To Folder

Warning there is no protection for overwriting files

Sequence of images

Many programs add numbers to the file name when they output multiple images, such as photoshop slices or rendering programs, so the -s switch tells the program to add numbers to the file name so we can process all the images in one batch.

Command line: -s sequence start index, sequence end index, increment step

example: -s 4,8,2 will load and process sprite0004.bmp, sprite0006.bmp and sprite0008.bmp

This 4-digit notation is default however some programs output with less digits therefore adding a 4th parameter to the command allows for different notation

Command line: -s sequence start index, sequence end index, increment step, number of digits

example: -s 4,8,2,1 will load and process sprite4.bmp, sprite6.bmp and sprite8.bmp

and if the digits parameter is 2, sprite00.bmp sprite01.bmp … sprite99.bmp etc

File name

The -f switch tells the tool the name of the file(s) to use as an input, notice there is no extension as the program will add the .bmp extension and any sequence of numbers

Command line: -f file name

Output test image

The -i switch tells the program to output a test bmp image so you can visualise the quality of the output, again no extension

Command line: -i

The image will be filename-out.bmp with filename being set with the -f switch

Sprite Sizes

The -z switch tells the tool to format the assembly output into frames, of n x n such as a 32×32 sprite will be made up of 4 sprites.

Command line: -z n

This sets both the width and height of the sprite to be n

example: -z 32 sets the sprite dimensions to 32×32 pixels

Command line: -z n0 n1

This sets the width of the sprite to n0 and the height of the sprite to be n1

example: -z 16, 48 sets the sprite dimensions to 16×48 pixels

Sprite frame center offsets

The -r switch allows you to set the x and y center of the sprite frame giving the sprite frame data offsets from, the x,y of the whole object.

Command line: -r x y

This sets an offset to the x and y position for the center of the sprite

Usage: -r 16 32

Setting the center of the sprite to 16 pixels on the x and 32 pixels on the y, this enables you to have your sprite position where you need it, such as at the players feet.

Character maps (tile maps) not tested

The -c switch should output 8×8 pixel data rather than 16×16 and like the sprites it allows you to output a block set to accompany the character data for use with tile map editors like mappy or tiled.

Command line: -c

This changes the output to 8×8 character data instead of 16×16 sprites

Command line: -c n

This will output a set of blocks n characters by n characters along with the character set

Command line: -c n0 n1

This will output a set of blocks n0 characters by n1 characters along with the character set

Notes: The maximum character size is 8×8 characters and outputting as a block set disables sequences so make sure all your characters are on the one image.

Repeated sprites

The -k switch tells the tool to keep the repeated characters or sprites, mostly you will not need this switch.

Command line: -k

Keep repeated sprite or characters

Transparency

The -t switch allows you to set the index of the transparent pixels.

Command line: -t n

The n is which colour in the palette is transparent (default 0)

Example -t 5

Tells the tool to set all the transparent pixels to colour number 5

Dither

The -d switch will make every other pixel a transparent pixel in a crosshatch pattern which may be handy for fake transparency.

Command line: -d

Palettes

There are a few switches that are related to palettes and colours.

Write out a palette file

The -w switch allows you to save the palette as a file for loading and mapping different images to

Command line: -w filename

This will save the palette as a binary file, the format of this file is :-

            word number of colours used
            byte red, byte green, byte blue .....

Generate a palette file

The -g switch tells the tool to generate a pallet from the command line

Command line: -g RRGGBB,RRGGBB,RRGGBB,RRGGBB…

This will generate a palette from RGB values as a string

Example -g FF00FF,FCD8FC,242448,48486C,6C6C90,9090B4,002400,484824

This will generate a palette of 8 colours

Important, this palette is on memory only, so the best thing to do is use this with the -w switch, which will save the generated palette to a .pal file for loading later

Load a palette file

The -l switch tells the tool to load a palette from a file. There are two file formats the tool understands, the first being the .pal file format and the other being the photoshop .act file format.

Command line: -l filename.pal

Loads a binary.pal palette file as per the -w

Command line: -l filename. act

loads a binary.act palette file from photoshop

Mapping the palette

The -m command allows you to map your graphics to other palettes, such as the spectrum next palettes or a pre-loaded palette

Command line: -m 8

Maps the graphics to the Spectrum Next 8-bit palette

Command line: -m 9

Maps the graphics to the Spectrum Next 9-bit palette

Command line: -m 0

Maps the graphics to a loaded .pal or .act file

Sine and cosines

The -j switch will output a fixed point (2.6) sine and cosine tables along with a z80 sine and cosine functions

Command line: -j

Generate a fixed-point sine table then exit (256 angles)

Note: this must be used with the -o output path switch or you will see nothing

Example -j -o path

Notice there are only 256 angles, this is to make programming easier as the angle fits in a byte rather than over two bytes!

Assembly

The -a switch will tell the tool to output an assembly file containing the sprite data so it can be included into the source build of your code. You can also add a % after the switch to make the output of the palette data as binary.

Command line: -a

Outputs an assembly file is something like this:-

   // Created on Thursday, 08 October 2020 @ 06:52:29 by the NEXT tool from
// patricia curtis at luckyredfish dot com
// Sprites mapped to the loaded palette

myspriteColours:	equ	16

//			 RRRGGGBB
myspritePalette:	db	%11100011		// Colour 00 is $e3 = 255,0,255
		db	%10000000		// Colour 01 is $80 = 153,0,0
		db	%00000000		// Colour 02 is $00 = 0,0,0
		db	%11001000		// Colour 03 is $c8 = 226,88,61

		
myspriteFrameCount:	equ	15
		//	xCount,yCount,    [xOffset,yOffset,4-bit, spriteIndex]    [repeated n sprites]
frame0:	.db	2,2,		-16,-16,128,0,		0,-16,192,1,		-16,0,128,2,
frame1:	.db	2,2,		-16,-16,128,0,		0,-16,192,1,		-16,0,128,4,


myspriteFrames:	.dw	myspriteFrame0,myspriteFrame1,myspriteFrame2,myspriteFrame3,myspriteFrame4,....

// 4-bit colour Sprites

myspriteSprites:	equ	39

//mysprite0 is from frame 0 at position x=0  y=0
mysprite0:		.db	$00,$00,$00,$00,$00,$00,$00,$00
		.db	$00,$00,$00,$00,$00,$00,$00,$99
		.db	$00,$00,$00,$00,$00,$90,$09,$92
		.db	$00,$00,$00,$00,$00,$92,$9e,$62
		.db	$00,$00,$00,$00,$09,$92,$ee,$62
		.db	$00,$00,$00,$09,$9a,$bb,$bb,$bd
		.db	$00,$00,$00,$ad,$bb,$bb,$bb,$bb
		.db	$00,$00,$aa,$db,$bb,$bb,$bb,$bb
		.db	$00,$0a,$db,$bb,$cc,$cc,$cc,$cc
		.db	$00,$02,$bb,$cc,$cc,$cc,$cc,$cc
		.db	$00,$88,$5c,$cc,$cc,$44,$44,$cd
		.db	$02,$85,$55,$cc,$44,$44,$44,$4c
		.db	$08,$55,$5f,$c4,$44,$99,$94,$44
		.db	$08,$55,$5f,$f4,$44,$66,$64,$44
		.db	$28,$55,$5f,$f4,$44,$99,$9c,$46
		.db	$25,$55,$5f,$fc,$44,$22,$26,$6a

//mysprite1 is from frame 0 at position x=16  y=0
mysprite1:		.db	$00,$00,$00,$00,$00,$00,$00,$00
		.db	$00,$29,$20,$00,$00,$00,$00,$00
		.db	$99,$29,$00,$00,$00,$00,$00,$00
		.db	$ee,$69,$00,$00,$00,$00,$00,$00
		.db	$ee,$92,$00,$00,$00,$00,$00,$00
		.db	$e2,$90,$00,$00,$00,$88,$00,$00
		.db	$bb,$a0,$00,$00,$08,$58,$00,$00
		.db	$bb,$da,$a0,$00,$85,$f6,$90,$00
		.db	$cb,$bb,$da,$a0,$84,$46,$88,$00
		.db	$cc,$cb,$bb,$da,$64,$ca,$58,$00
		.db	$dd,$dc,$bb,$44,$4c,$28,$58,$20
		.db	$cc,$bd,$ab,$44,$6a,$aa,$22,$00
		.db	$44,$cd,$ac,$bb,$bb,$a0,$08,$88
		.db	$44,$cd,$a2,$bb,$bb,$a8,$85,$58
		.db	$66,$9d,$a2,$bb,$bb,$d5,$ff,$f9
		.db	$aa,$aa,$aa,$db,$44,$44,$c4,$4f

//mysprite2 is a repeat of mysprite1 from frame 1 at position x=48  y=0
//mysprite3 is a repeat of mysprite2 from frame 2 at position x=64  y=0

//mysprite12 is from frame 6 at position x=192  y=0

//mysprite57 is a empty (transparent colour) therefore not outputted
//mysprite57 is a empty (transparent colour) therefore not outputted

Binary output (not tested)

The -b switch should output a binary file containing most of the same data as the assembly file.

Command line: -b

Format of file

byte num colours used 0 means no palette (mapped to spectrum next palette)
1 byte for each colour in RRRGGGBB format
byte for the number of frames in the animation
bytes xCount, yCount,[ xOffset, yOffset ,spriteIndex][repeated n sprites in frame]
repeat n frames byte for the number of sprites or characters (-c switch)
bytes for each 16×16 sprite (256 bytes) or 8×8 character (64 bytes)
byte number of blocks, zero if no block data in file
byte block width in characters
byte block height in characters
bytes for each block width * height bytes

As I say it has not been tested to there is no guarantee at this point so I would stick with the asm output for now.