teams.yml¶

Teams: names, size, roles, invitations, alliances, focus, rally, the bank, and the Team Points scale.

Every example on this page is taken from the shipped teams.yml. Changes apply with /hcf reload. Throughout the file, a limit of 0 means no limit. Teams have no enabled switch: the rest of the plugin is built on them.

Names¶

teams.yml

names:
  min-length: 3
  max-length: 16
  # Regex a team name must match in full. The default allows letters, digits and
  # underscores only. An invalid regex is reported in the console at load time and
  # the built-in default is used instead, rather than failing every command later.
  pattern: "^[A-Za-z0-9_]+$"
  # Names players may not use, compared case-insensitively. Staff-created system
  # teams are exempt from this list and from max-length - a server team's name may
  # be 32 characters, GlowstoneMountain say (hard-coded) - but not from min-length
  # or the pattern.
  blacklist:
    - "spawn"
    - "warzone"
    - "wilderness"
    - "staff"
    - "admin"

Key	As shipped	What it does
`min-length`, `max-length`	`3`, `16`	Length of a player's team name. Server teams staff create go up to 32 characters (hard-coded)
`pattern`	letters, digits, `_`	A regular expression the whole name must match. An invalid one is reported and the built-in one is used
`blacklist`	`spawn`, `warzone`, `wilderness`, `staff`, `admin`	Names players may not use, without case. Server teams are exempt

Members¶

teams.yml

# Maximum members per team. 0 = unlimited.
max-members: 20
# Maximum simultaneous co-leaders. 0 = unlimited.
max-co-leaders: 2
# Maximum simultaneous officers - the rank between member and co-leader. 0 = unlimited.
max-officers: 0

# How long an invitation stays valid, in seconds. 0 = invitations never expire.
invite-expiry-seconds: 300

# When the last remaining member leaves (or is removed), disband the team instead
# of leaving an empty one behind. Set to false if you would rather keep empty
# teams around, for example so their claims survive a temporary emptying.
disband-on-last-member-leave: true

# Role the outgoing leader drops to after handing over leadership.
# One of: leader, co-leader, officer, member.
role-after-leadership-transfer: co-leader

Key	As shipped	What it does
`max-members`	`20`	Members per team
`max-co-leaders`	`2`	Co-leaders at once
`max-officers`	`0`	Officers at once; `0` = no limit
`invite-expiry-seconds`	`300`	How long an invitation lasts; `0` never expires
`disband-on-last-member-leave`	`true`	Disband a team whose last member leaves
`role-after-leadership-transfer`	`co-leader`	What the old leader becomes: `leader`, `co-leader`, `officer` or `member`

Roles¶

teams.yml

required-roles:
  disband: leader
  rename: leader
  invite: officer
  revoke-invite: officer
  kick: co-leader
  promote: leader
  demote: leader
  transfer-leadership: leader
  ally: leader
  unally: leader
  focus: officer
  rally: officer
  bank-deposit: member
  bank-withdraw: leader
  # Opening /team settings.
  settings: leader

The minimum role for each action: leader, co-leader, officer or member. An unknown value falls back to leader, the safest, and is reported. The territory actions (claim, unclaim, set home, lock) are in claims.yml. Each team may choose its own role for any of them in /team settings, unless team-settings below locks it.

Team settings¶

teams.yml

# /team settings: a window where a team sets itself up with no command to type -
# its name, description and Discord invitation (typed in the game's own dialogs),
# who may join, which rank may do what (every key of required-roles above and in
# claims.yml, plus open-subclaims), its members (promote, demote, kick), its
# invitations, and the claim lock, HQ and base. Every member opens it; each button
# checks what it does and says, under it, who may use it.
team-settings:
  # false: every team follows the server's roles and default join mode, and
  # /team settings is refused.
  enabled: true
  # Who may join, among which a team chooses: closed (nobody - only staff put a
  # player in), invite (the invited), open (anybody, with /team join).
  join-modes: [closed, invite, open]
  # A team's join mode until it chooses one.
  default-join-mode: invite
  # Permissions no team may change: they follow the server's roles for everybody.
  locked: [disband, transfer-leadership]
  # Nobody hands out more than they have: whoever changes a permission must hold it,
  # and cannot set it above their own rank. The leader changes everything.
  description:
    # Shown in /team info. Colour codes are not kept: the team's words, as typed.
    max-length: 100
  discord:
    # What a Discord invitation link must look like. Shown in /team info, clickable.
    pattern: "^(https?://)?(www\\.)?(discord\\.gg|discord(app)?\\.com/invite)/[A-Za-z0-9-]{2,32}/?$"
  # The window's items, by permission key or button: profile, join-mode-closed,
  # join-mode-invite, join-mode-open, permissions, members, invites, invite, back,
  # lock-claim, sethq. A key left out keeps its default.
  icons: {}

