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-играх.
Это CLI-инструмент или библиотека?И то, и другое: это нативный CLI-бинарник на Rust для локальной и пакетной обработки, а тот же генератор собирается в библиотеку WebAssembly для браузерных пайплайнов.
Как запустить CLI?Соберите его из исходников с Rust 1.85+ через cargo, затем найдите бинарный файл в target/release/spritefusion-sprite-normals или установите его локально из этой директории.
Нужно ли что-то, кроме Rust, чтобы собрать это?Для CLI достаточно Rust 1.85+; для сборки WASM дополнительно нужны цель wasm32-unknown-unknown и wasm-bindgen CLI 0.2.126.
Есть ли ограничения на спрайты, которые он может обработать?Да: входные файлы ограничены 64 МиБ и примерно 4,19 миллиона пикселей, а анимации дополнительно ограничены 256 кадрами и тем же общим бюджетом декодированных пикселей; количество циклов повтора исходных GIF/APNG в результат не сохраняется.
Для кого это предназначено?Для разработчиков 2D-игр с динамическим освещением, пиксель-артистов, которые анимируют спрайты и нуждаются в соответствующих кадрах карт нормалей, и для всех, кто строит пайплайны ресурсов с обработкой через нативный CLI или в браузере.
Работает ли это офлайн или только в браузере?Работает полностью локально: CLI обрабатывает спрайты, листы и анимации на вашем компьютере, а сборка WASM даёт тот же генератор, работающий офлайн внутри браузера или веб-приложения.
Покидают ли мои работы компьютер?Нет, обработка происходит локально и в CLI, и в модуле 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 дней