skin3d


---

Skin3d is a JavaScript library for displaying and animating Minecraft player models in the browser. It supports rendering skins, capes, elytras, and ears, and provides a simple API for customizing animations, camera controls, and backgrounds.

> ✨ Recently refactored with improved modularity, better documentation, and dependency cleanup. See Migration Guide for details.

---

What is skin3d?

Skin3d is a JavaScript library for embedding interactive Minecraft player models in web applications. It supports HD skins, capes, elytras, ears, and name tags, along with built-in animations. You can customize camera controls, lighting, backgrounds, and extend functionality with your own features.

Built with: Three.js + TypeScript

---

Why use skin3d?

- Interactive 3D Minecraft player models in the browser
- Supports all modern skin and cape formats
- Easy to use, easy to extend
- Customizable animations and controls
- Works with any web framework or vanilla JS

---

Getting Started

Install via npm:

``sh
npm i skin3d
`

---

Basic Example

`html

`
`js
import { Render, WalkingAnimation } from 'skin3d';

const viewer = new Render({
canvas: document.getElementById("skin_view_container"),
width: 400,
height: 600,
skin: "img/skin.png"
});

viewer.autoRotate = true;
viewer.animation = new WalkingAnimation();
`

Note: The main class is now Render (previously View in v0.0.10). See Migration Guide for upgrading.

---

Features at a Glance

- Skin, Cape, Elytra, and Ears Rendering
- Name Tag Support (with Minecraft font)
- Orbit Controls (rotate, zoom, pan)
- Customizable Lighting
- Panorama and Image Backgrounds
- Built-in Animations (walk, run, rotate, etc.)
- Pause/Resume Rendering
---

API Highlights

- View: The main class for rendering and controlling the player model.
- PlayerObject: Access and control the skin, cape, elytra, and ears meshes.
- NameTagObject: Display a floating name tag above the player.
- Animations: Use built-in or custom animations for the player model.
- Controls: Enable or disable camera rotation, zoom, and pan.
- Lighting: Adjust ambient and camera-attached lights.
- Backgrounds: Set solid colors, images, or panoramic backgrounds.

---

Customization

You can load new skins, capes, or ears at any time:

`js
viewer.loadSkin("img/another_skin.png");
viewer.loadCape("img/cape.png");
viewer.loadEars("img/ears.png", { textureType: "standalone" });
viewer.background = "#222244";
viewer.loadPanorama("img/panorama.png");
`

Change camera and controls:

`js
viewer.fov = 70;
viewer.zoom = 1.2;
viewer.controls.enableRotate = true;
viewer.controls.enableZoom = false;
`

Add or remove animations:

`js
import { IdleAnimation, WalkingAnimation, RunningAnimation } from 'skin3d';

viewer.animation = new WalkingAnimation();
viewer.animation.speed = 2;
viewer.animation.paused = false;
viewer.animation = null; // Remove animation
`

See Examples for more usage patterns.

---

Advanced Usage

- Lighting:
`js
viewer.globalLight.intensity = 1.5;
viewer.cameraLight.intensity = 0.3;
`

- Name Tags:
`js
import { NameTagObject } from 'skin3d';

viewer.nameTag = "Steve";
viewer.nameTag = new NameTagObject("Alex", {
scale: 1.5,
textStyle: { fillStyle: "#FFD700" }
});
`

- Responsive Sizing:
`js
viewer.width = window.innerWidth;
viewer.height = window.innerHeight;

window.addEventListener('resize', () => {
viewer.width = window.innerWidth;
viewer.height = window.innerHeight;
});
`

See Advanced Usage for more features and optimization tips.

---

Font Setup

To display name tags in Minecraft style, add this to your CSS:

`css
@font-face {
font-family: 'Minecraft';
src: url('/path/to/minecraft.woff2') format('woff2');
}
`

---

Documentation

Comprehensive documentation is available in the DOCS directory:

- Getting Started - Installation, setup, and framework integration
- Examples - 10+ practical examples covering common use cases
- API Reference - Complete API documentation with all classes and methods
- Advanced Usage - Performance optimization, custom animations, and advanced features
- Architecture - Understanding the library structure and design patterns
- Migration Guide - Upgrading from previous versions
- Troubleshooting - Common issues and solutions

---

Recent Changes (v0.1.0)

$3

- Modular Architecture: Refactored for better code organization and maintainability
- New Export System: Improved module exports with better tree-shaking support
- Enhanced Documentation: Comprehensive guides, examples, and API reference
- Dependency Cleanup: Removed unused polyfills, optimized for production
- Main Class Rename: View → Render for clarity

$3

- src/Render.ts - Core rendering engine (replaces legacy skin3d.ts)
- src/Model.ts - Player model and mesh management
- src/Animation.ts - Animation system
- src/Nametag.ts - Name tag rendering
- src/index.ts - Main entry point

$3

The main class View has been renamed to Render:

`js
// Old
import { View } from 'skin3d';
const viewer = new View({ ... });

// New
import { Render } from 'skin3d';
const viewer = new Render({ ... });
`

See Migration Guide for complete upgrade instructions.

---

Project Structure

- src/Render.ts – Main rendering engine
- src/Model.ts – Player model and mesh components
- src/Animation.ts – Animation system
- src/Nametag.ts – Name tag rendering
- src/index.ts – Public API exports
- DOCS/` – Comprehensive documentation

---

License

skin3d is released under the MIT License.

---

Links

- Live Demo
- NPM Package
- GitHub Repository
- Community Chat

---