CombatJobs Documentation

Overview

The three ideas the rest follows from

• One job at a time. A player runs a single job until they craft the Oathstone, which unlocks a second job in the opposite category — a combat player gains a passive job, a passive player gains a combat one. The Oathstone is also the switching device, and switching is deliberately gated: 20 blocks of clear space, 20 seconds without taking damage, and a cooldown.
• Every job has a weakness that another job answers. Weaknesses are shown to a player before they commit. A Warrior burns through armour; a Blacksmith repairs it. That demand is what makes the economy work, and why a server can be deliberately combat-weighted — a few passive players supply a large fighting population through owned Workstations.
• Combat is never penalised for being popular. Balance is done by raising scarce rewards, never by lowering plentiful ones. If passive players are rare, their Workstation payouts and quest rewards go up; combat rewards never go down.

What is data and what is code

Jobs, skill trees, titles and abilities are YAML. Adding a job is a file. An ability names one of 25 primitives and gives it parameters, so a new ability is data too. The default roster ships 275 abilities (133 active, 142 passive). See Writing jobs in YAML.

Getting Started

Requirements

Install

1. Drop the jar in plugins/ and start the server.
2. Read the start-up banner. It prints what the plugin actually found:

   Storage ............. SQLite (combatjobs.db)
   Jobs ................ 21 (13 combat, 7 passive, 1 either), 506 titles
   Abilities ........... 275 abilities (133 active, 142 passive) from 25 primitives
   Permissions ......... LuckPerms 5.5.77 (contexts + meta)
   Economy ............. internal economy (online players only)
   Anti-cheat .......... none
   Land claims ......... none (world list unrestricted)
   Network ............. none (single server)

   Start every support conversation with this block. It is the difference between what a server has and what its owner believes it has.
3. Stop the server, edit plugins/CombatJobs/config.yml, start it again.

A bad value in config.yml is rejected as a whole file, with every problem named, and the previous settings keep running. A typo never half-applies.

Verify it

/cj capabilities     what integrations resolved
/cj debug cache      profiles in memory
/cj leaderboard      which boards this server has, and how full
/cj diagnose         writes a full support report to plugins/CombatJobs/diagnostics/

/cj diagnose contains no passwords or tokens — only whether each is set — so it is safe to attach to a support thread.

Five Settings to Decide

1. Storage

SQLite needs nothing and is right for one server. For a network, point every server at one MySQL/MariaDB:

storage:
  type: MYSQL
  host: 10.0.0.5
  database: combatjobs
  username: combatjobs
  password: '…'
  use-ssl: false      # true means full certificate verification

use-ssl: false disables TLS entirely and is only safe on the same host or private network. true means sslMode=verify-full, which refuses a self-signed certificate.

2. Economy

With Vault and an economy behind it, the plugin uses that. Without, it uses an internal economy — which works, but only knows about online players, so an offline player cannot be paid by a Workstation until they log in. That is why Vault is worth having.

3. Anti-cheat exemptions

Dashes, leaps and speed buffs look exactly like the cheats a movement check exists to catch. Exemption is done by bypass permission, granted for the length of the exemption window. Set this before you open to players — see Compatibility.

4. Arenas — define one before switching them on

arenas.enabled ships false, and the loader refuses true with no arena defined. Stand where one side should arrive and run /cj arena define <id>; walk to the other side and run it again. The second run prints the block, ready to paste under arenas.arenas:

    colosseum:
      display-name: 'Colosseum'
      world: world
      enabled: true
      spawns:
        - { x: 100.5, y: 65.0, z: 100.5, yaw: 0, pitch: 0 }
        - { x: 130.5, y: 65.0, z: 100.5, yaw: 180, pitch: 0 }

Then set arenas.enabled: true and /cj reload. One spawn per side, not per player — two spawns is all a 3v3 needs. It prints rather than saves on purpose: rewriting config.yml from code would strip every comment in it.

5. Which optional systems you want

Workstations, trading, the tavern, quests, bounties, clans, arenas, tournaments, the pass, prestige, leaderboards and decay each have an enabled switch. Turning one off removes it cleanly — its commands say so, its leaderboards stop existing, and anything that checked it stops checking.

The Job Roster

Every combat job declares an archetype, which arena matchmaking uses to balance teams by role as well as rating.

Combat jobs

Passive jobs

Either slot

