SDK Reference

@gameplaygen/sdk — TypeScript SDK for GameplayGen economy engine & content generators.

bash

npm install @gameplaygen/sdk

GameplayGen

typescript

import { GameplayGen } from '@gameplaygen/sdk';

const gg = new GameplayGen({
  apiKey: 'gp_your_api_key',       // required
  baseUrl: 'https://gameplaygen.com', // required
});

Option	Type	Required	Description
`apiKey`	`string`	`Yes`	`API key (gp_*)`
`baseUrl`	`string`	`Yes`	`API base URL (e.g. https://gameplaygen.com)`

gg.economy.createGame()

Create a new game. Returns game info including an API key.

typescript

await gg.economy.createGame('my-game');

gg.economy.defineCurrency()

Define a currency for your game. Idempotent — safe to call on startup.

typescript

await gg.economy.defineCurrency('gold', 'Gold', '💰', 1000000);

Param	Type	Required	Description
`currencyId`	`string`	`Yes`	`Unique currency identifier`
`name`	`string`	`Yes`	`Display name`
`icon`	`string`	`Yes`	`Emoji or icon URL`
`maxBalance`	`number`	`No`	`Optional max balance cap`

gg.economy.defineItem()

Define a purchasable item. Idempotent.

typescript

await gg.economy.defineItem('iron-sword', 'Iron Sword', {
  rarity: 'common',
  prices: [{ currencyId: 'gold', amount: 50 }],
});

Param	Type	Required	Description
`itemId`	`string`	`Yes`	`Unique item identifier`
`name`	`string`	`Yes`	`Display name`
`options.rarity`	`string`	`No`	`Rarity tier (common, rare, epic, legendary)`
`options.prices`	`Price[]`	`Yes`	`Array of { currencyId, amount }`

gg.economy.createPlayer()

typescript

await gg.economy.createPlayer('user_123', 'Alice');

Param	Type	Required	Description
`externalId`	`string`	`Yes`	`Your user/player ID`
`displayName`	`string`	`No`	`Optional display name`

gg.economy.createPlayersBatch()

Create up to 100 players in a single call. Returns an array of { externalId, playerId }. Ideal for game setup, migrations, or batch onboarding.

typescript

const players = await gg.economy.createPlayersBatch([
  { externalId: 'user_1', displayName: 'Alice', wallets: [{ currencyId: 'gold', balance: 100 }] },
  { externalId: 'user_2', displayName: 'Bob', wallets: [{ currencyId: 'gold', balance: 50 }] },
]);
// players = [{ externalId: 'user_1', playerId: 'j97...' }, ...]

Param	Type	Required	Description
`players`	`array`	`Yes`	`Array of player objects (max 100)`
`players[].externalId`	`string`	`Yes`	`Your user/player ID`
`players[].displayName`	`string`	`No`	`Display name`
`players[].wallets`	`array`	`No`	`Initial balances: [{ currencyId, balance }]`

gg.economy.grant()

Add currency to a player's wallet. The player is auto-created if needed.

typescript

await gg.economy.grant('user_123', 'gold', 100, 'quest_complete');

Param	Type	Required	Description
`externalId`	`string`	`Yes`	`Player ID`
`currencyId`	`string`	`Yes`	`Currency to grant`
`amount`	`number`	`Yes`	`Amount to grant`
`reason`	`string`	`Yes`	`Reason for the grant (e.g. quest_complete)`

gg.economy.spend()

Deduct currency. Throws GameplayGenError if insufficient balance.

typescript

await gg.economy.spend('user_123', 'gold', 30, 'shop_purchase');

Param	Type	Required	Description
`externalId`	`string`	`Yes`	`Player ID`
`currencyId`	`string`	`Yes`	`Currency to deduct`
`amount`	`number`	`Yes`	`Amount to deduct`
`reason`	`string`	`Yes`	`Reason for the spend`

gg.economy.purchase()

