JSON2Proto

Converts the JP, EN, TC, CN and KR Sekai master databases into binary Protobuf lists. Each file contains all five regions (tc corresponds to SekaiKit's tw).

Output	Sources
gacha.proto	gachas.json
honor.proto	honors.json, honorGroups.json
virtual_live.proto	virtualLives.json
character.proto	characterProfiles.json, gameCharacters.json, gameCharacterUnits.json
event.proto	events.json, eventDeckBonuses.json, eventCards.json, eventMusics.json, eventStories.json, JP gameCharacterUnits.json
card.proto	cards, cardRarities, masterLessons, cardEpisodes, cardMysekaiCanvasBonuses
song.proto	musics, musicTags, musicDifficulties, JP/EN musicArtists, musicVocals, outsideCharacters, gameCharacters, releaseConditions, musicOriginals, musicAssetVariants, JP musicCategories; shared music_metas.json
fixture.proto	mysekaiFixtures, both genre tables, mysekaiBlueprints, mysekaiBlueprintMysekaiMaterialCosts, mysekaiMaterials
sticker.proto	stamps.json
comic.proto	Comic records in tips.json
skill.proto	skills.json, including effects and level values
release_condition.proto	releaseConditions.json
episode.proto	eventStories, unitStories, cardEpisodes, character2ds

Build with the JSON2Proto Xcode scheme, or use SwiftPM (Swift 6.2 or newer):

swift run JSON2Proto output/
swift test

For reproducible offline conversions, pass --input-folder master-data/. That folder must contain jp/, en/, tc/, cn/, and kr/, each containing all of the applicable source tables above, plus shared/music_metas.json at the input root. A failed download, invalid table, duplicate entity ID, or missing character join fails conversion instead of publishing partial data.

The Update Assets workflow runs tests, builds, converts, and publishes only the thirteen corresponding .aar archives to Chorus-ACE/Sekai-Protobuf-Assets. Each Apple Archive contains its corresponding binary .proto file. The raw .proto outputs remain local build intermediates; legacy raw binaries are removed from the destination on the next successful run. The files in SekaiProtoDef/ are schema definitions.

The workflow checks every hour, on pushes, and on manual runs. Before building, it compares the Git blob SHAs of all required regional source JSON files (including musicArtists only for JP/EN and musicCategories only for JP) against the last successful run stored in GitHub Actions cache. The external song statistics source is checked by SHA-256; its exact checked bytes are included in the snapshot so conversion cannot race a later external update. Unrelated upstream commits are ignored. A changed converter repository revision, missing cache, or missing/changed published files also triggers conversion. Manual runs have a force option to bypass this check.

Downloads use the checked commit for each region and verify every Git blob SHA. After conversion, only changed Protobuf contents are recompressed; unchanged archives are retained so archive timestamps do not create false changes. Cached content hashes are bound to archive hashes; when the cache is missing, existing archives are extracted locally for comparison. Commits and normal pushes happen only when published assets change. Runs are serialized. The existing asset history is preserved.

Successful source checks are cached even when new JSON produces identical Protobuf, so the next hourly run can skip conversion. Failed downloads, builds, conversions, or pushes never advance the successful state. If the Actions cache expires, the workflow converts once again and still avoids publishing identical output.

Run the update-check regression tests with:

python3 -m unittest discover -s Scripts/tests -v

Character profiles and colors are joined by character ID. Event bonuses are consolidated with virtual singer variants mapped to their base characters. Event introductions (outline) are joined from each region’s eventStories.json by eventId; missing and empty introductions remain distinct. Old archives decode with no introduction. Regenerate and publish event.aar to deliver this field. Event card/music IDs are included for ExtendedEvent. Optional fields preserve presence, timestamps use milliseconds, and string enums retain upstream values. JSON2Proto/EarlyEventUnits.swift explicitly corrects the unit of events #1–42 in every region, including none for mixed-unit events. This compiled data table repairs historical upstream none values without requiring runtime resource files. Events #43 onward retain their upstream unit. Regenerate and publish event.aar for these corrections to reach clients. The generator also joins JP story banner character-unit IDs to base character IDs and computes focus_character_id and the one-based focus_character_index. Counts use JP startAt order (event ID breaks ties), after historical unit corrections, and exclude mixed-unit and World Link events. The resulting metadata is shared by event ID across all regions, regardless of regional release order or progress. Incomplete or inconsistent focus data for a unit event fails conversion instead of silently shifting later counts. These fields are optional: old archives, mixed events, World Link, and events absent from JP history have no focus metadata. Card parameters accept both the expanded JP/EN records and the compact TC/CN/KR arrays, preserving the power at each level in the same wire format. Card rules include the shared MySekai canvas fixed bonus by rarity directly in card.proto. Regenerate and publish card.aar when these rules change. Clients read canvas bonuses only from Protobuf; there is no runtime JSON fallback.

Updating the schema

SekaiProtoDef/ is the source of truth. Never renumber or reuse existing fields. After editing any schema, run:

sh Scripts/sync-protos.sh
# Or pass an explicit SekaiKit/SekaiKit/Protobuf directory.

Both projects use SwiftProtobufPlugin to generate Swift types during the build. Publish the updated assets before releasing a SekaiKit version that reads them. To test a conversion through SekaiKit:

mkdir -p archives
python3 Scripts/update_assets.py prepare --generated output --published archives
SEKAI_PROTOBUF_TEST_ASSETS="$PWD/archives" swift test --package-path ../SekaiKit

Joined content and migration

Content.proto defines typed records; no JSON strings or opaque JSON payloads are stored in the archives. Songs include regional credits, chart levels/counts, tags, media, vocalists and resolved unlock conditions. The song archive also carries the complete external vocalist list and shared chart statistics. Fixtures include genre names and all blueprints with their material costs. A missing material master record preserves the referenced ID and quantity with no name; an absent blueprint is distinct from a blueprint with zero materials. Episode records include parent ID, kind, titles and regional asset paths; character mappings share their archive. Scenario bodies remain JSON and are loaded on demand by SekaiKit. Skills preserve fractional effect durations. Gacha additions retain unknown raw categories, optional limits and full double-precision rates while preserving existing field numbers and legacy enums. Rate rows without a source ID remain present; the client assigns a negative one-based index as their display identity. Fractional skill durations and composer/arranger/lyricist credits are preserved.

External statistics currently use https://storage.sekai.best/sekai-best-assets/music_metas.json. If that host returns 403 or fails, the scheduled run fails without publishing partial assets or advancing its success state. Offline conversion accepts an explicitly supplied shared/music_metas.json; it never silently substitutes empty or fabricated statistics. Verification samples must not be published.

The client requires these new archives before release. Updating source code alone does not publish them. For conversion-to-client parity checks, set both SEKAI_ADDITIONAL_PROTOBUF_ASSETS to the archive directory and SEKAI_PROTOBUF_MASTER_DATA to the offline input directory when running SekaiKit tests.

Furniture dialogues join mysekaiCharacterTalkFixtureCommons with mysekaiCharacterTalkFixtureCommonMysekaiFixtureGroups, mysekaiCharacterTalkFixtureCommonTweetGroups, mysekaiCharacterTalkTweets, and gameCharacterUnits separately in each region. Original video links and video asset variants are also kept per region. Clients resolve the extracted MP4 filename through the region's moviebundlebuilddata.asset.

Furniture dialogue lists use the current archive format directly; an empty list means no matching dialogue. Regenerate and publish song.aar and fixture.aar to deliver the new video metadata and furniture text.

Titles and virtual lives are encoded as honor.proto and virtual_live.proto (published as .aar archives), using each edition's honors.json and virtualLives.json. Honor records retain levels, regional asset bundles and rarity, plus joined group backgrounds, custom frames and display metadata. Artwork layers use each region’s own group record; level-only bundles are retained for live-master titles. Virtual Lives retain setlists, schedules, performers, rewards, waiting rooms and item configuration. Their shared schema is LiveTitles.proto. Run sh Scripts/sync-protos.sh after schema changes. Every region is converted independently; no release offsets or shared asset names are assumed. Missing scalar values use Protobuf presence.

Episode archives retain optional episodeNoLabel and gameCharacterId fields for main-story and World Link headings. Existing ordering numbers remain unchanged. Regenerate and publish episode.aar to deliver these fields. SekaiKit can enrich older archives from the corresponding edition's JSON until publication.

card.proto also joins each regional card with its rarity's limits from cardRarities.json, master-rank bonuses from masterLessons.json, and ordered story bonuses from cardEpisodes.json. These inputs participate in hourly source tracking. The stat_rules field (23) is generated for every card; clients read embedded rules rather than downloading JSON separately.

Card power is shared across regions. After joining the regional sources, conversion copies each card's parameters, special-training fixed bonuses and stat_rules from its JP record to every matching regional record. Cards absent from JP use the first available record in EN, TC, CN, KR order. Regional names, release dates, skills and assets are preserved. SekaiKit exposes statRules as CardStatRules?, without a locale wrapper. Regenerate and publish card.aar to deliver this normalization.

Gacha conversion writes upstream category strings and double-precision rates only; the superseded enum and float field numbers/names are reserved. The fixture dialogues_included marker and the obsolete top-level skill enhancement condition are also reserved. Publish regenerated gacha.aar, skill.aar and fixture.aar with the current reader; it does not migrate earlier archive layouts.