Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 65 additions & 12 deletions unity-text-locator/SKILL.md

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions unity-text-locator/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
interface:
display_name: "Unity Translation Pipeline"
short_description: "Safely extract, translate, write, and debug Unity game text."
default_prompt: "Use $unity-text-locator to inspect this Unity game, extract and validate project-named translation CSVs, choose the correct writeback adapter, inspect TMP font-bundle compatibility and glyph coverage, and verify runtime loading before packaging."
short_description: "Extract and localize Unity text, catalogs, and TMP fonts safely."
default_prompt: "Use $unity-text-locator to discover every visible Unity text source, including DMSL, component UI, and Localization StringTables; extract and validate occurrence-mapped translation CSVs; generate isolated writeback candidates; trace the actual TMP FontAsset used by failing components; diagnose Addressables CRC or glyph-index failures from logs and Unicode evidence; and require paired runtime canaries before packaging."
21 changes: 18 additions & 3 deletions unity-text-locator/references/ainiee-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,22 @@ python unity-text-locator/scripts/validate_translation_csv.py \

## Guardrails

- Cache writes are atomic and cooperatively locked, but subagents should still produce separate batch JSON files and let one coordinator write `cache.json`.
- Do not let subagents write the same `cache.json` concurrently.
- Do not use AiNiee output directly for Unity writeback; always convert to `zh_cn` CSV and run Unity validation.
- Conversion verifies the source CSV content hash, index continuity, translation status, and nonblank output. Any incomplete row fails by default.
- `--allow-partial` emits blanks only for an explicitly requested review artifact. Do not pass such output to writeback.
- Blank translations remain intentional skips.
- If the translated cache has fewer rows than the source CSV, conversion emits blank rows for missing indexes and validation/reporting should catch the gap before writeback.

## Fixed-Byte DMSL Sources

Some DMSL containers store each string as `0x06 + uint32 little-endian length + UTF-8`, but the runtime or surrounding bundle still requires every replacement to fit the original byte span. Translation quality validation and structural-token validation do not prove this byte budget.

Use this loop:

1. Extract with `extract_dmsl_text.py`; keep its occurrence manifest and source SHA-256.
2. Translate through the normal AiNiee cache bridge and validate the returned one-column CSV.
3. Run `writeback_dmsl_text.py --dry-run`. The report must list every row whose UTF-8 translation exceeds its original byte budget and must not emit a candidate.
4. Shorten the reported Chinese rows without changing names, placeholders, tags, or meaning. Never silently truncate encoded bytes.
5. Re-run ordinary CSV validation and the DMSL dry run until every nonblank row fits.
6. Generate the candidate outside the game root, reopen it, and verify every occurrence and length prefix before any application step.

When TypeTree UI and DMSL records overlap the same bundle, use the writer's `--base-root` to layer the second candidate on the first. The final writer must still verify each field/record against the manifest rather than treating a prior candidate as trusted.
54 changes: 33 additions & 21 deletions unity-text-locator/references/font-asset-replacement.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,30 @@ Treat every font package as untrusted until its internal Unity version, TMP obje

Keep inspection reports in the game workspace, not in the shared skill repository, because reports echo user-supplied local paths. Do not commit font binaries unless their redistribution license has been reviewed and repository inclusion is intentional.

## Preflight
## Preflight And Usage Tracing

Run the read-only inspector before selecting a candidate:
Start from a text component that visibly reproduces the problem. Run `trace_tmp_font_usage.py` to follow its `m_fontAsset` and material PPtrs through External FileIDs/CAB names to the real bundle and PathIDs. Do not infer the "main font" from bundle filenames, object names, character coverage, or discovery order. A title screen, dialogue view, and settings page may use different TMP assets even when their styling looks similar.

Run the read-only inspector before selecting a target or donor:

```bash
python scripts/inspect_tmp_font_bundle.py "FontBundle" \
--target-asset "GameFolder/Game_Data/sharedassets0.assets" \
--translation-root "GameFolder/_translation/unity-text-report/validation" \
--out "GameFolder/_translation/unity-text-report/font-fix/font_inspection.json"
--out "CandidateRoot/font_inspection.json"
```

