nccgs 1.0.0

package/.claude/skills/optimize-audio/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: optimize-audio
+description: Optimizes Unity 6 audio memory, CPU cost, and playback quality through correct import settings and mixer configuration. Use when the user wants to reduce audio memory usage, choose the right Load Type for short clips versus music versus ambient beds, configure platform-appropriate sample rates and codecs, force 3D audio to mono, or reduce AudioMixer CPU cost from deep group trees or effects running on silent paths.
+---
+## 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 `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 eval --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 `eval`
+
+`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 `eval` as-is.
+
+## 1. Pre-Flight: Detect Audio System
+
+Before doing anything else, establish the audio environment:
+
+1. **Detect platform and sample rate:** Use `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** `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 `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.
+
+### 4A. Force To Mono and Spatial Settings
+
+For any AudioSource where `spatialBlend > 0` (3D positioned sound):
+
+1. **Check clip channel count:** Use `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 `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 `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 `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 `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).
+
+## 5. Validation
+
+After any import setting or mixer change:
+
+1. **Re-read clip stats:** Use `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
+
+### 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 `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 `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.
+
+## 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/.claude/skills/optimize-audio/resources/audio-import-api.md

@@ -0,0 +1,146 @@
+# Audio Import API Recipes
+
+C# code recipes for `unity command eval --code '<snippet>'`. All examples target the Unity 6
+AudioImporter API.
+
+`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 `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. `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
+var guids = UnityEditor.AssetDatabase.FindAssets("t:AudioMixer");
+var paths = System.Linq.Enumerable.Select(guids, UnityEditor.AssetDatabase.GUIDToAssetPath);
+return $"count={guids.Length}: {string.Join(", ", paths)}";
+```

package/.claude/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/.claude/skills/optimize-text-mesh-pro/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: optimize-text-mesh-pro
+description: >
+  Covers TextMeshPro font stacks, dynamic fallback atlases, padding and
+  sampling ratios, SDF16, AutoSize discipline, worldspace vs UGUI, and Memory
+  Profiler font-data capture. Use when the user mentions TextMeshPro,
+  Text Mesh Pro, TMP (TextMeshPro), font asset, dynamic atlas, TMP localization,
+  CJK (Chinese, Japanese, Korean) fonts, font alignment across
+  scripts, mixed western and eastern fonts, text rendering performance, profiler
+  markers related to text generation or glyph rasterization, font fallback
+  strategy, font normalization, multilingual or localized text rendering, SDF
+  font quality, or text-related memory issues—not for UI Toolkit layout
+  (unity-ui-toolkit) or non-TMP uGUI (unity-ui).
+---
+
+# Optimize TextMeshPro
+
+## 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-tmp-320-pre3) |
+| 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 via the Fallback list (or TMP Settings) for everything else. 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`** (TMP 3.2.0-pre.3+) 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
+```
+
+**NEVER ship a dynamic fallback font asset without enabling `Clear Dynamic Data On Build`.** Every glyph baked while testing in the editor is included in the player build if this toggle is off.
+
+---
+
+## 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`. The Scale value participates in the point-size-to-pixels math, so a non-1 scale produces non-standard point sizes. Advise the user to **set Scale = 1 on all font assets before adjusting padding ratios**.
+
+---
+
+## Sprite Assets
+
+If the user reports slow loading times for TMP Sprite Assets on mobile, check the source texture's Texture Type. It must be set to **Default** (not Sprite). Sprite type creates child sub-objects that TMP doesn't use; Default avoids them.
+
+---
+
+## 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, walk them through this procedure:
+
+1. **Window -> TextMeshPro -> Settings -> Import TMP Example & Extras** (one-time per project).
+2. Add the **`TMP_TextInfoDebugTool`** component to the TextMeshPro object displaying misaligned text.
+3. Enable **ShowLines** toggle - the ascender, descender, and baseline render as overlays.
+4. Mix Latin + CJK strings; if the lines diverge, **adjust ascender/descender on the TMP Font Asset** until they align.
+
+> **Caveat**: importing TMP Examples & Extras has been observed to cause an infinite import loop on some project layouts. If it happens, close Unity and re-open - the import resolves on the second attempt.
+
+---
+
+## 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.
+
+How to create:
+
+1. Select a TMP Text GameObject.
+2. In Inspector, find the **Material** section.
+3. **Right-click the Material header -> Create Material Preset.**
+4. Rename the new material and tweak settings.
+5. On the TMP Text component, pick the preset from the **Material Preset dropdown**.
+
+---
+
+## Dynamic OS Atlas Population (TMP 3.2.0-pre.3)
+
+If the user is shipping multilingual builds and concerned about build size, advise evaluating **`Atlas Population Mode = Dynamic OS`** (TMP 3.2.0-pre.3+):
+
+- In Editor: still uses the source font from the project.
+- In a player build: **the source font is not included**. At runtime, Unity searches the device for a font with the matching Family + Style name.
+
+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. |
+
+Wins: build size shrinks (no shipped CJK font files) and memory drops (system font is shared with the OS).
+
+---
+
+## Memory Profiler: Include Font Data
+
+If Memory Profiler shows unexpectedly large font asset sizes in the Editor, check whether **Include Font Data** is enabled on the `.ttf` / `.ttc` import settings. The Editor includes the source font file in the asset by default, but on device (especially with Dynamic OS), this cost is not paid.
+
+To make Editor captures match device: on the font file -> deselect **Include Font Data** in the import settings. Memory Profiler will then show overhead **without** the underlying font file.
+
+---
+
+## 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.
+
+---
+
+## Common Pitfalls
+
+If the user's setup matches any of these, flag it:
+
+- One giant dynamic font asset for all languages instead of static main + dynamic fallback - the dynamic atlas balloons.
+- Inconsistent padding ratio across primary + fallback - same line of text looks like two fonts.
+- Font asset Scale = 0.9 inherited from import - point sizes won't match design specs.
+- Leaving AutoSize on for live counters - hidden CPU spikes.
+- World-space `TextMeshProUGUI` inside a worldspace Canvas - extra rebuilds for no benefit; use `TextMeshPro`.
+- Forgetting **Clear Dynamic Data On Build** on dynamic fallback fonts - editor-test glyphs ship in the player.
+- Capturing Memory Profiler in Editor with Include Font Data on, then being surprised the on-device build is smaller.
+- Sprite asset source texture set to Sprite type - mobile loading slows from extra child sub-objects.
+
+---
+
+## References
+
+- TextMeshPro - Atlas Population Mode (Unity Manual): https://docs.unity3d.com/Packages/com.unity.textmeshpro@latest/manual/FontAssets.html