V1 API docs

Write an API client that plays instead of you

1) Start a game in Story mode
2) Beat as many levels as you can by writing code in your favorite IDE
3) Win a job interview at ICF Tech Hungary without boring HR questions

Your code shall call the endpoints of this API to play the game

Beating a Map (The Game)

You play a turn-based game - You set what you want to do on the next tick (turn) of the Map, and then trigger a tick.

To beat a Map, collect all the treasures on it by controlling your Hero. A Hero is basically your Player's "presence" on a Map. You can control your Hero by calling endpoints described below:

Right after your Map was generated (we'll talk about how this happens later), call the GET play/mapResource endpoint - it returns immutable resources that you should store until you finish the Map. I.e. you should only call this endpoint once for a Map.

After you got your Map's resources from GET play/mapResource, the turn-based game can start. There are two endpoints that you'll probably regularly call in your implementation:

1. GET play/mapState - returns the current state of all the moving parts on the Map
2. POST play/approveHeroTurn - sets the next move of a Hero

Combining the prefetched data from the GET play/mapResource endpoint with data from the GET play/mapState endpoint gives you the full state of the Map you're playing on - thus your API client implementation can decide what the next action of the Hero should be.

After your implementation calculated the action, it can call the POST play/approveHeroTurn endpoint to submit it. The submitted action will be executed on the next tick. POST play/approveHeroTurn also ticks the Map if all the Heroes on the Map approved their turn.

Game elements:

• Obstacle: You can't go through obstacles
• Treasure: You can collect them by stepping on them. Collect them all and win the map!
• Enemy: Tries to kill you before collecting the treasures
• Bullet: Enemies can shoot bullets at you, which then move on the map slowly, in a straight line
• Hero: Your (or in multiplayer, someone else's) presence on the map. A character you control

Enemies are moving towards the closest Hero. If they manage to step on the same field as a Hero, they deal Touch Damage. Enemies also shoot Bullets at you. A Bullet has a direction and advances one field on every tick (in a straight line).

To attack an Enemy, submit the "KICK_*" actions . These actions damage the Enemies standing on the Hero's field, on its neighboring field, and on its second neighboring field.

To protect against a Bullet, submit the USE_SHIELD action - it reduces the Bullet Damage to zero. You should apply "USE_SHIELD" exactly on the tick when the Bullet arrives on the field of your Hero.

You can tell that a Map is finished if "$.map.status" in the response of GET play/mapState is "WON".

Order of execution in a tick:

1. Bullets move
2. Enemies move
3. Heroes move
4. Heroes set defense up (USE_SHIELD)
5. Enemies attack (touch damage, shoot bullets)
6. Bullets deal damage
7. Heroes attack

Game Modes

Progressing through a Story (Story mode)

A Story is a predefined list of Map specifications, i.e., levels. It starts when you start the game on ponypanic.io or call the POST story/begin endpoint.

Playing in Story mode means that there is a StoryPlaythrough entity that tracks your progress across Story levels (Maps). A StoryPlaythrough always provides a Map that you have to beat to get to the next level.

When you play a StoryPlaythrough, we auto-generate Maps for you based on the Story's Map specification belonging to your current level.

After you beat a Map, you can proceed to the next level by calling the POST story/nextLevel endpoint. This endpoint generates you a whole new Map that you shall beat. After you finished the last Map, you won the StoryPlaythrough - Yaay, congrats!

If you hit a deadlock, just call POST story/resetLevel to generate a new Map for your current level.

To win a StoryPlaythrough, you have to beat all the generated Maps in a consecutive order.

Creating and playing standalone maps (Freestyle mode)

You can generate Maps by custom generation parameters (size, difficulty, etc). To do this, call POST freestyle/createMap and provide the parameters.

POST freestyle/createMap returns a Map-Token that you can use to interact with the Map.

To put a Hero on a Map (i.e., to be able to play the Map), call the POST freestyle/joinMap endpoint.

Authentication

There are three entities that you can authenticate to:

• Player entity: Your identity that is generated when you start the game on ponypanic.io. You should stick to one Player (instead of generating multiple ones) so we can count your score
• Map entity: A map that you can beat. Multiple Players can play on the same map if they can authenticate the Map (and the map itself allows for multiple players)
• StoryPlaythrough entity: Your progress during a playing through a story. It also authenticates your Player and the current level's Map so you don't have to authenticate neither Player nor Map if you authenticated the StoryPlaythrough

To authenticate an entity, add its token to your HTTP requests as the value of the appropriate header:

• For Player, add the Player-Token as the "player-token" header
• For Map, add the Map-Token as the "map-token" header
• For StoryPlaythrough, add the Story-Playthrough-Token as the "story-playthrough-token" header

Obtaining the tokens:

• Player-Token: 1) Click the "Show Tokens" button on the right side of the game interface on ponypanic.io. or 2) If you already registered with an email, click the login button on ponypanic.io and follow the instructions to claim your token
• Map-Token: Call POST freestyle/createMap (this creates a new Map so you can't obtain an existing Map's token this way)
• Story-Playthrough-Token: Click the "Show Tokens" button on the right side of the game interface on ponypanic.io

