Universal Gameplay Ability System Specification

flowchart TB
    accTitle: The four UGAS pillars
    accDescr: Inside the Gameplay Controller, the data, semantic, and logic layers connect to the mutation layer.
    subgraph GC[Gameplay Controller]
        Data["Data layer<br/>Attributes<br/>Attribute Sets"]
        Semantic["Semantic layer<br/>Gameplay Tags<br/>Tag Containers"]
        Logic["Logic layer<br/>Gameplay Abilities<br/>Ability Tasks"]
        Mutation["Mutation layer<br/>Gameplay Effects<br/>Modifiers<br/>Execution Calcs"]
        Data --> Mutation
        Semantic --> Mutation
        Logic --> Mutation
    end

flowchart TB
    accTitle: UGAS component relationships
    accDescr: The owner owns the Gameplay Controller and the avatar possesses it. The controller contains attribute sets, ability specs, a tag container, and active effects. Abilities use tasks and effects carry modifiers.
    Avatar["Actor (Avatar)"] -->|possesses| GC[Gameplay Controller]
    Owner[Owner Actor] ---|owns| GC
    GC ---|contains| Attributes[Attribute Sets]
    GC --> Abilities["Abilities (Specs)"]
    GC --> Tags["Tags (Container)"]
    GC --> Effects["Effects (Active)"]
    Abilities --> Tasks
    Effects --> Modifiers

interface IAbilitySystemInterface {
  /**
   * Returns the Gameplay Controllerassociated with this entity.
   * @returns The GC instance, or null if not available
   */
  GetGameplayController(): GameplayController | null;
}

struct Attribute {
  /** Permanent value, modified only by Instant effects */
  BaseValue: float;

  /** Dynamically calculated value including all active modifiers */
  CurrentValue: float;

  /** Collection of active modifiers affecting this attribute */
  Modifiers: ModifierStack;

  /** Static configuration for this attribute */
  Metadata: AttributeMetadata;
}

struct AttributeMetadata {
  /** Unique identifier for this attribute */
  Name: string;

  /** Attribute category */
  Category: AttributeCategory;

  /** Minimum allowed value (optional) */
  MinValue?: float | AttributeReference;

  /** Maximum allowed value (optional) */
  MaxValue?: float | AttributeReference;

  /** Replication configuration */
  ReplicationMode: AttributeReplicationMode;
}

enum AttributeCategory {
  /** Consumable values (Health, Mana, Stamina) */
  Resource,

  /** Derived statistics (Damage, Defense, Speed) */
  Statistic,

  /** Meta-attributes used for calculations only */
  Meta
}

Clamping:
  Min: 0.0
  Max: 100.0

Clamping:
  Min: 0.0
  Max: "MaxHealth"  # References another attribute

Attribute:
  Name: string              # Required: Unique identifier
  DefaultBaseValue: float   # Required: Initial base value
  Category: enum            # Optional: Resource | Statistic | Meta
  Clamping:                 # Optional: Value constraints
    Min: float | string     # Static value or attribute reference
    Max: float | string     # Static value or attribute reference
  ReplicationMode: enum     # Optional: None | OwnerOnly | All
  Metadata:                 # Optional: Additional configuration
    DisplayName: string     # Human-readable name
    Description: string     # Tooltip description
    UICategory: string      # UI grouping

/**
 * Registers an attribute set with this GC.
 * @param attributeSet - The set to register
 */
GC.RegisterAttributeSet(attributeSet: AttributeSet): void;

/**
 * Unregisters an attribute set from this GC.
 * @param attributeSet - The set to unregister
 */
GC.UnregisterAttributeSet(attributeSet: AttributeSet): void;

/**
 * Retrieves a registered attribute set by type.
 * @returns The attribute set, or null if not registered
 */
GC.GetAttributeSet<T extends AttributeSet>(): T | null;

$schema: https://ugas.jbltx.com/dev-5edc54d/schemas/attribute_set.json
Name: "DerivedStatsSet"
Dependencies:
  - "CombatAttributeSet"
Attributes:
  - Name: "EffectiveHealth"
    DefaultBaseValue: 0.0
    Category: Meta
    DerivedFrom:
      Expression: "Health * (1 + Defense / 100)"

AttributeSet:
  Name: string                    # Required: Unique set identifier
  Dependencies: [string]          # Optional: Required attribute sets
  Attributes: [Attribute]         # Required: List of attributes
  Metadata:                       # Optional: Additional configuration
    DisplayName: string
    Description: string

Category.Subcategory.Leaf

AddTag("State.Debuff.Stunned.Magic")
  ExplicitTagCounts["State.Debuff.Stunned.Magic"] = 1
  AllTagCounts["State.Debuff.Stunned.Magic"]      = 1
  AllTagCounts["State.Debuff.Stunned"]             = 1  ← propagated
  AllTagCounts["State.Debuff"]                     = 1  ← propagated
  AllTagCounts["State"]                            = 1  ← propagated

AddTag("State.Debuff.Stunned.Magic")  # second effect grants same tag
  ExplicitTagCounts["State.Debuff.Stunned.Magic"] = 2
  AllTagCounts["State.Debuff.Stunned.Magic"]      = 2
  AllTagCounts["State.Debuff.Stunned"]             = 2
  AllTagCounts["State.Debuff"]                     = 2
  AllTagCounts["State"]                            = 2

RemoveTag("State.Debuff.Stunned.Magic")  # first effect expires
  ExplicitTagCounts["State.Debuff.Stunned.Magic"] = 1  # still present!
  AllTagCounts["State.Debuff.Stunned.Magic"]      = 1
  AllTagCounts["State.Debuff.Stunned"]             = 1
  ...
  # MatchesTag("State.Debuff.Stunned") → still true, no event dispatched

RemoveTag("State.Debuff.Stunned.Magic")  # second effect expires
  ExplicitTagCounts["State.Debuff.Stunned.Magic"] = 0  # now absent
  AllTagCounts["State.Debuff.Stunned.Magic"]      = 0
  AllTagCounts["State.Debuff.Stunned"]             = 0
  ...
  # OnTagChanged dispatched for the leaf and each ancestor that hit 0

// Avoid this pattern
if (actor.isStunned && !actor.isImmune) { ... }

// Use tag queries
if (actor.Tags.MatchesTag("State.Debuff.Stunned") &&
    !actor.Tags.MatchesTag("Status.Immune.Stun")) { ... }

TagDefinition:
  Tag: string                     # Full hierarchical tag name
  Description: string             # Human-readable description
  AllowMultiple: boolean          # Can multiple instances exist? (default: false)
  DevComment: string              # Developer notes

$schema: https://ugas.jbltx.com/dev-5edc54d/schemas/gameplay_tag.json
Tags:
  - Tag: "State.Debuff.Stunned"
    Description: "Actor is unable to perform actions"

  - Tag: "State.Debuff.Stunned.Magic"
    Description: "Stun caused by magical effect"

  - Tag: "State.Debuff.Stunned.Physical"
    Description: "Stun caused by physical impact"

  - Tag: "Status.Immune.Stun"
    Description: "Actor is immune to stun effects"

