HCFCore

https://whosvon.github.io/EmberWiki/wiki/hcf-core/
This is fully in testing and not 100% working my discord is "user142124124" Let me know what needs fixed/changed

Install HCFCore
Requirements

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

Recommended integrations
Integration Purpose
PlaceholderAPI Scoreboard, TAB, hologram, and chat placeholders
Vault Economy bridge
Vault-compatible economy Player and faction balances
LuckPerms Permissions and staff ranks
WorldGuard Optional region integration
Lunar Client Optional automatic Spawn, KOTH, Outpost, and event waypoints
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

Class Role
Miner Mining effects, sneak invisibility, valuable-ore sensing
Archer Speed, empowered arrows, and marked targets
Bard Faction support effects powered by energy
Rogue Mobility, sneak invisibility, and positional backstab
Guardian Frontline damage reduction
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
Permission Access
hcf.admin Main HCFCore administration
hcf.lives.others View another player's lives
hcf.deathban.bypass Bypass deathbans
hcf.combattag.bypass Bypass combat tagging
hcf.claims.bypass Bypass claim protection
hcf.schematic.admin Manage schematics
hcf.waypoint.admin Manage Lunar waypoints
hcf.settings.admin Use /settings
hcf.mastery.admin Administer Mastery
hcf.class.admin Give and reload classes
hcf.spawn.admin Use /setspawn
hcf.events.admin Create and control events
hcf.farming.admin Create farming tools
hcf.season.admin Change season phases
hcf.season.pvp-bypass Damage players during SOTW
hcf.staff.use Use staff commands
hcf.staff.chat View and send staff chat
hcf.staff.see-vanished See vanished staff
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.