diff --git a/docs/Admin-Guide.md b/docs/Admin-Guide.md new file mode 100644 index 0000000..e408e22 --- /dev/null +++ b/docs/Admin-Guide.md @@ -0,0 +1,67 @@ +# Admin Guide + +This guide covers administrative controls and management of RS-ItemMagnet. + +--- + +# Administrative Access + +Administrators with the appropriate permissions can manage ItemMagnets regardless of ownership. + +--- + +# Common Administrative Tasks + +## Inspect Machines + +View machine settings and configuration. + +## Modify Machines + +Adjust: + +* Radius +* Filters +* Assigned containers +* Operational state + +## Remove Machines + +Remove invalid, abandoned, or problematic ItemMagnets. + +--- + +# Ownership System + +RS-ItemMagnet uses ownership protection. + +Normally only the owner may modify a machine. + +Administrators can bypass ownership restrictions when necessary. + +--- + +# Troubleshooting Player Issues + +Common causes of collection problems: + +* Missing target container +* Full container +* Incorrect filter settings +* Items outside collection radius + +--- + +# Best Practices + +Use administrative controls sparingly. + +Allow players to manage their own automation systems whenever possible. + +--- + +# Next Step + +Continue with: + +[Troubleshooting](Troubleshooting.md) diff --git a/docs/Changelog.md b/docs/Changelog.md new file mode 100644 index 0000000..3ba3f52 --- /dev/null +++ b/docs/Changelog.md @@ -0,0 +1,40 @@ +# 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 + +--- + +## Future Releases + +Future changes will be documented here. diff --git a/docs/Creating-Your-First-ItemMagnet.md b/docs/Creating-Your-First-ItemMagnet.md new file mode 100644 index 0000000..bbccd7b --- /dev/null +++ b/docs/Creating-Your-First-ItemMagnet.md @@ -0,0 +1,126 @@ +# 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/Filters.md b/docs/Filters.md new file mode 100644 index 0000000..87878a6 --- /dev/null +++ b/docs/Filters.md @@ -0,0 +1,107 @@ +# Filters + +Filters allow ItemMagnets to collect only specific items. + +This allows multiple ItemMagnets to operate in the same area while collecting different resources. + +--- + +# Why Use Filters? + +Without filters: + +```text +ItemMagnet +→ Collects Everything +``` + +With filters: + +```text +ItemMagnet A +→ Cobblestone + +ItemMagnet B +→ Iron + +ItemMagnet C +→ Redstone +``` + +--- + +# Configuring Filters + +Open the machine menu. + +Select: + +```text +Filters +``` + +Add or remove items from the filter list as desired. + +--- + +# Typical Uses + +## Mob Farms + +Collect: + +* Bones +* Arrows +* Rotten Flesh + +Ignore: + +* Player-dropped items + +--- + +## Mining Operations + +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) diff --git a/docs/Home.md b/docs/Home.md new file mode 100644 index 0000000..b1a8fd6 --- /dev/null +++ b/docs/Home.md @@ -0,0 +1,92 @@ +# RS-ItemMagnet Documentation + +Welcome to the official RS-ItemMagnet 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. + +Built for performance, reliability, multiplayer compatibility, and long-term server operation. + +--- + +# 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 + +--- + +# Quick Start + +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. + +--- + +# Documentation Index + +## Getting Started + +* [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) + +## Administration + +* [Admin Guide](Admin-Guide.md) +* [Troubleshooting](Troubleshooting.md) + +## Technical Information + +* [Storage and Persistence](Storage-and-Persistence.md) +* [Changelog](Changelog.md) + +--- + +# RS Ecosystem + +RS-ItemMagnet is part of the RS Ecosystem. + +```text +RS-MobStand + ↓ Generate + +RS-ItemMagnet + ↓ Collect + +RS-Auger + ↓ Transport + +RS-Warehouse + ↓ Store +``` + +Together these plugins create a complete automated resource collection and logistics system. + +--- + +# Support + +If you encounter a bug or have a feature request, please open an issue in the GitHub repository. + +--- + +Built by RSScripting + +Big Pappa • Atlas diff --git a/docs/Installation.md b/docs/Installation.md new file mode 100644 index 0000000..ed97502 --- /dev/null +++ b/docs/Installation.md @@ -0,0 +1,98 @@ +# Installation + +This guide explains how to install RS-ItemMagnet on your Paper Minecraft server. + +--- + +# Requirements + +* Minecraft 1.21+ +* Paper Server +* Java 21+ + +--- + +# Download + +Download the latest RS-ItemMagnet release from the GitHub Releases page. + +--- + +# Installation Steps + +## Step 1 + +Stop your Minecraft server. + +--- + +## Step 2 + +Copy the RS-ItemMagnet jar file into your server's: + +```text +plugins/ +``` + +directory. + +--- + +## Step 3 + +Start your server. + +During startup RS-ItemMagnet will: + +* Create its data folder +* Create its SQLite database +* Create required database tables +* Register commands and permissions + +--- + +## Step 4 + +Verify successful startup. + +You should see messages similar to: + +```text +[RS-ItemMagnet] SQLite database initialized. +[RS-ItemMagnet] Database tables initialized. +[RS-ItemMagnet] RS-ItemMagnet Enabled +``` + +--- + +# Updating + +To update RS-ItemMagnet: + +1. Stop the server. +2. Replace the existing jar file. +3. Start the server. + +Machine data and configuration are preserved automatically. + +--- + +# Uninstalling + +To remove RS-ItemMagnet: + +1. Stop the server. +2. Remove the plugin jar. +3. Remove the RS-ItemMagnet data folder if desired. + +Warning: + +Removing the data folder will permanently delete all ItemMagnet data. + +--- + +# Next Step + +Continue with: + +[Creating Your First ItemMagnet](Creating-Your-First-ItemMagnet.md) diff --git a/docs/Pause-and-Resume.md b/docs/Pause-and-Resume.md new file mode 100644 index 0000000..3a9e235 --- /dev/null +++ b/docs/Pause-and-Resume.md @@ -0,0 +1,78 @@ +# Pause and Resume + +RS-ItemMagnet machines can be temporarily paused without removing the machine or changing its configuration. + +--- + +# Why Pause a Machine? + +Pausing allows you to temporarily stop item collection while keeping: + +* Radius 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) diff --git a/docs/Permissions.md b/docs/Permissions.md new file mode 100644 index 0000000..aec5bae --- /dev/null +++ b/docs/Permissions.md @@ -0,0 +1,74 @@ +# Permissions + +RS-ItemMagnet supports permissions for players and administrators. + +--- + +# Player Permissions + +## rsim.use + +Allows players to use RS-ItemMagnet features. + +Default: + +```text +true +``` + +--- + +# Administrative Permissions + +## rsim.admin + +Provides access to administrative functions. + +Default: + +```text +op +``` + +Allows: + +* Administrative menus +* Ownership bypass +* Machine management +* Troubleshooting assistance + +--- + +# Ownership Protection + +Machine owners retain control of their ItemMagnets. + +Players without appropriate permissions cannot: + +* Modify settings +* Change filters +* Reassign containers +* Remove machines + +--- + +# Recommended Setup + +Players: + +```text +rsim.use +``` + +Staff: + +```text +rsim.admin +``` + +--- + +# Related Documentation + +* Admin Guide +* Troubleshooting diff --git a/docs/Radius-Settings.md b/docs/Radius-Settings.md new file mode 100644 index 0000000..9b4add6 --- /dev/null +++ b/docs/Radius-Settings.md @@ -0,0 +1,82 @@ +# Radius Settings + +Radius settings control how far an RS-ItemMagnet can detect and collect dropped items. + +--- + +# What Is Radius? + +The collection radius determines the area around the ItemMagnet where dropped items can be detected. + +Items outside the configured radius will be ignored. + +--- + +# Increasing Radius + +Larger radii allow the machine to collect items from a wider area. + +Benefits: + +* Larger collection area +* Fewer machines required +* Better coverage for large farms + +Considerations: + +* More items may be scanned +* Larger collection zones may overlap + +--- + +# Decreasing Radius + +Smaller radii restrict collection to nearby items. + +Benefits: + +* More precise collection +* Better separation between machines +* Easier farm specialization + +--- + +# Choosing the Right Radius + +Small Farms: + +```text +Small Radius +``` + +Large Farms: + +```text +Medium to Large Radius +``` + +Industrial Automation Systems: + +```text +Use the smallest radius necessary +``` + +to maintain predictable item routing. + +--- + +# Troubleshooting + +If items are not being collected: + +* Verify the item is inside the configured radius +* Verify filters allow the item +* Verify the target container has available space + +--- + +# Next Step + +Continue with: + +[Filters](Filters.md) diff --git a/docs/Storage-and-Persistence.md b/docs/Storage-and-Persistence.md new file mode 100644 index 0000000..39b1ba2 --- /dev/null +++ b/docs/Storage-and-Persistence.md @@ -0,0 +1,79 @@ +# 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 new file mode 100644 index 0000000..86e8705 --- /dev/null +++ b/docs/Troubleshooting.md @@ -0,0 +1,107 @@ +# Troubleshooting + +This guide covers common issues and their solutions. + +--- + +# Machine Not Collecting Items + +## Target Container Missing + +The assigned container no longer exists. + +Symptoms: + +* Machine shows a warning state. +* Items remain on the ground. + +Solution: + +* Replace the container. +* Reassign the target container if necessary. + +--- + +## Container Full + +The target container has no available space. + +Symptoms: + +* Items remain on the ground. +* Machine appears operational. + +Solution: + +* Remove items from the container. +* Expand storage capacity. + +RS-ItemMagnet automatically resumes collection when space becomes available. + +--- + +## Filter Blocking Items + +The item is not allowed by the machine's filter configuration. + +Solution: + +* Review filter settings. +* Add the desired item to the filter. + +--- + +## Item Outside Radius + +The item is located outside the configured collection area. + +Solution: + +* Increase radius. +* Move the machine closer to the collection area. + +--- + +# Machine Lost After Restart + +RS-ItemMagnet stores machine data in SQLite. + +Machine data should automatically persist across: + +* Server restarts +* Chunk unloads +* Player relogs + +If data is missing, contact the server administrator. + +--- + +# Ownership Problems + +Only the machine owner may modify settings. + +Administrators with appropriate permissions may bypass ownership restrictions. + +--- + +# Still Need Help? + +If the problem persists: + +1. Verify plugin version. +2. Review server logs. +3. Open an issue on the GitHub repository. + +--- + +# Known Behavior + +## 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. diff --git a/readme.md b/readme.md index 49ae141..7d7d9fe 100644 --- a/readme.md +++ b/readme.md @@ -44,8 +44,9 @@ RS-MobStand replaces those systems with a clean, configurable solution that is e ## Documentation -See the documentation inside the docs folder: +See the complete documentation: +- [Home](docs/Home.md) - [Installation](docs/Installation.md) - [Creating Your First ItemMagnet](docs/Creating-Your-First-ItemMagnet.md) - [Filters](docs/Filters.md) @@ -54,6 +55,7 @@ See the documentation inside the docs folder: - [Admin Guide](docs/Admin-Guide.md) - [Troubleshooting](docs/Troubleshooting.md) - [Storage and Persistence](docs/Storage-and-Persistence.md) +- [Permissions](docs/Permissions.md) - [Changelog](docs/Changelog.md) # Features @@ -209,11 +211,11 @@ If you encounter a bug or have a feature request, please open an issue in the Gi # License -Copyright © 2026 RSScripting +# License -All rights reserved. +This project is licensed under the MIT License. -This project may not be copied, modified, redistributed, or sold without explicit written permission from RSScripting. +See the LICENSE file for details. --- @@ -224,8 +226,3 @@ This project may not be copied, modified, redistributed, or sold without explici
Generate • Collect • Transport • Store
- - -- Generate • Collect • Transport • Store -