flowchart TB
    accTitle: Gameplay Ability lifecycle
    accDescr: Granting enables activation. Synchronous checks may fail or route to asynchronous confirmation or commit. Failed validation or commit returns to Granted. Successful commit enters Active; ending or cancellation returns through Ending to Granted.
    NotGranted -->|Grant| Granted
    Granted -->|TryActivate| Validating["Validating<br/>Synchronous checks"]
    Validating -->|Fail| Granted
    Validating -->|Pass| AsyncRequired{"Async required?"}
    AsyncRequired -->|Yes| PendingConfirmation
    AsyncRequired -->|No| Commit[Recheck + Commit]
    PendingConfirmation -->|Fail / cancel| Granted
    PendingConfirmation -->|Success| Commit
    Commit -->|Fail| Granted
    Commit -->|Success| Active
    Active -->|End / Cancel| Ending
    Ending --> Granted

function CanActivateAbility(spec: AbilitySpec): boolean {
  if (!IsStillGranted(spec) || HasConflictingActiveOrPendingAttempt(spec)) return false;
  const ownerTags = GC.GetOwnedTags();

  // Check required tags
  if (!ownerTags.HasAll(spec.AbilityClass.ActivationRequiredTags)) {
    return false;
  }

  // Check blocked tags
  if (ownerTags.HasAny(spec.AbilityClass.ActivationBlockedTags)) {
    return false;
  }

  // Check cooldown
  if (ownerTags.MatchesTag(GetCooldownTag(spec))) {
    return false;
  }

  // Check cost
  if (!CanAffordCost(spec)) {
    return false;
  }

  return true;
}

function CommitAbility(spec: AbilitySpec): boolean {
  // Internal GC transaction: defer callbacks until the attempt is terminal (§8.8).
  // On any failure roll back staged effects and return false.
  const transaction = BeginCommitTransaction(spec);
  if (!RecheckMutableRequirements(spec, spec.AttemptId)) return transaction.Fail();
  // Apply cost
  if (spec.AbilityClass.CostEffect) {
    const costSpec = MakeOutgoingSpec(spec.AbilityClass.CostEffect, spec.Level);
    if (!transaction.StageEffect(costSpec)) return transaction.Fail();
  }

  // Apply cooldown
  if (spec.AbilityClass.CooldownEffect) {
    const cooldownSpec = MakeOutgoingSpec(spec.AbilityClass.CooldownEffect, spec.Level);
    if (!transaction.StageEffect(cooldownSpec)) return transaction.Fail();
  }

  // Grant activation tags via an auto-generated Infinite Effect.
  // Direct tag mutation is prohibited (§3.1); all tag state flows through Effects.
  if (!spec.AbilityClass.ActivationOwnedTags.IsEmpty()) {
    const ownedTagsSpec = MakeOwnedTagsEffect(spec.AbilityClass.ActivationOwnedTags, spec.Level);
    // On commit publish its handle as spec.ActiveOwnedTagsHandle.
    if (!transaction.StageOwnedTagsEffect(ownedTagsSpec)) return transaction.Fail();
  }

  return transaction.Commit();
}

function CancelAbility(handle: AbilitySpecHandle): void {
  const spec = GetAbilitySpec(handle);
  if (!spec.IsActive) return;

  // Remove activation tags by removing the Effect that granted them.
  // Direct tag mutation is prohibited (§3.1).
  if (spec.ActiveOwnedTagsHandle) {
    RemoveActiveGameplayEffect(spec.ActiveOwnedTagsHandle);
    spec.ActiveOwnedTagsHandle = undefined;
  }

  // Call ability's end handler
  spec.AbilityInstance.EndAbility(true /* wasCancelled */);

  // Cleanup active tasks
  CancelAllAbilityTasks(handle);

  spec.IsActive = false;
}

Ability:
  Name: string                    # Required: Unique identifier

  Tags:
    AbilityTags: [string]         # Tags describing this ability
    BlockedByTags: [string]       # Tags that block activation
    BlockAbilitiesWithTags: [string]  # Tags blocked while active
    CancelAbilitiesWithTags: [string] # Tags cancelled on activation
    ActivationRequiredTags: [string]  # Required for activation
    ActivationBlockedTags: [string]   # Block activation if present
    ActivationOwnedTags: [string]     # Granted while active

  Cost: string                    # Effect name for cost
  Cooldown: string                # Effect name for cooldown

  AsyncValidation:                # Optional: async server validation (§8.8)
    Required: boolean             # If true, route through PendingConfirmation
    Kind: string                  # AntiCheat | RemoteInventory | Entitlement | Custom
    TimeoutMs: number             # Positive monotonic ms; omitted uses finite adapter default
    Predicted: boolean            # If true, client may speculatively Activate (§13.8)

  Tasks:                          # Sequential task definitions
    - Type: string                # Task type name
      Params: object              # Task-specific parameters

  Metadata:
    DisplayName: string
    Description: string
    Icon: string

struct GameplayEffect {
  /** Unique identifier */
  Name: string;

  /** Duration behavior */
  DurationPolicy: DurationPolicy;

  /** Duration value (if applicable) */
  Duration?: MagnitudeDefinition;

  /** Periodic execution settings */
  Period?: PeriodicSettings;

  /** Attribute modifications */
  Modifiers: Modifier[];

  /** Complex calculations */
  Executions: ExecutionCalculation[];

  /** Tags granted while active */
  GrantedTags: Tag[];

  /** Tags required on target for application */
  ApplicationRequiredTags: Tag[];

  /** Abilities granted while active */
  GrantedAbilities: AbilityGrant[];

  /** Execution policy for multiple instances */
  ExecutionPolicy: ExecutionPolicy;

  /**
   * Override conflict resolution priority.
   * When multiple active effects apply an Override modifier to the same
   * Attribute, the effect with the highest Priority value wins.
   * On equal Priority, last-applied wins (LIFO).
   * Defaults to 0. Negative values are valid.
   */
  Priority: integer;

  /** Gameplay cue tags */
  GameplayCues: Tag[];
}

struct PeriodicSettings {
  /** Time between executions */
  Period: float;

  /** Execute immediately on application? */
  ExecuteOnApplication: boolean;
}

$schema: https://ugas.jbltx.com/dev-5edc54d/schemas/gameplay_effect.json
Name: "GE_Poison"
DurationPolicy: HasDuration
Duration:
  Type: ScalableFloat
  Value: 10.0
Period:
  Period: 1.0
  ExecuteOnApplication: false
Modifiers:
  - Attribute: "Health"
    Operation: Add
    Magnitude:
      Type: ScalableFloat
      Value: -5.0  # 5 damage per second

abstract class ExecutionCalculation {
  /** Attributes to capture from source */
  SourceCaptureDefinitions: AttributeCapture[];

  /** Attributes to capture from target */
  TargetCaptureDefinitions: AttributeCapture[];

  /**
   * Whether this calculation may run inside a client-side prediction
   * (§13.4). Defaults to `true`. A calculation that consumes randomness
   * MUST either draw it from `context.RNG` (the deterministic, seeded
   * stream — see "Randomness in Execution Calculations" below) so it
   * stays predictable, or set this to `false` to declare that it
   * requires server authority and cannot be predicted. When `false`,
   * the activation that triggers this calculation MUST abort prediction
   * and fall back to server authority (§13.8.2) for the random outcome.
   */
  Predictable: boolean;  // default: true

  /** Perform the calculation */
  abstract Execute(
    source: CapturedAttributes,
    target: CapturedAttributes,
    context: EffectContext
  ): ModifierResult[];
}

