ZiggfreedCommon: shared engines & files

One library, several engines

ZiggfreedCommon is the jar the server loads before MMO Skill Tree. It is a hard requirement, it is never bundled inside the MMO jar, and one copy covers every mod on the server that needs it. What it does is worth knowing, because a lot of what looks like MMO Skill Tree machinery is actually the library's: the quest and achievement engines and the one progress record they keep per player, the one requirements block, the dialogue engine, NPC placement, the whole economy, reputations, the authored feedback moments and their neutral defaults, the in-world tracked-quest HUD, shared loot tables, the placed-block ledger, titles, gear sets, and the Records tab that ranks every player. Since 1.7.0 (CommonLib 2.2.0) it also draws the Objective Book (a quest journal, and an achievement Overview, Browse and Statistics view) and the Almanac. MMO Skill Tree feeds the book (its statistics, its quest and achievement categories) rather than drawing one of its own. The book is the library's item, opened with a right click, and players can craft it by hand from one Light Leather and two Plant Fiber, under Tools in the hand-crafting menu. The recipe ships in the library as Server/Item/Recipes/Ziggfreed_Objective_Book.json, and a pack overrides it by that id.

The practical consequence for a server owner is that some content lives under Server/ZiggfreedCommon/ instead of Server/MMOSkillTree/, and some files you edit live in mods/ziggfreedcommon/ instead of mods/mmoskilltree/. Everything else works the way it always did.

The progression runtime

There is one quest engine and one achievement engine per server, held by the library. Every mod that has quests or achievements registers its own vocabulary into them, so a single quest log, a single achievement list, and a single definition of "completed" serve the whole server.

• Five producers always run: breaking a block, killing a mob, crafting, picking an item up, and placing a block. They are never claimed by one mod and never stand down, so an objective counting any of those five counts correctly no matter which mod authored it.
• A mod with a moment of its own fires it itself. That is how a station, a minigame or a companion mod feeds the same quest log without the library having to know about it in advance.
• Achievements land instantly. Progress is folded on the spot rather than by a background pass, so an achievement finishes the moment its last criterion does.
• One record per player. A player's quests, achievements and what conversations remember about them are one saved record the library keeps, not three. A server upgraded from 1.5.x copies each player's old quest and achievement state onto it the first time they connect after the update, once and never again; nothing is asked of you.
• The MMO reacts to the moments the library produces. When the library announces a block broken, a mob killed, an item crafted or picked up, or a block placed, the MMO's XP, statistics and bonus drops all hang off that one announcement rather than detecting the action a second time. A kill by a player's turret or summoned ally is announced for the player who owns it, so it pays them.

Where a quest or achievement file lives is covered under content paths, and the authoring reference is on Authoring Quests and Authoring Achievements. The runtime is driven by hand through the library's own /zigprogress family; the MMO's /mmoquestadmin, /quest and /mmoachadmin are aliases over it.

One way to say "you need this first"

Every gated thing on the server - a quest, an achievement, a shop offer, a storefront, a board or one of its slots, a wallet, an NPC placement, a dialogue option, a mastery node - asks the same question the same way, through one Requires block. Learning it once covers all of them.

• Leaves: Factors (a reading with an optional Min and Max), Permission (one node), Quests (quest names that must be completed), and Custom (kinds a mod registers).
• Combinators: AllOf, AnyOf, and Not.

Levels, features, mastery and progression are all readings you can put bounds on - a level is a hytale:stat bound, a feature an mmoskilltree:feature bound, a collected quest a ziggfreedcommon:quest_completed bound - and an installed companion mod can contribute readings of its own. The one factor-spellings table, with a worked line for each, lives on Shared Schemas; this page keeps only the shape.

Completed means collected. A quest prerequisite and the quest_completed reading both mean the reward was actually taken; a quest finished but parked unclaimed satisfies neither.

A refusal lists everything. When a player looks at something they cannot have yet, the detail panel lists every unmet requirement, not just the first one, in plain wording per requirement kind. The full field reference is on Shared Schemas.

The dialogue engine

One dialogue engine runs on the server, and every mod registers its own actions and conditions into it. A single conversation can therefore mix two mods' actions: an MMO quest hand-in beside a station's own beat, in one option list, with no adapter in between.

• Conversations live in the shared store and reuse each other through native Parent inheritance; an Abstract file is a base other files inherit from.
• Seen-ness is a Once knob on a greeting or an option, optionally scoped to a world family, offered again each day or week, or kept apart for each character, so a first-visit line or a daily gift needs no hand-composed key.
• Anything else a conversation must remember is a declared Memories entry used by its plain name, with a stated lifetime (per world, cleared with a quest, or shared).
• Talk credit for a TALK_TO_NPC objective is explicit: a conversation credits with a MarkTalked action, and an NPC with no conversation credits through a talk action on its own role.

The library draws the conversation page too: the character's name, the quest step a player is on with them, their line, and the answers under it in one scrolling column, each answer led by a picture of what it does. Authoring reference: Authoring Dialogues and Quest Givers & Dialogue.

NPC placement

Where an NPC stands, which worlds it appears in, whether it appears at all, and what pressing F on it opens are one asset owned by the library. That covers the Adventurer's Guide, quest givers, the Mastery Trainer, and anything a pack places.

• A placement names a role and a position (world spawn with an offset, fixed coordinates, a structure, a zone, or a custom anchor), the worlds it applies to, an optional Requires gate, spawn limits, a lifecycle, and one interaction.
• The interaction is either a conversation or a menu destination, never both. A placement that authors neither opens that character's quest list.
• Two placements of one role are two standings of one character, so a quest bound to it is offered, credited and handed in at either with nothing authored twice.

The kill switch is mods/ziggfreedcommon/npc-placements.json and /mmonpc manages it live. Full guide: Placed NPCs & the Adventurer's Guide.

The economy

Wallets, storefronts, shelves, boards and contracts are the library's. MMO Skill Tree supplies the theme, the reward kinds and thin command aliases; the engine underneath is shared, so a second mod adding a currency or a shop does it the same way and both appear in the same screens.

• Wallets carry an icon, a colour, an optional cap, an optional backing item, what happens on death, optional decay, and a visibility gate. Prices and balances name the wallet beside the amount ("6 Hallow Sweets"), in its plural where the pack ships an amount line for it.
• Storefronts carry their shelves and shelf order, a currency strip in the header, and their own worlds and requirements.
• Shelf pools handle rotation, selection and rerolls; one generator file can write a whole family of offers.
• Boards carry rotation, slots by difficulty band, reroll cost and allowance, what each band is called, and per-band accept requirements. A contract is an ordinary quest with board membership.

Owner files are mods/ziggfreedcommon/currencies.json, shops.json, shop-pools.json and boards.json, each overriding by name one field at a time. Guides: Currencies, Token Shop, Bounty Board.

Reputation

A reputation is a player's standing with a faction or one character, kept by Hytale's own reputation system: the game saves it with the character, through death and across worlds. The library gives each one a name, a picture and its own rank names, adds standing from rewards and kills, and lets worn gear make every gain bigger by a percent (gear never adds standing of its own). Players find it on the Reputation tab of the shared menu, which lists each reputation they have met and, for the one they pick, how to earn it (with how much their gear raises each gain), every rank with the standing it takes and what it opens, and what they have earned. A bar on the World bars panel, named for the reputation alone, moves when standing earned out in the world changes it; standing earned in a menu (collecting a reward, buying something, a conversation line) is listed in that menu's notice instead, such as "+250 Town Guard". A notice marks each new rank. Content reads it through two factors (ziggfreedcommon:reputation and reputation_rank), pays it with the Reputation reward kind, and counts ranks with the REPUTATION_RANK objective kind.

A reputation is a pack's reputation group under Server/NPC/Reputation/Groups/ plus an optional companion file under Server/ZiggfreedCommon/Reputations/; the library ships the one rank ladder every reputation climbs. The owner file is mods/ziggfreedcommon/reputation.json: {"$Enabled": false} switches every reputation off, and any other key retunes one reputation by id. Seasons of Orbis ships the first two, Old Jack's Favor and the Hallowed. Authoring reference: Authoring Reputations.

Calendar events

A calendar event says when something is on: a yearly season such as Seasons of Orbis's Hallows_Eve, or anything else with days. It is one file, Server/ZiggfreedCommon/CalendarEvents/<Owner>/<Id>.json, and its file name is the id content names it by: a Season leaf on a placement, a storefront, a board, an offer, a quest, a dungeon, a bonus row or a reputation's kill row keeps that content to the time the event is live, and the reading ziggfreedcommon:calendar_live answers it for a lock or a roll. Window gives its days (Start and End as month-days with both days in, or a Rule for days that move), FirstYear the first year it runs, Clock the time zone its days are counted in (UTC unless set), and Herald the banner as it begins and ends. A server owner switches an event off or moves its days in mods/ziggfreedcommon/calendar.json (see The event and its days).

Live by a condition: Moon and Live

From CommonLib 2.5.0 an event can be live by a condition instead of by its dates: write a Moon or a Live group in place of the Window. Content keeps one Season string either way, so a shelf, a board slot or a kill row can follow the full moon, or an event made of other events.

// Server/ZiggfreedCommon/CalendarEvents/MyPack/MyPack_Full_Moon.json
{
  "Moon": { "MoonPhaseRange": [0, 1] },
  "Presentation": { "TitleKey": "calendar.mypack_full_moon.name" },
  "Herald": { "OncePerDay": true, "Start": { "TitleKey": "calendar.mypack_full_moon.herald.start" } }
}

// Server/ZiggfreedCommon/CalendarEvents/MyPack/MyPack_Hallowed_Moon.json: a full moon during Hallow's Eve
{
  "Live": { "AllOf": ["MyPack_Full_Moon", "Hallows_Eve"] }
}

