Skip to content
BranchesTags

Repository files navigation

🌊 SchemFlow

SchemFlow Logo

License Release GitHub Downloads Java Paper

⚡ Cloud-native schematic manager with local support and lightning-fast tab completion

Purpose-built for multi-server networks with offline capabilities and instant responsiveness

📥 Download Latest • 📖 Documentation • 🐛 Report Issues • 💬 Discord

🚀 Why Choose SchemFlow?

SchemFlow revolutionizes schematic management for Minecraft servers by combining cloud-native S3/MinIO storage with local schematic support, delivering unmatched performance and reliability. This open-source plugin eliminates the bottlenecks of traditional workflows while maintaining full compatibility with native WorldEdit formats.

⚡ What's New in v0.5.14

  • 🚀 Lag-Free Round Provisioning: provisionRoundWorld now pastes off the main thread (under FastAsyncWorldEdit) and creates void worlds without the costly spawn search — a large map went from a ~2.9 s main-thread freeze (watchdog risk) to ~110 ms on Paper 1.21.11.
  • 🗺️ Headless Map Capture: /SchemFlow savemap + saveRegionAsMap(...) save a region of any world (auto-loading its folder) to S3 with absolute origin preserved — batch-convert pre-built maps without an in-game selection.

⚡ What's New in v0.5.13

  • 🔌 Developer API: Provision and dispose worlds on demand from your own plugin — fully async, with a completion signal. Purpose-built for per-round minigame maps.
  • 🎯 Absolute-Origin Paste: Restore a schematic at its exact authored coordinates, so named locations (spawns, corners, regions) stay valid in the freshly created world.
  • 🧱 Map Builder Hook: Save a pos1/pos2 selection straight to S3 preserving the absolute origin for later one-call provisioning.
  • 🧹 One-Call World Teardown: Unload (no save) and delete an ephemeral world in a single call.

⚡ What's New in v0.5.12

  • 🏠 Local Schematic Support: Work offline with local:name syntax for downloaded schematics
  • ⚡ Lightning-Fast Tab Completion: Smart caching eliminates network delays (90% fewer S3 calls)
  • 🛡️ Safe Update Command: Dedicated /schemflow update with mandatory --confirm protection
  • 🎯 Optimized Performance: Cached data for instant command completion and duplicate prevention
  • 🔧 Enhanced User Experience: Default group displayed exactly as configured in config

⚡ Core Performance Benefits

  • Hybrid Storage: Cloud reliability + local speed for frequently-used schematics
  • Instant Tab Completion: No more waiting for S3 responses during command entry
  • Parallel Operations: Concurrent uploads/downloads across multiple server instances
  • Ephemeral Cache: Temporary paste files automatically cleaned up
  • Zero-Downtime Operations: Hot configuration reloading without restarts

🎯 Developer & Admin Friendly

  • Intuitive Commands: Smart tab completion with cached schematic names
  • WorldEdit Integration: Full compatibility with advanced flag support
  • Skript API: Custom automation scripts for advanced workflows
  • Comprehensive Safety: Trash system with restore, undo/redo, and confirmation prompts
  • Hot-Swappable Config: Update settings without server restarts

✨ Feature Showcase

🎮 Hybrid Schematic Management

  • Cloud Storage: S3/MinIO for cross-server synchronization
  • Local Support: Offline access with local:name syntax
  • Smart Caching: Lightning-fast tab completion with cached data
  • Safe Updates: Dedicated update command with confirmation
  • Real-time Sync: Instant cache updates across commands

🔧 Advanced WorldEdit Support

  • FastAsyncWorldEdit fully compatible
  • Entity handling with -e flag
  • Air block control with -a flag
  • Biome preservation with -b flag (default enabled)
  • Large schematic optimization for massive builds

🌐 Cloud Storage Integration

  • MinIO self-hosted solution
  • AWS S3 enterprise-grade storage
  • Compatible providers (Cloudflare R2, DigitalOcean Spaces, Wasabi, etc.)
  • Automatic compression with .schm format
  • Intelligent caching system for performance

