This is the multi-page printable view of this section. Click here to print.
Map Data Api
- 1: Introduction
- 2: Traits
- 2.1: Planet Traits
- 2.2: Robot Traits
- 2.3: Trait Structure
- 3: OpenAPI
1 - Introduction
Intoduction
The purpose of the map data api specification is to provide a standardised way to provide map related data for frontend applications.
Data Types
Data Types are oriented to be the intersect of Kafka and Player Data and Events. All basedatatypes can be derived by Kafka and player events. Optional data derivable by Kafka and player events are treated as normal value of planet or robot. Optional data defined per api source by are passed down in form of Traits for every planet or robot.
Planets
{
planetId: UUID
gameId: UUID | undefined
gameworldId: UUID | undefined
neighbours: Array<Neighbour>
resourceType: string | undefined
resource: Resource | undefined
movementDifficulty: number
traits: Array<Trait>
}
Neighbour
{
direction: string
id: UUID
}
Resource
{
amount: number
capacity: number
}
Robots
{
robotId: UUID
gameId: UUID | undefined
gameWorldId: UUID | undefined
planetId: UUID
// Can be a player Notion or UUID
playerId: string
vitals: Vitals | undefined
levels: Levels | undefined
cargo: Cargo | undefined
traits: Array<Trait>
}
Vitals
{
health: number
energy: number
}
Levels
{
health: number,
energy: number,
miningLevel: number,
miningSpeed: number,
damage: number,
energyRegeneration: number,
storage: number
}
Cargo
{
capacity: number
used: number | undefined
free: number | undefined
coal: number
iron: number
gem: number
gold: number
platin: number
}
Traits
for Traits refer to Traits
Examples
Planets:
[
{
"planetId": "01ed605c-f53d-49c8-b052-73ea016dacf3",
"gameworldId": "bece4219-7e31-480f-917f-21532b5fbe93",
"neighbours": [
{
"direction": "NORTH",
"id": "0a178693-635e-49e2-af0c-823cb84e61f4"
},
{
"direction": "SOUTH",
"id": "3ba59b3a-2c96-4b14-b23d-685fc88f2858"
}
],
"resourceType": "COAL",
"resource": {
"amount": 10000,
"capacity": 10000
},
"movementDifficulty": 0,
"traits": [
{
"trait": "position",
"context": "publicApi",
"data": {
"position": {
"x": 0,
"y": 0,
"z": 0
}
}
}
]
},
{
"planetId": "0a178693-635e-49e2-af0c-823cb84e61f4",
"gameworldId": "bece4219-7e31-480f-917f-21532b5fbe93",
"neighbours": [
{
"direction": "SOUTH",
"id": "01ed605c-f53d-49c8-b052-73ea016dacf3"
}
],
"movementDifficulty": 0,
"traits": [
{
"trait": "position",
"context": "publicApi",
"data": {
"position": {
"x": 0,
"y": 1,
"z": 0
}
}
}
]
},
{
"planetId": "01ed605c-f53d-49c8-b052-73ea016dacf3",
"gameworldId": "bece4219-7e31-480f-917f-21532b5fbe93",
"neighbours": [
{
"direction": "NORTH",
"id": "0a178693-635e-49e2-af0c-823cb84e61f4"
},
{
"direction": "SOUTH",
"id": "3ba59b3a-2c96-4b14-b23d-685fc88f2858"
}
],
"resourceType": "COAL",
"resource": {
"amount": 10000,
"capacity": 10000
},
"movementDifficulty": 0,
"traits": [
{
"trait": "position",
"context": "publicApi",
"data": {
"position": {
"x": 2,
"y": 12,
"z": 0
}
}
}
]
},
]
Robots:
[
{
"robotId": "0a178693-f53d-2c96-b23d-685fc88f2858",
"gameWorldId": "bece4219-7e31-480f-917f-21532b5fbe93",
"planetId": "01ed605c-f53d-49c8-b052-73ea016dacf3",
// Can be a player Notion or UUID since Players retrieve only a shortened PlayerId for other Players
"playerId": "bece4219-b052-49c8-f53d-73ea016dacf3",
"vitals": {
health: 20,
energy: 20
},
"levels": {
health: 0,
energy: 0,
miningLevel: 0,
miningSpeed: 0,
damage: 0,
energyRegeneration: 0,
storage: 0
},
"cargo": {
capacity: 20,
used: 20,
free: 0,
coal: 20,
iron: 0,
gem: 0,
gold: 0,
platin: 0
},
"traits": []
}
]
2 - Traits
2.1 - Planet Traits
Simple Traits
Depleted
Planet with a deposit that has been depleted by mining. Does not apply to planets that had no resource field at game start
{
trait: "depleted"
}
Discovered
Marker for a planet that has been discovered. Exact definition of a planet that has been discovered may varie by implementation.
{
trait: "discovered"
}
Undiscovered
Marker for a planet that has not been discovered yet. Exact definition of a planet that has been discovered may varie by implementation.
{
trait: "undiscovered"
}
Safe
Marker of a planet that is considered to be safe. Exact definition of a safe planet may varie by implementation.
{
trait: "safe"
}
Unsafe
Marker of a planet that is considered to be safe. Exact definition of a safe planet may varie by implementation.
{
trait: "unsafe"
}
Space Station
Marker of a planet that has a space station attached to it. (May not be implemented yet or beeing unused)
{
trait: "spaceStation"
}
Target Traits
Complex Traits
Position
Defines the relative position of a planet for rendering purpose. (e.g. Map rendering in a grid layout) Positions are relative to a layer if provided
{
trait: "position",
data: {
position: {
x: number
y: number
// technically not required yet but if needed in the future
z: number | undefined
}
}
}
Layer
Used to define a layer in which clusters of planets are defined. A cluster of planets are planets, that can be reached from any planet in the same cluster.
{
trait: "layer",
data: {
layer: string
}
}
Examples how data can be displayed :
Simple Traits (here depleted Trait)
As simple Traits work as a label , they can only show 2 states depending of the data. They can be used to determine if an icon should show different version (e.g. grayscale).
simplefied example of it can be used:
(planet containing ore and one having it depleted)
Position Trait
simplified view of data using the Position Trait in a global context
Json
{
{
"planetId": "1",
"gameworldId": "1",
"neighbours": [
{
"direction": "NORTH",
"id": "2"
},
],
"resourceType": null,
"resource": null,
"movementDifficulty": 0,
"traits": [
{
"trait": "position",
"context": "publicApi",
"data": {
"position": {
"x": 0,
"y": 0,
"z": 0
}
}
}
]
},
{
"planetId": "2",
"gameworldId": "1",
"neighbours": [
{
"direction": "SOUTH",
"id": "1"
},
{
"direction": "EAST",
"id": "3"
},
],
"resourceType": null,
"resource": null,
"movementDifficulty": 0,
"traits": [
{
"trait": "position",
"context": "publicApi",
"data": {
"position": {
"x": 0,
"y": 1,
"z": 0
}
}
}
]
},
{
"planetId": "3",
"gameworldId": "1",
"neighbours": [
{
"direction": "WEST",
"id": "2"
},
],
"resourceType": null,
"resource": null,
"movementDifficulty": 0,
"traits": [
{
"trait": "position",
"context": "publicApi",
"data": {
"position": {
"x": 0,
"y": 0,
"z": 0
}
}
}
]
},
{
"planetId": "4",
"gameworldId": "1",
"neighbours": [
{
"direction": "EAST",
"id": "1"
},
],
"resourceType": null,
"resource": null,
"movementDifficulty": 0,
"traits": [
{
"trait": "position",
"context": "publicApi",
"data": {
"position": {
"x": 0,
"y": 0,
"z": 0
}
}
}
]
},
}
Layer + Position Trait
Simplified view of data using a local context by providing the layer Trait
Json
{
{
"planetId": "1",
"gameworldId": "1",
"neighbours": [
{
"direction": "NORTH",
"id": "2"
},
],
"resourceType": null,
"resource": null,
"movementDifficulty": 0,
"traits": [
{
"trait": "position",
"context": "publicApi",
"data": {
"position": {
"x": 0,
"y": 0,
"z": 0
}
}
}
]
},
{
"planetId": "2",
"gameworldId": "1",
"neighbours": [
{
"direction": "SOUTH",
"id": "1"
},
{
"direction": "EAST",
"id": "3"
},
],
"resourceType": null,
"resource": null,
"movementDifficulty": 0,
"traits": [
{
"trait": "position",
"context": "publicApi",
"data": {
"position": {
"x": 0,
"y": 0,
"z": 0
}
}
}
{
"trait": "layer",
"data": {
"layer": ""
}
}
]
},
{
"planetId": "3",
"gameworldId": "1",
"neighbours": [
{
"direction": "WEST",
"id": "2"
},
],
"resourceType": null,
"resource": null,
"movementDifficulty": 0,
"traits": [
{
"trait": "position",
"context": "publicApi",
"data": {
"position": {
"x": 0,
"y": 1,
"z": 0
}
}
},
{
"trait": "layer",
"data": {
"layer": "1"
}
}
]
},
{
"planetId": "4",
"gameworldId": "1",
"neighbours": [
{
"direction": "EAST",
"id": "1"
},
],
"resourceType": null,
"resource": null,
"movementDifficulty": 0,
"traits": [
{
"trait": "position",
"context": "publicApi",
"data": {
"position": {
"x": -1,
"y": 0,
"z": 0
}
}
},
{
"trait": "layer",
"data": {
"layer": "2"
}
}
]
},
}
2.2 - Robot Traits
Simple Traits
Hostile
Marker for robots considered to be hostile / enemies.
{
trait: "hostile"
}
Friendly
Marker for friendly robots.
May apply for other players robots (e.g. Aliance).
{
trait: "friendly"
}
Target Traits
Complex Traits
Role Trait
Role of the robot.
primaryRole describes the main role of the robot.
secondaryRole describes the secondary Role of the Robot if needed.
example use of secondaryRole would be commander, a role that commands other robots.
Sample Roles:
- “miner”
- Mining of resources
- “fighter”
- Fighting other robots
- “scout”
- Exploring the map
- “commander”
- Commanding other robots
{
trait: "role",
data: {
primaryRole: string
secondaryRole: string | undefined
}
}
Roles
Similar to Role if a robot has multiple roles it fullfils
{
trait: "roles",
data: {
roles : string[]
}
}
State Trait
Defines the current actions a robot is doing
sample states:
- “mining”
- “fleeing”
- “trading”
- “upgrading”
- “moving”
{
trait: "state",
data: {
state : string
}
}
Status
Current Status Information of the robot
sample Status:
- “fullCargo”
- “lowHealth”
- “lowEnergy”
{
trait: "status",
data: {
status: string
}
}
Example Usage on how Robot Traits can be used
Hostile / Friendly
Different contexts can be used to determine which Robots are considered as friendly or hostile from multiple perspectives.
[
{
"trait": "hostile",
"context": "Player1"
},
{
"trait": "friendly",
"context": "Player2"
},
{
"trait": "hostile",
"context": "Player1_priority_attack_targets"
},
]
Role / Roles
Roles can be used depending on the data to visualize Robots differently. Example usages is to have different Models depending on the combination of Roles, or just as simple to highlight those through a search Option
{
"trait": "role",
"data": {
"primaryRole": "miner",
"secondaryRole": "commander"
}
}
{
"trait": "roles",
"data": {
"roles": [
"miner",
"commander"
]
}
}
2.3 - Trait Structure
Trait Categories
Simple Trait
{
// Optional value that represents the Trait Context if provided.
// Possible usage is to show context specific data if multiple are provided
context: string | undefined
// Trait Type Identifier
trait: string
}
Refer to PlanetTraits , RobotTraits for examples
Target Trait
Reference to other Planets / Robots for a specific
{
context: string | undefined
trait: string
// Selector to which Objects it References
selector: "robot" | "planet"
// List of the Ids that are referenced
target: Array<UUID>
}
Refer to PlanetTraits , RobotTraits for examples
Complex Trait
Traits that provide more Data that cant be provided as Simple Trait
{
context: string | undefined
trait: string
// Additional Data provided
data: TraitData
}
Refer to PlanetTraits , RobotTraits for examples
Reserved Trait Types
Some trait types are standardised by the api specification and should not be used for custom trait types specified by third partie implementation
Refer to PlanetTraits , RobotTraits for a list of predefined traits