• Live wins over a Moon, and either wins over a Window, which is then not used (the audit notes WINDOW_UNUSED or MOON_UNUSED). Neither needs a FirstYear.
• Such an event is live or not, and has no runs. Its Season, its <Id>_Live feature and calendar_live read it like any event, but nothing that counts runs sees it: no CALENDAR_ATTENDED credit, no past runs or yearly copies, no Almanac page, no season of its own on Records, and no calendar spawn rides it. A world spawn's own MoonPhaseRange follows the moon instead.
• An event whose Live leads round a loop back to itself is never live.
• /zigcalendar status <event> shows what the server reads: the moon's phase now in that world, or each event it follows. /zigcalendar force on <event> makes it live until you clear it or the server restarts, force off stops it, and force clear hands it back to its moon or its events.

On an MMO Skill Tree server, /mmoconfig validate lists them under calendar, and a server started with ZIGGFREEDCOMMON_AUDIT_ON_BOOT=1 prints them at boot under [calendar] audit.

Titles

A title is a name you earn, from an achievement or a quest, and show beside your name in menus, on Records and on the party, queue and results screens. Titles never show over your head.

• Choosing one. Open the menu's Settings tab and pick the tile under Title, or, on an MMO Skill Tree server, the Titles tile at the Adventurer's Guide. Both open the title picker: your earned titles as tiles with a Show button, and Show none to take yours off. The tiles show only while the server offers a title.
• How many you have. The Title tile and the picker's Earned heading count the titles you have earned of the ones you can see, such as "2 of 5".
• Still to earn. Under the earned ones, the picker lists every title you have not earned yet and the achievement or quest that gives it, with your progress toward it. Press a line to open that achievement or quest in your book. When a title comes with collecting an achievement's or a quest's rewards and you have finished it but not collected them, the line tells you to collect it there. When more than one thing gives a title, the picker names a reward waiting to be collected first, then an achievement, then a quest.
• Your first title shows itself. When you earn a title while you show none, it goes up beside your name straight away, as if you had picked it. If you took your title off with Show none, a new one stays off until you pick it. The notice for a new title says where to choose it.
• Secret titles. A title can stay secret until you earn it: it is left off the "Not earned yet" list and out of the count until it is yours.
• Titles from older feats. An achievement you earned before it came with a title hands the title over the next time you log in. One that pays its title on collecting waits until you collect it.

Titles for server owners and pack authors

A title is a file, Server/ZiggfreedCommon/Titles/<Id>.json, with a Text group (TitleKey for its name, FlavorKey for its line in the picker), an Order in the picker, Enabled and Hidden. An achievement or a quest pays it with the Title reward kind: { "Kind": "Title", "Params": { "Title": "Hallows_Eve_Hallowed" } }.

mods/ziggfreedcommon/titles.json retunes a title by its id, leaf by leaf, and holds two server-wide switches:

{
  "$Chat": true,
  "$AutoShow": false,
  "Hallows_Eve_Hallowed": { "Hidden": true }
}

• "$Chat": true shows the title a player picked beside their name in chat as well. It is off unless you set it, and while it is on the picker says the title shows in chat. Another mod that formats chat itself is left alone.
• "$AutoShow": false stops a new title from showing by itself when a player shows none.
• "Hidden": true on a title makes it secret until earned. "Enabled": false hides it everywhere without taking it from anyone who earned it.

Admins grant and take titles with /zigtitle grant, revoke and list, and each takes a player who is offline, by name or by player id. An offline change waits and happens the next time that player logs in, with the same notice as any new title. A title an admin revokes comes back at the next login while the achievement that gave it still stands, so revoke the achievement to take it for good. Every player holds /zigtitle open, which opens their picker.

Content can ask about titles through two factors, each taking a title id as its Param: ziggfreedcommon:title_earned (1 once the player has earned it) and ziggfreedcommon:title_shown (1 while it is the title they show). A conversation option, a shop offer or a quest gated this way is saved for the players who hold the title:

"Requires": {
  "Factors": [ { "Factor": "ziggfreedcommon:title_earned", "Param": "Hallows_Eve_Hallowed", "Min": 1 } ]
}

A locked line reads "an earned title" or "a title shown beside your name" unless your pack names its own title in a Factors overlay (see Naming overlays). A conversation line, a menu tile or a character opens the picker with "Open": "Titles".

Gear sets

A gear set is a group of items that pays a bonus when you wear or hold enough of them together, such as the Hallowed set from Seasons of Orbis. Putting on a piece shows a notice with your count against the full set ("1/2"), and each bonus that comes on names itself and the next one still ahead.

The set on your buff bar. While a bonus of a set you wear is on, the set shows one icon beside your other effects, with its name when you hover it. The icon stays after you log back in, change worlds or respawn, and goes when the bonus does.

