com.wallstop-studios.dxmessaging 2.1.4 → 2.1.5

package/{Docs/Helpers.md → docs/reference/helpers.md}

@@ -9,7 +9,7 @@
 - You write: `[DxAutoConstructor]` on a struct
 - Source generator sees: "Oh, they want a constructor!"
 - Source generator creates: A constructor with all the fields as parameters
-- You get: Less typing, fewer bugs, cleaner code
+- You get: Less typing, fewer bugs, more consistent code
 
 #### Learn more about source generators
 
@@ -105,18 +105,27 @@ public VideoSettingsChanged(int width, int height)
 
 ### 3. `[DxOptionalParameter]` - Optional Constructor Parameters
 
-Make constructor parameters optional with type-safe default values:
+The `DxOptionalParameterAttribute` marks a field as optional when used with `[DxAutoConstructor]`. The source generator emits a constructor parameter with a default value for annotated fields, making it easy to create messages with sensible defaults.
+
+#### How It Works with DxAutoConstructor
+
+When you combine `[DxOptionalParameter]` with `[DxAutoConstructor]`, the generator creates a constructor where:
+
+1. **Required fields** (without the attribute) become regular constructor parameters
+1. **Optional fields** (with the attribute) become parameters with default values
+1. **Parameter order** follows field declaration order
+1. **C# rules apply** - optional parameters must come after required parameters
 
 ```csharp
 [DxUntargetedMessage]
 [DxAutoConstructor]
 public readonly partial struct SettingsChanged
 {
-    public readonly float volume;
-    public readonly int quality;
-    [DxOptionalParameter]  // ← Defaults to type's default (false for bool)
+    public readonly float volume;                    // Required (no attribute)
+    public readonly int quality;                     // Required (no attribute)
+    [DxOptionalParameter]                            // Optional, defaults to false
     public readonly bool fullscreen;
-    [DxOptionalParameter(100)]  // ← Custom default value
+    [DxOptionalParameter(100)]                       // Optional, defaults to 100
     public readonly int brightness;
 }
 ```
@@ -133,56 +142,286 @@ public SettingsChanged(float volume, int quality, bool fullscreen = default, int
 }
 ```
 
-##### Usage
+#### Calling the Constructor
+
+Optional parameters support all standard C# calling conventions:
 
 ```csharp
-// All variations work!
+// Provide all arguments
 var settings1 = new SettingsChanged(0.8f, 2, true, 80);
+
+// Use all defaults
 var settings2 = new SettingsChanged(0.8f, 2);  // fullscreen=false, brightness=100
+
+// Use named arguments to skip some optionals
 var settings3 = new SettingsChanged(0.8f, 2, fullscreen: true);  // brightness=100
