375 lines
8.0 KiB
Markdown
375 lines
8.0 KiB
Markdown
# 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:**
|
|
```json
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"pokemon": [...],
|
|
"pokemonAllForms": [...],
|
|
"moves": [...],
|
|
"raw": [...]
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"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`:
|
|
|
|
```javascript
|
|
import { GamemasterClient } from './gamemaster-client.js';
|
|
```
|
|
|
|
Or use the singleton instance:
|
|
|
|
```javascript
|
|
import { gamemasterClient } from './gamemaster-client.js';
|
|
```
|
|
|
|
### Usage Examples
|
|
|
|
#### Get filtered pokemon
|
|
```javascript
|
|
const gm = new GamemasterClient('/api/gamemaster');
|
|
const pokemon = await gm.getPokemon();
|
|
console.log(`Loaded ${pokemon.length} pokemon`);
|
|
```
|
|
|
|
#### Get all forms with caching
|
|
```javascript
|
|
// 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
|
|
```javascript
|
|
const moves = await gm.getMoves();
|
|
console.log(`Available moves: ${moves.length}`);
|
|
```
|
|
|
|
#### Get raw unmodified data
|
|
```javascript
|
|
const raw = await gm.getRaw();
|
|
```
|
|
|
|
#### Check server status
|
|
```javascript
|
|
const status = await gm.getStatus();
|
|
console.log(`Last update: ${status.lastUpdate}`);
|
|
console.log(`Files available: ${status.totalFiles}`);
|
|
```
|
|
|
|
#### Find specific pokemon
|
|
```javascript
|
|
const arcanine = await gm.getPokemonById('growlithe_alola');
|
|
if (arcanine) {
|
|
console.log(arcanine.data.pokemonSettings);
|
|
}
|
|
```
|
|
|
|
#### Find specific move
|
|
```javascript
|
|
const thunderbolt = await gm.getMoveById('thunderbolt');
|
|
if (thunderbolt) {
|
|
console.log(thunderbolt.data.moveSettings);
|
|
}
|
|
```
|
|
|
|
#### Download file
|
|
```javascript
|
|
// Download to user's downloads folder
|
|
await gm.downloadFile('pokemon.json');
|
|
```
|
|
|
|
#### Clear cache
|
|
```javascript
|
|
// 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:
|
|
|
|
```javascript
|
|
// In server/oauth-proxy.js
|
|
import gamemasterRouter from './gamemaster-api.js';
|
|
app.use('/api/gamemaster', gamemasterRouter);
|
|
```
|
|
|
|
Run the OAuth proxy server:
|
|
```bash
|
|
npm run oauth-proxy
|
|
```
|
|
|
|
Or run dev with both frontend and server:
|
|
```bash
|
|
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
|
|
```javascript
|
|
{
|
|
templateId: "V0001_POKEMON_BULBASAUR",
|
|
data: {
|
|
pokemonSettings: {
|
|
pokemonId: "bulbasaur",
|
|
form: "NORMAL",
|
|
// ... other pokemon data
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Move Item
|
|
```javascript
|
|
{
|
|
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
|
|
```json
|
|
{
|
|
"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
|