Verify:

- the internal TMP font, material, and atlas names;
- the internal TMP face family, source Font identity, material, and atlas names;
- the serialized Unity version inside the bundle and target asset;
- character and glyph counts;
- static/dynamic population mode and existing character/glyph table counts;
- source Font PPtr and any family-identity conflict;
- atlas dimensions, format, stream path, platform blob, and color space;
- coverage of characters actually used by the validated translation;
- the package SHA-256 and size.

Prefer an exact engine version. Treat the same Unity major/minor as a candidate requiring a runtime canary. Treat cross-major/minor raw MonoBehaviour replacement as high risk even if UnityPy can parse both files.
Prefer an exact engine version. Treat the same Unity major/minor as a candidate requiring a runtime canary. Treat cross-version raw MonoBehaviour replacement as high risk even if UnityPy can parse both files.

## Diagnose The Symptom First

Expand All @@ -35,40 +38,49 @@ Prefer an exact engine version. Treat the same Unity major/minor as a candidate
| Pink/magenta text or rectangles | Missing/incompatible shader or material | Restore the target shader and validate material properties and atlas reference |
| `corrupted`, `Position out of bounds`, or load failure | Serialization/container mismatch | Roll back; do not continue from the candidate |
| Dialogue is correct but menus are not | Multiple font assets or UI systems | Map each visible component to its actual TMP or legacy font before changing more assets |
| Correct CSV/Unicode displays as another valid CJK character | Stored character/glyph index now points into a different source font | Compare CSV bytes and code points first; treat this as a glyph-index conflict, not a translation error |

Do not call glyph fragments "missing characters." Do not infer runtime texture orientation from exported-image coordinates; Unity runtime rendering is the authority.

## Dynamic TMP Source-Font Trap

Inspect `m_AtlasPopulationMode`, `m_CharacterTable`, `m_GlyphTable`, and `m_SourceFontFile` together. A dynamic TMP FontAsset can still serialize populated character and glyph tables. If its tables are populated, replacing only the referenced TTF/Font object is forbidden: character entries retain old glyph indices, while the new source font can assign those indices to unrelated glyphs. The result can be plausible but wrong Chinese, with one valid Han character consistently rendering as another.

Do not call glyph fragments “missing characters.” Do not infer runtime texture orientation from PIL or exported-image coordinates; Unity runtime rendering is the authority.
First prove the serialized CSV contains the intended Unicode code point. If it does, preserve the translation and repair the font asset. Do not add character aliases to hide missing donor coverage; aliases deliberately render a different glyph and make coverage reports misleading.

## Choose The Least Invasive Adapter

1. For Mono/TMP games with supported injection tables, prefer the preflighted runtime fallback workflow. It preserves original materials and atlases.
2. For IL2CPP games, do not claim the Mono fallback installer applies. Use a compatible IL2CPP runtime plugin only when its loader and interop generation are independently verified.
3. Use resource-level TMP replacement only when the target asset, container rules, and runtime test path are known.
3. Use resource-level TMP replacement only when the visible component, exact target objects, container rules, and runtime test path are known.
4. If no compatible package exists, generate a TMP FontAsset with the exact target Unity/TMP version. Treat editor installation as a build-time dependency, not a game runtime dependency.

## Resource-Level Replacement Contract
## Static Resource Replacement Contract

Before writing:

1. Identify the exact visible text component and its font asset. Do not replace every discovered font as the first experiment.
2. Back up every modified asset and record its SHA-256.
3. Inspect the candidate with `inspect_tmp_font_bundle.py` and save the report.
4. Prove required-character coverage against validated translations.
5. Preserve the target MonoBehaviour script, object name, material and atlas PathIDs, and target shader.
6. When materializing a streamed atlas, copy the full payload and all relevant Texture2D fields, including platform blob, format, dimensions, mip settings, preprocessing flags, color space, and stream state. A correct byte count alone is insufficient.
7. Reopen the candidate with UnityPy and validate object names, references, glyph/character counts, atlas dimensions, and payload length.
8. Apply one-font, one-screen canary first. Do not broaden the replacement until the canary renders correctly.
1. Identify the exact visible text component and its FontAsset, Material, and Texture2D PathIDs. Never replace every discovered font as the first experiment.
2. Back up every file that will eventually be applied and record its SHA-256. Build the candidate outside the game directory.
3. Inspect both target and donor and save the reports.
4. Prove required-character coverage against approved translation CSVs. Missing characters and implicit glyph aliases are blocking failures.
5. Preserve the target MonoBehaviour script, object name, FontAsset/Material/Texture PathIDs, and target shader.
6. Copy the donor character table, glyph table, font metrics, matching SDF atlas, and material parameters as one matched set. Never combine a donor table with a target atlas or retain target glyph indices against a donor source font.
7. When materializing a streamed atlas, copy the full payload and all Texture2D fields, including platform blob, format, dimensions, mip settings, preprocessing flags, color space, and stream state. A correct byte count alone is insufficient.
8. Require exact serialized Unity versions by default. A mismatch needs explicit opt-in and produces a canary-only candidate; it is not release evidence.
9. Reopen the candidate with UnityPy and validate names, PathIDs, script/shader identity, FontAsset material/atlas references, glyph/character counts, atlas dimensions, inline payload, and required-character coverage.
10. Apply one-font, one-screen canary first. Do not broaden the replacement until the canary renders correctly.

UnityPy reopening proves structural readability only. It does not prove GPU texture upload, shader compatibility, glyph coordinates, bundle integrity, or game-runtime loading.
Use `build_static_tmp_fontasset.py` only after all explicit target PathIDs are known. UnityPy reopening proves structural readability only; it does not prove GPU texture upload, shader compatibility, glyph coordinates, bundle integrity, or game-runtime loading.

## Runtime Canary

Use a screen containing representative simplified Chinese, punctuation, Latin text, heart/music symbols, and any retained Japanese names. Fully exit and restart the game between candidates so an old atlas cannot remain in memory.
Use a screen containing representative simplified Chinese, punctuation, Latin text, symbols, and any retained Japanese names. Fully exit and restart the game between candidates so an old atlas cannot remain in memory.

Require:

- correct glyph shapes without atlas fragments;
- correct glyph shapes without atlas fragments or wrong valid Han characters;
- acceptable outline, spacing, clipping, and alignment;
- no new asset corruption, missing font, shader, or repeated missing-glyph errors in the log;
- no new asset corruption, missing font, shader, or repeated missing-glyph errors in `Player.log`;
- coverage checks for menus, settings, shop/tutorial screens, dialogue, and at least one late-game scene when available.

On the first visual regression, stop, preserve the screenshot and candidate report, and restore the backup. Do not stack another speculative transformation on the broken candidate.
Expand Down
14 changes: 10 additions & 4 deletions unity-text-locator/references/runtime-sensitive-adapters.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,10 +29,16 @@ Text-table rows inside a bundle may be readable and writable while the resulting
Required gates:

1. Preserve original bundle packing/compression when rebuilding where possible.
2. Determine whether catalog entries carry CRC, hash, size, cache, or local-load options.
3. Treat catalog edits as integrity changes: keep an untouched original and write a candidate first.
4. Validate the rebuilt bundle in the Unity game runtime, ideally through the same loading route used by Addressables.
5. If runtime load fails or cannot be proven, do not apply the translated bundle or catalog even when translation CSV validation passed.
2. Read the rebuilt bundle's internal `AssetBundle.m_Name`; use that exact value to locate its binary catalog record. Do not match by an opaque on-disk filename alone.
3. Determine whether catalog entries carry CRC, hash, size, cache, or local-load options. Catalog layouts vary, so unknown or duplicate internal-name records are blocking failures.
4. For the supported binary layout, use `patch_addressables_catalog_crc.py` to create an external catalog candidate. By default, set only the uniquely identified record's four-byte CRC to zero and byte-compare the result. Do not guess `catalog.hash`, and do not update `bundleSize` without a separately proven layout and runtime need.
5. Treat the rebuilt bundle and matching catalog candidate as one canary unit. Apply both together after backing up both; if either copy fails, restore both. Never leave a new bundle paired with the old CRC catalog.
6. Validate the pair in the Unity game runtime through the same loading route used by Addressables.
7. If runtime load fails or cannot be proven, roll back both files even when CSV validation and UnityPy reopening passed.

