Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

3 Commits
docs
docs
 
 
README.md
README.md
 
 

Repository files navigation

AnarchyRuleEngine

Integration-first gameplay and rule engine for Paper 1.16.5.

This repository contains the public documentation showcase for AnarchyRuleEngine. The engine source code and release artifacts are maintained in a private repository.

Java 8 Paper 1.16.5 Version Status

AnarchyRuleEngine is a modular plugin foundation that provides a configurable Rule Engine, Core Services, an Integration Layer, gameplay modules, and diagnostics. It is designed to operate alongside an existing Paper server stack as a controlled modernization layer — not to replace it.

Gameplay modules are opt-in and disabled by default. Integration, compatibility scanning, and diagnostics are available from first startup without activating any gameplay.

Table of Contents

Overview

AnarchyRuleEngine is an engine plugin, not a server distribution. It provides:

  • A Rule Engine that evaluates YAML-configured rules against player interactions.
  • A Core Services layer that abstracts external plugin APIs behind stable interfaces.
  • An Integration Layer that detects and connects to optional plugins at startup.
  • Gameplay modules (combat, custom items) that can be individually enabled via feature flags.
  • Diagnostics including a compatibility scanner, state dump, config validator, and error history.

It does not force changes to existing mechanics. It can be started alongside a working server stack and remain fully passive until explicitly configured.

Project Goals

  • Isolate gameplay code from external plugin APIs.
  • Support gradual migration of legacy mechanics without rewriting the core.
  • Provide safe fallback service implementations when optional plugins are absent.
  • Make compatibility and runtime state fully observable.
  • Allow new rules, actions, conditions, items, and modules to be added without touching the engine core.

Safe-by-Default Behavior

The default configuration ships with all gameplay modules disabled and no runtime rules:

features:
  combat: false
  custom-items: false

rules: {}

On a clean start with this configuration:

  • No combat listeners or tasks are registered.
  • No custom item listeners or mechanics are active.
  • No rules are evaluated.
  • Integration detection, the Compatibility Scanner, and all diagnostic commands remain fully available.
  • Item definitions may still be loaded declaratively for admin tooling and matching, but custom item mechanics do not activate.

Architecture Overview

flowchart TD
    A[Commands / Events] --> B[Rule Engine]
    B --> C[Actions and Conditions]
    C --> D[Core Services]
    D --> E[Integration Layer]
    E --> F[WorldGuard]
    E --> G[LuckPerms]
    E --> H[Vault]
    E --> I[PlaceholderAPI]

    B --> J[Modules]
    J --> K[Combat]
    J --> L[Custom Items]

    B --> M[Diagnostics]
Loading

See full architecture documentation for package structure, lifecycle details, and component diagrams.

Core Services

Gameplay code communicates with external plugins exclusively through internal service interfaces. This prevents direct API dependencies in rules, conditions, and actions.

Service Default implementation Optional provider
RegionService DefaultRegionService WorldGuardRegionService
PermissionService DefaultPermissionService LuckPermsPermissionService
EconomyService DefaultEconomyService VaultEconomyService
PlaceholderService DefaultPlaceholderService PlaceholderApiService

Default implementations provide safe fallback behavior. The optional provider is activated automatically when the corresponding integration plugin is present and available at startup.

Optional Integrations

Integration Required Purpose
WorldGuard No Region access and protection checks
WorldEdit No Environment detection and WorldGuard ecosystem support
LuckPerms No Permission and group backend
Vault No Economy backend
PlaceholderAPI No External placeholder resolution

If an optional integration is unavailable, ARE keeps running with a safe default implementation. Note that some actions and conditions have reduced or no functionality without their provider — for example, economy actions require an active economy provider registered via Vault.

Requirements

Required:

  • Java 8
  • Paper 1.16.5

Optional:

  • WorldGuard 7.x and WorldEdit (for region conditions and protection checks)
  • LuckPerms (for permission and group-based conditions)
  • Vault with a compatible economy provider (for economy conditions and actions)
  • PlaceholderAPI (for external placeholder resolution in messages and conditions)

Installation and Safe First Startup

Installation is performed only through private evaluation builds or during controlled pilot testing.

  1. Obtain the approved private evaluation build through the pilot or evaluation process.
  2. Place the provided jar into the server's plugins/ directory.
  3. Start the server with the default configuration (modules disabled, rules: {}).
  4. Review the startup log and confirm:
    • Compatibility Scanner result (SAFE / WARNING)
    • Hook detection states for all optional integrations
    • Active Core Service implementations
    • Rules loaded: 0
    • Gameplay modules skipped (feature flags disabled)
  5. Run the following diagnostic commands as an administrator:
/are compatibility
/are dump
/are modules
/are validate
  1. Review the dump output and compatibility report before enabling any gameplay.
  2. Enable gameplay modules and rules only after review, preferably in a separate test environment.
  3. Restart the server fully after changing any feature flag — /are reload does not hot-enable or hot-disable modules.

