@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/optimize-audio/SECURITY.md

@@ -0,0 +1,16 @@
+# Security notes: optimize-audio
+
+This skill has the agent run C# inside the user's open Unity Editor through `unity command script eval`. Automated skill scanners flag that as a powerful capability. It is intentional, and it is limited by the safeguards below.
+
+## Accepted risks
+
+| Risk | Capability | Why it is accepted |
+|---|---|---|
+| `SEC_POWER_CAP` | Runs C# in the user's open Editor through `unity command script eval` | It only reaches the Editor the user already has open, on their own machine, as that user, so it grants nothing they couldn't do themselves. `script eval` sits behind the Pipeline capability gate. No code fetched from a remote source is run. Where a named `unity command` covers a step, the skill uses that instead of `script eval`. |
+
+## Mitigations
+
+- **Only the user's own Editor.** `unity command script eval` talks to the Editor open on this machine. It can't reach another machine or another user's Editor.
+- **Capability gate.** `script eval` is only available when the project's Pipeline package provides it.
+- **No remote code.** The agent runs C# it writes from this skill's own recipes. Nothing downloaded from outside is executed.
+- **Named commands first.** When a dedicated `unity command` covers a step, the skill uses it instead of `script eval`.

package/skills/optimize-audio/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: optimize-audio
+description: Optimizes audio memory, CPU cost, and playback quality through import settings and mixer configuration. Use when asked to reduce audio memory or Audio Mixer CPU cost, change clip Load Types, sample rates or codecs, or force 3D audio to mono.
+---
+## Critical Rules
+
+- Do not make changes before reporting findings to the user
+- Follow steps in strict order; never jump ahead
+- STOP at every `WAIT` checkpoint and await the user's response before continuing
+- Quality is more important than speed: measure before and after every change
+- Always verify results in a device build; Editor audio stats are indicative only
+
+## 0. Set up the execution path
+
+Every C# step below runs inside a live Editor through the Unity CLI. **The `unity-cli` skill owns
+getting you there** — installing the CLI, confirming a connected Editor, adding the project's
+`com.unity.pipeline` package, telling a genuinely absent Editor apart from one stuck in Safe Mode,
+and discovering the Editor's command catalog. Follow it first; don't re-derive any of it here.
+
+Two things it can't know for you:
+
+- **You need `script eval` in particular**, not just a reachable Editor. Confirm it appears in the
+  catalog. Its presence depends on the Pipeline package version, not on the CLI, so a healthy
+  install can still lack it — if it's missing, say so and stop.
+- **Do not hand-edit `.meta` files to change import settings.** Importer values only take effect
+  through `SaveAndReimport()` in a live Editor, so an unreachable Editor is a stop, not a cue to
+  edit metadata directly.
+
+Run C# with `unity command script eval --caller plugin --skill optimize-audio --code '<snippet>'`. Discover the parameter shape from
+`unity command --format json` rather than assuming one. `unity command` defaults to a 30 second
+timeout.
+
+### Passing C# to `script eval`
+
+`script eval` compiles a **statement block, not a file**. Two consequences, both of which cause a compile
+error rather than a warning:
+
+- **No `using` directives.** The compiler reads `using UnityEngine;` as a resource-disposal
+  statement and rejects it (`CS0210`).
+- **Types must be fully qualified.** A bare `AssetDatabase` or `AudioImporter` does not resolve
+  (`CS0246` / `CS0103`), and a bare `Object` is ambiguous with `object` (`CS0104`).
+
+The recipes in [resources/audio-import-api.md](resources/audio-import-api.md) are written
+fully qualified so they can be passed to `script eval` as-is.
+
+## 1. Pre-Flight: Detect Audio System
+
+Before doing anything else, establish the audio environment:
+
+1. **Detect platform and sample rate:** Use `script eval` to read `EditorUserBuildSettings.activeBuildTarget` and `AudioSettings.outputSampleRate`. The output sample rate affects whether overriding clip sample rates will actually save memory.
+2. **Detect AudioMixer presence:** Use the mixer-asset query recipe in [resources/audio-import-api.md](resources/audio-import-api.md) to see if a mixer graph exists. If none exists, note that routing and effect costs are not a concern.
+3. **Detect AudioListener:** Use the scene-component query recipe in [resources/audio-import-api.md](resources/audio-import-api.md) for `UnityEngine.AudioListener` to confirm exactly one listener is present. Multiple listeners produce incorrect spatialization; zero listeners produce silence.
+4. **Proceed** only after platform and listener state are confirmed.
+
+## 2. Assess Current State
+
+Before recommending any change, gather observable data:
+
+1. **Find all AudioSources:** Use the scene-component query recipe in [resources/audio-import-api.md](resources/audio-import-api.md) for `UnityEngine.AudioSource`. For each result, use **one** `script eval` call to batch-read properties — see the batch read recipe in [resources/audio-import-api.md](resources/audio-import-api.md).
+2. **Inspect mixer topology:** If a mixer was found in Pre-Flight, use `script eval` to read the AudioMixer's exposed parameters and group count. A group count above ~8 or effects on the Master group are immediate flags.
+3. **Check DSP buffer size:** Use the DSP buffer recipe in [resources/audio-import-api.md](resources/audio-import-api.md) to read buffer size. See DSP Buffer Size Guidelines in [resources/platform-settings.md](resources/platform-settings.md) for recommended values.
+4. **Report findings before making changes:** Summarize ALL detected sources, the listener count, and mixer depth to the user. Flag any immediate risks (e.g., stereo clip with `spatialBlend = 1`, Decompress On Load on a clip > 1 MB, reverb on the Master group).
+
+**WAIT for the user to review the assessment before proceeding.**
+
+## 3. Understand Request
+
+Route to the correct section based on what the user needs:
+
+| User Says | Path |
+|-----------|------|
+| "audio memory too high" / "memory profiler shows audio" | Section 4 — Import settings audit |
+| "load times slow" / "decompression stall" | Section 4 — Load Type review |
+| "DSP spike" / "mixer CPU" / "audio CPU high" | Section 4B — Mixer audit |
+| "3D sound wrong" / "only left channel plays" / "stereo in 3D" | Section 4A — Force To Mono + spatial settings |
+| "quality artifacts" / "voice sounds bad" / "Vorbis crackling" | Section 4C — Compression quality tuning |
+| "mobile audio battery" / "mobile memory" | Section 4D — Mobile sample rate override |
+| "set import settings on all clips" / "batch audio settings" | Section 4 — Bulk import audit |
+| "streaming" / "background loading" / "Addressables audio" | Section 4E — Streaming and async load |
+
+If the symptom is ambiguous, ask: "Is the problem audio memory usage, DSP CPU spikes, or audio playback quality?"
+
+## 4. Primary Diagnostic Workflow
+
+Use the findings from Section 2 to determine which sub-section applies. More than one may apply simultaneously.
+
+## 4. Primary Diagnostic Workflow
+
+Force-to-mono and spatial settings, the mixer audit, compression tuning, mobile sample-rate overrides, and load-type decisions: [references/diagnostics.md](references/diagnostics.md).
+## 5. Validation
+
+After any import setting or mixer change:
+
+1. **Re-read clip stats:** Use `script eval` to re-read `clip.loadType`, `clip.channels`, `AudioSettings.outputSampleRate`, and the importer's `compressionFormat` to confirm the change applied after reimport.
+2. **Confirm AudioSource routing:** Use the scene-component query recipe for `UnityEngine.AudioSource` and verify `audioSource.outputAudioMixerGroup` is assigned as expected after any mixer restructure.
+3. **Report delta:** State the before and after values for each setting changed. Do not assume the change was effective without reading back the applied importer values.
+4. **Iterate limit:** Maximum 3 adjust-and-verify cycles before pausing to ask the user for feedback.
+
+## 6. Troubleshooting
+
+Symptom → cause → fix for the audio problems this skill covers: [references/troubleshooting.md](references/troubleshooting.md).
+## 7. Completion
+
+After finishing the audit or optimization:
+
+- Summarize every setting changed with before/after values.
+- List any clips or groups that still need attention (e.g., clips that require on-device measurement to confirm savings).
+- If the user needs runtime memory measurement, point them at the Memory Profiler package, which reports the largest AudioClips by runtime byte cost.
+- If mixer CPU is still high after the audit, point them at the Unity Profiler's Audio module for DSP thread profiling.
+
+## Detailed References
+
+- **Platform settings, compression matrix, load types, sample rates:** [resources/platform-settings.md](resources/platform-settings.md)
+- **AudioImporter API recipes and code patterns:** [resources/audio-import-api.md](resources/audio-import-api.md)
+
+## See Also
+
+- **Memory Profiler package** — finds the largest AudioClips by runtime byte cost.
+- **Unity Profiler, Audio module** — DSP CPU markers and frame-time budget.
+- `audio-setup-mixers` — creating mixers and routing Audio Sources into groups.