Key	As shipped	What it does
`enabled`	`true`	`false`: every team follows `required-roles` and the default joining, and `/team settings` is refused
`join-modes`	`[closed, invite, open]`	Among which a team chooses who may join: nobody, the invited, anybody
`default-join-mode`	`invite`	A team's joining until it chooses
`locked`	`[disband, transfer-leadership]`	Permissions no team may change. The keys are those of `required-roles` here and in `claims.yml`, `create-subclaims` and `open-subclaims`
`description.max-length`	`100`	The longest description, in characters
`discord.pattern`	`discord.gg/...` or `discord.com/invite/...`	What a Discord invitation link must look like (a regular expression)
`icons`	`{}`	The window's items, by permission key or button: `profile`, `join-mode-closed`, `join-mode-invite`, `join-mode-open`, `permissions`, `members`, `invites`, `invite`, `back`, `lock-claim`, `sethq`

A team's choices — permissions, joining, description, Discord link — are kept in the database (hcf_team_settings). One stored before the server locked the permission, or switched the settings off, is ignored, not erased: unlock it and it applies again.

Shortcuts¶

teams.yml

# Shorter ways to type team commands.
shortcuts:
  enabled: true
  # Another word for a /team subcommand: /team i is /team info. A subcommand's own
  # name or alias always wins over a word here.
  subcommands:
    i: info
    h: hq
    home: hq
    sh: sethq
    d: deposit
    w: withdraw
    m: map
    k: kick
    s: settings
  # A command of its own: /hq is /team hq. The value is the subcommand, and may
  # carry arguments put before the player's own. A name that is already a command -
  # another plugin's, the server's - is left to it and reported in the console.
  commands:
    hq: hq
    base: base
    stuck: stuck
    fc: chat

Key	What it does
`subcommands`	Another word for a subcommand: `i: info` makes `/team i` work. A subcommand's own name or alias always wins
`commands`	A command of its own: `hq: hq` makes `/hq`. The value may carry arguments, put before the player's own. A name that is already a command — another plugin's, the server's — is left to it and reported in the console

Both are read again by /hcf reload; the commands are made and removed then, without a restart.

Alliances, focus and rally¶

teams.yml

alliances:
  enabled: true
  # Maximum allied teams per team. 0 = unlimited.
  max-allies: 1

teams.yml

focus:
  enabled: true
  # Maximum simultaneous focus targets (teams and players combined). 0 = unlimited.
  max-targets: 0

teams.yml

rally:
  enabled: true
  # How long a rally point stays active, in seconds. 0 = until cleared manually.
  duration-seconds: 300

Key	As shipped	What it does
`alliances.enabled`	`true`	Alliances at all
`alliances.max-allies`	`1`	Allied teams per team, checked on both sides
`focus.enabled`	`true`	Focus at all
`focus.max-targets`	`0`	Players and teams a team may focus at once
`rally.enabled`	`true`	Rally points at all
`rally.duration-seconds`	`300`	How long a rally point lasts; `0` until cleared

Looking for a team¶

teams.yml

# /lff [note] - "looking for faction": a player with no team tells everybody
# they want one, with a few words about themselves if they like.
lff:
  enabled: true
  # Seconds before the same player can use it again: an announcement, not a
  # spam channel.
  cooldown-seconds: 300
  # The longest note kept, in characters (0 to 200); the rest is cut.
  max-note-length: 64