Alchemist (Caster) — debuffs and area denial in a fight; potions and reagents in a town.

Optional job pack

Six extra passive jobs — baker, diplomat, fisherman, guide, lumberjack, tailor — ship inside the jar under jobs-optional/ rather than switched on. Copy the ones you want into plugins/CombatJobs/jobs/ and restart.

Progression

Skill trees and levels

• Each job has its own trees, and each tree levels 0–500 independently.
• The average of a job's trees drives the title tier and the Oathstone level gate — the same number shown on /skills and on the leaderboard.
• Nodes unlock an ability at a breakpoint; scaling applies at every single level, so the gaps between breakpoints still count.
• XP cost starts at progression.xp.base (100) and grows by growth (1.012) per level.

Abilities

Passive abilities apply while their tree level is held. Active abilities are bound to a hotbar slot in /abilities and cast with sneak + right-click.

Titles

Each job has a tiered title ladder; titles are globally unique across jobs. /title reroll rerolls within your tier for a fee (free with combatjobs.reroll.free).

The Oathstone and switching

The Oathstone unlocks your second job (in the opposite category) at job level 100 and is the item you switch with. The default recipe:

E S E      E = Echo Shard         (Ancient City)
N H N      S = Nether Star        (the Wither)
E T E      N = Netherite Ingot
           H = Heart of the Sea   (buried treasure)
           T = Totem of Undying   (Woodland Mansion)

Right-click it to switch. Every condition must hold at once, and a failed check says which one and how long is left:

The job you are not running still earns 25% of its normal XP and decays at 50% of the normal rate (inactive-job.*). Lost your Oathstone? /oathstone re-issues it.

Decay

Skills decay when a player is idle — but with guard rails so it is never punishing: nothing decays for the first 72 hours idle, then 1 level per hour, never below level 100, and never below the floor of the title tier you hold (decay.*).

Hero

Taking a job to the mastery cap — level 500 in all of its trees, not on average — gives a small chance (0.5% by default) to be crowned Hero. Heroes get an exclusive Ascendance tree that levels from a share of the XP they already earn, and carry an economic tax that applies at all times. hero.roll-trigger can roll on MASTERY, on PRESTIGE, or BOTH.

Prestige

/prestige previews, then /prestige confirm resets a mastered job for a permanent perk. Prestiging takes you off that job's level board, because its trees go back to zero; the prestige board ranks you instead.

Workstations & Economy

Everything a player can pay — a repair, a meal, a trade, an enchant — is priced through that player's own attributes, so a job's economic weakness is real rather than documented.

Workstations

Passive players place and own Workstations, set a fee with /workstation fee <percent> (default 15%, maximum 40%), and earn while combat players use them — including while the owner is offline, capped at 24 hours of output. Up to 3 per player, from job level 50, at least 16 blocks apart.

Population and scarcity

population.combat-target and passive-target set the split the server aims for. When passive players are below target, Workstation payouts, quest rewards and the tavern markup rise. One-directionally: nothing ever falls below its configured value when combat players are plentiful. Put %combatjobs_scarcity_<job>% somewhere players can see it — it tells them which job is underserved and paying more.

Trading, the tavern and quests

• /trade <player> runs an escrowed trade of items and currency, with a configurable tax and a list of things that may not be traded.
• The tavern innkeeper sells bonus food with rarity tiers and spoilage.
• /quests opens the quest board, served by guild workers in the world.

Clans, Arenas & the Pass

• Bounties — /bounty place <player> <amount> puts a price on a head; /bounty withdraw takes your own stake back. Heroes carry a standing bounty.
• Clans — ranks, a shared vault, renown, and wars declared with a stake (/clan war declare <clan> <stake>). Area abilities spare your own clan.
• Ranked arenas — 1v1, 2v2 and 3v3 brackets with Elo ratings, matchmaking balanced by rating and archetype. /arena top is the ladder.
• Tournaments — scheduled, with an entry fee and a prize table; rounds are arena matches.
• Season pass — 50 tiers with free and premium tracks and a daily XP cap. Pass XP comes from skill levels, Workstation use, bounties, arena matches and wins, tournaments and prestige. Premium is held through combatjobs.pass.premium or a stored purchase.
• Seasons — incrementing season.number starts a new season for the pass, arena ratings and per-season boards at once. Nothing is deleted.
• Leaderboards — 28 boards on the default roster, refreshed every 5 minutes. /top prints each board's age.

