Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/odrick/free-tex-packer-core
Free texture packer core
https://github.com/odrick/free-tex-packer-core
Last synced: 5 days ago
JSON representation
Free texture packer core
- Host: GitHub
- URL: https://github.com/odrick/free-tex-packer-core
- Owner: odrick
- License: mit
- Created: 2018-12-27T20:02:55.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-07-28T15:53:52.000Z (about 1 year ago)
- Last Synced: 2024-09-25T08:33:19.942Z (8 days ago)
- Language: JavaScript
- Homepage:
- Size: 79.1 KB
- Stars: 120
- Watchers: 5
- Forks: 41
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# free-tex-packer-core
[](https://www.npmjs.com/package/free-tex-packer-core) \
Core Free texture packer module
# Install
$ npm install free-tex-packer-core
# Basic usage
```js
let texturePacker = require("free-tex-packer-core");
let images = [];
images.push({path: "img1.png", contents: fs.readFileSync("./img1.png")});
images.push({path: "img2.png", contents: fs.readFileSync("./img2.png")});
images.push({path: "img3.png", contents: fs.readFileSync("./img3.png")});
texturePacker(images, null, (files, error) => {
if (error) {
console.error('Packaging failed', error);
} else {
for(let item of files) {
console.log(item.name, item.buffer);
}
}
});
```
## Asynchronous usage
### Async/await
```js
const { packAsync } = require('free-tex-packer-core');
const images = [
{path: "img1.png", contents: fs.readFileSync("./img1.png")},
{path: "img2.png", contents: fs.readFileSync("./img2.png")},
{path: "img3.png", contents: fs.readFileSync("./img3.png")}
];
async function packImages() {
try {
const files = await packAsync(images, null);
for(let item of files) {
console.log(item.name, item.buffer);
}
}
catch(error) {
console.log(error);
}
}
```
### Promises
```js
function packImages() {
packAsync(images, null)
.then((files) => {
for(let item of files) {
console.log(item.name, item.buffer);
}
})
.catch((error) => console.log(error));
}
```
# Advanced usage
Use packer options object
```js
let texturePacker = require("free-tex-packer-core");
let options = {
textureName: "my-texture",
width: 1024,
height: 1024,
fixedSize: false,
padding: 2,
allowRotation: true,
detectIdentical: true,
allowTrim: true,
exporter: "Pixi",
removeFileExtension: true,
prependFolderName: true
};
let images = [];
images.push({path: "img1.png", contents: fs.readFileSync("./img1.png")});
images.push({path: "img2.png", contents: fs.readFileSync("./img2.png")});
images.push({path: "img3.png", contents: fs.readFileSync("./img3.png")});
texturePacker(images, options, (files, error) => {
if (error) {
console.error('Packaging failed', error);
} else {
for(let item of files) {
console.log(item.name, item.buffer);
}
}
});
```
# Available options
* `textureName` - name of output files. Default: **pack-result**
* `suffix` - the suffix used for multiple sprites. Default: **-**
* `suffixInitialValue` - the initial value of the suffix. Default: **0**
* `width` - max single texture width. Default: **2048**
* `height` - max single texture height. Default: **2048**
* `fixedSize` - fix texture size. Default: **false**
* `powerOfTwo` - force power of two textures sizes. Default: **false**
* `padding` - spaces in pixels around images. Default: **0**
* `extrude` - extrude border pixels size around images. Default: **0**
* `allowRotation` - allow image rotation. Default: **true**
* `detectIdentical` - allow detect identical images. Default: **true**
* `allowTrim` - allow trim images. Default: **true**
* `trimMode` - trim or crop. Default: **trim**
* `alphaThreshold` - threshold alpha value. Default: **0**
* `removeFileExtension` - remove file extensions from frame names. Default: **false**
* `prependFolderName` - prepend folder name to frame names. Default: **true**
* `textureFormat` - output file format (png or jpg). Default: **png**
* `base64Export` - export texture as base64 string to atlas meta tag. Default: **false**
* `scale` - scale size and positions in atlas. Default: **1**
* `scaleMethod` - texture scaling method (BILINEAR, NEAREST_NEIGHBOR, BICUBIC, HERMITE, BEZIER). Default: **BILINEAR**
* `tinify` - tinify texture using [TinyPNG](https://tinypng.com/). Default: **false**
* `tinifyKey` - [TinyPNG key](https://tinypng.com/developers). Default: **""**
* `packer` - type of packer (MaxRectsBin, MaxRectsPacker or OptimalPacker). Default: **MaxRectsBin**, recommended **OptimalPacker**
* `packerMethod` - name of pack method (MaxRectsBin: BestShortSideFit, BestLongSideFit, BestAreaFit, BottomLeftRule, ContactPointRule. MaxRectsPacker: Smart, Square, SmartSquare, SmartArea). Default: **BestShortSideFit**
* `exporter` - name of predefined exporter (JsonHash, JsonArray, Css, OldCss, Pixi, GodotAtlas, GodotTileset, PhaserHash, PhaserArray, Phaser3, XML, Starling, Cocos2d, Spine, Unreal, UIKit, Unity3D, Egret2D), or custom exporter (see below). Default: **JsonHash**
* `filter` - name of bitmap filter (grayscale, mask or none). Default: **none**
* `appInfo` - external app info. Required fields: url and version. Default: **null**
# Custom exporter
Exporter property can be object. Fields:
* `fileExt` - files extension
* `template` - path to template file or
* `content` - content of template
Free texture packer uses [mustache](http://mustache.github.io/) template engine.
There are 3 objects passed to template:
**rects** (Array) list of sprites for export
| prop | type | description |
| --- | --- | --- |
| name | String | sprite name |
| frame | Object | frame info (x, y, w, h, hw, hh) |
| rotated | Boolean | sprite rotation flag |
| trimmed | Boolean | sprite trimmed flag |
| spriteSourceSize | Object | sprite source size (x, y, w, h) |
| sourceSize | Object | original size (w, h) |
| first | Boolean | first element in array flag |
| last | Boolean | last element in array flag |
**config** (Object) current export config
| prop | type | description |
| --- | --- | --- |
| imageWidth | Number | texture width |
| imageHeight | Number | texture height |
| scale | Number | texture scale |
| format | String | texture format |
| imageName | String | texture name |
| base64Export | Boolean | base64 export flag |
| base64Prefix | String | prefix for base64 string |
| imageData | String | base64 image data |
**appInfo** (Object) application info
| prop | type | description |
| --- | --- | --- |
| displayName | String | App name |
| version | String | App version |
| url | String | App url |
**Template example:**
```
{
"frames": {
{{#rects}}
"{{{name}}}": {
"frame": {
"x": {{frame.x}},
"y": {{frame.y}},
"w": {{frame.w}},
"h": {{frame.h}}
},
"rotated": {{rotated}},
"trimmed": {{trimmed}},
"spriteSourceSize": {
"x": {{spriteSourceSize.x}},
"y": {{spriteSourceSize.y}},
"w": {{spriteSourceSize.w}},
"h": {{spriteSourceSize.h}}
},
"sourceSize": {
"w": {{sourceSize.w}},
"h": {{sourceSize.h}}
},
"pivot": {
"x": 0.5,
"y": 0.5
}
}{{^last}},{{/last}}
{{/rects}}
},
"meta": {
"app": "{{{appInfo.url}}}",
"version": "{{appInfo.version}}",
"image": "{{config.imageName}}",
"format": "{{config.format}}",
"size": {
"w": {{config.imageWidth}},
"h": {{config.imageHeight}}
},
"scale": {{config.scale}}
}
}
```
**Custom template usage example**
```js
let texturePacker = require("free-tex-packer-core");
let images = [];
images.push({path: "img1.png", contents: fs.readFileSync("./img1.png")});
images.push({path: "img2.png", contents: fs.readFileSync("./img2.png")});
images.push({path: "img3.png", contents: fs.readFileSync("./img3.png")});
let exporter = {
fileExt: "json",
template: "./MyTemplate.mst"
};
texturePacker(images, {exporter: exporter}, (files, error) => {
if (error) {
console.error('Packaging failed', error);
} else {
for(let item of files) {
console.log(item.name, item.buffer);
}
}
});
```
# Used libs
* **Jimp** - https://github.com/oliver-moran/jimp
* **mustache.js** - https://github.com/janl/mustache.js/
* **tinify** - https://github.com/tinify/tinify-nodejs
* **MaxRectsPacker** - https://github.com/soimy/maxrects-packer
---
License: MIT