Atomic purchase — deducts the item's price and adds it to inventory. Rolls back on failure.

typescript

await gg.economy.purchase('user_123', 'iron-sword');

gg.economy.transfer()

Transfer currency to another player. Subject to anti-cheat laundering detection.

typescript

await gg.economy.transfer('user_123', 'player_99', 'gold', 50, 'trade');

Param	Type	Required	Description
`fromId`	`string`	`Yes`	`Sender player ID`
`toId`	`string`	`Yes`	`Recipient player ID`
`currencyId`	`string`	`Yes`	`Currency to transfer`
`amount`	`number`	`Yes`	`Amount to transfer`
`reason`	`string`	`Yes`	`Reason for the transfer`

gg.economy.getBalance()

Returns all currency balances for a player.

typescript

const bal = await gg.economy.getBalance('user_123');
// → [{ currencyId: 'gold', balance: 50 }, { currencyId: 'gems', balance: 10 }]

gg.economy.getInventory()

Returns all owned items with quantities.

typescript

const inv = await gg.economy.getInventory('user_123');
// → [{ itemId: 'iron-sword', quantity: 1 }, { itemId: 'health-potion', quantity: 3 }]

gg.economy.craft()

Execute a crafting recipe — consumes ingredients and grants outputs.

typescript

await gg.economy.craft('user_123', 'iron_sword_recipe');

gg.economy.rollLoot()

Roll a loot table and grant the results to a player.

typescript

const loot = await gg.economy.rollLoot('user_123', 'boss_dragon_table');

gg.economy.marketplaceList()

List an item for sale on the player marketplace.

typescript

await gg.economy.marketplaceList('user_123', 'iron-sword', {
  currencyId: 'gold', amount: 500,
});

gg.economy.marketplaceBuy()

Purchase a listing from the marketplace.

typescript

await gg.economy.marketplaceBuy('player_99', 'listing-123');

gg.economy.getAuditFlags()

Retrieve anti-cheat audit flags for review.

typescript

const flags = await gg.economy.getAuditFlags();

gg.economy.getStats()

Economy-wide statistics.

typescript

const stats = await gg.economy.getStats();
// → {
//   totalPlayers: 1247,
//   totalTransactions: 89432,
//   currencyStats: [{
//     currencyId: 'gold',
//     totalInCirculation: 5430000,
//     totalGranted: 8200000,
//     totalSpent: 2770000,
//   }]
// }

gg.economy.getConfig()

Get the game's economy configuration (currencies and items).

typescript

const config = await gg.economy.getConfig();
// → { currencies: [...], items: [...] }

gg.economy.getTransactions()

Paginated transaction history.

typescript

const txns = await gg.economy.getTransactions({ limit: 50 });

gg.generate()

Generate content using a GameplayGen generator.

typescript

const dungeon = await gg.generate('dungeon-layout', { width: 50, height: 50 });
const puzzle = await gg.generate('sokoban', { width: 8, height: 8 }, { difficulty: 0.5 });

Param	Type	Required	Description
`generatorId`	`string`	`Yes`	`Generator type (e.g. dungeon-layout, sokoban)`
`params`	`object`	`Yes`	`Generator-specific parameters`
`options`	`object`	`No`	`Additional options (e.g. difficulty)`

Error Handling

All errors throw GameplayGenError with a status code and message.

typescript

import { GameplayGen, GameplayGenError } from '@gameplaygen/sdk';

try {
  await gg.economy.spend('user_123', 'gold', 99999, 'shop_purchase');
} catch (err) {
  if (err instanceof GameplayGenError) {
    console.log(err.message);  // "Insufficient balance"
    console.log(err.status);   // 422
  }
}

Status	Suggestion
`401`	`Check your API key. It should start with gp_.`
`404`	`Resource not found. Make sure the player/currency/item exists.`
`422`	`Validation error. Check the request body.`
`429`	`Rate limited. Wait a moment and retry.`