Writing Jobs in YAML

There are three layers, and each one names the layer under it:

jobs/warrior.yml      a tree node names an ABILITY   ->  cj:shield_wall
abilities.yml         an ability names a PRIMITIVE   ->  shield, radius 4, 6s
(code)                25 primitives                      the only part in Java

A job file

plugins/CombatJobs/jobs/<id>.yml — the file name is the job id.

display-name: 'Warrior'
slot: COMBAT                # COMBAT | PASSIVE | EITHER
rarity: common
archetype: BULWARK          # combat jobs only

identity: 'Frontline anchor. Holds a line, absorbs punishment and controls the fight.'

# Shown to the player BEFORE they commit to this job.
combat-weakness: 'Slow on foot, poor against anything that kites, and a low critical rate.'
economic-weakness: '1.5x armour and weapon durability loss.'
creates-demand-for: [ 'blacksmith', 'miner' ]

strengths:
  damage_taken:   { op: MULTIPLY, value: 0.88, range: [0.85, 0.95] }
  max_health:     { op: ADD,      value: 4.0,  range: [2.0, 8.0] }

weaknesses:
  movement_speed: { op: MULTIPLY, value: 0.92, range: [0.88, 0.96] }
  durability_loss_multiplier: { op: MULTIPLY, value: 1.5, range: [1.3, 1.7] }

trees:
  tank:
    display-name: 'Tank'
    description: 'Soak damage and hold ground.'
    scaling:
      damage_taken: { op: MULTIPLY, per-level: -0.0004, cap: 0.2 }
    nodes:
      - { level: 1,   ability: 'cj:damage_reduction' }
      - { level: 20,  ability: 'cj:knockback_resist' }
      - { level: 440, ability: 'cj:last_stand' }

titles:
  - { tier: 1, min-level: 0,   names: [ 'Recruit', 'Footman' ] }
  - { tier: 2, min-level: 50,  names: [ 'Sergeant', 'Shieldbearer' ] }

Rules the loader enforces

• Every job needs a declared weakness. A job with no weakness generates no demand for another job.
• Title strings are globally unique. The plugin refuses to start on a collision.
• A combat job should declare an archetype — one of seven. An unrecognised one is refused; a missing one is a warning.
• An ability key that does not exist unlocks nothing and is named in the log at start-up.

range is the band a value may move within when it is rolled per player, which is what makes two Warriors slightly different. Strengths and weaknesses feed the same resolver, so a strength and an equal weakness cancel out exactly.

An ability

abilities:
  'cj:shield_wall':
    name: 'Shield Wall'
    description: 'Raise a barrier that absorbs the next few hits.'
    primitive: shield
    cooldown: 45
    params:
      amount: 8.0
      duration: 6

Whether an ability is passive or active is decided by its primitive. An ability that moves a player declares its anti-cheat exemption reason on the primitive, so a dash added as YAML is exempted without anyone remembering to do it. After editing, run /cj reload: a bad roster is refused with every problem named, and the previous roster keeps serving players.

Commands

Player commands

Every player command defaults to everyone, through combatjobs.command.<name>.

Admin commands

All under /cj (alias /combatjobs).

Permissions

Placeholders

Through PlaceholderAPI as %combatjobs_<key>% and through MiniPlaceholders as <combatjobs_<key>>. Every value is read from memory — nothing here touches the database.

Board ids come from /top: a job board is level_<job>; the rest are level, mastery, prestige, pass, balance, clan_renown, clan_wins. n is bounded by leaderboards.size. Values are inserted unparsed, so apply your own colours around them.

Configuration

config.yml is the reference — every setting carries a comment saying what it does and why the default is the default. messages.yml holds every line the plugin says, in MiniMessage.

How a reload works

/cj reload re-reads config.yml and messages.yml. An invalid file is rejected as a whole and the previous settings keep running. storage.*, network.transport, network.redis.* and license.key need a restart. A reload also calls off running arena matches (unrated), cancels and refunds a running tournament, re-places innkeepers and guild workers, and rebuilds leaderboards.

The sections

Settings whose consequences are not local

