Combat System

Submit Player Attacks

POST /mokepon/:playerId/attacks

Submits a player’s selected attack sequence for a battle. The attacks are stored on the server and can be retrieved by opponents using the GET endpoint.

Path Parameters

playerId

string

required

The unique player ID submitting their attacks

Request Body

attacks

array

required

Array of attack types (emoji strings). Each attack should be one of:

💧 (Water)
🔥 (Fire)
🌱 (Plant)

Response

The endpoint returns an empty response with HTTP 200 status on success.

Example

curl -X POST https://mokepon-ed1d40aff3a6.herokuapp.com/mokepon/0.8472916583920145/attacks \
  -H "Content-Type: application/json" \
  -d '{
    "attacks": ["💧", "💧", "🔥", "🌱", "💧"]
  }'

Attack sequences typically consist of 5 attacks selected by the player from their available attack pool. The order matters as attacks are executed sequentially during battle.

Get Opponent Attacks

GET /mokepon/:playerId/attacks

Retrieves the attack sequence for a specific player or CPU opponent. This endpoint is called to get an opponent’s attacks before or during battle.

Path Parameters

playerId

string

required

The unique ID of the opponent whose attacks you want to retrieve

Response

attacks

array

required

Array of attack types. For CPU players, this returns the attackList (dynamically generated attacks). For human players, returns the submitted attacks array.

isCPU

boolean

required

Indicates whether this player is CPU-controlled

Example

curl -X GET https://mokepon-ed1d40aff3a6.herokuapp.com/mokepon/cpu-0-1710086400123/attacks

{
  "attacks": ["🌱", "🔥", "🌱"],
  "isCPU": true
}

If the player ID doesn’t exist or the player hasn’t submitted attacks yet, the endpoint returns an empty attacks array rather than throwing an error.

Get CPU Attack

GET /mokepon/:playerId/cpu-attack

Returns the next attack selection for a CPU opponent. This endpoint randomly selects from the CPU’s available attacks and removes it from the pool for the current round. Each attack can only be used once per round unless replenished.

Path Parameters

playerId

string

required

The CPU player ID (must start with cpu- and have isCPU: true)

Response

attack

string

required

The selected attack type (💧, 🔥, or 🌱)

allAttacks

array

required

Complete list of all attacks used by this CPU so far in the current round

remainingAttacks

array

required

Array of attacks still available for this CPU to use in the current round

Example

curl -X GET https://mokepon-ed1d40aff3a6.herokuapp.com/mokepon/cpu-0-1710086400123/cpu-attack

{
  "attack": "🌱",
  "allAttacks": ["🌱"],
  "remainingAttacks": ["🌱", "🌱", "💧", "🔥"]
}

Understanding CPU Attack Selection

Attack Pool Management

CPU players maintain two attack arrays:

attacks: The master list of all available attacks (never modified)
availableAttacks: A copy that’s depleted as attacks are used

// Initial CPU attack pool (from index.js:159-172)
const attacks = [];
for (let j = 0; j < 3; j++) {
  attacks.push(mokepon.type); // 3 attacks of primary type
}

// Add two different attack types
if (mokepon.type === '💧') {
  attacks.push('🔥', '🌱');
} else if (mokepon.type === '🔥') {
  attacks.push('💧', '🌱');
} else {
  attacks.push('💧', '🔥');
}

// Result: [primary, primary, primary, type1, type2]

Random Selection Algorithm

The endpoint (combat.mdx:422-425):

Checks if availableAttacks is empty and resets it if needed
Generates a random index: Math.floor(Math.random() * availableAttacks.length)
Selects the attack at that index
Removes the selected attack from availableAttacks using splice()
Adds the attack to attackList for tracking

Each call to this endpoint selects one attack. Call it multiple times to build a full attack sequence for the CPU.

Check Type Advantage

POST /mokepon/:playerId/check-advantage

Checks if a CPU player has an elemental type advantage over the opponent. If advantage exists, the CPU receives an extra attack of its primary type (one-time bonus per battle).

Path Parameters

playerId

string

required

