premium banner

ClanZZ

ZZClan is the clan system of the ZZ ecosystem for Hytale. It combines JSON persistence, a visual clan panel, internal rank permissions, clan territory and war systems, and social providers consumed by other ZZ modules.

Description

What ZZClan Does

  • Handles clan creation, invitations, membership, MOTD, description, and the main clan panel.
  • Uses editable internal clan ranks stored in permissions.json.
  • Supports clan territory, visitor rules, and rank-based access on top of the ecosystem territory layer.
  • Supports clan war flows with declaration, warmup, active window, and conquest of frontier claims.
  • Registers organization and prefix providers that other modules can consume.

Commands And Workflow

  • /clan is the root command surface.
  • Current clan flows include create, invite, join, leave, kick, promote, demote, claim, unclaim, chat, voice, info, members, motd, and rankperm.
  • The main player experience is UI-first from the clan panel.
  • Territory and war actions depend on internal clan permissions, not only on clan.use.

Runtime Files And Data

  • config.json stores costs, limits, cooldowns, social settings, and war rules.
  • messages.json stores the editable message catalog.
  • permissions.json stores the base clan-rank and internal-permission model.
  • ui.json stores dashboard and panel behavior settings.
  • The module stores its runtime data under ZonaZeroMc/ZZClan.
  • clans/ stores one file per clan.
  • players/ stores player index and state.
  • audit/clans/ stores extended clan history.
  • wars.json stores war, capture, and conquest state.

Visible Config Example

This is the kind of main config.json file you will see when the module generates its settings:

{
  "version": 1,
  "prefix": "&6[&eZZClan&6] &r",
  "allowConsoleCommands": true,
  "auditEnabled": true,
  "auditMaxEntries": 250,
  "auditInlineEntries": 20,
  "inviteOnlyOnlinePlayers": true,
  "creationCost": 0.0,
  "memberUpgradeCost": 5000.0,
  "memberUpgradeSlots": 5,
  "maxExtraMemberSlots": 30,
  "claimUpgradeCost": 2500.0,
  "claimUpgradeGroups": 1,
  "maxExtraClaimGroups": 12,
  "creationCooldownSeconds": 3600,
  "inviteCooldownSeconds": 15,
  "inviteExpiresSeconds": 86400,
  "maxMembers": 20,
  "maxPendingInvitesPerClan": 20,
  "maxPendingInvitesPerPlayer": 3,
  "maxCustomRanks": 8,
  "rankNameMaxLength": 24,
  "nameMinLength": 3,
  "nameMaxLength": 16,
  "tagMinLength": 2,
  "tagMaxLength": 5,
  "descriptionMaxLength": 120,
  "messageMaxLength": 80,
  "maxActionsPerWindow": 8,
  "rateLimitWindowSeconds": 15,
  "removeExpiredInvitesOnLoad": true,
  "grantSingleplayerOwnerAdmin": true,
  "enableClanBalance": true,
  "enableClanProgression": false,
  "useClanTreasuryForMemberUpgrades": true,
  "useClanTreasuryForClaimUpgrades": true,
  "notifyMembersOnJoinLeave": true,
  "defaultClanPvpEnabled": false,
  "enableChatPrefixes": true,
  "enableNameplatePrefixes": true,
  "enableVoicePreparation": true,
  "enableClanWars": true,
  "warWarmupMinutes": 15,
  "warDurationMinutes": 180,
  "warCaptureShieldMinutes": 20,
  "warMinOnlineDefenders": 0,
  "warMaxCapturesPerWar": 8,
  "warDeclarationCost": 0.0,
  "allowedNamePattern": "^[A-Za-z0-9_-]+$",
  "allowedTagPattern": "^[A-Z0-9]+$",
  "defaultDescription": "Clan recien fundado.",
  "defaultMotd": "Bienvenidos al clan.",
  "blacklistedNames": ["admin", "staff", "owner", "mod"],
  "blacklistedTags": ["gm", "adm", "mod"],
  "offensiveWordBlacklist": [],
  "usePermissionNodes": ["clan.use", "clan.admin"],
  "adminPermissionNodes": ["clan.admin"],
  "adminPlayers": [],
  "adminRanks": [],
  "rankPermissionTemplates": ["rank.{rank}", "group.{rank}"]
}

permissions.json and ui.json are separate editable files, and they are also explained below.

Configuration Reference

Main Clan Settings In config.json

  • version (number): internal config schema version.
  • prefix (text): chat prefix used by the module.
  • allowConsoleCommands (true/false): allows console flows when enabled.
  • auditEnabled (true/false): enables or disables audit storage.
  • auditMaxEntries (number): max stored audit entries per clan history.
  • auditInlineEntries (number): number of audit entries used in inline previews.
  • inviteOnlyOnlinePlayers (true/false): restricts invites to online players when enabled.