If a rebuilt Addressables bundle produces a black screen, inspect `Player.log` before changing text or fonts again. Search first for `CRC Mismatch`, `Will not load AssetBundle`, bundle load exceptions, catalog parse errors, missing dependencies, and hash/cache failures. A CRC mismatch is an integrity-pair failure, not evidence that the translated text or TMP font is bad.

`patch_addressables_catalog_crc.py` is a candidate generator, not an installer. Its output and JSON byte-diff report must stay outside the game root. Application and rollback remain explicit, backed-up operations.

Translation structure validation answers whether rows are safe text. It does not prove resource-container integrity.

Expand Down
15 changes: 7 additions & 8 deletions unity-text-locator/references/unity-text-map.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
# Unity Text Location Map

## Contents

- Common locations and middleware clues
- Discovery order and tool choice
- Per-source CSV/manifest contract
- Safe writeback and validation
- Font fallback and completion evidence

## Common Locations

| Location | What it may contain | First action |
Expand Down Expand Up @@ -35,6 +27,7 @@
| `I2Languages`, `I2Loc`, `LanguageSource` | I2 Localization | Export ScriptableObjects/MonoBehaviours |
| `LocalizeStringEvent`, `StringTableCollection` | Unity Localization package | Export string tables and Addressables |
| `TextMeshPro`, `TMP_Text` | TextMeshPro UI text | Inspect prefabs/scenes/MonoBehaviours |
| `DMSL` near `0x06 + uint32 LE + UTF-8` operands | Custom length-prefixed scenario bytecode | Use the fixed-byte DMSL extractor and retain every occurrence/byte budget |
| `bansheegz_database`, `BGDatabase.dll`, `BGRepo` | BansheeGz BGDatabase | Use a game-runtime load/export/save probe; do not raw-patch payload bytes |
| `ES3`, `ES3Defaults`, `SaveFile.es3`, `AutoSave.es3` | Easy Save 3 persistence | Inspect defaults resource and confirm actual save path/timestamps |

Expand Down Expand Up @@ -119,6 +112,8 @@ searching for translated bytes after the write rather than trusting old offsets.
For raw fallback byte spans, write back only when the UTF-8 translated byte length
does not exceed the original byte span; pad shorter replacements with spaces.

For visible UI missed by scenario extraction, inspect MonoBehaviour TypeTrees for `m_text`, label/caption/title-like fields, and Unity Localization `m_TableData[*].m_Localized`. Preserve serialized-file identity, PathID, a typed field path, source field hash, and duplicate occurrence metadata; PathID alone is not unique across serialized files inside a bundle.

Before writing:

- create timestamped backups under the report `writeback/<source>/backups/` directory, or pass an explicit `--backup-dir` when a project needs a different backup root;
Expand All @@ -130,11 +125,15 @@ is only a structural check. Preserve compression/integrity metadata where
applicable and require a game-runtime bundle/Addressables load test before
applying the bundle or its catalog changes.

For a binary catalog, derive the lookup key from `AssetBundle.m_Name`, require one plausible record, and audit an exact four-byte CRC field change. Do not infer a record from the external bundle filename, and do not guess the catalog hash or stored bundle size.

## Chinese Font Fix

If translated Chinese renders as square boxes, the likely cause is that the game
uses embedded Japanese pixel fonts or a TMP font asset without Chinese glyphs.

If the serialized translation contains the correct Unicode but the screen shows a different valid Han character, this is not tofu and usually is not a translation error. Trace the visible component to its actual TMP FontAsset and check for a populated dynamic character/glyph table paired with a replaced source Font.

Preferred runtime font files on Windows, in order of availability:

- Microsoft YaHei (`msyh.ttc`/`msyh.ttf`)
Expand Down
Loading
Loading