The CPU player ID to check for advantage

Request Body

playerMokeponType

string

required

The opponent’s Mokepon type (💧, 🔥, or 🌱)

Response

success

boolean

required

Indicates if the check was successful

hasAdvantage

boolean

required

Whether the CPU has type advantage over the opponent

attacks

array

Updated master attack list (only present when hasAdvantage: true)

availableAttacks

array

Updated available attacks pool (only present when hasAdvantage: true)

Example

curl -X POST https://mokepon-ed1d40aff3a6.herokuapp.com/mokepon/cpu-0-1710086400123/check-advantage \
  -H "Content-Type: application/json" \
  -d '{
    "playerMokeponType": "🔥"
  }'

{
  "success": true,
  "hasAdvantage": true,
  "attacks": ["💧", "💧", "💧", "🔥", "🌱", "💧"],
  "availableAttacks": ["💧", "💧", "💧", "🔥", "🌱", "💧"]
}

Understanding Type Advantage Logic

Combat Rules

The type advantage system follows rock-paper-scissors mechanics (combat.mdx:531-535):

const combatRules = {
  '💧': '🔥', // Water beats Fire
  '🔥': '🌱', // Fire beats Plant
  '🌱': '💧'  // Plant beats Water
};

Advantage Check:

const hasAdvantage = combatRules[cpuType] === playerMokeponType;

Advantage Scenarios

CPU Type	Player Type	Has Advantage?
💧 Water	🔥 Fire	✅ Yes
💧 Water	🌱 Plant	❌ No
💧 Water	💧 Water	❌ No
🔥 Fire	🌱 Plant	✅ Yes
🔥 Fire	💧 Water	❌ No
🔥 Fire	🔥 Fire	❌ No
🌱 Plant	💧 Water	✅ Yes
🌱 Plant	🔥 Fire	❌ No
🌱 Plant	🌱 Plant	❌ No

Extra Attack Grant

When advantage is detected (combat.mdx:508-514):

Check if extra attack hasn’t been added yet (!cpuPlayer.extraAttackAdded)
Add one attack of the CPU’s primary type to attacks array
Add the same attack to availableAttacks pool
Set extraAttackAdded = true to prevent duplicate bonuses

The extra attack is granted only once per battle. The extraAttackAdded flag persists until the CPU is regenerated or the round is reset.

Strategic Implications

The advantage system creates:

Attack Count: 5 base attacks → 6 with advantage
Type Distribution: More attacks of the advantageous type
Winning Probability: Increased chance for the CPU to win the battle

Call this endpoint before the CPU starts selecting attacks for a battle to ensure the CPU receives its advantage bonus.

Reset CPU Attacks

POST /mokepon/:playerId/reset-attacks

Resets a CPU player’s available attacks to the full pool and clears the attack list. This should be called at the start of each new battle round to allow the CPU to use all attacks again.

Path Parameters

playerId

string

required

The CPU player ID whose attacks should be reset

Response

success

boolean

required

Indicates if the reset was successful

message

string

required

Description of the operation result

availableAttacks

array

required

The full attack pool after reset (includes any bonus attacks from advantage)

Example

curl -X POST https://mokepon-ed1d40aff3a6.herokuapp.com/mokepon/cpu-0-1710086400123/reset-attacks

{
  "success": true,
  "message": "CPU attacks reset successfully",
  "availableAttacks": ["🌱", "🌱", "🌱", "💧", "🔥"]
}

Understanding Attack Reset

What Gets Reset

The endpoint performs two operations (combat.mdx:456-463):

Restore Available Attacks: availableAttacks = [...attacks]
Clear Attack List: attackList = []

When to Reset

Call this endpoint:

Before each new battle round: So the CPU can select a fresh set of attacks
After a battle ends: To prepare for the next opponent
When restarting a battle: To give the CPU a clean slate

The reset includes any extra attacks granted by type advantage. If extraAttackAdded = true, the advantage attack remains in the pool.

Reset Behavior

