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 2.0
A complete rewrite in a simple to use app, does more much easier than the old versions.
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.