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, the authored feedback moments and their neutral defaults, the in-world tracked-quest HUD, shared loot tables, and the placed-block ledger.

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, 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, so a first-visit line 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.

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.
• 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.

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.

Eight moments fire today: a quest objective moving, a quest completed, a quest parked (its reward waiting to be collected), a quest's reward collected, an achievement unlocked, an achievement's reward collected, the note when a server-first claim is lost, and a rare loot pull (a roll that named a Cue). The library ships a plain, neutral file for the first seven, so a bare server gets a notice and a jingle out of the box; the MMO jar ships its own file for each of the eight - seven under the library's names (a pack that depends on the library loads after it, so the MMO's wording wins) plus Rare_Find, 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. A player's own quest-notification setting still decides which of the personal toasts they see. 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/. Six files and one folder there are yours to edit; two are runtime stores the server keeps for itself.

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 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 six editable files above.

Commands the library registers

Two families: /zigcommerce for the economy and /zigprogress for quests, achievements and dialogue memories. The MMO's own aliases over each are named 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. What stays the MMO's is the policy around it: where it sits and whether it is on at all (/mmoconfig questhud, the admin dashboard, hud-layout.json), and whether one player wants it (/mmohud show|hide quest, 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, bottom-left by default, 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 Activity ledgerin 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/HudBarPlacements/ naming a corner, offsets and how the rows spread there (TopLeft, TopRight and BottomLeft ship; a pack adds one by dropping a file, and every picker offers it). A panel names its spot in Server/ZiggfreedCommon/HudBarPanels/, and a server owner re-tunes either in mods/ziggfreedcommon/hud-bar-panels.json or hud-bar-placements.json. Every player may pick another offered spot for themselves, hide one panel, or hide them all: the MMO's Settings menu has a HUD bars button that opens the library's HUD settings page on its Mine tab, the admin HUD page's Bar Panels button opens the same page on its Server tab (which writes the owner file for you), and /zighud open|place|hide|show|default drives the same switches from the console. A single row is re-tuned by id in Server/ZiggfreedCommon/HudBars/, which is optional: the library ships no row file.

Related

• Companion Mods & Content Packs - installing it, and load order
• 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