Modular Storage System is a comprehensive Minecraft storage plugin. It provides a multi-tiered network-based storage system with craftable, expandable storage disks and an intuitive terminal interface. The plugin features automation capabilities through importers and exporters, making it perfect for advanced storage and logistics systems.

Core Storage System

• Network-Based Storage: Connect Storage Servers, Drive Bays, and Terminals with PoE Cables
• Multi-Tier Storage Disks: 1k, 4k, 16k, and 64k capacity tiers with hot-swappable functionality
• Advanced Terminals: Search, sort, and manage your items with persistent per-terminal settings
• Disk Information: Storage disks display detailed tooltips with capacity, usage, and crafter information
• Disk Recycling: Dismantle empty disks to recover components (Shift + Right-click)

Automation & Management

• Automation System: Import and export items automatically with configurable filters
• Furnace Integration: Specialized exporter GUI for targeting fuel and input slots separately
• Security Controls: Manage network access with Security Terminals

Customization & Visuals

• Optional Resource Pack: Gives MSS items distinct custom models so they're told apart from the vanilla blocks they reuse — items still work and are fully named/described without the pack
• Connection-Aware Cable Pipes: Optionally render placed PoE Cables as pipes that visually join to their neighbours
• Iron Wrench: Right-click to rotate an MSS block, Shift + Right-click to dismantle it straight back into your inventory
• Player-Facing Placement: MSS blocks orient their front toward whoever places them
• Terminal Screen Glow: Optional soft light in front of Terminal / Security Terminal screens (toggle in config)
• Vanilla Recipes: Everything is crafted with normal recipes at a crafting table and shows up in the vanilla recipe book

Performance & Configuration

• Block Marker Cache: Caches which blocks belong to MSS so redstone, pistons and network scans rarely touch the database
• Click Rate Limiting: GUI interactions are rate-limited to prevent database spam
• Database Backend: HikariCP connection pooling with SQLite (default) or MySQL/MariaDB
• Spigot and Paper: One jar runs on Spigot, Paper, and Paper forks (Purpur, Pufferfish and others) on every Minecraft release from 1.21 through 26.3
• Comprehensive Configuration: Customizable via config.yml, lang/en_US.yml, and recipes.yml files

---

Basic Network Setup

1. Craft a Storage Server - The central hub of your storage network
2. Place a Drive Bay - Adjacent to the Storage Server (holds up to 7 storage disks)
3. Add a Terminal - Adjacent to the Storage Server or Drive Bay for item access
4. Craft Storage Disks - Start with 1k disks and insert them into the Drive Bay
5. Start Storing - Right-click the Terminal to access your network storage

Network Components

• Storage Server: Must be present in every network, acts as the controller
• Drive Bay: Stores your storage disks, can have multiple per network
• Terminal: Access point to view and manage stored items
• PoE Cable: Extends connections beyond adjacent placement (max 800 cables per network)

---

How They Work

Importers automatically pull items from connected containers (chests, furnaces, etc.) into your storage network. Exporters automatically push items from your storage network into connected containers.

Setup Process

1. Craft an Importer or Exporter
2. Place it adjacent to a container (chest, furnace, hopper, etc.)
3. Connect it to your network using PoE Cables
4. Right-click to configure filters and enable/disable
5. Set filters by dragging items into filter slots (empty = import/export everything)

Special Container Support

• Furnaces: Dedicated GUI with separate filter sections for fuel (left) and input material (right) slots

  • XP Bottling Feature - Bottle XP generated from smelting
  • 18 filter slots for fuel items
  • 18 filter slots for material items
  • Intelligent slot targeting for automated smelting setups

• Brewing Stands: Specialized interfaces for ingredient and bottle slots

• All Containers: Works with chests, barrels, hoppers, dispensers, and more

Filter Configuration

• Empty Filters: Import/export all items (no restrictions)
• Item Filters: Drag items into filter slots to whitelist specific items
• Multiple Filters: Combine multiple items for complex filtering logic

---

Search Functionality

• Item Search: Click the spyglass button (bottom left) to search for items
• Type in Chat: Enter your search term in chat to filter items instantly
• Persistent Search: Search terms are saved per terminal location
• Clear Search: Shift + Click the spyglass or search again to clear

Sorting Options

• Alphabetical Sort: Default sorting mode, organizes items A-Z
• Quantity Sort: Click the name tag button to sort by item count (highest first)
• Persistent Settings: Sort preference is saved per terminal location

