@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/ui-uitk/references/ui-runtime-binding.md

@@ -0,0 +1,234 @@
+# Runtime Data Binding Reference
+
+## Table of Contents
+
+- [Core Concepts](#core-concepts)
+- [Data Source Setup](#data-source-setup)
+- [CRITICAL: Always Use nameof()](#critical-always-use-nameof)
+- [Explicit Binding Element](#explicit-binding-element)
+- [C# SetBinding (Programmatic)](#c-setbinding-programmatic)
+- [PanelRenderer with Bindings](#panelrenderer-with-bindings)
+
+Unity UI Toolkit runtime data binding for efficient UI updates.
+
+## Core Concepts
+
+**Use binding when:**
+- Connecting game state to UI (health, score, ammo)
+- Multiple UI elements display the same data
+- Data changes frequently but predictably
+
+**Avoid binding when:**
+- One-time UI updates
+- Per-frame updates (use direct property sets)
+- Simple direct property assignment is clearer
+
+## Data Source Setup
+
+### Required: [CreateProperty] Attribute
+
+```csharp
+using Unity.Properties;
+using UnityEngine;
+
+public class PlayerData
+{
+    [CreateProperty]
+    public int Health { get; set; }
+
+    // the private serialized field here helps the user see the property in the editor but do not create the property on the private member unless requested
+    [SerializeField, DontCreateProperty]
+    private float m_Speed;
+
+    // the public member gets a property created out of it so we bind to this property
+    [CreateProperty]
+    public float Speed
+    {
+        get => m_Speed;
+        set => m_Speed = value;
+    }
+}
+```
+
+
+## CRITICAL: Always Use nameof()
+```csharp
+element.SetBinding("value", new DataBinding
+{
+    dataSourcePath = new PropertyPath(nameof(HealthData.HealthPercentage))
+});
+```
+
+**Why nameof():**
+- Compile-time safety (no typos)
+- Refactoring support
+- IntelliSense/autocomplete
+- No capitalization errors
+
+**Nested properties:**
+```csharp
+dataSourcePath = new PropertyPath($"{nameof(PlayerData)}.{nameof(PlayerData.Health)}.{nameof(HealthData.Current)}")
+```
+
+### Explicit Binding Element
+
+```xml
+<UXML xmlns:ui="UnityEngine.UIElements" xmlns:engine="UnityEngine.UIElements">
+    <Slider name="volume-slider">
+        <Bindings>
+            <engine:DataBinding
+                property="value"
+                data-source-path="MasterVolume"
+                binding-mode="TwoWay"/>
+        </Bindings>
+    </Slider>
+</UXML>
+```
+
+The datasource can be set in the root VisualElement like:
+```xml
+    <ui:VisualElement name="root" data-source="project://database/Assets/Scripts/PlayerData.asset?fileID=11400000&amp;guid=976f7b99fc1424923aee5b5657723366&amp;type=2#PlayerData" class="root">
+```
+This is so that UIBuilder can also read the datasource and preview the binding and control.
+
+```csharp
+private void OnEnable()
+{
+    var root = GetComponent<UIDocument>().rootVisualElement;
+    root.dataSource = m_Settings;
+}
+```
+
+## C# SetBinding (Programmatic)
+
+### Basic Pattern
+
+```csharp
+using UnityEngine;
+using UnityEngine.UIElements;
+
+[RequireComponent(typeof(UIDocument))]
+public class HealthBarController : MonoBehaviour
+{
+    [SerializeField] private HealthData m_HealthData;
+    private Label m_HealthLabel;
+    private ProgressBar m_HealthBar;
+
+    private void OnEnable()
+    {
+        var root = GetComponent<UIDocument>().rootVisualElement;
+        m_HealthLabel = root.Q<Label>("health-label");
+        m_HealthBar = root.Q<ProgressBar>("health-bar");
+
+        m_HealthLabel.SetBinding("text", new DataBinding
+        {
+            dataSourcePath = new PropertyPath(nameof(HealthData.HealthText))
+        });
+
+        m_HealthBar.SetBinding("value", new DataBinding
+        {
+            dataSourcePath = new PropertyPath(nameof(HealthData.HealthPercentage))
+        });
+
+        m_HealthLabel.dataSource = m_HealthData;
+        m_HealthBar.dataSource = m_HealthData;
+    }
+
+    private void OnDisable()
+    {
+        if (m_HealthLabel?.HasBinding("text") == true)
+            m_HealthLabel.ClearBinding("text");
+        if (m_HealthBar?.HasBinding("value") == true)
+            m_HealthBar.ClearBinding("value");
+    }
+}
+```
+
+### Binding Modes
+
+```csharp
+element.SetBinding("text", new DataBinding
+{
+    dataSourcePath = new PropertyPath(nameof(Data.Score)),
+    bindingMode = BindingMode.ToTarget
+});
+
+slider.SetBinding("value", new DataBinding
+{
+    dataSourcePath = new PropertyPath(nameof(Settings.MasterVolume)),
+    bindingMode = BindingMode.TwoWay
+});
+```
+
+**Modes:**
+- `ToTarget` - Data → UI (read-only, default)
+- `ToSource` - UI → Data (write-only, rare)
+- `TwoWay` - Data ↔ UI (input fields)
+
+### Runtime-Created Elements
+
+```csharp
+var label = new Label();
+label.SetBinding("text", new DataBinding
+{
+    dataSourcePath = new PropertyPath(nameof(PlayerData.Name))
+});
+label.dataSource = m_PlayerData;
+parentElement.Add(label);
+```
+
+## PanelRenderer with Bindings
+
+**Unity 6.6+ only** - `PanelRenderer` is a new UI Toolkit runtime component.
+
+**Use `PanelRenderer` instead of `UIDocument` for runtime UI with bindings.**
+
+`PanelRenderer` provides `RegisterUIReloadCallback` which ensures bindings are properly re-established if the UI reloads.
+
+### PanelRenderer Controller
+
+```csharp
+using Unity.Properties;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+public class StatsController : MonoBehaviour
+{
+    [SerializeField] private MyStats m_Stats;
+    private ScriptableObject m_LoadedData;
+
+    private void Awake()
+    {
+        m_LoadedData = ScriptableObject.Instantiate(m_Stats);
+    }
+
+    private void OnEnable()
+    {
+        GetComponent<PanelRenderer>().RegisterUIReloadCallback(OnUIReload);
+    }
+
+    private void OnUIReload(PanelRenderer panelRenderer, VisualElement rootElement)
+    {
+        var hpLabel = rootElement.Q("hpLabel");
+        var mpLabel = rootElement.Q("mpLabel");
+
+        rootElement.dataSource = m_LoadedData;
+
+        hpLabel.SetBinding("text", new DataBinding
+        {
+            dataSourcePath = new PropertyPath(nameof(MyStats.HP))
+        });
+
+        mpLabel.SetBinding("text", new DataBinding
+        {
+            dataSourcePath = new PropertyPath(nameof(MyStats.MP))
+        });
+    }
+}
+```
+
+**Key benefits:**
+- Callback handles UI reload events automatically
+- Bindings re-established if UI is reloaded
+- Cleaner than manual OnEnable setup
+- Works with ScriptableObject data sources

package/skills/ui-uitk/references/uss-guide.md

@@ -0,0 +1,138 @@
+# USS Patterns and Examples
+
+## Table of Contents
+
+- [Design Tokens](#design-tokens)
+- [Transitions](#transitions)
+- [Pseudo-State Tinting](#pseudo-state-tinting)
+- [Text Wrapping](#text-wrapping)
+- [9-Slice Backgrounds](#9-slice-backgrounds)
+- [Child vs Descendant Selectors](#child-vs-descendant-selectors)
+- [Specificity](#specificity)
+
+## Design Tokens
+
+Use `:root` variables for repeated values:
+
+```uss
+:root {
+  --spacing-sm: 8px;
+  --spacing-md: 16px;
+  --spacing-lg: 24px;
+  --color-primary: #4da3ff;
+  --color-bg-dark: #1a1a1a;
+  --color-text: #ffffff;
+}
+
+.container {
+  padding: var(--spacing-md);
+  background-color: var(--color-bg-dark);
+  color: var(--color-text);
+}
+
+.button {
+  padding: var(--spacing-sm) var(--spacing-md);
+  background-color: var(--color-primary);
+}
+```
+
+## Transitions
+
+Define transition properties on the **base class**, not on `:hover`. Otherwise hover-out won't animate.
+
+```uss
+/* CORRECT */
+.button {
+  background-color: #4da3ff;
+  transition-duration: 0.2s;
+}
+.button:hover {
+  background-color: #6db3ff;
+}
+
+/* WRONG - transition on :hover won't animate out */
+.button {
+  background-color: #4da3ff;
+}
+.button:hover {
+  background-color: #6db3ff;
+  transition-duration: 0.2s;
+}
+```
+
+## Pseudo-State Tinting
+
+Prefer tinting one image instead of creating multiple image variants:
+
+```uss
+.button {
+  background-image: url("project://database/Assets/UI/Textures/button-bg.png");
+}
+
+.button:hover {
+  -unity-background-image-tint-color: rgba(255, 255, 255, 0.15);
+}
+
+.button:active {
+  -unity-background-image-tint-color: rgba(0, 0, 0, 0.2);
+}
+
+.button:disabled {
+  -unity-background-image-tint-color: rgba(128, 128, 128, 0.5);
+}
+```
+
+## Text Wrapping
+
+Labels don't wrap by default. Enable wrapping explicitly:
+
+```uss
+.description-text {
+  white-space: normal;
+  overflow: visible;
+}
+```
+
+## 9-Slice Backgrounds
+
+For scalable backgrounds that stretch without distorting edges:
+
+```uss
+.panel-background {
+  background-image: url("project://database/Assets/UI/Textures/panel-bg.png");
+  -unity-slice-left: 12;
+  -unity-slice-top: 12;
+  -unity-slice-right: 12;
+  -unity-slice-bottom: 12;
+  -unity-slice-scale: 1;
+}
+```
+
+Slice values define the non-stretched border regions in pixels.
+
+## Child vs Descendant Selectors
+
+Prefer child selectors for performance:
+
+```uss
+/* BETTER - child selector */
+.panel > .header > .title { }
+
+/* AVOID - descendant selector (slower) */
+.panel .header .title { }
+```
+
+## Specificity
+
+More specific selectors override less specific ones. If your styles aren't applying, check for conflicting selectors:
+
+```uss
+/* Less specific */
+.button { color: white; }
+
+/* More specific - wins */
+.panel .button { color: black; }
+
+/* Even more specific - wins */
+.panel > .content > .button { color: red; }
+```