memory-infrastructure-palace/docs/projects/Pokedex.Online/api-reference/gamemaster-api.md

Gamemaster API Documentation

Overview

The Gamemaster API provides access to processed Pokemon GO gamemaster data. Once gamemaster data is generated and saved via the GamemasterManager UI, it becomes available to all apps on the site.

Data Types:

• Pokemon (Filtered) - Base forms + regional variants (Alola, Galarian, Hisuian, Paldea)
• All Forms & Costumes - Complete dataset with all variants, costumes, events, shadows
• Moves - All quick and charged moves available in Pokemon GO
• Raw - Unmodified gamemaster data from PokeMiners

API Endpoints

Base URL

/api/gamemaster

GET /api/gamemaster/status

Get information about available files and their storage status.

Response:

{
  "available": [
    {
      "filename": "pokemon.json",
      "size": 1234567,
      "sizeKb": "1234.57",
      "modified": "2026-01-28T12:34:56.000Z"
    }
  ],
  "lastUpdate": "2026-01-28T12:34:56.000Z",
  "totalFiles": 4
}

GET /api/gamemaster/pokemon

Get filtered pokemon data (base forms + regional variants).

Response: Array of gamemaster items with pokemon settings.

GET /api/gamemaster/pokemon/allForms

Get all pokemon forms including costumes, event forms, shadows, etc.

Response: Array of all gamemaster pokemon items.

GET /api/gamemaster/moves

Get all pokemon moves (quick and charged).

Response: Array of gamemaster move items.

GET /api/gamemaster/raw

Get raw unmodified gamemaster data from PokeMiners.

Response: Complete raw gamemaster array.

POST /api/gamemaster/save

Save processed gamemaster data to server storage.

Headers:

Content-Type: application/json

Body:

{
  "pokemon": [...],
  "pokemonAllForms": [...],
  "moves": [...],
  "raw": [...]
}

Response:

{
  "message": "Files saved successfully",
  "files": {
    "pokemon": { "filename": "...", "size": ... },
    "pokemonAllForms": { ... },
    "moves": { ... },
    "raw": { ... }
  },
  "timestamp": "2026-01-28T12:34:56.000Z"
}

GET /api/gamemaster/download/:filename

Download a specific file directly.

Parameters:

• filename - One of: pokemon.json, pokemon-allFormsCostumes.json, pokemon-moves.json, latest-raw.json

Response: Binary JSON file with appropriate headers for download.

Client Library

Installation

Use the GamemasterClient class from src/utilities/gamemaster-client.js:

import { GamemasterClient } from './gamemaster-client.js';

Or use the singleton instance:

import { gamemasterClient } from './gamemaster-client.js';

Usage Examples

Get filtered pokemon

const gm = new GamemasterClient('/api/gamemaster');
const pokemon = await gm.getPokemon();
console.log(`Loaded ${pokemon.length} pokemon`);

Get all forms with caching

// First call fetches from server
const allForms = await gm.getAllForms({ useCache: true });

// Subsequent calls use cache
const cachedForms = await gm.getAllForms({ useCache: true });

Get moves

const moves = await gm.getMoves();
console.log(`Available moves: ${moves.length}`);

Get raw unmodified data

const raw = await gm.getRaw();

Check server status

const status = await gm.getStatus();
console.log(`Last update: ${status.lastUpdate}`);
console.log(`Files available: ${status.totalFiles}`);

Find specific pokemon

const arcanine = await gm.getPokemonById('growlithe_alola');
if (arcanine) {
  console.log(arcanine.data.pokemonSettings);
}

Find specific move

const thunderbolt = await gm.getMoveById('thunderbolt');
if (thunderbolt) {
  console.log(thunderbolt.data.moveSettings);
}

Download file

// Download to user's downloads folder
await gm.downloadFile('pokemon.json');

Clear cache

// Clear specific data
gm.clearCache('pokemon');

// Clear all cached data
gm.clearCache();

API Reference

new GamemasterClient(baseUrl = '/api/gamemaster')

Create a new client instance.

Parameters:

• baseUrl - Base URL for the API (defaults to /api/gamemaster)

getPokemon(options = {})

Get filtered pokemon data.

Options:

• useCache - (boolean) Use cached data if available

Returns: Promise<Array>

getAllForms(options = {})

Get all pokemon forms including costumes.

Returns: Promise<Array>

getMoves(options = {})

Get all pokemon moves.

Returns: Promise<Array>

getRaw(options = {})

Get raw unmodified gamemaster data.

Returns: Promise<Array>

getStatus()

Get server storage status and available files.

Returns: Promise<Object>

getPokemonById(pokemonId)

Find a specific pokemon in the filtered dataset.

Parameters:

• pokemonId - Pokemon ID string (e.g., "growlithe", "growlithe_alola")

Returns: Promise<Object|null>

getMoveById(moveId)

Find a specific move.

Parameters:

• moveId - Move ID string (e.g., "thunderbolt")

Returns: Promise<Object|null>

downloadFile(filename)

Download a file directly to the browser.

Parameters:

• filename - File to download (see POST /api/gamemaster/save)

Returns: Promise<void>

clearCache(key = null)

Clear cached data.

Parameters:

• key - (optional) Specific cache key to clear, or clears all if not provided

Server Setup

Required Environment Variables

None - the API runs with defaults.

File Storage

Processed gamemaster files are stored in:

server/data/gamemaster/

Directory is created automatically on first save.

Initialization

The gamemaster API is automatically integrated into the main server:

// In server/oauth-proxy.js
import gamemasterRouter from './gamemaster-api.js';
app.use('/api/gamemaster', gamemasterRouter);

Run the OAuth proxy server:

npm run oauth-proxy

Or run dev with both frontend and server:

npm run dev:full

Workflow

1. Generate Data

   • Open GamemasterManager at /gamemaster
   • Click "Fetch from PokeMiners"
   • Click "Process & Break Up Data"
   • Click "Save All Files to Server"

2. Access from Other Apps

   • Import GamemasterClient in any app
   • Call getPokemon(), getAllForms(), getMoves(), etc.
   • Data is available immediately

3. Refresh Data

   • Repeat generation process when PokeMiners releases updates
   • Files are overwritten, maintaining consistency across apps

Data Structure

Pokemon Item

{
  templateId: "V0001_POKEMON_BULBASAUR",
  data: {
    pokemonSettings: {
      pokemonId: "bulbasaur",
      form: "NORMAL",
      // ... other pokemon data
    }
  }
}

Move Item

{
  templateId: "V0002_MOVE_POUND",
  data: {
    moveSettings: {
      movementId: "pound",
      // ... other move data
    }
  }
}

Error Handling

All endpoints return appropriate HTTP status codes:

• 200 OK - Success
• 400 Bad Request - Invalid parameters
• 404 Not Found - Data not available (hasn't been generated yet)
• 500 Server Error - Server error

Example Error Response

{
  "error": "Pokemon data not available. Generate from GamemasterManager."
}

Performance Considerations

• All data is cached in memory after first request
• Files are stored as plain JSON for quick access
• Use useCache: true option in client to avoid repeated fetches
• Clear cache when refreshing data: gm.clearCache()

Security

• No authentication required (adjust if deploying publicly)
• Filename validation prevents path traversal attacks
• Large payloads supported (50MB limit)
• CORS configured for local development

Troubleshooting

"Data not available" error

• Run GamemasterManager to generate and save data first
• Check that /server/data/gamemaster/ directory exists

Files not persisting

• Ensure server has write permissions to /server/data/gamemaster/
• Restart server after manual directory creation

Large file downloads timing out

• Check network connection
• Try downloading individual files instead of all at once