OreoEssentials — Server Modules

What Are Server Modules?

The server folder (plugins/OreoEssentials/server/) contains configuration files for eleven distinct server-management features. Each feature has its own YAML file. Together they let you control everything from lag management to custom crafting rewards.

plugins/
  OreoEssentials/
    server/
      maintenance.yml     ← lock server from new players
      clearlag.yml        ← auto-remove entities & fight lag
      jumpads.yml         ← launch-pad blocks
      tempfly.yml         ← temporary flight by rank
      warnings.yml        ← player warning system
      modgui.yml          ← moderation GUI worlds filter
      help.yml            ← /help command content
      rules.yml           ← /rules command content
      motd.yml            ← join message of the day
      craft-actions.yml   ← rewards when crafting items
      shards.yml          ← cross-server world sharding

What Does It Do?

Maintenance mode lets you temporarily close the server to regular players while you do updates, fix bugs, or prepare an event. When enabled:

• Players not on the whitelist are blocked from joining with a custom message
• The server list shows a custom maintenance MOTD
• Optionally, the server list shows as full (hides the join button)
• A countdown timer can show time until maintenance ends

Quick Start

Config File: server/maintenance.yml

maintenance:
  enabled: false               # true = maintenance ON, no one can join except whitelist

  motd:
    line1: "&c&l⚠ MAINTENANCE ⚠"       # first line of server list description
    line2: "&7Server is under maintenance" # second line

  kick-message: "&c&l⚠ MAINTENANCE ⚠\n&7Please try again later."
  join-denied-message: "&cServer is under maintenance."
  # ↑ These messages are shown when a non-whitelisted player tries to connect

  whitelist: []
  # Add player UUIDs or names here. These players CAN join during maintenance.
  # Example:  whitelist: ["Steve", "Alex"]

  timer:
    end-time: 0                  # Unix timestamp (ms) when maintenance ends (set via /maintenance clock)
    show-in-motd: true           # Show countdown timer in server list MOTD
    format: "&eTime remaining: &f{TIME}"  # {TIME} is replaced with e.g. "1h 23m 45s"

  server-list:
    show-as-full: true           # Show max players = current players (looks full → hides join)
    hide-player-count: false      # Hide the player count entirely

Commands

Player Examples

What Does It Do?

When hundreds of item stacks pile up on the ground, or thousands of mobs accumulate, your server's TPS (Ticks Per Second) drops below 20 — causing lag. OreoLag automatically cleans up:

• Ground items — diamonds, wood, dirt that players dropped
• Mobs — cows, zombies, etc. (you can whitelist specific types)
• Other junk — experience orbs, arrows, primed TNT, falling blocks

Config File: server/clearlag.yml

enable: true                         # Master switch — false disables ALL clearlag features

global-broadcasts:
  enabled: true
  use-permission-for-broadcasts: false  # true = only players with the perm see warnings
  permission: "bukkit.broadcast"

area-filter: []                        # Entity types NEVER removed (e.g. ["ITEM"] to never clear items)

kill-mobs:                             # Manual /olagg killmobs command settings
  enabled: true
  remove-named: false                  # false = never kill mobs with custom names (e.g. named pets)
  mob-filter: []                        # Entity types to NEVER kill (whitelist): ["VILLAGER","WOLF"]

auto-kill-mobs:                        # Auto-kill mobs on a timer
  enabled: false
  interval: 600                         # Seconds between auto-kills (600 = every 10 minutes)
  broadcast-removal: true
  broadcast-message: "&6[OreoLag] &aRemoved +RemoveAmount mobs!"
  warnings:                             # Warn players before kill happens
    - "time:60 msg:&6[OreoLag] &eMobs will be killed in 60s!"
    - "time:10 msg:&6[OreoLag] &cMobs killed in 10s!"

auto-removal:                          # Auto-clear ground items and entities
  enabled: true
  autoremoval-interval: 480             # Seconds between clears (480 = every 8 minutes)
  broadcast-removal: true
  broadcast-message: "&6[OreoLag] &aRemoved +RemoveAmount entities!"
  flags:
    item: true                          # Remove ground items
    experience-orb: true               # Remove XP orbs
    falling-block: true                # Remove falling sand/gravel
    primed-tnt: true                   # Remove lit TNT
    projectile: false                  # Remove arrows etc.
    boat: false                         # Remove boats
    minecart: false                     # Remove minecarts
    itemframe: false                    # Remove item frames
  item-filter: []                       # Items NEVER removed: ["DIAMOND","NETHERITE_INGOT"]
  warnings:
    - "time:60 msg:&6[OreoLag] &eEntities cleared in 60s!"
    - "time:10 msg:&6[OreoLag] &cClearing in 10s!"

command-remove:                        # What /olagg clear removes (can be different from auto)
  enabled: true
  broadcast-removal: true
  # same flags/filter as auto-removal above

