Initial RS-ItemMagnet repository

docs/commands.md

@@ -0,0 +1,21 @@
+# Commands
+
+The main plugin command is:
+
+```text
+/rsim
+```
+
+## `/rsim`
+
+Displays the running RS-ItemMagnet plugin information.
+
+## `/rsim version`
+
+Displays the installed RS-ItemMagnet version.
+
+## `/rsim reload`
+
+Reloads the RS-ItemMagnet configuration.
+
+This command requires the admin permission.

docs/configuration.md

@@ -0,0 +1,91 @@
+# Configuration
+
+The configuration file is located at:
+
+`plugins/RS-ItemMagnet/config.yml`
+
+## Current Settings
+
+```yaml
+# Default scan radius for RS-ItemMagnet to scan for dropped items.
+default-radius: 10
+
+# Maximum radius players may set their RS-ItemMagnets to.
+# 0 = Unlimited.
+max-radius: 25
+
+# Seconds allowed to select a target Container.
+conversion-timeout: 30
+
+# Distance in blocks ABOVE and BELOW the magnet
+# that items may be collected from.
+#
+# 0 = Unlimited (legacy behavior)
+# >0 = Limit vertical collection distance.
+item-y-distance: 0
+
+# Whether OP players bypass permissions checks
+admin-bypass: true
+
+# Enable debug logging.
+debug-mode: false
+```
+
+## `default-radius`
+
+Sets the starting collection radius for newly created ItemMagnets.
+
+Default:
+
+`10`
+
+## `max-radius`
+
+Sets the maximum radius players may configure on an ItemMagnet.
+
+`0` means unlimited.
+
+Default:
+
+`25`
+
+## `conversion-timeout`
+
+Sets how many seconds a player has to select a target container during conversion.
+
+Default:
+
+`30`
+
+## `item-y-distance`
+
+Controls the vertical collection distance above and below the magnet.
+
+- `0` = unlimited vertical distance, preserving the legacy behavior.
+- `1` = collect up to 1 block above and 1 block below.
+- `2` = collect up to 2 blocks above and 2 blocks below.
+- Higher values increase the allowed vertical distance accordingly.
+
+Default:
+
+`0`
+
+## `admin-bypass`
+
+When enabled, OP players can bypass permission checks used by the plugin.
+
+Default:
+
+`true`
+
+## `debug-mode`
+
+Enables additional debug logging for troubleshooting.
+
+Default:
+
+`false`
+
+## Configuration Migration
+
+RS-ItemMagnet checks for missing configuration settings when it starts. New settings can be added to an existing configuration without replacing the server owner's existing values.

docs/index.md

@@ -0,0 +1,42 @@
+# RS-ItemMagnet Documentation
+
+RS-ItemMagnet is an automated item collection plugin for Paper Minecraft servers.
+
+## Documentation
+
+- [Installation](installation.md)
+- [Usage](usage.md)
+- [Configuration](configuration.md)
+- [Commands](commands.md)
+- [Permissions](permissions.md)
+- [Troubleshooting](troubleshooting.md)
+
+## What RS-ItemMagnet Does
+
+An ItemMagnet converts a lodestone into an automated item collector. It scans for dropped items within its configured radius and deposits accepted items into a configured hopper, chest, or barrel.
+
+ItemMagnets are configured through inventory menus and store their machine data persistently using SQLite.
+
+## Core Features
+
+- Configurable collection radius
+- Automatic item collection
+- Target hopper, chest, or barrel assignment
+- Target reassignment after conversion
+- Item filtering
+- Pause and resume controls
+- Radius preview using a temporary particle outline
+- Vertical collection-distance control
+- SQLite persistence
+- Administrative controls
+- OP update-available notification
+
+## Requirements
+
+- Paper 1.21+
+- Java version supported by the Paper version being used
+- A server with permission support
+
+## License
+
+RS-ItemMagnet is released under the MIT License.

docs/installation.md

@@ -0,0 +1,24 @@
+# Installation
+
+## Requirements
+
+RS-ItemMagnet is built for Paper Minecraft servers using the 1.21 API line.
+
+## Install
+
+1. Download the latest RS-ItemMagnet release.
+2. Place the plugin JAR in the server's `plugins` folder.
+3. Start or restart the server.
+4. Confirm that RS-ItemMagnet enables successfully in the server console.
+5. Review `plugins/RS-ItemMagnet/config.yml` and adjust settings if needed.
+
+The plugin creates and initializes its SQLite database automatically.
+
+## Updating
+
+1. Stop the server.
+2. Replace the existing RS-ItemMagnet JAR with the new version.
+3. Start the server.
+4. Allow the plugin to perform any configuration migrations required by the new version.
+
+When a new configuration setting is introduced, RS-ItemMagnet is designed to add missing settings without replacing the server owner's existing configuration values.