🤖 Automation & Safety

  • Skript integration with custom syntax
  • Developer API for on-demand world provisioning (reflection-friendly)
  • World provisioning system for hubs/spawns
  • Trash & Restore system with flat storage
  • Undo/Redo integration for deletes and pastes
  • Group lifecycle management (create/delete/rename)

🎯 Perfect For

🏢 Build Servers 🎮 Creative Networks 🏆 Competition Servers 🌍 Survival Servers
Template management Plot schematic storage Arena/map distribution Structure backups
Build preservation Player submissions Event preparation Town planning
Collaboration tools Contest archives Rapid deployment Restoration tools

🚀 Quick Start

📋 Requirements

  • Minecraft: 1.21 – 1.21.11 (Paper/Purpur recommended)
  • Java: 21+
  • WorldEdit: 7.2.18+ (or FastAsyncWorldEdit)

⚙️ Quick Configuration

# plugins/SchemFlow/config.yml
endpoint: "your-minio-server.com:9000"
secure: true
accessKey: "your-access-key"
secretKey: "your-secret-key"
bucket: "schematics"
extension: "schm"

# Local download target
downloadDir: "plugins/SchemFlow/schematics"

# Storage hierarchy (S3 object keys)
storage:
  rootDir: "FlowStack/SchemFlow"   # Root prefix in bucket
  defaultGroup: "default"         # Used when -group not provided

# Performance settings
cacheRefreshSeconds: 60           # Auto-refresh cache interval

Test your setup: /SchemFlow list

🎮 Command Reference

📜 Click to expand complete command list

Core Commands

Command Description Example
/SchemFlow help Show command overview /SchemFlow help
/SchemFlow list List all stored schematics by group /SchemFlow list
/SchemFlow cache Refresh schematic cache /SchemFlow cache
/SchemFlow reload Reload configuration /SchemFlow reload
/SchemFlow groups List all groups /SchemFlow groups

Schematic Operations

Command Description Example
/SchemFlow fetch [group:]name [destDir] Download schematic to disk /SchemFlow fetch lobby:castle
/SchemFlow upload <id> [-flags] [-group <name>] Upload selection as schematic /SchemFlow upload castle -eb -group lobby
/SchemFlow update [group:]name [-flags] [--confirm] NEW: Update existing schematic safely /SchemFlow update lobby:castle --confirm
/SchemFlow paste [group:]name|local:name [-flags] Paste schematic at location /SchemFlow paste lobby:castle -ea
/SchemFlow paste local:name [-flags] NEW: Paste from local downloads /SchemFlow paste local:my_build -a
/SchemFlow delete [group:]name Soft delete (move to trash) /SchemFlow delete lobby:old_castle

Local Schematic Management

Command Description Example
/SchemFlow local NEW: List local schematics /SchemFlow local
/SchemFlow local delete <name> [--confirm] NEW: Delete local schematic file /SchemFlow local delete old_build --confirm

Trash & Recovery

Command Description Example
/SchemFlow trash List trashed schematics /SchemFlow trash
/SchemFlow restore <name> [-group <dest>] Restore from trash to group /SchemFlow restore old_castle -group lobby
/SchemFlow trash clear --confirm Permanently clear ALL trash /SchemFlow trash clear --confirm
/SchemFlow undo Undo last delete or delegate to WorldEdit /SchemFlow undo
/SchemFlow redo Redo last undo or delegate to WorldEdit /SchemFlow redo

Group Management

Command Description Example
/SchemFlow group create <name> Create a new group /SchemFlow group create lobby
/SchemFlow group delete <name> [--confirm] Delete group (shows count first) /SchemFlow group delete Nature --confirm
/SchemFlow group rename <old> <new> Rename group (case-only changes allowed) /SchemFlow group rename nature Nature

Selection & World Tools

Command Description Example
/SchemFlow pos1 Set first selection corner /SchemFlow pos1
/SchemFlow pos2 Set second selection corner /SchemFlow pos2
/SchemFlow provision <world> Create/provision world from config /SchemFlow provision lobby

