1.0.2

Documentation update

README.md

@@ -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)
+![Status](https://img.shields.io/badge/Status-Active-brightgreen)
-![Development](https://img.shields.io/badge/Development-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
+### 🐾 Capture Supported Mobs
-- 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
 
-## 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
+Captured mobs can be carried as items in a player's inventory.
-Iron Bars | Iron Bars  | Iron Bars
+This makes it easy to transport mobs across your world.
-Iron Bars | Iron Ingot | Iron Bars
+
-Iron Bars | Iron Bars  | Iron Bars
+### 🔄 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
+
+---

src/docs/Admin-Guide.md

@@ -0,0 +1,88 @@
+# Administrator Guide
+
+This guide provides basic information for server administrators running RS-MobCages.
+
+RS-MobCages is designed to require minimal administration and works with its default behavior after installation.
+
+---
+
+## Installation
+
+Install RS-MobCages by placing the plugin `.jar` file into your server's:
+
+    plugins/
+
+folder.
+
+Restart the server and verify that RS-MobCages loads successfully.
+
+For detailed installation instructions, see:
+
+➡️ [Installation](./docs/Installation.md)
+
+---
+
+## Server Administration
+
+RS-MobCages currently does not require any special administrator setup.
+
+There are currently:
+
+- No required commands.
+- No required permissions.
+- No required configuration changes.
+
+Once the plugin is installed and enabled, players can use Mob Cages to capture and release supported mobs.
+
+---
+
+## Supported Mobs
+
+RS-MobCages only allows supported mobs to be captured.
+
+The list of supported mobs may expand as additional mob descriptors are added to the plugin.
+
+For the current list, see:
+
+➡️ [Supported Mobs](./docs/Supported-Mobs.md)
+
+---
+
+## Named Mob Protection
+
+Named mobs are protected from capture.
+
+This helps prevent players from accidentally capturing mobs that have been intentionally named.
+
+Server administrators should be aware of this behavior when testing or using Mob Cages.
+
+---
+
+## Plugin Updates
+
+When updating RS-MobCages:
+
+1. Stop the server.
+2. Back up your server.
+3. Remove the previous RS-MobCages `.jar` file.
+4. Place the new `.jar` file into the `plugins` folder.
+5. Start the server.
+6. Check the console to confirm that the plugin loaded successfully.
+
+Always review release notes when updating to a new version.
+
+---
+
+## Troubleshooting
+
+If RS-MobCages does not appear to be working correctly:
+
+- Verify that the plugin loaded successfully.
+- Check the server console for errors.
+- Confirm that the mob being tested is supported.
+- Make sure the player is using an appropriate Mob Cage.
+- Check that the mob does not have a custom name.
+
+For additional troubleshooting information, see:
+
+➡️ [Troubleshooting](./docs/Troubleshooting.md)

src/docs/Capturing-Mobs.md

@@ -0,0 +1,99 @@
+# Capturing Mobs
+
+This guide explains how to capture mobs using RS-MobCages.
+
+Mob Cages allow supported mobs to be captured and stored inside a portable cage for transportation.
+
+---
+
+## Before Capturing a Mob
+
+Before attempting to capture a mob, make sure you have:
+
+- An empty Mob Cage.
+- The Mob Cage in your main hand.
+- A supported mob to capture.
+
+Not every entity can be captured.
+
+Players cannot be captured, and named mobs are protected from accidental capture.
+
+For a complete list of supported mobs, see:
+
+➡️ [Supported Mobs](./docs/Supported-Mobs.md)
+
+---
+
+## Capturing a Mob
+
+To capture a mob:
+
+1. Place an empty Mob Cage in your main hand.
+2. Approach a supported mob.
+3. Use the Mob Cage on the mob.
+
+If the mob can be captured, the capture will be processed.
+
+The mob will be removed from the world and the empty Mob Cage will become a filled Mob Cage containing that mob.
+
+---
+
+## Successful Capture
+
+When a mob is successfully captured:
+
+- The original mob is removed from the world.
+- The Mob Cage becomes associated with the captured mob.
+- The filled cage can be carried in a player's inventory.
+- Mob-specific information is stored when supported by the mob's descriptor.
+
+The filled Mob Cage can then be transported and released at another location.
+
+See:
+
+➡️ [Releasing Mobs](./docs/Releasing-Mobs.md)
+
+---
+
+## Named Mobs
+
+RS-MobCages protects named mobs from being accidentally captured.
+
+If a mob has a custom name, it cannot be captured.
+
+This helps prevent players from accidentally placing important, decorative, or specially named mobs into a Mob Cage.
+
+---
+
+## Players
+
+Players cannot be captured.
+
+Mob Cages are intended for supported mobs only.
+
+---
+
+## Unsupported Mobs
+
+If you attempt to capture an unsupported entity, the capture will not be completed.
+
+RS-MobCages only captures mobs that are supported by the plugin.
+
+For the complete list, see:
+
+➡️ [Supported Mobs](./docs/Supported-Mobs.md)
+
+---
+
+## After Capturing
+
+Once a mob has been captured, the filled Mob Cage can be:
+
+- Carried in your inventory.
+- Moved to another location.
+- Stored until needed.
+- Released when you are ready to place the mob.
+
+To learn how to release a captured mob, continue to:
+
+➡️ [Releasing Mobs](./docs/Releasing-Mobs.md)

src/docs/Commands-and-Permissions.md

@@ -0,0 +1,29 @@
+# Commands and Permissions
+
+RS-MobCages does not currently require any commands or permissions for normal use.
+
+Players interact directly with Mob Cages to capture and release supported mobs.
+
+---
+
+## Commands
+
+RS-MobCages currently does not provide any player or administrator commands.
+
+All normal interaction is performed directly in-game using Mob Cages.
+
+---
+
+## Permissions
+
+RS-MobCages currently does not require any permissions.
+
+If the plugin is installed and enabled, players can use supported Mob Cages normally.
+
+---
+
+## Future Commands and Permissions
+
+Commands and permissions may be added in a future version if they become necessary.
+
+Any new commands or permissions will be documented here.

src/docs/Configuration.md

@@ -0,0 +1,44 @@
+# Configuration
+
+RS-MobCages currently requires little to no configuration.
+
+The plugin is designed to work immediately after installation without requiring players or server administrators to configure commands, permissions, or complex settings.
+
+---
+
+## Default Configuration
+
+After RS-MobCages is installed and the server is started, the plugin will create any required plugin files and use its default settings.
+
+For most servers, no additional configuration is required.
+
+---
+
+## Configuration File
+
+If RS-MobCages includes a configuration file, it can be found in:
+
+    plugins/RS-MobCages/
+
+Any available configuration options will be listed and explained in this documentation as they are added to the plugin.
+
+---
+
+## Current Configuration Options
+
+RS-MobCages does not currently require any configuration changes for normal operation.
+
+The plugin is designed to work with its default behavior after installation.
+
+---
+
+## Future Configuration Options
+
+Additional configuration options may be added in future versions as the plugin expands.
+
+If new options are introduced, this page will be updated to include:
+
+- The configuration option name.
+- Its default value.
+- What the option controls.
+- Any valid values or limitations.

src/docs/Crafting.md

@@ -0,0 +1,49 @@
+# Crafting a Mob Cage
+
+Before you can capture and transport mobs using RS-MobCages, you must first craft an empty Mob Cage.
+
+The empty Mob Cage is used to capture supported mobs and can be reused after the captured mob has been released.
+
+---
+
+## Crafting Recipe
+
+Place the required ingredients in a crafting table using the following recipe:
+
+**[INSERT CRAFTING RECIPE IMAGE HERE]**
+
+The recipe will produce an empty Mob Cage.
+
+---
+
+## Using the Mob Cage
+
+Once crafted, the empty Mob Cage can be used to capture a supported mob.
+
+To capture a mob:
+
+1. Hold the empty Mob Cage in your main hand.
+2. Right-click a supported mob.
+3. The mob will be captured inside the cage.
+
+The filled Mob Cage can then be carried in your inventory and transported to another location.
+
+For detailed instructions, see:
+
+➡️ [Capturing Mobs](./docs/Capturing-Mobs.md)
+
+---
+
+## Reusing the Cage
+
+Mob Cages are reusable.
+
+After releasing a captured mob, the cage becomes empty again and can be used to capture another supported mob.
+
+This means you do not need to craft a new cage every time you want to move a mob.
+
+```Note:  There is a known issue where sometimes cages will not stack when emptied. We are working to isolate and fix the issue, however, since it is not a breaking issue, it is lower on the priority list.```
+
+For more information, see:
+
+➡️ [Releasing Mobs](./docs/Releasing-Mobs.md)

src/docs/Getting-Started.md

@@ -0,0 +1,109 @@
+# Getting Started
+
+This guide will walk you through the basic process of using RS-MobCages.
+
+With RS-MobCages, you can capture supported mobs, carry them in your inventory, transport them to another location, and release them when you are ready.
+
+---
+
+## The Basic Process
+
+Using a Mob Cage follows a simple process:
+
+1. Obtain an empty Mob Cage.
+2. Capture a supported mob.
+3. Carry the filled cage to a new location.
+4. Release the mob.
+5. Reuse the empty cage.
+
+---
+
+## Step 1 — Obtain an Empty Mob Cage
+
+Before you can capture a mob, you need an empty Mob Cage.
+
+Make sure you have the cage available in your inventory and place it in your main hand.
+
+---
+
+## Step 2 — Find a Supported Mob
+
+Locate a mob supported by RS-MobCages.
+
+Not every entity can be captured.
+
+For example, players cannot be captured, and protected mobs such as named mobs may also be prevented from being captured.
+
+For a complete list of supported mobs, see:
+
+➡️ [Supported Mobs](./docs/Supported-Mobs.md)
+
+---
+
+## Step 3 — Capture the Mob
+
+Hold an empty Mob Cage in your main hand.
+
+Use the cage on a supported mob to capture it.
+
+If the capture is successful:
+
+- The mob is removed from the world.
+- The Mob Cage becomes a filled cage.
+- The captured mob can now be transported in your inventory.
+
+The filled Mob Cage stores the information needed to release the mob later.
+
+---
+
+## Step 4 — Transport the Mob
+
+Once captured, the Mob Cage can be carried in your inventory.
+
+Take the cage wherever you want to move the mob.
+
+This makes it easier to relocate mobs without using leads, boats, minecarts, or other traditional transportation methods.
+
+---
+
+## Step 5 — Release the Mob
+
+When you reach the desired location, use the filled Mob Cage to release the captured mob.
+
+The mob will be recreated in the world.
+
+After the mob has been released, the cage becomes empty and can be used again.
+
+For more information, see:
+
+➡️ [Releasing Mobs](./docs/Releasing-Mobs.md)
+
+---
+
+## Important Notes
+
+### Named Mobs
+
+RS-MobCages protects named mobs from being accidentally captured.
+
+If a mob has been given a custom name, the plugin may prevent it from being placed inside a Mob Cage.
+
+This helps protect important or decorative mobs from accidental removal.
+
+---
+
+### Players Cannot Be Captured
+
+Mob Cages are intended for supported mobs only.
+
+Players cannot be captured.
+
+---
+
+### Unsupported Mobs
+
+If a mob is not supported, RS-MobCages will not capture it.
+
+For a complete list of supported mobs, see:
+
+➡️ [Supported Mobs](./docs/Supported-Mobs.md)

src/docs/Installation.md

@@ -0,0 +1,108 @@
+# Installation
+
+This guide explains how to install RS-MobCages on your Paper Minecraft server.
+
+---
+
+## Requirements
+
+Before installing RS-MobCages, make sure your server meets the plugin requirements.
+
+- A supported version of Paper
+- A compatible Java version for your Minecraft server
+- Permission to install plugins on the server
+
+RS-MobCages is designed for Paper servers.
+
+---
+
+## Installing RS-MobCages
+
+### Step 1 — Stop Your Server
+
+Before installing or updating any plugin, stop your Minecraft server completely.
+
+---
+
+### Step 2 — Download RS-MobCages
+
+Download the latest release of RS-MobCages from one of the supported download locations.
+Place the downloaded `.jar` file somewhere you can easily access.
+
+---
+
+### Step 3 — Install the Plugin
+
+Move the RS-MobCages `.jar` file into your server's:
+
+    plugins/
+
+folder.
+
+Your server directory should look similar to:
+
+    server/
+    ├── plugins/
+    │   ├── RS-MobCages.jar
+    │   └── ...
+    ├── world/
+    ├── world_nether/
+    └── world_the_end/
+
+---
+
+### Step 4 — Start Your Server
+
+Start the Minecraft server normally.
+During startup, Paper will load RS-MobCages and create any required plugin files.
+After the server has finished starting, check the console for the RS-MobCages startup message.
+
+---
+
+## Verifying Installation
+
+Join the server and verify that RS-MobCages is loaded.
+You can also check the server console or run:
+
+    /plugins
+
+RS-MobCages should appear in the list of loaded plugins.
+
+---
+
+## First-Time Setup
+
+Once RS-MobCages is installed, continue to:
+
+➡️ [Getting Started](./docs/Getting-Started.md)
+
+The Getting Started guide will walk through obtaining and using your first Mob Cage.
+
+---
+
+## Updating RS-MobCages
+
+To update the plugin:
+
+1. Stop the server.
+2. Remove the old RS-MobCages `.jar` file from the `plugins` folder.
+3. Place the new `.jar` file into the `plugins` folder.
+4. Start the server.
+
+Unless otherwise noted in the release notes, existing plugin data and configuration files should be preserved.
+Always back up your server before performing updates.
+
+---
+
+## Troubleshooting Installation
+
+If RS-MobCages does not appear in `/plugins`:
+
+- Make sure the `.jar` file is inside the correct `plugins` folder.
+- Check that you are using a supported Paper server version.
+- Check the server console for plugin loading errors.
+- Verify that your Java version is compatible with your Minecraft server.
+
+For additional help, see:
+
+➡️ [Troubleshooting](./docs/Troubleshooting.md)

src/docs/Mob-Variants-and-Attributes.md

@@ -0,0 +1,99 @@
+# Mob Variants and Attributes
+
+Some mobs have different appearances, variants, or attributes that make them different from the standard version of that mob.
+
+RS-MobCages can store mob-specific information so that supported mobs can be released with the appropriate appearance or variant.
+
+The exact information stored depends on the mob and its support within RS-MobCages.
+
+---
+
+## Why Variants Matter
+
+Many Minecraft mobs are not visually identical.
+
+For example, two sheep may both be sheep, but they may have different wool colors.
+
+Other mobs may have different:
+
+- Colors
+- Variants
+- Types
+- Patterns
+- Appearances
+- Mob-specific attributes
+
+When supported, RS-MobCages stores this information when the mob is captured and applies it again when the mob is released.
+
+---
+
+## Examples
+
+Depending on the supported mob, this may include information such as:
+
+### Sheep
+
+Sheep may have different wool colors.
+
+A captured sheep can retain its supported wool color information when released.
+
+---
+
+### Cats
+
+Cats can have different variants and appearances.
+
+When supported, the captured cat's variant information can be stored and restored.
+
+---
+
+### Horses and Other Equines
+
+Horses and other equine mobs may have appearance or variant information that differs between individual mobs.
+
+Supported information can be stored as part of the captured mob's data.
+
+---
+
+### Other Variant Mobs
+
+Other supported mobs may also have their own descriptors for handling mob-specific information.
+
+As RS-MobCages expands, additional mobs and their supported attributes may be added.
+
+---
+
+## Attribute Support
+
+Not every property of a mob is necessarily stored.
+
+Support depends on the specific mob descriptor and the information currently implemented for that mob.
+
+For example, a supported mob may preserve:
+
+- Its variant
+- Its color
+- Its appearance
+- Other supported mob-specific information
+
+Other properties may not currently be preserved.
+
+---
+
+## Future Mob Support
+
+RS-MobCages is designed to allow additional mob types and mob-specific attributes to be added over time.
+
+As new mobs are added, their descriptors can define which information should be stored and restored.
+
+This allows the plugin to expand without requiring every mob to use the exact same capture and release logic.
+
+---
+
+## Important Notes
+
+Mob-specific support may change as RS-MobCages develops.
+
+The [Supported Mobs](./docs/Supported-Mobs.md) page will be updated as additional mobs are added.
+
+If a particular mob has special handling or limitations, those details should be documented with that mob's supported behavior.

src/docs/Releasing-Mobs.md

@@ -0,0 +1,90 @@
+# Releasing Mobs
+
+This guide explains how to release a mob that has been captured inside an RS-MobCage.
+
+Once a mob has been captured, the filled Mob Cage can be carried to another location and used to release the mob back into the world.
+
+---
+
+## Before Releasing a Mob
+
+Before releasing a mob, make sure:
+
+- You have a filled Mob Cage.
+- You are at the location where you want the mob to appear.
+- There is enough space for the mob to spawn.
+
+The filled Mob Cage contains the information needed to recreate the captured mob.
+
+---
+
+## Releasing the Mob
+
+To release a captured mob:
+
+1. Place the filled Mob Cage in your main hand.
+2. Move to the location where you want to release the mob.
+3. Use the Mob Cage to release the mob.
+
+If the release is successful, the captured mob will be recreated in the world.
+
+---
+
+## After Release
+
+After the mob has been successfully released:
+
+- The mob will appear in the world.
+- The filled Mob Cage becomes an empty Mob Cage.
+- The empty cage can be used again to capture another supported mob.
+
+This allows the same Mob Cage to be reused multiple times.
+
+---
+
+## Mob Information
+
+RS-MobCages uses mob descriptors to store and restore information about supported mobs.
+
+Depending on the type of mob, this may include information needed to preserve that mob's appearance or variant when it is released.
+
+For more information, see:
+
+➡️ [Mob Variants and Attributes](./docs/Mob-Variants-and-Attributes.md)
+
+---
+
+## Choosing a Release Location
+
+Before releasing a mob, make sure the intended location is suitable for that mob.
+
+For example:
+
+- The mob should have enough physical space to spawn.
+- The release location should not place the mob inside solid blocks.
+- The area should be appropriate for the mob you are releasing.
+
+If a release cannot be completed, check the surrounding area and try again.
+
+---
+
+## Reusing the Mob Cage
+
+One of the primary purposes of RS-MobCages is reusability.
+
+The same basic process can be repeated:
+
+1. Capture a mob.
+2. Transport the filled Mob Cage.
+3. Release the mob.
+4. Reuse the empty Mob Cage.
+
+---
+
+## Returning to Capture
+
+After releasing a mob, the empty Mob Cage is ready to be used again.
+
+To learn more about capturing mobs, see:
+
+➡️ [Capturing Mobs](./docs/Capturing-Mobs.md)

src/docs/Supported-Mobs.md

@@ -0,0 +1,102 @@
+# Supported Mobs
+
+This page lists the mobs that can be captured using RS-MobCages.
+
+RS-MobCages uses individual mob descriptors to determine how supported mobs are captured and released.
+
+Each supported mob may have its own handling for variants, appearance, or other mob-specific information.
+
+---
+
+## Supported Mobs
+
+RS-MobCages supports the following mobs:
+
+### Passive Mobs
+
+- Cow
+- Chicken
+- Pig
+- Sheep
+- Rabbit
+- Horse
+- Donkey
+
+### Cats and Wolves
+
+- Cat
+
+### Other Passive Mobs
+
+- Bee
+- Parrot
+
+### Villagers
+
+- Villager
+
+### Hostile Mobs
+
+- Zombie
+- Spider
+- Cave Spider
+
+---
+
+## Mob Variants
+
+Some mobs have multiple possible appearances or variants.
+
+When supported by the mob's descriptor, RS-MobCages stores the information necessary to recreate that variant when the mob is released.
+
+Examples may include:
+
+- Sheep wool color
+- Cat variants
+- Wolf variants
+- Horse appearance
+- Rabbit variants
+- Frog variants
+- Parrot variants
+- Axolotl variants
+- Tropical fish appearance
+
+For more information, see:
+
+➡️ [Mob Variants and Attributes](./docs/Mob-Variants-and-Attributes.md)
+
+---
+
+## Named Mobs
+
+Named mobs cannot be captured.
+
+If a mob has been given a custom name, RS-MobCages will prevent it from being captured.
+
+This helps protect:
+
+- Pets
+- Decorative mobs
+- Named villagers
+- Important server mobs
+- Other mobs that players have intentionally named
+
+---
+
+## Unsupported Mobs
+
+If a mob is not supported by RS-MobCages, it cannot be captured.
+
+The plugin will safely ignore unsupported entities.
+
+Players cannot be captured.
+
+---
+
+## Important Notes
+
+Support for a mob does not necessarily mean that every possible property of that mob is stored.
+
+Mob-specific information is handled individually by the mob's descriptor.
+
+Some mobs may preserve variants or appearance information, while others may only require their basic entity type to be stored.

src/docs/Troubleshooting.md

@@ -0,0 +1,126 @@
+# Troubleshooting
+
+This guide covers common issues you may encounter while using RS-MobCages.
+
+---
+
+## The Plugin Does Not Appear in `/plugins`
+
+If RS-MobCages does not appear in the `/plugins` list:
+
+1. Verify that the RS-MobCages `.jar` file is located in your server's:
+
+        plugins/
+
+   folder.
+
+2. Restart the server.
+
+3. Check the server console for errors related to RS-MobCages.
+
+4. Make sure you are using a supported Paper server version.
+
+If the plugin reports an error during startup, review the full error message in the server console.
+
+---
+
+## I Cannot Capture a Mob
+
+If a mob cannot be captured, check the following:
+
+- Make sure you are holding an empty Mob Cage.
+- Make sure the mob is supported by RS-MobCages.
+- Make sure the mob does not have a custom name.
+- Make sure you are interacting directly with the mob.
+
+Not every entity can be captured.
+
+For the current list of supported mobs, see:
+
+➡️ [Supported Mobs](./docs/Supported-Mobs.md)
+
+---
+
+## I Cannot Capture a Named Mob
+
+This is expected behavior.
+
+RS-MobCages prevents named mobs from being captured.
+
+A mob with a custom name is protected from accidental capture.
+
+If the mob is intentionally named, remove the custom name before attempting to capture it.
+
+---
+
+## I Cannot Capture a Player
+
+Players cannot be captured.
+
+Mob Cages are intended for supported mobs only.
+
+---
+
+## The Mob I Am Trying to Capture Is Not Supported
+
+RS-MobCages only captures mobs that are currently supported by the plugin.
+
+If a mob is not listed on the [Supported Mobs](./docs/Supported-Mobs.md) page, it cannot currently be captured.
+
+Additional mob support may be added in future updates.
+
+---
+
+## The Mob Will Not Release
+
+If a captured mob does not release as expected:
+
+- Make sure you are using a filled Mob Cage.
+- Make sure there is enough open space for the mob to appear.
+- Try moving to a different location.
+- Make sure the area is not blocked by solid blocks.
+
+If the problem continues, check the server console for any errors.
+
+---
+
+## The Mob Does Not Look the Same After Release
+
+Some mobs have variants, colors, or other unique attributes.
+
+RS-MobCages can preserve supported mob-specific information, but not every possible property is necessarily stored.
+
+For more information, see:
+
+➡️ [Mob Variants and Attributes](./docs/Mob-Variants-and-Attributes.md)
+
+---
+
+## The Plugin Stops Working After an Update
+
+If RS-MobCages worked previously but stops working after an update:
+
+1. Stop the server.
+2. Check that only one version of `RS-MobCages.jar` is installed.
+3. Verify that you are using the correct version of the plugin for your server.
+4. Check the server console for errors.
+5. Review the release notes for the version you installed.
+
+Always back up your server before updating plugins.
+
+---
+
+## Reporting a Bug
+
+If you believe you have found a bug, please include as much information as possible when reporting it.
+
+Helpful information includes:
+
+- Minecraft version
+- Paper version
+- RS-MobCages version
+- What you were doing when the problem occurred
+- Which mob was involved
+- Any relevant server console errors
+
+Clear reproduction steps make bugs much easier to identify and fix.