spritefusion-sprite-normals README

项目的 README,来自 github.com/Hugo-Dz/spritefusion-sprite-normals。合并为一个 markdown 文件:README.md。

Sprite Fusion Sprite Normals

A tool to generate normal maps for pixel art sprites and animations. Written in Rust, available as a CLI and a WebAssembly library.

Sprite Normals

Why ?

Normal maps let 2D sprites react to dynamic lighting. Ideal for 2.5D games.

Features:

Perfect for

💻 CLI

Build from source

Requires Rust 1.85 or newer. From this directory:

cargo build --release --locked

The binary is available at target/release/spritefusion-sprite-normals. To install it locally:

cargo install --path . --locked

Usage

spritefusion-sprite-normals <INPUT>... [OPTIONS]
spritefusion-sprite-normals sprite.png -o sprite_n.png
spritefusion-sprite-normals sprites/*.png --output-dir normals
spritefusion-sprite-normals sprite.png -o sprite_n.png --normal-strength 2
spritefusion-sprite-normals sheet.png --frame-size 32x32 -o sheet_n.png
spritefusion-sprite-normals walk.gif -o walk_n.png

Without an output path, maps are saved beside their inputs as <name>_n.png. Run spritefusion-sprite-normals --help for every option.

Animations

GIF and APNG inputs, and PNG sheets with --frame-size, produce three files:

Frames are arranged in row-major order. delays_ms contains [numerator, denominator] pairs in milliseconds. PNG sheets keep their layout and receive a default 100 ms frame delay. Source loop counts are not exported.

Normal PNGs are data textures: disable sRGB sampling in your engine. Use artwork at its native pixel resolution. Generation estimates relief from color and shape; painted highlights can also become surface detail.

🌐 Web (WASM)

Build with the wasm32-unknown-unknown Rust target and wasm-bindgen CLI 0.2.126:

cargo build --release --target wasm32-unknown-unknown --no-default-features --locked
wasm-bindgen target/wasm32-unknown-unknown/release/spritefusion_sprite_normals.wasm --target web --out-dir pkg

Use the generated package in your project:

import init, { generate_normal_map } from "./pkg/spritefusion_sprite_normals.js";

await init();
const result = generate_normal_map(inputBytes, JSON.stringify({ strength: 1.5 }));
try {
  const normalPng = result.normal_png;
  const colorPng = result.color_png;
  const metadata = JSON.parse(result.metadata);
  // Use these bytes to save files or create image URLs.
} finally {
  result.free();
}

Pass a Uint8Array and "{}" for default settings. Optional keys are strength, detail, smoothing, volume, frame_width, frame_height, and directx. Returned arrays own their bytes and remain valid after free().

The CLI and WASM module use the same generator and animation decoder. Inputs are limited to 64 MiB and 4,194,304 pixels including processing padding; animated inputs additionally allow up to 256 frames and 4,194,304 total decoded pixels.

Development

cargo test --locked
cargo clippy --all-targets --locked -- -D warnings
cargo fmt --check

Acknowledgments

Sprite Normals is a Sprite Fusion project. Sprite Fusion is a tool to generate pixel art sprites and animations for game development.

Other open source pixel art tools

Pixel Snapper

License

MIT License — Hugo Duprez.

spritefusion-sprite-normals (Hugo-Dz/spritefusion-sprite-normals)

正在搜索数据库…

这是什么?一个从像素风精灵图和动画精灵表生成法线贴图的工具,让 2D 精灵能在 2.5D 游戏中响应动态光照。
这是命令行工具还是库?两者都是:它是一个原生 Rust 命令行可执行文件,适用于本地或批量处理;同一个生成器还能编译为 WebAssembly 库,用于基于浏览器的处理流程。
我该怎样让命令行工具运行起来?使用 Rust 1.85+ 通过 cargo 从源码构建,然后在 target/release/spritefusion-sprite-normals 找到可执行文件,或在该目录下进行本地安装。
构建它除了 Rust 还需要别的吗?命令行版本只需要 Rust 1.85+;WASM 构建还需要额外安装 wasm32-unknown-unknown 目标以及 wasm-bindgen CLI 0.2.126。
它能处理的精灵有大小限制吗?有:输入文件上限为 64 MiB,约 419 万像素;动画另外限制为 256 帧,并受同样的解码像素总量限制;输出中不保留原始 GIF/APNG 的循环次数。
它面向哪些人?面向制作带动态光照的 2D 游戏的游戏开发者、需要匹配法线贴图帧的像素画动画师,以及需要原生命令行或浏览器内处理的资源流程构建者。
它能离线运行,还是只能在浏览器里用?它完全在本地运行:命令行工具在你的电脑上处理精灵、精灵表和动画;WASM 构建则在浏览器或网页应用中提供同样可离线运行的生成器。
我的美术作品会离开我的电脑吗?不会,命令行和 WASM 模块都在本地处理,不涉及服务器或上传。
我能输入哪些文件格式?可以使用 PNG 精灵或精灵表、GIF 和 APNG 文件作为输入。
处理动画输入后会得到什么?三个文件:一个无损的法线贴图图集、一个对应的颜色图集,以及一个 frames.json 文件,用于描述图集和帧的尺寸、列数、帧数和时序。
我能调整浮雕效果的强度吗?可以。通过 --normal-strength、--detail-strength、--detail-scale 和 --shape-strength 等参数,你可以分别控制整体深度、明暗起伏、平滑度和轮廓体积,每项都有合理的默认值。
它支持 DirectX 风格的法线贴图,还是只支持 OpenGL?默认使用 OpenGL 风格的法线,但也支持 --normal-format directx 参数,可反转绿色通道,以符合 DirectX 的约定。
有哪些类似的项目?Pixelorama, raylib, slimdeer, pyxel, bevy, aseprite, pdfcraft, parin
作者
Hugo-Dz
大小
0.7 MB
星标
836
更新
提交Oct 20
时长
30天
提交 · 90 天