@city41/gba-convertpng 0.0.3 → 0.0.5

package/README.md

@@ -2,7 +2,170 @@
 
 This is a nodejs based tool for converting png images to the tile data format used in GBA games.
 
-HEADS UP: I make games for the e-Reader, and so far have not done mainstream GBA development. So possibly this tool is missing things for GBA dev. If so, please let me know.
+**HEADS UP #1:** I make games for the e-Reader, and so far have not done mainstream GBA development. So possibly this tool is missing things for GBA dev. If so, please let me know.
+
+**HEADS UP #2:** This is a very simple tool that can only do a few simple things. If you want a lot of control over your graphics, you probably want to use [Grit](https://www.coranac.com/man/grit/html/grit.htm). Maybe someday convertpng will expand enough to be a good alternative to Grit.
+
+## Installation
+
+Make sure you have a recent version of [nodejs](https://nodejs.org/en) installed.
+
+```bash
+npm install -g @city41/gba-convertpng
+or
+yarn global add @city41/gba-convertpng
+```
+
+## Usage
+
+`convertpng` runs off a json spec file.
+
+```bash
+gba-convertpng myGBAResources.json
+```
+
+This json file provides everything that is needed to convert pngs to GBA data. Here is an example
+
+```json
+{
+  "outputDir": "./output",
+  "sprites": [
+    {
+      "file": "cursor.png",
+      "frames": 2
+    }
+  ],
+  "backgrounds": [
+    {
+      "file": "myBg.png"
+    }
+  ]
+}
+```
+
+This is about as simple as the spec file gets. It will load up `cursor.png` and `myBg.png` and convert them into tile data for the asz80 assembler in files `cursor.tiles.asm`, `cursor.palette.asm`, `myBg.tiles.asm`, `myBg.palette.asm` and `myBg.map.asm`.
+
+And for example, `cursor.palette.asm` looks like this
+
+```asm
+.dw 0x7c1f,0x28c4,0x7fff,0x76d2,0,0,0,0,0,0,0,0,0,0,0,0
+```
+
+Ideal for dropping into a game that uses the asz80 assembler.
+
+## File paths
+
+All of the image paths specified in the json spec are relative to the spec file. So in the above example, the pngs would be in the same directory as the spec file.
+
+The same is true for `outputDir`, this is a directory path relative to the json spec file. This directory must exist.
+
+## Other source code formats
+
+At the root of the json spec you can add `format` to specify C or pyz80 output.
+
+### C output
+
+```json
+{
+  "outputDir": "./output",
+  "format": "C",
+  "sprites": [
+    ...
+```
+
+C output is a standard C array, either bytes (tile data) or words (palettes). For example with the above json spec, the C output for the cursor palette would be `cursor.palette.c.inc`, and the contents would be
+
+```C
+{ 0x7c1f,0x28c4,0x7fff,0x76d2,0,0,0,0,0,0,0,0,0,0,0,0 }
+```
+
+The idea is to include it into your C source using the preprocessor, something like:
+
+```C
+const u8 cursorTiles[] =
+#include "cursor.tiles.c.inc"
+;
+const u16 cursorPalette[] =
+#include "cursor.palette.c.inc"
+;
+```
+
+(I do almost no C development, so the C output might not be ideal. Let me know if you have any ideas here.)
+
+### pyz80 output
+
+```json
+{
+  "outputDir": "./output",
+  "format": "pyz80",
+  "sprites": [
+    ...
+```
+
+If you specify "pyz80" as the `format`, the output will look like this, for example `cursor.palette.asm`
+
+```asm
+dw 0x7c1f,0x28c4,0x7fff,0x76d2,0,0,0,0,0,0,0,0,0,0,0,0
+```
+
+The only difference from asz80 is the lack of the leading period.
+
+## Other options
+
+## Sprite frames
+
+All sprite entries must specify how many frames of animation are contained within the png. Each frame should be horizontally laid out within the image.
+
+For example this png is a sprite that has four frames of animation
+
+![sprite with four frames](https://github.com/city41/gba-convertpng/blob/main/multipleFramesExample.png?raw=true)
+
+Even if a sprite just has a single frame of animation, then `"frames": 1` still needs to be specified.
+
+### shared palette
+
+A group of sprites can share a palette like this
+
+```json
+{
+  "outputDir": "./output",
+  "sprites": [
+    {
+      "sharedPalette": [
+        {
+          "file": "cursor.png",
+          "frames": 2
+        },
+        {
+          "file": "enemy.png",
+          "frames": 1
+        }
+      ],
+      "name": "global"
+    }
+  ]
+}
+```
+
+In this case convert-png will combine the colors of both sprites into a single 15 color palette, and output it as `global.shared.palette.[asm|c.inc]`, the tile output files for the sprites will be the same as before.
+
+## Trim palette
+
+You can add `"trimPalette": true` to any sprite or background. With this specified, the palette output data will only be as big as needed. For example the palette above with all the trailing zeros becomes this
+
+```asm
+.dw 0x7c1f,0x28c4,0x7fff,0x76d2
+```
+
+## Force palette
+
+Normally convertpng will examine the pngs and figure out an optimal palette. If you need your data to conform to an existing palette, specify it with `"forcePalette": "<palette-file>"`
+
+This should be a png image that is 15x1, each pixel being a color in the palette.
+
+With forced palettes, imagemagick will be used to push the png files to match this palette. If you create the pngs using that palette, this won't cause any changes. But if you don't, you might be surprised how much your sprite has changed.
+
+With a forced palette, the color indexes within the forced palette will be honored. So if within your palette you have a red at index 1, then the tile data for the sprites/backgrounds will be 1 whenever that red pixel is needed.
 
 ## Publishing
 

package/dist/asm.d.ts

@@ -1,2 +1,3 @@
-declare function toAsm(data: number[], width: "b" | "w", numbersPerRow: number): string;
+import { Format } from "./types";
+declare function toAsm(data: number[], width: "b" | "w", numbersPerRow: number, format: Format): string;
 export { toAsm };

package/dist/asm.js

@@ -2,18 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toAsm = toAsm;
 const toHex_1 = require("./toHex");
-function toAsm(data, width, numbersPerRow) {
+function toAsm(data, width, numbersPerRow, format) {
+    if (format !== "asz80" && format !== "z80" && format !== "pyz80") {
+        throw new Error(`toAsm: given an incompatible format (${format})`);
+    }
     const hexFn = width === "b" ? toHex_1.toHexByte : toHex_1.toHexWord;
+    const dPrefix = format === "pyz80" ? "" : ".";
     const rows = [];
     let row = [];
     for (let i = 0; i < data.length; ++i) {
         if (row.length === numbersPerRow) {
-            rows.push(` .d${width} ${row.join(",")}`);
+            rows.push(` ${dPrefix}d${width} ${row.join(",")}`);
             row = [];
         }
         row.push(hexFn(data[i]));
     }
-    rows.push(` .d${width} ${row.join(",")}`);
+    rows.push(` ${dPrefix}d${width} ${row.join(",")}`);
     return rows.join("\r\n") + "\r\n";
 }
 //# sourceMappingURL=asm.js.map

package/dist/background.d.ts

@@ -1,8 +1,8 @@
-import { BackgroundSpec } from "./types";
+import { BackgroundSpec, Format } from "./types";
 type ProcessBackgroundResult = {
     tilesAsmSrc: string;
     paletteAsmSrc: string;
     mapAsmSrc: string;
 };
-declare function processBackground(bg: BackgroundSpec): Promise<ProcessBackgroundResult>;
+declare function processBackground(bg: BackgroundSpec, format: Format): Promise<ProcessBackgroundResult>;
 export { processBackground };

package/dist/background.js

@@ -9,6 +9,7 @@ const canvas_1 = require("./canvas");
 const palette_1 = require("./palette");
 const tile_1 = require("./tile");
 const isEqual_1 = __importDefault(require("lodash/isEqual"));
+const c_1 = require("./c");
 function extractMap(allTilesThatFormImage, dedupedTiles) {
     const map = [];
     allTilesThatFormImage.forEach((tile, i) => {
@@ -22,16 +23,17 @@ function extractMap(allTilesThatFormImage, dedupedTiles) {
     });
     return map;
 }
-async function processBackground(bg) {
+async function processBackground(bg, format) {
     const canvas = await (0, canvas_1.reduceColors)(await (0, canvas_1.createCanvasFromPath)(bg.file), 16);
     const palette = (0, palette_1.extractPalette)(canvas, !bg.trimPalette);
     const allTilesThatFormImage = (0, tile_1.extractTiles)(canvas, palette, 1);
     const dedupedTiles = (0, tile_1.dedupeTiles)(allTilesThatFormImage);
     const map = extractMap(allTilesThatFormImage, dedupedTiles);
+    const toSrcFun = format === "C" ? c_1.toC : asm_1.toAsm;
     return {
-        tilesAsmSrc: (0, asm_1.toAsm)(dedupedTiles.flat(1), "b", 4),
-        paletteAsmSrc: (0, asm_1.toAsm)(palette, "w", 4),
-        mapAsmSrc: (0, asm_1.toAsm)(map, "w", 8),
+        tilesAsmSrc: toSrcFun(dedupedTiles.flat(1), "b", 4, format),
+        paletteAsmSrc: toSrcFun(palette, "w", 4, format),
+        mapAsmSrc: toSrcFun(map, "w", 8, format),
     };
 }
 //# sourceMappingURL=background.js.map

package/dist/c.d.ts

@@ -1,2 +1,3 @@
-declare function toC(data: number[], width: "b" | "w", numbersPerRow: number): string;
+import { Format } from "./types";
+declare function toC(data: number[], width: "b" | "w", numbersPerRow: number, format: Format): string;
 export { toC };

package/dist/c.js

@@ -2,7 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toC = toC;
 const toHex_1 = require("./toHex");
-function toC(data, width, numbersPerRow) {
+function toC(data, width, numbersPerRow, format) {
+    if (format !== "C") {
+        throw new Error(`toC: given an incompatible format (${format})`);
+    }
     const hexFn = width === "b" ? toHex_1.toHexByte : toHex_1.toHexWord;
     const rows = [];
     let row = [];

package/dist/main.js

@@ -82,11 +82,18 @@ function hydrateJsonSpec(jsonSpecPath) {
         }),
     };
 }
+const formatToExt = {
+    C: "c.inc",
+    asz80: "asm",
+    z80: "asm",
+    pyz80: "asm",
+    bin: "bin",
+};
 async function main(jsonSpec) {
     if (jsonSpec.format === "bin") {
         throw new Error("convertpng does not support bin format");
     }
-    const ext = jsonSpec.format === "z80" ? "asm" : "c.inc";
+    const ext = formatToExt[jsonSpec.format];
     for (const sprite of jsonSpec.sprites) {
         const processResult = await (0, sprite_1.processSprite)(sprite, jsonSpec.format, sprite.forcePalette);
         if ((0, sprite_1.isBasicSpriteSpec)(sprite)) {
@@ -112,7 +119,7 @@ async function main(jsonSpec) {
         }
     }
     for (const bg of jsonSpec.backgrounds) {
-        const processResult = await (0, background_1.processBackground)(bg);
+        const processResult = await (0, background_1.processBackground)(bg, jsonSpec.format);
         const fileRoot = path.basename(bg.file, path.extname(bg.file));
         const tilesAsmPath = path.resolve(jsonSpec.outputDir, `${fileRoot}.tiles.asm`);
         const paletteAsmPath = path.resolve(jsonSpec.outputDir, `${fileRoot}.palette.asm`);

package/dist/sprite.js

@@ -28,12 +28,14 @@ async function processBasicSprite(sprite, format, forcedPalette) {
             paletteSrc: palette,
         };
     }
-    const tileSrcFun = format === "z80" ? asm_1.toAsm : c_1.toC;
-    const paletteSrcFun = format === "z80" ? asm_1.toAsm : c_1.toC;
+    const toSrcFun = format === "C" ? c_1.toC : asm_1.toAsm;
+    if (typeof sprite.transparentColor === "number") {
+        palette[0] = sprite.transparentColor;
+    }
     return {
         canvas,
-        tilesSrc: [tileSrcFun(tiles, "b", 4)],
-        paletteSrc: paletteSrcFun(palette, "w", 4),
+        tilesSrc: [toSrcFun(tiles, "b", 4, format)],
+        paletteSrc: toSrcFun(palette, "w", 4, format),
     };
 }
 async function processSharedPaletteSprites(sharedPaletteSprite, format, forcedPalette) {
@@ -55,14 +57,16 @@ async function processSharedPaletteSprites(sharedPaletteSprite, format, forcedPa
         const t = (0, tile_1.extractTiles)(canvases[i], commonPalette, sharedPaletteSprite.sharedPalette[i].frames).flat(1);
         tiles.push(t);
     }
-    const tileSrcFun = format === "z80" ? asm_1.toAsm : c_1.toC;
-    const paletteSrcFun = format === "z80" ? asm_1.toAsm : c_1.toC;
+    const toSrcFun = format === "C" ? c_1.toC : asm_1.toAsm;
+    if (typeof sharedPaletteSprite.transparentColor === "number") {
+        commonPalette[0] = sharedPaletteSprite.transparentColor;
+    }
     return {
         // this is useless in this scenario, but canvas
         // really only exists for the puzzle generator
         canvas: canvases[0],
-        tilesSrc: tiles.map((t) => tileSrcFun(t, "b", 4)),
-        paletteSrc: paletteSrcFun(commonPalette, "w", 4),
+        tilesSrc: tiles.map((t) => toSrcFun(t, "b", 4, format)),
+        paletteSrc: toSrcFun(commonPalette, "w", 4, format),
     };
 }
 async function processSprite(sprite, format, forcedPalettePath) {

package/dist/types.d.ts

@@ -1,15 +1,17 @@
-export type Format = "C" | "z80" | "bin";
+export type Format = "C" | "z80" | "pyz80" | "asz80" | "bin";
 export type BasicSpriteSpec = {
     file: string;
     frames: number;
     trimPalette?: boolean;
     forcePalette?: string;
+    transparentColor?: number;
 };
 export type SharedPaletteSpriteSpec = {
     name: string;
     trimPalette?: boolean;
     sharedPalette: BasicSpriteSpec[];
     forcePalette?: string;
+    transparentColor?: number;
 };
 export type SpriteSpec = BasicSpriteSpec | SharedPaletteSpriteSpec;
 export type BackgroundSpec = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@city41/gba-convertpng",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Converts png images to GBA tile format",
   "main": "index.js",
   "repository": "github.com/city41/gba-convertpng",