npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@bsmth/sequence-loader

v1.2.0

Published

Streamlined sprite animation packing for webpack.

Downloads

17

Readme

📽🗺 bismuth sequence loader

Streamlined sprite animation packing for webpack.

Motivations

Implementing sprite based animations usually requires the use of a locally installed tool like TexturePacker, necessitating additional setup steps, making things inconvenient to upgrade and cumbersome to integrate with an existing webpack setup. @bsmth/sequence-loader attempts to solve this by fully integrating the packing step with webpack, passing the atlas images off to your existing image loader.


How it works

Instead of importing sequence info and generated atlas images seperately, you'll import a single .sequence.json file, pointing to your image sequence and containing instructions on how to generate the atlas. Based on this, @bsmth/sequence-loader then generates atlas images and sequence info automatically on the fly.


Installation

yarn add --dev @bsmth/sequence-loader @bsmth/loader-cache
npm i --save-dev @bsmth/sequence-loader @bsmth/loader-cache

Setup

You'll need to add the loader and its cache management plugin to your webpack config.

import { CachePlugin } from "@bsmth/loader-cache";

export default {
	module: {
		rules: [
			// ...
			{
				test: /\.sequence\.json$/i,
				type: "javascript/auto",
				use: [
					{
						loader: "@bsmth/sequence-loader",
						options: {
							// ...
						},
					},
				],
			},
		],
	},
	plugins: [
		// ...
		new CachePlugin({
			// ...
		}),
	],
};

Usage

Inside your project you can now create a .sequence.json file, pointing to your image sequence:

("$schema" is entirely optional, but it'll give you autocomplete and inline validation support. You can also use https://bit.ly/2SXgtdE as the URL)

{
	"$schema": "https://unpkg.com/@bsmth/[email protected]/schema/SequenceOptions.json",
	"files": "./path/to/my/sequence/*.png"
}

See .sequence.json options for more options.

Now, you can import that JSON:

import mySequence from "./my.sequence.json";

By default, mySequence will give you the following object:

{
	width: number,      // size of sequence
	height: number,
	pages: [
		{
			width: number,  // size of page
			height: number,
			img: unknown,   // whatever your image loader outputs
		},
		// ...
	],
	frames: [
		{
			frame: number,  // frame index
			x: number,      // position on page
			y: number,
			width: number,  // size of frame on page
			height: number,
			page: number,   // index of page including ths frame
			padding: {      // amount of 'whitespace' trimmed
				top: number,
				right: number,
				bottom: number,
				left: number,
			},
		},
		// ...
	],
}

You can also get the info in the same format used by TexturePacker, by adding "format": "TexturePacker" to your .sequence.json:

[
	{
		meta: {
			version: string,
			format: string,
			image: unknown, // whatever your image loader outputs
			scale: number,
			size: {
				w: number,
				h: number,
			},
		},
		frames: {
			"frame-000": {
				rotated: boolean,
				trimmed: boolean,
				frame: {
					w: number,
					h: number,
					x: number,
					y: number,
				},
				spriteSourceSize: {
					w: number,
					h: number,
					x: number,
					y: number,
				},
				sourceSize: {
					w: number,
					h: number,
				},
			},
			// ...
		},
	},
	// ...
];

Note that you'll receive an array of pages, since TexturePacker would create a separate JSON file for each.


Config

.sequence.json options

| Name | Type | Default | Description | | --------------- | ------------------------------ | ----------------- | ------------------------------------------------------------ | | files | string | './*.{png,jpg}' | A glob pattern pointing to your sequence frames.This is relative to the .json you're importing. | | scale | number | 1 | A scalar applied to your frames before being packed.Useful if the frames are at a higher resolution than the final animation. | | padding | number | 0 | Amout of pixels in between the packed frames.Useful if you see bleeding at the frame edges. | | trim | boolean | true | Whether to trim 'uninteresting' pixels off the frame edges.This reduces file size, but you'll need to reconstruct the trimmed areas manually. | | trimThreshold | number | 1 | The threshold below which a pixel will be considered 'uninteresting'.This represents the maximum difference from the top-left pixel of the image. | | relative | boolean | false | Whether to output coordinates relative to the page instead of pixel coordinates.Useful if the output image is being resized. | | pageMaxWidth | number | 4096 | Maximum width in pixels a page image (atlas) may be.Note that multiple pages may be created to fit all frames. | | pageMaxHeight | number | 4096 | Maximum height in pixels a page image (atlas) may be.Note that multiple pages may be created to fit all frames. | | format | 'default' \| 'TexturePacker' | 'default' | The format in which you'll receive the sequence.Choosing 'TexturePacker' gives you an array of objects that match the output of running TexturePacker with --format json | | imageQuery | string | '' | Query string appended to the generated image imports.Useful if you want to pass info to your image loader. |

Loader options

You can also add the above options as loader options. The'll act as defaults. Additionally loader-specific options are:

| Name | Type | Default | Description | | ---------------------- | ------------------------------- | ---------- | ------------------------------------------------------------ | | generateDeclarations | boolean | false | Whether to output a .d.ts files next to imported JSONs.This provides correct types based on your settings. | | output | 'esm' \| 'commonjs' | 'esm' | What module format the JS output should be generated in. | | logLevel | 'pretty' \| 'simple' \| 'off' | 'pretty' | How progress updates are displayed in the console.'pretty' may conflict with existing progress UIs, set to 'simple' or 'off' in that case. |


Typescript

@bsmth/sequence-loader can auto-generate declarations for your sequences!

By setting generateDeclarations to true in the loader config, @bsmth/sequence-loader will emit a .d.ts file next to each .sequence.json file you're importing, containing types for that specific sequence. Image import types are mapped to whatever the type of *.png is in your setup.


Caching

@bsmth/sequence-loader will cache all processed images and intermediates on disk. This is handled by the CachePlugin exported by @bsmth/loader-cache, which accepts some options.


Pitfalls/Shortcomings

Working with git / CI

Without an up to date cache, @bsmth/sequence-loader will create all atlases on startup. This can lead to insanely long build- and startup times. To circumvent this, it may be desirable to push the entire cache directory (.bsmth-loader-cache) to git LFS. While this is not ideal, all renditions will only be created once and reused on subsequent runs.


To-dos

  • [ ] better documentation
  • [ ] examples
  • [ ] tests

License

© 2021 the project bismuth authors, licensed under MIT.