docs/permissions.md

@@ -0,0 +1,21 @@
+# Permissions
+
+## `rsitemagnet.admin`
+
+Provides administrative access to RS-ItemMagnet features.
+
+Default:
+
+`op`
+
+## `rsitemagnet.bypass`
+
+Allows the player to bypass ItemMagnet ownership protection.
+
+Default:
+
+`op`
+
+## OP Bypass
+
+The `admin-bypass` configuration setting controls whether OP players receive the plugin's configured administrative bypass behavior.

docs/troubleshooting.md

@@ -0,0 +1,45 @@
+# Troubleshooting
+
+## ItemMagnet will not collect items
+
+Check the following:
+
+1. Confirm the machine is running rather than paused.
+2. Confirm a target container is assigned.
+3. Confirm the target is a hopper, chest, or barrel.
+4. Confirm the filter configuration is allowing the item.
+5. Confirm the item is within the configured collection radius.
+6. Check the server console for RS-ItemMagnet errors.
+
+## Target container is missing or invalid
+
+Open the ItemMagnet main menu and use **Target Container** to assign a new hopper, chest, or barrel.
+
+## Radius is not what I expected
+
+Open the Radius menu and check the current radius. The server configuration also controls the default and maximum radius.
+
+If vertical collection is restricted, check `item-y-distance` in `config.yml`.
+
+## Configuration changes are not taking effect
+
+Use:
+
+```text
+/rsim reload
+```
+
+or restart the server.
+
+If a new setting was introduced by an update, check the server console for configuration migration messages.
+
+## Need more help?
+
+When reporting a problem, include:
+
+- RS-ItemMagnet version
+- Paper version
+- Minecraft version
+- Relevant `config.yml` settings
+- Server console errors
+- Steps required to reproduce the problem

docs/usage.md

@@ -0,0 +1,68 @@
+# Usage
+
+## Creating an ItemMagnet
+
+An ItemMagnet is based on a lodestone.
+
+The current conversion process requires the player to use the plugin's required conversion item on the lodestone and then select a target container.
+
+Supported target containers are:
+
+- Hopper
+- Chest
+- Barrel
+
+## Main Menu
+
+Interacting with an ItemMagnet opens its main configuration menu.
+
+The current menu provides controls for:
+
+- **Convert Back** — restores the lodestone from the ItemMagnet.
+- **Running / Paused** — pauses or resumes the machine.
+- **Radius** — opens the radius configuration menu.
+- **Show Radius** — closes the menu and displays a temporary particle outline of the collection radius to the player.
+- **Target Container** — assigns or changes the container used for deposits.
+- **Filter** — configures item filtering.
+- **Admin** — opens administrative controls when permitted.
+
+## Radius
+
+The radius controls how far the ItemMagnet searches for dropped items.
+
+The current scanner uses the configured radius on the X, Y, and Z axes. The optional `item-y-distance` configuration setting can limit the vertical collection distance above and below the magnet.
+
+The radius menu provides:
+
+- `-10`
+- `-5`
+- `-1`
+- `+1`
+- `+5`
+- `+10`
+
+The configured maximum radius is enforced when players increase the radius.
+
+## Radius Preview
+
+Select **Show Radius** from the main menu to display the collection boundary temporarily.
+
+The preview is visible only to the player who requested it and shows the collection area without creating a permanent world effect.
+
+## Target Containers
+
+An ItemMagnet can deposit into a hopper, chest, or barrel.
+
+The target can be assigned during conversion and can later be changed from the main menu.
+
+While selecting a target, normal interaction with non-container blocks remains available. Selecting a valid hopper, chest, or barrel assigns it as the target.
+
+## Filters
+
+The filter menu allows the ItemMagnet to control which item types it accepts.
+
+Filter modes and individual filter entries are managed through the ItemMagnet inventory menus.
+
+## Pause and Resume
+
+The main menu displays the current machine state. A running ItemMagnet can be paused and resumed without converting the machine back into a normal lodestone.