struct AttributeCapture {
  Attribute: AttributeReference;
  CaptureTime: CaptureTime;  // OnApplication | OnExecution
}

class ExecCalc_PhysicalDamage extends ExecutionCalculation {
  SourceCaptureDefinitions = [
    { Attribute: "AttackPower", CaptureTime: OnExecution },
    { Attribute: "ArmorPenetration", CaptureTime: OnExecution }
  ];

  TargetCaptureDefinitions = [
    { Attribute: "Armor", CaptureTime: OnExecution }
  ];

  Execute(source, target, context): ModifierResult[] {
    const attackPower = source.Get("AttackPower");
    const armorPen = source.Get("ArmorPenetration");
    const targetArmor = target.Get("Armor");

    const effectiveArmor = Math.max(0, targetArmor - armorPen);
    const damageReduction = effectiveArmor / (effectiveArmor + 100);
    const finalDamage = attackPower * (1 - damageReduction);

    return [{
      Attribute: "Health",
      Operation: Add,
      Magnitude: -finalDamage
    }];
  }
}

interface DeterministicRNG {
  /** Next uniform float in [0, 1). Advances the stream by one draw. */
  NextFloat(): float;

  /**
   * Next integer in [minInclusive, maxExclusive). Rejection sampling can
   * consume multiple raw draws; all of them advance the stored cursor.
   * Bounds are signed 32-bit integers, with maxExclusive also allowing 2^31.
   * Invalid bounds fail before consuming a draw.
   */
  NextInt(minInclusive: int, maxExclusive: int): int;
}

$schema: https://ugas.jbltx.com/dev-5edc54d/schemas/gameplay_effect.json
Name: "GE_Burning"
DurationPolicy: HasDuration
Duration:
  Type: ScalableFloat
  Value: 5.0
GrantedTags:
  - "State.Debuff.Burning"
  - "State.Element.Fire"
Modifiers:
  - Attribute: "Health"
    Operation: Add
    Magnitude:
      Type: ScalableFloat
      Value: -10.0

$schema: https://ugas.jbltx.com/dev-5edc54d/schemas/gameplay_effect.json
Name: "GE_FireSword_Equipped"
DurationPolicy: Infinite
GrantedAbilities:
  - AbilityClass: "GA_FlameStrike"
    Level: 1
    InputID: "Ability.Weapon.Special"
    RemoveOnEffectRemoval: true

# GameplayEffect Definition Schema
type: object
required:
  - Name
  - DurationPolicy
properties:
  Name:
    type: string
    description: Unique effect identifier
  DurationPolicy:
    type: string
    enum:
      - Instant
      - HasDuration
      - Infinite
  Duration:
    type: object
    properties:
      Type:
        type: string
        enum:
          - ScalableFloat
          - AttributeBased
          - SetByCaller
      Value:
        type: number
  Period:
    type: object
    properties:
      Period:
        type: number
        minimum: 0
      ExecuteOnApplication:
        type: boolean
        default: false
  ExecutionPolicy:
    type: string
    enum:
      - RunInParallel
      - RunInSequence
      - RunInMerge
    default: RunInParallel
  Priority:
    type: integer
    default: 0
    description: Override conflict priority. Highest value wins when multiple Override modifiers target the same Attribute. Equal priority resolves by last-applied (LIFO).
  Modifiers:
    type: array
    items:
      type: object
      required:
        - Attribute
        - Operation
        - Magnitude
      properties:
        Attribute:
          type: string
        Operation:
          type: string
          enum:
            - Add
            - AddPost
            - Multiply
            - Override
        Magnitude:
          type: object
        Channel:
          type: string
          description: >
            Aggregation channel for Multiply modifiers. Modifiers sharing a
            Channel add their bonuses; channels multiply against each other.
            Omit to treat this modifier as an isolated singleton channel.
            Ignored on Add, AddPost, and Override operations.
  GrantedTags:
    type: array
    items:
      type: string
  GrantedAbilities:
    type: array
    items:
      type: object
      properties:
        AbilityClass:
          type: string
        Level:
          type: integer
          default: 1
        InputID:
          type: string
        RemoveOnEffectRemoval:
          type: boolean
          default: true
  GameplayCues:
    type: array
    items:
      type: string

stateDiagram-v2
    accTitle: Ability Task lifecycle
    accDescr: A task is instantiated from Inactive to Ready, then activated. Active tasks may tick, complete when triggered, or be cancelled when the ability is cancelled or the owner dies.
    Inactive --> Ready: Instantiate
    Ready --> Active: Activate
    Active --> Active: Tick (if needed)
    Active --> Completed: Trigger / Complete
    Active --> Cancelled: Cancel

class WaitForHealthThreshold extends AbilityTask {
  Threshold: float;
  Comparison: ComparisonType;  // LessThan | LessEqual | Greater | GreaterEqual

  OnActivate(): void {
    // Check immediately
    if (this.CheckThreshold()) {
      this.ThresholdReached.Broadcast();
      this.EndTask();
      return;
    }

    // Subscribe to attribute changes
    this.Owner.OnAttributeChanged.Subscribe("Health", this.OnHealthChanged);
  }

  OnHealthChanged(event: AttributeChangedEvent): void {
    if (this.CheckThreshold()) {
      this.ThresholdReached.Broadcast();
      this.EndTask();
    }
  }

  CheckThreshold(): boolean {
    const health = this.Owner.GetAttributeValue("Health");
    switch (this.Comparison) {
      case LessThan: return health < this.Threshold;
      case LessEqual: return health <= this.Threshold;
      case Greater: return health > this.Threshold;
      case GreaterEqual: return health >= this.Threshold;
    }
  }

  OnEndTask(): void {
    this.Owner.OnAttributeChanged.Unsubscribe("Health", this.OnHealthChanged);
  }
}

function EndAbility(wasCancelled: boolean): void {
  // Cancel all active tasks
  for (const task of this.ActiveTasks) {
    task.Cancel();
  }
  this.ActiveTasks.Clear();

  // Remove activation-owned tags by removing the Effect that granted them.
  // This is the normal (non-cancelled) end path; CancelAbility handles the cancel path.
  const spec = GC.GetAbilitySpec(this.Handle);
  if (spec?.ActiveOwnedTagsHandle) {
    GC.RemoveActiveGameplayEffect(spec.ActiveOwnedTagsHandle);
    spec.ActiveOwnedTagsHandle = undefined;
  }

  // Continue with ability end logic...
}

flowchart TB
    accTitle: Input integration pipeline
    accDescr: Device input passes through a modifier pipeline to an action identified by InputID, then through an action set context to ability activation.
    Device[Device Input] --> Modifiers[Modifier Pipeline]
    Modifiers --> Action["Action (InputID)"]
    Action --> ActionSet["Action Set (context)"]
    ActionSet --> Ability[Ability Activation]

Name: Fire
ValueType: Digital
TriggerBehavior: OnPressed
ConsumeInput: true
Tags:
  ActionTags:
    - Input.Type.Combat
Metadata:
  DisplayName: Fire Weapon
  Category: Combat

Name: OnFoot
Actions:
  - Move
  - Look
  - Fire
  - Aim
  - Reload
  - Jump
  - Sprint