package/skills/optimize-audio/references/diagnostics.md

@@ -0,0 +1,42 @@
+# 4A. Force To Mono and Spatial Settings
+
+For any AudioSource where `spatialBlend > 0` (3D positioned sound):
+
+1. **Check clip channel count:** Use `script eval` to read `audioSource.clip.channels`. If `channels == 2` and `spatialBlend == 1`, only the left channel plays — this is a bug, not a feature.
+2. **Recommend Force To Mono:** Use the read importer recipe in [resources/audio-import-api.md](../resources/audio-import-api.md) to inspect current settings, then apply Force To Mono using the force-to-mono recipe.
+3. **Apply and reimport:** Report before/after channel counts to the user.
+4. **Verify spatial blend:** Use `script eval` to confirm `audioSource.spatialBlend` is `1.0` (full 3D) and `audioSource.rolloffMode` is set to an appropriate curve.
+
+# 4B. AudioMixer Audit
+
+1. **Measure group depth:** Use `script eval` to walk the mixer's group tree and count levels. More than 3 levels (Master → SFX / Music / Voice → sub-bus) adds routing overhead every frame, even when children are silent.
+2. **Check effects on silent groups:** Use `script eval` to query each group's effects list. Effects such as `AudioReverbFilter` run their DSP at full cost even when no AudioSource routes to that group.
+3. **Flag SFX Reverb on parent groups:** This is the most expensive built-in effect. If found on the Master or a high-level group, flag it explicitly.
+4. **Present recommendations to the user:**
+   - Remove or bypass effects on groups that have no active sources.
+   - Use **snapshots** to switch mix states (combat / explore / pause) rather than toggling effects at runtime.
+   - Flatten unnecessary sub-buses; redirect sources to a shallower ancestor.
+
+   **WAIT for the user to approve the mixer changes before applying.**
+
+5. **Verify DSP buffer size:** If `bufferLength` from Pre-Flight is very small (< 256), recommend increasing it — see DSP Buffer Size Guidelines in [resources/platform-settings.md](../resources/platform-settings.md).
+
+# 4C. Compression Quality Tuning
+
+1. **Read current compression format:** Use the read importer recipe in [resources/audio-import-api.md](../resources/audio-import-api.md) to read `compressionFormat` and `quality` for the clips reported by the user.
+2. **Apply the platform matrix:** See the Compression Format Matrix in [resources/platform-settings.md](../resources/platform-settings.md) for per-platform recommendations.
+3. **Warn about lossy sources:** Use the lossy source check recipe in [resources/audio-import-api.md](../resources/audio-import-api.md). If the original file is MP3, warn the user that lossy source quality is lost permanently after Unity re-encodes. Recommend WAV or AIFF sources.
+
+# 4D. Mobile Sample Rate Override
+
+1. **Identify SFX clips on mobile target:** Use the scene-component query recipe for `UnityEngine.AudioSource` and filter for non-music, non-dialogue clips.
+2. **Read current sample rate setting:** Use the read importer recipe in [resources/audio-import-api.md](../resources/audio-import-api.md) to read `sampleRateSetting` and `sampleRateOverride` for each clip.
+3. **Apply mobile override:** Use the sample rate override recipe in [resources/audio-import-api.md](../resources/audio-import-api.md). See Sample Rate Recommendations in [resources/platform-settings.md](../resources/platform-settings.md) for per-use-case rates.
+4. **Report savings:** Halving the sample rate halves the PCM memory cost. Report the estimated saving for each clip changed.
+
+# 4E. Load Type and Streaming
+
+1. **Audit Load Type per clip:** Use `script eval` to read `clip.loadType` for each clip found in Section 2.
+2. **Apply the decision rule:** See Load Type Decision Table in [resources/platform-settings.md](../resources/platform-settings.md).
+3. **Flag mismatches:** See Load Type Mismatch Flags in [resources/platform-settings.md](../resources/platform-settings.md). Report both types of mismatches to the user.
+4. **Apply `Load In Background`** for any Streaming clip — use the Load In Background recipe in [resources/audio-import-api.md](../resources/audio-import-api.md).