Endpoints

All these endpoints are HTTP, use JSON in their request & response bodies, and require partial auth described in the Authentication section above. Their base URL is https://ponypanic.io/playGameApi/v1/.

1{
2    "map": {
3        "id": 99642,
4        "width": 5,
5        "height": 5,
6        "elapsedTickCount": 0,
7        "status": "PLAYING", // V1MapStatus
8        "isGameOver": false,
9        "treasures": [], // V1TreasureResponse array
10        "enemies": [], // V1EnemyResponse array
11        "bullets": [] // V1BulletResponse array
12    },
13    "heroes": [] // V1HeroResponse array
14}

1{
2    "compressedObstacles": {
3        "coordinateMap": {
4            "1": [ 2, 6, 8 ],
5            "2": [ 4, 5 ],
6            "4": [ 4, 8 ]
7        }
8    }
9}

1{
2    "heroId": 17, // Ignore this if you're playing Story mode
3    "action": "NOTHING" // :HeroAction
4}

1{
2    "storyPlaythroughId": 17,
3    "storyPlaythroughToken": "17_topsecret",
4    "playthroughState": V1PlaythroughStateResponse
5}

1{
2    "playthroughState": V1PlaythroughStateResponse
3}

1{
2    "playthroughState": V1PlaythroughStateResponse
3}

1{
2    "width": 5, // nullable
3    "height": 5, // nullable
4    "treasureCount": 2, // nullable
5    "obstaclesPresent": true, // nullable
6    "enemyConfig": V1EnemyConfigRequest, // nullable
7}

1{
2    "heroId": 17 // ID of the new Hero
3}

Schemas

1{
2    "currentLevel": 1, // number - nth level
3    "isCurrentLevelFinished": false, // boolean
4    "currentMapStatus": "PLAYING", // V1MapStatus
5    "storyLine": "hi there" // string
6}

1{
2    "id":1, // unique ID of the Hero
3    "position": {
4        "x": 4,
5        "y": 2
6    },
7    "health": 1.0, // dies when reaches 0
8}

1{
2    "id":1, // unique ID of the Treasure
3    "position": {
4        "x": 4,
5        "y": 2
6    },
7    "name": "Some treasure",
8    "collectedByHeroId": null // null or number
9}

1{
2    "id":1, // unique ID of the Enemy
3    "position": {
4        "x": 4,
5        "y": 2
6    },
7    "moveProbability": 0.2, // chance to step to a neighbouring field in a tick
8    "shootProbability": 0.3, // chance to release a bullet in a tick
9    "onTouchDamage": 0.4, // deals this much damage in every tick when located on the same field as a Hero
10    "bulletDamage": 0.5, // shoots bullets that has this much damage
11    "health": 0.6, // dies when reaches 0
12}

1{
2    "id":1, // unique ID of the Bullet
3    "position": {
4        "x": 4,
5        "y": 2
6    },
7    "damage": 0.3,
8    "direction": "RIGHT", // V1Direction
9    "shotByEnemyId": 23
10}

1{
2    "count": number, // count of enemies to put on the map 
3    "canMove": boolean, // sets if enemies can move
4    "canShoot": boolean, // sets if enemies can shoot
5    "canDamageOnTouch": boolean, // sets if enemies can deal damage when they touch a Hero 
6}