A set is one file, Server/ZiggfreedCommon/GearSets/<Set_Id>.json: its Members (the item ids that count), a Text group naming it, and Bonuses, one entry per tier. A tier asks for Pieces, Armor, Held or Utility (every minimum it names must be met, and every tier that holds applies, so tiers stack) and pays StatModifiers, an optional look (Effect) and an optional buff bar icon (Badge):

{
  "Text": { "TitleKey": "gearset.hallows_eve_hallowed.title" },
  "Members": ["Hallows_Eve_Jack_Helm", "Hallows_Eve_Jack_Shield"],
  "Bonuses": [
    {
      "Armor": 1, "Utility": 1,
      "Text": { "TitleKey": "gearset.hallows_eve_hallowed.tier_full" },
      "Effect": "Hallows_Eve_Hallowed_Set",
      "Badge": "Hallows_Eve_Hallowed_Badge",
      "StatModifiers": { "Health": [ { "Amount": 10, "CalculationType": "Additive" } ] }
    }
  ]
}

• Badge is the effect whose icon the set shows on the buff bar. The highest tier on that names a Badge sets the icon, so a set that gives each tier its own changes icon as you put on more of it. A set that names none shows the library's own gear set icon.
• Joins adds a file to another pack's set instead of making a second set over the same pieces: "Joins": "Hallows_Eve_Hallowed". Its members join the set's, a tier asking exactly what one of the set's tiers asks joins that tier (its stats added, its line after the set's, in the same notice), and any other tier is added after the set's own. The set keeps its own name, and its look and icon wherever its tier names one (the joining file's fill in only where it names none). MMO Skill Tree joins the Hallowed set this way, adding its luck and Artillery damage, so you still see one set and one notice. A file whose set is not on the server adds nothing, and /mmoconfig validate says so.
• mods/ziggfreedcommon/gear-sets.json switches a set off ({"Hallows_Eve_Hallowed": {"Enabled": false}}) or retunes it by id. Bonuses replaces whole, so restate every tier you keep.
• A quest step or an achievement that asks for a set's tier (GEAR_SET_TIER, its target the set's id) calls the set by its Text.TitleKey: "Wear 5 pieces of the Hallowed Set". A step with its own TextKey keeps its own words.

Timed bonuses on the buff bar

A mod can put a timed bonus, such as a boost or a blessing, on the game's buff bar as an icon whose ring runs down with the time it has left. It stays up after you log back in, change worlds or respawn. A bonus with no icon of its own shows one of the library's two, one for your own bonuses and one for bonuses running for the whole server, and up to four of each show side by side. MMO Skill Tree's XP boosts show this way (see Boosts on the buff bar).

Bosses without a boss bar

Some of the base game's own bosses fight without a boss bar: the Voidtaken Grizzly and the Revenant Guardian (the Skeleton Elite). Killing one counts as a boss fight won for the player who lands the killing blow, so a quest step, a bounty contract or an achievement that asks for boss fights counts it, and so does Records' Bosses Defeated. These fights show no notices as if a boss fight had started or been lost, and keep no tab under Records' Boss Fights.

The Feastmaster, the boss deep in the goblin Deepworks, is not one of them: it shows a boss bar, so its fight counts like any other boss fight, for everyone who took part. Its fight is Dungeon_Feastmaster_Encounter, the target MMO Skill Tree's Feastmaster achievements and the Bounty Pack's Feastmaster contract count. The Gobliterator, the war machine at the bottom of the Deepworks, fights the same way, as Goblin_Gobliterator_Encounter, or Goblin_Gobliterator_Encounter_Hard with Hard Mode switched on at the button in its arena.

The library ships a binding row for each of the three Deepworks fights under Server/ZiggfreedCommon/Encounters/, so each keeps its records on Records' Boss Fights under the game's own name (Feastmaster, Gobliterator MkIIII, Gobliterator MkIIII Final). The rows only name the fight and its boss, and the hard one labels its runs hard for a step or achievement that asks for the hard fight; nothing else changes, so the fights play as the game made them. Switch one off with Enabled false or from mods/ziggfreedcommon/encounters.json.

Each boss without a boss bar is a rule file under Server/ZiggfreedCommon/EncounterRules/, and the library ships three:

// Server/ZiggfreedCommon/EncounterRules/Bear_Voidtaken.json
{
  "Match": { "Role": "Bear_Voidtaken" },
  "NameKey": "server.npcRoles.Bear_Voidtaken.name"
}