package/skills/optimize-audio/references/troubleshooting.md

@@ -0,0 +1,41 @@
+# 6. Troubleshooting
+
+## Stereo clip on a 3D AudioSource — only left channel audible
+
+1. Confirm `audioSource.spatialBlend == 1`.
+2. Confirm `audioSource.clip.channels == 2`.
+3. Enable `forceToMono` in the AudioClip importer and reimport. Unity mixes both channels to mono during import, preserving level with `normalize = true` (keep on).
+4. If the user does not want to reimport: set `audioSource.panStereo = 0` as a runtime workaround, but warn this does not recover stereo information.
+
+## Decompress On Load clip causes memory spike
+
+1. Confirm `clip.loadType == AudioClipLoadType.DecompressOnLoad` and `clip.length` is long (> 5 s).
+2. Switch to `Streaming` if it is music or ambience, `CompressedInMemory` if played only occasionally.
+3. If the clip is short but still large: check `clip.channels` (stereo wastes double the memory) and `clip.frequency` (high sample rate on a mobile target wastes memory). Apply Force To Mono and/or sample rate override.
+
+## AudioMixer CPU spike — DSP thread hot
+
+1. Confirm with the mixer-asset query recipe that the mixer graph exists.
+2. Use `script eval` to list all groups and their attached effects. Look for reverb, chorus, or EQ on high-level groups.
+3. Move expensive effects down to leaf groups that are only active when sources are playing.
+4. Use snapshots to bypass effect chains during gameplay states where they are not heard (e.g., bypass reverb during a menu).
+5. If the DSP buffer is small (64 or 128 samples), raise it — see DSP Buffer Size Guidelines in [resources/platform-settings.md](../resources/platform-settings.md).
+
+## Vorbis quality artifacts on dialogue
+
+1. Confirm `defaultSampleSettings.compressionFormat == AudioCompressionFormat.Vorbis`.
+2. Confirm `defaultSampleSettings.quality` — default is 0.5, which is often audible on voice. Raise to 0.7–0.85.
+3. On iOS: switch to AAC instead of Vorbis (hardware decode, better quality at equivalent bitrate).
+4. Confirm the source file is lossless (WAV or AIFF). MP3 sources cannot recover quality lost before Unity's re-encode.
+
+## AudioListener count is not exactly one
+
+- **Zero listeners:** All audio will be silent. Use `script eval` to add an `AudioListener` component to the main camera: `UnityEngine.Camera.main.gameObject.AddComponent<UnityEngine.AudioListener>()`.
+- **Multiple listeners:** Unity uses the last enabled one, producing unpredictable spatialization. Use the scene-component query recipe for `UnityEngine.AudioListener` and disable all but the intended one.
+
+## `Load In Background` causes first-play silence
+
+This is expected behavior: the clip has not finished loading when `Play()` is first called. Mitigate with:
+1. Preload the clip at scene start by calling `clip.LoadAudioData()` before it is needed.
+2. Use `AudioSource.PlayScheduled()` with a slight delay to allow async load to complete.
+3. For AudioSources that must play immediately: switch to `CompressedInMemory` (synchronous on first play) rather than `Streaming` with background load.

package/skills/optimize-audio/resources/audio-import-api.md

@@ -0,0 +1,149 @@
+# Audio Import API Recipes
+
+C# code recipes for `unity command script eval --caller plugin --skill optimize-audio --code '<snippet>'`. All examples target the Unity 6
+AudioImporter API.
+
+`script eval` compiles a statement block, so there are no `using` directives and every type is written
+fully qualified. Each recipe `return`s its result as a string rather than calling `Debug.Log`, so
+the value comes back on the CLI's stdout instead of only reaching the Editor console.
+
+## Read AudioClip Importer Settings
+
+```csharp
+var path = UnityEditor.AssetDatabase.GetAssetPath(audioSource.clip);
+var importer = (UnityEditor.AudioImporter)UnityEditor.AssetImporter.GetAtPath(path);
+return $"forceToMono={importer.forceToMono}, loadType={importer.defaultSampleSettings.loadType}, " +
+          $"compressionFormat={importer.defaultSampleSettings.compressionFormat}, " +
+          $"quality={importer.defaultSampleSettings.quality}, " +
+          $"sampleRateSetting={importer.defaultSampleSettings.sampleRateSetting}, " +
+          $"sampleRateOverride={importer.defaultSampleSettings.sampleRateOverride}");
+```
+
+## Force To Mono and Reimport
+
+```csharp
+var path = UnityEditor.AssetDatabase.GetAssetPath(audioSource.clip);
+var importer = (UnityEditor.AudioImporter)UnityEditor.AssetImporter.GetAtPath(path);
+importer.forceToMono = true;
+importer.SaveAndReimport();
+return $"Reimported {path} — channels now: {audioSource.clip.channels}");
+```
+
+## Set Load Type
+
+```csharp
+var path = UnityEditor.AssetDatabase.GetAssetPath(audioSource.clip);
+var importer = (UnityEditor.AudioImporter)UnityEditor.AssetImporter.GetAtPath(path);
+var settings = importer.defaultSampleSettings;
+settings.loadType = UnityEngine.AudioClipLoadType.Streaming; // or CompressedInMemory, DecompressOnLoad
+importer.defaultSampleSettings = settings;
+importer.SaveAndReimport();
+```
+
+## Enable Load In Background
+
+```csharp
+var path = UnityEditor.AssetDatabase.GetAssetPath(audioSource.clip);
+var importer = (UnityEditor.AudioImporter)UnityEditor.AssetImporter.GetAtPath(path);
+importer.loadInBackground = true;
+importer.SaveAndReimport();
+```
+
+## Set Compression Format and Quality
+
+```csharp
+var path = UnityEditor.AssetDatabase.GetAssetPath(audioSource.clip);
+var importer = (UnityEditor.AudioImporter)UnityEditor.AssetImporter.GetAtPath(path);
+var settings = importer.defaultSampleSettings;
+settings.compressionFormat = UnityEngine.AudioCompressionFormat.Vorbis;
+settings.quality = 0.7f; // 0.0–1.0; raise to 0.7–0.85 for dialogue
+importer.defaultSampleSettings = settings;
+importer.SaveAndReimport();
+```
+
+## Override Sample Rate (Mobile)
+
+```csharp
+var path = UnityEditor.AssetDatabase.GetAssetPath(audioSource.clip);
+var importer = (UnityEditor.AudioImporter)UnityEditor.AssetImporter.GetAtPath(path);
+var settings = importer.defaultSampleSettings;
+settings.sampleRateSetting = UnityEditor.AudioSampleRateSetting.OverrideSampleRate;
+settings.sampleRateOverride = 22050u;
+importer.defaultSampleSettings = settings;
+importer.SaveAndReimport();
+```
+
+## Read AudioSource Properties (Batch)
+
+Read multiple properties in a single `script eval` call:
+
+```csharp
+var src = audioSource;
+return $"clip={src.clip?.name}, loadType={src.clip?.loadType}, " +
+          $"channels={src.clip?.channels}, frequency={src.clip?.frequency}, " +
+          $"spatialBlend={src.spatialBlend}, rolloff={src.rolloffMode}, " +
+          $"mixerGroup={src.outputAudioMixerGroup?.name ?? "None"}, " +
+          $"bypassEffects={src.bypassEffects}");
+```
+
+## Read DSP Buffer Size
+
+```csharp
+UnityEngine.AudioSettings.GetDSPBufferSize(out int bufferLength, out int numBuffers);
+return $"DSP buffer: {bufferLength} samples x {numBuffers} buffers");
+```
+
+## Check Source File Format (Lossy Warning)
+
+```csharp
+var path = UnityEditor.AssetDatabase.GetAssetPath(clip);
+if (path.EndsWith(".mp3", System.StringComparison.OrdinalIgnoreCase))
+    return $"'{clip.name}' is MP3 — lossy source quality is lost permanently after Unity re-encodes. Recommend WAV or AIFF sources.");
+```
+
+## Resolving `audioSource` / `clip` inside a snippet
+
+The recipes above are written against an `audioSource` or `clip` variable. `script eval` runs each
+snippet in a fresh scope, so nothing carries over between calls — resolve the object at the top of
+the same snippet that uses it.
+
+By scene object:
+
+```csharp
+var sources = UnityEngine.Object.FindObjectsByType<UnityEngine.AudioSource>(
+    UnityEngine.FindObjectsInactive.Include, UnityEngine.FindObjectsSortMode.None);
+var audioSource = System.Array.Find(sources, s => s.gameObject.name == "TheGameObjectName");
+```
+
+By asset path, when you already know the clip:
+
+```csharp
+var clip = UnityEditor.AssetDatabase.LoadAssetAtPath<UnityEngine.AudioClip>("Assets/Audio/Foo.wav");
+```
+
+## Enumerate scene components
+
+Substitute the component type (`UnityEngine.AudioSource`, `UnityEngine.AudioListener`). Inactive
+objects are included deliberately — a disabled second listener still counts against the
+one-listener rule.
+
+```csharp
+var found = UnityEngine.Object.FindObjectsByType<UnityEngine.AudioSource>(
+    UnityEngine.FindObjectsInactive.Include, UnityEngine.FindObjectsSortMode.None);
+var names = System.Linq.Enumerable.Select(found, c => c.gameObject.name);
+return $"count={found.Length}: {string.Join(", ", names)}";
+```
+
+## Enumerate mixer assets
+
+An `AudioMixer` is a project asset, not a scene object, so it is found through the asset database
+rather than a scene query.
+
+```csharp
+// Scope to Assets. Unscoped, FindAssets also walks read-only packages and reports mixers the
+// user did not author. The second parameter is string[] searchInFolders; there is no SearchMode
+// overload. Measured on one project: t:Material returned 81 unscoped against 9 under Assets.
+var guids = UnityEditor.AssetDatabase.FindAssets("t:AudioMixer", new[] { "Assets" });
+var paths = System.Linq.Enumerable.Select(guids, UnityEditor.AssetDatabase.GUIDToAssetPath);
+return $"count={guids.Length}: {string.Join(", ", paths)}";
+```