• storage.write-behind-seconds (30) — a ceiling on what a hard crash can lose, and on a network the latency of clan and bounty sync.
• progression.mastery-level — what "mastered" means for Hero, prestige and the mastery board at once.
• combat.damage-listener-priority (NORMAL) — where this plugin's damage scaling sits relative to mcMMO, Jobs Reborn or custom-enchant plugins.
• leaderboards.refresh-minutes (5) — lower is not better: each refresh is one query per board against the shared database.

Networks

Point every server at the same MySQL/MariaDB database first. That alone gives one profile per player wherever they log in, and leaderboards that are network-wide by construction. The bridge adds what memory-held state needs:

The bridge carries notices; the database carries state. A message says "clan 3f2a changed" and the server that hears it re-reads clan 3f2a — so a message applied twice, out of order or lost can never cost anybody a coin.

Transports

network:
  enabled: true
  server-id: lobby-1        # MUST differ on every server
  transport: REDIS          # REDIS | PROXY | NONE
  channel: combatjobs
  redis:
    host: 10.0.0.6
    port: 6379
    password: '…'

• REDIS (recommended) works with nobody online and between servers not behind the same proxy. Tested against a real Redis 8.10.1.
• PROXY uses BungeeCord's / Velocity's Forward subchannel, with one limitation: a server with nobody online cannot send. Those messages are dropped and counted in /cj network.
• NONE (default) is correct for one server.

server-id must be unique. Two servers sharing an id each ignore everything the other says, while the bridge reports itself healthy. Tune handoff-timeout-ms (750, bounded 50–5000) and heartbeat-seconds (30) for your latency.

Compatibility

Run means exercised on a running server; Compiled means compiled against the real jar but not yet run with it installed.

Anti-cheat

integrations:
  anticheat:
    exempt-on-ability: true
    linger-millis: 1500
    bypass-permissions:
      - 'grim.exempt'          # GrimAC
      - 'vulcan.bypass'        # Vulcan
      - 'spartan.bypass'       # Spartan
      - 'matrix.bypass'        # Matrix
      - 'nocheatplus.checks'   # NoCheatPlus
    # Optional: narrower nodes per reason (velocity | teleport | movement | fall | combat)
    bypass-permissions-by-reason:
      teleport: [ 'nocheatplus.checks.moving.morepackets' ]

None of these anti-cheats had a Minecraft 26.2 build when this was tested, so check the node against your anti-cheat's own documentation for the version you run.

Known overlaps

• Other job and damage plugins (Jobs Reborn, mcMMO, custom enchants) all scale the same hit; the result is their multipliers times ours. combat.damage-listener-priority decides the order.
• Combat tagging plugins have their own idea of "in combat"; this plugin's damage-free switch timer is independent of theirs.
• Chat and tab plugins — switch the matching display option off and use the placeholders instead.

Licensing

The released jar checks a licence key, put in plugins/CombatJobs/license.key as a single line (preferred) or in config.yml under license.key. The check is entirely offline: the key is a signed statement verified locally, with no phone-home, heartbeat or telemetry.

Nothing is ever deleted. A refusal leaves the database exactly as it was; fix the key and restart. Builds handed out from the bench may not check a key at all — ask when you request one.

Troubleshooting

Start with /cj diagnose.

Q: The plugin will not start

A: Read the console — config.yml has N problem(s) lists them all; Jobs could not be loaded means a malformed job file or two jobs sharing a title; Storage could not be opened names the database problem; arenas.enabled is true with no arena defined means define one or set it back to false.

Q: Nothing happens when I use an ability

A: Actives need a hotbar slot (/abilities) and are cast with sneak + right-click. Check it is unlocked on /skills, and look for undefined: ability keys in the start-up log.

Q: Players are kicked for flying

A: Set integrations.anticheat.bypass-permissions before opening to players.

Q: The leaderboard does not show me and I just levelled

A: Boards are snapshots refreshed on a timer; /top prints the age. /cj leaderboard refresh re-reads them now.

Q: Workstations are not earning while I am offline

A: You are on the internal economy, which only knows online players. Install Vault with any economy behind it.

Q: Two servers disagree about a clan, a bounty or the ladder

A: Run /cj network on both. Connected: no names the transport problem; Peers: 0 usually means a different channel; everything green but still disagreeing means two servers share a server-id.

Q: A player lost progress when they changed servers

A: Without the bridge that is expected. With it, watch Handoffs … timed out in /cj network and raise handoff-timeout-ms if servers are far apart.

Q: Need a build?

A: CombatJobs is not released. Ask for it in the Discord server.