Monoceros | With Fluxon scripts driving everything

What Is Monoceros?

Monoceros is designed for Minecraft server gameplay development. It provides a complete infrastructure layer for building custom server mechanics:

• A unified event listening and dispatching system
• A powerful Fluxon scripting engine as the replacement for Kether
• Visual-style action workflows and a flexible property system
• Packet-level tracing, interception, and rewriting
• Client-side illusions, fake blocks, fake world borders, and other volatile capabilities
• Five major gameplay mechanic domains: combat, regions, interactions, visuals, and sessions
• Configuration-driven design, hot-reload friendly, and far less hardcoding

Stop rebuilding the same foundation for every mechanic. Put your time back into gameplay design.



Core Features

1. Fluxon Scripting Engine

Monoceros uses Fluxon as its unified scripting runtime. Event listeners, commands, scheduled tasks, and workflow nodes can all be driven by scripts.

Scripts are loaded from the file system and support incremental hot reload, precompiled caching, SHA-256 change detection, and real-time FileWatcher monitoring.

Reserved system variables: sender, player, source, scriptId, now, and thread. They can be used directly in scripts.

Monoceros automatically imports cc.bkhk.monoceros.*, cc.bkhk.monoceros.api.*, org.bukkit.*, org.bukkit.entity.*, and org.bukkit.inventory.*, so manual imports are usually not required.

Scripts can directly access the Monoceros API through static calls. Relevant methods are annotated with @JvmStatic:

Built-in Extension Functions

Monoceros registers seven categories of extension functions into the Fluxon runtime. They can be called directly from scripts without imports:

• JSON: jsonParse(str) / jsonStringify(obj) / jsonPretty(obj) - JSON parsing and serialization
• HTTP: httpGet(url) / httpPost(url, body) / httpRequest(...) - Asynchronous HTTP requests, consumed with await
• UUID: uuid() / uuidFromString(str) / uuidFromName(name) - UUID generation and parsing
• Cooldown: cooldown(key, ms) / hasCooldown(key) / getCooldown(key) - Cooldowns and rate limiting
• Color: colored(text) / uncolored(text) - Color-code conversion, including the :: colored() extension style
• Logging: logInfo(msg) / logWarn(msg) / logDebug(msg) / logError(msg) - Structured logging
• Regex: regex(pattern) / regexMatch(text, pattern) / regexReplace(...) - Regex matching and replacement

2. Event Dispatcher System

Monoceros manages event listeners through a unified Dispatcher system:

• Three-level routing by event type, priority, and weight
• Multiple handlers under the same priority are sorted by weight
• Dynamic registration, dynamic unregistration, and automatic dispatch-table rebuilds after hot reload
• Five-stage pipeline: initPrincipal -> initVariables -> filter -> afterFilter -> postprocess
• Built-in cooldowns using Baffle, list filters, player extraction by reflection, and more
• Route targets include scripts, action workflows, and custom handlers

For states that Bukkit does not expose as native events, such as armor changes, Monoceros fills the gap through StateProbe.

3. Scheduler System

Monoceros supports four schedule types: delay ( DELAY), periodic ( PERIODIC), cron expression ( CRON), and conditional trigger ( CONDITIONAL).

• Maximum run count and maximum duration limits
• Pause, resume, and stop support, with full runtime control
• Prototype mode for parallel multi-instance execution
• Sender selectors: CONSOLE / ONLINE_PLAYER / PLAYER / WORLD / RANGE / AREA
• Lifecycle scripts: onStart / onStop / onPause / onResume

4. Action Workflows

Break complex logic into ordered node chains. Configuration becomes executable logic:

Monoceros includes 15 built-in action nodes:

• script - Calls a Fluxon script
• set - Sets a context variable
• log - Outputs a log message
• wait - Delays execution by ticks
• branch - Conditional branch using script evaluation and then/else paths
• loop - Iterates over values
• sound - Plays a sound
• tellraw - Sends rich text messages
• regex - Regex matching and capture-group extraction
• try-catch - Exception handling and fallback logic
• input - Waits for player input through chat capture with timeout support
• if-else - Conditional branch
• math - Math operations: abs, ceil, floor, round, sqrt, pow, min, max, random, sin, cos, tan, log
• coerce - Numeric range constraint
• dispatch - Dispatches to a child workflow, script, or dispatcher

