ugas

UGAS Schema Definitions

This directory contains formal schema definitions for the Universal Gameplay Ability System (UGAS) specification. These schemas are provided in both JSON Schema and YAML formats for maximum compatibility.

Schema Files

Schema	JSON	YAML	Description
Gameplay Controller	`gameplay_controller.json`	`gameplay_controller.yaml`	Interface schema for the Gameplay Controller (GC), the central hub managing abilities, effects, attributes, and tags
Attribute	`attribute.json`	`attribute.yaml`	Schema for individual attribute definitions with base values, clamping, and replication settings
Attribute Set	`attribute_set.json`	`attribute_set.yaml`	Schema for attribute collections that group related attributes
Gameplay Effect	`gameplay_effect.json`	`gameplay_effect.yaml`	Schema for effects that modify attributes, grant tags/abilities, with duration and magnitude definitions
Gameplay Ability	`gameplay_ability.json`	`gameplay_ability.yaml`	Schema for ability definitions with tag-based activation requirements and blocking rules
Gameplay Tag	`gameplay_tag.json`	`gameplay_tag.yaml`	Schema for the tag registry defining semantic state labels in hierarchical notation
Input Action	`input_action.json`	`input_action.yaml`	Schema for named semantic input intents with value types and trigger behaviors
Input Action Set	`input_action_set.json`	`input_action_set.yaml`	Schema for context-based groups of actions with tag-driven activation
Input Mapping	`input_mapping.json`	`input_mapping.yaml`	Schema for bindings between device inputs and actions, with chording, composition, and modifiers
Input Modifier	`input_modifier.json`	`input_modifier.yaml`	Schema for reusable input signal processing steps (dead zones, sensitivity, response curves)

Schema Format

All schemas follow standard JSON Schema (Draft 07) and YAML schema conventions:

JSON Schemas: Include $schema, $id, and title metadata
YAML Schemas: Structured for readability with inline comments
Cross-references: Use $ref for shared definitions within schemas

Usage Examples

Attribute Definition

# health_attribute.yaml
Name: Health
DefaultBaseValue: 100.0
Category: Resource
Clamping:
  Min: 0
  Max: MaxHealth  # Reference to another attribute
ReplicationMode: All
Metadata:
  DisplayName: Health Points
  Description: Character's life force
  UICategory: Vital Stats
  Icon: ui/icons/health.png

Gameplay Effect Definition

# damage_effect.yaml
Name: DamageEffect
DurationPolicy: Instant
Modifiers:
  - Attribute: Health
    Operation: Add
    Magnitude:
      Type: ScalableFloat
      Value: -25.0
GrantedTags:
  - State.Damaged
GameplayCues:
  - GameplayCue.Character.Damage

Gameplay Ability Definition

# fireball_ability.yaml
Name: FireballAbility
Tags:
  AbilityTags:
    - Ability.Magic.Fireball
  ActivationRequiredTags:
    - State.CanCast
  ActivationBlockedTags:
    - State.Silenced
    - State.Stunned
  ActivationOwnedTags:
    - State.Casting
Cost: ManaCostEffect
Cooldown: FireballCooldownEffect
Metadata:
  DisplayName: Fireball
  Description: Launch a ball of fire at the target
  Icon: ui/icons/fireball.png

Input Action Definition

# fire_action.yaml
Name: Fire
ValueType: Digital
TriggerBehavior: OnPressed
ConsumeInput: true
Tags:
  ActionTags:
    - Input.Type.Combat
Metadata:
  DisplayName: Fire Weapon
  Description: Pull the trigger on the equipped weapon
  Category: Combat

Input Action Set Definition

# onfoot_action_set.yaml
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
Metadata:
  DisplayName: On Foot

Input Mapping Definition

# onfoot_pc_mapping.yaml
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

Input Modifier Definition

# stick_deadzone_modifier.yaml
Name: StickDeadzone
Type: DeadZone
Params:
  InnerThreshold: 0.15
  OuterThreshold: 0.95
  DeadZoneShape: Radial
UserConfigurable: true
Metadata:
  DisplayName: Stick Dead Zone
  Description: Inner dead zone radius for analog sticks

Gameplay Tag Registry

# tag_registry.yaml
Tags:
  - Tag: State.Combat
    Description: Entity is in combat
    AllowMultiple: false

  - Tag: State.Debuff.Stunned
    Description: Entity is stunned and cannot act
    AllowMultiple: false

  - Tag: Ability.Magic.Fireball
    Description: Fireball ability identifier
    AllowMultiple: false

Gameplay Controller Instance

{
  "OwnerActor": {
    "ActorID": "player_001",
    "ActorType": "PlayerState"
  },
  "AvatarActor": {
    "ActorID": "character_001",
    "ActorType": "PlayerCharacter"
  },
  "AttributeSets": [
    {
      "Name": "VitalAttributes",
      "Attributes": [
        {
          "Name": "Health",
          "BaseValue": 100.0,
          "CurrentValue": 100.0
        },
        {
          "Name": "MaxHealth",
          "BaseValue": 100.0,
          "CurrentValue": 100.0
        }
      ]
    }
  ],
  "GrantedAbilities": [
    {
      "AbilityClass": "FireballAbility",
      "Level": 1,
      "InputID": "Ability1",
      "Handle": "ability_handle_001",
      "bIsActive": false
    }
  ],
  "ActiveEffects": [],
  "OwnedTags": ["State.Idle"],
  "ReplicationMode": "Mixed",
  "bIsActive": true
}

Schema Validation

JSON Schema Validation

Using Python:

import json
import jsonschema

# Load schema and data
with open('schemas/gameplay_effect.json') as f:
    schema = json.load(f)

with open('my_effect.json') as f:
    data = json.load(f)

# Validate
jsonschema.validate(data, schema)

Using Node.js (with ajv):

const Ajv = require('ajv');
const ajv = new Ajv();

const schema = require('./schemas/gameplay_effect.json');
const data = require('./my_effect.json');

const validate = ajv.compile(schema);
const valid = validate(data);

if (!valid) console.log(validate.errors);

YAML Schema Validation

YAML files can be validated by loading them and comparing against the schema structure, or by converting to JSON and using JSON Schema validation.

Specification Reference

These schemas are based on the Universal Gameplay Ability System Specification v1.0.0-draft.3, particularly:

Section 4: Gameplay Controller - gameplay_controller.{json,yaml}
Section 5: Attributes - attribute.{json,yaml}
Section 6: Attribute Sets - attribute_set.{json,yaml}
Section 7: Gameplay Tags - gameplay_tag.{json,yaml}
Section 8: Gameplay Abilities - gameplay_ability.{json,yaml}
Section 9: Gameplay Effects - gameplay_effect.{json,yaml}
Section 11: Input Integration - input_action.{json,yaml}, input_action_set.{json,yaml}, input_mapping.{json,yaml}, input_modifier.{json,yaml}
Appendix B: Complete Schema Reference

Notes

Single Source of Truth: While SPEC.md contains the authoritative specification, these machine-readable schemas enable automated validation and tooling.
Format Choice:
- Use JSON schemas for strict validation in programming contexts
- Use YAML schemas for human-readable configuration files
Extensions: Implementations may extend these schemas with additional properties while maintaining backward compatibility with the core specification.
Versioning: Schema files follow the UGAS specification version. Any breaking changes will result in new schema files with version suffixes.

License

These schemas are part of the UGAS specification and follow the same license as the parent repository.

This site is open source. Improve this page.