Priority: 0
ActivationTags:
  RequiredTags:
    - State.Alive
  BlockedTags:
    - State.InVehicle
    - State.Cutscene
InputBuffer:
  Enabled: true
  BufferWindow: 0.12
  MaxBufferSize: 2

ActionSet: OnFoot
Platform: PC
Bindings:
  - Action: Fire
    Inputs:
      - Device: Mouse
        Input: Mouse.LeftButton

  - Action: Move
    CompositeInputs:
      Up:
        Device: Keyboard
        Input: Key.W
      Down:
        Device: Keyboard
        Input: Key.S
      Left:
        Device: Keyboard
        Input: Key.A
      Right:
        Device: Keyboard
        Input: Key.D

  - Action: Look
    Inputs:
      - Device: Mouse
        Input: Mouse.Axis.X
      - Device: Mouse
        Input: Mouse.Axis.Y
    Modifiers:
      - MouseSensitivity

Name: StickDeadzone
Type: DeadZone
Params:
  InnerThreshold: 0.15
  OuterThreshold: 0.95
  DeadZoneShape: Radial
UserConfigurable: true
Metadata:
  DisplayName: Stick Dead Zone

struct InputBufferConfig {
  /** Enable input buffering */
  Enabled: boolean;

  /** Buffer window in seconds */
  BufferWindow: float;

  /** Maximum buffered inputs */
  MaxBufferSize: number;
}

function ProcessBufferedInputs(actionSet: ActionSet): void {
  const config = actionSet.InputBuffer ?? this.GlobalBufferConfig;
  if (!config.Enabled) return;

  const now = GetCurrentTime();

  // Remove expired inputs
  this.InputBuffer = this.InputBuffer.filter(
    input => now - input.Timestamp < config.BufferWindow
  );

  // Process valid inputs
  for (const input of this.InputBuffer) {
    if (TryActivateAbilityByInputID(input.ActionName)) {
      break;  // Successfully activated, stop processing
    }
  }

  this.InputBuffer.Clear();
}

interface IInputMapper {
  /** Get the active bindings for an action */
  GetBindingsForAction(action: ActionName): Binding[];

  /** Remap a binding to a new device input */
  RemapBinding(action: ActionName, oldInput: DeviceInput, newInput: DeviceInput): void;

  /** Reset all bindings to defaults for an action set */
  ResetToDefaults(actionSet: ActionSetName): void;

  /** Save current mappings to persistent storage */
  SaveMappings(): void;

  /** Load saved mappings from persistent storage */
  LoadMappings(): void;
}

$schema: https://ugas.jbltx.com/dev-5edc54d/schemas/gameplay_effect.json
Name: "GE_FireDamage"
DurationPolicy: Instant
Modifiers:
  - Attribute: "Health"
    Operation: Add
    Magnitude:
      Type: ScalableFloat
      Value: -25.0
GameplayCues:
  - "GameplayCue.Impact.Fire"

class GC_Impact_Fire extends GameplayCueBurst {
  OnExecute(context: CueContext): void {
    SpawnParticleSystem("PS_FireImpact", context.HitLocation);
    PlaySound("SFX_FireImpact", context.HitLocation);
  }
}

class GC_Status_Burning extends GameplayCueLooping {
  private ParticleComponent: ParticleSystem;

  OnAdd(context: CueContext): void {
    this.ParticleComponent = SpawnLoopingParticle("PS_BurningLoop", context.Target);
    StartLoopingSound("SFX_BurningLoop", context.Target);
  }

  OnRemove(): void {
    this.ParticleComponent.Destroy();
    StopLoopingSound("SFX_BurningLoop");
  }
}

class GameplayCueManager {
  private CueRegistry: Map<Tag, GameplayCueClass>;
  private ActiveLoopingCues: Map<ActiveEffectHandle, GameplayCue[]>;

  HandleCueNotify(tag: Tag, context: CueContext, type: CueNotifyType): void {
    const cueClass = this.CueRegistry.get(tag);
    if (!cueClass) return;

    switch (type) {
      case Execute:
        const burstCue = this.InstantiateCue(cueClass);
        burstCue.OnExecute(context);
        break;

      case Add:
        const loopingCue = this.InstantiateCue(cueClass);
        loopingCue.OnAdd(context);
        this.ActiveLoopingCues.get(context.EffectHandle).push(loopingCue);
        break;

      case Remove:
        const activeCues = this.ActiveLoopingCues.get(context.EffectHandle);
        for (const cue of activeCues) {
          cue.OnRemove();
        }
        this.ActiveLoopingCues.delete(context.EffectHandle);
        break;
    }
  }
}

if (!IsHeadlessServer()) {
  this.CueManager = new GameplayCueManager();
  this.CueManager.LoadCueAssets();
}

sequenceDiagram
    accTitle: Server authority and client prediction
    accDescr: The server replicates its authoritative Gameplay Controller to the client proxy. The client predicts from local input and sends it to the server, which reconciles the client with authoritative state.
    participant Server as Server GC (Authority)
    participant Client as Client GC (Proxy)
    Server->>Client: Replicate
    Note over Client: Local input / prediction
    Client->>Server: Predicted input
    Server->>Client: Reconcile

function TryActivateAbility_Predicted(handle: AbilitySpecHandle): void {
  const request = NewActivationRequest(handle); // stable attempt ID, even without prediction
  if (CanPredict(request)) {
    const before = CaptureState();             // BEFORE cost, tags, tasks, or effects
    RegisterPrediction(request, before);
    if (!TryActivateAbility_Local(handle, request.Key)) {
      RestorePredictionState(before);          // undo partial speculative work, silently
      RetireLocalSpeculation(request);
    }
  }
  SubmitOnce(request); // authority fallback also submits; retransmits reuse the same ID
}

function OnAuthoritativeUpdate(update: PredictionUpdate): void {
  if (!ValidateEpochOwnerRevisionAndOutcomes(update)) return;
  AcceptTerminalOutcomes(update);              // once; receipt is not resolution
  const suffix = FindCompleteReplaySuffix(update);
  InstallAuthoritativeState(update.State);     // includes unrelated server-originated effects
  if (suffix == null || !WithinReplayBudget(suffix)) {
    DiscardSpeculationAndPresentation();
    AwaitResynchronization();                  // never replay a truncated history
    return;
  }
  for (const frame of suffix) {
    ReplayOwningGC(frame, update.Outcomes);    // original IDs; no RPCs or duplicate cues
  }
}

struct GCSnapshot {
  /** Monotonic snapshot version for forward-compatibility checks */
  Version: integer;

  /** Reference to the snapshotted GC */
  OwnerActorID: string;

  /** Wall-clock or game-time at capture */
  CaptureTimestamp: number;

  /** Base Values, keyed by AttributeSet then Attribute name */
  AttributeSets: SerializedAttributeSet[];

  /** Every active (non-Instant) effect */
  ActiveEffects: ActiveEffectRecord[];

  /** Granted abilities not sourced from an active effect */
  GrantedAbilities: SerializedAbilityGrant[];
}

struct ActiveEffectRecord {
  /** Unique handle — preserved across save/load for external references */
  Handle: string;

  /** Effect class identifier (references a GameplayEffect definition) */
  EffectClass: string;

  /** Duration policy of the originating effect */
  DurationPolicy: "HasDuration" | "Infinite";

