1.0.2

Documentation update
2026-08-27 23:56:00 -05:00
1 parent b0b8c2f5c0
commit f15ace5865
@@ -1,48 +1,102 @@
-<div align="center">
+<p align="center">
+  <h1 align="center">RS-MobCages</h1>
+  <p align="center">
+    Capture, transport, and release mobs with portable Mob Cages.
+  </p>

-# RS-MobCage

-### Mob Capture & Transport for Modern Minecraft Servers
+<p align="center">

 ![Minecraft](https://img.shields.io/badge/Minecraft-1.21%2B-green)
 ![Platform](https://img.shields.io/badge/Platform-Paper-orange)
-![Status](https://img.shields.io/badge/Status-Stable-success)
-![Development](https://img.shields.io/badge/Development-Active-brightgreen)
+![Status](https://img.shields.io/badge/Status-Active-brightgreen)
+![Development](https://img.shields.io/badge/Development-Active-green)
 ![RS Ecosystem](https://img.shields.io/badge/RS-Ecosystem-purple)

-</div>
+</p>

-**RS-MobCage** is a Minecraft plugin that adds reusable Mob Cages for capturing, transporting, and releasing supported mobs.
+---

-A Mob Cage stores the captured mob's relevant information directly on the item, allowing the mob to be safely moved and released somewhere else.
+## Overview
+
+**RS-MobCages** allows players to capture supported mobs inside portable Mob Cages, carry them in their inventory, transport them wherever they are needed, and release them again.
+
+Mob Cages are designed to provide a simple and convenient way to move mobs without relying on leads, boats, minecarts, or other traditional transportation methods.
+Capture a mob, take it with you, and release it at its new destination.
+
+---

 ## Features

- Capture supported mobs using a reusable Mob Cage
- Release captured mobs by right-clicking the ground
- Preserves supported mob variants
- Preserves baby/adult state where supported
- Preserves supported mob attributes such as:
-    - Cow variants
-    - Chicken variants
-    - Pig variants
-    - Sheep color
-    - Horse color and markings
- Prevents named mobs from being captured
- Prevents players from being captured
- Requires mobs to be at full health before capture
- Prevents Mob Cages from being placed as blocks
- Handles mob equipment during capture
- Configurable equipment-drop behavior
- Custom Mob Cage recipe
- Uses persistent item data to identify and track cage state
- Supports adding additional mob types through the descriptor system
+### 🐾 Capture Supported Mobs

-## Mob Cage
+Use an empty Mob Cage on a supported mob to capture it.
+The cage stores the information needed to recreate the mob when it is released.

-The Mob Cage is crafted using:
+### 📦 Portable Mob Storage

-```text
-Iron Bars | Iron Bars  | Iron Bars
-Iron Bars | Iron Ingot | Iron Bars
-Iron Bars | Iron Bars  | Iron Bars
+Captured mobs can be carried as items in a player's inventory.
+This makes it easy to transport mobs across your world.
+
+### 🔄 Release Mobs Anywhere
+
+Release a captured mob when you are ready to place it in its new location.
+After release, the Mob Cage becomes empty and can be used again.
+
+### 🧬 Mob-Specific Data
+
+RS-MobCages uses mob descriptors to handle supported mobs and preserve mob-specific information when appropriate.
+This allows different types of mobs to be handled according to their individual requirements.
+
+### 🚫 Protected Mobs
+
+Players and named mobs cannot be captured.
+Named mobs are also protected from capture.
+
+### 🛡️ Safe Capture Handling
+
+If a creature is not supported by RS-MobCages, the plugin will safely prevent it from being captured.
+
+---
+
+## How It Works
+
+Using a Mob Cage is simple:
+
+1. Obtain an empty Mob Cage.
+2. Hold the empty cage in your main hand.
+3. Right-click a supported mob to capture it.
+4. Carry the filled Mob Cage to its new location.
+5. Release the mob.
+6. Reuse the empty Mob Cage.
+
+---
+
+## Documentation
+
+Complete documentation is available in the [`docs`](docs/) folder.
+
+Planned documentation includes:
+
+- [Installation](./docs/Installation.md)
+- [Getting Started](./docs/Getting-Started.md)
+- [Crafting a Mob Cage](docs/Crafting.md)
+- [Capturing Mobs](./docs/Capturing-Mobs.md)
+- [Releasing Mobs](./docs/Releasing-Mobs.md)
+- [Supported Mobs](./docs/Supported-Mobs.md)
+- [Mob Variants and Attributes](./docs/Mob-Variants-and-Attributes.md)
+- [Commands and Permissions](./docs/Commands-and-Permissions.md)
+- [Configuration](./docs/Configuration.md)
+- [Admin Guide](./docs/Admin-Guide.md)
+- [Troubleshooting](./docs/Troubleshooting.md)
+- [Changelog](./docs/Changelog.md)
+
+---
+
+## Requirements
+
+- Paper
+- A supported Minecraft server version
+- Java version required by the server version
+
+---