Shared Schemas

Quests, achievements, contracts, offers, storefronts, boards, wallets, NPC placements, conversations and mastery nodes all reuse the same handful of small sub-schemas instead of each rolling its own gate / price / reward / objective shape. This page documents each one, once. The per-type authoring pages (Quests & Bounties, Achievements, Masteries, Shops) link back here instead of repeating the tables.

The one Requires block

There is one requirement vocabulary on this server, and every gated surface speaks it: a quest, an achievement, a contract, an offer, a storefront, a wallet's visibility, an NPC placement, a conversation option, a board's per-band accept gate, a mastery node, a class advancement. A gate that works on one works on the next.

"Requires": {
  "Quests": ["intro_miner"],
  "Permission": "myserver.chapter2",
  "Factors": [ { "Factor": "mmoskilltree:feature", "Param": "taming", "Min": 1 },
               { "Factor": "hytale:stat", "Param": "MMO_TotalLevel", "Min": 50 } ],
  "AnyOf": [ { "Quests": ["route_a"] }, { "Quests": ["route_b"] } ]
}

Everything at the top level must pass, every AllOf group must pass, at least one AnyOf group must pass, and no Not group may pass. An absent block asks for nothing. Nesting stops at one level of grouping on purpose: a requirement that genuinely needs more belongs in a registered Custom kind.

Factor spellings

A level is not a field of its own - it is a bound on a named reading, which is what lets one spelling serve every mod on the server.

The portable hytale: readings mean the same thing in any mod, so a pack can gate on them without knowing which mods a server runs: hytale:stat (any registered stat channel), hytale:permission, hytale:held_item, hytale:held_tag, hytale:tool_power, hytale:tool_tier, hytale:tool_durability_percent, hytale:tool_quality, hytale:tool_item_level. The optional MMO Mob Scaling companion adds mmomobscaling:mob_rarity_tier, mob_rarity, mob_affix, mob_difficulty and region_power.

What a locked surface tells the player

A locked detail panel lists every unmet requirement, not just the first one, so somebody planning a long-term goal sees the whole picture. Each one is worded for its kind: a skill level ("Requires Mining level 40 (currently 22)"), a total level, a combat level, a permission, a quest to complete, an achievement to unlock, a feature that is off, a mastery node to own, and a plain line for a condition that is blocking because it passes (a Not group). Several routes in read as one line - "Unlocked by: A or B" - because they are alternatives, not a list of things to go and do.

Naming overlays: how a locked line reads

The words a locked surface prints for a factor are content too. A Server/ZiggfreedCommon/Factors/<Id>.json file is a naming overlay: it changes only how a requirement on one factor is worded to the player, never what the gate checks. The jar ships overlays for the skill-level, feature and mastery-node wordings, and a pack can ship its own overlay on any factor, including one somebody else registered, because overlays compose.

{
  "Factor": "hytale:stat",
  "ParamNames": {
    "KeyPattern": "mmoskilltree.skill.{param}",
    "StripPrefix": "MMO_Level_",
    "Case": "Lower",
    "WrapKey": "mmoskilltree.factor.skill_level",
    "Keys": {
      "MMO_CombatLevel": "mmoskilltree.factor.combat_level",
      "MMO_TotalLevel": "mmoskilltree.factor.total_level",
      "MMO_HighestSkillLevel": "mmoskilltree.factor.highest_skill_level"
    }
  }
}

• Factor names the factor id the overlay words.
• Text.TitleKey is the factor's own display name, used when nothing more specific resolves.
• ParamNames turns the condition's Param into a player-facing name: Keys maps exact params to keys; KeyPattern composes a key from the param after StripPrefix / StripThrough (drop everything through a separator) and Case folding; WrapKey wraps the resolved name in a phrase ("{0} level").
• A pattern whose resolved key is not shipped is skipped, falling back to the factor's own title - so an overlay can never print a raw key.

The practical payoff for a pack: a custom skill joins the level phrasing automatically the moment its pack ships a mmoskilltree.skill.<id> lang key, and a pack shipping its own mastery nodes (or a factor of its own) words its lock lines by dropping one overlay file beside them - no Java, and no per-mod lock-line renderer anywhere.

Where the block is authored

Damage schools