Feature Flags

Feature flags control module lifecycle. They are read once at startup:

features:
  combat: false
  custom-items: false
  • Setting a flag to true requires a full server restart to register listeners, tasks, and services.
  • Setting a flag to false requires a full server restart to cleanly unregister them.
  • /are reload intentionally does not enable or disable modules at runtime to prevent duplicate listeners, orphaned tasks, and partial runtime state.

Rule Engine

Rules are defined in config.yml under the rules: key. Each rule specifies conditions and actions. Rules are evaluated from highest to lowest priority. When a matched rule has stop-processing: true, lower-priority rules are skipped.

Example rule

rules:
  plast-use:
    enabled: true
    priority: 100
    stop-processing: true

    conditions:
      item: plast
      interaction-action:
        - RIGHT_CLICK_AIR
        - RIGHT_CLICK_BLOCK
      cooldown: plast

    actions:
      - type: cooldown
        seconds: 20
      - type: message
        message: "&a%player%, cooldown active for &c%cooldown_remaining%s&a."
      - type: remove-item
        amount: 1
      - type: cancel

Conditions

Built-in: always, item, material, interaction-action, permission, world, region, y-min, y-max, cooldown, on-cooldown, biome, gamemode, health, food, level, exp, weather, time, potion, sneaking, item-name, item-name-contains, light-level, dimension, mainhand, offhand, armor, enchantment, nearby-player, nearby-entity, nearby-block, scoreboard-team, flying, sprinting, swimming, gliding, on-ground, money.

Numeric conditions accept literal values or comparison expressions: health: "<=10", level: ">=30".

Actions

Built-in: message, cancel, cooldown, remove-item, sound, particle, title, actionbar, command, player-command, give-item, teleport, potion, clear-potion, heal, feed, lightning, gamemode, broadcast, kick, spawn-mob, explosion, set-block, clear-inventory, velocity, firework, economy.

All text-based actions support the internal placeholder engine and PlaceholderAPI placeholders when the integration is active.

Composite conditions

conditions:
  and:
    - item: plast
    - or:
        - world: world
        - world: world_nether
    - not:
        permission: anarchyruleengine.bypass.plast

and and or accept a list of condition maps. not accepts exactly one condition map. Composite conditions may be nested to any depth. Existing flat condition syntax remains fully supported and is treated as implicit AND.

Expression conditions

conditions:
  expression: "(%health% < 10 || %food% < 5) && %gamemode% == SURVIVAL"

Supported operators: ==, !=, >, >=, <, <=, &&, ||, !, and parentheses.

Scheduled and delayed actions

- type: delay
  delay: 5s
  actions:
    - type: message
      message: "&aDelayed message."

- type: repeat
  every: 2s
  times: 5
  actions:
    - type: particle
      particle: VILLAGER_HAPPY

Durations accept ticks (20t), milliseconds (500ms), seconds (5s), and minutes (1m).

Internal placeholders

Available in message and text fields: %player%, %display_name%, %world%, %x%, %y%, %z%, %material%, %interaction%, %rule_id%, %rule_priority%, %cooldown_id%, %cooldown_remaining%, %cooldown:<id>%.

Unknown placeholders are preserved unchanged, making configuration mistakes visible without breaking rule execution.

Rule groups

Rules may be organized into named groups for bulk enable/disable management via /are group.

Custom Item Framework

Custom items are defined in config.yml and activated through a centralized pipeline:

CustomItemListener
  → CustomItemUseService
    → CustomItemActivationPipeline
      → CustomItem.activate(...)

The pipeline enforces, in order:

  1. Feature flag check (custom-items must be enabled).
  2. Item recognition.
  3. Trigger type match.
  4. Permission check (if required-permission is set on the item).
  5. Enabled state (runtime toggle).
  6. Region check (if the item has requires-region-access: true).
  7. Cooldown check.
  8. Activation via CustomItem.activate(...).
  9. Cooldown start and item consume only after successful activation.

Region policy: The region check uses a strict implementation that does not honour general WorldGuard bypass flags or OP status. The only way to bypass region restrictions for custom items is the explicit permission:

anarchyruleengine.customitems.region-bypass

This permission defaults to false. Wildcard permission semantics depend on the installed permission system.

Modules

Modules encapsulate gameplay features with a well-defined lifecycle:

Module Feature flag Description
Core Always active Rule engine, diagnostics, services, commands
Combat features.combat Combat event handling
Custom Items features.custom-items Custom item activation pipeline

Each module registers its own listeners, tasks, and services during startup and cleans up on disable or reload. Module hot-reload is not supported — changes to feature flags require a full server restart.

Diagnostics

