OlEncounters

Build cinematic world encounters that arrive, fight, reward, and disappear without leaving the world damaged.

OlEncounters is a highly configurable encounter and world-event plugin for Paper and Folia. Create meteor impacts, portal invasions, structures that rise from the ground, flying encounters, boss arenas, resource sites, treasure events, and more—all from one system.

Every encounter can have its own schematic, arrival animation, mobs, waves, loot, leaderboard, messages, effects, location rules, and cleanup behavior.

More than a meteor plugin

OlEncounters is designed as a general encounter engine. A preset can represent almost any temporary world event:

• A meteor crashing into a forest
• A structure emerging from underground
• A dungeon entrance materializing through a portal
• A boss arena descending from the sky
• A flying structure arriving from the horizon
• A timed resource site with personal loot
• A multi-wave invasion with ranking rewards

Each preset is configured independently, so two encounters in the same category can behave completely differently.

Full-schematic arrival animations

The plugin can animate the schematic itself instead of moving only a decorative meteor core. Schematic blocks are represented with display entities during arrival, then the real structure is safely placed when the animation finishes.

Available encounter arrival modes:

• Instant placement
• Normal sky fall
• Slow cinematic descent
• Underground rise
• Portal arrival
• Materialization
• Horizontal fly-in

Animation duration, distance, particle density, sounds, display limits, batch size, and layer timing can be adjusted per encounter. Large schematics can use safe limits and automatic fallback behavior to protect server performance.

In-game setup and editing

Create encounters without manually calculating every position in configuration files. The guided setup system lets administrators build a new preset or edit an existing schematic directly in game.

Setup tools can be used to define:

• The schematic root block
• Selection boundaries
• Multiple mob spawn points
• Multiple loot locations
• Custom loot blocks, including chests or other materials
• Hologram and text positions
• Saved schematic names
• Whether the temporary setup structure should be removed afterward

Selecting an existing point again removes it. Setup inventories are backed up, temporary tools are cleaned when leaving, and administrators can exit with or without saving.

MythicMobs, waves, and animated mob arrivals

Build anything from a small creature encounter to a multi-stage boss fight. Each preset can define multiple MythicMobs entries, selection weights, spawn locations, and wave behavior.

Mob arrival modes include:

• Instant spawn
• Sky descent
• Underground emergence
• Portal arrival
• Materialization

Encounter mobs can be protected from natural distance-based despawning and are cleaned up by the event lifecycle. The MythicMobs selector supports multiple pages when the available mob list exceeds one inventory.

Flexible loot and rewards

Loot does not have to come from a single chest. Each encounter can contain multiple loot points, and nearly any configured block can act as a loot source.

The reward system supports:

• Personal or shared loot
• Drag-and-drop in-game loot editing
• Per-item chance, weight, and amount
• Multiple loot blocks
• Reopenable containers until they are emptied
• Locked reward vaults
• Optional key requirements
• Custom key items
• Damage-ranking rewards
• Console-command rewards
• ItemsAdder items
• NBT, PDC, and modern Data Component preservation

With personal loot enabled, every player's reward state is tracked independently.

Automatic encounters with advanced location rules

OlEncounters can automatically select and start encounters within configurable time and distance ranges. Multiple presets can share a category, with weighted selection controlling how often each one appears.

Automatic placement supports:

• Per-world configuration
• Custom center positions
• Minimum and maximum radius
• Circle, square, triangle, diamond, and hexagon search shapes
• Land, air, underground, and any-surface placement
• Configurable Y ranges
• Rough terrain and tree-top placement
• Allowed and blocked surface materials
• Water and lava rules
• World-border validation
• WorldGuard region avoidance
• Towny town avoidance
• TPS protection
• Inactivity cleanup when nobody participates

Location searches are processed in controlled batches to avoid freezing the server. Search results and rejection reasons are reported for easier administration and troubleshooting.

Messages, leaderboards, and player feedback

Every encounter can have independent start, arrival, combat, reward, and completion messages. Messages can target all players, nearby players, distant players, participants, administrators, or the console.

Optional combat features include:

• Live action-bar damage feedback
• Per-encounter damage leaderboards
• Rank-specific rewards
• Item or command rewards
• Clickable administrator location messages
• Turkish and English locale files
• Language-aware command suggestions

Leaderboards and action-bar feedback can be enabled or disabled separately for every encounter.

Safe cleanup and terrain restoration

Temporary events should not permanently damage the world. OlEncounters records the affected area and can restore it after the encounter ends.

Cleanup can remove:

• The encounter structure
• Blocks placed during the event
• Changes made by players
• Encounter mobs
• Loot blocks and containers
• Display entities
• Holograms
• Pending animation tasks

The plugin can display a cleanup countdown, use a separate inactivity timeout, and recover unfinished events after an unexpected server shutdown. FAWE can be used for efficient restoration of larger areas.

Built for Paper and Folia

OlEncounters uses region-aware and entity-aware scheduling for Paper and Folia environments. Expensive work is split into controlled batches, display counts can be limited, and automatic events can pause when server performance falls below configured thresholds.

Performance controls include:

• Folia-compatible scheduling
• Batched schematic animation
• Configurable display-entity limits
• Batched location searching
• TPS protection
• Safe chunk-loading limits
• Task and entity cleanup
• Controlled cancellation after startup failures

Integrations

Required

• CommandAPI

Supported integrations

• FastAsyncWorldEdit
• WorldEdit
• WorldGuard
• Towny
• MythicMobs
• ItemsAdder
• PlaceholderAPI
• FancyHolograms
• NBT API

Optional integrations are loaded through isolated safe hooks. If an optional plugin is missing, only the related features are disabled instead of crashing the entire plugin.

Requirements

• Paper or Folia
• Minecraft 1.21.1 or newer
• Java 21
• CommandAPI

WorldEdit or FastAsyncWorldEdit is recommended when using schematic-based encounters.

Main command

/olencounters

Setup, event management, automatic scheduling, previews, history, configuration, and diagnostic tools are organized under the main command. Command suggestions follow the selected Turkish or English locale.

Updating from OlMeteor

OlEncounters can detect an older OlMeteor data directory and migrate existing data to the new plugin folder. Compatibility aliases are retained for legacy commands, permissions, PlaceholderAPI identifiers, and persistent data tags.

Only one plugin JAR should be installed. Remove the old JAR before starting the server with OlEncounters.

Support information

When reporting a problem, include the OlEncounters version, Paper or Folia build, Java version, installed integrations, complete console error, relevant preset configuration, and reproduction steps.

OlEncounters 1.5.0
Developed by OlPlugins