Costs, Upgrades, And Limits

  • creationCost (number): cost to create a clan.
  • memberUpgradeCost (number): cost of one member-cap upgrade.
  • memberUpgradeSlots (number): extra member slots granted per upgrade.
  • maxExtraMemberSlots (number): max extra member slots obtainable.
  • claimUpgradeCost (number): cost of one claim-cap upgrade group.
  • claimUpgradeGroups (number): extra claim groups granted per upgrade.
  • maxExtraClaimGroups (number): max extra claim groups obtainable.
  • creationCooldownSeconds (number): cooldown before creating another clan.
  • inviteCooldownSeconds (number): cooldown between invite actions.
  • inviteExpiresSeconds (number): invite expiration time.
  • maxMembers (number): base max members per clan.
  • maxPendingInvitesPerClan (number): max pending invites stored by one clan.
  • maxPendingInvitesPerPlayer (number): max pending invites one player can hold.
  • maxCustomRanks (number): max custom ranks allowed.
  • rankNameMaxLength (number): max rank-name length.

Validation And Rate Limits

  • nameMinLength and nameMaxLength (number): allowed clan-name length range.
  • tagMinLength and tagMaxLength (number): allowed clan-tag length range.
  • descriptionMaxLength (number): max clan description length.
  • messageMaxLength (number): max MOTD length.
  • maxActionsPerWindow (number): action limit inside the current rate-limit window.
  • rateLimitWindowSeconds (number): rate-limit window size.
  • removeExpiredInvitesOnLoad (true/false): removes expired invites on load when enabled.
  • grantSingleplayerOwnerAdmin (true/false): grants owner admin conveniences in singleplayer-style setups when enabled.

Social And Economy Toggles

  • enableClanBalance (true/false): enables clan balance support.
  • enableClanProgression (true/false): enables progression support.
  • useClanTreasuryForMemberUpgrades (true/false): pays member upgrades from clan treasury when enabled.
  • useClanTreasuryForClaimUpgrades (true/false): pays claim upgrades from clan treasury when enabled.
  • notifyMembersOnJoinLeave (true/false): notifies members when players join or leave.
  • defaultClanPvpEnabled (true/false): default clan PvP state.
  • enableChatPrefixes (true/false): enables clan prefixes in chat.
  • enableNameplatePrefixes (true/false): enables clan prefixes on nameplates.
  • enableVoicePreparation (true/false): enables voice-preparation support.

Clan War Settings

  • enableClanWars (true/false): enables or disables clan wars.
  • warWarmupMinutes (number): warmup before war starts.
  • warDurationMinutes (number): war duration.
  • warCaptureShieldMinutes (number): shield time before captures can happen.
  • warMinOnlineDefenders (number): min online defenders required.
  • warMaxCapturesPerWar (number): max captures counted per war.
  • warDeclarationCost (number): cost to declare war.

Text Rules, Blacklists, And Admin Lists

  • allowedNamePattern (text): regex used to validate clan names.
  • allowedTagPattern (text): regex used to validate clan tags.
  • defaultDescription (text): default clan description.
  • defaultMotd (text): default clan MOTD.
  • blacklistedNames (list): blocked clan names.
  • blacklistedTags (list): blocked clan tags.
  • offensiveWordBlacklist (list): blocked offensive words.
  • usePermissionNodes (list): external nodes that grant normal clan access.
  • adminPermissionNodes (list): external nodes that grant clan admin access.
  • adminPlayers (list): player names that always count as admins.
  • adminRanks (list): rank names that always count as admins.
  • rankPermissionTemplates (list): templates used to resolve rank-based external permissions.

permissions.json

  • version (number): internal schema version for rank config.
  • cloneDefaultRanksIntoClan (true/false): clones default rank templates into new clans when enabled.
  • defaultRanks (list of entries): ordered rank templates used by the module.

ui.json

  • version (number): UI config schema version.
  • dashboardTitle (text): main dashboard title.
  • dashboardSubtitle (text): main dashboard subtitle.
  • memberListLimit (number): member rows shown in player UI.
  • inviteListLimit (number): invite rows shown in player UI.
  • auditPreviewLimit (number): audit preview size in player UI.
  • adminClanListLimit (number): clan rows shown in admin UI.
  • adminMemberListLimit (number): member rows shown in admin UI.
  • adminAuditPreviewLimit (number): audit preview size in admin UI.
  • auditPageLimit (number): full audit page size.
  • showAuditPreview (true/false): enables inline audit previews.
  • dateFormatPattern (text): date format used in UI rendering.

Permissions

External nodes:

  • clan.use
  • clan.admin

Internal rank permissions defined in permissions.json include:

  • open_panel
  • invite_members
  • kick_members
  • accept_invites
  • edit_description
  • edit_message
  • promote_members
  • demote_members
  • transfer_leadership
  • manage_alliances
  • manage_claims
  • claim_build
  • claim_interact
  • bank_deposit
  • bank_withdraw
  • manage_bank
  • manage_ranks
  • manage_voice
  • edit_settings
  • disband_clan
  • view_audit

Installation

  1. Copy ZZCore.jar into the server mods folder first.
  2. Copy ZZClan.jar into the same server mods folder after that.
  3. If you want clan claims, conquest, and war territory support, also install ZZFrontier.jar.
  4. Start Hytale.
  5. Configure costs, ranks, social settings, and war rules.

License

All Rights Reserved.

Redistribution, reposting, resale edits, or reuploading forks is not allowed without written permission from the author.

Links