Commit:

"Add complete documentation system"

Push

Tag ItemMagnet as complete

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)

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.

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)

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)

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

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)

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)

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

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)

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

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.