Dungeonis OpenAPI 3.1.0 spec for GPT function calling

dungeonis_mechanics_api.yaml

openapi: 3.1.0
info:
  title: Dungeonis Core Mechanics API
  version: 0.1.0
  description: API for core game mechanics like dice rolling, map, tokens, and memory. Designed for LLM function calling.
servers:
  - url: https://example.com
    description: Placeholder server for GPT registration
paths:
  /mechanics/roll_dice:
    post:
      summary: Roll Virtual Dice
      operationId: rollDice
      description: Simulates rolling one or more dice with a specified number of sides, optionally adding a modifier.
      tags: [dice]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                num_dice:
                  type: integer
                  description: The number of dice to roll.
                  minimum: 1
                  default: 1
                num_sides:
                  type: integer
                  description: The number of sides on each die (e.g., 4, 6, 8, 10, 12, 20, 100).
                  enum: [4, 6, 8, 10, 12, 20, 100]
                modifier:
                  type: integer
                  description: A flat value to add to the total result.
                  default: 0
              required:
                - num_dice
                - num_sides
      responses:
        '200':
          description: Dice roll results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  individual_rolls:
                    type: array
                    items:
                      type: integer
                    description: The result of each individual die roll.
                  total_sum_unmodified:
                    type: integer
                    description: The sum of the individual dice rolls before the modifier.
                  total_sum_modified:
                    type: integer
                    description: The final result after adding the modifier.
                required:
                  - individual_rolls
                  - total_sum_unmodified
                  - total_sum_modified
        '400':
          description: Invalid input for dice roll (e.g., invalid number of sides).

  /map/reveal:
    post:
      summary: Reveal part of the map
      operationId: revealMap
      description: Reveals a specified area of the map for players.
      tags: [map]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                map_id:
                  type: string
                  description: The unique identifier for the map.
                area:
                  type: object
                  description: The area to reveal (coordinates, shape, etc.).
              required:
                - map_id
                - area
      responses:
        '200':
          description: Map reveal result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  map_id:
                    type: string
                  revealed_area:
                    type: object
                required:
                  - map_id
                  - revealed_area
        '400':
          description: Invalid map or area specified.

  /map/annotate:
    post:
      summary: Annotate the map
      operationId: annotateMap
      description: Adds an annotation to the map (e.g., notes, markers).
      tags: [map]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                map_id:
                  type: string
                  description: The unique identifier for the map.
                annotation:
                  type: object
                  description: The annotation object (text, icon, position, etc.).
              required:
                - map_id
                - annotation
      responses:
        '200':
          description: Annotation added.
          content:
            application/json:
              schema:
                type: object
                properties:
                  map_id:
                    type: string
                  annotation:
                    type: object
                required:
                  - map_id
                  - annotation
        '400':
          description: Invalid annotation or map specified.

  /map/update:
    post:
      summary: Create or update a map
      operationId: updateMap
      description: Creates or updates a map with the provided data.
      tags: [map]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                map_id:
                  type: string
                  description: The unique identifier for the map.
                map_data:
                  type: object
                  description: The full map data to create or update.
              required:
                - map_id
                - map_data
      responses:
        '200':
          description: Map created or updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  map_id:
                    type: string
                  map_data:
                    type: object
                required:
                  - map_id
                  - map_data
        '400':
          description: Invalid map data specified.

  /token/move:
    post:
      summary: Move a token
      operationId: moveToken
      description: Moves a token to a new position on the map.
      tags: [token]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token_id:
                  type: string
                  description: The unique identifier for the token.
                x:
                  type: number
                  description: The new x coordinate.
                y:
                  type: number
                  description: The new y coordinate.
              required:
                - token_id
                - x
                - y
      responses:
        '200':
          description: Token moved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token_id:
                    type: string
                  x:
                    type: number
                  y:
                    type: number
                required:
                  - token_id
                  - x
                  - y
        '400':
          description: Invalid token or coordinates specified.

  /token/add_update:
    post:
      summary: Add or update a token
      operationId: addOrUpdateToken
      description: Adds a new token or updates an existing token on the map.
      tags: [token]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token_id:
                  type: string
                  description: The unique identifier for the token.
                token_data:
                  type: object
                  description: The full token data to add or update.
              required:
                - token_id
                - token_data
      responses:
        '200':
          description: Token added or updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token_id:
                    type: string
                  token_data:
                    type: object
                required:
                  - token_id
                  - token_data
        '400':
          description: Invalid token data specified.

  /memory/character:
    get:
      summary: Get all characters
      operationId: getAllCharacters
      description: Retrieves all characters from memory/persistent storage.
      tags: [memory]
      responses:
        '200':
          description: List of characters.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '404':
          description: No characters found.
    post:
      summary: Add or update a character
      operationId: addOrUpdateCharacter
      description: Adds a new character or updates an existing character in memory/persistent storage.
      tags: [memory]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                character_id:
                  type: string
                  description: The unique identifier for the character.
                character_data:
                  type: object
                  description: The full character data to add or update.
              required:
                - character_id
                - character_data
      responses:
        '200':
          description: Character added or updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  character_id:
                    type: string
                  character_data:
                    type: object
                required:
                  - character_id
                  - character_data
        '400':
          description: Invalid character data specified.