MinePlusCore

🎯 The Big Idea

Mineplus is a server-side infrastructure core for Paper/Spigot 1.21+ that turns Blockbench models (.bbmodel) into living, collidable, interactive machines — using nothing but vanilla BlockDisplay entities.

What does that mean for your server?

The core ships with zero gameplay content. No surprise blocks, no test machines, no world edits. Everything in-game exists because you defined it — through JSON files, the module API, or both.

✨ Feature Highlights

• 🧱 Virtual Blockbench rendering — a single-pass streaming .bbmodel importer with negative-coordinate geometry, outliner pivot transforms, per-cube light_emission, and per-face UV analysis that maps textures onto vanilla block materials.
• 🎯 Geometry-aware collision — per-cube SAT voxelization (GEOMETRY / SURFACE / AABB modes) places barrier blocks exactly where your model is solid. Hollow structures stay hollow; empty interiors stay walkable.
• 🧭 Rotation-perfect placement — rotations snap to the 24 orientation-preserving axis permutations, so barriers and visuals never drift apart, even on rotated placements.
• 🗂️ Multiblock registry & lifecycle — create / place / interact / upgrade / tick / break with a full hook and lifecycle-event system.
• ⏱️ Timed crafting processes — restart-safe, chunk-aware processes (vanilla furnace parity: paused in unloaded chunks, resumed on load), scaled by per-level speed multipliers.
• 🔗 Linking & signals — pipe-network style auto-linking (autoLinkNeighbors) plus directed signal propagation between machines.
• 💾 SQLite persistence, off the main thread — asynchronous write-behind queue; gameplay never blocks on disk I/O.
• 🖥️ Built-in admin CLI — inspect, respawn, reload, and diagnose every instance live.

🚀 Quick Start

1. Install — drop Mineplus.jar into plugins/ and restart. Paper/Spigot 1.21+, Java 21.

2. Add a model — export a model from Blockbench as .bbmodel into plugins/Mineplus/models/.

3. Define the machine — drop a JSON file into plugins/Mineplus/multiblocks/:

   {
     "id": "my_machine",
     "name": "My Machine",
     "levels": {
       "1": { "model": "models/my_machine.bbmodel" }
     }
   }
   

4. Reload & spawn — /mineplus reload all, then place it via the API, a module, or /mineplus model debugspawn <modelKey>.

5. That's it — every player, on every vanilla client, can already see and touch it.

📖 Full walkthroughs: docs/extension-workflows.md • Sample files: examples/README.md

🎬 Showcase — the Cannon

Everything below is a module feature, built entirely outside the core with JSON + ~600 lines of Java. Demo video and screenshots live on the Modrinth and Hangar pages.

▸ Explore the code: examples/mineplus-fun — hook, GUI, ballistics, placement rotation, and the module development guide.

🧱 Three Ways to Use Mineplus

The tiers stack: a JSON-defined machine can be driven by a Tier-3 module (see examples/mineplus-fun — a complete Juicer and a torch-fired Cannon built entirely outside the core).

🖥️ Admin Commands

⚙️ Configuration

plugins/Mineplus/settings.mp.yml is auto-generated on first start and controls the rendering engine — collision mode, rotation snapping, per-face rendering, and the anchor convention:

VIRTUAL_RENDERING:
  COLLISION_MODE: GEOMETRY        # AABB | GEOMETRY | SURFACE
  COLLISION_EPSILON: 0.001
  COLLISION_NON_AIR_POLICY: SKIP  # SKIP | STRICT
  ROTATION_SNAP: true
  ROTATION_SNAP_THRESHOLD_DEGREES: 5
  PER_FACE_RENDERING: true
  ORIGIN_MODE: AUTO               # AUTO | CENTER | GRID

ADDITIONAL_DEBUG_LOGS: false

📖 Every key documented: docs/config-reference.md

📚 Documentation

🏛️ Architecture at a Glance

MineplusPlugin
 └─ ConfigManager ─────────── settings.mp.yml
 └─ VirtualBlockManager ───── .bbmodel → BlockDisplay pipeline
     └─ PluginContext
         └─ InfrastructureEngine
             ├─ MultiBlockRegistry            (types + instances)
             ├─ MultiBlockLifecycleManager    (create/place/interact/upgrade/remove/tick)
             ├─ ModelRenderingManager         (level → model spawn/swap/remove)
             ├─ MultiBlockLinkingSystem       (links + signals)
             ├─ MachineProcessManager         (timed crafting, restart-safe)
             ├─ RecipeManager / UpgradeManager / GuiManager
             └─ PersistenceFacade             (SQLite, async write-behind)

• Persistence — state lives in plugins/Mineplus/infrastructure.db. Gameplay actions stage snapshots in memory; a background task flushes ~once per second and synchronously on shutdown/reload. After a hard crash, at most ~1 second of changes roll back.
• Chunk awareness — instances in unloaded chunks are fully skipped (no ticks, hooks, renders, or process advancement) and resume on chunk load — vanilla tile-entity parity.
• Ghost cleanup — orphaned BlockDisplay entities from crashes are detected and cleaned on chunk load.