Authoring Reputations

A reputation is how a faction, or one character, thinks of a player. The number is Hytale's own: the game keeps one per player for each reputation, saves it with the character, and keeps it through death and across worlds. ZiggfreedCommon adds what the game leaves out: a name and a picture, a cap, its own word for each rank, standing for kills, gear that makes every gain bigger while it is worn, rewards past the top rank, the Reputation tab on the shared menu, a bar that moves with standing, and a notice when a rank goes up.

Seasons of Orbis ships the first two, and both are quoted on this page: Old Jack's Favor, standing with one character, and the Hallowed (id Hallows_Eve_Hallowed), a reputation with no characters in it.

Where the files go

One reputation is up to four files under Server/, and only the reputation group is required.

MyFactionPack/
├── manifest.json                                      # "IncludesAssetPack": true
└── Server/
    ├── NPC/Reputation/Groups/Your_Traders.json        # the reputation itself
    ├── NPC/Groups/Your_Traders.json                   # the characters whose attitude follows it
    ├── Entity/Stats/ReputationGain_Your_Traders.json  # the stat gear speeds gains on
    └── ZiggfreedCommon/Reputations/MyStudio/Your_Traders.json

A reputation group with no companion file still works: it reads by its id, with no cap and no kills, and the page names it by its id. The game reads reputation groups and ranks once at start, so a change to either needs a restart.

The reputation group

{
  "NPCGroups": [ "Hallows_Eve_Old_Jack" ],
  "InitialReputationValue": 0
}

The rank ladder

Every reputation on a server climbs one ladder of seven ranks, which the library ships in Server/NPC/Reputation/Ranks/. A rank runs from its floor up to the next rank's floor, and its attitude is how the characters in a reputation's NPC groups treat a player who holds it.

To retune a rank, ship a file of the same name (MinValue, MaxValue, Attitude) in your own pack. The ladder is server-wide, so a mod that ships ranks of its own changes every reputation, and the game logs a warning at start when two ranks overlap or leave a gap. A rank holds its MinValue and stops short of its MaxValue, so give each rank the next one's floor as its MaxValue. Each reputation can still call a rank by a name of its own: see Ranks below.

The companion file

{
  "Text": {
    "TitleKey": "reputation.hallows_eve_old_jack.name",
    "FlavorKey": "reputation.hallows_eve_old_jack.flavor"
  },
  "Icon": "Hallows_Eve_Jack_Helm",
  "Order": 10,
  "Cap": 21000,
  "Ranks": {
    "Neutral":  { "Name": "reputation.hallows_eve_old_jack.rank.neutral" },
    "Friendly": { "Name": "reputation.hallows_eve_old_jack.rank.friendly" },
    "Honored":  { "Name": "reputation.hallows_eve_old_jack.rank.honored" },
    "Revered":  { "Name": "reputation.hallows_eve_old_jack.rank.revered" },
    "Exalted":  { "Name": "reputation.hallows_eve_old_jack.rank.exalted" }
  },
  "Earn": {
    "Lines": [
      "reputation.hallows_eve_old_jack.earn.quests",
      "reputation.hallows_eve_old_jack.earn.board",
      "reputation.hallows_eve_old_jack.earn.talk",
      "reputation.hallows_eve_old_jack.earn.gear"
    ]
  }
}

Old Jack's favor stops at Exalted's floor, and his ranks read Stranger, Regular, Trusted, Confidant and Jack's Own. His four earn lines read "Do his errands and his daily jobs.", "Take contracts from his board.", "Stop by for a word once a day." and "Wear a Jack Helm, and everything you do for him earns more favor while you have it on." The Hallowed has no cap. It counts kills of the season's creatures and pays a loot table every 5,000 past Exalted:

{
  "Text": {
    "TitleKey": "reputation.hallows_eve_hallowed.name",
    "FlavorKey": "reputation.hallows_eve_hallowed.flavor"
  },
  "Icon": "Hallows_Eve_Hollow_Lantern",
  "Order": 20,
  "Kills": [
    { "NPCGroups": [ "Hallows_Eve_Event_Mobs" ], "Amount": 2 }
  ],
  "Beyond": {
    "Every": 5000,
    "Rewards": [ { "Kind": "Lootable", "Params": { "Lootable": "Hallows_Eve_Hallowed_Cache" } } ]
  },
  "Earn": {
    "Lines": [
      "reputation.hallows_eve_hallowed.earn.kills",
      "reputation.hallows_eve_hallowed.earn.jack",
      "reputation.hallows_eve_hallowed.earn.treats",
      "reputation.hallows_eve_hallowed.earn.gear"
    ]
  }
}