Tool Command Description
Compatibility Scanner /are compatibility Checks external plugin presence, API compatibility, potential conflicts
State Dump /are dump Exports full engine state: services, hooks, rules, modules, errors
Config Validator /are validate Validates on-disk config.yml without changing active state
Module Status /are modules Lists registered modules with their current lifecycle state
Error History /are errors Shows recent internal errors recorded by the engine
Rule Tracing /are trace <player> on|off Enables per-player rule execution tracing
Debug Mode /are debug [player] on|off|status Controls verbose rule execution output
Performance Stats /are stats Shows rule evaluation statistics; supports reset and export
Profiler /are profiler Controls the internal performance profiler

The startup log also includes a service summary, hook detection results, and module initialization status.

Commands

All subcommands are registered under /are (alias: /anarchyruleengine).

Command Purpose Type Permission
/are help Shows available commands Read-only —
/are version Shows plugin version and server platform Read-only —
/are reload Atomically reloads items and rules from config State-changing anarchyruleengine.command.reload
/are validate Validates config without applying changes Read-only anarchyruleengine.command.validate
/are give <player> <itemId> [amount] Gives a configured custom item State-changing anarchyruleengine.command.give
/are item <...> Custom item management (list, info, give) Mixed anarchyruleengine.command.give
/are rules Lists all loaded rules Read-only anarchyruleengine.command.inspect
/are inspect <ruleId> Describes a loaded rule Read-only anarchyruleengine.command.inspect
/are rule <ruleId> enable|disable|reset Toggles runtime rule state State-changing anarchyruleengine.command.rule
/are group <groupId> <...> Manages rule groups (enable/disable) State-changing anarchyruleengine.command.group
/are debug [player] on|off|status Controls verbose debug output State-changing anarchyruleengine.command.debug
/are trace <player> on|off|status|stop Enables per-player rule execution tracing State-changing anarchyruleengine.command.trace
/are stats [reset|export] Shows, resets, or exports rule evaluation statistics Mixed anarchyruleengine.command.stats
/are profiler <...> Controls the performance profiler Mixed anarchyruleengine.command.profiler
/are errors [clear] Shows or clears internal error history Mixed anarchyruleengine.command.errors
/are dump Generates a full engine state dump Read-only anarchyruleengine.command.dump
/are modules Lists registered modules and their status Read-only anarchyruleengine.command.modules
/are compatibility Runs compatibility and environment check Read-only anarchyruleengine.command.compatibility
/are gui Opens the rule administration GUI State-changing anarchyruleengine.command.gui

Configuration Examples

Annotated rule and integration examples are available separately:

Reload Safety

/are reload follows a transactional pattern:

  1. The candidate config.yml is parsed and all rules are fully constructed and validated.
  2. If any step fails, the previous working rule set and custom-item registry remain active — no partial state is applied.
  3. If all steps succeed, the new snapshot replaces the active state atomically.
  4. Module feature flags are not affected by reload. Changes to feature flags require a full server restart.
  5. Reload does not register duplicate listeners or tasks.

Testing

The engine has been functionally tested in a dedicated Paper 1.16.5 test environment.

Validation included:

  • plugin startup and shutdown
  • reload workflow
  • rule loading
  • compatibility diagnostics
  • core services
  • optional integrations
  • custom item framework
  • feature flags
  • diagnostic commands

Testing was performed on a dedicated local Paper 1.16.5 server configured for engine validation.

Production deployment on VimeWorld has not yet been performed.

Known Limitations

  • Feature flag changes require a full server restart. /are reload does not hot-enable or hot-disable modules.
  • Optional integrations provide reduced functionality when unavailable. Some conditions and actions are inert or return safe defaults without their required provider.
  • WorldGuard is required for real region protection. The default RegionService does not enforce region boundaries.
  • Economy actions require a registered economy provider via Vault. Without it, economy actions will not execute.
  • Production testing against a live server environment has not been performed. Controlled pilot testing in an isolated environment is recommended before production deployment.
  • Command implementation is planned for further modularization in a future release.

Documentation

Document Description
Architecture Package structure, lifecycle, component diagrams
Public API Stable public API surface for external consumers
Module API API for building and registering custom modules
Integration Audit External plugin compatibility analysis
Advanced rules Annotated YAML rule examples
Content integrations Integration-specific rule examples

Source Availability

  • The AnarchyRuleEngine source code is private.
  • Build artifacts are not publicly distributed.
  • This repository provides technical documentation and showcase materials.
  • Access to the implementation may be provided separately for evaluation or collaboration.

Current Release Status

AnarchyRuleEngine v1.0.0 is integration-ready for controlled pilot testing.

It is designed for passive first startup and staged feature activation. All gameplay modules are disabled by default. The engine can be started alongside an existing server stack without activating any gameplay or altering existing mechanics.

Functional testing has been completed in a dedicated local Paper test environment.

It has not been validated against a production server environment. Controlled pilot testing in an isolated or staging environment is recommended before enabling any gameplay modules in production.

About

Public showcase and documentation of AnarchyRuleEngine, a private modular gameplay engine for Minecraft Paper servers.

Topics

architecturedocumentationgame-enginejavaminecraftminecraft-serverpaperrule-engineserver-developmentworldguard

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Contributors