updated README with detailed plugin overview, usage, commands, and configuration documentation

README.md

@@ -1,2 +1,79 @@
 # PixelBlocks
 
+**Design and build your own custom Minecraft blocks. In Minecraft.**
+
+*No resource packs. No client mods. 100% server-side.*
+
+PixelBlocks is a Paper plugin that lets 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. Ownership protection keeps builds safe on multiplayer servers, and nothing about vanilla gameplay changes for players who don't use the feature.
+
+## 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.
+
+| | | |
+|---|---|---|
+| Glass | End Crystal | Glass |
+| Diamond Block | Heart of the Sea | Diamond Block |
+| Grass Block | Grass Block | Grass Block |
+
+## Requirements & installation
+
+- Paper 1.21+
+- Java 21
+
+Drop `PixelBlocks-<version>-all.jar` into your server's `plugins/` folder and start the server. Config and storage are created on first start.
+
+## Commands
+
+Root command: `/pixelblocks` (alias `/pb`), players only.
+
+| 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, optionally with a fixed UUID (e.g. to restore a lost item for an existing block) | `pixelblocks.command.give` | op |
+| `/pixelblocks exit` | Leaves the pixel block you are currently in | `pixelblocks.command.exit` | everyone |
+| `/pixelblocks destroyall` | Destroys **all** pixel blocks on the server (bypasses ownership) | `pixelblocks.command.destroyall` | op |
+
+## Configuration
+
+`plugins/PixelBlocks/config.yml`:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `pixelsPerBlock` | `16` | Edge length of the build area in blocks (= resolution of the miniature) |
+| `onlyBreakableByOwners` | `false` | Only the owner may break a pixel block |
+| `onlyEditableByOwners` | `true` | Only the owner may enter and edit a pixel block |
+
+**Note:** don't change `pixelsPerBlock` once pixel blocks exist, because existing build dimensions and the miniature scale would no longer match.
+
+## Data & backups
+
+- `plugins/PixelBlocks/blocks.db`: SQLite database with pixel block metadata (owner, position, orientation).
+- `plugins/PixelBlocks/worlds/<block-uuid>/`: one world per pixel block containing its build contents.
+
+Back up both to preserve all pixel blocks.
+
+## Building from source
+
+```bash
+gradle build
+```
+
+The plugin jar ends up in `build/libs/` as `PixelBlocks-<version>-all.jar`. To copy it to a local test server automatically, set `testServerPluginsDir=/path/to/server/plugins` in `gradle.properties` and run `gradle copyJarToTestServer`.