Head Lab

# Head Lab

**Design, preview and grab custom player heads — entirely in-game. No websites, no `/give` commands to copy, no permissions.**

Head Lab is a **client-side** custom player head editor and generator for Fabric. Press **K** (rebindable) or run `/headlab-editor` to open a pixel editor, paint a custom head, watch it live in 3D, and get the finished player head straight into your inventory — in singleplayer or on any server. It's an in-game replacement for online head generators and skin-to-head websites.

## Features

- **Pixel editor** — paint all 6 faces on an unfolded net, with base + hat layers. Pencil, eraser, fill (flood fill within a face) and color picker. Undo/redo, mirror mode, and tool hotkeys.
- **Live 3D preview** — rotate, auto-rotate, and switch between a head or full-body view.
- **Full color control** — 32-color palette, HSV picker, alpha bar for shading, hex input, and recent colors.
- **Skin import** — load any player's skin as a head by nickname (pulled from the server, with autocomplete), or one-click your own skin.
- **No permissions needed** — in creative the head is delivered via the vanilla creative packet, so it works on any server without OP, plugins or commands.
- **Load existing heads** — open the editor while holding a head to edit it, or paste a Value / URL / hash.

## How to use

1. Press **K** (or run `/headlab-editor`) to open. Holding a head loads it automatically.
2. Start from **New**, **My skin**, a player's skin (**Load**), or the head in your **Hand**.
3. Paint on the unfolded net — pick a tool (`B` / `E` / `G` / `I`) and a color, switch base/hat with `Tab`, mirror with `M`, undo with `Ctrl+Z`.
4. Check the live 3D preview — drag to rotate or switch to the full-body view.
5. Press **Generate** — in creative the head drops straight into your inventory.

> ℹ️ Generating uploads your drawing to [MineSkin](https://mineskin.org/) for a Mojang-signed texture (required so vanilla renders custom skins). An optional API key gives faster limits — set it with the **API Key…** button or in `config/headlab.properties`.

## Commands

There's also an optional server-side command (requires permission level 2 — OP or creative on a server):

/headlab give <Value | URL | hash>
/headlab givemany <1–64> <Value | URL | hash>

`<input>` accepts exactly what the editor does:

- **Value** (base64) — e.g. `eyJ0ZXh0dXJlcyI6ey...`
- **texture URL** — e.g. `http://textures.minecraft.net/texture/abc123&hellip;`
- **hash** — e.g. `abc123…`

## FAQ

**Does the server need the mod?** No — everything except the optional `/headlab give` command is client-side.

**Do I need OP / permissions?** No. Creative delivery uses the vanilla inventory packet.

**Why does Generate need internet?** Head textures must be signed by Mojang; MineSkin does that.

**Which versions?** Minecraft **1.20.2 – 1.20.4** with Fabric Loader ≥ 0.16 and Fabric API.

## Requirements

- Fabric Loader ≥ 0.16
- [Fabric API](https://modrinth.com/mod/fabric-api)