Key	As shipped	What it does
`enabled`	`true`	`/lff` at all
`cooldown-seconds`	`300`	Before the same player can use it again
`max-note-length`	`64`	The longest note kept, 0 to 200 characters; colour codes are stripped

Bank¶

teams.yml

bank:
  # Turning this off rejects every deposit/withdraw on a team bank.
  # Money moves between a player's balance and the bank with /team deposit and
  # /team withdraw; turning the economy off in economy.yml disables those too.
  enabled: true

Key	As shipped	What it does
`bank.enabled`	`true`	Deposits and withdrawals. Turning the economy off disables them too

Points¶

teams.yml

points:
  # Points a newly created team starts with.
  starting: 0
  # Floor the score can never drop below.
  minimum: 0

  # The scale: what earns - or, with a negative number, costs - points. As
  # shipped a kill is +1 and a death -2, and an event is worth far more than the
  # kills fought for it along the way - a KOTH 100 (koth.points-per-capture
  # below), a Citadel 300 - so the event, not the farm, decides the ranking.
  # To the killer's team, for killing a player of any other team, or of none. A
  # player with no team can be an alt: watch for farming.
  per-kill: 1
  # To the victim's team, for any death of a member. A death costs more than a
  # kill earns: trading lives is a loss.
  per-death: -2
  # What a team loses when its DTR makes it raidable - being raided is the worst
  # that can happen to it. Either a share of its points, 0 to 100 (50: half)...
  raidable-loss-percent: 50
  # ...or, with the share at 0, a fixed number (write a negative one).
  per-raidable: 0
  # What it loses goes to the team whose kill made it raidable - the raid pays.
  # Never to an ally; nobody takes it when no team caused it (a fall, a mob).
  raidable-steal: true
  # To the team that captures a Citadel: three times a KOTH's hold.
  per-citadel-capture: 300
  # To the team that wins a Conquest: a long fight over several zones.
  per-conquest-win: 250
  # To the team that wins a DTC, or a Slide.
  per-dtc-win: 200
  per-slide-win: 200
  # To the team of the player who wins Kill the King, and to the team that wins
  # a Last Break - the last hit decides it, however the rest went.
  per-king-win: 150
  per-last-break-win: 150
  # To the team that wins a Totem, and a Mini Totem (a column of 3 blocks or fewer).
  per-totem-win: 150
  per-mini-totem-win: 80

Key	As shipped	What it does
`starting`	`0`	Points a new team starts with
`minimum`	`0`	The floor points never go below
`per-kill`	`1`	To the killer's team, for killing a player of another team or of none
`per-death`	`-2`	To the victim's team, for any death of a member
`raidable-loss-percent`	`50`	The share of its points a team loses when its DTR makes it raidable, 0 to 100
`per-raidable`	`0`	The same as a fixed number (negative), used when the share is `0`
`raidable-steal`	`true`	What it loses goes to the team whose kill made it raidable — not an ally's, and nobody's when no team caused the death
`per-citadel-capture`	`300`	To the team that captures a Citadel
`per-conquest-win`	`250`	To the team that wins a Conquest
`per-dtc-win` · `per-slide-win`	`200`	To the team that wins a DTC, a Slide
`per-king-win`	`150`	To the team of the player who wins Kill the King
`per-last-break-win`	`150`	To the team that wins a Last Break
`per-totem-win`	`150`	To the team that wins a Totem
`per-mini-totem-win`	`80`	To the team that wins a Mini Totem — a column of 3 blocks or fewer

KOTH captures¶

teams.yml

koth:
  # Cap on how many KOTH captures count toward a team's ranking. 0 = uncapped.
  # A KOTH capture is worth points-per-capture (a Citadel's is
  # points.per-citadel-capture); both count toward the cap, which is a balance
  # decision for your server, so it ships uncapped.
  max-counted-captures: 0
  points-per-capture: 100
  # Counted captures are reset by staff with /team resetkoth - at the start of a
  # map, or of whatever ranking period the server runs.