Flags & Options

  • -e: Include/paste entities
  • -a: Ignore air blocks when pasting
  • -b: Include/preserve biomes (enabled by default)
  • -group <name>: Target a specific group instead of default
  • --confirm: Required for destructive operations (update, delete, clear)

🔄 What's New: Local Support & Performance

🏠 Local Schematic Workflow

# Download a schematic for offline use
/SchemFlow fetch lobby:castle

# List your local schematics
/SchemFlow local

# Paste from local storage (works offline!)
/SchemFlow paste local:castle -a

# Clean up local files when done
/SchemFlow local delete castle --confirm

⚡ Lightning-Fast Tab Completion

  • Before: Every tab press = S3 API call (slow, expensive)
  • After: Cached data = instant completion (90% fewer S3 calls)
  • Smart Updates: Cache refreshes automatically on operations
  • Duplicate Prevention: No more repeated schematic names in tab completion

🛡️ Safe Update Command

# Old way: upload overwrites silently
/SchemFlow upload existing_build  # Dangerous!

# New way: explicit update with confirmation
/SchemFlow update existing_build --confirm  # Safe!

🔐 Permissions

Core Permissions

  • schemflow.admin — Full access (default: op)
  • schemflow.help — View help (default: true)
  • schemflow.list — List schematics (default: true)
  • schemflow.fetch — Download schematics (default: true)
  • schemflow.local — NEW: Manage local schematics (default: true)

Build & Modify Permissions

  • schemflow.pos1 / schemflow.pos2 — Set selection corners (default: true)
  • schemflow.upload — Upload new schematics (default: op)
  • schemflow.paste — Paste schematics (default: op)
  • schemflow.delete — Soft delete schematics (default: op)
  • schemflow.restore — Restore from trash (default: op)

Administrative Permissions

  • schemflow.trash.clear — Permanently clear trash (default: op)
  • schemflow.cache — Refresh cache (default: op)
  • schemflow.reload — Reload configuration (default: op)
  • schemflow.provision — Provision worlds (default: op)
  • schemflow.groups — List groups (default: op)
  • schemflow.group.create — Create groups (default: op)
  • schemflow.group.delete — Delete groups (default: op)
  • schemflow.group.rename — Rename groups (default: op)

📁 Storage Architecture

S3/MinIO Structure

SchemFlow organizes schematics with a clean, predictable hierarchy:

<rootDir>/                          # Configurable root (e.g., "FlowStack/SchemFlow")
├── SF_default/                     # Default group (SF_ prefix internal only)
│   ├── castle.schm
│   └── spawn.schm
├── SF_lobby/                       # Custom group
│   ├── entrance.schm
│   └── hub.schm
└── .trash/                         # Flat trash storage
    ├── old_castle.schm            # Deleted schematics (no group prefix)
    └── broken_build.schm

Local Downloads

Downloaded schematics are stored in downloadDir (configurable):

plugins/SchemFlow/schematics/       # Default download location
├── castle.schm                     # Downloaded from server
├── spawn.schm                      # Available offline
└── my_build.schm                   # Local-only schematic

Group Management

  • Internal Prefix: Groups use SF_ prefix in S3 paths (transparent to users)
  • User-Friendly Names: Commands use clean names: lobby, builds, default
  • Default Group: Configurable in config.yml under storage.defaultGroup
  • Case Sensitivity: Group renames allow case-only changes for consistency

🤖 Skript Integration

SchemFlow provides powerful Skript syntax for automation:

# List all available schematics
set {_schematics::*} to schemflow schematics

# Download a schematic for local use
fetch schemflow schematic "castle" to "plugins/SchemFlow/schematics"

# Paste at player location  
paste schemflow schematic "castle" at location of player

# Use local schematics
paste schemflow schematic "local:spawn" at location of player

# Advanced automation example
every 1 hour:
    loop {backup_locations::*}:
        paste schemflow schematic "checkpoint" at loop-value
        
# Update workflow with safety
command /updatebuild <text>:
    trigger:
        if player has permission "schemflow.upload":
            execute console command "/schemflow update %arg-1% --confirm"