+var settings4 = new SettingsChanged(0.8f, 2, brightness: 50);    // fullscreen=false
+```
+
+#### Supported Default Value Types
+
+The attribute provides constructor overloads for all common primitive types:
+
+<!-- markdownlint-disable MD046 -->
+
+!!! info "Built-in Type Support"
+
+    === "Numeric"
+
+        | Category              | Types                             |
+        | --------------------- | --------------------------------- |
+        | **Signed Integers**   | `sbyte`, `short`, `int`, `long`   |
+        | **Unsigned Integers** | `byte`, `ushort`, `uint`, `ulong` |
+        | **Floating Point**    | `float`, `double`                 |
+
+    === "Other"
+
+        | Category      | Types    |
+        | ------------- | -------- |
+        | **Boolean**   | `bool`   |
+        | **Character** | `char`   |
+        | **String**    | `string` |
+
+    For enums, Unity types, and other complex types, use the `Expression` property.
+
+<!-- markdownlint-enable MD046 -->
+
+##### Examples by type
+
+```csharp
+[DxAutoConstructor]
+public readonly partial struct TypeExamples
+{
+    // Boolean
+    [DxOptionalParameter(true)]
+    public readonly bool isEnabled;
+
+    // Character
+    [DxOptionalParameter('X')]
+    public readonly char grade;
+
+    // String
+    [DxOptionalParameter("unknown")]
+    public readonly string playerName;
+
+    // Signed integers
+    [DxOptionalParameter((sbyte)-1)]
+    public readonly sbyte signedByte;
+
+    [DxOptionalParameter((short)100)]
+    public readonly short shortValue;
+
+    [DxOptionalParameter(42)]
+    public readonly int score;
+
+    [DxOptionalParameter(9999999999L)]
+    public readonly long bigNumber;
+
+    // Unsigned integers
+    [DxOptionalParameter((byte)255)]
+    public readonly byte level;
+
+    [DxOptionalParameter((ushort)1000)]
+    public readonly ushort maxHealth;
+
+    [DxOptionalParameter(50u)]
+    public readonly uint count;
+
+    [DxOptionalParameter(100UL)]
+    public readonly ulong totalPoints;
+
+    // Floating point
+    [DxOptionalParameter(1.5f)]
+    public readonly float speed;
+
+    [DxOptionalParameter(3.14159)]
+    public readonly double precision;
+}
 ```
 
-###### Supported default value types
+#### Using Type Defaults
 
-- Numeric types: `int`, `uint`, `long`, `ulong`, `short`, `ushort`, `byte`, `sbyte`, `float`, `double`
-- Text types: `char`, `string`
-- Boolean: `bool`
+When you use `[DxOptionalParameter]` without a value, the field defaults to the type's default value:
 
 ```csharp
-[DxOptionalParameter(42)]        // int default
-public readonly int score;
+[DxAutoConstructor]
+public readonly partial struct DefaultExamples
+{
+    [DxOptionalParameter]  // Defaults to 0
+    public readonly int count;
+
+    [DxOptionalParameter]  // Defaults to false
+    public readonly bool isActive;
 
-[DxOptionalParameter("unknown")] // string default
-public readonly string playerName;
+    [DxOptionalParameter]  // Defaults to null
+    public readonly string name;
 
-[DxOptionalParameter(true)]      // bool default
-public readonly bool isActive;
+    [DxOptionalParameter]  // Defaults to 0.0f
+    public readonly float multiplier;
+}
 ```
 
-###### Advanced: Custom expressions for any type
+#### Advanced: Custom Expressions for Any Type
 
-For types that don't have built-in support (like enums, nullables, or custom structs), use the `Expression` property:
+For types that don't have built-in constructor overloads (enums, nullables, Unity types, custom structs), use the `Expression` property. The expression is inserted verbatim into the generated constructor, and the C# compiler enforces type safety:
 
 ```csharp
 [DxAutoConstructor]
