Skip to main content

​
Introduction

The Mokepon Game API is a RESTful backend service built with Express.js that powers a multiplayer monster battle game. It manages player sessions, character (Mokepon) selection, real-time position tracking, and turn-based combat mechanics with CPU opponents.

​
Base URL

https://mokepon-ed1d40aff3a6.herokuapp.com

​
Authentication

The API currently does not implement authentication. All endpoints are publicly accessible. Player identity is managed through unique session IDs generated by the /join endpoint.

​
Common Patterns

​
Player Identification

All player-specific endpoints use :playerId as a URL parameter. This ID is obtained when a player first joins the game via the /join endpoint.

​
Percentage-Based Positioning

The game uses a normalized coordinate system where positions are stored as percentages (0-100) of the map size. This allows the game to work seamlessly across different screen sizes and resolutions.
  • xPercent: Horizontal position (0-100)
  • yPercent: Vertical position (0-100)

​
CPU Players

The server automatically generates 3 CPU-controlled Mokepons when human players join. CPU players:
  • Have IDs prefixed with cpu-
  • Are marked with isCPU: true
  • Automatically select attacks through dedicated endpoints
  • Regenerate when all human players leave

​
CORS Configuration

The API is configured with the following CORS settings: 
{
  origin: process.env.NODE_ENV === 'production' 
    ? 'https://mokepon-ed1d40aff3a6.herokuapp.com' 
    : '*',
  methods: ['GET', 'POST', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization']
}
In development mode, CORS allows requests from any origin (*). In production, only requests from the production domain are allowed.

​
Error Handling

All endpoints use centralized error handling middleware. Errors return JSON responses with the following structure: 
{
  "success": false,
  "message": "Error description",
  "error": "Stack trace (development only)"
}

​
Common HTTP Status Codes

  • 200 - Success
  • 400 - Bad Request (missing or invalid parameters)
  • 404 - Not Found (player or resource doesn’t exist)
  • 500 - Internal Server Error

​
API Endpoints

Join Game

Create a new player session and receive a unique player ID

Assign Mokepon

Select and assign a Mokepon character to a player

Remove Player

Remove a player from the active game session

Get Safe Position

Get a spawn position that’s not too close to other players

Update Position

Update player position and retrieve nearby enemies

Submit Attacks

Submit the player’s selected attacks for a battle

Get Attacks

Retrieve an opponent’s attack sequence

CPU Attack

Get a CPU’s next attack selection

Check Advantage

Check if CPU has type advantage and grant bonus attack

Reset Attacks

Reset CPU’s available attacks for a new battle round

​
Mokepon Types

The game features six different Mokepons with three elemental types:
MokeponTypeEmoji
HipodogeWater💧
PydosWater💧
CapipepoPlant🌱
TucapalmaPlant🌱
RatigueyaFire🔥
LangostelvisFire🔥

​
Type Advantage System

Combat follows a rock-paper-scissors mechanic:
  • 💧 Water beats 🔥 Fire
  • 🔥 Fire beats 🌱 Plant
  • 🌱 Plant beats 💧 Water
When a CPU has type advantage over an opponent, it receives an extra attack of its primary type through the /check-advantage endpoint.

​
Security Features

The API uses Helmet.js for security headers including:
  • Content Security Policy (CSP)
  • DNS Prefetch Control
  • Frame Options
  • HSTS (HTTP Strict Transport Security)
  • IE No Open
  • XSS Filter
Additionally, compression middleware is enabled for improved performance.

Build docs developers (and LLMs) love

Get started for freeTalk to us