From e25d4da319bd666a2b30b779cff17575541ca49d Mon Sep 17 00:00:00 2001 From: Big Pappa Date: Mon, 8 Jun 2026 21:24:32 -0500 Subject: [PATCH] Commit: "Add complete documentation system" --- docs/Admin-Guide.md | 165 ++++++++++++---- docs/Changelog.md | 84 ++++---- docs/Creating-Your-First-ItemMagnet.md | 126 ------------ docs/Creating-Your-First-MobStand.md | 89 +++++++++ docs/FAQ.md | 126 ++++++++++++ docs/Filters.md | 230 ++++++++++++++------- docs/Gravity-Settings.md | 109 ++++++++++ docs/Home.md | 134 ++++++++----- docs/Installation.md | 81 ++++---- docs/Leave-Alive-Settings.md | 134 +++++++++++++ docs/Main-Menu.md | 121 ++++++++++++ docs/Pause-and-Resume.md | 191 +++++++++++------- docs/Permissions.md | 155 ++++++++++++--- docs/Radius-Settings.md | 76 +++---- docs/Storage-and-Persistence.md | 79 -------- docs/Troubleshooting.md | 264 ++++++++++++++++++++----- readme.md | 2 +- 17 files changed, 1546 insertions(+), 620 deletions(-) delete mode 100644 docs/Creating-Your-First-ItemMagnet.md create mode 100644 docs/Creating-Your-First-MobStand.md create mode 100644 docs/FAQ.md create mode 100644 docs/Gravity-Settings.md create mode 100644 docs/Leave-Alive-Settings.md create mode 100644 docs/Main-Menu.md delete mode 100644 docs/Storage-and-Persistence.md diff --git a/docs/Admin-Guide.md b/docs/Admin-Guide.md index e408e22..f506182 100644 --- a/docs/Admin-Guide.md +++ b/docs/Admin-Guide.md @@ -1,67 +1,164 @@ # Admin Guide -This guide covers administrative controls and management of RS-ItemMagnet. +The Admin Menu provides server operators with administrative controls and diagnostic information for RS-MobStand. + +This menu is intended for server staff and administrators. --- -# Administrative Access +# Accessing the Admin Menu -Administrators with the appropriate permissions can manage ItemMagnets regardless of ownership. +The Admin button appears within the Main Menu for authorized users. + +Open: + +```text id="u56k0l" +Main Menu + ↓ +Admin +``` + +to access administrative functions. --- -# Common Administrative Tasks +# Administrative Features -## Inspect Machines - -View machine settings and configuration. - -## Modify Machines - -Adjust: - -* Radius -* Filters -* Assigned containers -* Operational state - -## Remove Machines - -Remove invalid, abandoned, or problematic ItemMagnets. +Depending on your server configuration and plugin version, the Admin Menu may contain various management and diagnostic tools. --- -# Ownership System +# Reload Configuration -RS-ItemMagnet uses ownership protection. +The Reload Configuration option allows administrators to reload the plugin configuration without restarting the server. -Normally only the owner may modify a machine. +This is useful when: -Administrators can bypass ownership restrictions when necessary. +* Adjusting plugin settings +* Testing configuration changes +* Applying updates to configuration files + +### When To Use Reload + +After editing: + +```text id="k7y2gj" +config.yml +``` + +you can reload the plugin to apply changes immediately. + +--- + +# Plugin Version Information + +The Admin Menu displays plugin version information. + +Information may include: + +* Installed Version +* Latest Available Version +* Update Status + +Possible status values: + +```text id="4m7j1f" +Up To Date +``` + +The installed version matches the latest available version. + +```text id="awpjol" +Update Available +``` + +A newer version is available. + +```text id="hrsd1g" +Unable To Check +``` + +The plugin could not reach the update source. + +This may occur when: + +* Internet access is unavailable +* The update source is inaccessible +* The repository is private + +--- + +# Ownership Bypass + +Administrators may bypass normal ownership restrictions. + +This allows staff to: + +* Inspect Mob Stands +* Modify configurations +* Troubleshoot player issues + +without needing ownership of the Mob Stand. --- # Troubleshooting Player Issues -Common causes of collection problems: +When assisting players: -* Missing target container -* Full container -* Incorrect filter settings -* Items outside collection radius +### Verify Ownership + +Ensure the player owns the Mob Stand or has appropriate permissions. + +### Verify Filters + +Incorrect filter settings are a common cause of unexpected behavior. + +### Verify Radius + +Confirm the Mob Stand is scanning the intended area. + +### Verify Pause Status + +A paused Mob Stand will not process mobs. --- # Best Practices -Use administrative controls sparingly. +### Reload Sparingly -Allow players to manage their own automation systems whenever possible. +Frequent reloads are generally unnecessary. + +### Test Configuration Changes + +Verify changes on a test stand before making server-wide adjustments. + +### Keep Backups + +Maintain backups of configuration files before making major changes. + +### Monitor Updates + +Review plugin updates periodically for bug fixes and new features. --- -# Next Step +# Security -Continue with: +Administrative access should only be granted to trusted staff members. -[Troubleshooting](Troubleshooting.md) +Administrative permissions may allow: + +* Bypassing ownership protection +* Accessing administrative controls +* Modifying player Mob Stands + +--- + +# Related Pages + +* Permissions +* Troubleshooting +* Main Menu +* Installation diff --git a/docs/Changelog.md b/docs/Changelog.md index 3ba3f52..291e016 100644 --- a/docs/Changelog.md +++ b/docs/Changelog.md @@ -1,40 +1,56 @@ # Changelog -## Version 1.0.3 - -### Infrastructure - -* Migrated to Maven single-source versioning -* Added GitHub update checking -* Standardized version display system -* Added GitHub repository support - -### Multiplayer - -* Fixed player selection conflicts -* Added UUID-based selection tracking -* Improved multi-user machine configuration - -### Reliability - -* Verified restart persistence -* Verified chunk unload/reload handling -* Verified player relog persistence -* Verified machine recreation behavior - -### Administration - -* Improved version information display -* Standardized update status reporting - -### Documentation - -* Added README documentation -* Added MIT License -* Added complete documentation system +All notable changes to RS-MobStand will be documented here. --- -## Future Releases +# Unreleased -Future changes will be documented here. +## Documentation + +* GitHub repository created +* Wiki created +* Installation guide added +* Player documentation added +* Administrative documentation added + +--- + +# Version 1.0.4 + +## Version Management + +* Migrated to Maven-based version management +* Implemented single source of truth using pom.xml +* Removed version.txt dependency +* Added GitHub version checking + +## Administrative Improvements + +* Added improved version status display +* Added update availability detection +* Added "Unable To Check" status handling + +## Stability + +* Verified multiplayer menu isolation +* Confirmed per-player menu tracking +* Confirmed ownership protection behavior + +## Documentation + +* Added README improvements +* Added GitHub Wiki +* Added installation and support documentation + +--- + +# Future + +Planned ecosystem integrations: + +* RS-ItemMagnet +* RS-Auger +* RS-Warehouse + +Additional features and improvements will be documented as development continues. diff --git a/docs/Creating-Your-First-ItemMagnet.md b/docs/Creating-Your-First-ItemMagnet.md deleted file mode 100644 index bbccd7b..0000000 --- a/docs/Creating-Your-First-ItemMagnet.md +++ /dev/null @@ -1,126 +0,0 @@ -# Creating Your First ItemMagnet - -This guide walks through creating and configuring your first RS-ItemMagnet. - ---- - -# Step 1 - Place a Lodestone - -Place a Lodestone where you want your ItemMagnet to operate. - -The Lodestone will serve as the machine block for the ItemMagnet. - ---- - -# Step 2 - Convert the Machine - -Open the RS-ItemMagnet menu and select: - -```text -Convert Machine -``` - -Click the Lodestone you placed. - -The Lodestone is now an RS-ItemMagnet. - ---- - -# Step 3 - Assign a Container - -Open the machine menu. - -Select: - -```text -Assign Container -``` - -Then click the container you want the machine to use. - -Supported containers include: - -* Chests -* Barrels -* Hoppers -* Other supported inventory blocks - ---- - -# Step 4 - Configure Radius - -Open: - -```text -Radius Settings -``` - -Select the collection radius you want the machine to use. - -Larger radii allow collection from a larger area. - ---- - -# Step 5 - Configure Filters (Optional) - -Open: - -```text -Filters -``` - -Configure which items should be accepted or rejected. - -Filters allow ItemMagnets to specialize in collecting specific resources. - ---- - -# Step 6 - Test Collection - -Drop an item inside the configured radius. - -The ItemMagnet should: - -1. Detect the item -2. Attract the item -3. Deliver the item to the assigned container - ---- - -# Ownership - -The player who creates the ItemMagnet becomes its owner. - -Only the owner (or authorized administrators) may: - -* Modify settings -* Change filters -* Reassign containers -* Remove the machine - ---- - -# Troubleshooting - -If items are not being collected: - -* Verify a container is assigned -* Verify the container has available space -* Verify filters allow the item -* Verify the item is within range - -For additional help see: - -[Troubleshooting](Troubleshooting.md) - ---- - -# Next Step - -Continue with: - -[Radius Settings](Radius-Settings.md) - -or - -[Filters](Filters.md) diff --git a/docs/Creating-Your-First-MobStand.md b/docs/Creating-Your-First-MobStand.md new file mode 100644 index 0000000..a5baebd --- /dev/null +++ b/docs/Creating-Your-First-MobStand.md @@ -0,0 +1,89 @@ +# Creating Your First Mob Stand + +This guide will walk you through converting an ordinary Armor Stand into a fully functional Mob Stand. + +--- + +# Requirements + +Before creating a Mob Stand, ensure you have: + +* An Armor Stand +* A Stick +* Permission to use RS-MobStand + +--- + +# Step 1: Place an Armor Stand + +Place an Armor Stand where you want your Mob Stand to operate. + +Choose a location that is close to the mobs you want to manage. + +--- + +# Step 2: Convert the Armor Stand + +Hold a **Stick** in your hand. + +Sneak and right-click the Armor Stand. + +The Armor Stand will immediately convert into a Mob Stand. + +Once converted: + +* The Armor Stand becomes a Mob Stand. +* Ownership is assigned to the player who performed the conversion. +* The Mob Stand is ready to be configured. + +--- + +# Step 3: Open the Mob Stand Menu + +Right-click your Mob Stand to open the main configuration menu. + +From this menu you can configure: + +* Scan Radius +* Leave Alive +* Adult Filters +* Baby Filters +* Gravity +* Pause / Resume + +--- + +# Ownership + +Mob Stands are owned by the player who creates them. + +By default: + +* Owners can modify their own Mob Stands. +* Other players cannot change settings. +* Administrators may bypass ownership restrictions. + +--- + +# Converting Back to an Armor Stand + +If you no longer need a Mob Stand: + +1. Open the Mob Stand menu. +2. Select **Convert Back to Armor Stand**. + +The Mob Stand will immediately return to a normal Armor Stand. + +--- + +# Next Steps + +Now that your Mob Stand has been created, continue with: + +* Main Menu +* Radius Settings +* Leave Alive Settings +* Filters +* Pause and Resume + +These guides explain how each setting affects Mob Stand behavior. diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000..9ca795d --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,126 @@ +# Frequently Asked Questions + +--- + +## How do I create a Mob Stand? + +Place an Armor Stand. + +Sneak and right-click it while holding a Stick. + +The Armor Stand will immediately convert into a Mob Stand. + +--- + +## Can other players modify my Mob Stand? + +No. + +Only the owner can modify a Mob Stand unless a player has administrative permissions. + +--- + +## How do I remove a Mob Stand? + +Open the Main Menu and select: + +```text id="y2jlwm" +Convert Back to Armor Stand +``` + +The Mob Stand will immediately return to a normal Armor Stand. + +--- + +## Do Mob Stands survive server restarts? + +Yes. + +All Mob Stand settings are saved automatically. + +--- + +## Can I have multiple Mob Stands? + +Yes. + +Players may create as many Mob Stands as allowed by server rules and performance considerations. + +--- + +## Why is my Mob Stand not processing mobs? + +Check: + +* Pause Status +* Radius Settings +* Adult Filters +* Baby Filters +* Leave Alive Settings + +See the Troubleshooting guide for detailed assistance. + +--- + +## What does Leave Alive do? + +Leave Alive determines how many matching mobs remain alive. + +Example: + +```text id="0g7vqf" +Leave Alive: 5 +``` + +Five matching mobs will always remain. + +--- + +## What does Gravity do? + +Gravity determines whether the Mob Stand behaves like a normal Armor Stand. + +Enabled: + +```text id="pnnc4e" +Falls normally +``` + +Disabled: + +```text id="70x2p4" +Remains fixed in place +``` + +--- + +## Can administrators bypass ownership? + +Yes. + +Players with: + +```text id="x2tq67" +rsmobstand.admin +``` + +may bypass ownership restrictions. + +--- + +## Does RS-MobStand require any dependencies? + +No. + +RS-MobStand operates independently and does not require additional plugins. + +--- + +## Where can I get support? + +Review: + +* Troubleshooting +* Admin Guide + +If additional help is needed, open an issue on GitHub. diff --git a/docs/Filters.md b/docs/Filters.md index 87878a6..fca9f9f 100644 --- a/docs/Filters.md +++ b/docs/Filters.md @@ -1,107 +1,191 @@ # Filters -Filters allow ItemMagnets to collect only specific items. +Filters determine which mobs a Mob Stand will manage. -This allows multiple ItemMagnets to operate in the same area while collecting different resources. +Using filters allows you to target specific mob types while ignoring others. + +Each Mob Stand maintains separate filter lists for: + +* Adult Mobs +* Baby Mobs + +This provides precise control over farm behavior and mob management. + +--- + +# Adult Filters + +Adult Filters control which adult mobs may be processed. + +Only enabled adult mob types are considered by the Mob Stand. + +Example: + +```text id="6kiz54" +Cow ✓ Enabled +Pig ✓ Enabled +Chicken ✗ Disabled +``` + +Result: + +```text id="mgj55p" +Cows and Pigs may be processed. +Chickens are ignored. +``` + +--- + +# Baby Filters + +Baby Filters control which baby mobs may be processed. + +This allows baby mobs to be treated differently from adults. + +Example: + +```text id="gqz7ir" +Baby Cow ✗ Disabled +Adult Cow ✓ Enabled +``` + +Result: + +```text id="8jlwmr" +Adult cows may be processed. +Baby cows are ignored. +``` + +This is particularly useful for breeding operations. --- # Why Use Filters? -Without filters: +Filters provide flexibility and precision. -```text -ItemMagnet -→ Collects Everything +Common uses include: + +* Separating breeding stock +* Managing specific farm animals +* Protecting decorative mobs +* Controlling resource production +* Supporting specialized farm layouts + +--- + +# Opening Filters + +Open: + +```text id="ybxbik" +Main Menu + ↓ +Adult Filters ``` -With filters: +or -```text -ItemMagnet A -→ Cobblestone +```text id="7p2qcz" +Main Menu + ↓ +Baby Filters +``` -ItemMagnet B -→ Iron +to access the desired filter menu. -ItemMagnet C -→ Redstone +--- + +# Enabling a Filter + +When a mob filter is enabled: + +```text id="0rmr5g" +Enabled +``` + +the Mob Stand is allowed to manage that mob type. + +--- + +# Disabling a Filter + +When a mob filter is disabled: + +```text id="v6knu8" +Disabled +``` + +the Mob Stand completely ignores that mob type. + +--- + +# Example Farm Setup + +### Breeding Farm + +Adult Filters: + +```text id="16mubg" +Cow ✓ +Pig ✓ +``` + +Baby Filters: + +```text id="w1cgrh" +Cow ✗ +Pig ✗ +``` + +Result: + +```text id="ikccfc" +Adults may be managed. +Babies are protected until they mature. ``` --- -# Configuring Filters +### Single Species Farm -Open the machine menu. +Adult Filters: -Select: - -```text -Filters +```text id="akd7zm" +Cow ✓ +Pig ✗ +Chicken ✗ +Sheep ✗ ``` -Add or remove items from the filter list as desired. +Result: + +```text id="5of87d" +Only cows are managed. +``` --- -# Typical Uses +# Tips -## Mob Farms +### Use Leave Alive Together With Filters -Collect: +Combining filters with Leave Alive settings provides maximum control. -* Bones -* Arrows -* Rotten Flesh +### Separate Different Farms -Ignore: +Use filters to prevent one Mob Stand from affecting unrelated mobs. -* Player-dropped items +### Protect Breeding Stock + +Disable baby filters when maintaining breeding populations. --- -## Mining Operations +# Related Pages -Collect: - -* Cobblestone -* Stone -* Ores - -Ignore: - -* Other farm resources - ---- - -## Storage Sorting - -Use multiple ItemMagnets with different filters to automatically route resources into separate storage systems. - ---- - -# Troubleshooting - -Item not being collected? - -Verify: - -* Item is included in the filter -* Item is within range -* Target container has available space - ---- - -# Best Practices - -Use filters whenever multiple ItemMagnets operate in the same area. - -This creates cleaner and more predictable automation systems. - ---- - -# Next Step - -Continue with: - -[Pause and Resume](Pause-and-Resume.md) +* Main Menu +* Radius Settings +* Leave Alive Settings +* Gravity Settings +* Pause and Resume diff --git a/docs/Gravity-Settings.md b/docs/Gravity-Settings.md new file mode 100644 index 0000000..48535d1 --- /dev/null +++ b/docs/Gravity-Settings.md @@ -0,0 +1,109 @@ +# Gravity Settings + +The Gravity setting controls whether a Mob Stand is affected by Minecraft's normal gravity mechanics. + +This allows players to create both grounded and floating Mob Stand designs. + +--- + +# What Gravity Does + +When gravity is enabled, the Mob Stand behaves like a normal Armor Stand and will fall if there is no supporting block beneath it. + +When gravity is disabled, the Mob Stand remains fixed in place. + +--- + +# Gravity Enabled + +With gravity enabled: + +```text +Gravity: Enabled +``` + +The Mob Stand will: + +* Fall when unsupported +* React to normal Minecraft physics +* Behave like a standard Armor Stand + +This is useful when you want the Mob Stand to remain part of a physical structure. + +--- + +# Gravity Disabled + +With gravity disabled: + +```text +Gravity: Disabled +``` + +The Mob Stand will: + +* Remain suspended in place +* Ignore normal falling behavior +* Stay exactly where it was positioned + +This is useful for: + +* Floating displays +* Decorative installations +* Elevated farm layouts +* Difficult-to-reach locations + +--- + +# Changing Gravity + +Open: + +```text +Main Menu + ↓ +Gravity +``` + +Click the Gravity option to toggle between enabled and disabled states. + +The change takes effect immediately. + +--- + +# Visual Indicator + +The Gravity button displays the current state. + +### Enabled + +The button appears active and indicates that gravity is currently enabled. + +### Disabled + +The button indicates that gravity is currently disabled. + +--- + +# Tips + +### Floating Farm Designs + +Disable gravity to keep Mob Stands suspended in midair. + +### Ground-Based Farms + +Enable gravity if you want the Mob Stand to behave like a normal Armor Stand. + +### Building Adjustments + +You can temporarily disable gravity while positioning a Mob Stand, then re-enable it afterward if desired. + +--- + +# Related Pages + +* Main Menu +* Radius Settings +* Leave Alive Settings +* Filters diff --git a/docs/Home.md b/docs/Home.md index b1a8fd6..11e1482 100644 --- a/docs/Home.md +++ b/docs/Home.md @@ -1,80 +1,110 @@ -# RS-ItemMagnet Documentation +# RS-MobStand Wiki -Welcome to the official RS-ItemMagnet documentation. +Welcome to the official RS-MobStand documentation. -RS-ItemMagnet is an automated item collection plugin for Paper Minecraft servers. It allows players to create ItemMagnets that collect dropped items and deliver them directly into designated storage containers. +RS-MobStand transforms ordinary Armor Stands into configurable Mob Stands capable of managing nearby mobs through an intuitive graphical interface. -Built for performance, reliability, multiplayer compatibility, and long-term server operation. +Designed for survival servers, RS-MobStand provides a lightweight and configurable alternative to traditional mob farm systems while maintaining excellent server performance. --- # Features -* Automated item collection -* Configurable collection radius -* Advanced item filtering -* Container assignment and reassignment -* Ownership protection -* Pause and resume controls -* SQLite persistence -* Chunk-safe operation -* Multiplayer support -* Administrative controls +### Mob Stand Conversion + +Convert ordinary Armor Stands into fully functional Mob Stands. + +### Radius Control + +Configure how far each Mob Stand scans for mobs. + +### Leave Alive Support + +Specify how many mobs remain alive while processing continues. + +### Adult Filters + +Control which adult mobs are managed by a Mob Stand. + +### Baby Filters + +Control which baby mobs are managed by a Mob Stand. + +### Gravity Toggle + +Enable or disable gravity for individual Mob Stands. + +### Pause / Resume + +Temporarily disable Mob Stand processing without removing the stand. + +### Ownership Protection + +Only the owner (or an administrator) can modify a Mob Stand. + +### Persistent Storage + +All Mob Stand settings survive server restarts. + +### Administrative Controls + +Built-in administrative tools for server operators. --- -# Quick Start +# Getting Started -1. Place a Lodestone. -2. Convert it into an RS-ItemMagnet. -3. Assign a target container. -4. Configure radius and filters. -5. Drop items within range. -6. Watch items get collected automatically. +1. Place an Armor Stand. +2. Sneak and right-click the Armor Stand while holding a Stick. +3. Convert the Armor Stand into a Mob Stand. +4. Configure the stand using the menu system. +5. Begin managing nearby mobs. --- -# Documentation Index +# Wiki Navigation -## Getting Started +## Player Guides -* [Installation](Installation.md) -* [Creating Your First ItemMagnet](Creating-Your-First-ItemMagnet.md) - -## Player Guide - -* [Filters](Filters.md) -* [Radius Settings](Radius-Settings.md) -* [Pause and Resume](Pause-and-Resume.md) +* Creating Your First Mob Stand +* Main Menu +* Radius Settings +* Leave Alive Settings +* Gravity Settings +* Filters +* Pause and Resume ## Administration -* [Admin Guide](Admin-Guide.md) -* [Troubleshooting](Troubleshooting.md) - -## Technical Information - -* [Storage and Persistence](Storage-and-Persistence.md) -* [Changelog](Changelog.md) +* Installation +* Permissions +* Admin Guide +* Troubleshooting +* Changelog --- # RS Ecosystem -RS-ItemMagnet is part of the RS Ecosystem. +RS-MobStand is part of the RS Ecosystem. ```text +Generate + │ + ▼ RS-MobStand - ↓ Generate - + │ +Collect + ▼ RS-ItemMagnet - ↓ Collect - + │ +Transport + ▼ RS-Auger - ↓ Transport - + │ +Store + ▼ RS-Warehouse - ↓ Store ``` Together these plugins create a complete automated resource collection and logistics system. @@ -83,10 +113,16 @@ Together these plugins create a complete automated resource collection and logis # Support -If you encounter a bug or have a feature request, please open an issue in the GitHub repository. +If you encounter an issue: + +1. Verify your plugin version. +2. Check the Troubleshooting page. +3. Gather any console errors. +4. Open a GitHub issue if necessary. --- -Built by RSScripting +# License -Big Pappa • Atlas +MIT License +Copyright © 2026 RSScripting diff --git a/docs/Installation.md b/docs/Installation.md index ed97502..0aaee2f 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -1,20 +1,22 @@ # Installation -This guide explains how to install RS-ItemMagnet on your Paper Minecraft server. +This guide explains how to install RS-MobStand on your Minecraft server. --- # Requirements +RS-MobStand requires: + * Minecraft 1.21+ * Paper Server -* Java 21+ +* Java 21 or newer --- # Download -Download the latest RS-ItemMagnet release from the GitHub Releases page. +Download the latest RS-MobStand release from the official GitHub repository. --- @@ -22,77 +24,84 @@ Download the latest RS-ItemMagnet release from the GitHub Releases page. ## Step 1 -Stop your Minecraft server. +Stop your server. --- ## Step 2 -Copy the RS-ItemMagnet jar file into your server's: +Place: -```text -plugins/ +```text id="xx4q8l" +RS-MobStand-x.x.x.jar ``` -directory. +into your server's: + +```text id="hbg7va" +plugins +``` + +folder. --- ## Step 3 -Start your server. +Start the server. -During startup RS-ItemMagnet will: - -* Create its data folder -* Create its SQLite database -* Create required database tables -* Register commands and permissions +RS-MobStand will automatically generate its configuration files. --- ## Step 4 -Verify successful startup. +Verify the plugin loads successfully. -You should see messages similar to: +You should see startup messages indicating RS-MobStand has been enabled. -```text -[RS-ItemMagnet] SQLite database initialized. -[RS-ItemMagnet] Database tables initialized. -[RS-ItemMagnet] RS-ItemMagnet Enabled +--- + +## Step 5 + +Configure settings if desired. + +Any configuration changes can be applied using: + +```text id="f9icq7" +Admin Menu + ↓ +Reload Config ``` +or by restarting the server. + --- # Updating -To update RS-ItemMagnet: +To update: 1. Stop the server. -2. Replace the existing jar file. +2. Replace the existing jar. 3. Start the server. -Machine data and configuration are preserved automatically. +Your Mob Stand data and configuration will remain intact. --- -# Uninstalling +# Verifying Installation -To remove RS-ItemMagnet: +Create a test Armor Stand. -1. Stop the server. -2. Remove the plugin jar. -3. Remove the RS-ItemMagnet data folder if desired. +Sneak and right-click it while holding a Stick. -Warning: - -Removing the data folder will permanently delete all ItemMagnet data. +If the Armor Stand converts successfully, the installation is complete. --- -# Next Step +# Related Pages -Continue with: - -[Creating Your First ItemMagnet](Creating-Your-First-ItemMagnet.md) +* Creating Your First Mob Stand +* Permissions +* Troubleshooting diff --git a/docs/Leave-Alive-Settings.md b/docs/Leave-Alive-Settings.md new file mode 100644 index 0000000..a676a17 --- /dev/null +++ b/docs/Leave-Alive-Settings.md @@ -0,0 +1,134 @@ +# Leave Alive Settings + +The Leave Alive setting determines how many matching mobs should remain alive within a Mob Stand's operating area. + +This allows players to automate mob management while still maintaining a breeding population, display mobs, or farm infrastructure. + +--- + +# What Leave Alive Does + +When a Mob Stand processes matching mobs, it will stop once the configured number of mobs remains. + +Example: + +```text +Leave Alive: 5 +``` + +Current matching mobs: + +```text +15 Cows +``` + +Result: + +```text +10 Cows Processed +5 Cows Remain Alive +``` + +--- + +# Why Use Leave Alive? + +Leave Alive gives you greater control over your farms. + +Common uses include: + +* Maintaining breeding stock +* Preventing complete farm depletion +* Keeping decorative mobs alive +* Controlling resource production rates + +--- + +# Setting Leave Alive + +Open: + +```text +Main Menu + ↓ +Leave Alive +``` + +Adjust the value to the desired amount. + +The Mob Stand will automatically respect this limit during operation. + +--- + +# Example Configurations + +## Leave Alive: 0 + +```text +All matching mobs may be processed. +``` + +Best for: + +* Resource-only farms +* Maximum production + +--- + +## Leave Alive: 2 + +```text +Always leave two matching mobs alive. +``` + +Best for: + +* Basic breeding farms +* Simple population maintenance + +--- + +## Leave Alive: 10 + +```text +Maintain a larger breeding population. +``` + +Best for: + +* Large animal farms +* Decorative enclosures +* High-growth breeding systems + +--- + +# Tips + +### Breeding Farms + +A Leave Alive value of 2 or more is recommended. + +### Decorative Areas + +Use a higher Leave Alive value to maintain the desired appearance. + +### Resource Farms + +Use a lower value if maximum production is the goal. + +--- + +# Important Notes + +Leave Alive only applies to mobs that match the current filter settings. + +If a mob is not included in the filters, it is ignored entirely by the Mob Stand. + +--- + +# Related Pages + +* Main Menu +* Radius Settings +* Filters +* Pause and Resume diff --git a/docs/Main-Menu.md b/docs/Main-Menu.md new file mode 100644 index 0000000..f753587 --- /dev/null +++ b/docs/Main-Menu.md @@ -0,0 +1,121 @@ +# Main Menu + +The Main Menu is the central control panel for your Mob Stand. + +To open it, simply right-click your Mob Stand. + +From here you can access all configuration options available to the stand. + +--- + +# Main Menu Options + +## Convert Back to Armor Stand + +Returns the Mob Stand to a normal Armor Stand. + +Use this option if you no longer need automated mob management. + +**Warning:** Any Mob Stand configuration will be removed. + +--- + +## Admin Menu + +**Operators Only** + +Provides access to administrative tools and plugin information. + +This option is only visible to server operators and administrators. + +--- + +## Pause / Resume Processing + +Temporarily enables or disables Mob Stand processing. + +### When Enabled + +The Mob Stand will continue managing nearby mobs normally. + +### When Disabled + +The Mob Stand remains configured but will not process mobs until re-enabled. + +--- + +## Scan Radius + +Controls how far the Mob Stand searches for nearby mobs. + +Larger radii cover more area but may process additional mobs. + +Select this option to open the Radius Settings menu. + +--- + +## Gravity + +Controls whether the Mob Stand is affected by gravity. + +### Enabled + +The Mob Stand behaves like a normal Armor Stand and can fall. + +### Disabled + +The Mob Stand remains fixed in place. + +--- + +## Leave Alive + +Determines how many matching mobs should remain alive. + +Example: + +```text +Leave Alive: 5 +``` + +If ten matching mobs are present, the Mob Stand will only process five and leave five alive. + +Select this option to open the Leave Alive Settings menu. + +--- + +## Adult Filters + +Configure which adult mobs are managed by this Mob Stand. + +Only enabled adult mob types will be processed. + +Select this option to open the Adult Filters menu. + +--- + +## Baby Filters + +Configure which baby mobs are managed by this Mob Stand. + +Only enabled baby mob types will be processed. + +Select this option to open the Baby Filters menu. + +--- + +# Menu Layout + +Depending on permissions and server settings, some menu options may appear differently. + +Administrators may have access to additional controls. + +--- + +# Related Pages + +* Radius Settings +* Leave Alive Settings +* Filters +* Pause and Resume +* Admin Guide diff --git a/docs/Pause-and-Resume.md b/docs/Pause-and-Resume.md index 3a9e235..90cb0f3 100644 --- a/docs/Pause-and-Resume.md +++ b/docs/Pause-and-Resume.md @@ -1,78 +1,129 @@ # Pause and Resume -RS-ItemMagnet machines can be temporarily paused without removing the machine or changing its configuration. +The Pause feature allows you to temporarily disable a Mob Stand without removing it or changing its configuration. + +This is useful when performing maintenance, redesigning farms, or temporarily stopping resource generation. --- -# Why Pause a Machine? +# What Pause Does -Pausing allows you to temporarily stop item collection while keeping: +When a Mob Stand is paused: -* Radius settings +```text id="hldq1q" +Processing Stops +``` + +The Mob Stand remains fully configured but will not manage mobs until processing is resumed. + +All settings remain intact, including: + +* Radius +* Leave Alive +* Adult Filters +* Baby Filters +* Gravity Settings + +--- + +# What Pause Does Not Do + +Pausing a Mob Stand does not: + +* Remove the Mob Stand +* Reset any settings +* Change ownership +* Affect filter configuration +* Convert the Mob Stand back into an Armor Stand + +Think of Pause as an on/off switch for processing. + +--- + +# Pausing a Mob Stand + +Open: + +```text id="s41m2x" +Main Menu + ↓ +Pause Processing +``` + +Once paused, the Mob Stand will stop managing nearby mobs. + +--- + +# Resuming a Mob Stand + +Open: + +```text id="8dxvt0" +Main Menu + ↓ +Resume Processing +``` + +The Mob Stand immediately returns to normal operation using its existing configuration. + +--- + +# Why Use Pause? + +Common reasons include: + +### Farm Maintenance + +Temporarily stop processing while making changes to a farm. + +### Testing Configurations + +Experiment with settings without permanently changing farm behavior. + +### Resource Management + +Disable production until resources are needed. + +### Seasonal Events + +Temporarily disable farms without removing player setups. + +--- + +# Visual Indicators + +The Pause button displays the current state of the Mob Stand. + +### Processing Enabled + +The Mob Stand is actively managing nearby mobs. + +### Processing Disabled + +The Mob Stand is paused and will not process mobs. + +--- + +# Tips + +### Use Pause Before Major Changes + +If you're redesigning a farm, pause the Mob Stand first. + +### No Reconfiguration Required + +After resuming, all previous settings remain unchanged. + +### Safe to Leave Paused + +A Mob Stand can remain paused indefinitely until processing is resumed. + +--- + +# Related Pages + +* Main Menu +* Radius Settings +* Leave Alive Settings * Filters -* Ownership -* Container assignments - -fully intact. - ---- - -# Pausing a Machine - -Open the machine menu. - -Select: - -```text -Pause -``` - -The machine will immediately stop collecting items. - -Any items within range will remain on the ground. - ---- - -# Resuming a Machine - -Open the machine menu. - -Select: - -```text -Resume -``` - -The machine will resume normal operation and continue collecting items. - ---- - -# Typical Uses - -## Maintenance - -Pause the machine while modifying nearby farms or storage systems. - -## Storage Changes - -Pause collection while reorganizing containers. - -## Troubleshooting - -Pause a machine to isolate automation issues during testing. - ---- - -# Notes - -Pausing does not remove or alter machine settings. - -The machine can be resumed at any time. - ---- - -# Next Step - -Continue with: - -[Admin Guide](Admin-Guide.md) +* Gravity Settings diff --git a/docs/Permissions.md b/docs/Permissions.md index aec5bae..67af965 100644 --- a/docs/Permissions.md +++ b/docs/Permissions.md @@ -1,74 +1,171 @@ # Permissions -RS-ItemMagnet supports permissions for players and administrators. +RS-MobStand uses permissions to control who can create, manage, and administer Mob Stands. + +Server owners can use these permissions to grant access to players, moderators, and administrators. --- # Player Permissions -## rsim.use - -Allows players to use RS-ItemMagnet features. - -Default: +## Use RS-MobStand ```text -true +rsmobstand.use +``` + +Allows a player to: + +* Convert Armor Stands into Mob Stands +* Open Mob Stand menus +* Configure owned Mob Stands +* Use normal plugin functionality + +Recommended for: + +```text +All Players ``` --- # Administrative Permissions -## rsim.admin - -Provides access to administrative functions. - -Default: +## Admin Access ```text -op +rsmobstand.admin ``` -Allows: +Allows a player to: -* Administrative menus -* Ownership bypass -* Machine management -* Troubleshooting assistance +* Access the Admin Menu +* Bypass ownership restrictions +* Modify Mob Stands owned by other players +* Assist with troubleshooting + +Recommended for: + +```text +Administrators +Moderators +Trusted Staff +``` --- # Ownership Protection -Machine owners retain control of their ItemMagnets. +Even with normal use permissions, players may only modify Mob Stands they own. -Players without appropriate permissions cannot: +Ownership is automatically assigned when a player converts an Armor Stand into a Mob Stand. -* Modify settings -* Change filters -* Reassign containers -* Remove machines +Without administrative permissions: + +```text +Player A + └─ Can modify Player A's Mob Stands + +Player B + └─ Cannot modify Player A's Mob Stands +``` + +With: + +```text +rsmobstand.admin +``` + +ownership restrictions may be bypassed. --- -# Recommended Setup +# Recommended Permission Setup + +## Survival Servers Players: ```text -rsim.use +rsmobstand.use ``` -Staff: +Administrators: ```text -rsim.admin +rsmobstand.use +rsmobstand.admin ``` --- -# Related Documentation +## Staff Teams + +Moderators: + +```text +rsmobstand.use +rsmobstand.admin +``` + +Administrators: + +```text +rsmobstand.use +rsmobstand.admin +``` + +--- + +# Permission Plugins + +RS-MobStand works with common permission systems including: + +* LuckPerms +* PermissionsEx +* GroupManager +* Other Bukkit-compatible permission managers + +--- + +# Troubleshooting + +### Players Cannot Create Mob Stands + +Verify: + +```text +rsmobstand.use +``` + +has been granted. + +--- + +### Staff Cannot Access Admin Features + +Verify: + +```text +rsmobstand.admin +``` + +has been granted. + +--- + +### Player Cannot Modify Their Mob Stand + +Verify: + +* The player owns the Mob Stand. +* The player has the required permissions. +* The Mob Stand was successfully converted. + +--- + +# Related Pages * Admin Guide +* Creating Your First Mob Stand * Troubleshooting diff --git a/docs/Radius-Settings.md b/docs/Radius-Settings.md index 9b4add6..d4be076 100644 --- a/docs/Radius-Settings.md +++ b/docs/Radius-Settings.md @@ -1,82 +1,86 @@ # Radius Settings -Radius settings control how far an RS-ItemMagnet can detect and collect dropped items. +The Radius setting controls how far a Mob Stand searches for nearby mobs. + +Adjusting the radius allows you to balance coverage, efficiency, and farm design. --- -# What Is Radius? +# What Radius Does -The collection radius determines the area around the ItemMagnet where dropped items can be detected. +The Mob Stand scans for matching mobs within its configured radius. -Items outside the configured radius will be ignored. +Only mobs located within this area are eligible for processing. --- # Increasing Radius -Larger radii allow the machine to collect items from a wider area. +A larger radius allows a Mob Stand to cover a wider area. Benefits: -* Larger collection area -* Fewer machines required -* Better coverage for large farms +* Covers larger farms +* Detects mobs farther away +* Reduces the need for multiple Mob Stands Considerations: -* More items may be scanned -* Larger collection zones may overlap +* May include mobs you did not intend to manage +* May overlap with other Mob Stands --- # Decreasing Radius -Smaller radii restrict collection to nearby items. +A smaller radius limits the Mob Stand to a more focused area. Benefits: -* More precise collection -* Better separation between machines -* Easier farm specialization +* Greater precision +* Easier farm separation +* Better control over specific mob groups --- -# Choosing the Right Radius +# Choosing a Radius -Small Farms: +The ideal radius depends on your farm design. -```text -Small Radius -``` +### Small Farms -Large Farms: +Use a smaller radius to target a specific enclosure. -```text -Medium to Large Radius -``` +### Large Farms -Industrial Automation Systems: +Use a larger radius to cover the entire farm area. -```text -Use the smallest radius necessary -``` +### Multiple Mob Stands -to maintain predictable item routing. +When using several Mob Stands nearby, consider reducing radius values to prevent excessive overlap. --- -# Troubleshooting +# Radius Limits -If items are not being collected: +Server administrators may configure a maximum radius. -* Verify the item is inside the configured radius -* Verify filters allow the item -* Verify the target container has available space +If a radius exceeds the server limit, the Mob Stand will automatically use the highest allowed value. --- -# Next Step +# Tips -Continue with: +* Start small and increase as needed. +* Avoid unnecessarily large radii. +* Verify the Mob Stand is affecting the intended mobs. +* Use filters alongside radius settings for maximum control. -[Filters](Filters.md) +--- + +# Related Pages + +* Main Menu +* Leave Alive Settings +* Filters +* Pause and Resume diff --git a/docs/Storage-and-Persistence.md b/docs/Storage-and-Persistence.md deleted file mode 100644 index 39b1ba2..0000000 --- a/docs/Storage-and-Persistence.md +++ /dev/null @@ -1,79 +0,0 @@ -# Storage and Persistence - -RS-ItemMagnet uses SQLite to store machine data. - -This allows machine information to persist automatically across server restarts and reloads. - ---- - -# What Is Stored? - -The following information is stored: - -* Machine location -* Owner information -* Assigned container -* Radius settings -* Filter configuration -* Machine status - ---- - -# Persistence Features - -RS-ItemMagnet automatically preserves machine data across: - -* Server restarts -* Chunk unloads -* Chunk reloads -* Player disconnects -* Player reconnects - -No manual intervention is required. - ---- - -# Database System - -RS-ItemMagnet uses SQLite. - -Benefits include: - -* No external database required -* Simple setup -* Reliable storage -* Fast lookups -* Easy backups - ---- - -# Backups - -Server administrators should include the RS-ItemMagnet data folder in normal server backup procedures. - -This ensures all machine information can be restored if necessary. - ---- - -# Database Safety - -Machine data is automatically saved and updated as changes occur. - -Unexpected server shutdowns should not normally result in data loss. - ---- - -# Troubleshooting - -If machine data appears missing: - -1. Verify the database file exists. -2. Check server logs for database errors. -3. Restore from backup if necessary. - ---- - -# Related Documentation - -* Troubleshooting -* Admin Guide diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index 86e8705..7c60a4c 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -1,107 +1,265 @@ # Troubleshooting -This guide covers common issues and their solutions. +This guide covers the most common issues encountered when using RS-MobStand and provides steps to resolve them. --- -# Machine Not Collecting Items +# Mob Stand Will Not Convert -## Target Container Missing +### Symptoms -The assigned container no longer exists. +* Sneak-right-clicking an Armor Stand does nothing. +* The conversion does not occur. -Symptoms: +### Check -* Machine shows a warning state. -* Items remain on the ground. +Verify that: -Solution: +* You are holding a Stick. +* You are sneaking. +* You have the required permission. +* The target is a normal Armor Stand. -* Replace the container. -* Reassign the target container if necessary. +### Solution + +Ensure you are: + +```text id="6rj03f" +Sneaking ++ +Holding a Stick ++ +Right-Clicking an Armor Stand +``` --- -## Container Full +# Cannot Open Mob Stand Menu -The target container has no available space. +### Symptoms -Symptoms: +* Right-clicking a Mob Stand does nothing. +* The menu does not appear. -* Items remain on the ground. -* Machine appears operational. +### Check -Solution: +Verify that: -* Remove items from the container. -* Expand storage capacity. +* The stand is already converted. +* You own the Mob Stand. +* You have permission to use Mob Stands. -RS-ItemMagnet automatically resumes collection when space becomes available. +### Solution + +Try interacting with a Mob Stand that you own. + +Administrators can bypass ownership restrictions using: + +```text id="jhy0k0" +rsmobstand.admin +``` --- -## Filter Blocking Items +# "You Do Not Own This Mob Stand" -The item is not allowed by the machine's filter configuration. +### Symptoms -Solution: +You receive an ownership error message. -* Review filter settings. -* Add the desired item to the filter. +### Cause + +The Mob Stand belongs to another player. + +### Solution + +* Use your own Mob Stand. +* Ask the owner for assistance. +* Have an administrator assist you. + +Administrators with: + +```text id="3u4r6l" +rsmobstand.admin +``` + +may bypass ownership restrictions. --- -## Item Outside Radius +# Mob Stand Is Not Processing Mobs -The item is located outside the configured collection area. +### Check Pause Status -Solution: +Verify the Mob Stand is not paused. -* Increase radius. -* Move the machine closer to the collection area. +Open: + +```text id="50s1d7" +Main Menu + ↓ +Pause / Resume +``` + +and ensure processing is enabled. --- -# Machine Lost After Restart +### Check Radius -RS-ItemMagnet stores machine data in SQLite. +Verify the configured radius is large enough to reach the intended mobs. -Machine data should automatically persist across: +Open: -* Server restarts -* Chunk unloads -* Player relogs +```text id="kce0j6" +Main Menu + ↓ +Radius +``` -If data is missing, contact the server administrator. +and review the current value. --- -# Ownership Problems +### Check Filters -Only the machine owner may modify settings. +Verify the mob type is enabled in the appropriate filter menu. -Administrators with appropriate permissions may bypass ownership restrictions. +Review: + +* Adult Filters +* Baby Filters + +If a mob is disabled in filters, it will be ignored. + +--- + +### Check Leave Alive + +Verify the Leave Alive setting is not preventing additional processing. + +Example: + +```text id="j11jv0" +Leave Alive: 10 +``` + +If only ten matching mobs exist, no additional processing will occur. + +--- + +# Mobs Are Being Ignored + +### Cause + +The mob type may be disabled in filters. + +### Solution + +Open: + +```text id="yzr39t" +Adult Filters +``` + +or + +```text id="jq4z32" +Baby Filters +``` + +and verify the desired mob type is enabled. + +--- + +# Gravity Is Not Working As Expected + +### Cause + +Gravity may be disabled. + +### Solution + +Open: + +```text id="r5g7t1" +Main Menu + ↓ +Gravity +``` + +and verify the current setting. + +--- + +# Configuration Changes Are Not Taking Effect + +### Cause + +The configuration may not have been reloaded. + +### Solution + +Administrators can use: + +```text id="db0vtg" +Admin Menu + ↓ +Reload Config +``` + +after making configuration changes. + +--- + +# Version Status Shows "Unable To Check" + +### Cause + +The plugin could not contact the update source. + +Possible reasons: + +* No internet access +* GitHub unavailable +* Repository is private + +### Solution + +This does not affect plugin operation. + +RS-MobStand will continue functioning normally. + +--- + +# Server Performance Concerns + +### Recommendations + +* Avoid excessively large radius values. +* Use filters to limit processing. +* Only create Mob Stands where needed. +* Review server performance regularly. --- # Still Need Help? -If the problem persists: +Before requesting support, gather: -1. Verify plugin version. -2. Review server logs. -3. Open an issue on the GitHub repository. +* Minecraft Version +* Paper Version +* RS-MobStand Version +* Screenshots (if applicable) +* Console Errors (if applicable) + +Providing this information helps resolve issues more quickly. --- -# Known Behavior +# Related Pages -## Full Containers - -When a container becomes full: - -* Items remain on the ground. -* No items are lost. -* Collection automatically resumes when storage space becomes available. - -This behavior is intentional. +* Installation +* Permissions +* Admin Guide +* Main Menu diff --git a/readme.md b/readme.md index 7d7d9fe..cf04f5f 100644 --- a/readme.md +++ b/readme.md @@ -48,7 +48,7 @@ See the complete documentation: - [Home](docs/Home.md) - [Installation](docs/Installation.md) -- [Creating Your First ItemMagnet](docs/Creating-Your-First-ItemMagnet.md) +- [Creating Your First ItemMagnet](docs/Creating-Your-First-MobStand.md) - [Filters](docs/Filters.md) - [Radius Settings](docs/Radius-Settings.md) - [Pause and Resume](docs/Pause-and-Resume.md)