  /** Effect level at time of application */
  Level: integer;

  /** GC that applied this effect */
  InstigatorGC: string;

  /** Ability that applied this effect (if any) */
  SourceAbility?: string;

  /** Remaining duration in seconds. Present only for HasDuration effects. */
  RemainingDuration?: number;

  /** Periodic execution state. Present only for periodic effects. */
  PeriodicState?: PeriodicExecutionState;

  /** Execution policy state for multi-instance effects */
  ExecutionPolicyState?: ExecutionPolicyState;

  /** Number of active instances (RunInParallel) or queued+active instances (RunInSequence) */
  InstanceCount: integer;

  /** Attribute values captured OnApplication (frozen at apply-time) */
  CapturedAttributes?: Map<string, number>;

  /** SetByCaller magnitudes set at application time */
  SetByCallerMagnitudes?: Map<string, number>;
}

function RestoreGC(gc: GameplayController, snapshot: GCSnapshot): void {
  // 1. Attributes
  for (const set of snapshot.AttributeSets) {
    const attrSet = gc.GetAttributeSet(set.Name);
    for (const attr of set.Attributes) {
      attrSet.SetBaseValue(attr.Name, attr.BaseValue);
    }
  }

  // 2. Active Effects — order matters for RunInSequence queues
  for (const record of snapshot.ActiveEffects) {
    const spec = ReconstructEffectSpec(record);
    gc.ApplyGameplayEffect(spec, {
      ResumeRemainingDuration: record.RemainingDuration,
      ResumePeriodicState: record.PeriodicState,
      RestoredHandle: record.Handle
    });
  }

  // 3. Non-effect-granted Abilities
  for (const grant of snapshot.GrantedAbilities) {
    gc.GrantAbility(grant.AbilityClass, grant.Level, grant.InputID);
  }

  // 4. Recompute
  gc.RecalculateAllAttributes();
}

function AdvanceOfflineTime(
  snapshot: GCSnapshot,
  currentTime: number
): void {
  const elapsed = currentTime - snapshot.CaptureTimestamp;

  for (const record of snapshot.ActiveEffects) {
    if (record.DurationPolicy === "HasDuration" && record.RemainingDuration != null) {
      record.RemainingDuration -= elapsed;
      if (record.RemainingDuration <= 0) {
        // Effect expired while offline — remove from snapshot before restore
        continue;
      }
    }
    if (record.PeriodicState) {
      record.PeriodicState.PeriodElapsed += elapsed;
    }
  }
}

Ability:
  Name: "GA_Fireball"

  Tags:
    AbilityTags:
      - "Ability.Type.Spell"
      - "Ability.Element.Fire"
    ActivationOwnedTags:
      - "State.Casting"
    CancelAbilitiesWithTags:
      - "State.Stunned"
    ActivationBlockedTags:
      - "State.Silenced"

  Cost: "GE_Fireball_Cost"
  Cooldown: "GE_Fireball_Cooldown"

class ExecCalc_ArmorPenetration extends ExecutionCalculation {
  SourceCaptureDefinitions = [
    { Attribute: "AttackPower", CaptureTime: OnExecution },
    { Attribute: "ArmorPenetrationFlat", CaptureTime: OnExecution },
    { Attribute: "ArmorPenetrationPercent", CaptureTime: OnExecution },
    { Attribute: "CriticalChance", CaptureTime: OnExecution },
    { Attribute: "CriticalDamage", CaptureTime: OnExecution }
  ];

  TargetCaptureDefinitions = [
    { Attribute: "Armor", CaptureTime: OnExecution },
    { Attribute: "DamageReduction", CaptureTime: OnExecution }
  ];

  Execute(source, target, context): ModifierResult[] {
    // Get source stats
    const attackPower = source.Get("AttackPower");
    const armorPenFlat = source.Get("ArmorPenetrationFlat");
    const armorPenPercent = source.Get("ArmorPenetrationPercent");
    const critChance = source.Get("CriticalChance");
    const critDamage = source.Get("CriticalDamage");

    // Get target stats
    const targetArmor = target.Get("Armor");
    const damageReduction = target.Get("DamageReduction");

    // Calculate effective armor
    const armorAfterFlat = Math.max(0, targetArmor - armorPenFlat);
    const effectiveArmor = armorAfterFlat * (1 - armorPenPercent);

    // Armor damage reduction formula
    const armorDR = effectiveArmor / (effectiveArmor + 100);

    // Base damage
    let damage = attackPower * (1 - armorDR);

    // Apply critical hit.
    // Draw from the deterministic, seeded stream (context.RNG) rather than a
    // bare RandomFloat(), so a predicting client and the server roll the same
    // crit and avoid a rollback. The stream is seeded from PredictionKey.Seed
    // (§13.8.1) and positioned at the activation Sub's shared cursor (§9.5.1); see the
    // "Randomness in Execution Calculations" rule in §9.5. (This calculation
    // stays Predictable; a roll that must be server-only would instead set
    // Predictable = false: check before speculative commit, or unwind and
    // await the SAME authoritative request if discovered later (§13.4).)
    if (context.RNG.NextFloat() < critChance) {
      damage *= critDamage;
      context.SetTag("Hit.Critical");
    }

    // Apply flat damage reduction
    damage *= (1 - damageReduction);

    return [{
      Attribute: "Health",
      Operation: Add,
      Magnitude: -damage
    }];
  }
}

struct SpatialAnchor {
  /**
   * The world position. The coordinate frame, units, and handedness are engine-defined; this
   * specification treats positions as opaque points and requires only that the §17.2 queries behave
   * as specified over them.
   */
  Position: Vector3;

  /** Optional facing, used by directional queries (cones, forward line-of-sight). Identity if absent. */
  Orientation?: Quaternion;

  /** The GC this anchor represents. */
  Owner: GameplayController;
}

/** Restricts a query's candidate set before distance/shape tests are applied. */
struct SpatialFilter {
  /** Candidate must own ALL of these tags (§7, hierarchical). Empty = no tag requirement. */
  RequireTags?: GameplayTag[];

  /** Candidate must own NONE of these tags. */
  ExcludeTags?: GameplayTag[];

  /**
   * Affiliation of the candidate relative to the querying GC, resolved by the implementation's team
   * model: Any | Allied | Hostile | Neutral | SelfOnly | ExcludeSelf.
   */
  Affiliation?: Affiliation;

  /** Hard cap on the number of results (0 = unbounded), combined with a query's own ordering. */
  MaxResults?: int;
}

interface SpatialQuery {
  /** Distance between two anchors (or anchor and point), in engine units. */
  Distance(a: SpatialAnchor | Vector3, b: SpatialAnchor | Vector3): float;

  /** Anchors whose position lies within `radius` of `center`, matching `filter`. */
  OverlapSphere(center: Vector3, radius: float, filter: SpatialFilter): SpatialAnchor[];

  /** Anchors within an oriented box, a capsule, or a forward cone (directional shapes use Orientation). */
  OverlapBox(center: Vector3, halfExtents: Vector3, orientation: Quaternion, filter: SpatialFilter): SpatialAnchor[];
  OverlapCapsule(p0: Vector3, p1: Vector3, radius: float, filter: SpatialFilter): SpatialAnchor[];
  OverlapCone(apex: Vector3, direction: Vector3, range: float, halfAngleDeg: float, filter: SpatialFilter): SpatialAnchor[];

