goober/nte-exporter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nte-exporter/docs/mapping-updates.md
Golumpa 5fe39b96ae Add achievement export support
2026-08-19 13:00:09 +01:00

4.4 KiB
Raw Blame History

Mapping updates

tools/update_mappings.py rebuilds arcs.json, characters.json, items.json, and achievements.json directly from the current Waifus-Grace/NTE_Assets tables.

English display names and achievement descriptions come from Localization/en/game.json. The data tables provide localization namespace/key references and quality metadata; their embedded LocalizedString values are deliberately ignored.

The generated files are an authoritative snapshot, not an additive merge. When NTE_Assets removes an ID, changes its casing, or updates its metadata, the staged mapping reflects that change. This is intentional for a live-service game whose asset tables evolve over time.

Review workflow

GitHub Actions

Run Update mappings from the repository's Actions tab. The optional source_ref input accepts an NTE_Assets branch, tag, or commit and defaults to main.

The workflow rebuilds the mappings, runs the complete test suite, uploads the JSON review report, and opens a pull request from dev/automated-mapping-update. Running it again updates the same open pull request. If the authoritative snapshot has not changed, it reports zero changes and does not create a commit or pull request.

The repository setting Allow GitHub Actions to create and approve pull requests must be enabled for automatic pull-request creation. The workflow uses only the repository-scoped GITHUB_TOKEN and grants it contents: write and pull-requests: write permissions.

Local

Stage the latest candidate files without touching the committed mappings:

python tools/update_mappings.py

The required JSON tables are downloaded from the main branch by default. Pin a tag, branch, or commit for reproducible review:

python tools/update_mappings.py --source-ref e9752e5963103529f0d683fd0aed4752b7dfad78

To use an existing local checkout without network access:

python tools/update_mappings.py --assets-root path\to\NTE_Assets

The default output is build/mapping-update/ and contains the four candidate mapping files plus mapping-update-report.json. The report lists additions, updates, and deletions by file and records SHA-256 hashes for every source table.

After reviewing the report and diff, apply the validated snapshot explicitly:

python tools/update_mappings.py --apply
python -m pytest -q

For CI, --check exits with status 1 whenever the generated snapshot differs from the committed mappings. It still writes the staged artifacts.

Source rules

  • Every achievement in DT_AchievementConfigInfo is emitted to achievements.json with its localized title and description, target, category, quality, and rewards.
  • Every Arc in DT_ForkItemData is emitted to arcs.json.
  • Every character in DT_Character is emitted to characters.json.
  • Other pull rewards are selected by GachaIllustrate and resolved to the inventory tables for quality and localization keys. Appearance-table IDs provide canonical casing for glider rewards.
  • Mystery Box rewards are selected from every row in DT_GashaponLotteryGlobal. No event IDs are hard-coded, so future rotations are included automatically. Rewards resolve through the inventory, capital, appearance, and vehicle-item tables using case-insensitive IDs.
  • Fashion, avatar-frame, and business-card Mystery Box rewards are categorized as cosmetics; other Mystery Box rewards, including vehicle keys and currencies, are categorized as items.
  • Names are resolved strictly through Localization/en/game.json. A missing or ambiguous key fails the update instead of falling back to a DT value.
  • Character-awakening and character-vehicle illustration entries are not independent pull rewards and are excluded.
  • Orange, purple, and blue item qualities map to S, A, and B.

UID compatibility boundary

This updater reads and writes only the generated reward and achievement mapping files. It never reads or writes the permanent, limited, beginner, or Arc pool mapping files. Banner IDs, timestamps, record ordering, format version, and all UID inputs are therefore unchanged by mapping synchronization.

Reward and achievement IDs or display metadata may change or disappear when the authoritative NTE_Assets snapshot changes. Existing exports remain unchanged; new exports use the current asset snapshot. UID stability is independent of display mappings.