diff --git a/README.md b/README.md index d133901..f215823 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,102 @@ -
+

+

RS-MobCages

+

+ Capture, transport, and release mobs with portable Mob Cages. +

-# RS-MobCage -### Mob Capture & Transport for Modern Minecraft Servers +

![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) -

+

-**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 \ No newline at end of file +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 + +--- \ No newline at end of file diff --git a/src/docs/Admin-Guide.md b/src/docs/Admin-Guide.md new file mode 100644 index 0000000..076a5a2 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/src/docs/Capturing-Mobs.md b/src/docs/Capturing-Mobs.md new file mode 100644 index 0000000..a95f990 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/src/docs/Commands-and-Permissions.md b/src/docs/Commands-and-Permissions.md new file mode 100644 index 0000000..bcb6f4f --- /dev/null +++ b/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. diff --git a/src/docs/Configuration.md b/src/docs/Configuration.md new file mode 100644 index 0000000..5f5039b --- /dev/null +++ b/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. \ No newline at end of file diff --git a/src/docs/Crafting.md b/src/docs/Crafting.md new file mode 100644 index 0000000..5864f8e --- /dev/null +++ b/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) diff --git a/src/docs/Getting-Started.md b/src/docs/Getting-Started.md new file mode 100644 index 0000000..b7c918b --- /dev/null +++ b/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) \ No newline at end of file diff --git a/src/docs/Installation.md b/src/docs/Installation.md new file mode 100644 index 0000000..57b9c4e --- /dev/null +++ b/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) \ No newline at end of file diff --git a/src/docs/Mob-Variants-and-Attributes.md b/src/docs/Mob-Variants-and-Attributes.md new file mode 100644 index 0000000..1285212 --- /dev/null +++ b/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. diff --git a/src/docs/Releasing-Mobs.md b/src/docs/Releasing-Mobs.md new file mode 100644 index 0000000..ef879bf --- /dev/null +++ b/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) \ No newline at end of file diff --git a/src/docs/Supported-Mobs.md b/src/docs/Supported-Mobs.md new file mode 100644 index 0000000..2c32773 --- /dev/null +++ b/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. diff --git a/src/docs/Troubleshooting.md b/src/docs/Troubleshooting.md new file mode 100644 index 0000000..ce49e45 --- /dev/null +++ b/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. diff --git a/src/docs/images/MobCageRecipe.jpg b/src/docs/images/MobCageRecipe.jpg new file mode 100644 index 0000000..df1da9c Binary files /dev/null and b/src/docs/images/MobCageRecipe.jpg differ