• Match.Role is the creature's role id, matched exactly with case ignored, so a copy of the creature under another role id never counts. NameKey names the fight, here with the game's own name for the creature. Enabled (true unless set) and Parent work as in any shared file.
• A step counting one of these fights names the role id as its target (Bear_Voidtaken, Skeleton_Elite_Phase_2) under ENCOUNTER_DEFEATED or ENCOUNTER_ATTEMPT; a step with no target counts these and scripted boss fights alike. The Feastmaster's own fight is a scripted one with a boss bar, so a step for it names Dungeon_Feastmaster_Encounter.
• The Revenant Guardian's rule names its second phase, which the fight always ends in, so each fight counts once. One that dies in a single blow from above a fifth of its health skips that phase and counts nothing.
• The third file, Goblin_Feastmaster.json, names the Feastmaster's role, Dungeon_Feastmaster_Boss. It counts only a Feastmaster killed outside its fight (one spawned on its own, with no fight around it), for the player who lands the killing blow, so a fight is never counted twice. It keeps its old file name, so an override under goblin_feastmaster still reaches it.
• mods/ziggfreedcommon/encounter-rules.json switches a rule off by its id in lower case ({"bear_voidtaken": {"Enabled": false}}), and the kill then counts as a kill and nothing more. /zigencounter reload reads it again, and /zigencounter validate reports a rule with no role or a role the game does not have.

Waves of adds in a boss fight

From CommonLib 2.5.0 the library ships two encounter macros under Server/EncounterManager/Macros/ that a fight's script references, so a boss can wait behind waves of adds, or call more in as the fight goes on. Seasons of Orbis's hard ride uses both: the Headless Horseman rises only after three waves of Jack Skeletons and Jack Archers, and at 80, 60, 40 and 20 percent of his health his pumpkins hatch five Pumpkin Fiends, with two more Jack Archers beside them.

• Zc_Wave_Rise raises one wave now, with the game's own Spawn action, so a mod that scales spawned creatures scales them too. Two rows rise from the script's entity toward the way it faces: NearCount of Role spread across NearAngle degrees NearDistance blocks out, and FarCount of FarRole across FarAngle degrees FarDistance blocks out. A spot that is not open floor is skipped, so check each spot in the arena, and give FarRole the near row's role for a wave of one kind. Then it sends Signal (zc:wave, or zc:wave:<label>), which the library counts as one of the run's waves, and when Moment names a feedback moment, each member is shown it with the wave's number as wave.
• Zc_Wave_Chain runs Waves of those, one after another. A player coming within PlayerRange of the script's entity starts Delay (long enough for an intro camera to end); then the first wave rises. A wave is beaten once one of its creatures has been seen and none of Groups is left alive within Range, or after WatchSeconds if none is ever seen, so a spawn that fails never holds the fight. Gap seconds later the next one rises. While the chain runs it holds PendingFlag, so a boss gated on that flag rises once the chain is done, and DoneFlag goes up at the end. A player who falls mid-wave comes back to the same wave.

{ "Reference": "Zc_Wave_Chain",
  "Modify": {
    "Role": "Hallows_Eve_Jack_Skeleton", "FarRole": "Hallows_Eve_Jack_Skeleton_Archer",
    "Waves": 3,
    "NearCount": [3, 3], "NearAngle": 90, "NearDistance": [7, 7],
    "FarCount": [2, 2], "FarAngle": 37, "FarDistance": [19, 19],
    "Groups": ["Hallows_Eve_Horseman_Adds_Group"],
    "Range": 80, "PlayerRange": 80, "Delay": [8, 8], "Gap": [4, 4],
    "PendingFlag": "Orbis_Boss_Guards_Pending", "DoneFlag": "Orbis_Boss_Waves_Done"
  } }

• The chain counts waves with the library's own reading of the run, ziggfreedcommon:encounter_waves (every zc:wave beat the run has heard), so run it as the fight's first waves, before any other wave beat, and keep its Signal a wave beat. It fails open rather than looping: a script the library keeps no run for ends the chain after its first wave, so the boss still rises.
• Every flag and timer is named in the macro's parameters, so give each chain in a script its own names. A DoneFlag nothing clears keeps the chain beaten through every reset of the fight, which is how the Horseman's waves stay beaten after a wipe on him. To raise the chain again, clear its DoneFlag, WaitingFlag, UpFlag, SeenFlag and ClearedFlag.
• Every feedback moment a fight shows now carries wave, the waves the run has raised so far, beside its other values (see Feedback).

A binding row can also let a companion mod scale the boss itself, with Scale.Companion: see Bosses that grow with their fight. A won fight's chest is the binding row's Spoils: see A boss fight's chest.

Records

The menu's Records tab, which ranks every player on the server, is the library's too: Combat, Gathering, Adventure, Boss Fights and Renown over All Time, This Week, This Month and each season, with MMO Skill Tree adding its Skills tab. Its settings are in mods/ziggfreedcommon/stats.json. Everything about it is on Records.

Authored feedback moments

The moments the server celebrates are authored JSON rather than hard-wired text. A moment file carries four independent groups - an on-screen toast, a server-wide broadcast, a sound, and a console command - over one line shape of a translation key, the values that fill its blanks, and a colour.

