Skip to main content

​
Get Safe Position

GET /mokepon/:playerId/safePosition
Calculates and returns a safe spawn position for a player that is not too close to existing players. The algorithm attempts up to 20 times to find a position with adequate spacing from other players.

​
Path Parameters

​
playerId
string
required
The unique player ID requesting a safe spawn position

​
Response

​
xPercent
number
required
Horizontal position as a percentage of map width (0-95)
​
yPercent
number
required
Vertical position as a percentage of map height (0-95)
​
safe
boolean
required
Indicates whether a safe position was found within 20 attempts. If false, the position may be close to other players.

​
Example

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

{
  "xPercent": 42.83749283749283,
  "yPercent": 67.29384729384729,
  "safe": true
}

​
Understanding the Safe Position Algorithm

​
Percentage-Based Coordinate System

The game uses normalized coordinates where positions are stored as percentages (0-100) of the map size. This provides several benefits:
  • Responsive Design: Works seamlessly across different screen sizes
  • Scalability: Map can be rendered at any resolution
  • Consistency: Same relative positions regardless of display dimensions
Positions are limited to 0-95% to leave room at the edges of the map, preventing players from spawning at the very border.

​
Safe Distance Calculation

The algorithm uses a 20% safe distance radius (game-state.mdx:299). Distance is calculated using the Euclidean distance formula: 
const distance = Math.sqrt(
  Math.pow(xPercent1 - xPercent2, 2) + 
  Math.pow(yPercent1 - yPercent2, 2)
);
A position is considered safe if distance >= 20 (percentage points) from all other players.

​
Algorithm Flow

  1. Generate random coordinates (0-95% range)
  2. Check distance from all existing players with defined positions
  3. If any player is within 20% distance, reject position
  4. Repeat up to 20 times
  5. Return the position with safe: true if found, or safe: false after 20 attempts
If safe: false is returned, the client should decide whether to:
  • Use the provided position anyway
  • Request a new position
  • Wait for players to move before spawning

​
Update Player Position

POST /mokepon/:playerId/position
Updates a player’s current position on the map and returns a list of all nearby enemies (both human players and CPU Mokepons). This endpoint should be called frequently during gameplay to keep positions synchronized.

​
Path Parameters

​
playerId
string
required
The unique player ID whose position is being updated

​
Request Body

​
xPercent
number
required
New horizontal position as a percentage of map width (0-100)
​
yPercent
number
required
New vertical position as a percentage of map height (0-100)

​
Response

​
enemies
array
required
Array of enemy player objects currently in the game

​
Example

curl -X POST https://mokepon-ed1d40aff3a6.herokuapp.com/mokepon/0.8472916583920145/position \
  -H "Content-Type: application/json" \
  -d '{
    "xPercent": 45.5,
    "yPercent": 62.3
  }'

{
  "enemies": [
    {
      "id": "cpu-0-1710086400123",
      "xPercent": 28.456,
      "yPercent": 55.123,
      "mokepon": {
        "name": "Capipepo",
        "type": "🌱"
      },
      "isCPU": true
    },
    {
      "id": "0.9234567890123",
      "xPercent": 72.891,
      "yPercent": 38.456,
      "mokepon": {
        "name": "Ratigueya",
        "type": "🔥"
      },
      "isCPU": false
    },
    {
      "id": "cpu-1-1710086400123",
      "xPercent": 51.234,
      "yPercent": 70.789,
      "mokepon": {
        "name": "Hipodoge",
        "type": "💧"
      },
      "isCPU": true
    }
  ]
}

​
Understanding Position Updates

​
Filtering Logic

The endpoint filters players to include in the enemies array based on these criteria (game-state.mdx:345-352):
  1. Exclude Self: player.id !== playerId
  2. Has Mokepon: player.mokepon exists
  3. Has Position: Both xPercent and yPercent are defined
  4. All Player Types: Includes both human players (isCPU: false) and CPU players (isCPU: true)
Players who have joined but not yet selected a Mokepon or set their position will not appear in the enemies list.

​
Real-Time Synchronization

This endpoint serves dual purposes:
  1. Update Own Position: Stores the current player’s new position on the server
  2. Retrieve Enemy Positions: Gets the latest positions of all other players
The endpoint does NOT validate if the position is safe or if the movement is valid. The client is responsible for implementing collision detection and movement rules.

​
CPU Player Positioning

CPU players are positioned when they’re generated:
  • X Position: Evenly distributed across segments with randomization
  • Y Position: Random value between 30% and 70% of map height
  • Segment Calculation: segment = 100 / (CPU_COUNT + 1) ensures spacing
// CPU positioning formula (from index.js:154-156)
xPercent = 20 + segment * i + (Math.random() * 10 - 5);
yPercent = 30 + Math.random() * 40;

​
When to Call This Endpoint

Recommended usage patterns:
  • Movement: Every time the player moves
  • Polling: At regular intervals (e.g., every 100-500ms) to track enemy positions
  • Before Battle: To ensure enemy position is current before initiating combat

​
Performance Considerations

The endpoint:
  • Returns all players on every call (no pagination)
  • Performs array filtering on each request
  • Does not implement rate limiting
For games with many players, consider implementing client-side caching and only requesting updates when needed to reduce server load.

Build docs developers (and LLMs) love

Get started for freeTalk to us