Repository navigation
commander_system_wiki
Misty void edited this page Oct 18, 2026
·
1 revision
Applicable Version: Minecraft Java 1.20.1 + Forge 47 (Mod ID:
commander_vote_sta). This document covers all features of the mod: voting for commander, skill wheel, six tactical skills, aiming preview, levels and skill points, every config parameter, all commands, and FAQ. Usage only, no code involved. All "default values" refer to the factory values in the config file, all of which can be changed.
- What Is This Mod
- Installation & Getting Started
- Commander Identity: Voting + Admin Appointment
- Skill Wheel (Keybind, Interface, Controls)
- Aiming Mode & Preview
- Six Skills Explained in Detail
- Artillery Designator (Toolkit Mode Item)
- Levels, Skill Points, Cooldowns, Spam Penalty
- Config File Complete Manual
- Command Reference Table
- Death Messages & Damage Type
- List of Added Entities/Items
- Performance Notes for Server Admins
- FAQ - Frequently Asked Questions
Adds a "Commander" gameplay system to your server:
- Players elect their own commander via intra-team voting (admins can also directly appoint).
- The commander presses the V key to open the skill wheel, allowing them to use 6 tactical skills: Recon Scan, Airdrop Supplies, Tactical Smoke Wall, Artillery Support, All-Out Assault, Strategic Retreat.
- Each skill has level requirements and skill point costs. Levels and points are stored in scoreboards, making it easy to integrate with minigame plugins.
- All numbers, texts, sounds, particles, and loot are defined in a single JSON configuration file. Every field comes with comments. Changes take effect in-game via hot-reload - no server restart needed.
The team system required is simply vanilla /team commands (e.g., red/blue teams). The mod does not create its own team system.
- Place the mod JAR into the
mods/folder on both the server and client (requires Forge 47.x for 1.20.1). (The wheel interface, aiming preview, designator item, beam/supply crate rendering are client-side features, so clients must have the mod too.) - Start the server. On first launch, the config file will be auto-generated at:
config/commander_system.json - An admin can use
/commander grant <player>to appoint an initial commander, or let players start a vote (see next chapter). - The commander presses V to open the wheel and begin using skills.
Join a team (admin adds you: /team join red <playername>)
then /commander vote start to initiate a campaign to become your team's commander
teammates run /commander vote yes or no
when time runs out, if yes > no, you are elected
press V to open the skill wheel and use skills
- Who can initiate: Any player, no special permission required (no OP needed).
- What they run for: To become the commander of their own team.
- Prerequisite: The initiator must belong to a scoreboard team (e.g., red/blue), and their team must not already have a commander.
- Who sees the announcement: Broadcast only goes to online teammates; other teams know nothing about it.
- Who can vote: Only members of the initiating team. Players from other teams will receive "There is no active vote for your team."
- Can the nominee vote themselves: No, the nominated player cannot vote for themselves.
- How many votes per person: One vote, but can be changed (casting yes/no again overwrites the previous vote).
- Concurrent votes allowed: Only one vote across the entire server at a time; while red is voting, blue cannot start one.
-
Duration: Default 60 seconds (
vote.durationSeconds), automatically tallied when time expires. - Early tally: If all eligible members of the team have voted, the result is calculated immediately.
- Election condition: Yes > No (ties or fewer yes counts as failure), and the system must be enabled.
-
Result broadcast: A server-wide broadcast announces the winner, prefixed by team name, e.g.:
[Red Team] Xiao Ming is now the commander of this team.
How team names are displayed: First checks if a custom display name was set. If set, that name is used; otherwise the raw team ID (red/blue) is shown, along with the team's color.
Each team can have only 1 commander at any time. This restriction applies to all entry methods:
- Before starting a vote: checks if the team already has a commander - if yes, vote initiation is blocked.
- If an admin uses
/commander grantto appoint someone else during an ongoing vote - when the vote ends, even if votes pass, the broadcast says "Team already has a commander, no duplicate appointment." - If
/commander granttargets a player whose team already has a commander - the command is skipped with a message. - This check includes offline players: the save file records each commander's name, verified via the scoreboard team member list. Even if the commander is offline, they still occupy the slot.
| Command | Effect |
|---|---|
/commander grant <player> |
Directly appoint a commander (skips if the team already has one) |
/commander cancel |
Revoke all commanders and cancel any ongoing vote |
/commander enable / disable
|
Master switch for the entire system |
/commander levellimit on/off |
Temporarily toggle level restrictions |
Commander identities persist with the world save - they survive server restarts.
- Default key: V (can be changed in Options - Key Bindings - Commander System - Open Skill Wheel).
- Only the commander can open it. Non-commanders pressing V will see nothing and receive a chat message: "Only the commander can use skills and open the skill wheel." (Identity is checked server-side.)
- Alternatively, skills can be executed directly via command:
/commander skill scan|airdrop|smoke|artillery|assault|retreat. - If the commander's identity is revoked while the wheel is open, the wheel will close automatically on the next second's refresh.
A pure-code drawn circular wheel (no textures used). Six sectors correspond to six skills in fixed order:
| Number Key / Sector Order | Skill | Background Color |
|---|---|---|
| 1 | Recon Scan | Blue |
| 2 | Airdrop Supplies | Green |
| 3 | Tactical Smoke Wall | Gray-Blue |
| 4 | Artillery Support | Orange-Red |
| 5 | All-Out Assault | Gold |
| 6 | Strategic Retreat | Cyan |
- Mouse hover: The sector smoothly pops out and enlarges; the center disk shows the full skill name, description, and real-time status.
- Click a sector or press 1-6: Use that skill.
- Skills on cooldown appear dimmed, with remaining seconds displayed around the outer edge and a gradually closing dark ring.
- Center disk (when not hovering) shows: number of ready skills (e.g., "Ready 4 / 6"), your current skill points balance, and operation tips.
- Status refreshes every second (the server pushes data once per second).
- Press V again or Esc to close.
| Status | Text (Default) |
|---|---|
| Available | Ready! Click to use |
| Cooldown | Cooling down - {seconds}s left |
| Level insufficient | Need level {X} - You are level {Y} |
| Skill points insufficient | Not enough skill points - Need {X} - You have {Y} |
| Spam penalty active | Spam penalty active - Cost x{multiplier} |
| Module disabled | This skill module is disabled in config |
| System disabled | Commander system is disabled |
All these texts can be customized in the wheel section of the config. The skill name, short name, and description can also be edited individually (wheel.scan.name / shortName / desc, etc.).
Clicking "Airdrop" on the wheel does not immediately enter aiming mode. Instead, a second identical wheel appears, allowing you to choose the supply type for this drop (three types by default):
| ID | Name | Behavior |
|---|---|---|
supply |
Supply Crate | Standard logic: upon landing, spawns a pile of items (default) or a chest |
repair |
Vehicle Repair Crate | By default entity is empty - temporarily behaves like supply crate; fill in an entity ID to spawn that entity |
vehicle |
Vehicle Airdrop | Upon landing, directly spawns the configured vehicle entity (default: superbwarfare:sodayo_pick_up; if that mod isn't installed, a chat error will appear) |
After selecting the type, you then enter aiming mode.
Skills that require selecting a landing point (Airdrop, Artillery (direct mode), Tactical Smoke Wall) first enter aiming mode after selection. The preview is drawn directly in the game world (visible only to you, no network packets sent):
| Skill | Preview Appearance | Activation Condition |
|---|---|---|
| Airdrop | A green circle on top of the target block + center dot | Crosshair must point at a block (range 64 blocks) |
| Artillery | A cannon calibration reticle: filled square + border + corner brackets + scope ring + crosshair + impact zone circle; square size = actual scatter area | Crosshair must point at a block (range 128 blocks) |
| Smoke Wall | A line from the crosshair point + semi-transparent curtain facade + two end pillars | Does not require a block hit; if pointing at air, appears at max detection distance (smoke.spawnRange, default 32 blocks) |
- Left-click: Confirm activation (intercepts the vanilla punch/block-break action).
- Right-click / Esc: Cancel aiming.
- Preview and actual execution use exactly the same calculation: the server recalculates based on the crosshair position at the moment of confirmation.
- When "no-wall-penetration" is enabled, artillery impacts can also be blocked by roofs.
Each skill has an independent module switch (
moduleScan,moduleAirdrop,moduleSmoke,moduleArtillery,moduleAssault,moduleRetreat). When disabled, the wheel displays "Module disabled."
- Effect: All non-friendly players within a radius of 64 blocks centered on the commander receive a glowing outline for 10 seconds. Three expanding rings of end rod particles and a pling sound are played.
-
Who can see the glow is determined by
scan.glowVisibility:-
team(default): Only the commander and their teammates can see it via targeted packet sending; enemies see nothing. -
self: Only the commander sees it. -
all: Everyone on the server sees it (vanilla glow effect).
-
- After scanning, the commander and teammates receive a list of detected enemies.
- Default cooldown: 30s, level requirement: 5, skill point cost: 1.
-
Process: Aim - Left-click confirm - A beacon-style beam (color
airdrop.beamColor, default white) appears at the landing point - after 5 seconds, supplies fall from the sky. -
Supply crate (default): A supply crate entity descends slowly from 24 blocks above the landing point (0.35 blocks/tick), with trailing particles and a parachute particle ring. Upon landing, scatters the contents as item drops (default
landAsItems=true).- Descent follows a straight line without passing through blocks.
- Setting
landAsItems=falsemakes it place a chest filled with supplies, which disappears after 120 seconds.
- Default loot: Cooked beef x8, Golden apple x2, Arrow x32, Golden carrot x6 (fully editable; item IDs support other mods).
- Vehicle/Entity type: When the selected type's entity field is non-empty, after the beam phase ends, the entity is spawned directly at the landing point. Facing direction is snapped to cardinal directions. If the entity ID/NBT is invalid, nothing is spawned and the reason is printed in your chat.
- Default cooldown: 120s, level requirement: 10, skill point cost: 2.
- Process: Select skill - Enter aiming mode - Left-click to deploy the smoke wall. First generates a central panel, then spreads left and right layer by layer (default every 4 ticks). The wall surface is perpendicular to your line of sight.
-
What is generated is controlled by
smoke.customEntity(default is empty):- Set to
commander:smoke_wall- uses the built-in smoke wall entity: invisible body, particle-based, advances 0.06 blocks per tick, lasts 20 seconds; teammates standing inside gain Speed I + Jump Boost I. - You can also use other mod's entity IDs, attaching custom data via
customEntityNbt. - If the ID doesn't exist or the entity cannot be spawned: a clear error message appears in chat.
- Set to
-
Number of panels:
smoke.countsets a fixed total number (max 33). Set to 0 = auto-calculate. -
No wall penetration (
smoke.blockWalls, default true): Spreading stops on a side if there is a solid block in the way. - Default cooldown: 90s, level requirement: 15, skill point cost: 2.
Two modes, chosen by artillery.mode:
A. direct (default) - Direct overhead bombardment
- After aiming and confirming: a salvo of 5 shells falls one by one (interval 15 ticks = 0.75s). Each shell draws a descending trail of smoke particles 10 ticks before impact.
-
Landing pattern:
landing=scatter(default) - each shell lands randomly within a square area of +/-3 blocks around the aim point.same= all shells land exactly on the crosshair point. -
Approach direction:
vertical(default) = straight down.mortar= from an oblique angle, elevationmortarAngle(default 45 degrees). -
Damage: 8 points (4 hearts) at epicenter, linearly decreasing to 30% at the edge. Knockback 0.5. Setting
damage=-1reverts to vanilla explosion damage. -
Hit vehicles: When
hitVehicles=true(default), vehicles and other non-living entities are also affected. - No wall penetration: Impact point snaps to the top face of the first block.
-
Block destruction:
destroyBlocks=false(default) - never destroys any blocks. - Camera shake: Explosions cause nearby players' screens to shake (intensity 0.85, range 40 blocks). Affects visuals only.
- Battle report: After the salvo, the commander receives: "Hit X targets, dealing Y total damage."
- Default cooldown: 120s, level requirement: 20, skill point cost: 3.
B. toolkit - Issue artillery toolkits
- Using the skill gives you an Artillery Designator into your inventory.
- Then, holding the designator and right-clicking at the crosshair location calls in the same artillery strike.
- Effect: Applies positive effects to all online players on the commander's friendly team. Default: Strength I + Speed I + Regeneration I for 20 seconds.
- The effect list, amplifier, and duration are all configurable under
assault.effects. - If the commander has no team, the skill affects only themselves.
- Default cooldown: 180s, level requirement: 25, skill point cost: 3.
- Default effects: Speed II + Resistance I + Fire Resistance for 15 seconds (
retreat.effectsconfigurable). - Default cooldown: 180s, level requirement: 30, skill point cost: 2.
- Item ID:
nbt_6_commander_vote_sta:artillery_designator. Found in Creative Mode under "Tools & Utilities". - Hold and right-click = calls in an artillery strike at the crosshair location (within 128 blocks).
- Has an independent cooldown (default 120s) and is also subject to the global 1.5s public cooldown.
- Success/failure messages appear in chat.
Full check sequence for a skill activation:
System enabled -> Module enabled -> Global cooldown ready -> Skill cooldown ready -> Level sufficient -> Skill points sufficient -> Activation succeeds
- By default, does not use vanilla XP. Reads the scoreboard objective
commander_level. - To level up:
/scoreboard players set <player> commander_level 20 - Default level requirements: scan 5, airdrop 10, smoke 15, artillery 20, assault 25, retreat 30.
- Change
levels.sourcetoxpto use vanilla experience levels. -
/commander levellimit offignores all level requirements.
- Reads the scoreboard objective
commander_points. Points are checked first, deducted only on success. - Default costs: scan 1, airdrop 2, smoke 2, artillery 3, assault 3, retreat 2.
- Adding points:
/scoreboard players add <player> commander_points 10 -
skillPoints.enabled=falsecompletely disables the skill point system.
| Skill | scan | airdrop | smoke | artillery | assault | retreat | designator | global |
|---|---|---|---|---|---|---|---|---|
| Default | 30s | 120s | 90s | 120s | 180s | 180s | 120s | 1.5s |
- Global public cooldown: After using any skill, all skills are locked for an additional 1.5 seconds (0 = disabled).
- Enabled by default: Using the 3rd or subsequent skill within a 60-second window doubles the skill point cost.
- A notification is shown the first time the penalty triggers. While active, the wheel displays "Cost x2".
File location: config/commander_system.json
- Every field has a comment above it; deleting them does not affect reading.
- Save changes, then run
/commander reload(needs OP 2) - takes effect immediately. - Missing fields are automatically restored with default values on reload.
- Corrupted JSON will not crash the game: the load fails gracefully, keeping the currently active config.
- Double quotes inside NBT strings must be escaped as
\".
| Section | Controls | Most Used Keys (Default Values) |
|---|---|---|
moduleScan etc. (6 booleans) |
Skill module switches | All true
|
moduleIdentity / moduleLevelLimit
|
Reserved fields, currently control nothing | true |
vote |
Voting |
durationSeconds (60) |
levels |
Level restrictions |
enabled (true), six skill levels |
skillPoints |
Skill points |
enabled (true), six skill costs |
cooldowns |
Cooldowns |
globalTicks (30) |
penalty |
Spam penalty |
windowSeconds (60), allowedCount (2) |
scan |
Recon scan |
radius (64), glowSeconds (10) |
airdrop |
Airdrop |
beamSeconds (5), beamColor (FFFFFF) |
smoke |
Smoke wall |
customEntity (empty), count (0) |
artillery |
Artillery |
mode (direct), strikes (5), damage (8) |
assault / retreat
|
Team buffs |
seconds, effects list |
wheel |
All text on the wheel | Leave empty = built-in text |
messages |
All chat messages + prefix | prefix=[Commander]
|
/commander artillery approach vertical|mortar
/commander artillery angle 35
/commander artillery bearing look|south|west|north|east
/commander artillery shake 0.5 | off
| Command | Description |
|---|---|
/commander vote start |
Initiate a campaign to become your team's commander |
/commander vote yes / vote no
|
Vote yes/no for the ongoing vote in your team |
| `/commander skill scan | airdrop |
/commander help |
Print help |
| Command | Description |
|---|---|
/commander grant <player> |
Directly appoint a commander |
/commander cancel |
Revoke all commanders + cancel any ongoing vote |
/commander enable / disable
|
Master switch |
/commander levellimit on/off |
Toggle level restrictions |
/commander reload |
Hot-reload the config file |
/commander checknbt <NBT text> |
Validate SNBT syntax |
/commander artillery approach/angle/bearing/shake |
Quick artillery adjustments |
- Artillery uses a custom damage type
commander_artillery, tagged with vanilla tags:-
minecraft:is_explosion- blast protection works normally. -
minecraft:bypasses_cooldown- ignores invincibility frames.
-
- Death messages come in two variants:
- On the victim's screen: "You were torn to pieces by artillery called in by {commander}"
- In chat for everyone: "{victim} was blown to bits by {commander}'s artillery"
- Kill credit goes to the commander who called the strike.
| Thing | ID | Purpose |
|---|---|---|
| Artillery Designator | nbt_6_commander_vote_sta:artillery_designator |
Toolkit mode artillery trigger |
| Smoke Wall Entity | commander:smoke_wall |
Built-in smoke wall |
| Supply Crate Entity | commander:supply_crate |
Falling chest model |
| Airdrop Beam Entity | commander:airdrop_beam |
Beacon-style beam |
| Damage Type | nbt_6_commander_vote_sta:commander_artillery |
Artillery damage |
This mod is designed for permanent multiplayer battle servers:
- Network efficiency: smoke particles merged per column; glow markers sent via targeted packets.
- Near-zero per-tick overhead: task table allocates nothing when idle.
- Caching: particle/sound ID resolution cached globally.
- No memory leaks: cooldown tables cleaned every 10 seconds.
- Raycasting only runs at skill activation - no per-tick raycasts.
Under normal combat conditions, the impact on TPS is negligible.
Q: Pressing V does nothing? A: You are not the commander. Start a vote or ask an admin to grant you.
Q: Why can't I vote? "There is no active vote for your team"? A: Voting is per team. Make sure you have joined a team.
Q: My teammate voted, but isn't counted? A: Only online teammates are eligible. If all eligible voters have voted, the result is calculated immediately.
Q: How do I level up a player / give skill points?
/scoreboard players set <player> commander_level 30
/scoreboard players add <player> commander_points 10
Q: The smoke wall skill did nothing?
A: smoke.customEntity is empty by default. Set it to commander:smoke_wall or another mod's entity ID.
Q: Airdrop vehicle gives error "Entity ID does not exist"? A: The default vehicle is from the Superb Warfare mod. Replace with a valid entity ID from your server.
Q: I changed the config but it didn't take effect?
A: Double quotes inside NBT strings must be escaped as \". Use /commander checknbt to validate.
Q: Can voting be restricted to OPs only? A: Any player can start a vote. There is no separate vote switch.
Q: If the commander goes offline, do their skills remain? A: Yes, identity persists with the world save.
Q: Can two votes happen at the same time? A: No, only one vote is allowed server-wide at any time.
| Item | Default Value |
|---|---|
| Vote duration | 60 seconds |
| Wheel key | V |
| Global cooldown | 1.5 seconds |
| Skill cooldowns | Recon 30 / Airdrop 120 / Smoke 90 / Artillery 120 / Assault 180 / Retreat 180 / Designator 120 |
| Skill levels | 5 / 10 / 15 / 20 / 25 / 30 |
| Skill points cost | 1 / 2 / 2 / 3 / 3 / 2 |
| Spam penalty | 3rd skill within 60s costs x2 |
| Recon | Radius 64, glow 10s, teammates only |
| Airdrop | Beam 5s, loot: beef x8, apple x2, arrow x32, carrot x6 |
| Artillery | 5 shells, 0.75s interval, damage 8, no block destruction |
| Message prefix | [Commander] |