MachinaWards

A comprehensive MOBA-style ward system for Minecraft servers that provides area protection, intrusion alerts, and member management.

Features

🛡️ Protection System

Area Protection: Create protected zones with configurable radius
Multiple Tiers: Different ward types with varying protection levels
Access Control: Add members to share ward access
Configurable Rules: Toggle protection for block placement, breaking, interaction, explosions, and fire

🚨 Alert System

Intrusion Detection: Get notified when unauthorized players enter your ward
Multiple Alert Types: Title, action bar, and chat notifications
Cooldown System: Prevent spam alerts with configurable cooldowns
Member Alerts: Share notifications with ward members

🏪 Economy Integration

Vault Support: Purchase wards using server economy
Shop GUI: Browse and buy different ward tiers
Custom Recipes: Craft wards using configurable materials

🎮 User Interface

Ward Management: Right-click ward blocks to manage settings
Member Management: Add/remove members through GUI
Activity History: View recent intrusion logs
Alert Toggles: Enable/disable notifications per ward

Installation

Prerequisites

Minecraft Server: Spigot/Paper 1.21+
Java: Version 19 or higher
Vault: For economy features (optional but recommended)

Setup Steps

Download: Get the latest JAR from the releases
Install: Place MachinaWards.jar in your plugins/ folder
Start Server: Start or restart your server
Configure: Edit plugins/MachinaWards/config.yml
Permissions: Set up permission groups

Configuration

Basic Settings

# Global settings
region:
  shape: square  # square or column
  worlds: []     # empty means all worlds allowed
  
height:
  min_y: -64
  max_y: 319

alerts:
  enabled: true
  cooldown_ms: 10000
  title_format: "&cIntruder!"
  actionbar_format: "&7%name% entered your ward"

protection:
  block_place: true
  block_break: true
  interact: true
  explosion: true
  fire: true

Ward Tiers

wards:
  basic:
    display_name: "&aBasic Ward"
    result_material: BEACON
    price: 1000.0
    radius: 8
    notify: true
    custom_recipe:
      - ["SEA_LANTERN", "ENDER_EYE", "SEA_LANTERN"]
      - ["OBSIDIAN", "BEACON", "OBSIDIAN"]
      - ["IRON_INGOT", "IRON_INGOT", "IRON_INGOT"]
      
  advanced:
    display_name: "&bAdvanced Ward"
    result_material: CONDUIT
    price: 5000.0
    radius: 16
    notify: true
    custom_recipe:
      - ["DIAMOND", "NETHER_STAR", "DIAMOND"]
      - ["OBSIDIAN", "CONDUIT", "OBSIDIAN"]
      - ["GOLD_INGOT", "GOLD_INGOT", "GOLD_INGOT"]

Commands

Command	Description	Permission
`/ward help`	Show help information	`wards.player.*`
`/ward shop`	Open the ward shop	`wards.player.*`
`/ward list`	List your wards	`wards.player.*`
`/ward addmember <player>`	Add member to ward	`wards.player.*`
`/ward removemember <player>`	Remove member from ward	`wards.player.*`
`/ward reload`	Reload configuration	`wards.admin`

Permissions

Player Permissions

wards.player.1 - Allow 1 ward
wards.player.3 - Allow 3 wards
wards.player.5 - Allow 5 wards
wards.player.10 - Allow 10 wards

Admin Permissions

wards.admin - Full administrative access
- Bypass all ward protections
- Remove any ward
- Reload configuration
- Access admin commands

Usage Guide

Creating Wards

Purchase: Use /ward shop or craft using recipes
Place: Right-click to place the ward block
Configure: Right-click the placed ward to manage settings

Managing Wards

Toggle Alerts: Enable/disable intrusion notifications
Add Members: Grant access to trusted players
View History: Check recent intrusion logs
Remove Ward: Break the ward block (owner/admin only)

Protection Features

Automatic: Protection activates immediately upon placement
Smart Detection: Only affects unauthorized players
Member Access: Members can bypass all protections
Admin Override: Admins can bypass with permission

Economy Integration

Vault Setup

Install Vault plugin
Install an economy plugin (e.g., EssentialsX, iConomy)
Configure economy settings
Set ward prices in config

Shop Features

Tier Cards: Browse available ward types
Price Display: See costs before purchase
Instant Delivery: Receive items immediately
Balance Check: Automatic verification

Performance Features

Optimization

World Indexing: Fast ward lookups by world
Square Math: Efficient area calculations
Memory Caching: In-memory ward storage
Lazy Loading: Database access only when needed

Database

SQLite Storage: Lightweight, file-based database
Automatic Setup: Tables created on first run
Data Persistence: Wards survive server restarts
Logging System: Track all intrusion events

Developer API

Main Classes

MachinaWards - Main plugin class
WardManager - Core ward management service
Ward - Ward data model
SqliteStore - Database persistence layer

Key Methods

// Get ward manager
WardManager manager = MachinaWards.get().manager();

// Create ward
Ward ward = new Ward(id, owner, world, x, y, z, radius, tier, notify, timestamp);
manager.add(ward);

// Check protection
Ward ward = manager.findAt(location);
if (ward != null && !ward.hasAccess(player.getUniqueId())) {
    // Handle protection
}

// Get tier information
RecipeLoader.WardTier tier = manager.getTier("basic");

Events

WardPlaceEvent - When a ward is placed
WardBreakEvent - When a ward is broken
WardEntryEvent - When a player enters a ward
WardProtectionEvent - When protection is triggered

Troubleshooting

Common Issues

Wards not working

Check permissions are set correctly
Verify Vault is installed (for shop features)
Check console for error messages

Database errors

Ensure write permissions in plugin folder
Check SQLite is included in JAR
Verify Java version compatibility

Performance issues

Reduce ward radius values
Limit number of wards per player
Adjust alert cooldown settings

Debug Mode

Enable debug logging in config.yml:

debug: true

Support

Getting Help

Issues: Report bugs on GitHub
Questions: Ask in discussions
Feature Requests: Submit via issues

Contributing

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Author: Machina
Minecraft Version: 1.21+
API: Spigot/Paper
Dependencies: Vault, SQLite

Happy Warding! 🛡️✨

Wards

📖About Wards