🔌 Developer API

Other plugins can drive SchemFlow on demand — provision a fresh world, paste a map at its exact authored coordinates, and receive a completion signal — without a compile-time dependency. Every entry point lives on WorldProvisioner (reachable via SchemFlowPlugin.getInstance().getProvisioner()) and is safe to call from any thread; all Bukkit world operations are marshalled to the main thread internally.

Method Returns Purpose
provisionRoundWorld(world, group, schematic, pasteAtOrigin, gamerules) CompletableFuture<World> Create a void world, async-fetch the schematic from S3, paste it, apply gamerules. Completes only once the map is fully pasted. Idempotent per world name.
disposeWorld(world) CompletableFuture<Void> Unload (no save) and delete the world folder.
inspect(group, schematic) SchematicInfo Dimensions + authored min corner, for callers that paste at a fixed point. Call off the main thread.
saveSelectionAsMap(player, group, name) CompletableFuture<Void> Save a pos1/pos2 selection to S3 preserving the absolute origin (map builder).

Paste-at-origin (pasteAtOrigin = true) restores every block at the coordinate it was authored at, so absolute named locations stay valid in the new world. This requires maps saved via saveSelectionAsMap (which preserves the absolute origin); schematics created with /SchemFlow upload paste relatively and should be re-exported if you need absolute placement.

Reflection example (zero compile-time dependency)

Object plugin = Class.forName("com.c4g7.schemflow.SchemFlowPlugin")
        .getMethod("getInstance").invoke(null);
Object prov = plugin.getClass().getMethod("getProvisioner").invoke(plugin);

CompletableFuture<?> future = (CompletableFuture<?>) prov.getClass()
        .getMethod("provisionRoundWorld", String.class, String.class, String.class, boolean.class, java.util.Map.class)
        .invoke(prov, "round_42", "blockparty", "W-BLOCKPARTY-regular-Island", true, null);

future.whenComplete((world, error) -> {
    if (error != null) { /* handle failure */ return; }
    // (org.bukkit.World) world is fully pasted — safe to teleport players in
});

The method names and signatures above are a stable contract for reflection callers — they will not change without a major-version bump.

⚙️ Advanced Configuration

🔧 Click to expand complete configuration reference

Complete Configuration Example

# S3/MinIO Connection Settings
endpoint: "play.min.io"              # S3 endpoint URL or host:port
secure: true                         # Use HTTPS/TLS encryption
accessKey: "MINIO_ACCESS_KEY"        # S3 access credentials
secretKey: "MINIO_SECRET_KEY"        # S3 secret credentials  
bucket: "schematics"                 # Storage bucket name
extension: "schm"                    # File extension (.schm or .schematic)

# Local Storage Settings
downloadDir: "plugins/SchemFlow/schematics"  # Local download directory

# Performance & Caching
autoListOnStart: true                # List schematics on startup
cacheRefreshSeconds: 60              # Auto-refresh interval (0 = disabled)
fetchOnStart: ""                     # Auto-fetch schematic on startup

# Storage Hierarchy
storage:
  rootDir: "FlowStack/SchemFlow"     # Root prefix in S3 bucket
  defaultGroup: "default"            # Default group name (shown in UI)

# World Provisioning System
provisionOnStartup: false            # Enable auto-provisioning
worlds:
  - name: "lobby"                    # World name
    enabled: true                    # Enable this world
    flat: true                       # Use flat world generator
    schem: "lobby_base"              # Schematic to paste
    pasteAt: "0,64,0"                # Paste coordinates (x,y,z)
    gamerules:                       # Custom game rules
      doMobSpawning: false
      doDaylightCycle: false
      doWeatherCycle: false
      randomTickSpeed: 0

Performance Tuning

  • Cache Settings: Set cacheRefreshSeconds to 300+ for large storage buckets
  • Network Optimization: Use local MinIO for best performance (sub-10ms latency)
  • Local Downloads: Keep frequently-used schematics local for instant access
  • FastAsyncWorldEdit: Enable for 10x faster large schematic operations
  • Concurrent Operations: SchemFlow handles multiple simultaneous operations