  /** Whether `b` is visible from `a` with no occluder between them. Occlusion is engine-defined. */
  LineOfSight(a: Vector3, b: Vector3): boolean;

  /** The `count` nearest anchors to `center` matching `filter`, ordered nearest-first. */
  Nearest(center: Vector3, count: int, filter: SpatialFilter): SpatialAnchor[];
}

struct Region {
  /** Region identity, for authoring and debugging. */
  Name: string;

  /** The volume, as a §17.2 shape anchored in the world. */
  Shape: "Sphere" | "Box" | "Capsule";
  Origin: Vector3;             // sphere / box centre, or capsule reference point
  Radius?: float;              // Sphere and Capsule
  HalfExtents?: Vector3;       // Box
  Orientation?: Quaternion;    // Box
  P0?: Vector3; P1?: Vector3;  // Capsule endpoints

  /** Which GCs the region acts on (§17.2 SpatialFilter); empty = all spatial GCs. */
  Filter?: SpatialFilter;

  /** Tags granted to a GC while its anchor is inside the region; removed on exit. */
  GrantedTags: GameplayTag[];
}

struct PerceptionConfig {
  /** Maximum sense range; MAY be AttributeBased (§9.4.2), e.g. reduced while blinded. */
  Range: float;

  /** Forward field-of-view half-angle in degrees; omitted = omnidirectional. */
  FovHalfAngleDeg?: float;

  /** Require unobstructed line-of-sight (§17.2) to sense the target. */
  RequireLineOfSight: boolean;

  /** Which GCs are sensed (§17.2 SpatialFilter) — typically Hostile. */
  Filter: SpatialFilter;
}

struct Placement {
  /** The GameplayControllerConfig to instantiate (§4), by name. */
  Controller: string;

  /** Stable identity for this instance — the key for persistence (§14) and cross-references. */
  InstanceId?: string;

  /** Spawn pose. The Position becomes the instance's spatial anchor (§17.1). */
  Position?: Vector3;
  Rotation?: Quaternion;

  /** Tags granted to the instance on spawn (§7) — team, role, difficulty band, etc. */
  StartupTags?: GameplayTag[];

  /** Effects applied to the instance on spawn (§9) — starting buffs, passives, loadout. */
  StartupEffects?: string[];

  /** Base-value overrides applied after the controller's defaults (§5) — e.g. an elite's Health. */
  AttributeOverrides?: Map<string, number>;

  /** Whether the instance spawns active; false authors a dormant/pre-placed entity. Default true. */
  Enabled?: boolean;
}

struct Scene {
  /** Unique scene identifier. */
  Name: string;

  /** Parent scenes this one composes on top of, additively (§18.5). */
  Extends?: string[];

  /** Controller instances placed into the world. */
  Placements: Placement[];

  /** Standing zones active while the scene is loaded (§17.4). */
  Regions?: Region[];

  /** Named poses for dynamic spawning at runtime (§18.4). */
  SpawnPoints?: SpawnPoint[];
}

struct SpawnPoint {
  /** Spawn point identifier, referenced by spawning logic. */
  Name: string;

  Position: Vector3;
  Rotation?: Quaternion;

  /** Classification tags for selection — team, wave, encounter (§7). */
  Tags?: GameplayTag[];
}

https://ugas.jbltx.com/{version}/schemas/{schema-name}.json

# Gameplay Controller Interface Schema Definition
# Based on UGAS Specification dev-5edc54d - Section 4

type: object
required:
  - OwnerActor
  - AttributeSets
properties:
  OwnerActor:
    type: object
    description: Logical owner of the GC (responsible for lifecycle, network authority, persistence)
    properties:
      ActorID:
        type: string
        description: Unique identifier for the owner actor
      ActorType:
        type: string
        description: Type of the owner actor

  AvatarActor:
    type: object
    description: World spatial representation (optional, can be same as Owner)
    properties:
      ActorID:
        type: string
        description: Unique identifier for the avatar actor
      ActorType:
        type: string
        description: Type of the avatar actor

  AttributeSets:
    type: array
    items:
      type: object
      properties:
        Name:
          type: string
          description: AttributeSet identifier
        Attributes:
          type: array
          items:
            type: object
            properties:
              Name:
                type: string
              BaseValue:
                type: number
              CurrentValue:
                type: number
    minItems: 1
    description: Registered attribute containers

  GrantedAbilities:
    type: array
    items:
      type: object
      required:
        - AbilityClass
      properties:
        AbilityClass:
          type: string
          description: Ability class identifier
        Level:
          type: integer
          default: 1
          minimum: 1
          description: Ability level
        InputID:
          type: string
          description: >-
            Input binding identifier. References an Action Name from the input
            layer. When the bound Action triggers, the GC calls TryActivateAbility
            for this grant.
        Handle:
          type: string
          description: Unique handle for this granted ability instance
        bIsActive:
          type: boolean
          default: false
          description: Whether the ability is currently active
    description: All abilities granted to this GC

  ActiveEffects:
    type: array
    items:
      type: object
      required:
        - Handle
        - EffectClass
      properties:
        Handle:
          type: string
          description: Unique identifier for this active effect
        EffectClass:
          type: string
          description: GameplayEffect class reference
        DurationPolicy:
          type: string
          enum: [HasDuration, Infinite]
          description: Duration policy of the originating effect (§14.3)
        RemainingDuration:
          type: number
          description: >-
            Remaining duration in seconds. Present only for HasDuration
            effects (§14.3.1)
        Stacks:
          type: integer
          minimum: 1
          default: 1
          description: Number of effect stacks
        StartTime:
          type: number
          description: Timestamp when effect was applied
        Level:
          type: integer
          minimum: 1
          default: 1
        InstigatorGC:
          type: string
          description: Reference to the GC that caused this effect
        SourceAbility:
          type: string
          description: >-
            Ability that applied this effect (for provenance tracking,
            §14.3.2)
        PeriodicState:
          type: object
          description: >-
            Periodic execution state for effects with Period settings
            (§14.3.3)
          properties:
            PeriodElapsed:
              type: number
              description: Seconds elapsed since last periodic execution
            ExecutionCount:
              type: integer
              minimum: 0
              description: Total periodic executions fired
        CapturedAttributes:
          type: object
          additionalProperties:
            type: number
          description: >-
            Attribute values captured OnApplication, keyed by attribute
            name (§14.3)
        SetByCallerMagnitudes:
          type: object
          additionalProperties:
            type: number
          description: >-
            Runtime-provided magnitudes, keyed by data tag (§14.3)
    description: Currently active effects applied to this GC (serialization protocol §14)

  ActiveActionSets:
    type: array
    items:
      type: string
    description: Currently active ActionSet names (derived from tag evaluation at runtime)

  OwnedTags:
    type: array
    items:
      type: string
      pattern: "^[A-Z][a-zA-Z0-9]*(\\.[A-Z][a-zA-Z0-9]*)*$"
    description: Current semantic state tags (hierarchical dot notation)

  ReplicationMode:
    type: string
    enum: [Minimal, Mixed, Full, None]
    default: Mixed
    description: "Replication strategy: Minimal (only cues & tags for AI), Mixed (full to owner, minimal to others for players), Full (complete to all for single-player/spectators), None (no replication for server-only)"

  bIsActive:
    type: boolean
    default: true
    description: Whether this GC is currently active

  Metadata:
    type: object
    description: Optional metadata for display and debugging
    properties:
      DisplayName:
        type: string
      Description:
        type: string
      Tags:
        type: array
        items:
          type: string
      DebugCategory:
        type: string