Control flow supports Continue, Delay for asynchronous continuations without blocking, Branch for conditional branches, and Break for interruption.

5. Packet Listening with Wireshark

Low-level packet listening, filtering, tracing, interception, and rewriting:

• Supports PacketReceiveEvent and PacketSendEvent
• Player-level packet sessions through PacketSession, with per-player Tap enable/disable control
• Interception and rewriting are controlled by the global wireshark.allow-intercept switch and stay conservative by default
• Supports field-level rewriting through field-set
• Built-in MeteorInjector suppressor to automatically block external injector interference

6. Volatility

Client-side illusion effects that do not modify the real server state:

• Fake blocks: sendBlockChange / sendBlockChanges
• World borders: static borders and dynamically interpolated borders
• Entity metadata: glowing, invisibility, pose, health, riding state, and more
• Illusion sessions: each illusion effect is precisely identified through IllusionKey(viewerId, namespace, targetId), allowing multiple mechanics to write concurrently and roll back precisely by key

7. Property System

A unified property read/write framework covering core Bukkit objects:

• Location: x/y/z/yaw/pitch/world/block/chunk/direction, readable and writable
• Vector: complete 3D vector math including construction, arithmetic, geometry, and rotation
• Entity / LivingEntity / Player: chained access and writing for full property sets
• World: time, weather, difficulty, and player list
• ItemStack: type, amount, enchantments, flags, durability
• Block: type, light level, biome, and data
• Event: generic event properties plus dedicated property accessors for 15 specific event types

Six Extension Domains

Entity Domain

Entity operations: damage, healing, teleportation, potion effects, attribute toggles, and equipment setting.
Location operations: construction, cloning, modification, arithmetic, and distance calculation.
Vector operations: a complete 3D math library, including normalization, dot product, cross product, and rotation.

Event Domain

Event control: cancellation, ignore flags, property writing, and reply messages.
Asynchronous waiting: event.wait can wait asynchronously for a specified event to be triggered, with timeout support.

Illusion Domain

• Glowing effects with rollback support
• Visual warnings using Title, Subtitle, ActionBar, and world border pressure
• Breathing warnings based on sine-wave changes
• Fake blocks, fake health, and client-side holographic text
• Illusion context switching

Item Domain

Full item lifecycle: build items, change names, lore, enchantments, flags, durability, colors, and tags.
Item operations: consume, destroy, drop, and give.
Inventory operations: check, count, find, switch, and take out.
Potion operations: query, set, remove, and clear.

Memory Domain

Key-value storage across six scopes: GLOBAL / PLAYER / ENTITY / WORKFLOW / SCRIPT / SESSION.
TTL expiration is supported, such as 3000ms or 3s, with automatic expiration checks and thread-safe storage.

Target Domain

Nine target selection modes: self, world, whole server, radius, cuboid, nearest N targets, ring, specified player, and line-of-sight selection.
Target operations: filter by type, filter by script condition, and execute child workflows for each target.



Five Gameplay Mechanic Domains

Combat Mechanics

• Cooldown management: setCooldown / getCooldownRemaining / hasCooldown
• Combo tracking: recordHit, returning combo count, plus getComboCount and resetCombo
• Status stacking: apply with stacks/maxStacks and TTL, remove, and get
• Skill executor: five-stage execution chain CONDITION -> WINDUP -> EXECUTE -> RECOVERY -> COOLDOWN

Region Mechanics

• Region definitions: Cuboid and Sphere
• Region events: enter, leave, and stay, with configurable detection intervals
• Region effects: automatic Buff/Debuff application
• Region scripts: onEnter / onLeave / onStay

Interaction Mechanics

• Interaction types: right click, left click, sneak right click, sneak left click, and sneak toggle
• Material filters: trigger by item type
• Line-of-sight locking: getLookAtTarget obtains the target entity and distance
• Cooldown control: independent cooldowns per interaction definition

Visual Mechanics

• BossBar: create, update, show, and hide, with color and style support
• ActionBar: duration-based message pushing
• Title: complete control over fadeIn, stay, and fadeOut
• Message queue: priority sorting to prevent message overwrites

Session Mechanics

• Player sessions: get, set, remove, and has, with snapshot and restore support
• Mechanic participation: joinMechanic / leaveMechanic / getActiveMechanics
• Context isolation: each player has an independent session, so multiple mechanics do not interfere with each other
• Direct API access: Monoceros.api().sessions() returns the SessionService and is available from scripts in one line

Command System

Main command: /monoceros, alias: /mono, permission prefix: monoceros.command.

Command definitions are also configurable. Parameter types include STRING / INT / DOUBLE / BOOLEAN / PLAYER / WORLD / MATERIAL / SCRIPT_ID.



Configuration-Driven and Hot-Reload Friendly

All core features are driven by YAML configuration. Changes can be applied immediately with /mono reload:

File change detection is based on SHA-256 plus FileWatcher, so only files that actually changed are reloaded instead of refreshing everything.

Command reload uses delayed registration to avoid conflicts with Paper's asynchronous command-tree construction thread, keeping hot reload clean and error-free.



Cross-Version Support

Monoceros covers Minecraft 1.12.2 through 26.1.2. Version differences are handled through modular layers:

• module-legacy-api: legacy Material, NBT, and text compatibility
• module-modern: Data Components and modern ItemMeta support
• module-java17 / module-java21: isolation for Java-version-specific dependencies
• NMS differences are bridged through TabooLib nmsProxy, keeping business logic free from version checks

Operations and Diagnostics

• /mono selfcheck: automatically detects configuration errors, missing dependencies, and incompatible versions
• /mono diag dump: exports full runtime-state information
• /mono diag cache: exports cache hit rates and compilation statistics
• DiagnosticLogger: unified diagnostic logging with toggleable debug mode
• Reload reports: each reload outputs loaded / updated / failed / costMs

AI-Assisted Development Examples

Monoceros provides a Monoceros AI Skill that can be used directly in AI coding assistants with Skill support, such as Kiro. This Skill includes knowledge of Monoceros configuration formats, mechanic services, and Fluxon scripting syntax, helping the assistant generate more accurate configurations and scripts.

The Skill files are available in the repository: https://github.com/YsGqHY/Monoceros/tree/master/.claude/skills

How to use it: place the Skill files into the corresponding directory of your AI coding assistant, then describe your requirement in a conversation. The AI will automatically call the Monoceros Skill to retrieve the relevant knowledge before generating the result.

Example 1: Writing a Fluxon Script

Based on the Fluxon syntax and Monoceros context-variable knowledge provided by the Skill, the AI generates an accurate script:

Example 2: Generating a Complete Configuration Plan

Based on the dispatcher, scheduler, and workflow configuration knowledge in the Skill, the AI generates a complete solution in one pass:

Dispatcher configuration:
Schedule configuration:
Script:
Example 3: Debugging Packets

Example 4: Designing an Action Workflow



Quick Start

1. Put the Monoceros plugin into your plugins/ directory.
2. Start the server. Monoceros will generate the default configuration and example files automatically.
3. Edit configuration files under dispatcher/, schedule/, script/, and related directories.
4. Use /mono reload to hot-reload changes instantly.
5. Use /mono status to inspect service states and /mono selfcheck to troubleshoot problems.

Why Choose Monoceros?

• Gameplay infrastructure: no need to develop a separate plugin foundation for every mechanic
• Configuration-driven: both server planners and developers can participate in gameplay design
• Fluxon scripts: a more modern and powerful scripting experience, closer to Kotlin-style scripting
• Built-in extension function library: JSON / HTTP / UUID / cooldown / color / logging / regex, ready out of the box
• Hot reload: configuration and script changes take effect in seconds
• Cross-version support: one configuration system covers Minecraft 1.12.2 through 26.1.2
• Modular architecture: 28 submodules composed by need, with clear responsibilities

Links

• GitHub repository: https://github.com/YsGqHY/Monoceros
• Discord community: https://discord.gg/Uz3EXh99T
• Issue tracker: https://github.com/YsGqHY/Monoceros/issues
• Releases: https://github.com/YsGqHY/Monoceros/releases