Security Best Practices

  • S3 Credentials: Use dedicated MinIO/S3 user with bucket-only permissions
  • Network Security: Enable TLS/SSL (secure: true) for production
  • Permission Groups: Restrict upload/delete permissions to trusted users
  • Backup Strategy: Regular S3 bucket backups for disaster recovery

🔧 Development & Building

Build from Source

git clone https://github.com/c4g7-dev/SchemFlow.git
cd SchemFlow
mvn clean package

Output: target/SchemFlow-0.5.14-all.jar

Development Setup

  • IDE: IntelliJ IDEA or Visual Studio Code with Java extensions
  • Java: OpenJDK 21+ (tested with 21, 17 compatible)
  • Dependencies: Automatically resolved via Maven
  • Testing: Paper/Purpur test server with WorldEdit or FAWE

Project Structure

src/main/java/com/c4g7/schemflow/
├── SchemFlowPlugin.java           # Main plugin class
├── cmd/                           # Command handling
├── select/                        # Selection management
├── skript/                        # Skript integration
├── util/                          # Utilities (SafeIO, ZipUtils)
├── we/                           # WorldEdit integration
└── world/                        # World provisioning + on-demand API (WorldProvisioner, SchematicInfo)

🤝 Contributing

We welcome contributions! Here's how to get started:

  1. Fork the repository on GitHub
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Implement your changes with tests
  4. Commit your changes (git commit -m 'Add amazing feature')
  5. Push to your branch (git push origin feature/amazing-feature)
  6. Open a Pull Request with detailed description

Development Guidelines

  • Follow existing code style and patterns
  • Add JavaDoc comments for public methods and classes
  • Test with both WorldEdit and FastAsyncWorldEdit
  • Ensure backward compatibility with existing configurations
  • Update documentation for new features

Testing Checklist

  • Commands work with tab completion
  • Local schematic operations function offline
  • S3/MinIO operations handle network failures gracefully
  • Group management preserves data integrity
  • Trash/restore cycle works correctly

📊 Performance Benchmarks

Operation v0.5.11 v0.5.12 Improvement
Tab completion response 800ms 50ms 16x faster
List 1000 schematics 2.1s 0.1s 21x faster
Local schematic paste N/A 0.3s Instant offline
Cache refresh efficiency 100% S3 calls 10% S3 calls 90% reduction
Update command safety ❌ Silent overwrite ✅ Explicit confirm Accident prevention

Benchmarks performed on Paper 1.21+ with 8GB RAM, local MinIO instance

🆘 Support & Community

Discord GitHub Issues Documentation

Getting Help

Common Issues

  • S3 Connection: Check endpoint, credentials, and bucket permissions
  • Tab Completion Slow: Increase cacheRefreshSeconds or check network latency
  • Local Schematics Not Found: Verify downloadDir path and file permissions
  • Update Command Fails: Ensure --confirm flag is included for safety

📜 License & Credits

License

SchemFlow is released under the Apache-2.0 License — see LICENSE for details.

Credits & Acknowledgments

  • Lead Developer: c4g7-dev team
  • Community Contributors: Bug reports, feature requests, and code contributions
  • Beta Testers: Early adopters who helped refine v0.5.12 features

Dependencies & Integration

  • Paper/PaperMC - High-performance Minecraft server platform
  • WorldEdit - World manipulation and schematic format
  • FastAsyncWorldEdit - Performance enhancement layer
  • Skript - Scripting integration for automation
  • MinIO - High-performance S3-compatible object storage

🌊 SchemFlow v0.5.14 — On-demand world provisioning API for build & game networks

Made with ❤️ by c4g7-dev and the Minecraft community

⭐ Star us on GitHub • 🚀 Download v0.5.14 • 💬 Join Discord

About

Lightning‑fast schematic management for Minecraft servers (S3/MinIO-backed).

github.com/c4g7-dev/SchemFlow

Resources

Readme
Apache-2.0 license

Contributing

Contributing
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages