HCFCore

The complete operator guide for HCFRevamped—from first boot to opening day. HCFCore brings factions, claims, events, farming, seasons, mastery, armor classes, staff tools, Lunar Client waypoints, and production safeguards together in one server platform.

Production safety: Stop the server before replacing HCFCore jars. Keep exactly one enabled HCFCore jar in plugins/, never edit files inside the jar, and never use /reload or PlugMan with HCFCore.

Install HCFCore

Requirements

• Java 21
• Leaf or Paper 1.21.11
• HCFCore-0.16.0-SNAPSHOT.jar

Recommended integrations

Installation order

1. Stop the server.
2. Place HCFCore-0.16.0-SNAPSHOT.jar in plugins/.
3. Remove or disable every older HCFCore jar.
4. Install the recommended dependencies.
5. Start the server once.
6. Confirm HCFCore ... enabled appears in logs/latest.log.
7. Stop the server cleanly.
8. Configure plugins/HCFCore/modules/.
9. Start the server again.
10. Run /hcf status and /hcf integrations.

Directory layout

plugins/HCFCore/
├── modules/                 Editable module configuration
│   ├── claims.yml
│   ├── classes.yml
│   ├── combat.yml
│   ├── cooldowns.yml
│   ├── deathban.yml
│   ├── dtr.yml
│   ├── economy.yml
│   ├── events.yml
│   ├── factions.yml
│   ├── farming.yml
│   ├── integrations.yml
│   ├── leaderboards.yml
│   ├── lunar.yml
│   ├── mastery.yml
│   ├── messages.yml
│   ├── mob-drops.yml
│   ├── protection.yml
│   ├── schematics.yml
│   ├── season.yml
│   ├── spawn.yml
│   ├── staff.yml
│   ├── storage.yml
│   └── visuals.yml
├── data/                    Runtime state; do not edit while running
│   ├── events.yml
│   ├── factions.yml
│   ├── farming.yml
│   ├── leaderboards.yml
│   ├── lunar-waypoints.yml
│   ├── mastery-progress.yml
│   ├── season.yml
│   ├── spawn.yml
│   └── staff.yml
└── schematics/              Supported .schem and .schematic files

Module files contain settings. Data files contain player and server state. Keep YAML indentation as spaces, never tabs, and back up plugins/HCFCore/data/ before a reset or major update.

First-time setup

• Install Java 21, Leaf/Paper 1.21.11, PlaceholderAPI, Vault, an economy, and LuckPerms.
• Start once and confirm HCFCore loads without exceptions.
• Run /hcf integrations.
• Stand at the intended Spawn and run /setspawn.
• Configure the Lunar Spawn waypoint with /hcfwp setspawn.
• Review factions.yml, claims.yml, dtr.yml, and combat.yml.
• Review deathban.yml, protection.yml, and cooldowns.yml.
• Configure farming prices, contracts, Mastery rewards, and class armor.
• Create KOTH, Outpost, and supply-drop regions.
• Test Vault deposits with a non-admin account.
• Configure TAB and scoreboard placeholders.
• Assign LuckPerms permissions.
• Test SOTW PvP protection.
• Back up the complete server.
• Run a private multiplayer test before launch.

Spawn and safe teleports

/setspawn
/spawn
/spawn cancel

The default /spawn countdown is five minutes from wilderness and two minutes from the player's own claim. It is denied in enemy claims; use /f stuck for a five-minute escape countdown.

Movement, damage, combat tagging, logout, a changed claim relation, or an unsafe destination cancels the teleport. /f stuck searches for unclaimed, border-safe terrain with solid ground and enough room for the player. Configure these rules in modules/spawn.yml.

Factions

Player commands

/f create <name>             /f invite <player>
/f uninvite <player>         /f join <faction>
/f leave                     /f show [faction]
/f claim [radius]            /f unclaim
/f sethome                   /f home
/f stuck                     /f map
/f deposit <amount>          /f withdraw <amount>
/f chat [message]            /fc

Leadership commands

/f promote <player>          /f demote <player>
/f kick <player>             /f transfer <player>
/f disband

