Model and feed reference

1  Overview

1.1 The pipeline

./afkj-parse build reads raw tables, joins them into a model, projects the model into the feed, and publishes the feed only if every gate passes. The source is this repo's extract output (out/raw/, the default) or an AFKJourneyData checkout (--source ../AFKJourneyData); both are described in Raw data §2.

A gate passes when it has no error finding; with --strict, warnings fail it too. A failed gate stops the stages after it, and the previous out/api/ and out/internal/ stay in place. The model dump is written as soon as the model exists, before its gate is judged, so a failed run still leaves a model to inspect. --limit N parses only the first N heroes and never writes the feed.

1.2 What each output is for

report.json also records lists (the resolved config.json hero lists), config {path, sha256}, and, when the feed was published, feed {out, generatedAt, sha256, internalSha256}.

The projection reproduces the output of afkj-data-viewer's scripts/export-api.ts (contract v1) exactly, plus a few game ids; section 8 records how that was verified before the viewer was retired and deleted. out/api/ is that projection in stargazer's vocabulary (section 3).

2  The model

2.1 Conventions

The model is plain dicts and lists, built by src/afkj_parse/model/. There is no types module: this section is the shape documentation. Field names are camelCase. The model is locale-independent: every piece of text is held as a LocalizedRef and resolved per locale only when the feed is built.

A LocalizedRef (model/refs.py) is one of:

Key semantics are in Raw data §5. Fields holding a ref end in Ref (nameRef, titleRef, descriptionRef, tipRef, …). Every key the model references is also recorded in a registry by the kind of record that holds it, so the model gate can check that each resolves (M7).

Numbers read from tables go through the viewer's num rule: a number stays, anything else becomes 0. Booleans such as isShow and isMelee are normalised to true/false.

2.2 The dump

write_dump (model/build.py) replaces out/build/model/ with:

The in-memory model is the same object: {season, heroes, artifacts, phantimals, charms, keywords, factions, buffs, controlEffects}. season is the live season's SeasonType (the highest online Season row above 100; 108 in build 14368).

// meta.json, build 14368
{ "source": { "kind": "extract", "label": "extract 1.6.11, build 14368", "gameVersion": "1.6.11",
              "dataBuild": 14368, "extractor": "0.2.0" },
  "season": 108, "heroCount": 131 }

2.3 Hero

One record per hero candidate (a playable Unit with an enable flag, or listed in forceParse), in unit-id order (model/heroes.py). The roster rules are in Raw data §8.3.

// heroes/rs.json (Lumont), skillSlots abridged
{ "codename": "rs", "unitId": 11, "nameRef": "89574582654232036", "titleRef": "8225152550786035586",
  "rarity": 1, "job": 1, "heroTagId": 2, "gender": "male", "seasonType": null, "damageType": "AD",
  "isMelee": true, "enabled": true, "script": "rs", "skillSlots": [ … ], "passiveBuffs": [ … ],
  "scriptBuffIds": [3, 1106, 1107, 1108, 1111, 1112] }

2.4 Skill slot

build_slots (model/skills.py) groups the partition's rows by (DisplaySlot || Slot, DisplayName) in first-seen order, then sorts the slots by displaySlot (stable, so ties keep first-seen order). What the slot numbers mean is in Raw data §9.1.

2.5 Skill level

The refinements come from ExclusiveHeroLevel (Raw data §12.3, §12.4). Refine 2 is the class Rivalry skill: the lowest EX level with ExtraSkill set names a row in the single Rivalry caster's partition. Refine 4 is the set of new PVP stats. Refine 1 and 3 are skipped, as the in-game UI skips them. Lumont's EX slot ends like this:

{ "skillId": 101, "skillLevel": 5, "isDev": false, "isShow": true,
  "descriptionRef": "17598539104553094781", "sArgs": [0.6, 8, 0.15, 0.03, 20, 0, …],
  "plusRatio": 0, "buffName": null, "buffId": null, "unlockAwakenLevel": 0, "refineTier": 2, "refineStatsAdded": [] },
{ "skillId": -1, "skillLevel": 6, "isDev": false, "isShow": true, "descriptionRef": null, "sArgs": [],
  "plusRatio": 0, "buffName": null, "buffId": null, "unlockAwakenLevel": 0, "refineTier": 4,
  "refineStatsAdded": [ {"code": "PVPRES", "value": 10}, {"code": "PVPBLOCK", "value": 15},
                        {"code": "PVPCritD", "value": 10} ] }

A typical hero has six kit slots, a few internal ones (the basic attack, per-skill "skill strength" rows, sub-triggers) and one special-modes slot. In build 14368 the 131 parsed heroes hold 775 kit, 752 internal and 120 special-modes slots.

2.6 Artifact

model/artifacts.py takes the six permanent spell artifacts (SeasonType 1 and FairyType 1) and every Fairy row of the live season. Each anchors on the first SkillID of its Fairy row in the leaderavatar caster (4009), then takes every row of that file sharing the anchor's (Slot, SkillName) (Raw data §14). The list is sorted pre-season first, then by fairyId.

2.7 Phantimal

model/phantimals.py takes exactly the units named by CampPet.CampPetUnitID whose skill file starts with camppet (Raw data §15). Only shown, non-dev rows are kept, grouped by DisplaySlot. The list is sorted by faction, then unit id.

2.8 Charms

model/charms.py reads GemSuit (hero, quality, SkillID = base*100 + level) against the gem caster (4022) and GemQuality (Raw data §16). Unlike the other parts, charms are one object:

2.9 Keywords and factions

// keywords.json                                        // factions.json
{ "weakest": { "key": "weakest",                        { "1": "10677098034559408920",
               "tipRef": "15060488439880168031" }, … }    "2": "8229542281409421451", … }

2.10 Buffs and control effects

model/buffs.py reads SkillBuff, SkillBuffUI and, when the source has it, HeroScripts (Raw data §10). buffs is {"<id>": record}, keyed by SkillBuff.ID, holding only the records some hero links, files by name or names in its script (1,158 of 3,616 in build 14368). controlEffects is {code: {labelRef, isBuff, popupType}}, one entry per SkillBuffUI row (17), keyed by BuffEffectName, with PopupText as the label.

A record holds raw fields only: no tags, marker or visibility classes, and no inferred targets.

Linking rules:

• Rows link by id. A kit or special-modes level links its record by BuffID, or, when the row has no id, by its Buff name if exactly one record has that name. Internal slots (dev and sub-trigger rows) link nothing. In build 14368, all 338 rows with a BuffID point at the record their Buff names, and 194 levels link a record.
• Records are keyed by id, not name. 30 SkillBuff names are shared by records that differ, e.g. rs_atk2_debuff (ids 1109 and 1110, with different ARM_x and MR_x).
• Passives are filed by name. A record named <codename>_… (the part before the first _, case-insensitive) that no row links is that hero's passive. This is a naming convention, not a fact.
• A passive's slot comes from the first token, in the order atk4 → EX, atk5 → EX, atk3, atk2, ult, awake (and awaken) → Awakening, mastery, imba → special-modes (4001), atk → basic (0), that starts a _ segment of the name after the codename. No token means hero-wide (displaySlot: null). In build 14368, 1,102 records are filed by name, 136 of them hero-wide.
• Scripts name buffs by id. A hero's scriptBuffIds are the HeroScripts settings of its script that name a buff: the name contains buff (BUFF_SETTING), is not a quantity (BUFF_QUANTITY), and the value is a SkillBuff id (Raw data §10.5). This is a fact: the script applies them. In build 14368 hero scripts name 885 records; 837 of the 1,102 filed by name are among them, and 14 records (shared ones such as common_taunt) are kept only because a script names them. Without the table, the list is empty and M17 notes it.

The builder reports a row whose buff is not in SkillBuff, or whose Buff name differs from its BuffID's record, as M17 warnings (section 6.1).

// buffs.json (model dump), one record          // controlEffects.json
"1701": { "id": 1701, "name": "rabbitbow_ult",    { "stun": { "labelRef": "8916278348205271970",
  "duration": 6, "isDot": false,                             "isBuff": false, "popupType": 14 }, … }
  "dotDmgType": null, "dotInterval": 0,
  "stats": { "ARM_x": -0.3 }, "controlEffects": [], "addSource": "owner", "canDispel": true,
  "maxStackTimes": 1, "shieldType": null, "clearOnDeath": true, "clearOnCasterDeath": false,
  "battleEndContinued": false, "hidePopup": false, "buffType": 0 }

3  The feed

The build projects every file once in the game's own vocabulary (feed/project.py, section 4), then feed/contract.py splits that projection into two trees. out/api/ is stargazer's contract, version 2: only what stargazer shows, under stargazer's names and encoding. out/internal/, beside it, keeps the game's identities, raw numbers and buff records for the diff and our tools. Nothing in out/api/ names a game key, code or id: the feed gate holds it to contract.SCHEMA (F14) and to the contract's name tables (F15).

3.1 Layout

out/api/                   stargazer's contract, version 2
  manifest.json
  <locale>/                one folder per locale, by its standard code (de, ja, ko, zh-tw …)
    skills.json            every hero, keyed by slug, with the glossary and the panel terms
    artifacts.json
    phantimals.json
    charms.json
  skillNumbers.json        what the skill panel shows per level, locale-independent (section 3.8)
out/internal/              the game's vocabulary, for the diff and the tools
  keys.json                every stargazer id and name in out/api/, mapped to the game's (section 3.9)
  buffs.json               the buff registry (section 3.10)
  skillNumbers.json        the game's raw numbers per level (section 3.11)
  en/skills.json           the English heroes as the game names them (section 3.12)

Files are written with two-space indentation. With build 14368, 16 locales and 129 heroes: 66 files in out/api/ (15 MB) and 4 in out/internal/ (2 MB). Each tree is replaced whole on publish, so no stale file survives. What contract.py turns into stargazer's vocabulary:

A glossary key, stat code or damage code with no entry in its table fails F15, and a marker or blank left unconverted fails F4, so nothing ships under its game name. Only glossary entries the exported text uses are exported (F15 checks that too).

3.2 manifest.json

{ "generatedAt": "2026-10-24T07:08:49.817Z",
  "locales": ["de", "en", "es", …, "zh", "zh-tw"],
  "localeNames": { "de": "Deutsch", "en": "English", …, "zh-tw": "繁體中文" },
  "heroCount": 129, "artifactCount": 18, "phantimalCount": 5, "charmCount": 19,
  "contractVersion": 2, "season": 8 }

generatedAt is UTC ISO 8601 with milliseconds, as JavaScript's toISOString() prints it. The data build the feed came from is in keys.json, not here.

3.3 _meta

Every locale file starts with _meta: generatedAt, locale, season and the file's count (heroCount, artifactCount, phantimalCount, charmCount). skills.json's also holds terms and keywords (section 4.5).

3.4 Heroes: skills.json

{_meta, heroes: {slug: entry}}, sorted by slug.

// en/skills.json, one hero, abridged
"lumont": { "slug": "lumont", "name": "Lumont", "title": "Benign Horn",
  "skills": {
    "ultimate": { "name": "Lumont's Charge",
      "levels": [ { "level": 1, "description": "… he deals {atk}[[240%]] damage to all adjacent enemies and
                    [[taunts|taunt]] them for [[3]]s. Lumont is [[unaffected|unaffected]] …" }, … ] },
    "ex": { "name": "Totem Slam", "levels": [ … ],
      "refinements": [
        { "tier": 2, "description": "In Rivalry Mode, when HP drops below [[60%]], reduces damage taken by [[15%]] …" },
        { "tier": 4, "description": "Refine 4: In Rivalry Mode, increases 10 Crit Resist, 15 Ranged DEF, 10 Crit DMG DEF." } ] },
    … } }

3.5 artifacts.json

{_meta, artifacts: {slug: entry}}, in model order (pre-season first, then by fairyId). slug, set and name are as in the model, with the name resolved; id and season are stargazer's (section 3.1); statBonuses is [{stat, value}] with stargazer's stats keys; levels is [{level, description}].

{ "slug": "awakening", "set": "pre-season", "name": "Awakening Spell", "id": 1, "season": 0,
  "statBonuses": [ {"stat": "atk", "value": 4.2}, {"stat": "phys-def", "value": 26.4}, … ],
  "levels": [ { "level": 1, "description": "[[5]]s after the battle starts, summons Radiant Life to restore
                [[3]] [[weakest]] allied heroes' max HP by [[7%]] every [[10]]s." }, … ] }

3.6 phantimals.json

{_meta, phantimals: {slug: entry}}, in model order: slug, name, faction (the faction's name in the locale), id, factions (stargazer's keys for every faction it counts for), damage, range (its attack range in tiles), season, and skills, [{name, levels: [{level, description}]}] ordered by DisplaySlot.

{ "slug": "wedge-of-matter", "name": "Wedge of Matter", "faction": "Celestial", "id": 5,
  "factions": ["hypogean", "celestial"], "damage": "magic", "range": 20, "season": 8, "skills": [ … ] }

3.7 charms.json

{_meta, tierNames, charms}. tierNames is the four resolved tier names (EN: Elite, Epic, Legendary, Mythic). charms is a list, not a map, in id order:

{ "id": "s8-19", "heroes": ["yamato-gabumon"],
  "tiers": [ "For every [[5]]s alive in battle, increases ATK by [[4%]] and Phys & Magic DEF by [[6%]], …", …3 more ] }

heroes is the sorted slugs of the charm's heroes, leaving out blocklisted ones. tiers is four descriptions; a missing one is "", which the gate rejects (F6). A charm keeps its number for the season unless the game puts a new charm before it; the diff warns when an existing charm's number changes (D6), since stargazer's charm tags are keyed by it.

3.8 skillNumbers.json (out/api/)

What the game's skill panel shows for each hero level, once for every locale:

{ "_meta": { "generatedAt": "…", "season": 8 },
  "heroes": { "eironn": { "initialEnergy": 200, "skills": {
      "ultimate": [ { "level": 1, "cooldown": 2, "initialCooldown": 0, "range": "global" }, … ], … } } } }

The levels are exactly those skills.json lists (F13). cooldown is left out when the skill has no timer, and initialCooldown with it; 0 stays, an instant skill. range is the tiles, "global" from 15 up, and absent when the row has none. initialEnergy is the hero's energy at battle start (startMp, 0 when unset).

3.9 keys.json

The map from out/api/'s ids and names back to the game's, for the diff and the tools:

{ "_meta": { "generatedAt": "…", "season": 8, "source": { "kind": "extract", "dataBuild": 14368 } },
  "heroes": { "lumont": { "codename": "rs", "unitId": 11 }, … },
  "artifacts": { "awakening": { "fairyId": 1 }, … },
  "phantimals": { "wedge-of-matter": { "codename": "…", "unitId": …, "campSlot": 5 }, … },
  "charms": { "s8-1": "ep8basic", …, "s8-19": "ep6liveUpgrade" },
  "keywords": { "unaffected": "uncontrol", … } }   // the 30 glossary keys the text uses

source.kind is extract or dump; dataBuild is the data build number, or null when unknown. tools/stargazer_tags.py charms() reads stargazer's charm files back into game names through it, and tools/battle_scripts.py takes codenames from it.

3.10 buffs.json

The buff registry for the heroes in the feed (feed/build.py _buffs, feed/project.py hero_buffs), in out/internal/. It is locale-independent apart from the control-effect labels, which are keyed by the game's locale codes. About 690 KB for build 14368.

• Slot keys are ultimate, skill2, skill3, mastery, ex, awakening, basic, special-modes, in that order, present only when the slot has something.
• attached (a fact) lists the shown feed levels that link a record: not dev, not hidden, not refinements, and honouring awakeningLv2Blocklist.
• inferredPassives and inferredHeroWide (a convention) are the hero's passiveBuffs, filed under the slot their name points to, or hero-wide when it points to none.
• scriptBuffs (a fact) are the hero's scriptBuffIds: the records its own battle script names. An inferred passive also listed there is confirmed by the hero's script. Empty on dump input.

Lyca (rabbitbow) shows why the file exists: rabbitbow_ult (id 1701), filed under her ultimate, carries stats {ARM_x: -0.3}, a 30% Phys DEF cut her text never states.

"heroes": { "lyca": { "codename": "rabbitbow",
  "slots": {
    "ultimate": { "attached": [ {"level": 1, "buffId": 1707}, …, {"level": 5, "buffId": 1707} ],
                  "inferredPassives": [1701] },
    "skill2":   { "attached": [ {"level": 1, "buffId": 1702}, … ], "inferredPassives": [1703, 1708] },
    "skill3":   { "attached": [], "inferredPassives": [1704, 1705] },
    "ex":       { "attached": [], "inferredPassives": [1706, 1709] } },
  "inferredHeroWide": [], "scriptBuffs": [1701] }, … },
"controlEffects": { "stun": { "isBuff": false, "popupType": 14, "label": { "en": "Stunned", "zh": "眩晕", … } }, … }

Build 14368: 129 heroes, 1,154 records, 17 control effects. 36 codes on records have no popup entry; they are script-internal, and F10 lists them as info.

3.11 skillNumbers.json (out/internal/)

Each skill level's cooldowns, energy and range as the game stores them, once for every locale (feed/project.py hero_numbers, artifact_numbers, phantimal_numbers); out/api/'s file (section 3.8) is derived from it. Each hero entry also carries the hero's energy from its Unit row (HERO_ENERGY): startMp (energy at battle start; 0 for 66 heroes, up to 1000 for three), baseMp (the maximum, 1000 for all) and victimMpCoef (a multiplier on the energy it gains when hit; 1 for most, from 0 to 2). About 630 KB for build 14368.

{ "_meta": { "schemaVersion": 1, "generatedAt": "…", "season": 108, "source": { … } },
  "heroes": { "eironn": { "codename": "…", "startMp": 200, "baseMp": 1000, "victimMpCoef": 1.2, "skills": {
      "skill2": [ { "level": 1, "cd": 7, "initCd": 1, "globalCd": 1, "costMp": 0, "gainMp": 56,
                    "victimMp": 1, "range": 1 }, … ], … } } },
  "artifacts": { "<slug>": [ { "level": 1, "cd": …, … } ] },
  "phantimals": { "<slug>": [ [ { "level": 1, … } ] ] } }   // one list per skill, in phantimals.json's order

• The levels are exactly those skills.json, artifacts.json and phantimals.json list, in their order; F13 checks it. Refinements have none.
• The values are the game's, unconverted. cd and initCd of 9999 and above (9999, 99999, 999999, 9999990) mean the skill has no timer: a passive, or an ultimate gated by energy (costMp 1000).
• The game's own label for a cooldown panel is the cooldown term, in every locale: "Cooldown: ${1}\nInitial Cooldown: ${2}" / "冷却时间：${1}\n初始冷却时间：${2}", with ${1} the cooldown and ${2} the initial cooldown ({cooldown} and {initialCooldown} in out/api/).
• What the skill panel shows (traced in the game's UI code, Src/game_module3.luae, the hero skill view; confirmed in game on 2026-09-27: Eironn's ultimate shows a cooldown tag, and his ranges read 1 or "Global"): for the selected slot it walks the shown levels (the slot's IsShow rows) the hero has unlocked and takes the highest one, so upgrading a skill reveals each level's values. It shows three tags. Cooldown: cd as ${1}s, hidden from 60 up; its tooltip is the cooldown term with cd and initCd. Range: range as the bare number, or the rangeGlobal term ("Global") from 15 up, hidden when null; its tooltip is the range term ("Tiles: ${1}" / "技能范围：${1}"). Initial energy: on the ultimate only, the hero's startMp (0 when unset); its tooltip is the initialEnergy term. Energy a skill grants later (an EX or awakening level's "gains 300 extra Initial Energy") is in that level's text, not in startMp.
• range is the same on every level except Marilee's Ultimate (2, then 3) and Skill 3 (2, then 1) on build 14368; three ultimates have 0 (Dionel, Lamentis, Thador), which the panel would show as 0.
• The diff reports a changed value per level (skill2 L1 cd 8 → 7), so a balance change that touches no text still shows.

3.12 en/skills.json (out/internal/)

The English heroes in the game's vocabulary: the same entries as out/api/en/skills.json plus each hero's codename and unitId and each slot's skillTypeCodes (only when non-empty), with the game's glossary keys, <ATK> markers and ${1} blanks, and every resolvable glossary entry. The diff takes skill-type changes from it; the Debuff and Haste nets and research/tempbuff_targets.py read its text.

4  Projection

Projection turns the model into one locale's entries (feed/project.py), and feed/build.py assembles every locale into a payload of {relative path: document}, which the feed gate checks before publish writes anything. Each function ports the matching one in export-api.ts.

4.1 Heroes

• DisplaySlot to key. For each of DisplaySlot 1 to 6, the hero's kit slots with that DisplaySlot merge into one key (ultimate, skill2, skill3, mastery, ex, awakening). The first non-empty skillTypeCodes and the first name that resolves win. internal and special-modes slots, and kit slots at any other DisplaySlot, are not projected.
• Dev and hidden levels are dropped: a level with isDev or without isShow is left out. A level whose text is missing stays, with a null description.
• Refinements leave the level list. A level with a refineTier goes to refinements as {tier, description}. Refine 4 renders the template body from refineStatsAdded; Refine 2 interpolates the Rivalry text against its sArgs only. A refinement without text is dropped.
• Interpolation rows. A kit level interpolates against {sArgs, plusRatio, knockBack}, with the slot's knockBack.

4.2 config.json lists

Entries are {"hero": …, "note": …}, where hero is an English name, codename or Unit ID. Each must match exactly one hero, or the run stops with exit code 2.

4.3 Slugs

Slugs come from afkj_common.rules.assign_slugs, the one place both capabilities decide them, so image files and feed entries join by slug. The input is each entity's English name, resolved as in section 5.3.

• Heroes and phantimals: lowercase, drop ' and ’, turn every run of other characters into -, trim dashes (Elijah & Lailah → elijah-lailah). No English name, or a name that slugs to nothing, falls back to the codename.
• Artifacts: the same after removing a trailing " Spell" (Vine Snare Spell → vine-snare); the fallback is fairy-<id>.
• Collisions: artifacts and phantimals that collide get -<id> appended, in ascending id order. Hero collisions are a model-gate error (M2).
• Charms use their charmId unchanged.

4.4 Locales and their names

The emitted locales are every locale the source has, minus locales.skip, sorted. --locales en,zh narrows that set further; it never adds a skipped or missing locale, and a set without en is refused before anything is built (stargazer requires it, and the feed gate compares every locale with it). Slugs are always from English, so every locale has the same keys.

manifest.localeNames gives each locale's native name: the text of a fixed per-locale key (LOCALE_NAME_KEYS) in that locale's own dictionary. zh and tw share one "Chinese" key, so they are named explicitly (简体中文, 繁體中文). A locale with no known key, or whose dictionary lacks it, is named by its upper-cased code.

4.5 Keyword glossary and slot terms

• Glossary. A keyword from SkillKeywords gets a key only if its tip resolves in English. Those keys form keyword_keys: in hero and charm text a [kw]label[/] tag becomes [[label|kw]] only for these keys. Artifact and phantimal text never carries keys; their tags become [[label]]. In out/api/, skills.json's _meta.keywords maps the keys this locale's hero and charm text uses, under their own names, sorted, to their tips resolved in the locale; out/internal/en/skills.json keeps every resolvable entry under its game key.
• Terms. _meta.terms holds ultimate, exclusiveEquipment and the skill panel's labels cooldown, range, rangeGlobal and initialEnergy (section 3.11): fixed keys (SLOT_TERM_HASHES) looked up in the locale and cleaned, "" when missing, with named blanks in out/api/. stargazer's importers take their slot labels from the first two. The source gate checks the keys exist (S8).

"terms": { "ultimate": "Ultimate", "exclusiveEquipment": "Exclusive Equipment",
           "cooldown": "Cooldown: {cooldown}\nInitial Cooldown: {initialCooldown}", "range": "Tiles: {range}",
           "rangeGlobal": "Global", "initialEnergy": "Initial Energy: {energy}" }   // out/api/en

5  Text rendering

feed/text.py reproduces afkj-data-viewer's format.ts exactly; each function names the format.ts function it ports. The feed's consumers are JavaScript, so numbers follow JavaScript's rules. tests/test_parse_feed.py checks the number formatting against Node itself on 6,000 values, including near-ties and exponent ranges, when node is installed.

5.1 The feed's text encoding

Fields are looked up as lookupField does: SArgN by index into sArgs (out of range is missing); any other name as lower-first, as given, or all lowercase. Hero rows hold sArgs, plusRatio and knockBack; artifact, phantimal and charm rows hold sArgs and plusRatio; the Refine 2 row holds sArgs only. A % field whose value is not a finite number prints as String(value) without the %.

5.2 cleanText

Before interpolation, text is cleaned:

• The dev marker (不用翻译), in half- or full-width parentheses, is removed.
• Client markup (<color=…>, <sprite …>, <nobr>) is removed: any tag that starts with an ASCII lowercase letter. The game's own stat codes are uppercase and stay.
• The result is trimmed with JavaScript's trim() whitespace set.

5.3 Names versus descriptions

5.4 English fallback

Each locale's text is looked up key by key with English behind it (Strings): a key absent from the locale falls back to English; a key present but empty stays empty (and then resolves as in section 5.3). The viewer's per-locale subsets behaved the same way.

5.5 JavaScript number rules

5.6 The Refine 4 body

Refine 4 has no description row. Its body is the localized "Refinement" template (key 15370264355377780556, e.g. EN <color=${1}>Refine ${2}: In Rivalry Mode, increases ${3}.</color>), cleaned (which also drops ${1}, inside the colour tag), with ${2} the tier and ${3} the added stats as <value> <name> joined by ", ". Each name is the stat's own, in the same locale (UnitAttr.Tips); values print with String(). The source gate requires the template (S8), so there is no fallback text.

en  Refine 4: In Rivalry Mode, increases 10 Crit Resist, 15 Ranged DEF, 10 Crit DMG DEF.
zh  精炼4级：竞技模式中，提升10 抗暴击, 15 远程防御, 10 暴击耐性

6  The model and feed gates

6.1 The model gate

checks/model.py checks that the model is complete and consistent enough to project. Hero checks cover the heroes the feed will carry (the model minus blocklist). M collects the findings the builders raised on the way.

./afkj-parse roster prints M6's and M12's suggestions beside the hero list (CLI §10).

6.2 The feed gate

checks/feed.py checks stargazer's importer contract: every rule is one that stargazer's importers, or their silent filters, would otherwise trip over. "Major" locales are en and zh, the ones stargazer requires text in.

F11 is not implemented: image checks were cut.

./afkj-parse check [--out DIR] runs this gate on a feed on disk (default out/api). It loads manifest.json, skillNumbers.json and each listed locale's bulk files; a missing one fails F8. out/internal/ beside it is loaded when there and checked by F10 and F13; a feed without it passes. Any other file under the directory is a stray (F9). Exit code 0 means the gate passed, 1 that it failed, 2 that the directory has no manifest.json.

7  The diff and the baseline

diff.py compares a new feed with the last one stargazer imported, the baseline in out/baseline/. It informs the decision to import. With no baseline, everything is new and stargazer's git diff after import is the review.

7.1 The diff gate

./afkj-parse build runs it after the feed gate passes, unless --no-diff. Its warnings fail it only under --strict, and a failed diff gate means the feed is not published.

7.2 diff.md

The build writes the report to out/build/diff.md; ./afkj-parse diff prints the same report for any two feeds. It compares the bulk files of out/api/ and the files of out/internal/.

• Identity. Entries match by the game's identity, through keys.json: hero and phantimal codename, artifact fairyId, charm name. A slug change reads as a rename, and a charm whose number moved as one too (D6). When a side has no keys.json, both sides match by slug.
• Heroes. Added, removed and renamed heroes; per existing hero, title changes, slots added or removed, level-count, refinement and skill-type changes, per-level cooldown, energy and range changes (a number the new feed no longer has reads → (gone); a key the baseline lacks is an addition and stays out of the notes), and the number of changed texts per locale (the hero's name, slot names, levels, refinements). An addition or removal names the blocklist or forceParse edit that explains it, from the last build report's lists against _accepted.json's.
• Attention. Heroes over the attention share head the report, each with its drill-down command.
• Artifacts, phantimals, charms. Added, removed and changed (fields, plus per-locale text counts): an artifact's set, id, season and statBonuses, a phantimal's id, factions, damage and range, a charm's heroes.
• Buff records. Records added or removed; field deltas per record, grouped by hero (1701 rabbitbow_ult: stats.ARM_x -0.3 → -0.25); heroes whose buff links changed (scriptBuffs count as links). Not compared when a side has no buffs.json.
• Manifest. Count, season and locale deltas, and the source's from keys.json.
• Shared text. Changes to a locale's glossary tips, _meta.terms labels and charm tier names, each with the locales it changed in.
• Changed fields. The safety net: every changed field of every file, whether or not a section above names it, grouped by pattern (internal/skillNumbers.json heroes.*.skills.ex[].range: added ×508) with generatedAt ignored; the first 40 patterns are listed. A file present on one side only reads (the whole file).

From the 1.7.4 dump feed to build 14368: heroes +3 (Aster, Estrilda, Senea) and 21 changed, Isabella and Silvina gain Awakening L2, and the season flip reads as artifacts +12 −12, phantimals +5 −5, charms +19 −17.

7.3 One hero's texts

./afkj-parse diff --hero SLUG [--locale CODE] prints every changed text of one hero in one locale (en by default), old over new:

$ ./afkj-parse diff --hero karma --locale zh        # 1.7.4 dump feed → build 14368, abridged
karma (doublehead), zh: 2 changed

ultimate L1
  - None
  + 选择一名敌人为目标，喀尔马高举战斧砸向目标，对目标造成{atk}[[400%]]的伤害以及[[2.5]]秒眩晕。…

ex L3
  - …战斧的攻击命中敌人时会附带{hp}[[20%]]的魔法伤害。
  + …战斧的攻击命中敌人时会附带{hp}[[15%]]的魔法伤害。

--base takes a baseline directory or any feed directory, so two builds can be compared without accepting either.

7.4 The baseline and accept

./afkj-parse accept makes the feed stargazer imported the next diff's base. It copies the feed's files (manifest.json, skillNumbers.json and each locale's four bulk files) into out/baseline/api/ and out/internal/'s into out/baseline/internal/, as compact JSON, and writes out/baseline/_accepted.json:

{ "acceptedAt": "…", "feed": { "generatedAt": "…", "season": 8, "source": { … } },
  "config": { "path": "config.json", "sha256": "…" }, "lists": { "blocklist": [ … ], … } }

It refuses (exit code 1) when there is no build report, when the report failed, when the report's feed generatedAt differs from the feed's manifest, or when the feed's or the internal files no longer match the sha256 the build recorded after publishing them (an edit, a lost file, a copy), so only the very feed that passed every gate becomes a baseline. It also refuses (exit code 2) a baseline that overlaps the feed, the internal files, the work directory or the source the build read. make clean keeps out/baseline/; only accept replaces it.

The baseline lives only under out/, which git ignores, so a fresh clone has none. There build still passes, the diff gate reports "no baseline yet", and stargazer's git diff after the import is the comparison (Integrations §2.3). A baseline also carries its source: against an extract baseline, the same build read from the dump lists 14 buff records removed and changed links on 126 heroes (build 14368), because the dump has no HeroScripts (section 2.10), plus the source kind in the internal files' _meta. Heroes, artifacts, phantimals and charms compare equal. Accepting a dump-built feed moves that difference into the next extract diff, as records added.

8  Parity with afkj-data-viewer (record)

Before stargazer switched to this feed, it was compared with afkj-data-viewer's for the same input, file by file and leaf by leaf, ignoring generatedAt, the game ids the projection adds (unitId, fairyId, campSlot and the like, the manifest's season and source) and buffs.json. Both runs matched exactly, with no allowlist of intended differences:

Measured 2026-09-26; on the 1.7.4 dump the feed gate's F12 fails on Karma's Ultimate L1 (a key empty in that dump only), so that run was built without the gate. Stargazer then imported this repo's feed of build 14368 and none of its generated files changed. The viewer was retired and deleted, and the comparison script is gone (git history keeps tests/parity.py); regressions now show in the diff against the last imported feed (section 7) and in the synthetic world's golden feed, tests/mini_feed.json, which both source layouts must build identically, apart from _meta.source.

9  Known quirks, revisited

Behaviours the feed had because afkj-data-viewer's feed had them, found in the P3 review (2026-09-26) and settled on 2026-09-27 with one principle: use the game's own data instead of rules kept by hand. The Refine 4 stat names are the game's (section 5.6; they had been a fixed English table, so 14 non-English locales changed and stargazer re-imported them once), the Refine 4 fallback text and the no-op ${1} replacement are gone, and skill-type codes sit on kit slots only. What remains is below.

9.1 Kept on purpose

9.2 Game-data behaviours (checked harmless)

9.3 Buff linking (conventions in buffs.json)

These rules come from the viewer's buff inference and affect only buffs.json, which stargazer does not read. They are kept apart from the rows' own links (attached) and the script's (scriptBuffs) so a client can weigh them.