---

Crafting

All MSS items are crafted with normal recipes at a vanilla crafting table and appear in the vanilla recipe book. Storage disks can also be assembled from a Storage Disk Housing + a tier Disk Platter. Every recipe — shape, ingredients, and whether it's enabled — is fully configurable in recipes.yml.

Storage Capacities

• 1k Disk: 8,128 items total (127 items per cell × 64 cells)
• 4k Disk: 32,512 items total (508 items per cell × 64 cells)
• 16k Disk: 130,048 items total (2,032 items per cell × 64 cells)
• 64k Disk: 520,192 items total (8,128 items per cell × 64 cells)

Storage Disk Features

• Persistent Tooltips: Disks display capacity, usage statistics, and crafter information
• Unique IDs: Each disk has a unique identifier for recovery purposes
• Crafter Attribution: Shows who crafted the disk with UUID tracking
• Hot-Swappable: Remove and insert disks without losing data
• Empty Recycling: Shift + Right-click empty disks to recover components

---

The plugin provides several administrative and utility commands:

Command	Description	Permission
/mss help	Show help menu with all available commands	Default
/mss give <item> [player]	Give MSS items to yourself or another player	modularstoragesystem.admin
/mss recovery <disk_id>	Recover a lost storage disk by its ID	modularstoragesystem.recovery
/mss info	Show plugin statistics and network information	modularstoragesystem.admin
/mss recipes	List all available recipes and their status	modularstoragesystem.admin
/mss reload [config|recipes|all]	Reload configuration files (incl. the resource pack)	modularstoragesystem.admin
/mss migratedb <sqlite|mysql>	Import all data from the other database into the active one	modularstoragesystem.admin

Available Items for /mss give

• server, bay, terminal, security
• cable, exporter, importer, wrench
• housing, platter1k, platter4k, platter16k, platter64k
• disk1k, disk4k, disk16k, disk64k

---

The plugin includes three main configuration files:

• config.yml: Network limits, database settings, permissions, performance options, and the resource pack
• lang/en_US.yml: All plugin messages and text (supports localization)
• recipes.yml: Complete recipe definitions with enable/disable options for each recipe

The plugin uses HikariCP connection pooling and supports either SQLite (default) or MySQL/MariaDB — see below.

---

All plugin data (networks, storage disks, stored items, drive bays, importers/exporters) lives in a database — either SQLite (default; a storage.db file, zero setup) or MySQL/MariaDB (for shared or remote databases). Pick one with database.type: sqlite or mysql in config.yml; MySQL host/credentials are configured in the same file.

Switching storage types without data loss

Changing database.type by itself does not move your data — the new database starts empty (your old data stays safe in the old database, it just isn't loaded). To carry everything across, use the built-in importer:

1. Install the new plugin jar and start the server once on your existing database so its schema upgrades in place.
2. Set database.type to the destination (e.g. mysql) in config.yml and restart — this creates the empty new schema.
3. Run /mss migratedb <old-type> confirm (e.g. /mss migratedb sqlite confirm). This copies every table from the old database into the active one.
4. Restart the server so all in-memory data reflects the import.

Do steps 2–4 with no players online, and back up first. The migration is atomic — it rolls back on any error and leaves the active database unchanged — and is verified to preserve every row in both directions, including when importing from an older plugin version's database. Item NBT is copied verbatim, so data is preserved as long as the Minecraft version stays the same.

Upgrading from an older version

Just replace the jar and start the server — the plugin runs idempotent, additive schema migrations on startup that bring older databases up to date without losing data (verified, including the legacy storage_items table layout). Your config files are never overwritten on update, so customizations are safe — but new keys are not auto-merged into them, so after a feature update:

• config.yml — nothing to do. Missing keys fall back to the bundled defaults, so the plugin runs unchanged; regenerate it only if you want to see and tweak newly-added options.
• lang/en_US.yml: nothing to do. Keys missing from your copy fall back to the bundled English text, so new messages show up even if you customized the file. Merge new keys in only to translate or restyle them.
• recipes.yml — if you've customized it, merge in new/changed recipes (or delete it to regenerate). Recipes that exist only in the new jar are silently not registered, and changed ingredients won't reach recipes your file already defines, until you refresh it.

/mss reload re-reads your existing files but does not pull in new defaults — regenerate or hand-merge instead.

---

• Server: Spigot, Paper, or a Paper fork (Purpur, Pufferfish and others), Minecraft 1.21 or newer. One jar covers every version. Tested on Paper 1.21 and Spigot 1.21.1, and on both at 1.21.11, 26.1.2, 26.2 and 26.3.
• Java: whatever your server version needs (Java 21 for 1.21.x, Java 25 for 26.x).

Spigot vs Paper

Everything works on both, including XP bottling. One difference:

• Moving an existing database from Paper to Spigot is not supported. Paper stores items in its own format, which Spigot cannot read. Moving from Spigot to Paper works.

1. Download the latest release
2. Place the .jar file in your server's plugins folder
3. Restart your server
4. Configure the plugin via the generated config files as needed
5. (Optional) Enable the resource pack in config.yml to give MSS items their custom skins

Resource pack

The pack ships inside the plugin. On startup MSS writes it to plugins/ModularStorageSystem/resourcepack.zip, a standalone pack you can use however you like:

• Let MSS serve it: set resource-pack.enabled, handled-by-mss and self-host.enabled to true, set self-host.public-address to an address players can reach, and open self-host.port.
• Serve it yourself: upload the zip to your host and set resource-pack.url, or use server.properties.
• Install it by hand: players can drop the zip into their own resourcepacks folder.

Plugin updates refresh that file automatically. If you replace it with your own pack, MSS leaves yours alone.

Metrics

MSS reports anonymous usage statistics to bStats (server count, versions, database type and a few settings). To opt out for every plugin on the server, set enabled: false in plugins/bStats/config.yml.

MSS respects claim and region plugins (WorldGuard, GriefPrevention, Towny, Lands, Factions and others) with no extra setup. With permissions.respect_claims: true (the default):

• Opening or using an MSS block needs build access where it stands.
• A new MSS block can't connect to MSS blocks on land you can't build on, and an importer or exporter can't attach to a container there.
• Breaking MSS blocks is up to the protection plugin, as with any block.

MSS asks the protection plugin the same way a block break would, so any plugin that protects blocks from breaking works. Tested with WorldGuard and GriefPrevention on Spigot and Paper, and Towny on Paper.

These plugins build their custom blocks on note blocks, which MSS also uses for its own block skins. MSS detects them and adapts, set by integrations.custom-block-plugins in config.yml:

• coexist (default): placed MSS blocks stay their vanilla blocks, and MSS adds its item models to that plugin's resource pack. That plugin sends the merged pack, so MSS's own pack delivery turns off. Rebuild that plugin's pack once after the first start (/oraxen reload all, /nexo reload all or /iazip).
• blocks (experimental): coexist, plus MSS registers its storage server, drive bay, terminal and security terminal as that plugin's custom blocks, so placed MSS blocks get their skins too. On first start MSS writes the block definitions and logs the reload command to run once. MSS still handles identity, placement rules, drops and cleanup.

Both modes are built on each plugin's public API but have not yet been tested with the real plugins. Please report any problems.

Other plugins can build on MSS through its public API in the package org.jamesphbennett.modularstoragesystem.api. Add depend: [ModularStorageSystem] to your plugin.yml and compile against the MSS jar as a provided dependency.

MSSApi api = MSSApi.get();
String network = api.networks().networkAt(block.getLocation());
long diamonds = api.storage().count(network, api.storage().hash(new ItemStack(Material.DIAMOND)));

What it covers:

• Storage: list, count, store and extract a network's items, and attach extra storage (a StorageProvider, for example a container behind a storage bus).
• Networks: the network at a block or next to it, and a snapshot of its members.
• Events: NetworkUpdatedEvent, NetworkRemovedEvent, NetworkContentsChangedEvent (at most once per network per tick) and MSSReloadEvent.
• Security: the network's security terminal checks and the same protection plugin check MSS uses itself.
• Items and recipes: items that count as MSS items, recipes in the recipes.yml format that run through MSS's own crafting checks, and resource pack models.
• Disks: new disk tiers, and storage on a single disk outside a drive bay.
• Terminals: open a terminal without a block, and ask a player for one line of chat input.
• Database: MSS's connection pool for your own tables, which /mss migratedb then moves along with MSS's.

Call the API on the main thread. apiVersion() only goes up and keeps every older method. Each method is documented in the source of the api package.