https://github.com/nickacpt/nmsr-rs
NickAc's Minecraft Skin Renderer - Render Minecraft skins with true perspective
https://github.com/nickacpt/nmsr-rs
avatar avatar-service ears ears-mod jni-library minecraft minecraft-avatar minecraft-skin minecraft-skin-renderer minecraft-skins nmsr renderer rust skin-stealer uv-map web-service wgpu wgpu-rs
Last synced: about 1 month ago
JSON representation
NickAc's Minecraft Skin Renderer - Render Minecraft skins with true perspective
- Host: GitHub
- URL: https://github.com/nickacpt/nmsr-rs
- Owner: NickAcPT
- License: apache-2.0
- Created: 2022-10-25T00:07:23.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-01T18:06:29.000Z (3 months ago)
- Last Synced: 2025-04-12T17:06:57.558Z (about 1 month ago)
- Topics: avatar, avatar-service, ears, ears-mod, jni-library, minecraft, minecraft-avatar, minecraft-skin, minecraft-skin-renderer, minecraft-skins, nmsr, renderer, rust, skin-stealer, uv-map, web-service, wgpu, wgpu-rs
- Language: Rust
- Homepage: https://nmsr.nickac.dev/
- Size: 7.81 MB
- Stars: 54
- Watchers: 2
- Forks: 5
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# NickAc's Minecraft Skin Renderer
A speedy and fairly-accurate Minecraft avatar renderer service.
A hosted version of NMSR is available [here](https://nmsr.nickac.dev/). 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._
> [!IMPORTANT]
> If you are self-hosting an instance that you run in production, you should fill the contact information in the `config.toml` file (see example.config.toml).
>
> This is used to provide contact information in the headers of outgoing requests to the various APIs, just in case they need to contact you.
## 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](#uv-map-layouts).
### `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`](https://github.com/NickAcPT/nmsr-rs/tree/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