-public readonly partial struct ComplexMessage
+public readonly partial struct AdvancedDefaults
 {
+    // Nullable types
     [DxOptionalParameter(Expression = "null")]
-    public readonly string? optionalName;
+    public readonly int? optionalId;
 
+    // Enum values
     [DxOptionalParameter(Expression = "DamageType.Physical")]
-    public readonly DamageType type;
+    public readonly DamageType damageType;
 
+    // Unity types
     [DxOptionalParameter(Expression = "Vector3.zero")]
     public readonly Vector3 position;
+
+    [DxOptionalParameter(Expression = "Color.white")]
+    public readonly Color tint;
+
+    // Static constants
+    [DxOptionalParameter(Expression = "float.MaxValue")]
+    public readonly float range;
+
+    // Named constants from your code
+    [DxOptionalParameter(Expression = "GameConstants.DefaultHealth")]
+    public readonly int health;
+}
+```
+
+<!-- markdownlint-disable MD046 -->
+
+!!! tip "Expression rules"
+
+    - The expression is inserted **verbatim** into the generated code
+    - Must be a valid C# constant expression
+    - Type safety is enforced by the C# compiler at build time
+    - Perfect for enums, nullable types, static constants, or complex defaults
+
+<!-- markdownlint-enable MD046 -->
+
+#### Code Examples
+
+#### Example 1: Basic Optional Parameter with Default Value
+
+```csharp
+[DxTargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct Heal
+{
+    public readonly int amount;
+    [DxOptionalParameter(false)]
+    public readonly bool isCritical;
+}
+
+// Usage:
+var normalHeal = new Heal(25);             // isCritical = false
+var critHeal = new Heal(50, true);         // isCritical = true
+```
+
+#### Example 2: Multiple Optional Parameters
+
+```csharp
+[DxBroadcastMessage]
+[DxAutoConstructor]
+public readonly partial struct SpawnEffect
+{
+    [DxOptionalParameter(1.0f)]
+    public readonly float scale;
+
+    [DxOptionalParameter(Expression = "Color.white")]
+    public readonly Color color;
+
+    [DxOptionalParameter(5.0f)]
+    public readonly float duration;
+
+    [DxOptionalParameter(false)]
+    public readonly bool looping;
+}
+
+// Usage:
+var defaultEffect = new SpawnEffect();                          // All defaults
+var largeEffect = new SpawnEffect(2.5f);                        // Custom scale
+var redEffect = new SpawnEffect(1.0f, Color.red);               // Custom color
+var customEffect = new SpawnEffect(1.5f, Color.blue, 10f, true); // All custom
+```
+
+#### Example 3: Mix of Required and Optional Fields
+
+```csharp
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct GameEvent
+{
+    // Required fields (must be provided)
+    public readonly string eventName;
+    public readonly int playerId;
+
+    // Optional fields (have defaults)
+    [DxOptionalParameter(0)]
+    public readonly int score;
+
+    [DxOptionalParameter("")]
+    public readonly string metadata;
+
+    [DxOptionalParameter(Expression = "System.DateTime.UtcNow")]
+    public readonly System.DateTime timestamp;
 }
+
+// Usage:
+var minimalEvent = new GameEvent("LevelStart", 1);
+var scoredEvent = new GameEvent("EnemyKilled", 1, 100);
+var fullEvent = new GameEvent("Achievement", 1, 500, "first_blood");
 ```
 
-###### How it works
+#### Example 4: Game Settings Message
+
+```csharp
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct AudioSettingsChanged
+{
+    [DxOptionalParameter(1.0f)]
+    public readonly float masterVolume;
+
+    [DxOptionalParameter(0.8f)]
+    public readonly float musicVolume;
+
+    [DxOptionalParameter(1.0f)]
+    public readonly float sfxVolume;
+
+    [DxOptionalParameter(true)]
+    public readonly bool muteWhenUnfocused;
+}
+
+// Apply all defaults
+audioSettings.Emit();
+
+// Only change music volume
+new AudioSettingsChanged(musicVolume: 0.5f).Emit();
+
+// Change multiple settings
+new AudioSettingsChanged(0.7f, 0.6f, 0.9f, false).Emit();
+```
+
+#### Best Practices
+
+<!-- markdownlint-disable MD046 -->
+
+!!! success "Recommendations"
+
+    1. **Order matters** — Place required fields before optional fields in your struct
+    1. **Use meaningful defaults** — Choose defaults that represent the most common use case
+    1. **Prefer explicit values** — Use `[DxOptionalParameter(0)]` instead of `[DxOptionalParameter]` when clarity helps
+    1. **Use Expression for complex types** — Don't fight the type system; use `Expression` for enums and Unity types
+    1. **Document unusual defaults** — If a default isn't obvious, add a comment explaining why
 
-- The expression is inserted verbatim into the generated constructor
-- The C# compiler validates type safety automatically
-- Perfect for enums, nullable types, static constants, or complex defaults
+<!-- markdownlint-enable MD046 -->
 
 ## Why Use Attributes Instead of Manual Implementation
 
@@ -218,7 +457,7 @@ public readonly partial struct Heal : ITargetedMessage<Heal>
 
 - ✅ **Less code** - 50% fewer lines
 - ✅ **Fewer bugs** - Can't forget fields in constructor
-- ✅ **Cleaner** - Focus on data, not boilerplate
+- ✅ **Focused** - Focus on data, not boilerplate
 - ✅ **Refactor-safe** - Add field? Constructor updates automatically!
 
 ## Complete Example: Attribute Definition vs Generated Output
@@ -397,21 +636,106 @@ msg.Emit(testBus);
 
 ## Attributes Quick Reference
 
-| Attribute               | Purpose                              | Example                                                               |
-| ----------------------- | ------------------------------------ | --------------------------------------------------------------------- |
-| `[DxUntargetedMessage]` | Mark as global message               | `[DxUntargetedMessage]`                                               |
-| `[DxTargetedMessage]`   | Mark as targeted message             | `[DxTargetedMessage]`                                                 |
-| `[DxBroadcastMessage]`  | Mark as broadcast message            | `[DxBroadcastMessage]`                                                |
-| `[DxAutoConstructor]`   | Generate constructor                 | `[DxAutoConstructor]`                                                 |
-| `[DxOptionalParameter]` | Make parameter optional (default)    | `[DxOptionalParameter] public readonly bool flag;`                    |
-| `[DxOptionalParameter]` | Make parameter optional (custom)     | `[DxOptionalParameter(42)] public readonly int count;`                |
-| `[DxOptionalParameter]` | Make parameter optional (expression) | `[DxOptionalParameter(Expression = "null")] public readonly string?;` |
+### Message Type Attributes
+
+<!-- markdownlint-disable MD046 -->
+
+=== "Untargeted"
+
+    Mark as a global message (no target):
+
+    ```csharp
+    [DxUntargetedMessage]
+    public readonly partial struct GamePaused { }
+    ```
+
+=== "Targeted"
+
+    Mark as a message sent to a specific target:
+
+    ```csharp
+    [DxTargetedMessage]
+    public readonly partial struct Heal
+    {
+        public readonly int amount;
+    }
+    ```
+
+=== "Broadcast"
+
+    Mark as a message broadcast from a source:
+
+    ```csharp
+    [DxBroadcastMessage]
+    public readonly partial struct TookDamage
+    {
+        public readonly int amount;
+    }
+    ```
+
+<!-- markdownlint-enable MD046 -->
+
+### Constructor Generation Attributes
+
+#### `[DxAutoConstructor]`
 
-### Works with
+Automatically generates a constructor with all public fields as parameters:
 
-- Top-level types (public structs/classes)
-- Nested types (types inside other classes)
-- Internal types (assembly-private messages)
+```csharp
+[DxAutoConstructor]
+public readonly partial struct Damage
+{
+    public readonly int amount;
+    public readonly string type;
+}
+// Generates: Damage(int amount, string type)
+```
+
+#### `[DxOptionalParameter]`
+
+Makes a constructor parameter optional. Three usage patterns:
+
+<!-- markdownlint-disable MD046 -->
+
+??? example "Default Value (type default)"
+
+    Uses the type's default value (`0`, `false`, `null`, etc.):
+
+    ```csharp
+    [DxOptionalParameter]
+    public readonly bool flag;
+    // Generates: bool flag = default
+    ```
+
+??? example "Custom Value (primitive)"
+
+    Provides a specific default value:
+
+    ```csharp
+    [DxOptionalParameter(42)]
+    public readonly int count;
+    // Generates: int count = 42
+    ```
+
+??? example "Expression (complex types)"
+
+    Uses a verbatim expression for enums, Unity types, etc.:
+
+    ```csharp
+    [DxOptionalParameter(Expression = "DamageType.Physical")]
+    public readonly DamageType damageType;
+    // Generates: DamageType damageType = DamageType.Physical
+    ```
+
+<!-- markdownlint-enable MD046 -->
+
+### Supported Types
+
+These attributes work with:
+
+- **Top-level types** — public structs and classes
+- **Nested types** — types inside other classes
+- **Internal types** — assembly-private messages
 
 ## Common Patterns with Attributes
 
@@ -565,8 +889,8 @@ public readonly partial struct MyMessage : IUntargetedMessage<MyMessage>
 **Yes!** In Visual Studio/Rider:
 
 1. Right-click on the message type
-   $11. Select "Go to Implementation" or "Go to Definition"
-   $11. You'll see the auto-generated file
+1. Select "Go to Implementation" or "Go to Definition"
+1. You'll see the auto-generated file
 
 **Or** check your `obj/` folder for `.g.cs` files.
 
@@ -612,58 +936,62 @@ public readonly partial struct MessageA
 
 ## Troubleshooting Source Generators
 
-### "Attributes not working / code not generated"
+<!-- markdownlint-disable MD046 -->
 
-#### Checklist
+??? warning "Attributes not working / code not generated"
 
-1. ✅ Is type marked `partial`?
-1. ✅ Did you rebuild the project?
-1. ✅ Is Unity 2021.3+ (Roslyn source generator support)?
-1. ✅ Check `obj/` folder for `.g.cs` files
+    ### Checklist
 
-##### Fix
+    1. ✅ Is type marked `partial`?
+    1. ✅ Did you rebuild the project?
+    1. ✅ Is Unity 2021.3+ (Roslyn source generator support)?
+    1. ✅ Check `obj/` folder for `.g.cs` files
 
-```csharp
-// ❌ Missing partial, will not compile
-[DxAutoConstructor]
-public readonly struct MyMsg { }
+    #### Fix
 
-// ✅ Correct
-[DxAutoConstructor]
-public readonly partial struct MyMsg { }
-```
+    ```csharp
+    // ❌ Missing partial, will not compile
+    [DxAutoConstructor]
+    public readonly struct MyMsg { }
 
-### "Constructor not generated"
+    // ✅ Correct
+    [DxAutoConstructor]
+    public readonly partial struct MyMsg { }
+    ```
 
-**Cause:** No public fields to generate from
+??? warning "Constructor not generated"
 
-```csharp
-// ❌ No public fields
-[DxAutoConstructor]
-public readonly partial struct Empty { }
+    **Cause:** No public fields to generate from
 
-// ✅ Has public field
-[DxAutoConstructor]
-public readonly partial struct WithData {
-    public readonly int value;
-}
-```
+    ```csharp
+    // ❌ No public fields
+    [DxAutoConstructor]
+    public readonly partial struct Empty { }
+
+    // ✅ Has public field
+    [DxAutoConstructor]
+    public readonly partial struct WithData {
+        public readonly int value;
+    }
+    ```
+
+??? warning "Unity can't find generated code"
 
-### "Unity can't find generated code"
+    ##### Solution
 
-#### Solution
+    1. Close Unity
+    1. Delete `Library/` folder
+    1. Reopen Unity
+    1. Let it reimport everything
 
-1. Close Unity
-1. Delete `Library/` folder
-1. Reopen Unity
-1. Let it reimport everything
+<!-- markdownlint-enable MD046 -->
 
 ## Related Documentation
 
-- **[API Reference](Reference.md)** — Complete API documentation
-- **[Message Types](MessageTypes.md)** — When to use Untargeted/Targeted/Broadcast
-- **[Quick Reference](QuickReference.md)** — Cheat sheet
-- **[Design & Architecture](DesignAndArchitecture.md)** — How source generation works internally
+- **[API Reference](reference.md)** — Complete API documentation
+- **[Message Types](../concepts/message-types.md)** — When to use Untargeted/Targeted/Broadcast
+- **[Quick Reference](quick-reference.md)** — Cheat sheet
+- **[Design & Architecture](../architecture/design-and-architecture.md)** — How source generation works internally
 
 ## Summary
 
@@ -682,4 +1010,4 @@ public readonly partial struct WithData {
 - ✅ Explicit control
 - ✅ Understanding exactly what happens
 
-**Best practice:** Start with attributes (they cover 99% of cases), switch to manual only when needed!
+**Recommendation:** Start with attributes (they cover most cases), switch to manual only when needed.

package/docs/reference/helpers.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: b0acf41d45fbf7d4a87de97d414daf03
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: