111 lines
4.8 KiB
Markdown
111 lines
4.8 KiB
Markdown
# Mapping updates
|
|
|
|
`tools/update_mappings.py` rebuilds `arcs.json`, `characters.json`,
|
|
`items.json`, and `achievements.json` directly from the current
|
|
[`Waifus-Grace/NTE_Assets`](https://github.com/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. **Use workflow
|
|
from** selects the exporter branch whose updater is run and the target branch
|
|
for the resulting pull request. The `source_ref` input separately selects 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-<selected-branch>`. Running it again for the same
|
|
selected branch updates that branch's 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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
python tools/update_mappings.py --source-ref e9752e5963103529f0d683fd0aed4752b7dfad78
|
|
```
|
|
|
|
To use an existing local checkout without network access:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
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.
|
|
- Vehicle liveries are resolved from their illustration name and icon. Rows
|
|
whose icon identifies a different reward are treated as unreleased upstream
|
|
placeholders and skipped until the assets are corrected.
|
|
- 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 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.
|