The 9 canonical damage-school ids, referenced by an ability's Cause and by the gear/mastery MMO_Bonus_<School> / MMO_BonusFlat_<School> / MMO_SchoolResist_<School> channels. Documented once here; Abilities and Gear stats link back to this roster rather than each keeping their own list.

Envelope vs. body casing (the older payload types)

The shared library types and every structured MMO type are authored in PascalCase from top to bottom, and the file is the asset. That includes mastery tracks and classes, which became structured types in 1.6.0. The remaining raw-Payload types - the older quest / achievement / dialogue shapes, and the per-pack map types (XP maps, mob-kill XP, item and action requirements, boost templates, command rewards) - still carry two casing rules in one file:

• The asset envelope (Name, Payload) is PascalCase - the codec throws at server start if a key does not start upper-case.
• The Payload body (id, displayName, objectives,rewards, ...) is authored in lowerCamelCase by convention. Field keys are read case-insensitively, so PascalCase body keys also parse, but do not mix conventions within one file.

Cost (price object)

There is one price spelling in the library, and everything that charges uses it: an offer, a shelf's or a board's reroll, anything else that takes payment.

"Cost": {
  "Currencies": { "Bounty_Token": 150 },
  "Items": [ { "Item": "Ingredient_Lightning_Essence", "Count": 1 } ]
}

A mastery node's Cost is this group, in this spelling - mastery tracks are a structured PascalCase type, so there is no lowerCamelCase cost dialect to learn. A node with no Cost key is free, and there is no scalar cost + currencyId shorthand anywhere. Mastery adds one extension of its own on top: see Authoring Mastery Tracks.

Rewards: an open vocabulary

A reward is { "Kind": ..., "Params": { ... } }. Kind is an open registered id, not a fixed list - anything registered can be authored, including a kind a companion mod provides, and a kind nothing on this server registers is reported by /mmoconfig validate as an UNKNOWN_REWARD_KIND warning rather than silently dropped.

{ "Kind": "Mmo_Xp", "Params": { "Skill": "MINING", "Amount": "1400" } }

NameKey, DescriptionKey, Icon and QueueIfOffline apply to every kind. An empty Kind pays nothing out, deliberately: it lets a generator row leave a reward slot unused without the table needing two shapes.

The two buckets: Auto and Claim

Every progression schema - a quest, an achievement, an achievement-point milestone, a board contract - pays through one Rewards group holding two lists of those rewards:

"Rewards": {
  "Auto": [
    { "Kind": "Mmo_Xp", "Params": { "Skill": "MINING", "Amount": "1400" } }
  ],
  "Claim": [
    { "Kind": "Currency", "Params": { "Currency": "bounty_token", "Amount": "160" } },
    { "Kind": "Item", "Params": { "Item": "Ingredient_Bar_Copper", "Count": "8" } }
  ]
}

• Auto lands the instant the content settles - the moment the last step ticks over, wherever the player is standing.
• Claim waits to be collected, and it is the default: anything in Claim parks the quest or achievement as ready-to-collect. Content paying only Auto settles on the spot with nothing to collect. Put anything needing bag room in Claim, where the room can be checked before it is handed over.
• Each bucket is one leaf for inheritance: a file with a Parent that re-authors Claim replaces the inherited Claim list whole and keeps the inherited Auto untouched.

A shop offer is the one surface that keeps a bare list - "Rewards": [ ... ] with no buckets - because a purchase has no completion to wait for: it is handed over at the counter. Every other surface above takes the group.

Writing a reward kind of your own, with no Java

A kind is content too. Server/ZiggfreedCommon/RewardKinds/<Id>.json declares a parameter list and one console command line, and the filename IS the kind id - which is how this mod's own skill-tree kinds are defined.

{
  "Name": "Skill experience",
  "Params": {
    "Skill":  { "Required": true },
    "Amount": { "Required": true },
    "Silent": { "Default": "false" }
  },
  "Command": "mmoawardxp {player} {Skill} {Amount} --silent={Silent}",
  "Presentation": {
    "NameKey": "mmoskilltree.reward.xp.{Skill}",
    "Args": ["Amount"],
    "Icon": { "ByParam": "Skill", "Default": "Rock_Crystal_Iridescent_Small",
              "Values": { "MINING": "Tool_Pickaxe_Crude" } }
  }
}