The library ships a plain, neutral file for each moment it fires, from a quest objective moving to a new rank with a reputation, so a bare server gets a notice and a jingle out of the box. MMO Skill Tree ships its own file for some of the quest and achievement moments under the library's names (a pack that depends on the library loads after it, so the MMO's wording wins), plus Rare_Find, a rare loot pull (a roll that named a Cue), which is the MMO's own. A server owner overrides any of them by name the same way, and can add a broadcast or a console command to a moment that did not have one. Every server, with or without the MMO, gets the same toast and sound for the same action: collecting a quest's or an achievement's reward lists what it paid and plays the legendary chest; a conversation line or an item that pays out on use shows "Rewards received." with what it handed over and the pickup sound; a purchase at a shop plays coins; and opening a reward chest plays one sound, grander with the rarest reward inside (Reward_Chest_Opened). Which quest and achievement toasts a player sees is their own notification level on the menu's Settings tab, and a quest showing on their quest tracker draws no corner toast at all. See Feedback & Combat Text.

The placed-block ledger

One ledger records what a player put down, and everything reads it: XP, statistics, quest progress and achievement progress alike. Place a block and break it again and it credits nothing, anywhere. The ledger file is mods/ziggfreedcommon/placed-blocks.json, a runtime store rather than something you edit; the four knobs that steer it stay in the MMO's own skill-config.json. Details: Anti-Exploit Features.

Where shared content lives

A shared type is a folder under Server/ZiggfreedCommon/. The filename is the content's name, a namespace folder keeps one pack's files apart from another's, and precedence is the ordinary built-in defaults, then packs, then your owner file. Files reuse each other with a top-level Parent, which merges field by field rather than replacing wholesale.

Server/ZiggfreedCommon/<Type>/<Namespace>/<Name>.json

Any of these folders lives inside a content pack: a folder with a manifest carrying "IncludesAssetPack": true, zipped with forward-slash entries and dropped in Mods/. See Building the zip.

The library carries a few more folders for other mods that use it; the ones above are the ones an MMO Skill Tree server meets. The MMO's own asset folders under Server/MMOSkillTree/ (abilities, bonus drops, skill trees, custom skills, and the rest) are unchanged.

Files you can edit

The library generates its own folder, mods/ziggfreedcommon/, beside mods/mmoskilltree/. Most of what is there is yours to edit; the few runtime stores the server keeps for itself say so in the table.

An editable one overrides content by name, one field at a time. Switching a storefront or a board off is {"<name>": {"Enabled": false}}; a name nothing ships is simply a new entry. A runtime store is not an override file and has no override semantics: back it up with the world, do not hand-edit it.

The Almanac's server totals

Each tile on a season's Almanac page shows the whole server's number beside the player's own ("8,431 on this server"), for the year the player is reading or for every season. The library keeps those totals in almanac-server-tallies.json, a runtime store it writes for itself, in mods/ziggfreedcommon/ with the library's other files.

• What writes it. Every time a player's Almanac record counts a tally, the same count is added to the server's total, a taking-part included (once per player per season). The file is written a few seconds after a count, together with every count made in between, and once more when the server stops, so nothing counted is lost at a restart. The write before it is kept beside it as almanac-server-tallies.json.bak; a file that will not read falls back to the .bak, then to empty, with a line in the log.
• What is in it. Counts only, keyed by season and tally (hallows_eve/ghouls_felled for every season, hallows_eve@2026/ghouls_felled for one year). It names no player.
• Do not edit it. The server holds the totals in memory and writes them back on the next count, so an edit made while it runs is lost. Back it up with the world.
• Resetting it. Nothing resets it on its own, and no command does. To start the server's totals over, stop the server and delete almanac-server-tallies.json and its .bak. Players' own tallies are kept on each player and are not touched. Switching the Almanac off ("$Enabled": false in almanac.json) stops the counting and keeps the file.

The MMO-side files that still win

Moving the engines did not move your existing achievement overrides. These stay in mods/mmoskilltree/ and still take precedence per name over anything a pack or the jar ships:

• achievements/ - the same for an achievement, plus point-milestones.json
• bonus-drops.json - see Bonus Drops

quests/ is not in this list any more: on the first start after 1.6.1 every file there is rewritten into mods/ziggfreedcommon/quests/, one shared-shape file per quest named after the quest id, the original renamed .legacy, and the old folder is never read again. See Quests: the older shape.

dialogues.json is not in this list: it is retired in 1.6.0, renamed in place to .legacy on the first start after upgrading with one boot warning, never read and nothing carried across. Its replacement, mods/ziggfreedcommon/dialogues.json, is one of the editable files above.

Commands the library registers

The library's command families are in the table below. The two an admin reaches for most are /zigcommerce for the economy and /zigprogress for quests, achievements and dialogue memories, each with the MMO's own aliases named beside it; /zigtitle grants and takes titles, and /zigstats looks up a player's stats. /zigdungeon lists the dungeons and the copies open now, closes a copy and takes you into a dungeon yourself (see Authoring Dungeons), /zigclaims give puts a loot table's roll in a player's Claims and /zigclaims chest stands a reward chest beside a player to try one (see Claims), and /zigcalendar shows and forces the calendar's events (see Calendar events).

