@bscotch/sprite-source 1.4.0

package/LICENSE.md

@@ -0,0 +1,29 @@
+# License for the Stitch Monorepo
+
+License information for the content of this git repository. The various packages in this repo are developed by [Butterscotch Shenanigans](https://www.bscotch.net) ("Bscotch").
+
+## License files
+
+Whenever a `LICENSE` file is found in a folder, or a license is specified by a `package.json` or similar manifest file, that license takes precedence for all files in that folder and its subfolders.
+
+This is the root-most `LICENSE` file, and therefore dictates the default licensing in this repository.
+
+## Stitch name and logo
+
+![Stitch Logo](https://img.bscotch.net/fit-in/256x256/logos/stitch.png "The Stitch Logo, copyright and trademark Butterscotch Shenanigans, all rights reserved.")
+
+Stitch™ and its logo are trademarks of Bscotch. Bscotch reserves all rights to Stitch and its logo.
+
+Stitch Logo ©2022 by Bscotch. All rights reserved.
+
+## Other code and content
+
+Everything found in this project, except for the Stitch name and logo as described above or unless otherwise specified by a more proximal LICENSE file, falls under the MIT license (https://opensource.org/license/mit/):
+
+Copyright 2023 Butterscotch Shenanigans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# Sprite Source
+
+This project provides utilities for creating art asset pipelines for GameMaker games. It is used in [Stitch for VSCode](https://marketplace.visualstudio.com/items?itemName=bscotch.bscotch-stitch-vscode) and developed against the pipeline and team requirements of [Butterscotch Shenanigans](https://www.bscotch.net/). It may or may not be applicable to other use cases.
+
+**⚠️ This package will make irreversible changes to your files! Use it at your own risk, and use version control to keep everything safe.**
+
+## Core Concepts
+
+An "art pipeline" is the process by which an artist gets from their art from editing/creating tools (like Clip Studio Paint or Photoshop) to having an in-game sprite. For the approach taken by this package, an art pipeline consists of the following:
+
+1. Art Generator. The tools used by artists to create art assets. In our case, Clip Studio Paint.
+2. A "Sprite Source". A Sprite Source is a collection of _raw_ art exports created by the Art Generator, placed into "staging" areas. This is documented by a `sprites.source.json` configuration file. Staging areas are listed in this file, where each consists of:
+   - A directory where raw exports can be found.
+   - Configuration information for how raw files should be transformed. For example, whether images should be renamed, cropped, and/or bled.
+3. A "Sprite Destination" (SpriteDest). This is assumed to be a GameMaker project, where final versions of art assets should end up as sprite frames (or Spine sprites). This is all governed by a `sprites/.stitch/sprites.import.json` config file in the GameMaker project. This config file contains an array of "sources", where each source includes:
+   - The path to a Sprite Source
+   - Optional paths to "Collaborator Sources". These are other Sprite Sources that are _not_ used for import, but if sprites are found in both the source and the collaborator sources, then imports will only happen if
+   - Options to ignore source files or auto-prefix them
+
+## Configuration
+
+Your pipelines are configured by a combination of config files:
+
+- A config called `.stitch/sprites.import.json` will be added to your project's `sprites` folder. This config lists your Sprite Sources and adds some options for how to handle them, like prefixing incoming sprite names.
+- A config called `.stitch/sprites.source.json` will be added to _each_ of your root Sprite Source folders. These folders are what the project's `sprites.import.json` references. These configs are used to describe your "stages", which are a collection of subconfigs describing _which_ image files within the root Sprite Source folder should be exported and how to transform them (e.g. adding bleeds, cropping, or renaming).
+
+This config files include a field called `$schema`, pointing to a JSON Schema that describes their content. If you open these config files in editors that understand that information, like VSCode and many other IDEs and code editors, you'll be able to hover over things to get descriptions, get autocompletes, and see warnings if something looks invalid.
+
+## Usage
+
+You can create and use pipelines using this package from Stitch for VSCode, the CLI, or programmatically.
+
+### Requirements
+
+To create an art pipeline, you'll need:
+
+- A folder (of folders) of source images
+  - Spine sprites are allowed
+  - Only PNGs are supported
+  - Each terminal folder containing one or more PNGs is treated as a "Sprite", with each PNG treated as a subimage for that sprite
+    - The terminal folder name is used as the sprite name (⚠️ make sure each one is unique!)
+    - The subimage order in GameMaker will match the alphabetical sort order of the PNG names
+- A GameMaker project using a fairly current version of GameMaker
+- Git. (Not strictly required, but a _really_ good idea!)
+
+### Stitch for VSCode
+
+[Stitch for VSCode](https://marketplace.visualstudio.com/items?itemName=bscotch.bscotch-stitch-vscode) has this package built right into it, and has an option to turn on a "watch" mode so that as you make changes to your source images they'll immediately get imported into your GameMaker project.
+
+To use it, get VSCode and install the Stitch extension, then open the Stitch panel and look for the "Sprite Sources" sub-panel (it's probably the bottom-most one). From there you can find buttons to add sprite source folders, add stages to them, open the config files for direct editing, toggle the import watcher, manually run an import, and see a list of sprites updated in the current session.
+
+### CLI
+
+To get some CLI commands, you can install this globally via `npm install -g @bscotch/sprite-source` (or `pnpm add -g @bscotch-sprite-source`). This will make the CLI command `spsrc` available in you your terminal (run `spsrc --help` to see your options).
+
+As of writing, there are two CLI commands:
+
+- `spsrc add-source path/to/image/collection path/to/project.yyp` will initialize the two configuration files you need to create a default pipeline
+- `spsrc import path/to/project.yyp` will run the transform/import process on any changed source images, syncing your source images with your GameMaker sprites
+
+### Programmatic
+
+If you have a Typescript-aware code editor, you can write Node scripts in Typescript or JavaScript and get information from your editor about the programmatic API.
+
+The main entrypoints are:
+
+```ts
+import { SpriteSource, SpriteDest } from '@bscotch/sprite-source';
+
+const source = await SpriteSource.from('path/to/raw/exports');
+// Ensure that the cached data about the raw images is up to date.
+await source.update();
+
+// Import into a project
+const dest = await SpriteDest.from('my/project.yyp');
+await dest.import({
+  sources: [
+    {
+      source: source.configFile,
+      prefix: 'sp_',
+    },
+  ],
+});
+```

package/dist/SpriteCache.d.ts

@@ -0,0 +1,67 @@
+import { Pathy } from '@bscotch/pathy';
+import { SpritesInfo } from './SpriteCache.schemas.js';
+import { SpriteDir } from './SpriteDir.js';
+import type { Log } from './types.js';
+export declare class SpriteCache {
+    readonly maxDepth: number;
+    readonly issues: Error[];
+    readonly logs: Log[];
+    readonly spritesRoot: Pathy;
+    /**
+     * @param spritesRoot The path to the root directory containing
+     * sprites. For a SpriteSource, this is the root of a set
+     * of nested folders-of-images. For a SpriteDest (a project),
+     * this is the `{project}/sprites` folder.
+     * @param maxDepth The maximum depth to search for sprites. For a SpriteSource this is probably Infinity. For a SpriteDest, this should be 1.
+     */
+    constructor(spritesRoot: string | Pathy, maxDepth?: number);
+    get stitchDir(): Pathy<unknown>;
+    get cacheFile(): Pathy<{
+        [x: string]: unknown;
+        version: number;
+        info: Record<string, {
+            [x: string]: unknown;
+            spine: false;
+            checksum: string;
+            frames: Record<string, {
+                width: number;
+                height: number;
+                checksum: string;
+                changed: number;
+            }>;
+        } | {
+            [x: string]: unknown;
+            spine: true;
+            checksum: string;
+            changed: number;
+        }>;
+        $schema?: string | undefined;
+    }>;
+    protected getSpriteDirs(dirs: Pathy[]): Promise<SpriteDir[]>;
+    protected loadCache(): Promise<SpritesInfo>;
+    /**
+     * Update the sprite-info cache.
+     */
+    protected updateSpriteInfo(ignore?: string[] | null): Promise<{
+        [x: string]: unknown;
+        version: number;
+        info: Record<string, {
+            [x: string]: unknown;
+            spine: false;
+            checksum: string;
+            frames: Record<string, {
+                width: number;
+                height: number;
+                checksum: string;
+                changed: number;
+            }>;
+        } | {
+            [x: string]: unknown;
+            spine: true;
+            checksum: string;
+            changed: number;
+        }>;
+        $schema?: string | undefined;
+    }>;
+}
+//# sourceMappingURL=SpriteCache.d.ts.map

package/dist/SpriteCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpriteCache.d.ts","sourceRoot":"","sources":["../src/SpriteCache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAS,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EACL,WAAW,EAGZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAGtC,qBAAa,WAAW;IAcpB,QAAQ,CAAC,QAAQ;IAbnB,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,CAAM;IAC9B,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,CAAM;IAC1B,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC;IAE5B;;;;;;OAMG;gBAED,WAAW,EAAE,MAAM,GAAG,KAAK,EAClB,QAAQ,SAAW;IAK9B,IAAI,SAAS,mBAEZ;IAED,IAAI,SAAS;;;;;;;;;;;;;;;;;;;;OAIZ;cAEe,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;cAsBlD,SAAS,IAAI,OAAO,CAAC,WAAW,CAAC;IAiCjD;;OAEG;cACa,gBAAgB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI;;;;;;;;;;;;;;;;;;;;;CA0E1D"}

package/dist/SpriteCache.js

@@ -0,0 +1,139 @@
+import { pathy } from '@bscotch/pathy';
+import { computePngChecksums } from '@bscotch/pixel-checksum';
+import { cacheVersion, spritesInfoSchema, } from './SpriteCache.schemas.js';
+import { SpriteDir } from './SpriteDir.js';
+import { computeStringChecksum } from './checksum.js';
+import { retryOptions, spriteCacheFilename } from './constants.js';
+import { SpriteSourceError, getDirs } from './utility.js';
+export class SpriteCache {
+    maxDepth;
+    issues = [];
+    logs = [];
+    spritesRoot;
+    /**
+     * @param spritesRoot The path to the root directory containing
+     * sprites. For a SpriteSource, this is the root of a set
+     * of nested folders-of-images. For a SpriteDest (a project),
+     * this is the `{project}/sprites` folder.
+     * @param maxDepth The maximum depth to search for sprites. For a SpriteSource this is probably Infinity. For a SpriteDest, this should be 1.
+     */
+    constructor(spritesRoot, maxDepth = Infinity) {
+        this.maxDepth = maxDepth;
+        this.spritesRoot = pathy(spritesRoot);
+    }
+    get stitchDir() {
+        return this.spritesRoot.join('.stitch');
+    }
+    get cacheFile() {
+        return this.stitchDir
+            .join(spriteCacheFilename)
+            .withValidator(spritesInfoSchema);
+    }
+    async getSpriteDirs(dirs) {
+        const waits = [];
+        const spriteDirs = [];
+        for (const dir of dirs) {
+            waits.push(SpriteDir.from(dir, this.logs, this.issues)
+                .then((sprite) => {
+                if (sprite) {
+                    spriteDirs.push(sprite);
+                }
+            })
+                .catch((err) => {
+                this.issues.push(new SpriteSourceError(`Error processing "${dir.relative}"`, err));
+            }));
+        }
+        await Promise.all(waits);
+        return spriteDirs;
+    }
+    async loadCache() {
+        let cache;
+        try {
+            cache = await this.cacheFile.read({
+                fallback: {},
+                ...retryOptions,
+            });
+            if (cache.version !== cacheVersion) {
+                cache = {
+                    version: cacheVersion,
+                    info: {},
+                };
+                this.issues.push(new SpriteSourceError(`Sprite cache version is out of date. Will rebuild.`));
+            }
+        }
+        catch (err) {
+            cache = {
+                version: cacheVersion,
+                info: {},
+            };
+            this.issues.push(new SpriteSourceError(`Could not load sprite cache. Will rebuild.`, err));
+        }
+        return cache;
+    }
+    /**
+     * Update the sprite-info cache.
+     */
+    async updateSpriteInfo(ignore) {
+        const ignorePatterns = ignore?.map((pattern) => new RegExp(pattern));
+        // Load the current cache and sprite dirs
+        const [cache, allSpriteDirs] = await Promise.all([
+            this.loadCache(),
+            getDirs(this.spritesRoot.absolute, this.maxDepth).then((dirs) => this.getSpriteDirs(dirs)),
+        ]);
+        // Filter out ignored spriteDirs
+        const spriteDirs = !ignore?.length
+            ? allSpriteDirs
+            : allSpriteDirs.filter((dir) => !ignorePatterns?.some((pattern) => dir.path.relative.match(pattern)));
+        // For each sprite, update the cache with its size, frames (checksums, changedAt, etc)
+        const waits = [];
+        for (const sprite of spriteDirs) {
+            waits.push(sprite.updateCache(cache));
+        }
+        await Promise.all(waits);
+        // Add any missing checksums
+        const checksumsToCompute = [];
+        for (const [sprite, info] of Object.entries(cache.info)) {
+            if (info.spine)
+                continue;
+            for (const [frame, frameInfo] of Object.entries(info.frames)) {
+                if (frameInfo.checksum)
+                    continue;
+                checksumsToCompute.push([
+                    sprite,
+                    frame,
+                    this.spritesRoot.join(sprite, frame).absolute,
+                ]);
+            }
+        }
+        const checksums = computePngChecksums(checksumsToCompute.map(([_s, _f, framePath]) => framePath));
+        checksumsToCompute.forEach(([sprite, frame], idx) => {
+            const spriteCache = cache.info[sprite];
+            if (spriteCache.spine)
+                return; // Shouldn't happen
+            spriteCache.frames[frame].checksum = checksums[idx];
+            spriteCache.checksum = ''; // Will be recomputed below
+        });
+        // Ensure cumulative checksums for all non-spine sprites
+        for (const [, spriteCache] of Object.entries(cache.info)) {
+            if (spriteCache.spine || spriteCache.checksum)
+                continue;
+            const frameChecksums = Object.values(spriteCache.frames)
+                .map((f) => f.checksum)
+                .sort();
+            spriteCache.checksum = computeStringChecksum(frameChecksums.join('-'));
+        }
+        // Remove any sprite info that no longer exists
+        const existingSpriteDirs = new Set(spriteDirs.map((dir) => dir.path.relative));
+        for (const spriteDir of Object.keys(cache.info)) {
+            if (!existingSpriteDirs.has(spriteDir)) {
+                delete cache.info[spriteDir];
+            }
+        }
+        // Save and return the updated cache
+        await this.cacheFile.write(cache, {
+            ...retryOptions,
+        });
+        return cache;
+    }
+}
+//# sourceMappingURL=SpriteCache.js.map

package/dist/SpriteCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpriteCache.js","sourceRoot":"","sources":["../src/SpriteCache.ts"],"names":[],"mappings":"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"}

package/dist/SpriteCache.schemas.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+export declare const cacheVersion = 2;
+export type ImageSummary = z.infer<typeof imageSummarySchema>;
+declare const imageSummarySchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    checksum: z.ZodString;
+    changed: z.ZodNumber;
+}, z.core.$strip>;
+export type SpriteSummary = z.infer<typeof spriteSummarySchema>;
+declare const spriteSummarySchema: z.ZodObject<{
+    spine: z.ZodLiteral<false>;
+    checksum: z.ZodString;
+    frames: z.ZodRecord<z.ZodString, z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        checksum: z.ZodString;
+        changed: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+export type SpineSummary = z.infer<typeof spineSummarySchema>;
+declare const spineSummarySchema: z.ZodObject<{
+    spine: z.ZodLiteral<true>;
+    checksum: z.ZodString;
+    changed: z.ZodNumber;
+}, z.core.$loose>;
+export type SpritesInfo = z.infer<typeof spritesInfoSchema>;
+export declare const spritesInfoSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+    version: z.ZodDefault<z.ZodNumber>;
+    info: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        spine: z.ZodLiteral<false>;
+        checksum: z.ZodString;
+        frames: z.ZodRecord<z.ZodString, z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            checksum: z.ZodString;
+            changed: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$loose>, z.ZodObject<{
+        spine: z.ZodLiteral<true>;
+        checksum: z.ZodString;
+        changed: z.ZodNumber;
+    }, z.core.$loose>]>>>;
+}, z.core.$loose>;
+export declare const spritesInfoInfo: {
+    schema: z.ZodObject<{
+        $schema: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+        version: z.ZodDefault<z.ZodNumber>;
+        info: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+            spine: z.ZodLiteral<false>;
+            checksum: z.ZodString;
+            frames: z.ZodRecord<z.ZodString, z.ZodObject<{
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                checksum: z.ZodString;
+                changed: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$loose>, z.ZodObject<{
+            spine: z.ZodLiteral<true>;
+            checksum: z.ZodString;
+            changed: z.ZodNumber;
+        }, z.core.$loose>]>>>;
+    }, z.core.$loose>;
+    name: string;
+    filename: string;
+};
+export declare function lastChanged(info: SpriteSummary | SpineSummary): number;
+/**
+ * Returns `true` if `a` is newer than `b`.
+ */
+export declare function isNewer(a: SpriteSummary | SpineSummary, b: SpriteSummary | SpineSummary): boolean;
+export {};
+//# sourceMappingURL=SpriteCache.schemas.d.ts.map

package/dist/SpriteCache.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpriteCache.schemas.d.ts","sourceRoot":"","sources":["../src/SpriteCache.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,QAAA,MAAM,kBAAkB;;;;;iBAKtB,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,QAAA,MAAM,mBAAmB;;;;;;;;;iBAQvB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,QAAA,MAAM,kBAAkB;;;;iBAYtB,CAAC;AAIH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;iBAS5B,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;CAI3B,CAAC;AAEF,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,UAI7D;AAED;;GAEG;AACH,wBAAgB,OAAO,CACrB,CAAC,EAAE,aAAa,GAAG,YAAY,EAC/B,CAAC,EAAE,aAAa,GAAG,YAAY,WAGhC"}

package/dist/SpriteCache.schemas.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { jsonSchemaRemoteDir } from './constants.js';
+export const cacheVersion = 2;
+const imageSummarySchema = z.object({
+    width: z.number(),
+    height: z.number(),
+    checksum: z.string().describe('Pixel-based checksum of the image.'),
+    changed: z.number().describe('Unix timestamp of last modification date.'),
+});
+const spriteSummarySchema = z.looseObject({
+    spine: z.literal(false),
+    checksum: z
+        .string()
+        .describe('A checksum combining the pixel-based checksums of all of the frame checksums.'),
+    frames: z.record(z.string(), imageSummarySchema),
+});
+const spineSummarySchema = z.looseObject({
+    spine: z.literal(true),
+    checksum: z
+        .string()
+        .describe('A checksum combining the pixel-based checksum of the atlas file with the contets of the atlas and json files.'),
+    changed: z
+        .number()
+        .describe('Unix timestamp of the most recent modified date for all associate files (atlas, json, png).'),
+});
+const schemaFilename = 'stitch.sprite-cache.schema.json';
+const remoteFilename = `${jsonSchemaRemoteDir}/${schemaFilename}`;
+export const spritesInfoSchema = z.looseObject({
+    $schema: z.string().default(remoteFilename).optional(),
+    version: z.number().default(1),
+    info: z
+        .record(z.string(), z.discriminatedUnion('spine', [spriteSummarySchema, spineSummarySchema]))
+        .default({}),
+});
+export const spritesInfoInfo = {
+    schema: spritesInfoSchema,
+    name: 'Sprite Cache',
+    filename: schemaFilename,
+};
+export function lastChanged(info) {
+    return info.spine
+        ? info.changed
+        : Math.max(...Object.values(info.frames).map((f) => f.changed), 0);
+}
+/**
+ * Returns `true` if `a` is newer than `b`.
+ */
+export function isNewer(a, b) {
+    return lastChanged(a) > lastChanged(b);
+}
+//# sourceMappingURL=SpriteCache.schemas.js.map

package/dist/SpriteCache.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpriteCache.schemas.js","sourceRoot":"","sources":["../src/SpriteCache.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAErD,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC;AAG9B,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;IACnE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;CAC1E,CAAC,CAAC;AAGH,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC;IACxC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACvB,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,QAAQ,CACP,+EAA+E,CAChF;IACH,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,kBAAkB,CAAC;CACjD,CAAC,CAAC;AAGH,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC;IACvC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;IACtB,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,QAAQ,CACP,+GAA+G,CAChH;IACH,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,QAAQ,CACP,6FAA6F,CAC9F;CACJ,CAAC,CAAC;AAEH,MAAM,cAAc,GAAG,iCAAiC,CAAC;AACzD,MAAM,cAAc,GAAG,GAAG,mBAAmB,IAAI,cAAc,EAAE,CAAC;AAElE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,WAAW,CAAC;IAC7C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE;IACtD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9B,IAAI,EAAE,CAAC;SACJ,MAAM,CACL,CAAC,CAAC,MAAM,EAAE,EACV,CAAC,CAAC,kBAAkB,CAAC,OAAO,EAAE,CAAC,mBAAmB,EAAE,kBAAkB,CAAC,CAAC,CACzE;SACA,OAAO,CAAC,EAAE,CAAC;CACf,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,MAAM,EAAE,iBAAiB;IACzB,IAAI,EAAE,cAAc;IACpB,QAAQ,EAAE,cAAc;CACzB,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,IAAkC;IAC5D,OAAO,IAAI,CAAC,KAAK;QACf,CAAC,CAAC,IAAI,CAAC,OAAO;QACd,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;AACvE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO,CACrB,CAA+B,EAC/B,CAA+B;IAE/B,OAAO,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC"}

package/dist/SpriteDest.actions.d.ts

@@ -0,0 +1,18 @@
+import { type Yyp, type YypResourceId } from '@bscotch/yy';
+import type { SpriteDestAction } from './SpriteDest.schemas.js';
+export interface ApplySpriteActionOptions {
+    projectYypPath: string;
+    action: SpriteDestAction;
+    yyp: Yyp;
+}
+export interface SpriteDestActionResult {
+    resource: YypResourceId;
+    folder: {
+        name: string;
+        folderPath: string;
+    };
+    /** The path to the sprite source root from which this action started */
+    sourceRoot: string;
+}
+export declare function applySpriteAction({ projectYypPath, action, yyp, }: ApplySpriteActionOptions): Promise<SpriteDestActionResult>;
+//# sourceMappingURL=SpriteDest.actions.d.ts.map

package/dist/SpriteDest.actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpriteDest.actions.d.ts","sourceRoot":"","sources":["../src/SpriteDest.actions.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,GAAG,EACR,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAKhE,MAAM,WAAW,wBAAwB;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,gBAAgB,CAAC;IACzB,GAAG,EAAE,GAAG,CAAC;CACV;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,iBAAiB,CAAC,EACtC,cAAc,EACd,MAAM,EACN,GAAG,GACJ,EAAE,wBAAwB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAqL5D"}

package/dist/SpriteDest.actions.js

@@ -0,0 +1,163 @@
+import { pathy } from '@bscotch/pathy';
+import { Yy, yySpriteSchema, } from '@bscotch/yy';
+import path from 'path';
+import { FIO_RETRY_DELAY, MAX_FIO_RETRIES } from './constants.js';
+import { readdirSafeWithFileTypes } from './safeFs.js';
+import { getPngSize } from './utility.js';
+export async function applySpriteAction({ projectYypPath, action, yyp, }) {
+    let trace = [];
+    try {
+        // Ensure the target path exists
+        const targetFolder = pathy(action.dest);
+        // If this is a `create` action, delete the existing sprite
+        // (no effect when there literally is no existing sprite, but
+        // there could be leftover files, or a sprite with the same name
+        // but different type, etc.)
+        if (action.kind === 'create') {
+            trace.push(`Recursively deleting ${targetFolder}`);
+            await targetFolder.delete({
+                recursive: true,
+                force: true,
+                maxRetries: MAX_FIO_RETRIES,
+                retryDelay: FIO_RETRY_DELAY,
+            });
+        }
+        trace.push(`Ensuring ${targetFolder}`);
+        await targetFolder.ensureDirectory();
+        // Get the list of children in the source and destination
+        trace.push(`Reading ${targetFolder.absolute} and ${action.source}`);
+        const [initialDestFileNames, sourceFileNames] = await Promise.all([
+            readdirSafeWithFileTypes(targetFolder),
+            readdirSafeWithFileTypes(action.source),
+        ]);
+        const initialDestFiles = initialDestFileNames
+            .filter((f) => f.isFile())
+            .map((f) => pathy(f.name, targetFolder));
+        const sourceFiles = sourceFileNames
+            .filter((f) => f.isFile())
+            .map((f) => pathy(f.name, action.source));
+        const sourcePngs = sourceFiles.filter((f) => f.basename.match(/\.png$/i));
+        // Get origin info etc
+        trace.push(`Getting origin info`);
+        const size = await getPngSize(sourcePngs[0]);
+        const width = size.width;
+        const height = size.height;
+        const xorigin = Math.floor(width / 2) - 1;
+        const yorigin = Math.floor(height / 2) - 1;
+        // Load the yy file, or populate a default one
+        const yyFile = initialDestFiles.find((f) => f.basename.toLowerCase() === `${action.name}.yy`.toLowerCase()) || pathy(`${action.name}.yy`, targetFolder);
+        if (!(await yyFile.exists())) {
+            trace.push(`Creating ${yyFile.absolute}`);
+            await Yy.write(yyFile.absolute, {
+                name: action.name,
+                type: action.spine ? 2 : 0,
+                width,
+                height,
+                sequence: { xorigin, yorigin },
+            }, 'sprites', yyp);
+        }
+        trace.push(`Reading yy file ${yyFile}`);
+        let yy = await Yy.read(yyFile.absolute, 'sprites');
+        // Populate the frames to get UUIDs
+        // Keep the old frameIds if it's a spine sprite (the alternative would be to ensure we rename the GameMaker-generated thumbnail)
+        const frames = action.spine ? yy.frames : [];
+        frames.length = action.spine ? 1 : sourcePngs.length;
+        yy = yySpriteSchema.parse({ ...yy, frames });
+        if (action.spine) {
+            trace.push('Is Spine action');
+            // Copy over and rename the skeleton files
+            const uuid = yy.frames[0].name;
+            const ioWaits = [];
+            const keepers = new Set([yyFile.basename.toLowerCase()]);
+            for (const fileType of ['json', 'atlas', 'png']) {
+                const sourceFile = sourceFiles.find((f) => f.hasExtension(fileType));
+                const destFile = pathy(`${fileType === 'png' ? sourceFile.name : uuid}.${fileType}`, targetFolder);
+                trace.push(`Copying ${sourceFile} to ${destFile}`);
+                ioWaits.push(sourceFile.copy(destFile).catch((reason) => {
+                    trace.push(reason);
+                    throw reason;
+                }));
+                keepers.add(destFile.basename.toLowerCase());
+                keepers.add(`${uuid}.${fileType}`.toLowerCase());
+            }
+            // Delete excess files
+            for (const file of initialDestFiles) {
+                if (!keepers.has(file.basename.toLowerCase())) {
+                    trace.push(`Deleting ${file}`);
+                    ioWaits.push(file
+                        .delete({
+                        force: true,
+                        maxRetries: MAX_FIO_RETRIES,
+                        retryDelay: FIO_RETRY_DELAY,
+                    })
+                        .catch((reason) => {
+                        trace.push(reason);
+                        throw reason;
+                    }));
+                }
+            }
+            trace.push('Awaiting io ops');
+            await Promise.all(ioWaits);
+        }
+        else {
+            trace.push('Is non-Spine action');
+            // Ensure the source pngs are sorted by basename
+            sourcePngs.sort((a, b) => a.basename.localeCompare(b.basename, 'en-US'));
+            // Ensure the width & height are still correct
+            yy.width = width;
+            yy.height = height;
+            // Copy over the pngs
+            const ioWaits = [];
+            const keepers = new Set([yyFile.basename.toLowerCase()]);
+            for (let i = 0; i < sourcePngs.length; i++) {
+                const uuid = yy.frames[i].name;
+                const png = sourcePngs[i];
+                const destFile = pathy(`${uuid}.png`, targetFolder);
+                trace.push(`Copying ${png} to ${destFile}`);
+                ioWaits.push(png.copy(destFile).catch((reason) => {
+                    trace.push(reason);
+                    throw reason;
+                }));
+                keepers.add(destFile.basename.toLowerCase());
+            }
+            // Delete excess files
+            for (const file of initialDestFiles) {
+                if (!keepers.has(file.basename.toLowerCase())) {
+                    trace.push(`Deleting ${file}`);
+                    ioWaits.push(file
+                        .delete({
+                        force: true,
+                        maxRetries: MAX_FIO_RETRIES,
+                        retryDelay: FIO_RETRY_DELAY,
+                    })
+                        .catch((reason) => {
+                        trace.push(reason);
+                        throw reason;
+                    }));
+                }
+            }
+            trace.push('Awaiting io ops');
+            await Promise.all(ioWaits);
+        }
+        // Save the yy file
+        trace.push(`Saving yy file ${yyFile}`);
+        await Yy.write(yyFile.absolute, yy, 'sprites', yyp);
+        // Send back info that can be used to update the project file
+        return {
+            resource: {
+                name: yy.name,
+                path: yyFile.relativeFrom(path.dirname(projectYypPath)),
+            },
+            folder: {
+                name: yy.parent.name,
+                folderPath: yy.parent.path,
+            },
+            sourceRoot: action.sourceRoot,
+        };
+    }
+    catch (err) {
+        trace.push(err);
+        throw trace;
+    }
+}
+//# sourceMappingURL=SpriteDest.actions.js.map