• Command takes three substitutions, all case-sensitive: {player}, {uuid}, and {<ParamName>} for any parameter. A placeholder naming nothing is left standing rather than blanked, so a typo turns up in the command that ran, and the content audit reports it before a player ever earns the reward.
• Params entries carry two independent knobs: Required refuses to pay out, loudly, when a reward does not name that parameter; Default stands in when a reward leaves it out.
• Presentation says how the kind's rewards read where one is shown before it is handed over. NameKey is a template: each {Param} is replaced by that parameter's value, lower-cased. Args is an ordered list saying what fills the resolved key's {0}, {1}, ... blanks, with two rules: an entry that IS a parameter name binds that parameter's value (naming Amount binds the number itself, so a {0, number} blank groups its digits in each player's own locale - +2,000 rather than +2000), and an entry that is not a parameter name is read as a localization-key template and renders as a nested translated name. A key written with a {0, number} blank but no Args entry to fill it renders nothing in that slot, so author them together. Icon is {Default, ByParam, Values}; leave ByParam out for one picture on every reward of the kind.
• Kind files layer
  defaults<pack<owner
  like any other asset, and a file carrying "Parent": "<id>" starts from that kind, with Values merging per value - which is how a pack adding a skill of its own extends an icon table in three lines.

Shared loot tables

A Server/ZiggfreedCommon/Lootables/<Id>.json is a named, reusable table anything can point at: a mob drop, a lucky block break, a work station's rare find, a quest reward. Wherever a Loot block appears, "Lootables": ["<id>"] names one and "Rolls": [...] writes the same thing inline.

One roll

A roll is one conditional payout: a gate (Conditions, then Chance), a payoff (Grants, plus whatever Ladder floor the moment reached), and an optional celebration (Cue).

Bonus drops reuse this same roll shape inside each row's Loot block, so a table learned here reads the same there.

When the player is not there

One inventory-room probe runs before any claim charges, so a reward is never taken for granted and then lost. A grant owed to an offline player spools to mods/mmoskilltree/pending-rewards.json, keyed by player UUID only, and is handed over on their next connect. A grant with no resolvable UUID refuses loudly rather than queueing under a name that might belong to somebody else later.

Objectives and criteria

A step is the same shape in both stores, and both store it the same way: a quest keys its steps by id under Objectives, an achievement keys its criteria by id under Criteria. The key is what a player's progress is filed under and what a child under Parent re-tunes, so one criterion can be retuned by name while the rest are inherited, and re-authoring a file can never re-point a tally somebody is part-way through.

STAT_THRESHOLD and the level channels

STAT_THRESHOLD is a value-based step that completes when a native stat channel reaches Amount. Target is the channel id, so any registered channel - including one another mod writes - becomes a step with no new objective kind:

{ "Kind": "STAT_THRESHOLD", "Target": "MMO_TotalLevel", "Amount": 50 }

This mod mirrors four level readings onto that substrate - MMO_Level_<SKILLID>, MMO_CombatLevel, MMO_TotalLevel, MMO_HighestSkillLevel - and they are the same channels a Requires factor bound reads. REACH_LEVEL is the friendly form and keeps working unchanged: it resolves onto STAT_THRESHOLD at runtime, with TOTAL / ALL / GLOBAL reading the total channel, * / ANY / a blank target reading the highest, and anything else reading that skill's own channel. Both render as the same sentence on screen.

One matching rule, everywhere

A quest step, a contract step and an achievement criterion are all matched by the same rule, so a step that counts on one counts the same on the next:

• Targets compare case-insensitively, under every match mode. trork and Trork are the same quarry.
• An empty Target matches everything. That is how "kill anything in this zone" or "break any block" is written - pair it with a Zone or a Qualifier to narrow it.
• A missing Qualifier means any; an empty one accepts only an event carrying none; a non-empty one compares case-insensitively.
• MatchMode defaults to CONTAINS in both stores.

Objective kind roster

Only the "quest-producible" values below can advance a quest step; achievements accept every one of them.

See also

• Authoring Quests & Bounties - the shared quest file, boards and contracts.
• Authoring Achievements - the shared achievement file, categories and point milestones.
• Masteries - the mastery-only stat-sacrifice cost extension and the modifier grammar.
• Shops & Currencies - the surfaces that consume Cost and Rewards most heavily.
• ZiggfreedCommon - which engine reads which of these, and the owner files that override them.
• Publishing & Translations - packaging the folder these files live in as an installable .zip.