Every player also holds a few that open a screen: /ziggui opens the shared menu (on an MMO Skill Tree server it lands on your skills, the same as /xp), /zighud opens the menu's Settings tab, /zigalmanac open opens the Almanac, /zigtitle open opens the title picker, /zigleaderboard encounter opens Records' Boss Fights, and /zigparty opens your party, with invite, accept and leave beside it.

/zigcommerce

The economy admin family. MMO Skill Tree's /mmoshop, /mmobounty and /mmocurrency are thin aliases that call straight through to it, so either spelling does the same thing to the same data.

# Audit every wallet, storefront, pool, board and contract on the server
/zigcommerce validate

# What wallets exist, and what each one is called
/zigcommerce wallets

# What one storefront is offering right now
/zigcommerce shops --shop=General

# What one board is offering, and when it rotates next
/zigcommerce boards --board=Daily

# What a player holds, has bought this period, and has rerolled
/zigcommerce show --player=Steve

# Hand out, take away, or set a balance outright
/zigcommerce give --player=Steve --currency=Bounty_Token --amount=250
/zigcommerce take --player=Steve --currency=Bounty_Token --amount=50
/zigcommerce set  --player=Steve --currency=Bounty_Token --amount=0

# Give a player their purchase limits or their reroll allowance back
/zigcommerce resetlimits --player=Steve
/zigcommerce resetrerolls --player=Steve

• Permission nodes: ziggfreed.ziggfreedcommon.command.zigcommerce for the family and ziggfreed.ziggfreedcommon.command.zigcommerce.<verb> per verb. A verb needs both. Nobody holds either until you grant it, and the console holds everything.
• Per-player verbs need the player online. Their economy state lives on their own character, so an edit while they are away has nowhere to land.
• There is deliberately no "rotate this board now". What a rotating pool shows is worked out from its name, its cadence and the clock with no stored schedule, so every player sees the same shelf and a restart shows what was there before. Clearing a player's rerolls is the real fix underneath that wish: their shelf goes back to the shared draw and their allowance for the period comes back.

/zigprogress

The progression admin family, over the one shared quest and achievement runtime: what the catalogue holds, where one player stands, and the few things an admin puts right by hand. It has three nested groups, quest, achievement and memory, plus reload. MMO Skill Tree's /mmoquestadmin, /quest and /mmoachadmin are aliases over it that keep their own names, arguments and permission gates; either spelling drives the same engine, so a quest given or an achievement unlocked from here pays out, toasts and announces exactly as an earned one does. What the aliases keep that this family deliberately has not got: /mmoquestadmin reload (re-lays the older pack quest layer, then the same republish of the shared store, owner folder included), /mmoquestadmin list (the MMO's category view), the offline half of /mmoquestadmin complete (the reward spools until the player next connects), and /mmoachadmin reset's release of the server-firsts a player won.

# The merged catalogue, and one player's log (the player must be online)
/zigprogress quest list [--tag=<tag>]
/zigprogress quest status --player=Steve [--quest=<id>]

# Start, close out, or wipe a quest for a player
/zigprogress quest give --quest=<id> --player=Steve      # or --everyone (every world)
/zigprogress quest complete --quest=<id> --player=Steve
/zigprogress quest reset --quest=<id|all> --player=Steve  # a wipe; 'all' also clears quest memories

# The player-side moves, from the console or on somebody's behalf
/zigprogress quest accept|claim|abandon --quest=<id> --player=Steve

# Achievements
/zigprogress achievement list [--tag=<tag>]
/zigprogress achievement status --player=Steve
/zigprogress achievement give --achievement=<id> --player=Steve
/zigprogress achievement claim --achievement=<id|all> --player=Steve
/zigprogress achievement reset --achievement=<id|all> --player=Steve

# Forget everything every conversation remembers about a player
/zigprogress memory forget --player=Steve

# Fold the shared quest and achievement assets again and publish them
/zigprogress reload

• Permission nodes are derived from the names: ziggfreed.ziggfreedcommon.command.zigprogress for the family, .zigprogress.<group> for a group and .zigprogress.<group>.<verb> for a verb, a verb needing all of its ancestors. Nobody holds any of them until you grant it, and the console holds everything.
• Per-player verbs need the player online. Progress lives on the player's own character. That is also why quest complete has no offline form here: the MMO alias keeps that half, because only the MMO keeps the directory of everyone who has ever connected.
• quest reset is a wipe. It drops the completion record too, and --quest=all also clears what conversations remember about quests; a greeting a character remembers is not quest progress, which is what memory forget is for.
• achievement reset cannot release a server-first the player won. It wipes the record and says the claim is still recorded; /mmoachadmin reset releases it as well.
• Everything it says is translated in all 9 languages, in ziggfreedcommon.progression.admin.lang.