// Before reset
cpuPlayer.availableAttacks = ['🌱', '💧'];  // Depleted
cpuPlayer.attackList = ['🌱', '🌱', '🔥'];  // Used attacks
cpuPlayer.attacks = ['🌱', '🌱', '🌱', '💧', '🔥'];  // Master list

// After reset
cpuPlayer.availableAttacks = ['🌱', '🌱', '🌱', '💧', '🔥'];  // Restored
cpuPlayer.attackList = [];  // Cleared
cpuPlayer.attacks = ['🌱', '🌱', '🌱', '💧', '🔥'];  // Unchanged

This endpoint does NOT reset the extraAttackAdded flag. If you want to remove the advantage bonus, you must regenerate the CPU player entirely.

Combat Flow Example

Here’s a complete battle flow using all combat endpoints:

// 1. Player finds a CPU opponent
const cpuId = 'cpu-0-1710086400123';
const playerType = '🔥';

// 2. Check if CPU has type advantage
const advantage = await fetch(`/mokepon/${cpuId}/check-advantage`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ playerMokeponType: playerType })
}).then(r => r.json());

if (advantage.hasAdvantage) {
  console.log('CPU got a bonus attack!');
}

// 3. Reset CPU attacks for a fresh battle
await fetch(`/mokepon/${cpuId}/reset-attacks`, {
  method: 'POST'
});

// 4. CPU selects 5 attacks
const cpuAttacks = [];
for (let i = 0; i < 5; i++) {
  const result = await fetch(`/mokepon/${cpuId}/cpu-attack`)
    .then(r => r.json());
  cpuAttacks.push(result.attack);
}

// 5. Player submits their attacks
await fetch(`/mokepon/${playerId}/attacks`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ attacks: playerAttacks })
});

// 6. Get CPU's final attack sequence
const cpuFinalAttacks = await fetch(`/mokepon/${cpuId}/attacks`)
  .then(r => r.json());

// 7. Execute battle logic on client side
// Compare playerAttacks vs cpuFinalAttacks.attacks

Overview

Endpoints

Submit Player Attacks

Path Parameters

Request Body

Response

Example

Get Opponent Attacks

Path Parameters

Response

Example

Get CPU Attack

Path Parameters

Response

Example

Understanding CPU Attack Selection

Attack Pool Management

Random Selection Algorithm

Check Type Advantage

Path Parameters

Request Body

Response

Example

Understanding Type Advantage Logic

Combat Rules

Advantage Scenarios

Extra Attack Grant

Strategic Implications

Reset CPU Attacks

Path Parameters

Response

Example

Understanding Attack Reset

What Gets Reset

When to Reset

Reset Behavior

Combat Flow Example

Build docs developers (and LLMs) love

Overview

Endpoints

​Submit Player Attacks

​Path Parameters

​Request Body

​Response

​Example

​Get Opponent Attacks

​Path Parameters

​Response

​Example

​Get CPU Attack

​Path Parameters

​Response

​Example

​Understanding CPU Attack Selection

​Attack Pool Management

​Random Selection Algorithm

​Check Type Advantage

​Path Parameters

​Request Body

​Response

​Example

​Understanding Type Advantage Logic

​Combat Rules

​Advantage Scenarios

​Extra Attack Grant

​Strategic Implications

​Reset CPU Attacks

​Path Parameters

​Response

​Example

​Understanding Attack Reset

​What Gets Reset

​When to Reset

​Reset Behavior

​Combat Flow Example

Build docs developers (and LLMs) love

Submit Player Attacks

Path Parameters

Request Body

Response

Example

Get Opponent Attacks

Path Parameters

Response

Example

Get CPU Attack

Path Parameters

Response

Example

Understanding CPU Attack Selection

Attack Pool Management

Random Selection Algorithm

Check Type Advantage

Path Parameters

Request Body

Response

Example

Understanding Type Advantage Logic

Combat Rules

Advantage Scenarios

Extra Attack Grant

Strategic Implications

Reset CPU Attacks

Path Parameters

Response

Example

Understanding Attack Reset

What Gets Reset

When to Reset

Reset Behavior

Combat Flow Example