asyncapi.yaml

asyncapi: 3.0.0
info:
  title: GABP Events
  version: 1.1.0
  description: |
    AsyncAPI specification for GABP (Game Agent Bridge Protocol) events.
    
    This specification describes the event channels available in GABP for 
    real-time communication between game mods and automation bridges.
  contact:
    name: GABP Maintainers
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

defaultContentType: application/json

channels:
  events:
    address: 'events/{channel}'
    title: GABP Event Channel
    description: Generic event channel for GABP events
    parameters:
      channel:
        description: The event channel name (e.g., 'player/move', 'world/block_change')
        schema:
          type: string
          pattern: '^[a-z]+(/[a-z_]+)*$'
          examples:
            - 'player/move'
            - 'world/block_change'
            - 'inventory/update'
    messages:
      eventMessage:
        $ref: '#/components/messages/EventMessage'

  'player/move':
    address: 'player/move'
    title: Player Movement Events
    description: Events triggered when players move in the game world
    messages:
      playerMoveEvent:
        $ref: '#/components/messages/PlayerMoveEvent'

  'world/block_change':
    address: 'world/block_change'
    title: World Block Change Events
    description: Events triggered when blocks are placed, broken, or modified
    messages:
      blockChangeEvent:
        $ref: '#/components/messages/BlockChangeEvent'

  'inventory/update':
    address: 'inventory/update'
    title: Inventory Update Events
    description: Events triggered when player inventories change
    messages:
      inventoryUpdateEvent:
        $ref: '#/components/messages/InventoryUpdateEvent'

  'attention/opened':
    address: 'attention/opened'
    title: Attention Opened Events
    description: Summarized attention items that just opened
    messages:
      attentionOpenedEvent:
        $ref: '#/components/messages/AttentionOpenedEvent'

  'attention/updated':
    address: 'attention/updated'
    title: Attention Updated Events
    description: Meaningful updates to a currently open attention item
    messages:
      attentionUpdatedEvent:
        $ref: '#/components/messages/AttentionUpdatedEvent'

  'attention/cleared':
    address: 'attention/cleared'
    title: Attention Cleared Events
    description: Attention items that were cleared or otherwise no longer gate execution
    messages:
      attentionClearedEvent:
        $ref: '#/components/messages/AttentionClearedEvent'

operations:
  subscribeToEvents:
    action: receive
    channel:
      $ref: '#/channels/events'
    summary: Subscribe to GABP events
    description: |
      Receive events from subscribed channels. Events are delivered in sequence
      order per channel using the `seq` field.