/mmonpc

Manages placed NPCs live, writing to the placements owner file:

/mmonpc list                       # every placement, and whether it is on
/mmonpc disable --arg1=Mmo_Hub     # switch one off (the NPC standing there despawns)
/mmonpc disable --arg1=*           # switch them all off
/mmonpc enable  --arg1=Mmo_Hub     # back on
/mmonpc reconcile                  # sweep now, ignoring the usual debounce
/mmonpc reconcile --arg1=default   # sweep one world
/mmonpc list --arg1=structures          # the structure-marker sightings recorded here
/mmonpc list --arg1=markers             # the marker entities actually live right now
/mmonpc list --arg1=channels            # which interaction destinations are registered

/mmomigrate

Reports what on your server still speaks a retired format, and converts the owner files that can be converted safely.

/mmomigrate                                  # scan everything, change nothing
/mmomigrate --action=owner                   # what could be converted
/mmomigrate --action=owner --confirm=yes     # actually convert, with a backup first
/mmomigrate --action=pack                    # what your installed packs still carry
/mmomigrate --action=report                  # the newest report's path and counts

An owner quests/ file not yet converted is reported as one the server handles on its next start, its .legacy leftover as one it already did, and a pack's older Server/MMOSkillTree/Quests/ file as converted at load. Content packs are never rewritten in game; the web Migration Converter handles those.

Translation keys and the filename rule

The library ships its own files, in all 9 languages:

Keys a pack or a server owner can answer

Some names are looked up by convention, so authoring the key is all it takes to give something a proper name in every language:

For a shelf or a band the ladder is: what the content itself authors, then your own key, then the library's neutral default, then the raw name. Character keys are matched exactly, so the capitalisation has to match the character's name as authored. More on all of this: Localization.

The tracked-quest HUD

The in-world panel of a player's pinned quests is the library's. It is attached to every player when they are ready, and it repaints on the quest engine's own events (a pin or unpin, an accept, an objective moving, a completion, a claim, an abandon) rather than on a timer, reading the same titles and objective lines the quest log does. It looks exactly as it did. Each player shows or hides it, and picks one of the spots offered to it, on the menu's Settings tab (/mmohud show|hide quest flips the same switch), and mods/ziggfreedcommon/player-settings.json sets what a player starts with or locks a choice for everyone. What stays the MMO's is the server's side of it: where it sits for a player who has not picked a spot and whether it is on at all (/mmoconfig questhud, the admin dashboard, hud-layout.json), plus a world's own HUD rule. See Quest tracking.

The bar panels

A value that keeps moving belongs on a bar, not on the corner feed. The library draws two panels of progress bars for every player: the World bars (players see them as "XP and reputation gains"), top-right as shipped, where the MMO puts a skill's XP the moment it gains (the gain on top, the fill to the next level underneath, the level at each end) and the library puts a reputation's standing (its name and picture with the gain, the fill through the rank held; the rank itself is on the Reputation tab and the rank-up notice), and the Activity ledger ("Crafting progress") in the top-left column, where a work station puts the run's own rows (skill XP, every stack it handed over, a gold row per lucky find, the run itself) and holds them until the worker steps away. A row exists because a mod reported a movement; nothing is authored for one, so a skill a pack or a server owner added gets a bar like any other.

Where a panel sits is a spot, one file under Server/ZiggfreedCommon/HudSpots/ naming a corner, offsets and how the rows spread there (Top_Left, Top_Right and Bottom_Left ship for the bars; a pack adds one by dropping a file, and every picker offers it). The quest tracker takes spots too, but only one that lists Quest_Tracker in its Panels: Quest_Tracker_Right and Quest_Tracker_Left ship. A panel names its spot in Server/ZiggfreedCommon/HudPanels/, and a server owner re-tunes either in mods/ziggfreedcommon/hud-panels.json or hud-spots.json. Every player may show, hide or move each display and the quest tracker for themselves on the menu's Settings tab (plain /zighud opens it). A panel's Player group, and mods/ziggfreedcommon/player-settings.json for the tracker and the notification level, set what a player starts with, and Locked fixes a choice for everyone: it leaves the Settings tab, and each player's own choice comes back when you lift the lock. The HUD settings page is the server's layout, opened from a Settings tile for admins or the admin HUD page's Bar Panels button, and writes the owner file for you; /zighud place|hide|show|default drives the same choices from the command line, and refuses one the server has locked. A single row is re-tuned by id in Server/ZiggfreedCommon/HudRows/, which is optional: the library ships no row file.

Related

• Companion Mods & Content Packs - installing it, and load order
• Authoring Dungeons - dungeons for pack authors, new in CommonLib 2.4.0
• Claims for mod authors - the Claims tab, boss Claims, reward chests and diminishing returns
• Configuration - the MMO's own files
• Content pack asset types - the full folder reference for authors
• Troubleshooting - raw keys, empty shops, files that stopped being read