package/skills/optimize-audio/resources/platform-settings.md

@@ -0,0 +1,48 @@
+# Audio Platform Settings Reference
+
+## Compression Format Matrix
+
+| Platform | Recommended Format | Notes |
+|---|---|---|
+| PC / cross-platform | Vorbis, quality 0.5–0.7 | Raise to 0.7–0.85 for dialogue; default 0.5 often adds artifacts |
+| iOS | AAC | Hardware decode; cheapest CPU |
+| Android | Vorbis | Software decode |
+| Xbox | XMA | Use platform override in import settings |
+| PlayStation | ATRAC9 | Use platform override in import settings |
+| Web | Vorbis | Browser handles decode |
+
+## Sample Rate Recommendations
+
+| Use Case | Recommended Rate |
+|---|---|
+| PC / console music and voice | 44100 Hz |
+| PC / console SFX | 44100 Hz |
+| Mobile SFX | 22050 Hz |
+| Mobile dialogue | 22050 or 44100 Hz |
+| UI clicks / blips | 22050 Hz |
+
+Halving the sample rate halves the PCM memory cost. Always report the estimated saving for each clip changed.
+
+## Load Type Decision Table
+
+| Load Type | Behavior | Use For |
+|---|---|---|
+| Decompress On Load | PCM in memory at load; zero per-play CPU | Short SFX < 200 KB (uncompressed) |
+| Compressed In Memory | Stays compressed; decompresses on play | Medium clips played occasionally |
+| Streaming | Streams from disk; minimal RAM, higher disk I/O | Music, long ambience, voice-overs |
+
+### Load Type Mismatch Flags
+
+- **Decompress On Load** on a clip > 1 MB bloats memory.
+- **Streaming** on a clip that plays dozens of times simultaneously adds disk pressure.
+- Always apply `Load In Background` for any Streaming clip to prevent the main thread stalling on first play.
+
+## DSP Buffer Size Guidelines
+
+| Setting | Buffer Size | Use Case |
+|---|---|---|
+| Best Latency | 256 | Rhythm games, real-time synthesis |
+| Good Latency | 512 | General gameplay |
+| Best Performance | 1024 | Ambient/cinematic, battery-saving |
+
+A very small buffer (64 or 128) costs more CPU per frame. If `bufferLength` is < 256, recommend increasing to "Good Latency" or "Best Performance" to trade latency for CPU stability.

