Something went wrong. Try again.
OpenAPI 3.0 compliant spec for TLE Community.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473// Functions for reusing bits within this API spec.// Note that stuff in here is going outside the Open API recommendations to try to make this whole// API spec to try to write and understand. Ultimately a full JSON file is output at the end but we use these functions// to simplify generation of that result.
/** Takes the output of buildingBase() (which includes a `v2/` prefix) and produces a word string ie "planetarycommand" */export const tags = (base: string) => { const list = base.split('/'); const tag = list[list.length - 1].toLowerCase(); return { tags: [tag] };};
// Overrides the tag on every operation in a paths object. Used by multi-tile buildings (e.g.// /v2/beach1../v2/beach13) so all tiles group under a single Swagger UI tag rather than one// tag per tile path.export const retag = <T extends Record<string, Record<string, { tags?: string[] }>>>( paths: T, tag: string): T => { for (const pathItem of Object.values(paths)) { for (const operation of Object.values(pathItem)) { operation.tags = [tag]; } } return paths;};
export const security = () => { return { security: [{ tokenHttpAuthentication: [] }] };};
// Operation-level prose: `summary` is the short line Swagger UI shows next to the path,// `description` is the fuller explanation shown when the operation is expanded. Both are// lifted from the original pod documentation.export const operation = (summary: string, description: string) => { return { summary, description };};
export const jsonContent = (data: object = {}) => { return { content: { 'application/json': { ...data } } };};
export const requestBodySchema = (schema: object) => { return { requestBody: { ...jsonContent({ schema }) } };};
export const response200 = (description: string, resultSchema: object) => { return { '200': { description, ...jsonContent({ schema: { type: 'object', properties: { id: { type: 'number' }, jsonrpc: { type: 'string' }, result: resultSchema }, }, }), }, };};
export const response500 = () => { return { '500': { description: 'RPC Error', content: { 'application/json': { schema: { $ref: '#/components/schemas/rpc_error' } } }, }, };};
export const statusSchema = () => { return { type: 'object', properties: { server: { $ref: '#/components/schemas/server_status' }, empire: { $ref: '#/components/schemas/empire_status' }, body: { $ref: '#/components/schemas/body_status' }, }, required: ['server'], };};
// The base `/v2/<name>` path segment for a building or module, derived from its doc page name// (e.g. `buildingBase('GasGiantPlatform')` -> `/v2/gasgiantplatform`).export const buildingBase = (name: string) => `/v2/${name.toLowerCase()}`;
// The `build`, `upgrade`, `downgrade`, `demolish`, `repair`, and `get_stats_for_level` methods// shared by every regular (non-module) building type. `view` is intentionally excluded — nearly// every building type adds its own extra fields to `view`, so it's defined per-building via// buildingView() instead.export const buildingCommonMethods = (base: string) => { const buildingIdRequestBody = requestBodySchema({ type: 'object', required: ['building_id'], properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } }, });
const pendingBuildSchema = { type: 'object', properties: { seconds_remaining: { type: 'integer' }, start: { type: 'string' }, end: { type: 'string' }, }, required: ['seconds_remaining', 'start', 'end'], };
const queueResultSchema = (description: string) => ({ ...response200(description, { type: 'object', required: ['building', 'status', 'buildings'], properties: { building: { type: 'object', properties: { id: { type: 'integer' }, level: { type: 'integer' }, pending_build: pendingBuildSchema, }, required: ['id', 'level', 'pending_build'], }, status: statusSchema(), buildings: { $ref: '#/components/schemas/buildings_list' }, }, }), ...response500(), });
const buildingViewResultSchema = (description: string) => ({ ...response200(description, { type: 'object', required: ['building', 'status', 'buildings'], properties: { building: { $ref: '#/components/schemas/building' }, status: statusSchema(), buildings: { $ref: '#/components/schemas/buildings_list' }, }, }), ...response500(), });
return { [`${base}/build`]: { post: { ...tags(base), ...security(), ...operation( 'Queue this building for construction.', "Adds this building to the planet's build queue at the given surface coordinates. Throws 1002, 1010, 1011, 1012, and 1013." ), ...requestBodySchema({ type: 'object', required: ['body_id', 'x', 'y'], properties: { body_id: { type: 'integer', description: 'The id of the planet you wish to build on.' }, x: { type: 'integer', minimum: -5, maximum: 5, description: 'The x axis of the tile on the planet surface to place the building on. Valid values are between -5 and 5 inclusive.', }, y: { type: 'integer', minimum: -5, maximum: 5, description: 'The y axis of the tile on the planet surface to place the building on. Valid values are between -5 and 5 inclusive.', }, }, }), responses: queueResultSchema("Adds this building to the planet's build queue."), }, },
[`${base}/upgrade`]: { post: { ...tags(base), ...security(), ...operation( 'Queue an upgrade for this building.', 'Adds the requested upgrade to the build queue. Throws 1002, 1010, 1011, 1012, and 1013.' ), ...buildingIdRequestBody, responses: queueResultSchema('Adds the requested upgrade to the build queue.'), }, },
[`${base}/downgrade`]: { post: { ...tags(base), ...security(), ...operation( 'Downgrade this building by one level.', "Downgrades a building by one level and then returns the building's view. Downgrading a level 1 building removes it, so the client must drop it from the display. Throws 1012." ), ...buildingIdRequestBody, responses: buildingViewResultSchema( "Downgrades a building by one level and then returns the building's view." ), }, },
[`${base}/demolish`]: { post: { ...tags(base), ...security(), ...operation( 'Instantly destroy this building.', 'Instantly destroys a building. Throws 1012.' ), ...buildingIdRequestBody, responses: { ...response200('Instantly destroys a building.', { type: 'object', required: ['status', 'buildings'], properties: { status: statusSchema(), buildings: { $ref: '#/components/schemas/buildings_list' }, }, }), ...response500(), }, }, },
[`${base}/repair`]: { post: { ...tags(base), ...security(), ...operation( 'Repair this building to full efficiency.', "Restores a building's efficiency to 100%, spending the resources listed in the view's repair_costs, then returns the building's view." ), ...buildingIdRequestBody, responses: buildingViewResultSchema( "Restores a building's efficiency to 100%, then returns the building's view." ), }, },
[`${base}/get_stats_for_level`]: { post: { ...tags(base), ...security(), ...operation( "Project this building's stats at a given level.", 'Returns the projected stats of an existing building at a certain level. The building must already exist, because where it is and who owns it affects its stats. Intended for power users and script writers. Throws 1009.' ), ...requestBodySchema({ type: 'object', required: ['building_id', 'level'], properties: { building_id: { type: 'integer', description: 'The unique id of the building you want to get the stats for.', }, level: { type: 'integer', minimum: 1, maximum: 100, description: 'An integer between 1 and 100 representing the level you want to see the stats for.', }, }, }), responses: { ...response200( 'Returns the projected stats of a building at a given level. The building must already exist, since where it exists and who owns it affects the stats.', { type: 'object', required: ['building', 'status'], properties: { building: { type: 'object', properties: { id: { type: 'integer' }, name: { type: 'string' }, image: { type: 'string' }, level: { type: 'integer' }, food_hour: { type: 'integer' }, food_capacity: { type: 'integer' }, energy_hour: { type: 'integer' }, energy_capacity: { type: 'integer' }, ore_hour: { type: 'integer' }, ore_capacity: { type: 'integer' }, water_hour: { type: 'integer' }, water_capacity: { type: 'integer' }, waste_hour: { type: 'integer' }, waste_capacity: { type: 'integer' }, happiness_hour: { type: 'integer' }, upgrade: { type: 'object', properties: { cost: { $ref: '#/components/schemas/building_cost' }, production: { $ref: '#/components/schemas/building_production' }, image: { type: 'string' }, }, required: ['cost', 'production', 'image'], }, }, required: ['id', 'name', 'image', 'level'], }, status: statusSchema(), }, } ), ...response500(), }, }, }, };};
// The `view` method for a building or module. `extraProperties`/`extraRequired` describe fields// the building type adds as siblings of `building`/`status` (e.g. OreStorage adds `ore_stored`,// PlanetaryCommand adds `planet`, Capitol adds `rename_empire_cost`).export const buildingView = ( base: string, extraProperties: object = {}, extraRequired: string[] = []) => { return { [`${base}/view`]: { post: { ...tags(base), ...security(), ...operation( "Retrieve this building's properties.", 'Retrieves the properties of the building: its production, capacity, efficiency, repair costs, upgrade and downgrade options, and any pending build or work state. Throws 1002 and 1010.' ), ...requestBodySchema({ type: 'object', required: ['building_id'], properties: { building_id: { type: 'integer', description: 'The id of the building you wish to retrieve.', }, }, }), responses: { ...response200('Retrieves the properties of the building.', { type: 'object', required: ['building', 'status', ...extraRequired], properties: { building: { $ref: '#/components/schemas/building' }, status: statusSchema(), ...extraProperties, }, }), ...response500(), }, }, }, };};
export const speciesSchema = () => { return { type: 'object', required: [ 'name', 'description', 'min_orbit', 'max_orbit', 'manufacturing_affinity', 'deception_affinity', 'research_affinity', 'management_affinity', 'farming_affinity', 'mining_affinity', 'science_affinity', 'environmental_affinity', 'political_affinity', 'trade_affinity', 'growth_affinity', ], properties: { name: { type: 'string', description: 'The name of the species. Limited to 30 characters, cannot be blank, and cannot contain @, &, <, >, or ;.', }, description: { type: 'string', description: 'The species description. Limited to 1024 characters and cannot contain < or >.', }, min_orbit: { type: 'integer', minimum: 1, maximum: 7, description: 'The closest orbit this species can inhabit, where 1 is nearest the star. Every orbit from min_orbit to max_orbit inclusive costs a point. Must be less than or equal to max_orbit.', }, max_orbit: { type: 'integer', minimum: 1, maximum: 7, description: 'The furthest orbit this species can inhabit, where 1 is nearest the star. Every orbit from min_orbit to max_orbit inclusive costs a point. Must be greater than or equal to min_orbit.', }, manufacturing_affinity: { type: 'integer', minimum: 1, maximum: 7, description: '7 is best. Determines advantages in manufactured goods, such as ships.', }, deception_affinity: { type: 'integer', minimum: 1, maximum: 7, description: '7 is best. Determines advantages in spying.', }, research_affinity: { type: 'integer', minimum: 1, maximum: 7, description: '7 is best. Determines advantages in upgrading buildings.', }, management_affinity: { type: 'integer', minimum: 1, maximum: 7, description: '7 is best. Determines advantages in the speed of building.', }, farming_affinity: { type: 'integer', minimum: 1, maximum: 7, description: '7 is best. Determines advantages in food production.', }, mining_affinity: { type: 'integer', minimum: 1, maximum: 7, description: '7 is best. Determines advantages in mineral production.', }, science_affinity: { type: 'integer', minimum: 1, maximum: 7, description: '7 is best. Determines advantages in energy, propulsion, and other technologies.', }, environmental_affinity: { type: 'integer', minimum: 1, maximum: 7, description: '7 is best. Determines advantages in waste and water management.', }, political_affinity: { type: 'integer', minimum: 1, maximum: 7, description: '7 is best. Determines advantages in managing population happiness.', }, trade_affinity: { type: 'integer', minimum: 1, maximum: 7, description: '7 is best. Determines advantages in freight handling.', }, growth_affinity: { type: 'integer', minimum: 1, maximum: 7, description: '7 is best. Determines advantages in colonization.', }, }, };};