Skip to main content

​
Join Game

GET /join
Creates a new player session and returns a unique player ID. This is the first endpoint that must be called when a player enters the game. If no CPU Mokepons exist, this endpoint will also trigger the generation of 3 CPU opponents.

​
Response

​
success
boolean
required
Indicates if the player was successfully created
​
id
string
required
Unique player identifier (random decimal string)

​
Example

curl -X GET https://mokepon-ed1d40aff3a6.herokuapp.com/join

{
  "success": true,
  "id": "0.8472916583920145"
}
The player ID is a random decimal string generated using Math.random(). Store this ID for all subsequent API calls.

​
Assign Mokepon

POST /mokepon/:playerId
Assigns a Mokepon character to a player. This must be called after joining the game and before the player can participate in battles.

​
Path Parameters

​
playerId
string
required
The unique player ID obtained from the /join endpoint

​
Request Body

​
mokeponName
string
required
Name of the Mokepon to assign. Valid options:
  • Hipodoge (Water 💧)
  • Pydos (Water 💧)
  • Capipepo (Plant 🌱)
  • Tucapalma (Plant 🌱)
  • Ratigueya (Fire 🔥)
  • Langostelvis (Fire 🔥)

​
Response

​
success
boolean
required
Indicates if the Mokepon was successfully assigned

​
Example

curl -X POST https://mokepon-ed1d40aff3a6.herokuapp.com/mokepon/0.8472916583920145 \
  -H "Content-Type: application/json" \
  -d '{"mokeponName": "Hipodoge"}'

{
  "success": true
}

​
Error Cases

  • 400 Bad Request: Missing playerId or mokeponName
  • 404 Not Found: Player ID doesn’t exist in the active players list

​
Remove Player (DELETE)

DELETE /player/:playerId
Removes a player from the active game session. This is typically called when a player manually restarts or reloads the game.

​
Path Parameters

​
playerId
string
required
The unique player ID to remove from the game

​
Response

​
success
boolean
required
Indicates if the player was successfully removed
​
message
string
required
Description of the operation result

​
Example

curl -X DELETE https://mokepon-ed1d40aff3a6.herokuapp.com/player/0.8472916583920145

{
  "success": true,
  "message": "Player removed successfully"
}
When the last human player is removed, the server automatically regenerates all CPU Mokepons with new positions and characters.

​
Remove Player (GET - Beacon API)

GET /player/:playerId
Alternative endpoint for removing a player using a GET request. This is designed to work with the Browser Beacon API, which allows sending requests during page unload events (when the user closes the tab or navigates away).

​
Path Parameters

​
playerId
string
required
The unique player ID to remove from the game

​
Response

​
success
boolean
required
Indicates if the player was successfully removed
​
message
string
required
Description of the operation result

​
Example

curl -X GET https://mokepon-ed1d40aff3a6.herokuapp.com/player/0.8472916583920145

{
  "success": true,
  "message": "Player removed successfully"
}
This endpoint uses the same logic as the DELETE endpoint but accepts GET requests to support the Beacon API, which typically uses GET or POST methods.

​
Implementation Notes

​
Player Storage

Players are stored in an in-memory array on the server: 
const players = [];
Important: Player data is stored in memory and will be lost if the server restarts. There is no persistent database.

​
Player Class Structure

Each player is instantiated from the Player class with the following properties: 
class Player {
  constructor(id) {
    this.id = id;
    this.xPercent = undefined;
    this.yPercent = undefined;
    this.mokepon = null;
    this.attacks = [];
    this.isCPU = false;
  }
}

​
CPU Regeneration Logic

The server checks if human players remain active after each player removal. The regeneration logic (player-management.mdx:280):
  1. Removes all existing CPU players from the players array
  2. Generates 3 new CPU Mokepons with random selections
  3. Assigns random positions spread across the map
  4. Initializes each CPU with a standard attack set

​
Mokepon Type Detection

When a Mokepon is assigned, its type is automatically determined by the getMokeponType() function (player-management.mdx:105-119) based on the character name.

Build docs developers (and LLMs) love

Get started for freeTalk to us