tps-meter:                             # Run commands when TPS is low
  enabled: false
  interval: 15                          # Check TPS every 15 seconds
  tps-trigger: 14.0                    # Run commands when TPS drops BELOW this
  tps-recover: 19.0                    # Run recover-commands when TPS rises ABOVE this
  broadcast-enabled: true
  commands: []                          # Console commands on low TPS (e.g. ["olagg clear"])
  recover-commands: []

Warning Format

Warnings use a special inline format: time:<seconds> msg:<message>

warnings:
  - "time:300 msg:&6[OreoLag] &eItems will be cleared in 5 minutes!"
  - "time:60  msg:&6[OreoLag] &eItems cleared in 60 seconds!"
  - "time:10  msg:&6[OreoLag] &cClearing in 10s! Pick up your items!"

Commands

Player Examples

What Does It Do?

A Jump Pad is an invisible trigger attached to any specific block coordinate. When a player walks over that block, they get launched with a configurable velocity — great for parkour, arenas, hubs, or just having fun.

Creating a Jump Pad

Config File: server/jumpads.yml

This file stores the pad data — you don't edit it manually. Use the command to create pads.

jumpads:
  launch_1:                    # pad name (lowercased)
    name: launch_1
    world: world               # Minecraft world name
    x: 100                     # Block X coordinate
    y: 64                      # Block Y coordinate
    z: 200                     # Block Z coordinate
    power: 1.2                 # Horizontal launch force (higher = farther)
    upward: 1.0                # Vertical launch force (higher = higher)
    useLookDir: true           # true = launches in the direction you're looking

Understanding Power Values

Commands

Player Examples

What Does It Do?

TempFly gives players the ability to fly for a limited time. When the time runs out, flight is automatically disabled. Different ranks can get different durations. This is perfect for reward systems, donor perks, or event prizes.

Config File: server/tempfly.yml

use-permission-groups: true
# Check these permissions to decide how long to give
permission-groups:
  vip: 300            # "oe.tempfly.vip" → 300 seconds (5 min)
  premium: 600        # "oe.tempfly.premium" → 600 seconds (10 min)
  elite: 1800         # "oe.tempfly.elite" → 1800 seconds (30 min)

use-luckperms-groups: true
# Or use LuckPerms primary group name directly
luckperms-groups:
  default: 180        # "default" group → 180 seconds (3 min)
  vip: 300
  premium: 600

How Duration Resolution Works

Commands

Player Examples

What Does It Do?

Staff can give players formal warnings. The system tracks how many warnings each player has and automatically applies a punishment (kick, temp ban, or ban) when the limit is reached. Warnings can expire after a set time. All data is saved to warnings.yml.

Config File: server/warnings.yml

warnings:
  max-warnings: 3          # Number of warnings before punishment triggers

  max-action: tempban      # What happens at max warnings:
  #   none    = just notify, no punishment
  #   kick    = kick from server
  #   tempban = temporary ban (uses max-action-duration)
  #   ban     = permanent ban

  max-action-duration: 7d  # Duration for tempban: supports d/h/m/s (e.g. "3d12h")

  broadcast-on-warn: false # Broadcast to all staff when someone is warned
  # Requires oreo.warn.see-broadcasts permission to receive the broadcast

  expire-after: ""          # How long until warnings expire (e.g. "30d")
  # Leave blank ("") for warnings that never expire

Commands

How It Works Step by Step

Player Examples

What Does It Do?

ModGUI provides a visual, clickable GUI panel for staff members. Instead of memorizing dozens of commands, moderators can open one menu and access everything: player inspection, inventory viewing, banning, kicking, freezing, notes, IP lookup, chat moderation, world management, and performance tools.

How to Open

Config File: server/modgui.yml

worlds: {}
# World-specific configurations for ModGUI world management features.
# Leave empty to use defaults. Example:
# worlds:
#   world:
#     pvp: true
#     mob-spawning: true

Available Sub-Menus

Freeze Feature

Moderators can freeze a player (from the Player Actions menu or by command). A frozen player cannot move, chat, or interact. This is useful for mid-investigation holds.

Player Examples

Config: server/help.yml

help:
  mode: paginated   # "paginated" (pages with navigation) or "simple" (just print lines)

  # --- Simple mode only ---
  simple-text:
    - "&6=== SERVER HELP ==="
    - "&e/home &7- Teleport to your home"
    - "&e/warp &7- List server warps"

  # --- Paginated mode ---
  header: "&8&m------&r &6&lServer Help &7(Page {page}/{total}) &8&m------"
  footer: "&8&m------&r &7Use &e/help <page> &7to navigate &8&m------"
  entries-per-page: 8    # How many commands show per page

  entries:               # List of commands to display
    - command: "&e/home"
      description: "Teleport to your home"
      # no permission = visible to everyone

    - command: "&e/ban"
      description: "Ban a player (staff only)"
      permission: "oreo.ban"
      # ↑ Only shown to players who have this permission

