|
| 1 | +# CueCustomParametersResolver |
| 2 | + |
| 3 | +> **Type:** `Gamesmiths.Forge.Statescript.Properties.CueCustomParametersResolver` |
| 4 | +> **Output Type:** `Dictionary<StringKey, object>` |
| 5 | +
|
| 6 | +Produces the custom parameter bag attached to a cue's `CueParameters.CustomParameters` when a graph fires a cue. It delegates to an `ICueCustomParametersProvider`, which builds a dictionary keyed by `StringKey` from the current graph state. Bind it to the optional **Custom Parameters** input of [ExecuteCueNode](../nodes/action/execute-cue-node.md), [UpdateCueNode](../nodes/action/update-cue-node.md), and [CueNode](../nodes/state/cue-node.md). |
| 7 | + |
| 8 | +A cue handler then reads the values back by key from the `CueParameters` it receives. This is the cue-side analog of [EffectContextDataResolver](effect-context-data-resolver.md): instead of producing an `EffectApplicationContext` for the effect pipeline, it produces the parameter dictionary the cue handler consumes. |
| 9 | + |
| 10 | +## Constructor |
| 11 | + |
| 12 | +```csharp |
| 13 | +new CueCustomParametersResolver(provider) |
| 14 | +``` |
| 15 | + |
| 16 | +| Parameter | Type | Description | |
| 17 | +|-----------|------|-------------| |
| 18 | +| provider | `ICueCustomParametersProvider` | The provider that builds the custom parameter bag from the graph state. | |
| 19 | + |
| 20 | +## Defining a provider |
| 21 | + |
| 22 | +Derive from `CueCustomParametersProvider` and override `CreateCustomParameters`. Return a `Dictionary<StringKey, object>` whose keys are whatever your cue handler reads back. |
| 23 | + |
| 24 | +```csharp |
| 25 | +public sealed class DamageCueParametersProvider : CueCustomParametersProvider |
| 26 | +{ |
| 27 | + public override Dictionary<StringKey, object> CreateCustomParameters( |
| 28 | + GraphContext graphContext, |
| 29 | + CueCustomParameterInputs inputs) |
| 30 | + { |
| 31 | + graphContext.TryResolve("damage", out int damage); |
| 32 | + graphContext.TryResolve("isCritical", out bool isCritical); |
| 33 | + |
| 34 | + return new Dictionary<StringKey, object> |
| 35 | + { |
| 36 | + ["damage"] = damage, |
| 37 | + ["isCritical"] = isCritical, |
| 38 | + }; |
| 39 | + } |
| 40 | +} |
| 41 | +``` |
| 42 | + |
| 43 | +The same keys are then available in the cue handler: |
| 44 | + |
| 45 | +```csharp |
| 46 | +public void OnExecute(IForgeEntity? target, CueParameters? parameters) |
| 47 | +{ |
| 48 | + if (parameters?.CustomParameters is { } custom && custom.TryGetValue("damage", out object? damage)) |
| 49 | + { |
| 50 | + var amount = (int)damage; |
| 51 | + // ... |
| 52 | + } |
| 53 | +} |
| 54 | +``` |
| 55 | + |
| 56 | +## Declaring authored inputs |
| 57 | + |
| 58 | +Instead of reading values from named graph variables, a provider can declare **inputs** that the graph editor renders as nested resolvers directly on the node's Custom Parameters section. Override `Inputs` and read the resolved values from the `CueCustomParameterInputs` bag: |
| 59 | + |
| 60 | +```csharp |
| 61 | +public sealed class StrengthCueParametersProvider : CueCustomParametersProvider |
| 62 | +{ |
| 63 | + public override IReadOnlyList<CueCustomParameterInput> Inputs => |
| 64 | + [new CueCustomParameterInput("Strength", typeof(int))]; |
| 65 | + |
| 66 | + public override Dictionary<StringKey, object> CreateCustomParameters( |
| 67 | + GraphContext graphContext, |
| 68 | + CueCustomParameterInputs inputs) |
| 69 | + { |
| 70 | + return new Dictionary<StringKey, object> { ["strength"] = inputs.Get<int>("Strength") }; |
| 71 | + } |
| 72 | +} |
| 73 | +``` |
| 74 | + |
| 75 | +Each declared input renders its own resolver dropdown (constant, variable, activation data, math, ...) in the editor, so a designer can author the value without touching graph variables. `CueCustomParameterInputs.Get<T>` reads the resolved value (`default` when no resolver is bound); declared input value types must be supported by `Variant128`. The same `Name` is used both as the editor label and as the key passed to `Get<T>`. A provider that needs object-lane values (entities, tags) is not limited by this: it can read them directly from `graphContext` and box them into the bag. |
| 76 | + |
| 77 | +## Behavior |
| 78 | + |
| 79 | +- On each resolve, calls `provider.CreateCustomParameters(graphContext, inputs)`, which builds a fresh dictionary. Declared inputs are resolved lazily from the bag as the provider reads them. |
| 80 | +- The node resolves the bag once per execution and shares the same dictionary across the whole `cueTag[] x target[]` matrix, attaching it to the `CueParameters.CustomParameters` of every fired cue. |
| 81 | +- When the **Custom Parameters** input is unbound, cues fire without custom parameters (the dictionary is `null`). |
| 82 | + |
| 83 | +## Usage |
| 84 | + |
| 85 | +```csharp |
| 86 | +graph.VariableDefinitions.DefineObjectProperty( |
| 87 | + "damageParams", |
| 88 | + new CueCustomParametersResolver(new DamageCueParametersProvider())); |
| 89 | + |
| 90 | +var executeCue = new ExecuteCueNode(); |
| 91 | +executeCue.BindInput(ExecuteCueNode.CueTagInput, "hitCue"); |
| 92 | +executeCue.BindInput(ExecuteCueNode.TargetInput, "target"); |
| 93 | +executeCue.BindInput(ExecuteCueNode.CustomParametersInput, "damageParams"); |
| 94 | +``` |
| 95 | + |
| 96 | +## See Also |
| 97 | + |
| 98 | +- [Resolvers Overview](README.md) |
| 99 | +- [EffectContextDataResolver](effect-context-data-resolver.md) |
| 100 | +- [ExecuteCueNode](../nodes/action/execute-cue-node.md) |
| 101 | +- [UpdateCueNode](../nodes/action/update-cue-node.md) |
| 102 | +- [CueNode](../nodes/state/cue-node.md) |
0 commit comments