Core

Core is a focused Paper 1.21.11 moderation and server-essentials plugin for Java 21. It deliberately does not include economy, homes, warps, kits, private-message/chat commands, broad grief tools, or chat formatting. Carbon remains responsible for chat, and another economy plugin remains responsible for money.

Included

• /skylines <feature> as the branded command surface, with /core and /vcore compatibility
• Central, namespaced /skylines give <item> [player] [amount] registry exclusively for config-backed MC Skylines suite items
• /modmode / /core modmode transient LuckPerms elevation while preserving ordinary RP/job groups
• Direct Carbon integration that automatically enables spy during mod mode and restores its prior state afterward
• Manual and automatic /afk, configurable activity detection, broadcasts, action-bar reminders, and optional AFK kicking
• Protected-target /sudo with per-command permissions, allow/deny policy, safe auditing, and no chat impersonation mode
• Essentials-style utilities and shortcuts: /fly, /god, /gm, /gmc, /gms, /gma, /gmsp, /tp, /tph, /back, /heal, /feed, /speed, /ci, /ec, /invsee, /workbench, /anvil, and /ping
• Spawn: /spawn, /setspawn, first-join/every-join spawn, respawn handling, and configurable void rescue
• Manual warnings, kicks, permanent/temporary mutes, and permanent/temporary UUID bans
• Paper native profile-ban mirroring for interoperability
• Configured offense ladders through /punish <player> or /punish <player> <offense>
• Two-stage punishment GUI with a final permission, policy-revision, target-protection, and expected-step check
• Rolling warning thresholds with cooldowns and automatic actions
• Searchable, paginated punishment history
• Audited /removepunishment and warning-only /removewarn soft removal
• Safe MiniMessage sign colors/styles plus region-owned, line-by-line /editsign
• Particle-free, plugin-scoped /vanish and configurable visual-only /smite
• Persistent god/fly states, if enabled
• MiniMessage in every configurable message, GUI title, item name, lore line, and offense display name
• SQLite WAL storage, prepared statements, transactions, schema versioning, startup integrity checks, backups, and retention controls
• Reload with full validation and atomic configuration replacement
• WorldGuard entry checks for staff teleports
• LuckPerms-backed protection checks for offline staff targets

Install

1. Run Paper 1.21.11 on Java 21.
2. Remove the previous Core JAR, then copy build/libs/MCSkylines-Core-1.10.0.jar into the server's plugins folder. The internal plugin name and plugins/Core/ data folder remain unchanged.
3. Install LuckPerms for mod mode. WorldGuard and CarbonChat are optional soft integrations.
4. Start the server once, stop it, and edit the generated files under plugins/Core/.
5. Operators automatically receive core.admin. Grant narrower nodes to non-OP staff through LuckPerms and mod mode.
6. Use /skylines reload after changing Core configuration. A changed database path requires a restart.

Core declares SQLite through Paper's supported plugin-library loader, keeping the plugin JAR small while Paper caches the verified Maven dependency.

Configuration files

• config.yml — feature switches, storage safety, AFK policy, sudo policy, state behavior, teleport policy, mute command roots, spawn behavior, hooks, and retention
• punishments.yml — offense ladders, lookback windows, warning thresholds, durations, and reasons
• guis.yml — inventory sizes, slots, materials, MiniMessage names, and lore
• messages.yml — all user-visible text and MiniMessage formatting
• spawn.yml — atomically saved spawn coordinates; normally managed with /setspawn
• data.db — authoritative punishment, state, player identity, trigger, and audit data
• backups/ — timestamped startup database backups

Reload validates complete candidate files before replacing live policy. Invalid enum values, durations, materials, duplicate/out-of-range slots, unsafe database paths, unsupported config versions, and missing required nodes reject the reload.

Punishment schedules

Each offense has a stable lowercase key, display metadata, an individual permission, a rolling lookback, and ordered steps:

offenses:
  spam:
    display-name: "<yellow>Spam / Flooding"
    icon: PAPER
    slot: 10
    permission: core.punish.offense.spam
    lookback: 90d
    description:
      - "<gray>Repeated or disruptive messages."
    steps:
      - type: WARN
        reason: "Spam / flooding"
      - type: MUTE
        duration: 15m
        reason: "Repeated spam / flooding"
      - type: BAN
        duration: 1d
        reason: "Chronic spam / flooding"

Supported action types are WARN, KICK, MUTE, and BAN. Durations support compounds such as 1d12h, with s, m, h, d, w, mo, and y. Use permanent only for mutes and bans. The hard safety maximum is ten years.

Ladder calculation and insertion happen in one SQLite transaction. When a GUI confirmation specifies an expected step, any concurrent advancement makes that GUI stale. Configure exhausted ladders globally with repeat-last or deny.

Warning rules count non-revoked warnings in a rolling window. The highest matching threshold is selected, and its cooldown is claimed transactionally so concurrent warnings cannot double-trigger it.

/removewarn <case-id> <reason> removes only a warning; /removepunishment <case-id> <reason> handles any case. Removal is a transactional soft delete: the case disappears from history, warning thresholds, offense ladders, mute checks, and ban enforcement, while removal actor/time/reason remain in SQLite and an audit event is written. Removing one ban never pardons a different active ban.

Signs

Players with core.sign.format may use colors (named or hex), bold, italic, underline, strikethrough, reset, and the enabled gradient/rainbow options on placed signs or through /editsign [front|back] <1-4> [text]. The same permission enables configurable Bukkit legacy forms such as &a, &l, &r, &#RRGGBB, &x&F&F&0&0&F&F, and their section-sign equivalents. Operators receive this through core.admin. Formatting markup does not count toward signs.max-visible-characters-per-line; visible Unicode code points do. Click, hover, insertion, font, keybind, translation, selector, score, NBT, and newline tags are not registered and cannot create interactive signs.

/editsign changes the side the player is looking at unless front or back is supplied. Omitting text clears that line. Plain-text changes made through /editsign or the normal sign editor retain the line's existing color and decorations; supplying formatting or reset markup replaces them. Waxed signs and region bypass each have separate permissions. By default, the target sign must be in a WorldGuard region where the player is an owner or member. Property synchronizes landlords and active tenants as those WorldGuard owners/members, so rented properties work without database coupling. The check fails closed when WorldGuard is unavailable.

Vanish and smite

/vanish [player] [on|off] uses Bukkit's plugin-scoped hide/show API and never applies an invisibility potion, so it produces no invisibility particles. It is session-only, preserves hides owned by other plugins, suppresses a vanished player's real quit message when configured, and updates visibility when mod mode changes. Successful transitions can send editable fake vanilla-style quit/join messages to ordinary players. Core also removes the player from each affected viewer's Paper player list and publishes the conventional plugin-owned vanished=true metadata used by TAB's layout/global-list compatibility. Only tab entries actually removed by Core are candidates for restoration.

core.vanish.see sees Core-vanished players; by default those viewers do not receive the fake quit/join messages. Other-player and protected-target controls are separate nodes. The fake-message audience, individual messages, tab-list removal, and TAB metadata integration are configurable under vanish.

If TAB's Layout or Global Playerlist is enabled, grant tab.seevanished to the same senior staff who receive core.vanish.see; TAB uses its own permission when deciding who may see metadata-marked vanished players.

/smite <player> uses a visual lightning effect, so it cannot ignite blocks or apply uncontrolled lightning area damage. Direct damage and self-target policy are configured under smite; ordinary Bukkit damage events still run so protection plugins can cancel the damage.

Moderation mode setup

Moderators retain their ordinary RP/job groups at all times. /modmode attaches moderation.activated-group as a transient LuckPerms inheritance node; it does not change their primary group and is never written to LuckPerms storage. /modmode off, logout, plugin shutdown, or disabling the feature removes the node.

Create the activated group and grant the actual staff capabilities to it. Grant only core.modmode to the moderator's permanent/base staff role:

/lp creategroup mod-active
/lp group moderator permission set core.modmode true

/lp group mod-active permission set core.utilities true
/lp group mod-active permission set core.utilities.others true
/lp group mod-active permission set core.warn true
/lp group mod-active permission set core.kick true
/lp group mod-active permission set core.mute true
/lp group mod-active permission set core.unmute true
/lp group mod-active permission set core.history true
/lp group mod-active permission set core.history.reason true
/lp group mod-active permission set core.punish true
/lp group mod-active permission set core.punish.offense.* true
/lp group mod-active permission set core.notify true

core.utilities is the convenient self-utility preset that makes /fly, /gmc, /heal, /feed, /speed, /tp, /ec, /workbench, /anvil, and similar commands available while mod mode is active. core.utilities.others adds other-player targeting and read-only /invsee. Grant individual nodes instead when a staff tier should receive only part of that set.

Add senior-only nodes such as core.ban, core.unban, core.punish.direct, or staff-target overrides only to the appropriate activated senior group. You can change activated-group to that group name; changing it requires a restart so an active session can never silently swap privilege sets during reload.

For Carbon 3, the current official permission model uses carbon.spy and carbon.channel.<channel>.see / .speak. For a channel whose Carbon key is staff:

/lp group mod-active permission set carbon.spy true
/lp group mod-active permission set carbon.channel true
/lp group mod-active permission set carbon.channel.staff true
/lp group mod-active permission set carbon.channel.staff.see true
/lp group mod-active permission set carbon.channel.staff.speak true

With integrations.carbon.auto-enable-spy: true, entering mod mode enables Carbon spy through Carbon's API. Exiting restores the exact spy state from before that session. Removing the transient group also removes access to configured staff channels. Use the actual keys from your Carbon channel configuration.

The plugin independently rejects every command listed under moderation.gated-commands unless the player is active. This prevents a stray permanent Core permission from bypassing mode. core.modmode.bypass is intended only for owner/automation accounts. Console is always exempt.

An action-bar reminder is displayed while active. Successful entry and exit are broadcast using editable MiniMessage templates. By default, every five minutes the moderator receives a chat reminder with their elapsed session time, while other online staff with core.modmode.reminder.notify receive a separate administrative notice. Public broadcasts, both reminder layers, their intervals, and their audiences are configurable under moderation; the text is in messages.yml.

Exiting also restores the pre-session game mode, god state, plugin flight state, flight allowance, current flying state, walk speed, fly speed, and Carbon spy state. One-shot actions such as teleports, heals, and punishments are intentionally not reversed.

AFK

/afk toggles your own state. /afk status, /afk <player> status, and /afk <player> <on|off> provide status and staff control. Automatic AFK is based on configurable movement, final Paper chat, interaction, and command activity signals. Core observes chat without formatting, rerouting, or cancelling it, so Carbon remains the chat owner.

AFK state is intentionally session-only. It is cleared on disconnect and is never used as authentication or punishment evidence. Configure automatic timing, manual-AFK clearing, movement tolerance, broadcasts, action-bar reminders, and optional kick timing under afk. The kick is disabled by default. Use core.afk.auto.bypass and core.afk.kick.bypass for service accounts or staff who must remain connected.

Sudo

/sudo <player> <command...> executes a command as an online player. It does not provide a chat/message impersonation form. Three independent checks apply:

1. The actor needs core.sudo and, by default, active mod mode.
2. The command needs core.sudo.command.<root>. For example, /sudo Alex gamemode creative requires core.sudo.command.gamemode.
3. The command root must pass sudo.allowed-command-roots and sudo.blocked-command-roots. An empty allowlist delegates selection entirely to granular permissions; the blocklist always wins.

Namespaces cannot bypass policy: minecraft:op is also checked as op. /core, /skylines, /vcore, and /mcskylines are checked against their actual subcommand, so /skylines gamemode ... still requires .command.gamemode. Recursive sudo and changing mod mode through any of those aliases are always rejected. Protected targets require core.sudo.target.protected; self-targeting requires both configuration opt-in and core.sudo.self.

The target is notified before execution by default. Audit records contain the normalized command root and result, not arguments, avoiding accidental storage of passwords or other sensitive command data. The target's own command permissions still apply.

Utility commands and aliases

/skylines give <item> [player] [amount] gives to the command executor when the player is omitted. Console must specify an online player. A numeric second argument is treated as the self-give amount. Examples: /skylines give health:first_aid_kit, /skylines give narcotics:calming_herb 8, /skylines give robberies:breaching_charge, and /skylines give vehicles:part/engine Alex 2. Vanilla Minecraft materials are deliberately excluded. Unqualified names resolve only when unique; tab completion shows the authoritative namespaced keys.

The command requires skylines.give, with skylines.give.others, skylines.give.bypass-limit, and granular skylines.give.item.<namespace>.<item> nodes. Slashes in item keys become dots in permission nodes. core.give... compatibility nodes are also accepted. Operators receive all of them through core.admin. Core validates provider ownership, fresh one-unit results, serialized item size, amount limits, target state, permissions, and inventory capacity before mutating the inventory. Giving is audited; full inventories fail atomically by default.

Suite modules register factories, not cached item stacks. Their providers consult the module's live config for every creation, so reloading the module is sufficient. Core is deliberately not reloaded as a side effect, avoiding reload cycles and stale service references. Database-issued or owner-bound objects such as Economy cards and vehicle title vouchers are excluded from the generic registry.

• Game modes: /gamemode or /gm, with /gmc, /gms, /gma, and /gmsp shortcuts. Each shortcut accepts an optional player when the actor has core.gamemode.others.
• Teleport: /teleport, /tp, or /tele; /tphere, /tph, or /teleporthere.
• Back: /back returns to the location before the last successful Core teleport or to the last death location. A successful /back swaps the saved location, so the command can be used again to return. Locations and cooldowns are session-only and clear on logout/restart.
• Inventory: /clearinventory or /ci; /enderchest, /ec, or /echest; /invsee or /inventorysee.
• Workstations: /workbench, /wb, or /craft; /anvil.
• Diagnostics: /ping [player].

Inspecting another inventory or ender chest is read-only by default. Modification requires the separate .modify permission, and protected targets require the corresponding .protected permission. Opens and destructive inventory clears are written to Core's audit table.

Compatibility

• Carbon: Core does not register messaging, reply, channel, or chat-format commands. Mutes cancel Paper's final async chat event and only the command roots listed under mute.blocked-command-roots (default: /me). Mod mode uses Carbon's API solely to snapshot/enable/restore spy state; channel capability still comes from the transient LuckPerms group.
• WorldGuard / Property: staff teleport destinations check ENTRY; sign edits require WorldGuard owner/member status by default. WorldGuard bypass is honored. Property landlords and tenants work through their synchronized WorldGuard domains.
• LuckPerms: normal Bukkit permission checks work automatically. When installed, LuckPerms evaluates core.punishment.immune and the legacy core.bypass.target alias for offline players. security.protected-uuids provides an independent fallback.
• CoreProtect: Core does not write fake block interactions into CoreProtect. Moderation and administrative actions use their own audit table, while CoreProtect remains authoritative for block inspection and rollback.
• Other ban tools: Core mirrors active database bans to Paper's native profile ban list. Its SQLite record remains authoritative; use /unban so both stores are updated.
• Other spawn plugins: when spawn.use-for-respawn is enabled, Core applies its destination at HIGHEST so earlier general-purpose plugins cannot silently replace it. Disable this setting when another plugin should own death respawns. Set respawn-only-without-bed: true only when beds and respawn anchors should take precedence.

Every shortcut also has a namespaced form such as /core:fly. If another plugin claims /fly, use /core fly or the namespaced form, or disable the shortcut under commands.enabled.

Build and test

.\gradlew.bat clean test jar

The build requires Java 21. The output is build/libs/MCSkylines-Core-1.10.0.jar.

See the permissions table below for the full permission model and the operational security notes in the plugin repository for the security/operations model.

Production verification runbook

Use a non-owner moderator account and a protected staff test account so permission boundaries are exercised rather than bypassed by operator status.

1. Enter and leave /modmode. Confirm the transient group appears only while active, Carbon spy returns to its previous state, and game mode, flight, speeds, and god mode return to their pre-session values.
2. Test one offense ladder twice and confirm the second action advances to the next configured step. Open an old confirmation screen after another moderator advances the case and confirm the stale action is rejected.
3. Create a warning that crosses a configured threshold, then verify its cooldown prevents a duplicate automatic action. Remove the warning and confirm it disappears from the active ladder and history view without deleting the audit record.
4. Test a temporary mute in Carbon chat and through every command root in mute.blocked-command-roots. Confirm unrelated commands continue to work.
5. Vanish and reconnect with ordinary players and senior staff online. Check the fake join/quit audience, tab-list removal, and core.vanish.see behavior.
6. Exercise /sudo against an allowed root, a blocked root, a namespaced command, a protected target, and a target who lacks permission for the requested command.
7. Edit both sides of a sign as a property member, an outsider, and a region-bypass administrator. Include a waxed sign and an over-length line.
8. Test spawn on first join, ordinary join, death with and without a bed, and void rescue according to the selected policy.
9. Use representative self and other-player utility commands, then disconnect and confirm session-only /back, AFK, bypass, and vanish state clears as documented.
10. Run /skylines reload; deliberately test an invalid candidate configuration on staging and confirm the live policy remains unchanged.

Current boundaries

Core intentionally does not own economy, homes, warps, kits, private messaging, chat formatting, or block rollback. Carbon remains the chat owner, Economy owns money, and CoreProtect remains the block-history owner. Mod mode grants only the configured transient LuckPerms group; it is not a substitute for carefully scoped permissions.