Added HANGAR.md documentation, including overview, crafting, commands, configuration, and requirements. Included related screenshots.

2026-07-24 16:15:54 +02:00
parent ef2352d381
commit 1566419f85
3 changed files with 70 additions and 0 deletions
@@ -0,0 +1,70 @@
+# PixelBlocks
+
+**Design and build your own custom Minecraft blocks. In Minecraft.**
+
+*No resource packs. No client mods. 100% server-side.*
+
+![A tiny hut with a grass base, built as a single custom pixel block](https://mhsl.eu/gitea/Minecraft/PixelBlocks/raw/branch/main/docs/screenshots/pixelblock-hut.png)
+
+PixelBlocks lets your players create their own blocks: place a pixel block, walk inside it, and build its appearance pixel by pixel in a dedicated building dimension. Every block placed inside becomes one pixel of the custom block (16×16×16 by default), just like a Minecraft block texture, but in 3D and made of real blocks.
+
+Since everything is rendered with vanilla display entities, custom blocks are visible to every player instantly: nothing to install, nothing to download.
+
+## ✨ Why PixelBlocks?
+
+- **Custom blocks without mods or resource packs:** everything is rendered with vanilla display entities; clients need nothing installed.
+- **Portable builds:** break a pixel block and it drops as an item, contents included. Place it somewhere else, give it away, or collect them.
+- **Real block feel:** the design is rendered in the world with real block models, including correct rotations and orientations, scaled down to a single block.
+- **Ownership built in:** the first player to place an empty pixel block becomes its owner; editing and breaking can be restricted to owners via config.
+- **Made for vanilla, survival and SMP servers:** pixel blocks are earned in-game through a late-game crafting recipe that players discover naturally, no commands or admin intervention needed.
+- **Localized:** English and German out of the box, following each player's client language.
+
+## 🧭 How it works
+
+1. Craft a pixel block and place it anywhere in the world.
+2. Right-click it to enter its building dimension: a floating grass platform with a marked build area and an exit portal.
+3. Build the block's look inside the marked area, pixel by pixel. Leave through the portal (or `/pixelblocks exit`) and the placed block now shows your design.
+4. Break the block to pick it up. Item and design travel together.
+
+The building dimensions are fully protected: no mob spawns, no explosions, no redstone contraptions escaping the build area, no liquids flowing out, and players cannot open containers that don't belong there.
+
+## 🛠️ Crafting
+
+The recipe unlocks for a player as soon as they click a Heart of the Sea or an End Crystal in their inventory.
+
+![Crafting recipe: glass, end crystal and glass on top, diamond block, heart of the sea and diamond block in the middle, grass blocks at the bottom](https://mhsl.eu/gitea/Minecraft/PixelBlocks/raw/branch/main/docs/screenshots/crafting-recipe.png)
+
+| | | |
+|---|---|---|
+| Glass | End Crystal | Glass |
+| Diamond Block | Heart of the Sea | Diamond Block |
+| Grass Block | Grass Block | Grass Block |
+
+## ⌨️ Commands & permissions
+
+Root command: `/pixelblocks` (alias `/pb`)
+
+| Command | Description | Permission | Default |
+|---|---|---|---|
+| `/pixelblocks create` | Creates a pixel block at your position | `pixelblocks.command.create` | op |
+| `/pixelblocks give [uuid]` | Gives a pixel block item | `pixelblocks.command.give` | op |
+| `/pixelblocks exit` | Leaves the current pixel block | `pixelblocks.command.exit` | everyone |
+| `/pixelblocks destroyall` | Destroys all pixel blocks | `pixelblocks.command.destroyall` | op |
+
+## ⚙️ Configuration
+
+```yaml
+pixelsPerBlock: 16           # resolution of the miniature (don't change once blocks exist)
+onlyBreakableByOwners: false # only the owner may break a pixel block
+onlyEditableByOwners: true   # only the owner may enter and edit a pixel block
+```
+
+## 📦 Requirements
+
+- Paper 1.21 or newer (built against the latest release)
+- Java 21+ (Java 25 for current Paper versions)
+
+## 🔗 Links
+
+- [Source code](https://mhsl.eu/gitea/Minecraft/PixelBlocks)
+- Found a bug or have an idea? Open an issue in the repository!