Config: server/rules.yml

rules:
  lines:
    - "&6=== SERVER RULES ==="
    - "&e1. &7No hacking or using unfair advantages"
    - "&e2. &7Be respectful to all players"
    - "&e3. &7No griefing or stealing"
    - "&e4. &7No spamming or advertising other servers"
    - "&e5. &7Follow staff instructions"
    - "&7Breaking rules may result in a ban."

Commands

Player Examples

What Does It Do?

When a player joins the server, they receive a customizable join message after a short delay. You can configure:

• A default message all players see
• A first-join message for brand new players
• Group-specific messages for different ranks (VIP, staff, etc.)

Config File: server/motd.yml

motd:
  enabled: true
  delay-ticks: 20        # Ticks before sending (20 ticks = 1 second). Lets the world load first.

  default:               # Default MOTD for everyone
    - "&6Welcome back, &e%player%&6!"
    - "&7There are &a%online% &7players online."
    - "&7Type &e/help &7for commands."

  first-join:           # Shown only on the VERY FIRST join ever
    enabled: true
    lines:
      - "&a&lWELCOME TO THE SERVER, &e&l%player%&a&l!"
      - "&7This is your first time here. Type &e/rules &7to read the server rules."
      - "&7Need help? Type &e/help &7for all commands."

  groups:               # Rank-specific overrides — checked top to bottom
    - permission: "group.admin"
      lines:
        - "&c[ADMIN] &7Welcome back, &c%player%&7!"
        - "&7Staff channel: /staffchat"

    - permission: "group.vip"
      lines:
        - "&6[VIP] &7Welcome, &6%player%&7!"
        - "&7Your VIP perks: /fly, /nick, /kit vip"

Placeholders

Commands

Player Examples

What Does It Do?

Craft Actions let you reward players for crafting specific items. When someone crafts a configured item, the server can:

• Run console commands (give money, effects, broadcast, etc.)
• Send the player a custom MiniMessage formatted message

Works for both vanilla items (like DIAMOND_SWORD) and custom-named recipes from the CustomCraft system.

Config File: server/craft-actions.yml

actions:

  # --- Vanilla item: use the Material name (all caps) ---
  DIAMOND_PICKAXE:
    commands:
      - "eco give %player% 50"        # Give $50 via Vault economy
      - "broadcast &e%player% crafted a Diamond Pickaxe!"
    message: "<green>You earned <gold>$50</gold> for crafting this pickaxe!</green>"

  DIAMOND_SWORD:
    commands:
      - "effect give %player% strength 60 1"
    message: "<aqua>You feel powerful wielding this sword!</aqua>"

  # --- Custom recipe: use the recipe name (lowercase) ---
  my_magic_staff:
    commands:
      - "give %player% blaze_rod 1"
    message: "<yellow>You crafted a magical staff!</yellow>"

Available Placeholders

Player Examples

What Does It Do?

Imagine a world so large it can't run on one server. Sharding splits the world into a grid of zones, each hosted on its own server. When a player walks from one zone to the next, they're silently transferred to the correct server — the world feels endless and seamless.

Config File: server/shards.yml

sharding:
  enabled: false             # Must set to true to activate sharding
  proxy: VELOCITY          # VELOCITY or BUNGEECORD
  transfer-cooldown-ms: 3000 # Milliseconds between transfers (prevents exploit loops)

  redis:
    host: localhost
    port: 6379
    password: ""            # Leave blank if no auth

  worlds:
    world:                  # Minecraft world name
      enabled: true
      mode: GRID             # GRID (rectangular zones) or RADIAL (ring zones)
      shard-size: 10000      # Size of each zone in blocks
      transfer-buffer: 12    # Blocks from border that trigger transfer
      safe-zone: 16          # Block radius around border that prevents combat
      dimension-servers:
        overworld: "shard-%shard%"  # Server name pattern. %shard% = "0-0", "1-0", etc.

How It Works

GRID vs RADIAL Mode

Safe Zone

The safe-zone setting creates a combat-free border buffer. Players within safe-zone blocks of a shard boundary cannot be attacked. This prevents players from exploiting border transfers during combat.

Commands

All Permissions

Maintenance

ClearLag

JumpPads

TempFly

Warnings

ModGUI

Help & Rules

MOTD

Shards

Frequently Asked Questions

item-filter:
  - DIAMOND
  - NETHERITE_INGOT
  - NETHERITE_SCRAP
  - ELYTRA

auto-kill-mobs:
  mob-filter:
    - WOLF
    - CAT
    - HORSE

entries-per-page: 5   # Show 5 commands per page instead of 8

groups:
  - permission: "group.vip"
    lines:
      - "&6Welcome back, VIP %player%!"
      - "&7Your exclusive /kit vip is ready!"