Key	As shipped	What it does
`max-counted-captures`	`0`	How many KOTH and Citadel captures count for a team's ranking; `/team resetkoth` resets the counts
`points-per-capture`	`100`	Points a KOTH capture is worth; a Citadel's is `points.per-citadel-capture`

The whole shipped file¶

View it on GitHub.

teams.yml

# ---------------------------------------------------------------------------
# HCFCore - Team module configuration
# ---------------------------------------------------------------------------
# Every rule the team module applies is defined here. Nothing below is
# duplicated as a constant in the plugin's code: no gameplay value should ever
# need a recompile.
#
# Changes take effect on /hcf reload - no server restart needed.
#
# Convention used throughout this file: a limit of 0 means "no limit".
#
# Lines "# --8<-- [start:...]" and "# --8<-- [end:...]" mark the parts the online
# documentation quotes from this file. They are comments and change nothing.
# ---------------------------------------------------------------------------

names:
  min-length: 3
  max-length: 16
  # Regex a team name must match in full. The default allows letters, digits and
  # underscores only. An invalid regex is reported in the console at load time and
  # the built-in default is used instead, rather than failing every command later.
  pattern: "^[A-Za-z0-9_]+$"
  # Names players may not use, compared case-insensitively. Staff-created system
  # teams are exempt from this list and from max-length - a server team's name may
  # be 32 characters, GlowstoneMountain say (hard-coded) - but not from min-length
  # or the pattern.
  blacklist:
    - "spawn"
    - "warzone"
    - "wilderness"
    - "staff"
    - "admin"

# Maximum members per team. 0 = unlimited.
max-members: 20
# Maximum simultaneous co-leaders. 0 = unlimited.
max-co-leaders: 2
# Maximum simultaneous officers - the rank between member and co-leader. 0 = unlimited.
max-officers: 0

# How long an invitation stays valid, in seconds. 0 = invitations never expire.
invite-expiry-seconds: 300

# When the last remaining member leaves (or is removed), disband the team instead
# of leaving an empty one behind. Set to false if you would rather keep empty
# teams around, for example so their claims survive a temporary emptying.
disband-on-last-member-leave: true

# Role the outgoing leader drops to after handing over leadership.
# One of: leader, co-leader, officer, member.
role-after-leadership-transfer: co-leader

# ---------------------------------------------------------------------------
# Minimum role required for each action. One of: leader, co-leader, officer,
# member. An unrecognised value falls back to "leader" (the safest option) and is
# reported in the console. Each team may choose its own in /team settings, unless
# team-settings below says otherwise.
# ---------------------------------------------------------------------------
required-roles:
  disband: leader
  rename: leader
  invite: officer
  revoke-invite: officer
  kick: co-leader
  promote: leader
  demote: leader
  transfer-leadership: leader
  ally: leader
  unally: leader
  focus: officer
  rally: officer
  bank-deposit: member
  bank-withdraw: leader
  # Opening /team settings.
  settings: leader

# /team settings: a window where a team sets itself up with no command to type -
# its name, description and Discord invitation (typed in the game's own dialogs),
# who may join, which rank may do what (every key of required-roles above and in
# claims.yml, plus open-subclaims), its members (promote, demote, kick), its
# invitations, and the claim lock, HQ and base. Every member opens it; each button
# checks what it does and says, under it, who may use it.
team-settings:
  # false: every team follows the server's roles and default join mode, and
  # /team settings is refused.
  enabled: true
  # Who may join, among which a team chooses: closed (nobody - only staff put a
  # player in), invite (the invited), open (anybody, with /team join).
  join-modes: [closed, invite, open]
  # A team's join mode until it chooses one.
  default-join-mode: invite
  # Permissions no team may change: they follow the server's roles for everybody.
  locked: [disband, transfer-leadership]
  # Nobody hands out more than they have: whoever changes a permission must hold it,
  # and cannot set it above their own rank. The leader changes everything.
  description:
    # Shown in /team info. Colour codes are not kept: the team's words, as typed.
    max-length: 100
  discord:
    # What a Discord invitation link must look like. Shown in /team info, clickable.
    pattern: "^(https?://)?(www\\.)?(discord\\.gg|discord(app)?\\.com/invite)/[A-Za-z0-9-]{2,32}/?$"
  # The window's items, by permission key or button: profile, join-mode-closed,
  # join-mode-invite, join-mode-open, permissions, members, invites, invite, back,
  # lock-claim, sethq. A key left out keeps its default.
  icons: {}