The main faction settings live in:

• factions.yml — names, limits, roles, invitations, home delay, and faction bank.
• claims.yml — claim size, Spawn distance, and outsider protection.
• dtr.yml — maximum DTR, death loss, regeneration, and raidable windows.

Faction money uses Vault. Deposits and withdrawals validate values, limits, permissions, balances, persistence, and rollback behavior.

World events

HCFCore supports KOTH, Outpost, and Supply Drop events.

Create a region

/event pos1
/event pos2
/event create <id> <koth|outpost|supply-drop> <display name>

Examples:

/event create citadel koth Citadel
/event create north-road outpost North Road
/event create plains-drop supply-drop Plains Supply Drop

Manage events

/event
/event status
/event start <id>
/event stop
/event delete <id>

Only living, non-spectator players inside the cuboid count. Members of one faction count as one team, while factionless players count individually. Only one team progresses at a time, and contested reset behavior is configurable.

Rewards are persisted before console commands run. Active event Lunar waypoints are added and removed automatically. Configure duration, capture time, rotation, rewards, and supply loot in modules/events.yml.

Automatic events are disabled by default. Build and test every arena first, then enable rotation.

automatic:
  enabled: true
  startup-delay: 15m
  interval: 2h
  rotation: [citadel, north-road, plains-drop]

Farming and crop market

/farming
/farm
/farming sell
/farming tool <player> [level]

The farming menu shows level, experience, mature crops harvested, lifetime earnings, dynamic prices, and sell-all confirmation. Only mature Ageable crops grant progress. Harvester tools use PersistentDataContainer tags, so renamed vanilla hoes cannot imitate them.

Dynamic prices start at the configured base price, decline as daily supply rises, never fall below the minimum multiplier, and reset at midnight UTC.

Sales are protected by a persisted transaction record, main-thread item changes, duplicate-sale prevention, rollback after rejected payouts, and a configurable maximum transaction value. Configure levels, tools, prices, crops, and contracts in modules/farming.yml.

Seasons, SOTW, and EOTW

Season phases progress through PRESEASON, SOTW, ACTIVE, EOTW, and ENDED.

/season
/season status
/season sotw
/season active
/season eotw
/season end
/season set <phase> [duration]

Examples:

/season set sotw 2h
/season set active
/season set eotw 90m

SOTW can disable player-versus-player damage. Phases and deadlines are saved atomically, so restarts do not reset active timers. Timed SOTW advances to ACTIVE; timed EOTW advances to ENDED. Configure modules/season.yml.

Mastery

/mastery
/mastery reload
/mastery reset <player>
/mastery setprogress <player> <mastery> <task> <amount>
/mastery complete <player> [mastery]

Bundled tracks include Warrior, Monster Hunter, Farmer, Miner, Artisan, Angler, and Trailblazer. Each track can contain multiple tasks and a reward; completing every enabled track grants the one-time final reward.

Supported task types:

PLAYER_KILL     MOB_KILL       BREAK_BLOCK     HARVEST_CROP
PLACE_BLOCK     CRAFT_ITEM     FISH_ITEM       CONSUME_ITEM
ENCHANT_ITEM    PLAY_MINUTES   WALK_BLOCKS

WALK_BLOCKS ignores flying, gliding, vehicles, and teleport-like movement. Player-placed block tracking helps prevent place-and-break farming. Configure modules/mastery.yml; change season-id to start fresh progression without deleting old data.

Armor classes

/class
/class status
/class pack
/class kit <player> <class>
/class reload

All four tagged pieces must match the same class and equipment slot. Renamed vanilla armor cannot activate a class. Custom models are optional; enable their keys only after the matching resource pack is hosted at a direct HTTPS URL with the correct SHA-1. Configure modules/classes.yml and modules/visuals.yml.

Lunar Client

HCFRevamped recommends Lunar Client, but standard Minecraft clients can join.

/hcfwp list
/hcfwp setspawn
/hcfwp set <id> <koth|outpost|event> <display name>
/hcfwp remove <id>
/hcfwp refresh

