README.md

NickAc's Minecraft Skin Renderer

A speedy and fairly-accurate Minecraft avatar renderer service.

A hosted version of NMSR is available here. It's provided on a best-effort basis, so please don't abuse it.

NMSR supports custom render parameters, player armour, armour trims, many render modes, native Ears mod support and Minecraft capes.

Getting Started

Moving off from a different avatar service? We've got you covered. Self-hosting NMSR is easy as 1, 2, 3!

Docker

1. Clone the repository and rename the example.config.toml file to config.toml.
2. Run docker build -t nmsr .
3. Run docker run -p 8080:8080 nmsr

No Docker

1. Clone the repository.
2. Run cargo run --release --bin nmsr-aas
3. You're done! The service is now running on http://localhost:8080.

Supported render modes

Category	Render Mode	Description	Example	Example (Back)
Body	FullBody	Full body render
	FullBodyIso	Full body isometric render
	BodyBust	Body bust render
	FrontBust	Bust isometric front render
	FrontFull	Full isometric front render
Head	Head	Head render
	HeadIso	Head isometric render
	Face	Face render
Extra	Skin	Player skin
	Custom	Custom render settings

Examples shown are of the author's skin, rendered using the ears feature enabled.

Crates

Since this project contains a few crates, here's a short explanation for each.

nmsr-aas - NickAc's Minecraft Skin Renderer as a Service

The star of the show. This is the service that does the actual rendering. If you're looking to self-host NMSR, this is the crate you're looking for.

nmsr-3d-renderer/nmsr-player-parts - Player parts provider

Abstraction of a Minecraft player model. This serves as a base for the 3d model cubes and quads.

When compiled with the ears feature, it also provides Ears mod support.

nmsr-3d-renderer/nmsr-rendering - 3D rendering

The actual 3D rendering engine. This is where the magic happens. Implemented using wgpu-rs which allows for plugging many different rendering backends.

nmsr-lib - UV map library

This is the (now legacy) UV map library. This used to do the actual "rendering" in previous versions. It requires pre-rendered images to be provided.

Currently, it uses version 2 of the UV map layout instead of the previous format.

For more information on the UV map layout, see here.

utils/** - Utilities

Crates in this directory are provided as-is and some may or may not be maintained.

Contains experiments that could be promoted to officially supported crates in the future.

nmsr-jni

This is the JNI library, which contains the native code for invoking the skin renderer from the JVM.

UV map layouts

Version 2

This is the current version of the UV map layout. It's an 8-bit RGBA image. It improves on the previous version by not being wasteful with the bits, at the cost of being more complex.

UV map layout v2

R								G								B								A
0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19	20	21	22	23	24	25	26	27	28	29	30	31
U						V						Shading								Depth

Version 1

This is the previous version of the UV map layout. It's a 16-bit RGBA image. It's wasteful with the bits, but it's simple.

If you're looking for the last commit that used this UV map layout, checkout commit e62100095a7fcdc83c989a4fb603866cf338edca.

UV map layout v1

R																G																B																A
0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19	20	21	22	23	24	25	26	27	28	29	30	31	32	33	34	35	36	37	38	39	40	41	42	43	44	45	46	47	48	49	50	51	52	53	54	55	56	57	58	59	60	61	62	63
U																V (100% - V coordinate)																Depth																Alpha