# Shorter ways to type team commands.
shortcuts:
  enabled: true
  # Another word for a /team subcommand: /team i is /team info. A subcommand's own
  # name or alias always wins over a word here.
  subcommands:
    i: info
    h: hq
    home: hq
    sh: sethq
    d: deposit
    w: withdraw
    m: map
    k: kick
    s: settings
  # A command of its own: /hq is /team hq. The value is the subcommand, and may
  # carry arguments put before the player's own. A name that is already a command -
  # another plugin's, the server's - is left to it and reported in the console.
  commands:
    hq: hq
    base: base
    stuck: stuck
    fc: chat

alliances:
  enabled: true
  # Maximum allied teams per team. 0 = unlimited.
  max-allies: 1

focus:
  enabled: true
  # Maximum simultaneous focus targets (teams and players combined). 0 = unlimited.
  max-targets: 0

rally:
  enabled: true
  # How long a rally point stays active, in seconds. 0 = until cleared manually.
  duration-seconds: 300

# /lff [note] - "looking for faction": a player with no team tells everybody
# they want one, with a few words about themselves if they like.
lff:
  enabled: true
  # Seconds before the same player can use it again: an announcement, not a
  # spam channel.
  cooldown-seconds: 300
  # The longest note kept, in characters (0 to 200); the rest is cut.
  max-note-length: 64

bank:
  # Turning this off rejects every deposit/withdraw on a team bank.
  # Money moves between a player's balance and the bank with /team deposit and
  # /team withdraw; turning the economy off in economy.yml disables those too.
  enabled: true

points:
  # Points a newly created team starts with.
  starting: 0
  # Floor the score can never drop below.
  minimum: 0

  # The scale: what earns - or, with a negative number, costs - points. As
  # shipped a kill is +1 and a death -2, and an event is worth far more than the
  # kills fought for it along the way - a KOTH 100 (koth.points-per-capture
  # below), a Citadel 300 - so the event, not the farm, decides the ranking.
  # To the killer's team, for killing a player of any other team, or of none. A
  # player with no team can be an alt: watch for farming.
  per-kill: 1
  # To the victim's team, for any death of a member. A death costs more than a
  # kill earns: trading lives is a loss.
  per-death: -2
  # What a team loses when its DTR makes it raidable - being raided is the worst
  # that can happen to it. Either a share of its points, 0 to 100 (50: half)...
  raidable-loss-percent: 50
  # ...or, with the share at 0, a fixed number (write a negative one).
  per-raidable: 0
  # What it loses goes to the team whose kill made it raidable - the raid pays.
  # Never to an ally; nobody takes it when no team caused it (a fall, a mob).
  raidable-steal: true
  # To the team that captures a Citadel: three times a KOTH's hold.
  per-citadel-capture: 300
  # To the team that wins a Conquest: a long fight over several zones.
  per-conquest-win: 250
  # To the team that wins a DTC, or a Slide.
  per-dtc-win: 200
  per-slide-win: 200
  # To the team of the player who wins Kill the King, and to the team that wins
  # a Last Break - the last hit decides it, however the rest went.
  per-king-win: 150
  per-last-break-win: 150
  # To the team that wins a Totem, and a Mini Totem (a column of 3 blocks or fewer).
  per-totem-win: 150
  per-mini-totem-win: 80

koth:
  # Cap on how many KOTH captures count toward a team's ranking. 0 = uncapped.
  # A KOTH capture is worth points-per-capture (a Citadel's is
  # points.per-citadel-capture); both count toward the cap, which is a balance
  # decision for your server, so it ships uncapped.
  max-counted-captures: 0
  points-per-capture: 100
  # Counted captures are reset by staff with /team resetkoth - at the start of a
  # map, or of whatever ranking period the server runs.