@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/levelplay-unity-integration/references/troubleshooting.md

@@ -0,0 +1,99 @@
+# LevelPlay Common Issues and Solutions
+
+Detailed troubleshooting for issues that can occur during integration, referenced from the Common Issues
+table in SKILL.md. Read this when the user reports a compile error, a build failure, ads not loading,
+callbacks not firing, or a platform-specific build error.
+
+**Note**: This section addresses issues that can occur during integration. If you haven't started the
+integration yet, begin with Step 1: Verify Environment.
+
+## Contents
+- [CS0246 — namespace 'Unity.Services.LevelPlay' not found](#cs0246--namespace-unityserviceslevelplay-not-found)
+- [Android gradle build fails / iOS build fails with dependency errors](#android-gradle-build-fails--ios-build-fails-with-dependency-errors)
+- [Ads not loading](#ads-not-loading)
+- [Callbacks not firing](#callbacks-not-firing)
+- [Platform-specific build errors](#platform-specific-build-errors)
+
+## CS0246 — namespace 'Unity.Services.LevelPlay' not found
+
+**Root cause**: Ads Mediation package not installed in Unity project
+
+**Symptoms:**
+- Compiler errors: `The type or namespace name 'LevelPlay' could not be found`
+- Compiler errors: `The type or namespace name 'Unity.Services.LevelPlay' could not be found`
+- Red underlines in Unity Editor on all LevelPlay code
+
+**Solutions:**
+1. Stop providing code immediately
+2. Read `Packages/packages-lock.json` and look for `com.unity.services.levelplay` (the package id behind the **Ads Mediation** display name). Answer this from the project, not by asking the user to read the Package Manager window: it is the same question, and reading it is both faster and reliable.
+3. If the id is absent, the package is not installed. Direct to Step 3 to install via Unity Package Manager
+4. Have them restart Unity Editor after installation (important!)
+5. Verify installation by checking that `using Unity.Services.LevelPlay;` no longer shows errors
+6. Only resume code generation after confirmation and verification
+
+**Prevention**: Always verify package installation at Step 7 checkpoint before generating any code.
+
+## Android gradle build fails / iOS build fails with dependency errors
+
+**Root cause**: Native dependencies not resolved
+
+**Symptoms:**
+- **Android**: Gradle build errors mentioning missing dependencies or classes
+- **iOS**: CocoaPods errors, missing frameworks, or linker errors
+- Code compiles perfectly in Unity Editor but fails during platform build
+- Build succeeds in Editor but crashes immediately on device
+
+**Solutions:**
+1. Verify you have a dependency manager installed (Mobile Dependency Resolver, Unity External Dependency Manager, or EDM4U)
+2. Check your project's Assets folder for dependency manager tools
+3. Run dependency resolution:
+   - **Android (newer MDR versions)**: Should auto-resolve on build. If failing, manually resolve via Assets > Mobile Dependency Resolver > Android Resolver > Resolve
+   - **Android (older/other managers)**: Assets > [Your Dependency Manager] > Android Resolver > Resolve
+   - **iOS (all managers)**: Assets > [Your Dependency Manager] > iOS Resolver > Install Cocoapods
+4. Verify resolution:
+   - **Android**: Check `Assets/Plugins/Android/` for gradle files
+   - **iOS**: Look for Podfile or CocoaPods confirmation in console
+5. If you don't have a dependency manager, restart Unity - you should see a prompt to install Mobile Dependency Resolver
+6. Rebuild for your target platform after resolution
+
+**Prevention**: Complete Step 4 (dependency resolution) before building for Android/iOS.
+
+## Ads not loading
+
+**Possible causes:**
+- SDK not initialized before loading ads
+- Incorrect App Key
+- Ad object created before initialization completes
+- Network connectivity issues
+- Ad inventory not available in test region
+
+**Solutions:**
+- Verify `LevelPlay.Init()` is called and `OnInitSuccess` fires before creating ad objects
+- Create ad objects only after `OnInitSuccess` callback
+- Check App Key matches LevelPlay dashboard
+- Test on real devices with active internet connection
+- Enable test mode in LevelPlay dashboard for guaranteed test ads (Note: dashboard test mode is separate from mock ads in the Unity Editor — it enables real test ads on device)
+
+## Callbacks not firing
+
+**Possible causes:**
+- Events registered after SDK initialization
+- Missing event subscriptions
+- Script destroyed before callbacks execute
+
+**Solutions:**
+- Register callbacks before calling `Init()`
+- Verify all callbacks are subscribed (check with Debug.Log statements)
+- Use persistent GameObject with DontDestroyOnLoad if needed
+
+## Platform-specific build errors
+
+**iOS:**
+- Ensure SKAdNetwork IDs are configured in Info.plist
+- Verify ATT is implemented correctly (see `references/ios-setup.md`)
+- Check Xcode build settings for required frameworks
+
+**Android:**
+- Verify Google Play Services is included
+- Check AndroidManifest.xml for required permissions
+- Ensure Gradle dependencies are resolved

package/skills/localize-unity-project/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: localize-unity-project
+description: Sets up Unity Localization, including locales, String and Asset Tables, and CJK fonts. Use when the user wants to add languages or translate UI text.
+---
+
+## Important
+
+- Use the unity cli (`unity command --format json`) and the `unity-cli` and `unity-pipeline` skills for each step.
+- Before making changes, establish a baseline of the current behavior so you can tell whether a later result is actually caused by your change.
+- Create a restore point you can roll back to if your changes fail.
+- Do only what's asked. Don't change unrelated assets or files. Avoid long explanations.
+- Never leave verification code in the user's script. Never build logging or detection they didn't ask for.
+
+## Terms
+
+These names differ between the Editor UI, the package API and this skill:
+
+- **Table collection**: the asset (`StringTableCollection` or `AssetTableCollection`) holding one **table** per locale plus the shared key list, `SharedData`.
+- **`LocalizedTmpFont`**: the package type that references a `TMP_FontAsset` entry in an Asset Table.
+- **`LocalizedFontAsset`**: this skill's component template ([scripts/LocalizedFontAsset.cs](scripts/LocalizedFontAsset.cs)), not a package type. It applies a `LocalizedTmpFont` to the `TMP_Text` on its GameObject.
+
+## 1. Check the Localization package is installed
+Before doing anything else, verify that the Localization package is installed. Many APIs in this skill
+will fail silently or throw confusing errors if the package isn't present.
+
+1. **Check by reading the project, not by asking the Package Manager.** Look for
+   `com.unity.localization` in **`Packages/packages-lock.json`**, because it records what Unity
+   actually resolved and reading it needs no Editor or async call. `Packages/manifest.json` only
+   records what was *requested*.
+2. **Install if missing:** `UnityEditor.PackageManager.Client.Add("com.unity.localization")`.
+3. **Wait properly.** `Client.Add` is **asynchronous**, and busy-waiting on `IsCompleted` blocks the
+   main thread you are running on. Return after firing the install, then **poll `packages-lock.json`
+   in a later call** until the id appears. The install triggers a domain reload, so expect the first
+   poll or two to fail.
+4. **Confirm the types are actually loaded** before using them, since the lock file can be written
+   before the assemblies are ready:
+   ```csharp
+   var t = System.Type.GetType(
+       "UnityEngine.Localization.Settings.LocalizationSettings, Unity.Localization");
+   return t != null ? "ready" : "not loaded yet";
+   ```
+   Only proceed once that returns `ready`.
+
+## 2. Read the documentation
+
+### Full topic map
+
+Read [documentation-lookup.md](references/documentation-lookup.md) before any workflow or diagnosis. It covers where the package's local docs live, how to version the doc URLs, and which manual page to open first.
+
+### API reference
+
+Read [documentation-lookup.md](references/documentation-lookup.md#api-reference) before guessing a package or Engine API signature. It covers the installed package version, `xrefmap.yml` caching, and grepping it for a class or method.
+
+## 3. Localization Settings & Locales
+If `LocalizationEditorSettings.ActiveLocalizationSettings` is null, you must find or create it:
+1. **Find:** Use `AssetDatabase.FindAssets("t:LocalizationSettings", new[] { "Assets" })`. If found, load the first one and assign it to `LocalizationEditorSettings.ActiveLocalizationSettings`.
+   - **Always pass the search folders.** An unscoped `FindAssets` searches the whole project including
+     read-only packages, so it can return an asset from a package and you end up pointing the project
+     at something you cannot edit. This applies to every `FindAssets` call in this skill.
+2. **Create:** If not found, create a new instance and save it to `Assets/Localization/LocalizationSettings.asset`. Use `ScriptableObject.CreateInstance<LocalizationSettings>()` followed by `AssetDatabase.CreateAsset()`.
+3. **Activate:** Set `LocalizationEditorSettings.ActiveLocalizationSettings = settings`.
+4. **Locales:** Ensure locales (en, fr, de, etc.) exist. Create them if missing and add them to settings using `LocalizationEditorSettings.AddLocale(locale)`.
+
+## 4. Modifying Localization Tables
+Programmatic changes to String or Asset tables require notification to the Editor.
+Always create the required asset tables, unless there is already an existing one in the project.
+
+### **Safe Population Pattern**
+When populating tables from a dataset, match by `Locale.Identifier.Code` explicitly. The order of `GetLocales()` is not guaranteed to match your input data array — assuming it does will cause silent data mismatches that are very hard to debug.
+For **Asset Tables**, use the GUID of the asset: `table.GetEntry(sharedId) ?? table.AddEntry(sharedId, guid);`.
+
+### **Refresh & Notification**
+After any modification (adding keys, updating values), notify the Editor so it can refresh its internal state. Skipping this will leave the Editor showing stale data until the next reimport.
+1. Call `EditorUtility.SetDirty(collection)`, `EditorUtility.SetDirty(collection.SharedData)`, on each modified `Table`.
+2. **Notify:** `LocalizationEditorSettings.EditorEvents.RaiseCollectionModified(sender, collection);`
+3. Always call `AssetDatabase.SaveAssets()` at the end.
+
+## 5. UI Localization and Layout
+### **Namespacing & Conflicts**
+
+Read [locale-switching.md](references/locale-switching.md) before adding a language menu or any locale-switching code, so the change goes through the package rather than a hand-rolled current-language variable.
+
+### **Localized String Events (Robust Binding)**
+1. **Check Component Type:** Identify if the target is `TextMeshPro` or legacy `UnityEngine.UI.Text`.
+2. **Bind Correctly:** add the public `UnityEngine.Localization.Components.LocalizeStringEvent`
+  component and wire it yourself — set `StringReference` to the table entry, then add an
+  `OnUpdateString` listener that assigns the value to the text component (`TMP_Text.text` for
+  TextMeshPro, `UnityEngine.UI.Text.text` for legacy Text).
+
+  Do **not** reflect into `UnityEditor.Localization.Plugins.TMPro.LocalizeComponent_TMPro` or its
+  UGUI counterpart, because they are `internal` and can change in any package release.
+3. **Layout Rebuild:** After setting localized text or populating a list, call `UnityEngine.UI.LayoutRebuilder.ForceRebuildLayoutImmediate(parentTransform)` to ensure dimensions update.
+
+## 6. Asian Language Font Support (CJK)
+Read [references/cjk-fonts.md](references/cjk-fonts.md) before setting up fonts for Chinese, Japanese or Korean locales, and follow it in order.
+
+## 7. Automatic Layout (UGUI)
+Translated strings are often much longer than the source text, so a label sized for one language clips or overflows in another.
+
+1. Read the UGUI auto layout pages listed in [references/docs-map.md](references/docs-map.md) before changing a layout, because the right layout group and fitter settings depend on the existing hierarchy.
+2. Change only the containers of labels that overflow in at least one locale, because a fixed layout that already fits every locale is the user's design.
+3. Verify by switching to each locale and checking `TMP_Text.isTextOverflowing` on the affected labels.
+
+### Notes when translating an existing project
+
+Read [translating-existing-project.md](references/translating-existing-project.md) when localizing UI that already exists. It covers minimal-code-change mapping, listener wiring with its read-back checks, and the refresh rules.
+
+### Table completeness check (run this before declaring the work done)
+
+Read [references/table-completeness-check.md](references/table-completeness-check.md), run the check it contains, and report the output.
+
+- **Smart Strings**: Set up smart strings where needed. Inspect the context of each string by taking the entire UI it is on, and any scripts that affect it, into account. Set the context on the string table to ensure translations make sense.
+
+## 8. Recommended Translation Strategy
+Read [references/translation-strategy.md](references/translation-strategy.md) when translating an existing project or finding text that still needs localizing.
+
+
+## 9. Accelerated Localization Workflow
+To localize an entire project efficiently, use a batch processing script that handles all scenes in one pass.
+
+**Ask before acting:** Before running any batch operation, confirm with the user:
+> "This will open every scene in the project, attach `LocalizeStringEvent` components, and save all modified scenes. This cannot be undone automatically. Shall I proceed?"
+
+Only proceed once the user has confirmed. The batch processor template is in [scripts/L10nBatchProcessor.cs](scripts/L10nBatchProcessor.cs).
+
+`LocalizeAll` also enforces this itself, so do not remove or bypass these checks when adapting the template: it refuses to run in batch mode, prompts the user to save or discard unsaved scene changes, and shows a blocking Editor dialog that lists the scenes it will rewrite. Tell the user to watch the Editor and click the confirm button; if they cancel, it throws `OperationCanceledException` and writes nothing. Report that as a cancellation, not an error to work around.
+
+It walks **both** `Text` and `TMP_Text`, and `LocalizeAll` **returns the labels it could not match**
+(as `scene :: object :: "text"`). Print that list. It is the whole point of the return value: a run
+that wires 20 labels and silently leaves 9 alone looks identical to a complete one otherwise. The
+list covers authored text only, so pair it with the code scan in [references/translation-strategy.md](references/translation-strategy.md) and the table completeness
+check in Step 7.
+
+### **Technical Tips for Speed**
+- **Table References:** Use `TableReference` names (strings) instead of GUIDs — they are easier to read and maintain.
+- **Batch Refresh:** Use `LocalizationSettings.Instance.ForceRefresh()` after modifications to force the UI to update in the editor.
+- **Font Swap Automation:** Create the `GameAssets` table once and use a script to attach the `LocalizedFontAsset` component ([template](scripts/LocalizedFontAsset.cs)) to all labels in one pass.
+
+## Troubleshooting errors
+
+If an error appears in the console or the game UI, look it up in [references/troubleshooting.md](references/troubleshooting.md), apply the resolution, then reread the [docs pages](#full-topic-map) for the step that produced it.
+
+## Final step
+
+Run these checks in order. If any check fails, reread the [docs pages](#full-topic-map) to find out what you missed, fix it, and run the checks again.
+
+1. Run `unity command console status` (the `console_status` check) and confirm `groundTruth.consoleErrors` is 0 and `compilationFailed` is false.
+2. Run the [table completeness check](references/table-completeness-check.md) and keep its output for the report.
+3. Stop there unless the user asked for proof or a specific fault is suspected, such as a label that doesn't change when the locale changes.
+4. If a fault is suspected and the change affects runtime behaviour, enter Play mode once to chase it. Read the world through `eval`, for example `LocalizationSettings.SelectedLocale` and the `text` of the label in question, rather than adding logging. Take no screenshots, because they take too much time. Exit Play mode when you're done.
+
+## Final report
+
+Report these in order:
+
+1. **What changed**: locales, tables, keys, components and font assets you added or changed.
+2. **Not converted**: every text site you didn't convert, and why, including `LocalizeAll`'s unmatched labels.
+3. **Verification results**: the result of each Final step check, including the table completeness check output and any gaps.
+4. **Follow-up**: what the user must do, such as confirm which gaps are intentional, review translations, or rebuild Addressables content.

package/skills/localize-unity-project/references/api-notes.md

@@ -0,0 +1,15 @@
+# Localization API pitfalls
+
+These are the failures the API pages don't warn about. For the API itself, read the `LocalizationEditorSettings`, Addressables and TMP pages listed in `docs-map.md`, and the `Addressables.md` manual page for how Asset Tables load their assets.
+
+## Asset Table entries need a save
+`EditorUtility.SetDirty(table)` only marks the table. Without `AssetDatabase.SaveAssets()` an entry added with `table.GetEntry(sharedEntryId) ?? table.AddEntry(sharedEntryId, guid)` reads back correctly for the rest of the session and is gone when the Editor closes. Follow the save sequence in the parent skill: dirty the collection and its `SharedData` too, then save once at the end.
+
+## Avoid the Resources folder
+Don't reference assets inside a `Resources/` folder in Asset Tables, because Addressables can't load sub-assets from `Resources/` and fails with `OperationException: Failed to load sub-asset`. This catches the TMP default font, which lives under `Assets/TextMesh Pro/Resources/`. Copy the asset out with `AssetDatabase.CopyAsset` (for example to `Assets/Fonts/`), and use the copy's path for Addressables and the Asset Table.
+
+## TMP_FontAsset repair
+If fonts appear as "tofu" or throw `UnassignedReferenceException`:
+- Check that the Material and Atlas Texture are nested under the Font Asset in the Project window.
+- Re-assign `fontAsset.material.mainTexture = fontAsset.atlasTexture;` and re-save.
+- If the font was deleted and recreated, update the GUID in both the Asset Table and the Addressables Group.

package/skills/localize-unity-project/references/cjk-fonts.md

@@ -0,0 +1,83 @@
+# CJK Font Support
+
+Avoid TMP Fallback Fonts for CJK locales. Use **Asset Table Font Swapping** for each specific locale instead — fallbacks are unreliable and hard to debug when glyphs are missing.
+
+### Prerequisite: TMP Essential Resources must be imported
+
+**Check this before touching any TMP API.** In a project that has never imported them,
+`TMP_Settings.instance` is `null` and TMP calls fail with a bare
+`NullReferenceException` that names nothing useful. `TMP_FontAsset.CreateFontAsset` is one of them, so
+font creation dies on the first line with an error that looks like a bug in your code.
+
+```csharp
+// The check.
+var ready = TMPro.TMP_Settings.instance != null;
+```
+
+If it is not ready, import them **non-interactively**:
+
+```csharp
+// Do NOT use EditorApplication.ExecuteMenuItem("Window/TextMeshPro/Import TMP Essential Resources").
+// It returns true and then opens a dialog that waits for a human, so nothing gets imported and the
+// run appears to hang. Import the package directly instead.
+string package = null;
+var cache = System.IO.Path.GetFullPath(System.IO.Path.Combine(
+    UnityEngine.Application.dataPath, "..", "Library", "PackageCache"));
+foreach (var dir in System.IO.Directory.GetDirectories(cache))
+{
+    // TMP ships inside com.unity.ugui in Unity 6, and the folder name carries a version hash,
+    // so search for the file rather than hardcoding a path.
+    var candidate = System.IO.Path.Combine(dir, "Package Resources", "TMP Essential Resources.unitypackage");
+    if (System.IO.File.Exists(candidate)) { package = candidate; break; }
+}
+UnityEditor.AssetDatabase.ImportPackage(package, false);   // false = non-interactive
+```
+
+Then poll `TMP_Settings.instance != null` in a **later** call, the same way as the package check in
+Step 1 of the skill, and only continue once it is non-null. Verified on Unity 6000.5.8f1: the non-interactive
+import completes in a few seconds and the assets land in `Assets/TextMesh Pro`.
+
+1. **Use locale-specific fonts:** Western fonts like Arial or Liberation Sans don't contain CJK glyphs, which results in "tofu" (square blocks). Always use a font designed for the target language:
+   - For **Simplified Chinese (zh-Hans)**: Use `msyh.ttc` (Microsoft YaHei) or equivalent.
+   - For **Japanese (ja)**: Use `msgothic.ttc` (MS Gothic) or equivalent.
+   - For **Korean (ko)**: Use `malgun.ttf` (Malgun Gothic) or equivalent.
+   - If system font copying fails, stop and report it. Do not substitute with a Western font.
+2. **Robust Font Creation:** Create dynamic `TMP_FontAsset` from imported fonts.
+3. **Multi-Atlas & Dynamic:** CJK character sets are too large for static atlases; a single atlas will run out of space immediately.
+   - `fontAsset.atlasPopulationMode = AtlasPopulationMode.Dynamic;`
+   - `fontAsset.isMultiAtlasTexturesEnabled = true;`
+4. **Sub-Assets:** add the atlas textures **and the material**. Adding only the texture is the usual
+   mistake, and the material then never reaches the file at all: measured on Unity 6000.5.8f1, a font
+   asset saved without the second call contains **zero** `Material` objects on disk, and one with it.
+   A material that exists only in memory is not part of the asset, so anything that loads the asset
+   fresh gets whatever TMP reconstructs rather than the material you configured, and any setting you
+   applied to it is silently gone.
+    ```csharp
+    // Every atlas texture, not just the first. Step 3 enabled multi-atlas, so there may be several.
+    foreach (var atlas in fontAsset.atlasTextures)
+    {
+        UnityEditor.AssetDatabase.AddObjectToAsset(atlas, fontAsset);
+    }
+    // The material too. Without this line it is not written into the asset.
+    UnityEditor.AssetDatabase.AddObjectToAsset(fontAsset.material, fontAsset);
+    ```
+    - Explicitly link the material's texture: `fontAsset.material.mainTexture = fontAsset.atlasTexture;`
+      and set the font asset, its material, and its textures dirty before saving. (`atlasTexture` is
+      the first entry of `atlasTextures`, which is what the primary material draws from, so this is
+      consistent with adding every texture above.)
+    - **Verify against the file, not against the object you are holding.** After
+      `AssetDatabase.SaveAssets()`, call `AssetDatabase.LoadAllAssetsAtPath(path)` and confirm a
+      `Material` is among the returned objects. Do not settle for `fontAsset.material != null`: that
+      stays true whether or not the material was saved, because TMP will hand back an in-memory one,
+      so it cannot tell a saved material from an unsaved one.
+5. **Addressables:** Every asset referenced in an Asset Table must be marked as Addressable. 
+    - Do not reference assets inside a `Resources/` folder in an Asset Table. This causes `OperationException: Failed to load sub-asset` errors. If an asset is in `Resources/`, copy it to `Assets/Fonts/` or similar before making it Addressable.
+    - If a font asset is deleted and recreated, the new GUID must be manually updated in the Asset Table and re-added to Addressables.
+6. **Specialized Types:** For TextMesh Pro font swapping, prefer `LocalizedTmpFont` over `LocalizedAsset<TMP_FontAsset>` to avoid implicit conversion errors.
+7. **Build Requirement:** After updating Asset Tables or Addressable groups, trigger a build: `AddressableAssetSettings.BuildPlayerContent();`.
+
+### **Verification Step**
+Before concluding any CJK localization task:
+1. **The Tofu Check:** Switch the editor locale to `zh-Hans`, `ja`, and `ko`. Inspect the UI. If any characters appear as squares (tofu), the font setup has FAILED.
+2. **Asset Table Check:** Verify that the `AssetTable` for the CJK locale points to the correct CJK `TMP_FontAsset`, NOT a default Western font.
+3. **Multi-Atlas Check:** Confirm `isMultiAtlasTexturesEnabled` is `true` on the CJK font assets.

package/skills/localize-unity-project/references/docs-map.md

@@ -0,0 +1,42 @@
+# Localization docs map
+
+## Pages
+
+Localization manual, local at `<project-folder>/Library/PackageCache/com.unity.localization@*/Documentation~/` (online fallback: `https://docs.unity3d.com/Packages/com.unity.localization@<VERSION>/manual/`, same names with `.html`):
+- `QuickStartGuideWithVariants.md`: end-to-end setup.
+- `LocaleSelector.md`: startup locale selectors, including the Specific Locale Selector.
+- `StringTables.md` and `AssetTables.md`: table collections and entries.
+- `Addressables.md`: how tables and assets use Addressables groups.
+- `EditModeSupport.md`: the Localization Scene Controls window and Edit mode events.
+- `Smart/SmartStrings.md`: smart strings, plurals and arguments.
+
+Localization API, under `https://docs.unity3d.com/Packages/com.unity.localization@<VERSION>/api/`:
+- `UnityEditor.Localization.LocalizationEditorSettings.html`: settings, locales and collections.
+- `UnityEngine.Localization.Settings.LocalizationSettings.html`: `SelectedLocale` and `AvailableLocales`.
+- `UnityEngine.Localization.Components.LocalizeStringEvent.html`: binding a string to a label.
+- `UnityEngine.Localization.LocalizedTmpFont.html`: the localized TMP font reference.
+
+TMP API, under `https://docs.unity3d.com/Packages/com.unity.ugui@<VERSION>/api/`:
+- `TMPro.TMP_FontAsset.html`: `atlasPopulationMode`, `isMultiAtlasTexturesEnabled` and `HasCharacters`.
+- `TMPro.TMP_Text.html`: `text` and `isTextOverflowing`.
+
+UGUI manual, under `https://docs.unity3d.com/Packages/com.unity.ugui@<VERSION>/manual/`:
+- `UIAutoLayout.html`: how layout groups and layout elements size labels.
+- `script-VerticalLayoutGroup.html` and `script-ContentSizeFitter.html`: the components that let labels grow with longer translations.
+
+Addressables API, under `https://docs.unity3d.com/Packages/com.unity.addressables@<VERSION>/api/`:
+- `UnityEditor.AddressableAssets.Settings.AddressableAssetSettings.html`: `CreateOrMoveEntry` and `BuildPlayerContent`.
+
+Script Reference, under `https://docs.unity.com/en-us/engine/<VERSION>/script-reference/`:
+- `unityeditor/packagemanager/client/add.md`: adding a package from script.
+- `unityeditor/assetdatabase/addobjecttoasset.md` and `unityeditor/assetdatabase/loadallassetsatpath.md`: saving and reading back sub-assets.
+- `unityeditor/assetdatabase/importpackage.md`: importing a `.unitypackage` without a dialog.
+- `unityeditor/events/unityeventtools/addpersistentlistener.md` and `unityengine/events/unityeventbase/setpersistentlistenerstate.md`: persistent listeners.
+
+## Engine API lookup
+
+Engine APIs (`UnityEditor.AssetDatabase`, `UnityEditor.PackageManager`, `UnityEngine.Events`) are versioned by Unity version, so check the project's Unity version first. Then:
+
+1. If the Editor install folder has a `Data/Documentation` folder (e.g. `.../Unity/Hub/Editor/6000.6.0b2/Editor/Data/Documentation`), grep the html files in the `en/ScriptReference` folder inside, and skip the remaining steps.
+2. Otherwise, fetch and cache `https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/xrefmap.yml` (replace `<VERSION>` with the Unity version, e.g. `6000.3`) and grep it for the `uid` (about 6 MB, so don't read the whole file).
+3. Convert the `uid` to a markdown page: remove the parameters in brackets, lowercase it, replace `.` with `/`, and add `.md`. Then fetch `https://docs.unity.com/en-us/engine/<VERSION>/script-reference/<converted uid>`. For example, `UnityEditor.AssetDatabase.ImportPackage(System.String,System.Boolean)` => `https://docs.unity.com/en-us/engine/6000.3/script-reference/unityeditor/assetdatabase/importpackage.md`. If the page doesn't exist, use the `href` in the `xrefmap.yml` entry under `https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/`.

package/skills/localize-unity-project/references/documentation-lookup.md

@@ -0,0 +1,33 @@
+# Full topic map
+
+Before you go forward with a workflow or diagnosis:
+
+1. Open and read the [documentation page(s)](#full-topic-map) that cover the specific subject related to what you intend to do or fix and check if you've missed anything.
+2. Name the file(s) you read in your response.
+
+This is because your training knowledge about Unity might be out of date, incorrect, or for the wrong Unity version.
+
+The docs pages are local markdown conversions of the Unity Manual, stored at `<project-folder>/Library/PackageCache/com.unity.localization@*/`. When reading docs, read only the .md files in that subfolder and don't browse other Library or PackageCache folders, because that takes too much time. This limit doesn't apply to package lookups that other steps run, such as the TMP import in [references/cjk-fonts.md](cjk-fonts.md). If that folder has no `.md` files, use the online pages at `https://docs.unity3d.com/Packages/com.unity.localization@<VERSION>/manual/` instead, because some package versions don't ship their docs.
+
+Prefer `WebFetch` over `WebSearch` — faster and lands on the exact reference. Only fetch what you need. Replace `<VERSION>` with the following before fetching:
+
+- **Package on docs.unity3d.com**: The package version, eg `@6.6` or `@2.0`. Check the package version if unsure.
+- **docs.unity.com**: The product version, eg `7000.0`
+
+Read the Unity version from `ProjectSettings/ProjectVersion.txt`, and each package's major.minor from `Packages/packages-lock.json` (for example `1.5` for `com.unity.localization`). TextMesh Pro (TMP) API pages are in the `com.unity.ugui` docs. If `packages-lock.json` lists `com.unity.textmeshpro` instead, use `https://docs.unity3d.com/Packages/com.unity.textmeshpro@<VERSION>/api/` with that package's version.
+
+Read [references/docs-map.md](docs-map.md) for the manual, API and Script Reference pages to read.
+
+# API reference
+
+The API is `UnityEngine.Localization` and `UnityEditor.Localization`, part of the `com.unity.localization` package. It is versioned by package version, not Unity version (e.g. `@1.4`, `@1.5`), so check the project's installed package version before relying on a specific class or method.
+
+1. Read the installed package version from `Packages/packages-lock.json`, as in [Step 1](../SKILL.md#1-check-the-localization-package-is-installed).
+2. Fetch and cache `https://docs.unity3d.com/Packages/com.unity.localization@<version>/xrefmap.yml` (replace `<version>` with the installed package version, e.g. `1.5`). This file maps every public API member's fully qualified name to its docs page `href` (e.g. `href: api/UnityEngine.Localization.LocalizedTmpFont.html` => `https://docs.unity3d.com/Packages/com.unity.localization@1.5/api/UnityEngine.Localization.LocalizedTmpFont.html`).
+3. Grep the yml file locally for a class or method instead of refetching per lookup. Don't read the whole file.
+
+Always fetch the version matching the installed package rather than relying on training knowledge, since APIs are frequently marked obsolete between major versions. The same steps work for the TMP (`com.unity.ugui` or `com.unity.textmeshpro`) and `com.unity.addressables` APIs.
+
+For Engine APIs (`UnityEditor.AssetDatabase`, `UnityEditor.PackageManager`, `UnityEngine.Events`), follow the Engine API lookup steps in [references/docs-map.md](docs-map.md).
+
+For Asset Table entry, `Resources/` folder and font repair pitfalls, see [references/api-notes.md](api-notes.md).

package/skills/localize-unity-project/references/locale-switching.md

@@ -0,0 +1,17 @@
+# **Namespacing & Conflicts**
+
+- **Single Instance:** Always check `GameObject.Find("YourCanvasName")` and destroy the old one before creating a new one.
+- **Locale switching: use the package, and keep preview and runtime separate.** These are two
+  different mechanisms, and conflating them is why locale switching often ends up hand-rolled.
+  - **To preview a locale while authoring**, use the **Localization Scene Controls** window
+    (`Window > Asset Management > Localization Scene Controls`). This is Editor-only. It is not a
+    runtime feature, so it is not the answer when the game itself needs a language setting.
+  - **To switch locale at runtime**, assign `LocalizationSettings.SelectedLocale`. That is the
+    supported entry point, and everything bound through `LocalizeStringEvent` updates from it.
+  - **To pin which locale the game starts in**, configure a startup locale selector on the
+    Localization Settings asset. `SpecificLocaleSelector` is the one that forces a chosen locale;
+    the default chain otherwise picks up the system language.
+  - **NEVER hand-roll locale state.** A real in-game language menu is fine and expected, as long as
+    it sets `SelectedLocale` and lets the package propagate the change. What is forbidden is a debug
+    dropdown or menu that tracks its own "current language" variable, swaps strings itself, or
+    reaches around the package, because nothing else in the project will follow it.

package/skills/localize-unity-project/references/table-completeness-check.md

@@ -0,0 +1,47 @@
+# Table Completeness Check
+
+Enumerating the tables answers "did every key get a value in every locale" mechanically, so a missing
+entry is found before anyone plays the game. Run it and report the output.
+
+```csharp
+var gaps = new System.Collections.Generic.List<string>();
+var checkedCount = 0;
+
+foreach (var col in UnityEditor.Localization.LocalizationEditorSettings.GetStringTableCollections())
+{
+    foreach (var key in col.SharedData.Entries)
+    {
+        foreach (var table in col.StringTables)
+        {
+            checkedCount++;
+            var entry = table.GetEntry(key.Id);
+            // A missing entry and a present-but-empty entry both show as untranslated in game.
+            if (entry == null || string.IsNullOrWhiteSpace(entry.Value))
+            {
+                gaps.Add($"{col.TableCollectionName} / {table.LocaleIdentifier.Code} / {key.Key}");
+            }
+        }
+    }
+}
+
+// Zero entries is not a pass. It means no collections or no locales were found, so the check
+// examined nothing: report that distinctly instead of letting it read as success.
+if (checkedCount == 0)
+{
+    return "INCONCLUSIVE: no table entries found. Either no String Table Collection exists yet, "
+         + "or the collection has no locale tables. Fix that before trusting this check.";
+}
+
+return gaps.Count == 0
+    ? $"COMPLETE: {checkedCount} entries checked, no gaps"
+    : $"GAPS ({gaps.Count} of {checkedCount} checked):\n  " + string.Join("\n  ", gaps);
+```
+
+Verified on Unity 6000.5.8f1 against a table with one deliberately emptied `ja` value: it reports
+`GAPS 1 of 4` naming exactly that entry, `COMPLETE (4 checked)` once the value is filled, and
+`INCONCLUSIVE` in a project with no tables.
+
+**Report the gap list rather than resolving it silently.** Some gaps are decisions, not mistakes: a
+locale you were not asked to translate, or a key that is intentionally identical across languages.
+Filling those with the English text hides the decision. List them and let the user say which are
+intentional.

package/skills/localize-unity-project/references/translating-existing-project.md

@@ -0,0 +1,47 @@
+# Notes when translating an existing project
+- **Minimal Code Changes**: Never modify code unrelated to localization. Use a static helper class (e.g., `L10n`) to wrap `LocalizationSettings.StringDatabase.GetLocalizedString` for easy injection into existing scripts.
+- **Robust Mapping Strategy**: When mapping existing UI text to keys, sort keys by string length (descending) and match longest strings first. This prevents short strings (like "NO") from matching parts of longer sentences. Use case-insensitive matching where appropriate.
+- **Component Event Listeners**: wire `LocalizeStringEvent.OnUpdateString` with
+`UnityEventTools.AddPersistentListener`, passing a delegate built over the text component's public
+`text` setter. The setter has no C# method-group name, so build the delegate by name:
+`(UnityAction<string>)Delegate.CreateDelegate(typeof(UnityAction<string>), text, "set_text")`.
+That is reflection over a **public** member, which is fine. See
+[scripts/L10nBatchProcessor.cs](../scripts/L10nBatchProcessor.cs) for the working version, including
+clearing any existing persistent listeners first so repeated runs don't stack duplicates.
+  - Do **not** write the persistent-call fields directly through `SerializedObject` (`m_MethodName`,
+    `m_Mode`, `m_PersistentCalls`). Those are private serialized names with no compatibility
+    guarantee, and it isn't necessary: `AddPersistentListener` with the delegate above produces the
+    same serialized call (target = the text component, method = `set_text`, mode = `EventDefined`).
+  - **You must then set the call state, or the label will not update in the Editor.**
+    `AddPersistentListener` leaves the call at `UnityEventCallState.RuntimeOnly`, so the binding is
+    correct but dormant outside Play mode: switching locale in the Editor changes nothing, and it
+    stays that way through a save and reload. Fix it with the public
+    `UnityEventBase.SetPersistentListenerState`:
+    ```csharp
+    UnityEventTools.AddPersistentListener(lse.OnUpdateString, setText);
+    var index = lse.OnUpdateString.GetPersistentEventCount() - 1;
+    lse.OnUpdateString.SetPersistentListenerState(
+        index, UnityEngine.Events.UnityEventCallState.EditorAndRuntime);
+    ```
+  - Persistent listeners **MUST** point to a method on a `UnityEngine.Object`; lambdas will fail.
+  - **Then confirm the binding is live, don't assume it.** Wiring that looks right in the Inspector
+    but does nothing is the characteristic failure of this step. All of the read-back you need is
+    public API on the event, so none of this requires touching serialized fields:
+
+    | Check | Call | Expect |
+    |---|---|---|
+    | Something was wired | `GetPersistentEventCount()` | `> 0` |
+    | It points at the text component | `GetPersistentTarget(i)`, `GetPersistentMethodName(i)` | the component, `set_text` |
+    | It will fire while authoring | `GetPersistentListenerState(i)` | `EditorAndRuntime` |
+    | It actually updates the label | `lEvent.RefreshString()` | the text value changes |
+
+    Do all four, because a binding that is wired but never fires reads as done while leaving the
+    label unlocalized.
+- **Initialization & Refresh**: 
+    - `LocalizationEditorSettings.CreateStringTableCollection` expects a **directory path** (e.g., `Assets/Localization`), not a full asset path.
+    - Always call `lEvent.RefreshString()` after assigning a `LocalizedString` reference programmatically to update the UI immediately.
+    - Keys must exist with a **non-empty value in every table** of a collection (en, de, ja, …). A key
+      that exists with an empty value is the common gap, and it is not silent: the package prints its
+      own "No translation found for …" text **into the game UI**, so the shipped screen shows a
+      developer message. Do not eyeball this. Run the completeness check below.
+- **Verification**: After modifying tables or addressables, run `AddressableAssetSettings.BuildPlayerContent()` and switch the Editor locale to verify changes. Check `LocalizationSettings.Instance` status after activation.

package/skills/localize-unity-project/references/translation-strategy.md

@@ -0,0 +1,41 @@
+## Recommended translation strategy
+To efficiently translate an existing project, follow this multi-step workflow:
+
+1. **Extraction & Component Setup:**
+   - **Find all occurrences. There are two separate hiding places, and scanning one misses the other.**
+     - **Authored text** sits on components in scenes and prefabs: legacy `UnityEngine.UI.Text` and
+       TextMeshPro (`TMP_Text`, the base of `TextMeshProUGUI` and `TextMeshPro`). Walk **both**
+       families. Measured on a real project: `FindObjectsByType<Text>` found 1 component while
+       `FindObjectsByType<TMP_Text>` found 13, so a legacy-only pass reports success having done
+       almost nothing.
+     - **Text composed in code** never appears on a component at edit time, so no scene walk can see
+       it. `scoreLabel.text = $"EXP {value}"` is invisible to every component-based scan and is the
+       string that survives a "finished" localization pass. Find it in the C# instead:
+       ```bash
+       # Assignments and SetText calls that carry a string literal.
+       grep -rnE '\.text\s*(=|\+=)\s*\$?"|SetText\(\s*\$?"' --include='*.cs' Assets/
+       ```
+       That pattern catches plain, interpolated, concatenated and `+=` forms plus `SetText`, and
+       deliberately does not match `label.text = someVariable` or `label.text = Localize("KEY")`
+       (nothing to extract at the first, already routed at the second). Its blind spot is a literal
+       held in a variable or const declared elsewhere; if the count looks low for the project, grep
+       that file's string literals too.
+   - **Report what you did not convert.** A composed string usually needs a smart string or a format
+     argument, which is a judgment call, and some are genuinely not worth localizing. Whichever you
+     choose, list every site the scan found alongside whether it was converted, and why not if it
+     wasn't. Reporting "localized 24 strings" while nine found sites went untouched is the failure
+     mode this list exists to prevent: the work looks finished and the gap only surfaces in a
+     screenshot from another locale.
+   - **Shared Table:** Create a central String Table (e.g., `UIStrings`) with the base language and a "Context" column for each key to guide translators.
+   - **Attach Components:** For every UI element found, attach a `LocalizeStringEvent` (for text) and the skill's `LocalizedFontAsset` component (for font swapping).
+   - **Validation:** Ensure these components are set up with persistent listeners (`EditorAndRuntime`) so they update in the Editor immediately when the locale changes.
+
+2. **Context-Aware Translation:**
+   - **Translate:** Once the table is populated, provide translations for each locale.
+   - **Context is King:** Always refer to the "Context" column or inspect the UI layout to ensure the translation fits the intended meaning and space.
+   - **Grammar & Tone:** Ensure the tone matches the game's style. For example, use imperative verbs for buttons (e.g., German: "Lauf!" instead of "Laufen") and correct pluralization for labels (e.g., "Punkte" instead of "Punkt").
+
+3. **Quality Assurance (QA):**
+   - **Switch locale:** Through `eval`, run `LocalizationSettings.SelectedLocale = LocalizationSettings.AvailableLocales.GetLocale("de");` for each target locale in turn, because a script call is repeatable and doesn't depend on an Editor window being open.
+   - **Visual Inspection:** Methodically inspect every prefab and scene in the base language and all target languages.
+   - **Layout Fit:** Check for text overflows or "tofu" (missing glyphs). Adjust font sizes or use `ContentSizeFitter` if strings are too long.

package/skills/localize-unity-project/references/troubleshooting.md

@@ -0,0 +1,12 @@
+# Localization error messages
+
+Exact error strings this skill's steps can produce, with the root cause and the fix.
+
+| Error | Root cause | Resolution |
+|---|---|---|
+| `CS0118: 'UI' is a namespace but is used like a type` | An unqualified UI type name such as `Image` or `Mask` resolves to the `UnityEngine.UI` namespace. | Fully qualify the type, for example `UnityEngine.UI.Image`. |
+| `OperationException: Failed to load sub-asset` | An Asset Table entry points at an asset inside a `Resources/` folder, which Addressables can't load as a sub-asset. | Copy the asset out of `Resources/`, mark the copy Addressable, and point the table entry at the copy's GUID. |
+| Text starting `No translation found for` shown in the game UI | The key has no entry, or an empty value, in the selected locale's table. | Run the table completeness check in `table-completeness-check.md` Fill the gaps for the keys and locales the user asked for, and report the rest without changing them. |
+| `NullReferenceException` on the first TMP call, for example `TMP_FontAsset.CreateFontAsset` | TMP Essential Resources were never imported, so `TMP_Settings.instance` is `null`. | Import them non-interactively as in `cjk-fonts.md`. |
+| `UnassignedReferenceException` on a font asset, or glyphs show as squares (tofu) | The font asset's material or atlas texture wasn't saved as a sub-asset, or the font lacks the locale's glyphs. | Follow the font repair steps in `api-notes.md` and the font setup in `cjk-fonts.md`. |
+| `OperationCanceledException` from `LocalizeAll` | The user clicked Cancel in the confirmation dialog. | Report it as a cancellation. Don't retry or bypass the dialog. |