# Attribute Definition Schema
# Based on UGAS Specification dev-5edc54d - Appendix B

type: object
required:
  - Name
  - DefaultBaseValue
properties:
  Name:
    type: string
    description: Unique identifier for this attribute
  DefaultBaseValue:
    type: number
    description: Initial base value
  Category:
    type: string
    enum: [Resource, Statistic, Meta]
    default: Statistic
  Clamping:
    type: object
    properties:
      Min:
        oneOf:
          - type: number
          - type: string
            description: Attribute reference
      Max:
        oneOf:
          - type: number
          - type: string
            description: Attribute reference
  ReplicationMode:
    type: string
    enum: [None, OwnerOnly, All]
    default: All
  Metadata:
    type: object
    properties:
      DisplayName:
        type: string
      Description:
        type: string
      UICategory:
        type: string
      Icon:
        type: string

# AttributeSet Definition Schema
# Based on UGAS Specification dev-5edc54d - Appendix B

type: object
required:
  - Name
  - Attributes
properties:
  Name:
    type: string
    description: Unique set identifier
  Dependencies:
    type: array
    items:
      type: string
    description: Required attribute sets
  Attributes:
    type: array
    items:
      $ref: "#/$defs/Attribute"
  Metadata:
    type: object
    properties:
      DisplayName:
        type: string
      Description:
        type: string

$defs:
  Attribute:
    type: object
    required:
      - Name
      - DefaultBaseValue
    properties:
      Name:
        type: string
        description: Unique identifier for this attribute
      DefaultBaseValue:
        type: number
        description: Initial base value
      Category:
        type: string
        enum: [Resource, Statistic, Meta]
        default: Statistic
      Clamping:
        type: object
        properties:
          Min:
            oneOf:
              - type: number
              - type: string
          Max:
            oneOf:
              - type: number
              - type: string
      ReplicationMode:
        type: string
        enum: [None, OwnerOnly, All]
        default: All
      Metadata:
        type: object
        properties:
          DisplayName:
            type: string
          Description:
            type: string
          UICategory:
            type: string
          Icon:
            type: string

# Ability Definition Schema
# Based on UGAS Specification dev-5edc54d - Appendix B

type: object
required:
  - Name
properties:
  Name:
    type: string
    description: Unique identifier for this ability
  Tags:
    type: object
    properties:
      AbilityTags:
        type: array
        items:
          type: string
        description: Tags that describe this ability
      BlockedByTags:
        type: array
        items:
          type: string
        description: Tags that prevent this ability from running
      BlockAbilitiesWithTags:
        type: array
        items:
          type: string
        description: While this ability is active, block abilities with these tags
      CancelAbilitiesWithTags:
        type: array
        items:
          type: string
        description: Cancel abilities with these tags when this ability activates
      ActivationRequiredTags:
        type: array
        items:
          type: string
        description: Tags required on the GC to activate this ability
      ActivationBlockedTags:
        type: array
        items:
          type: string
        description: Tags that block activation of this ability
      ActivationOwnedTags:
        type: array
        items:
          type: string
        description: Tags granted to the GC while this ability is active
  Cost:
    type: string
    description: Reference to cost GameplayEffect
  Cooldown:
    type: string
    description: Reference to cooldown GameplayEffect
  MaxRange:
    type: number
    minimum: 0
    description: "Maximum targeting range in engine units (§17.3). Absent or 0 means self-targeted / no range gate; a target-requiring activation MUST be within range (§17.2 Distance), validated server-side per §13.7."
  AsyncValidation:
    type: object
    description: Optional asynchronous server-side validation for activation (§8.8). When present and Required is true, an activation that passes the synchronous checks enters PendingConfirmation before Commit instead of committing synchronously.
    properties:
      Required:
        type: boolean
        description: If true, route activation through the PendingConfirmation state and await server validation before Commit. Absent or false keeps the synchronous Validating -> Commit behaviour.
      Kind:
        type: string
        description: Category of asynchronous validation, e.g. AntiCheat | RemoteInventory | Entitlement | Custom.
      TimeoutMs:
        type: number
        exclusiveMinimum: 0
        description: "Positive server monotonic timeout in milliseconds (§8.8). When omitted the adapter MUST supply a documented finite positive default; expiry fails without commit."
      Predicted:
        type: boolean
        description: "If true, Required MUST be true. The owning client MAY predict while authority validates; inability to predict still submits the same authority request (§8.8)."
    allOf:
      - if:
          required: [Predicted]
          properties:
            Predicted:
              const: true
        then:
          required: [Required]
          properties:
            Required:
              const: true
  Tasks:
    type: array
    items:
      type: object
      required:
        - Type
      properties:
        Type:
          type: string
          description: Task type identifier
        Params:
          type: object
          description: Task-specific parameters
        TickInterval:
          type: number
          description: Seconds between task ticks; 0 means every frame. Only meaningful for ticking tasks.
        Priority:
          type: integer
          description: Tick scheduling priority when the per-frame tick budget is exhausted; higher ticks first.
  Metadata:
    type: object
    properties:
      DisplayName:
        type: string
      Description:
        type: string
      Icon:
        type: string

# GameplayEffect Definition Schema
# Based on UGAS Specification dev-5edc54d - Appendix B

type: object
required:
  - Name
  - DurationPolicy
allOf:
  - if:
      properties:
        DurationPolicy:
          const: HasDuration
    then:
      required:
        - Duration
