Ilia Denisov
998 lines
30 KiB
YAML
998 lines
30 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: Galaxy Game Service REST API
|
||
version: v1
|
||
description: |
|
||
This specification documents the REST contract of `galaxy/game`.
|
||
|
||
The service hosts a single game instance and exposes endpoints for game
|
||
initialization, turn advancement, game-state queries, player reports, and
|
||
batched player command execution.
|
||
|
||
Transport rules:
|
||
- request bodies are JSON
|
||
- `PUT /api/v1/command` is rate-limited to one concurrent execution;
|
||
requests that cannot acquire the execution slot within 100 ms receive
|
||
`504 Gateway Timeout`
|
||
- `501 Not Implemented` is returned without a body when the game has not
|
||
been initialized
|
||
- validation errors return `400` with `{"error": "message"}`
|
||
- game-engine errors return `500` with `{"generic_error": "message", "code": integer}`
|
||
- other internal errors return `500` with `{"error": "message"}`
|
||
servers:
|
||
- url: http://localhost:8080
|
||
description: Default local listener for Game Service.
|
||
tags:
|
||
- name: GameLifecycle
|
||
description: Game initialization, state retrieval, and turn advancement.
|
||
- name: PlayerActions
|
||
description: Player command execution, order validation, and turn-report retrieval.
|
||
- name: Health
|
||
description: Technical liveness probes used by Runtime Manager and operator tooling.
|
||
paths:
|
||
/api/v1/status:
|
||
get:
|
||
tags:
|
||
- GameLifecycle
|
||
operationId: getGameStatus
|
||
summary: Get the current game state
|
||
description: |
|
||
Returns the current game state including turn number, stage, and a
|
||
summary of all players. Returns `501` if the game has not yet been
|
||
initialized.
|
||
responses:
|
||
"200":
|
||
description: Current game state.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/StateResponse"
|
||
"501":
|
||
description: Game has not been initialized yet.
|
||
"500":
|
||
$ref: "#/components/responses/InternalError"
|
||
/api/v1/init:
|
||
post:
|
||
tags:
|
||
- GameLifecycle
|
||
operationId: initGame
|
||
summary: Initialize a new game
|
||
description: |
|
||
Generates a new game instance with the supplied list of races.
|
||
Requires at least 10 race entries.
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/InitRequest"
|
||
responses:
|
||
"201":
|
||
description: Game initialized successfully.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/StateResponse"
|
||
"400":
|
||
$ref: "#/components/responses/ValidationError"
|
||
"500":
|
||
$ref: "#/components/responses/InternalError"
|
||
/api/v1/report:
|
||
get:
|
||
tags:
|
||
- PlayerActions
|
||
operationId: getReport
|
||
summary: Get a player turn report
|
||
description: |
|
||
Returns the full game report for the specified player and turn.
|
||
`player` must be a non-blank race name. `turn` defaults to `0`.
|
||
parameters:
|
||
- $ref: "#/components/parameters/PlayerParam"
|
||
- $ref: "#/components/parameters/TurnParam"
|
||
responses:
|
||
"200":
|
||
description: Player turn report.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Report"
|
||
"400":
|
||
$ref: "#/components/responses/ValidationError"
|
||
"500":
|
||
$ref: "#/components/responses/InternalError"
|
||
/api/v1/command:
|
||
put:
|
||
tags:
|
||
- PlayerActions
|
||
operationId: executeCommands
|
||
summary: Execute a batch of player commands
|
||
description: |
|
||
Applies one or more game commands for the specified actor. Serialized
|
||
to one concurrent execution; requests that cannot acquire the execution
|
||
slot within 100 ms return `504 Gateway Timeout`. Returns `204 No
|
||
Content` on success.
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/CommandRequest"
|
||
responses:
|
||
"204":
|
||
description: All commands applied successfully.
|
||
"400":
|
||
$ref: "#/components/responses/ValidationError"
|
||
"504":
|
||
description: Command execution slot not acquired within 100 ms.
|
||
"500":
|
||
$ref: "#/components/responses/InternalError"
|
||
/api/v1/order:
|
||
put:
|
||
tags:
|
||
- PlayerActions
|
||
operationId: validateOrder
|
||
summary: Validate and store a player order without executing it
|
||
description: |
|
||
Validates and stores the game commands structurally without executing them.
|
||
Returns `204 No Content` if the order is valid and accepted.
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/CommandRequest"
|
||
responses:
|
||
"204":
|
||
description: Order is structurally valid.
|
||
"400":
|
||
$ref: "#/components/responses/ValidationError"
|
||
"500":
|
||
$ref: "#/components/responses/InternalError"
|
||
/api/v1/turn:
|
||
put:
|
||
tags:
|
||
- GameLifecycle
|
||
operationId: generateTurn
|
||
summary: Advance the game to the next turn
|
||
description: |
|
||
Processes the current turn and generates the next one. Returns the
|
||
updated game state.
|
||
responses:
|
||
"200":
|
||
description: Updated game state after turn generation.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/StateResponse"
|
||
"500":
|
||
$ref: "#/components/responses/InternalError"
|
||
/healthz:
|
||
get:
|
||
tags:
|
||
- Health
|
||
operationId: healthz
|
||
summary: Engine liveness probe
|
||
description: |
|
||
Returns `{"status":"ok"}` with HTTP `200` whenever the HTTP server
|
||
is serving requests, regardless of whether the engine has been
|
||
initialised through `POST /api/v1/init`. Used by `Runtime Manager`
|
||
to probe a freshly started container before `init` runs. Carries
|
||
no game-state semantics; use `GET /api/v1/status` for game-state
|
||
inspection.
|
||
responses:
|
||
"200":
|
||
description: Engine HTTP server is up.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/HealthzResponse"
|
||
components:
|
||
parameters:
|
||
PlayerParam:
|
||
name: player
|
||
in: query
|
||
required: true
|
||
description: Race name of the player requesting the report. Must be non-blank.
|
||
schema:
|
||
type: string
|
||
minLength: 1
|
||
TurnParam:
|
||
name: turn
|
||
in: query
|
||
required: false
|
||
description: Turn number to load the report for. Defaults to 0.
|
||
schema:
|
||
type: integer
|
||
minimum: 0
|
||
default: 0
|
||
schemas:
|
||
HealthzResponse:
|
||
type: object
|
||
description: Engine liveness probe response payload.
|
||
required:
|
||
- status
|
||
properties:
|
||
status:
|
||
type: string
|
||
description: Always "ok" while the engine HTTP server is serving requests.
|
||
enum:
|
||
- ok
|
||
StateResponse:
|
||
type: object
|
||
description: Summary game state returned after initialization and at each turn boundary.
|
||
required:
|
||
- id
|
||
- turn
|
||
- stage
|
||
- player
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
description: Unique identifier of this game instance.
|
||
turn:
|
||
type: integer
|
||
minimum: 0
|
||
description: Current turn number.
|
||
stage:
|
||
type: integer
|
||
minimum: 0
|
||
description: Current stage within the turn for games that support state modification.
|
||
player:
|
||
type: array
|
||
description: Summary state for each player participating in the game.
|
||
items:
|
||
$ref: "#/components/schemas/PlayerState"
|
||
PlayerState:
|
||
type: object
|
||
description: Brief player state returned as part of the game state response.
|
||
required:
|
||
- id
|
||
- raceName
|
||
- planets
|
||
- population
|
||
- extinct
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
description: Unique player identifier within this game.
|
||
raceName:
|
||
type: string
|
||
description: Name of the player's race.
|
||
planets:
|
||
type: integer
|
||
minimum: 0
|
||
description: Number of planets currently owned by the player.
|
||
population:
|
||
type: number
|
||
description: Total population summed across all player planets.
|
||
extinct:
|
||
type: boolean
|
||
description: True when the race has been eliminated or voluntarily quit.
|
||
InitRequest:
|
||
type: object
|
||
description: Initialization request specifying the race list for a new game.
|
||
required:
|
||
- races
|
||
properties:
|
||
races:
|
||
type: array
|
||
description: List of participating races. Minimum 10 entries required.
|
||
minItems: 10
|
||
items:
|
||
$ref: "#/components/schemas/InitRace"
|
||
InitRace:
|
||
type: object
|
||
description: A single race entry in an initialization request.
|
||
required:
|
||
- raceName
|
||
properties:
|
||
raceName:
|
||
type: string
|
||
description: Name of the race. Must be non-blank and satisfy the entity-name format.
|
||
minLength: 1
|
||
CommandRequest:
|
||
type: object
|
||
description: |
|
||
Batch command payload. `actor` identifies the race submitting the commands.
|
||
Each element of `cmd` is a polymorphic command object discriminated by the
|
||
`@type` field. At least one command is required.
|
||
required:
|
||
- actor
|
||
- cmd
|
||
properties:
|
||
actor:
|
||
type: string
|
||
description: Race name of the actor submitting the commands. Must be non-blank.
|
||
minLength: 1
|
||
cmd:
|
||
type: array
|
||
description: One or more commands to execute in order.
|
||
minItems: 1
|
||
items:
|
||
$ref: "#/components/schemas/Command"
|
||
Command:
|
||
type: object
|
||
description: |
|
||
Polymorphic game command. The `@type` field identifies the variant.
|
||
Each variant extends the base fields with additional type-specific
|
||
parameters documented in `pkg/model/order/order.go`.
|
||
required:
|
||
- "@type"
|
||
- cmdId
|
||
properties:
|
||
"@type":
|
||
$ref: "#/components/schemas/CommandType"
|
||
cmdId:
|
||
type: string
|
||
format: uuid
|
||
description: Unique command identifier (RFC 4122 UUID).
|
||
cmdApplied:
|
||
type: boolean
|
||
description: Set in command-result responses; true when the command was applied.
|
||
cmdErrorCode:
|
||
type: integer
|
||
description: Set in command-result responses; non-zero when the command was rejected.
|
||
CommandType:
|
||
type: string
|
||
description: Discriminator identifying the game command variant carried in a `cmd` element.
|
||
enum:
|
||
- raceQuit
|
||
- raceVote
|
||
- raceRelation
|
||
- shipClassCreate
|
||
- shipClassMerge
|
||
- shipClassRemove
|
||
- shipGroupBreak
|
||
- shipGroupLoad
|
||
- shipGroupUnload
|
||
- shipGroupSend
|
||
- shipGroupUpgrade
|
||
- shipGroupMerge
|
||
- shipGroupDismantle
|
||
- shipGroupTransfer
|
||
- shipGroupJoinFleet
|
||
- fleetMerge
|
||
- fleetSend
|
||
- scienceCreate
|
||
- scienceRemove
|
||
- planetRename
|
||
- planetProduce
|
||
- planetRouteSet
|
||
- planetRouteRemove
|
||
Report:
|
||
type: object
|
||
description: |
|
||
Full game report for one player at one turn boundary. Optional array
|
||
fields are omitted when empty.
|
||
required:
|
||
- version
|
||
- turn
|
||
- mapWidth
|
||
- mapHeight
|
||
- mapPlanets
|
||
- race
|
||
- votes
|
||
- voteFor
|
||
- player
|
||
properties:
|
||
version:
|
||
type: integer
|
||
minimum: 0
|
||
description: Report format version.
|
||
turn:
|
||
type: integer
|
||
minimum: 0
|
||
description: Turn number this report covers.
|
||
mapWidth:
|
||
type: integer
|
||
minimum: 0
|
||
description: Width of the star map.
|
||
mapHeight:
|
||
type: integer
|
||
minimum: 0
|
||
description: Height of the star map.
|
||
mapPlanets:
|
||
type: integer
|
||
minimum: 0
|
||
description: Total number of planets on the map.
|
||
race:
|
||
type: string
|
||
description: Race name of the report recipient.
|
||
votes:
|
||
type: number
|
||
description: Fraction of alliance votes held by this race.
|
||
voteFor:
|
||
type: string
|
||
description: Race name this player is currently voting for.
|
||
player:
|
||
type: array
|
||
description: Diplomatic and aggregate statistics for each known player.
|
||
items:
|
||
$ref: "#/components/schemas/ReportPlayer"
|
||
localScience:
|
||
type: array
|
||
description: Science projects owned by this race.
|
||
items:
|
||
$ref: "#/components/schemas/Science"
|
||
otherScience:
|
||
type: array
|
||
description: Science projects owned by other known races.
|
||
items:
|
||
$ref: "#/components/schemas/OtherScience"
|
||
localShipClass:
|
||
type: array
|
||
description: Ship classes designed by this race.
|
||
items:
|
||
$ref: "#/components/schemas/ShipClass"
|
||
otherShipClass:
|
||
type: array
|
||
description: Ship classes belonging to other known races.
|
||
items:
|
||
$ref: "#/components/schemas/OtherShipClass"
|
||
battle:
|
||
type: array
|
||
description: UUIDs of battle reports relevant to this turn.
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
bombing:
|
||
type: array
|
||
description: Bombing events that occurred during this turn.
|
||
items:
|
||
$ref: "#/components/schemas/Bombing"
|
||
incomingGroup:
|
||
type: array
|
||
description: Identified ship groups inbound toward this race's planets.
|
||
items:
|
||
$ref: "#/components/schemas/IncomingGroup"
|
||
localPlanet:
|
||
type: array
|
||
description: Full state of planets owned by this race.
|
||
items:
|
||
$ref: "#/components/schemas/LocalPlanet"
|
||
shipProduction:
|
||
type: array
|
||
description: Active ship construction status on this race's planets.
|
||
items:
|
||
$ref: "#/components/schemas/ShipProduction"
|
||
route:
|
||
type: array
|
||
description: Cargo route configuration per planet.
|
||
items:
|
||
$ref: "#/components/schemas/Route"
|
||
otherPlanet:
|
||
type: array
|
||
description: Partial state of planets owned by other known races.
|
||
items:
|
||
$ref: "#/components/schemas/OtherPlanet"
|
||
uninhabitedPlanet:
|
||
type: array
|
||
description: Uninhabited planets within sensor range.
|
||
items:
|
||
$ref: "#/components/schemas/UninhabitedPlanet"
|
||
unidentifiedPlanet:
|
||
type: array
|
||
description: Unidentified planet positions within sensor range.
|
||
items:
|
||
$ref: "#/components/schemas/UnidentifiedPlanet"
|
||
localFleet:
|
||
type: array
|
||
description: Named fleets belonging to this race.
|
||
items:
|
||
$ref: "#/components/schemas/LocalFleet"
|
||
localGroup:
|
||
type: array
|
||
description: Ship groups belonging to this race.
|
||
items:
|
||
$ref: "#/components/schemas/LocalGroup"
|
||
otherGroup:
|
||
type: array
|
||
description: Ship groups belonging to other known races.
|
||
items:
|
||
$ref: "#/components/schemas/OtherGroup"
|
||
unidentifiedGroup:
|
||
type: array
|
||
description: Unidentified ship group positions within sensor range.
|
||
items:
|
||
$ref: "#/components/schemas/UnidentifiedGroup"
|
||
ReportPlayer:
|
||
type: object
|
||
description: Diplomatic and aggregate statistics for one player as seen in a report.
|
||
required:
|
||
- name
|
||
- drive
|
||
- weapons
|
||
- shields
|
||
- cargo
|
||
- population
|
||
- industry
|
||
- planets
|
||
- relation
|
||
- votes
|
||
- extinct
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: Race name.
|
||
drive:
|
||
type: number
|
||
description: Current drive technology level.
|
||
weapons:
|
||
type: number
|
||
description: Current weapons technology level.
|
||
shields:
|
||
type: number
|
||
description: Current shields technology level.
|
||
cargo:
|
||
type: number
|
||
description: Current cargo technology level.
|
||
population:
|
||
type: number
|
||
description: Total population across all planets.
|
||
industry:
|
||
type: number
|
||
description: Total industrial output.
|
||
planets:
|
||
type: integer
|
||
minimum: 0
|
||
description: Number of planets owned.
|
||
relation:
|
||
type: string
|
||
description: Current diplomatic relation toward this race.
|
||
votes:
|
||
type: number
|
||
description: Fraction of alliance votes held.
|
||
extinct:
|
||
type: boolean
|
||
description: True when the race has been eliminated or quit.
|
||
Science:
|
||
type: object
|
||
description: A science project describing technology investment ratios.
|
||
required:
|
||
- name
|
||
- drive
|
||
- weapons
|
||
- shields
|
||
- cargo
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: Science project name.
|
||
drive:
|
||
type: number
|
||
description: Investment ratio for drive technology (0–1).
|
||
weapons:
|
||
type: number
|
||
description: Investment ratio for weapons technology (0–1).
|
||
shields:
|
||
type: number
|
||
description: Investment ratio for shields technology (0–1).
|
||
cargo:
|
||
type: number
|
||
description: Investment ratio for cargo technology (0–1).
|
||
OtherScience:
|
||
allOf:
|
||
- $ref: "#/components/schemas/Science"
|
||
- type: object
|
||
required:
|
||
- race
|
||
properties:
|
||
race:
|
||
type: string
|
||
description: Race that owns this science project.
|
||
ShipClass:
|
||
type: object
|
||
description: Design parameters for one ship class.
|
||
required:
|
||
- name
|
||
- drive
|
||
- armament
|
||
- weapons
|
||
- shields
|
||
- cargo
|
||
- mass
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: Ship class name.
|
||
drive:
|
||
type: number
|
||
description: Drive technology level.
|
||
armament:
|
||
type: integer
|
||
minimum: 0
|
||
description: Number of weapon mounts (ammo units).
|
||
weapons:
|
||
type: number
|
||
description: Weapons technology multiplier.
|
||
shields:
|
||
type: number
|
||
description: Shields technology multiplier.
|
||
cargo:
|
||
type: number
|
||
description: Cargo technology multiplier.
|
||
mass:
|
||
type: number
|
||
description: Computed ship mass.
|
||
OtherShipClass:
|
||
allOf:
|
||
- $ref: "#/components/schemas/ShipClass"
|
||
- type: object
|
||
required:
|
||
- race
|
||
properties:
|
||
race:
|
||
type: string
|
||
description: Race that owns this ship class.
|
||
Bombing:
|
||
type: object
|
||
description: Record of a bombing event that occurred during turn processing.
|
||
required:
|
||
- planet
|
||
- planetName
|
||
- owner
|
||
- attacker
|
||
- production
|
||
- industry
|
||
- population
|
||
- colonists
|
||
- capital
|
||
- material
|
||
- attack
|
||
- wiped
|
||
properties:
|
||
planet:
|
||
type: integer
|
||
minimum: 0
|
||
description: Global planet number.
|
||
planetName:
|
||
type: string
|
||
description: Planet name.
|
||
owner:
|
||
type: string
|
||
description: Race name of the planet owner.
|
||
attacker:
|
||
type: string
|
||
description: Race name of the attacker.
|
||
production:
|
||
type: string
|
||
description: Production type active on the planet at the time of bombing.
|
||
industry:
|
||
type: number
|
||
description: Industrial capacity remaining after the bombing.
|
||
population:
|
||
type: number
|
||
description: Population remaining after the bombing.
|
||
colonists:
|
||
type: number
|
||
description: Colonist units remaining after the bombing.
|
||
capital:
|
||
type: number
|
||
description: Capital reserves remaining after the bombing.
|
||
material:
|
||
type: number
|
||
description: Material reserves remaining after the bombing.
|
||
attack:
|
||
type: number
|
||
description: Aggregate attack power applied during the bombing.
|
||
wiped:
|
||
type: boolean
|
||
description: True when all population was eliminated by the bombing.
|
||
IncomingGroup:
|
||
type: object
|
||
description: An identified ship group inbound toward a planet of this race.
|
||
required:
|
||
- origin
|
||
- destination
|
||
- distance
|
||
- speed
|
||
- mass
|
||
properties:
|
||
origin:
|
||
type: integer
|
||
minimum: 0
|
||
description: Planet number where this group originated.
|
||
destination:
|
||
type: integer
|
||
minimum: 0
|
||
description: Planet number this group is heading toward.
|
||
distance:
|
||
type: number
|
||
description: Remaining travel distance.
|
||
speed:
|
||
type: number
|
||
description: Travel speed.
|
||
mass:
|
||
type: number
|
||
description: Total mass of the group.
|
||
UnidentifiedPlanet:
|
||
type: object
|
||
description: Minimal sensor reading for an unidentified planet.
|
||
required:
|
||
- x
|
||
- "y"
|
||
- number
|
||
properties:
|
||
x:
|
||
type: number
|
||
description: Horizontal map coordinate.
|
||
"y":
|
||
type: number
|
||
description: Vertical map coordinate.
|
||
number:
|
||
type: integer
|
||
minimum: 0
|
||
description: Global planet number.
|
||
UninhabitedPlanet:
|
||
allOf:
|
||
- $ref: "#/components/schemas/UnidentifiedPlanet"
|
||
- type: object
|
||
description: An uninhabited planet within sensor range.
|
||
required:
|
||
- size
|
||
- name
|
||
- resources
|
||
- capital
|
||
- material
|
||
properties:
|
||
size:
|
||
type: number
|
||
description: Planet size.
|
||
name:
|
||
type: string
|
||
description: Planet name.
|
||
resources:
|
||
type: number
|
||
description: Natural resource yield (R).
|
||
capital:
|
||
type: number
|
||
description: Capital reserves stored on the planet (CAP).
|
||
material:
|
||
type: number
|
||
description: Material reserves stored on the planet (MAT).
|
||
LocalPlanet:
|
||
allOf:
|
||
- $ref: "#/components/schemas/UninhabitedPlanet"
|
||
- type: object
|
||
description: Full state for a planet owned by this race.
|
||
required:
|
||
- industry
|
||
- population
|
||
- colonists
|
||
- production
|
||
- freeIndustry
|
||
properties:
|
||
industry:
|
||
type: number
|
||
description: Industrial capacity of the planet (I).
|
||
population:
|
||
type: number
|
||
description: Population of the planet (P).
|
||
colonists:
|
||
type: number
|
||
description: Number of colonists on the planet (COL).
|
||
production:
|
||
type: string
|
||
description: Current production assignment.
|
||
freeIndustry:
|
||
type: number
|
||
description: Unused industrial capacity available for new production (L).
|
||
OtherPlanet:
|
||
allOf:
|
||
- $ref: "#/components/schemas/LocalPlanet"
|
||
- type: object
|
||
description: Partial planet state for a planet owned by another race.
|
||
required:
|
||
- owner
|
||
properties:
|
||
owner:
|
||
type: string
|
||
description: Race name of the planet owner.
|
||
Route:
|
||
type: object
|
||
description: Cargo route configuration originating from one planet.
|
||
required:
|
||
- planet
|
||
- route
|
||
properties:
|
||
planet:
|
||
type: integer
|
||
minimum: 0
|
||
description: Source planet number.
|
||
route:
|
||
type: object
|
||
description: |
|
||
Mapping from destination planet number (as a string key) to the
|
||
cargo load type being routed (MAT, CAP, COL, EMP).
|
||
additionalProperties:
|
||
type: string
|
||
ShipProduction:
|
||
type: object
|
||
description: Active ship construction progress on one planet.
|
||
required:
|
||
- planet
|
||
- class
|
||
- cost
|
||
- prodUsed
|
||
- percent
|
||
- free
|
||
properties:
|
||
planet:
|
||
type: integer
|
||
minimum: 0
|
||
description: Planet number where construction is taking place.
|
||
class:
|
||
type: string
|
||
description: Name of the ship class being built.
|
||
cost:
|
||
type: number
|
||
description: Total production cost for one unit of this class.
|
||
prodUsed:
|
||
type: number
|
||
description: Production units already spent on this build.
|
||
percent:
|
||
type: number
|
||
description: Completion percentage of the current build.
|
||
free:
|
||
type: number
|
||
description: Remaining free industrial capacity on this planet.
|
||
LocalFleet:
|
||
type: object
|
||
description: A named fleet belonging to this race.
|
||
required:
|
||
- name
|
||
- groups
|
||
- destination
|
||
- speed
|
||
- state
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: Fleet name.
|
||
groups:
|
||
type: integer
|
||
minimum: 0
|
||
description: Number of ship groups in this fleet.
|
||
destination:
|
||
type: integer
|
||
minimum: 0
|
||
description: Destination planet number.
|
||
origin:
|
||
type: integer
|
||
minimum: 0
|
||
description: Origin planet number when the fleet is in transit.
|
||
range:
|
||
type: number
|
||
description: Remaining travel range when the fleet is in transit.
|
||
speed:
|
||
type: number
|
||
description: Travel speed.
|
||
state:
|
||
type: string
|
||
description: Fleet operational state.
|
||
OtherGroup:
|
||
type: object
|
||
description: A ship group visible to this race belonging to another race.
|
||
required:
|
||
- number
|
||
- class
|
||
- tech
|
||
- cargo
|
||
- load
|
||
- destination
|
||
- speed
|
||
- mass
|
||
properties:
|
||
number:
|
||
type: integer
|
||
minimum: 0
|
||
description: Group identifier number.
|
||
class:
|
||
type: string
|
||
description: Ship class name.
|
||
tech:
|
||
type: object
|
||
description: Technology levels of this group keyed by tech type name.
|
||
additionalProperties:
|
||
type: number
|
||
cargo:
|
||
type: string
|
||
description: Type of cargo carried by this group.
|
||
load:
|
||
type: number
|
||
description: Current cargo load quantity.
|
||
destination:
|
||
type: integer
|
||
minimum: 0
|
||
description: Destination planet number.
|
||
origin:
|
||
type: integer
|
||
minimum: 0
|
||
description: Origin planet number when the group is in transit.
|
||
range:
|
||
type: number
|
||
description: Remaining travel range when the group is in transit.
|
||
speed:
|
||
type: number
|
||
description: Travel speed.
|
||
mass:
|
||
type: number
|
||
description: Total mass of the group.
|
||
LocalGroup:
|
||
allOf:
|
||
- $ref: "#/components/schemas/OtherGroup"
|
||
- type: object
|
||
description: A ship group belonging to this race with full ownership detail.
|
||
required:
|
||
- id
|
||
- state
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
description: Unique group identifier.
|
||
state:
|
||
type: string
|
||
description: Group operational state.
|
||
fleet:
|
||
type: string
|
||
nullable: true
|
||
description: Name of the fleet this group belongs to, or null if ungrouped.
|
||
UnidentifiedGroup:
|
||
type: object
|
||
description: Positional reading for an unidentified ship group.
|
||
required:
|
||
- x
|
||
- "y"
|
||
properties:
|
||
x:
|
||
type: number
|
||
description: Horizontal map coordinate.
|
||
"y":
|
||
type: number
|
||
description: Vertical map coordinate.
|
||
ValidationErrorResponse:
|
||
type: object
|
||
description: Validation error returned for malformed requests.
|
||
required:
|
||
- error
|
||
properties:
|
||
error:
|
||
type: string
|
||
description: Human-readable validation error message from the binding layer.
|
||
InternalErrorResponse:
|
||
type: object
|
||
description: |
|
||
Internal server error. The shape depends on the error source:
|
||
- `{"error": "message"}` for generic runtime errors
|
||
- `{"generic_error": "message", "code": integer}` for game-engine errors
|
||
properties:
|
||
error:
|
||
type: string
|
||
description: Generic runtime error message.
|
||
generic_error:
|
||
type: string
|
||
description: Game-engine error message.
|
||
code:
|
||
type: integer
|
||
description: Game-engine error code.
|
||
responses:
|
||
ValidationError:
|
||
description: Request body or query parameters are invalid.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ValidationErrorResponse"
|
||
examples:
|
||
validationError:
|
||
value:
|
||
error: "Key: 'InitRequest.Races' Error:Field validation for 'Races' failed on the 'gte' tag"
|
||
InternalError:
|
||
description: Internal Game Service error.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/InternalErrorResponse"
|