Gear that speeds gains

Gear never adds standing. It makes each gain bigger, by a percent, through two stats: the library's ReputationGain, which counts for every reputation, and ReputationGain_<Id>, which counts for one. The library ships the first. For gear that favors one reputation, ship the second yourself, with <Id> spelled as the reputation group's file name, a base Max of 0 and a Min of -100. The companion file needs no leaf for it: the library finds the stat by its name.

{
  "InitialValue": 0.0,
  "Min": -100.0,
  "Max": 0.0,
  "Shared": false,
  "HideFromTooltip": false
}

Give each item a modifier on the stat's Max, in whole percent points: 10 is +10%. The game applies and clears it as the item goes on and off. Armor names the stat in Armor.StatModifiers, a shield in Utility.StatModifiers, and a gear set's tier in its own.

"StatModifiers": {
  "ReputationGain_Hallows_Eve_Old_Jack": [ { "Amount": 10, "CalculationType": "Additive", "Target": "Max" } ]
}

The library adds the two stats together and multiplies every gain by that much, rounded, never to less than 1: with the Jack Helm on, a 250 reward pays 275. A kill, a quest, a contract, a daily line and a reward collected from a boss's chest or a dungeon's clear all count, and so does standing past the top rank. A loss is never changed, and the Cap cuts the gain after the boost. The total counts from -100% to +1,000%. The item's tooltip line reads the client.lang key itemTooltip.stats.<Stat> ("Old Jack's Favor Gain: 10%"), and the reputation's page ends How to earn on "Your gear raises what you earn here by 10%." while it is worn.

Earning standing

• Rewards. The Reputation reward kind moves standing by a whole Amount, negative to cost standing, anywhere a reward pays: a quest, a contract, a shop offer, an achievement, a loot table, a conversation line's Grant. In a reward list it reads "+250 Old Jack's Favor". See Rewards.
• Kills, through the companion's Kills table. The standing lands a moment after the kill. A row with a Season counts only while that calendar event runs, the same Season leaf shops, boards, quests and dungeons use, so a reputation can pay a little more during an event and go back to its usual rows when the event ends.
• A word each day. A Start beat with a daily Once can pay a little standing the first time each day a player stops to talk: see Beats that pay.

{ "Kind": "Reputation", "Params": { "Reputation": "Hallows_Eve_Old_Jack", "Amount": 250 } }

"Kills": [
  { "NPCGroups": [ "Your_Bandits" ], "Amount": 5 },
  { "NPCGroups": [ "Your_Night_Creatures" ], "Amount": 1, "Season": "Your_Event" }
]

Reading standing

Two readings join the shared factor vocabulary, so a Requires block, a conversation condition or a loot roll can ask about any reputation:

Each one fails closed: a reputation the server lacks or has switched off, a rank not on the ladder, or no live player answers nothing, and the gate stays shut. A player who has never touched a reputation reads its starting value. Write a Min on every condition. The worked spellings are on Shared Schemas.

"Requires": {
  "Factors": [
    { "Factor": "ziggfreedcommon:reputation_rank", "Param": "Hallows_Eve_Old_Jack/Honored", "Min": 1 }
  ]
}

How a lock reads

A lock on a rank names the rank and the reputation by itself: the rank's name (its Ranks name, else the library's word) with the reputation's own name, so a gate on Town_Guard/Honored reads "Requires Honored with Town Guard". A board slot, a contract and a shop offer all read it this way. A shop offer that asks for several things lists each on a line of its own, and one with more than one way in reads "Unlocked by:" with each way; hovering the offer, or pressing Buy, says the same. The generic line ("a rank with a reputation") reads only when the reputation names itself nowhere or the rank is not on its ladder.

To word a lock your own way, such as "Requires Trusted with Old Jack" in place of "Trusted with Old Jack's Favor", ship a naming overlay with a ParamNames.Keys entry for each exact Param you gate on, each pointing at a full lang key. An overlay entry is asked first and wins:

{
  "Factor": "ziggfreedcommon:reputation_rank",
  "ParamNames": {
    "Keys": {
      "Hallows_Eve_Old_Jack/Friendly": "hallowseve.progression.factor.hallows_eve_old_jack.friendly",
      "Hallows_Eve_Old_Jack/Honored": "hallowseve.progression.factor.hallows_eve_old_jack.honored"
    }
  }
}

Those two keys read "Regular with Old Jack" and "Trusted with Old Jack". A gate on a rank the overlay does not list reads the library's own line, the rank's name with the reputation's.

A step on a rank

The REPUTATION_RANK objective kind counts holding a rank: Target is the rank id and Qualifier the reputation id (leave it out to count any reputation). Every rank from the reputation's starting rank up to the one held is credited, at login and after every reward or kill, so a jump never misses a rank. Below the starting rank, only the ranks reached going down are credited. A quest step and an achievement's criterion both take it. Jack's Confidant in Seasons of Orbis is an achievement whose one criterion is reaching Revered with Old Jack:

"Criteria": {
  "reach-confidant": {
    "Kind": "REPUTATION_RANK",
    "Target": "Revered",
    "MatchMode": "EXACT",
    "Qualifier": "Hallows_Eve_Old_Jack",
    "Amount": 1,
    "TextKey": "objective.hallows_eve.jack_confidant"
  }
}

What a player sees

• The Reputation tab on the shared menu, once they have any standing with a reputation. A line at the top says what reputation is for, then one row per reputation they have met ("Who knows you"): its rank, and how far it is to the next rank or, past the top, to the next reward when the reputation pays one.
• The page of the one they pick: their rank and a bar toward the next one, the description whole, then How to earn (your Earn lines, and a last line with how much their gear raises or lowers each gain, while it does), Ranks (every rank from the starting one to the top, plus the one they hold if it is below the start, each with the standing it takes, what it opens and the achievement it earns with what that pays), Past the top rank when Beyond pays, with what is waiting and the Collect button, and Your standing (what they have earned and the most they can earn).
• What a rank opens is read from the content itself, with nothing to author: every shop offer and every board slot whose Requires asks for that rank, by its name and where it is ("Burning Jack Helm at Old Jack's Stall", "An extra Night Work contract at Old Jack's Board"). It lists them all year, so a seasonal stall that is packed away still shows what each rank holds.
• A bar on the World bars panel each time a reward or a kill out in the world moves their standing, beside the skill XP bars. It reads the reputation's name and picture alone with the gain, and fills through the rank held; the rank shows on the Reputation tab and in the rank-up notice.
• Standing earned inside a menu (collecting a reward, buying something, taking a quest that pays out at once or picking a line in a conversation) is listed in the notice that pops up in that menu, with the rest of what they got, such as "+250 Town Guard". When a reputation's Cap held part of it back, the notice shows the part they got. It does not play again as a bar once the menu closes, so the Settings tab has no "Reputation changes in menus" switch any more.
• A notice when a rank goes up during play: the Reputation_Rank feedback moment, which a pack or a server owner replaces by shipping a file of the same name. A fall raises no notice, and logging in raises none.

A conversation line or a placement opens the page through the Reputation destination: "Open": "Reputation" opens on the first reputation the player has met, and { "Type": "Reputation", "Reputation": "<Id>" } on that one. Old Jack's "How do we stand?" uses the second form.

Switching off and retuning

{ "$Enabled": false }                                    // every reputation off
{ "Hallows_Eve_Old_Jack": { "Cap": 9000 } }              // retune one, leaf by leaf
{ "Hallows_Eve_Hallowed": { "Enabled": false } }         // switch one off

A reputation switched off is gone from the server: its readings answer nothing, rewards naming it refuse to pay, and the page leaves it out. Nobody's standing is touched, so switching it back on picks up where every player left off. Hytale's own /reputation command sets a player's standing directly: every reading sees the new number, but the Cap does not apply and no bar, notice or Beyond reward follows.

Checking your work

The library audits every reputation at boot and logs its errors once, so a server without MMO Skill Tree still hears them. The whole audit, warnings included, runs at boot on a server started with the environment variable ZIGGFREEDCOMMON_AUDIT_ON_BOOT=1, under [reputation] audit beside the library's other passes, and each error is still printed once. On an MMO Skill Tree server, /mmoconfig validate lists the findings under reputation with the rest of the content audit.

The library's own words live in ziggfreedcommon.reputation.lang: the seven rank names, the generic factor names, the page, the bar and the notice. A reputation's name, description and rank names are keys in your own lang file.

See also

• Shared Schemas - the Reputation reward kind, the factor spellings and naming overlays.
• Beats that pay - a daily line that pays standing.
• A slot's own gate - a board posting that opens with standing.
• ZiggfreedCommon - what the library owns, and its owner files.