properties:
  Name:
    type: string
    description: Unique effect identifier
  DurationPolicy:
    type: string
    enum:
      - Instant
      - HasDuration
      - Infinite
  Duration:
    $ref: "#/$defs/MagnitudeDefinition"
  Period:
    type: object
    required:
      - Period
    properties:
      Period:
        type: number
        exclusiveMinimum: 0
        description: Time interval for periodic execution
      ExecuteOnApplication:
        type: boolean
        default: false
        description: Whether to execute immediately on application
  ExecutionPolicy:
    type: string
    enum:
      - RunInParallel
      - RunInSequence
      - RunInMerge
    default: RunInParallel
  Priority:
    type: integer
    default: 0
    description: >-
      Override conflict resolution priority. When multiple active effects apply an Override
      modifier to the same Attribute, the effect with the highest Priority value wins.
      On equal Priority, last-applied wins (LIFO). Negative values are valid.
  Modifiers:
    type: array
    items:
      $ref: "#/$defs/Modifier"
  Executions:
    type: array
    items:
      type: object
      properties:
        CalculatorClass:
          type: string
          description: Custom calculation class reference
  GrantedTags:
    type: array
    items:
      type: string
    description: Tags granted while this effect is active
  ApplicationRequiredTags:
    type: array
    items:
      type: string
    description: Tags required on target for effect to apply
  GrantedAbilities:
    type: array
    items:
      type: object
      properties:
        AbilityClass:
          type: string
          description: Ability class to grant
        Level:
          type: integer
          default: 1
          description: Level of the granted ability
        InputID:
          type: string
          description: Optional input binding
        RemoveOnEffectRemoval:
          type: boolean
          default: true
          description: Remove ability when effect expires
  GameplayCues:
    type: array
    items:
      type: string
    description: Visual/audio cues to trigger
  Area:
    type: object
    description: "Optional area application (§17.3). When present, the effect applies to every anchor matching the filter within the shape (via the §17.2 spatial queries) instead of a single target; the execution policy (§9.6) governs per-target combination."
    required:
      - Shape
    properties:
      Shape:
        type: string
        enum:
          - Sphere
          - Cone
        description: "Query shape centered at the application origin (EffectContext.WorldOrigin, §9.9)."
      Radius:
        $ref: "#/$defs/MagnitudeDefinition"
        description: "Sphere radius / cone range. May be AttributeBased to scale with an attribute (§9.4.2)."
      HalfAngleDeg:
        type: number
        minimum: 0
        maximum: 180
        description: "Cone half-angle in degrees (Cone shape only)."
      RequireTags:
        type: array
        items:
          type: string
        description: "Candidate must own all these tags (§7, hierarchical). Empty = no requirement."
      ExcludeTags:
        type: array
        items:
          type: string
        description: "Candidate must own none of these tags."
      Affiliation:
        type: string
        enum:
          - Any
          - Allied
          - Hostile
          - Neutral
          - SelfOnly
          - ExcludeSelf
        default: ExcludeSelf
        description: "Affiliation of candidates relative to the applying GC (§17.2)."
      MaxTargets:
        type: integer
        minimum: 0
        description: "Cap on affected targets (0 = unbounded), applied after ordering."
    allOf:
      - if:
          properties:
            Shape:
              const: Sphere
        then:
          required:
            - Radius
      - if:
          properties:
            Shape:
              const: Cone
        then:
          required:
            - Radius
            - HalfAngleDeg

$defs:
  MagnitudeDefinition:
    type: object
    required:
      - Type
    properties:
      Type:
        type: string
        enum:
          - ScalableFloat
          - AttributeBased
          - CustomCalculation
          - SetByCaller
      Value:
        type: number
        description: Static value for ScalableFloat. A ScalableFloat needs Value, Curve, or both (§9.4.2).
      Curve:
        type: string
        description: Curve table reference
      CurveInput:
        type: string
        description: Input parameter for curve evaluation
      BackingAttribute:
        type: string
        description: Attribute to use for AttributeBased magnitude
      Source:
        type: string
        enum:
          - Source
          - Target
        description: Which GC to read the backing attribute from
      Coefficient:
        type: number
        default: 1
        description: Multiplicative coefficient
      PreMultiplyAdditive:
        type: number
        default: 0
        description: Value added before multiplication
      PostMultiplyAdditive:
        type: number
        default: 0
        description: Value added after multiplication
      CalculatorClass:
        type: string
        description: Custom calculation class for CustomCalculation type
      DataTag:
        type: string
        description: Tag for SetByCaller data lookup
    allOf:
      - if:
          properties:
            Type:
              const: ScalableFloat
        then:
          anyOf:
            - required:
                - Value
            - required:
                - Curve
      - if:
          properties:
            Type:
              const: AttributeBased
        then:
          required:
            - BackingAttribute
      - if:
          properties:
            Type:
              const: CustomCalculation
        then:
          required:
            - CalculatorClass
      - if:
          properties:
            Type:
              const: SetByCaller
        then:
          required:
            - DataTag

  Modifier:
    type: object
    required:
      - Attribute
      - Operation
      - Magnitude
    properties:
      Attribute:
        type: string
        description: Target attribute to modify
      Operation:
        type: string
        enum:
          - Add
          - AddPost
          - Multiply
          - Override
        description: >-
          Mathematical operation to apply.
          Add: pre-multiply flat additive (pipeline step 2, before the multiply steps).
          Multiply: signed bonus aggregated per Channel at step 4 — the channel factor is
          (1 + sum of magnitudes), so +0.25 means +25% and -0.25 means -25%. There is no Divide
          operation: express a 50% reduction as Multiply with magnitude -0.5.
          AddPost: post-multiply flat additive (pipeline step 5, after all multiply steps; very rare).
          Override: replaces the computed result at step 6.
          Step numbers refer to the Current-Value pipeline (§5.3). On an Instant effect each
          modifier instead writes the Base Value directly in authored order, where Multiply scales
          the base by (1 + magnitude) with no channel grouping — so magnitude 0 is the identity
          (§5.2).
      Magnitude:
        $ref: "#/$defs/MagnitudeDefinition"
      Channel:
        type: string
        description: >-
          Optional named aggregation channel for Multiply modifiers. Modifiers sharing a channel
          sum their magnitudes into a single factor of (1 + sum); distinct channels produce factors
          that multiply against each other. Used for damage-bucket systems (see §5.3 Channel
          Aggregation). Omit to place the modifier in its own implicit singleton channel,
          contributing (1 + magnitude) independently of every other modifier — omission does NOT
          pool modifiers into a shared global channel. Ignored on Add, AddPost, and Override
          modifiers.

# Tag Registry Schema
# Based on UGAS Specification dev-5edc54d - Appendix B

type: object
properties:
  Tags:
    type: array
    items:
      type: object
      required:
        - Tag
      properties:
        Tag:
          type: string
          pattern: "^[A-Z][a-zA-Z0-9]*(\\.[A-Z][a-zA-Z0-9]*)*$"
          description: Hierarchical tag in dot notation (e.g., State.Debuff.Stunned)
        Description:
          type: string
        AllowMultiple:
          type: boolean
          default: false
        DevComment:
          type: string

@online{epicgames_gas,
  author = {{Epic Games}},
  title = {Understanding the Unreal Engine Gameplay Ability System},
  year = {2024},
  url = {https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-the-unreal-engine-gameplay-ability-system},
  urldate = {2026-02-03}
}

@online{tranek_gasdoc,
  author = {Dan Tranek},
  title = {GASDocumentation: Understanding Unreal Engine's GameplayAbilitySystem},
  year = {2024},
  url = {https://github.com/tranek/GASDocumentation},
  urldate = {2026-02-03}
}

@online{unity_gas,
  author = {{Unity Technologies}},
  title = {Unity Gameplay Ability System},
  year = {2024},
  url = {https://github.com/sjai013/unity-gameplay-ability-system},
  urldate = {2026-02-03}
}

@online{godot_attributes,
  author = {{OctoD}},
  title = {Godot Gameplay Attributes},
  year = {2024},
  url = {https://github.com/OctoD/godot_gameplay_attributes},
  urldate = {2026-02-03}
}


@book{gregory_engine,
  author = {Jason Gregory},
  title = {Game Engine Architecture},
  edition = {3rd},
  publisher = {A K Peters/CRC Press},
  year = {2018},
  isbn = {978-1138035454}
}

@online{gambetta_prediction,
  author = {Gabriel Gambetta},
  title = {Client-Side Prediction and Server Reconciliation},
  year = {2021},
  url = {https://www.gabrielgambetta.com/client-side-prediction-server-reconciliation.html},
  urldate = {2026-02-03}
}

@online{gaffer_sync,
  author = {Glenn Fiedler},
  title = {State Synchronization},
  year = {2019},
  url = {https://gafferongames.com/post/state_synchronization/},
  urldate = {2026-02-03}
}