Spawn, KOTH, Outpost, and event waypoints are delivered through Lunar Apollo plugin messages. Active HCFCore events manage their own temporary waypoint. Configure colors, beams, outlines, Spawn, and join messaging in modules/lunar.yml.

Schematics

Place supported files in plugins/HCFCore/schematics/.

/sc list
/sc load <filename>
/sc paste <x> <y> <z>
/sc status
/sc cancel

The command parser supports coordinates such as x0, y0, and z0 where applicable. Files are validated away from the main server thread and pasted at a rate limited across ticks.

Legacy .schematic conversion is supported. Unsafe NBT lengths are rejected before allocation. Configure file size, block, palette, dimension, concurrency, and per-tick limits in modules/schematics.yml.

Always test important builds on a copy of the world first.

Leaderboards and staff tools

Leaderboards

/leaderboards
/top
/stats

Seasonal kills, deaths, KDR, playtime, and kill rank are stored in data/leaderboards.yml using periodic atomic saves. Configure menu limits in modules/leaderboards.yml.

Staff

/staff
/vanish
/freeze <player>
/staffchat <message>
/inspect <player>

Staff mode saves the previous game mode, enables creative and vanish, then restores the previous mode when disabled. Freeze state survives restarts, and disconnecting while frozen writes a staff alert to the console. /inspect is read-only to prevent accidental item edits and duplication.

Settings and permissions

/settings exposes every leaf setting from every loaded module:

• Left-click a Boolean to toggle it.
• Left-click another value to replace it in chat.
• Right-click to restore the bundled default.
• Type cancel to abort a chat edit.
• Restart-sensitive values require confirmation.

Changes are validated before saving. Invalid edits are rejected and rolled back, while passwords remain hidden in menu output and audit logs. Stop the server and edit the file directly for large or structural YAML changes.

Permission nodes

Example LuckPerms setup:

/lp group admin permission set hcf.admin true
/lp group admin permission set hcf.settings.admin true
/lp group mod permission set hcf.staff.use true
/lp group mod permission set hcf.staff.chat true
/lp group mod permission set hcf.staff.see-vanished true

Grant each role only the permissions it requires.

PlaceholderAPI

Faction

%hcfcore_faction_name%          %hcfcore_faction_role%
%hcfcore_faction_dtr%           %hcfcore_faction_max_dtr%
%hcfcore_faction_raidable%      %hcfcore_faction_raid_time%
%hcfcore_faction_members%       %hcfcore_faction_online%
%hcfcore_faction_claims%        %hcfcore_faction_bank%

Player and class

%hcfcore_lives%                 %hcfcore_deathbanned%
%hcfcore_deathban_time%         %hcfcore_protected%
%hcfcore_protection_time%       %hcfcore_combat_tagged%
%hcfcore_combat_time%           %hcfcore_lunar_client%
%hcfcore_class_active%          %hcfcore_class_name%
%hcfcore_bard_energy%

Mastery

%hcfcore_mastery_completed%     %hcfcore_mastery_total%
%hcfcore_mastery_percent%       %hcfcore_mastery_final_completed%
%hcfcore_mastery_<id>_percent%
%hcfcore_mastery_<id>_completed%

Events, farming, and seasons

%hcfcore_event_active%          %hcfcore_event_name%
%hcfcore_event_type%            %hcfcore_event_capture_time%
%hcfcore_farming_level%         %hcfcore_farming_experience%
%hcfcore_farming_harvested%     %hcfcore_farming_earned%
%hcfcore_season_phase%          %hcfcore_season_time%
%hcfcore_sotw_protected%        %hcfcore_kills%
%hcfcore_deaths%                %hcfcore_kdr%
%hcfcore_playtime_minutes%      %hcfcore_kills_rank%

Server health

%hcfcore_storage_type%          %hcfcore_storage_healthy%
%hcfcore_storage_queue%         %hcfcore_waypoint_count%
%hcfcore_koth_waypoints%        %hcfcore_outpost_waypoints%
%hcfcore_event_waypoints%

Database and safe updates

SQLite is the simplest choice for one server. MySQL is preferable when external tools need access or when preparing network infrastructure.

Configure modules/storage.yml while the server is stopped. For MySQL, create a dedicated database and user, grant only required permissions, prefer a private network address, use a strong password, and never publish storage.yml. Start the server, run /hcf status, then inspect the storage health and queue placeholders. Storage changes require a complete restart.

Update procedure

1. Announce maintenance and stop the server cleanly.
2. Back up plugins/HCFCore/, worlds, economy data, permission data, and the database.
3. Place the new jar in plugins/.
4. Move the old jar outside plugins/ or rename it to .jar.disabled.
5. Confirm exactly one enabled HCFCore jar remains.
6. Start the server and inspect logs/latest.log.
7. Run /hcf status and /hcf integrations.
8. Test Spawn, factions, farming sales, events, classes, and staff tools.

Never downgrade newer data without restoring its matching backup.

Public launch checklist

Test with at least three non-operator accounts:

• Create, invite, join, leave, promote, and disband factions.
• Claim and unclaim land; verify outsider block and container protection.
• Trigger DTR loss and regeneration.
• Test faction-bank deposit and withdrawal failure paths.
• Start /spawn from wilderness, friendly land, and enemy land.
• Test /f stuck from a real enemy claim.
• Move, take damage, enter combat, and disconnect during teleports.
• Capture and contest a KOTH with different factions.
• Open a supply drop; complete and restart during an event.
• Harvest every configured crop.
• Sell crops and verify exact money and item changes.
• Double-click the selling UI and disconnect during normal farming.
• Complete a daily contract only once.
• Activate every armor class; test Rogue backstab and Guardian reduction.
• Verify SOTW blocks PvP and survives a restart with its deadline intact.
• Verify leaderboards after kills and playtime.
• Freeze, disconnect, reconnect, inspect, and unfreeze a player.
• Verify vanished staff are hidden from normal players.
• Load and paste representative schematics.
• Confirm TAB and scoreboard placeholders never show raw percent signs.
• Review the console for warnings, exceptions, and failed saves.

Troubleshooting

HCFCore does not load

• Confirm Java 21 and Leaf/Paper 1.21.11.
• Confirm exactly one enabled HCFCore jar exists.
• Read the first HCFCore exception in logs/latest.log.
• Check YAML indentation and values.

Vault economy is unavailable

• Install Vault and a compatible economy provider.
• Restart completely.
• Run /hcf integrations.

Raw placeholders appear

• Install PlaceholderAPI and keep it enabled in integrations.yml.
• Restart and confirm HCFCore registered the hcfcore expansion.

Spawn or Lunar waypoint is missing

• For Spawn, stand at the destination and run /setspawn with hcf.spawn.admin.
• For Lunar, join with Lunar Client, confirm lunar.yml is enabled, run /hcfwp refresh, and verify the waypoint world exists.

Event creation fails

• Set both corners in the same world.
• Use a unique, lowercase, safe ID.

Farming sale fails

• Confirm Vault and the economy provider are loaded.
• Confirm the inventory contains configured sell materials.
• Check maximum-transaction.
• Inspect logs and data/farming.yml for a pending transaction before changing data.

Schematic loading fails

• Confirm the file is inside plugins/HCFCore/schematics/.
• Check allowed extensions and configured limits.
• Verify the source is not truncated or malformed.
• Convert unsupported legacy blocks or adjust the legacy policy.

Never delete data files as a first troubleshooting step. Back them up and inspect the log first.

Opening-day order

1. Start in PRESEASON while staff verifies the map.
2. Confirm Spawn, claims, KOTH regions, Outposts, and waypoints.
3. Run /season sotw.
4. Allow players to create factions and claim.
5. Verify SOTW PvP protection with test accounts.
6. Let SOTW transition automatically to ACTIVE.
7. Start the first event manually.
8. Watch storage health, transaction logs, TPS, and player reports.
9. Enable automatic event rotation only after every arena is proven.
10. Take an opening-day backup.

Quick command reference

Keep this guide updated whenever commands, permissions, module names, or production procedures change.