components:
  messages:
    EventMessage:
      name: EventMessage
      title: GABP Event Message
      summary: Base GABP event message format
      contentType: application/json
      payload:
        $ref: '#/components/schemas/EventMessage'

    PlayerMoveEvent:
      name: PlayerMoveEvent
      title: Player Movement Event
      summary: Player position and movement update
      contentType: application/json
      payload:
        allOf:
          - $ref: '#/components/schemas/EventMessage'
          - type: object
            properties:
              channel:
                const: 'player/move'
              payload:
                $ref: '#/components/schemas/PlayerMovePayload'

    BlockChangeEvent:
      name: BlockChangeEvent
      title: Block Change Event
      summary: World block modification event
      contentType: application/json
      payload:
        allOf:
          - $ref: '#/components/schemas/EventMessage'
          - type: object
            properties:
              channel:
                const: 'world/block_change'
              payload:
                $ref: '#/components/schemas/BlockChangePayload'

    InventoryUpdateEvent:
      name: InventoryUpdateEvent
      title: Inventory Update Event
      summary: Player inventory change event
      contentType: application/json
      payload:
        allOf:
          - $ref: '#/components/schemas/EventMessage'
          - type: object
            properties:
              channel:
                const: 'inventory/update'
              payload:
                $ref: '#/components/schemas/InventoryUpdatePayload'

    AttentionOpenedEvent:
      name: AttentionOpenedEvent
      title: Attention Opened Event
      summary: A summarized attention item has opened
      contentType: application/json
      payload:
        allOf:
          - $ref: '#/components/schemas/EventMessage'
          - type: object
            properties:
              channel:
                const: 'attention/opened'
              payload:
                $ref: '#/components/schemas/AttentionPayload'

    AttentionUpdatedEvent:
      name: AttentionUpdatedEvent
      title: Attention Updated Event
      summary: A summarized attention item has changed meaningfully
      contentType: application/json
      payload:
        allOf:
          - $ref: '#/components/schemas/EventMessage'
          - type: object
            properties:
              channel:
                const: 'attention/updated'
              payload:
                $ref: '#/components/schemas/AttentionPayload'

    AttentionClearedEvent:
      name: AttentionClearedEvent
      title: Attention Cleared Event
      summary: A summarized attention item has been cleared
      contentType: application/json
      payload:
        allOf:
          - $ref: '#/components/schemas/EventMessage'
          - type: object
            properties:
              channel:
                const: 'attention/cleared'
              payload:
                $ref: '#/components/schemas/AttentionPayload'

  schemas:
    EventMessage:
      type: object
      title: GABP Event Message
      description: Base schema for all GABP event messages
      required:
        - v
        - id
        - type
        - channel
        - seq
        - payload
      properties:
        v:
          type: string
          const: 'gabp/1'
          description: Protocol version identifier
        id:
          type: string
          format: uuid
          description: Unique event identifier
        type:
          type: string
          const: 'event'
          description: Message type
        channel:
          type: string
          minLength: 1
          description: Event channel name
        seq:
          type: integer
          minimum: 0
          description: Sequence number for this channel
        payload:
          type: object
          description: Event-specific data
        timestamp:
          type: string
          format: date-time
          description: Optional ISO 8601 timestamp when event occurred
      additionalProperties: false

    PlayerMovePayload:
      type: object
      title: Player Movement Payload
      description: Data payload for player movement events
      required:
        - playerId
        - position
      properties:
        playerId:
          type: string
          description: Unique player identifier
        position:
          type: object
          required: [x, y, z]
          properties:
            x:
              type: number
              description: X coordinate
            y:
              type: number
              description: Y coordinate
            z:
              type: number
              description: Z coordinate
          additionalProperties: false
        velocity:
          type: object
          properties:
            x:
              type: number
              description: X velocity component
            y:
              type: number  
              description: Y velocity component
            z:
              type: number
              description: Z velocity component
          additionalProperties: false
        rotation:
          type: object
          properties:
            yaw:
              type: number
              minimum: -180
              maximum: 180
              description: Yaw rotation in degrees
            pitch:
              type: number
              minimum: -90
              maximum: 90
              description: Pitch rotation in degrees
          additionalProperties: false
      additionalProperties: false

    BlockChangePayload:
      type: object
      title: Block Change Payload
      description: Data payload for block change events
      required:
        - position
        - action
      properties:
        position:
          type: object
          required: [x, y, z]
          properties:
            x:
              type: integer
              description: Block X coordinate
            y:
              type: integer
              description: Block Y coordinate
            z:
              type: integer
              description: Block Z coordinate
          additionalProperties: false
        action:
          type: string
          enum: [place, break, replace]
          description: Type of block change
        oldBlockType:
          type: string
          description: Previous block type (for break/replace actions)
        newBlockType:
          type: string
          description: New block type (for place/replace actions)
        playerId:
          type: string
          description: Player who caused the change (if applicable)
        tool:
          type: string
          description: Tool used for the action (if applicable)
      additionalProperties: false

    InventoryUpdatePayload:
      type: object
      title: Inventory Update Payload
      description: Data payload for inventory update events
      required:
        - playerId
        - action
      properties:
        playerId:
          type: string
          description: Player whose inventory changed
        action:
          type: string
          enum: [add, remove, move, update]
          description: Type of inventory change
        slot:
          type: integer
          minimum: 0
          description: Inventory slot number
        item:
          type: object
          properties:
            type:
              type: string
              description: Item type identifier
            count:
              type: integer
              minimum: 0
              description: Number of items
            metadata:
              type: object
              description: Item-specific metadata
          additionalProperties: false
        previousItem:
          type: object
          description: Previous item in slot (for replace actions)
          properties:
            type:
              type: string
            count:
              type: integer
              minimum: 0
            metadata:
              type: object
          additionalProperties: false
      additionalProperties: false

    AttentionPayload:
      type: object
      title: GABP Attention Payload
      description: Summarized attention item payload for attention lifecycle channels
      required:
        - attentionId
        - state
        - severity
        - blocking
        - stateInvalidated
        - summary
        - openedAtSequence
        - latestSequence
        - totalUrgentEntries
      properties:
        attentionId:
          type: string
          minLength: 1
          description: Stable identifier for this attention item
        state:
          type: string
          enum: [open, cleared]
          description: Lifecycle state of the attention item
        severity:
          type: string
          enum: [info, warning, error, fatal]
          description: Highest summarized severity for this attention item
        blocking:
          type: boolean
          description: Whether bridge-side execution should be gated while this item is open
        stateInvalidated:
          type: boolean
          description: Whether prior game-state assumptions should be treated as stale
        summary:
          type: string
          minLength: 1
          description: Compact semantic summary of what requires attention
        causalOperationId:
          type: string
          description: Optional operation identifier associated with this attention item
        causalMethod:
          type: string
          description: Optional method, tool, or capability identifier associated with this attention item
        openedAtSequence:
          type: integer
          minimum: 0
          description: First diagnostics-plane sequence associated with this attention item
        latestSequence:
          type: integer
          minimum: 0
          description: Latest diagnostics-plane sequence associated with this attention item
        diagnosticsCursor:
          type: integer
          minimum: 0
          description: Optional cursor the bridge can use to inspect more detailed diagnostics
        totalUrgentEntries:
          type: integer
          minimum: 0
          description: Total number of summarized urgent entries represented by this item
        sample:
          type: array
          description: Optional representative sample of summarized urgent entries
          items:
            type: object
            required:
              - level
              - message
              - repeatCount
              - latestSequence
            properties:
              level:
                type: string
                enum: [info, warning, error, fatal]
                description: Severity level for the sampled entry
              message:
                type: string
                minLength: 1
                description: Representative message text
              repeatCount:
                type: integer
                minimum: 1
                description: Number of similar entries summarized by this sample
              latestSequence:
                type: integer
                minimum: 0
                description: Latest diagnostics-plane sequence represented by this sample
            additionalProperties: false
      additionalProperties: false