package/skills/optimize-text-mesh-pro/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: optimize-text-mesh-pro
+description: Optimizes TextMeshPro rendering, memory, and font setup, including font asset stacks, fallback atlases, SDF quality, and worldspace text. Use when the user asks about TextMeshPro font assets, CJK font fallbacks, or TMP memory, build size, quality or performance, not about translating text.
+---
+
+# Optimize TextMeshPro
+
+## Important
+
+- Use the unity cli (`unity command --format json`) and the `unity-cli` and `unity-pipeline` skills for each step.
+- 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.
+- Don't use `using` directives or unqualified types in the `snippet` for `eval`. The compiler reads `using UnityEngine` and a bare `AssetDatabase`, `Volume`, or `Object` causes errors (CS0246 / CS0103 / CS0104). `return` what you want to read; it arrives at `data.result.result`.
+- Never leave verification code in the user's script; never build logging or detection they didn't ask for. See [Final step](#final-step).
+- Avoid long explanations.
+
+First, read the Unity version from `ProjectSettings/ProjectVersion.txt` and the `com.unity.ugui` or `com.unity.textmeshpro` version from `Packages/packages-lock.json`, because the doc URLs and some advice depend on them. For example, before you recommend Dynamic OS, check that `TMPro.AtlasPopulationMode.DynamicOS` exists in the installed package's [API reference](#api-reference), because older `com.unity.textmeshpro` versions don't have it.
+
+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.
+
+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.
+- **Engine on docs.unity.com**: The Unity version, eg `6000.3`
+
+For TextMeshPro, if `com.unity.ugui` is 2.0 or later, TMP is part of uGUI and its docs are in the `com.unity.ugui` package; otherwise they are in the `com.unity.textmeshpro` package. Use the one listed in `Packages/packages-lock.json`.
+
+## Full topic map
+
+Docs pages, API entry points, and glossary: [references/topic-map.md](references/topic-map.md).
+
+## API reference
+
+Read [API reference](references/topic-map.md#api-reference) before relying on a class or method name.
+
+## Workflow
+
+1. Read the Unity version and the `com.unity.ugui` or `com.unity.textmeshpro` version, as described above.
+2. Read the doc pages that cover the area you'll work on, as described above.
+3. Identify the symptom with the [Triage](#triage--identify-the-symptom-first) table, asking the user if they haven't described one.
+4. Follow the matching section. Give advice by default, and change settings only when the user asks you to, because many of these settings change memory use or build size for the whole project. Before you change anything, create a restore point.
+5. Run the [Final step](#final-step), then give the [Final report](#final-report).
+
+## Triage — identify the symptom first
+
+Before providing tips, identify which category the user's issue falls into. If the user has not described a specific symptom, ask: "Are you seeing a **memory/atlas bloat**, **visual quality**, **CPU/performance**, **build size**, or **localization/alignment** issue with TextMeshPro?"
+
+| Symptom | Go To |
+|---|---|
+| Memory Profiler shows large or multiple TMP atlases | [Font Stack & Dynamic Fallbacks](#font-stack--dynamic-fallbacks), [Memory Profiler: Include Font Data](#memory-profiler-include-font-data) |
+| Inconsistent glyph weight, fuzzy edges, visual quality | [Padding & Sampling Ratios](#padding--sampling-ratios), [Font Asset Scale](#font-asset-scale), [Atlas Render Mode: SDF16](#atlas-render-mode-sdf16) |
+| CPU spikes during text updates or Canvas rebuilds | [AutoSize](#autosize), [Worldspace vs Canvas Text](#worldspace-vs-canvas-text) |
+| Build size too large from shipped font files | [Dynamic OS Atlas Population](#dynamic-os-atlas-population) |
+| Mixed Latin + CJK alignment looks off | [Font Normalization](#font-normalization) |
+| Need multiple font styles (italic, outline, glow) | [Material Presets](#material-presets) |
+
+---
+
+## Core Rules
+
+- **Main font = static asset with all glyphs baked in.** Add **dynamic** fallbacks to the font asset's own Fallback list for everything else, not the global list in TMP Settings, unless every font in the project should share them (see `FontAssetsFallback.md`). Keep dynamic atlas size at **512-1024** to bound peak memory.
+- **Dynamic fallback fonts -> enable `Clear Dynamic Data On Build`.** Otherwise editor-baked glyphs ship in the player.
+- **Keep Padding-to-Sampling-Point-Size ratio consistent across primary + fallback fonts.** Mismatch produces inconsistent glyph weight on the same line.
+- **Latin sampling point size 70-90; CJK 36-50.** Different scripts need different sampling sizes for clean SDF.
+- **Font asset Scale = 1.** Anything else (e.g., 0.9) breaks standard point-size math.
+- **Disable AutoSize at runtime once layout is locked.** AutoSize is for design, not for live counters.
+- **Worldspace text -> use `TextMeshPro`, not `TextMeshProUGUI`.** Canvas overhead in worldspace is not free.
+- **Parent often-changing TMP UI to its own Canvas** to bound rebuild cost.
+- **TMP material presets > duplicating font assets** for italic / bold / outline / glow variants of the same font.
+- **For shipping multilingual builds on iOS/Android, evaluate `Atlas Population Mode = Dynamic OS`** to leverage system fonts and shrink the build.
+
+---
+
+## Font Stack & Dynamic Fallbacks
+
+If the user reports memory bloat from TMP atlases, advise this font stack pattern:
+
+```
+Main font asset (static, all required Latin glyphs baked)
+  -> Fallback 1: Dynamic font (atlas 512 or 1024) for CJK
+  -> Fallback 2: Dynamic font for symbols / emoji
+```
+
+Don't use one dynamic font asset for every language, because its atlas keeps growing with every glyph the game uses. Check `Clear Dynamic Data On Build` on each dynamic fallback, as the Core Rules say (see `FontAssets.md`).
+
+---
+
+## Padding & Sampling Ratios
+
+If the user reports inconsistent stroke widths or glyph weight differences between primary and fallback fonts, check the padding-to-sampling-point-size ratio.
+
+The ratio is `Padding / SamplingPointSize`. With Padding = 9 and Sampling Point Size = 90, ratio = **10%**.
+
+- A primary font with one ratio and a fallback with a different ratio produces **inconsistent stroke widths** on the same line.
+- Pick a ratio (10% is a safe default), apply it to all font assets in the chain.
+
+Recommended sampling point sizes:
+
+- **Latin scripts**: 70-90.
+- **CJK scripts**: 36-50 (CJK glyphs are visually denser; smaller sampling sizes still produce clean SDF and save atlas memory).
+
+---
+
+## Font Asset Scale
+
+If the user reports point sizes not matching design specs, check the font asset Scale value. Some imported TMP font assets ship with `Scale = 0.9` instead of `1.0`. A non-1 Scale changes every rendered point size (see `FontAssetsProperties.md`). Advise the user to **set Scale = 1 on all font assets before adjusting padding ratios**.
+
+---
+
+## Sprite Assets
+
+For the source texture settings a Sprite Asset needs, read `Sprites.md` (see the [Full topic map](#full-topic-map)). If the user reports slow loading times for TMP Sprite Assets on mobile, check the source texture's Texture Type, and suggest setting it back to **Default** once the Sprite Asset is created, because Sprite type keeps child sprite sub-objects that TMP doesn't use.
+
+---
+
+## AutoSize
+
+If the user reports CPU spikes on text fields that change frequently (timers, counters, chat, dynamic player names), check whether `enableAutoSizing` is on. AutoSize resizes the text whenever the string changes, causing constant CPU spikes.
+
+Advise: **disable AutoSize and hard-code the chosen point size** once layout is locked. Keep AutoSize on only for genuinely static labels that auto-fit on locale change.
+
+---
+
+## Atlas Render Mode: SDF16
+
+If a static font with point size **72 or larger** looks unclear or has fuzzy edges, advise switching the **Atlas Render Mode** to **SDF16**. Higher precision SDF for big glyphs, at slightly more atlas memory.
+
+---
+
+## Font Normalization
+
+If the user reports misaligned Latin + CJK text on the same line, compare the line metrics of the primary and fallback font assets, and advise adjusting the fallback's ascender and descender until they match the primary's. Read `FontAssetsLineMetrics.md` (see the [Full topic map](#full-topic-map)) for what each metric controls.
+
+To show the lines in the scene, the `TMP_TextInfoDebugTool` component from TMP Examples & Extras draws them. Ask the user before importing Examples & Extras, because it adds unrelated example assets to the project.
+
+---
+
+## Material Presets
+
+If the user needs multiple styles (italic, bold, outline, glow) of the same font, advise material presets instead of duplicating font assets. Presets share the same font texture but override shader parameters. For the Material Preset property on the text component, read `TMPObjectUIText.md`, and for the shader settings a preset can override, read `Shaders.md` (see the [Full topic map](#full-topic-map)).
+
+---
+
+## Dynamic atlases, profiling, worldspace text
+
+### Dynamic OS Atlas Population
+
+### Memory Profiler: Include Font Data
+
+### Worldspace vs Canvas Text
+
+Read [dynamic atlases, profiling, and worldspace text](references/dynamic-atlas-and-profiling.md) when build size, font-data memory, or worldspace Canvas text is in play.
+
+## Final step
+
+Do the following checks:
+
+1. Check the project has zero console errors. Use `console_status` for counts.
+2. Stop there unless the user asked you to prove it works or you suspect a specific fault.
+3. If you do enter Play mode, do it once only to chase a fault you already suspect. Read the world through `eval` rather than adding logging. Take no screenshots as they take too much time.
+
+If a check fails, go back and reread the [docs pages](#full-topic-map) to find out what you missed.
+
+If you changed settings, also read them back through the API, because an Inspector or script change can fail to save. For example: `TMP_FontAsset.atlasPopulationMode`, `m_ClearDynamicDataOnBuild` (through `SerializedObject`), the font asset's `faceInfo.scale`, `enableAutoSizing` on the text component, `TrueTypeFontImporter.includeFontData`, and `TextureImporter.textureType` for a sprite source texture. If a value doesn't match what you set, set it again and read it back.
+
+If you changed settings to reduce memory or build size, compare a measurable result before and after, because a saved setting doesn't prove the problem is gone. For example, record the number and dimensions of `TMP_FontAsset.atlasTextures` for each font asset in the stack before your change, and read them again after. If the result didn't improve, reread the [docs pages](#full-topic-map), and say so in the final report rather than claiming a fix.
+
+## Final report
+
+Report the following, in this order:
+
+1. The symptom category, and each setting you recommended or changed, with the current and recommended values.
+2. The verification results from the final step, including the before and after measurements.
+3. Any side effects of your changes, such as Examples & Extras assets you imported or other assets that use a font asset you changed.
+4. Follow-up the user must do, such as testing Dynamic OS fonts on iOS and Android devices, or capturing a new Memory Profiler snapshot.
+5. The doc pages you read.

package/skills/optimize-text-mesh-pro/references/dynamic-atlas-and-profiling.md

@@ -0,0 +1,28 @@
+# Dynamic OS Atlas Population
+
+If the user is shipping multilingual builds and concerned about build size, advise evaluating **`Atlas Population Mode = Dynamic OS`**. Read the Dynamic OS font asset section of [Font assets](https://docs.unity.com/en-us/engine/<VERSION>/manual/uitoolkits/uielements/uie-work-with-text/uie-font-asset/uie-font-asset.md) for what it changes in the build. The TMP package manual doesn't cover Dynamic OS, but this page covers the font assets that TMP and UI Toolkit share.
+
+At runtime, Dynamic OS looks for a device font with the same Family and Style name as the source font, so choose a source font whose name exists on each target platform. Recommended system fonts for CJK:
+
+| Platform | Recommended system font |
+|---|---|
+| **Android** | NotoSans (covers Chinese, Japanese, Korean glyphs broadly). |
+| **iOS** | PingFang for Simplified/Traditional Chinese. iOS uses **unique fonts per language** for CJK (different families for Chinese, Japanese, Korean) - check the fallback chain when shipping a single TMP setup across all three. |
+
+---
+
+# Memory Profiler: Include Font Data
+
+If Memory Profiler shows unexpectedly large font asset sizes, check **Include Font Data** on the `.ttf` / `.otf` import settings. Read [TrueTypeFontImporter.includeFontData](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unityeditor/truetypefontimporter/includefontdata.md) for what it controls.
+
+Keep it on for fonts that dynamic font assets use, because they generate glyphs from the font data at runtime. Don't turn it off just to make an Editor capture look like a device, because it changes what ships in the build. For build size, use static font assets or [Dynamic OS](#dynamic-os-atlas-population) instead.
+
+---
+
+# Worldspace vs Canvas Text
+
+If the user has worldspace text (damage numbers, signs, holograms) using `TextMeshProUGUI`, advise switching to **`TextMeshPro`**. Worldspace Canvas is a known inefficiency.
+
+If a `TextMeshProUGUI` element's `text` changes often (timers, counters, chat), advise **parenting it under a child GameObject with its own Canvas component**. Canvas rebuilds are scoped per-Canvas, so isolating the volatile field cuts rebuild cost on the rest of the UI.
+
+---