Reference
SDKs
Official typed clients for the ForjeGames API. Use them to embed ForjeGames in your own CLI tools, bots, or backend services.
Install
npm install @forjegames/sdkAuthentication
Both SDKs read FORJEGAMES_API_KEY from the environment by default. You can also pass the key explicitly to the constructor.
import { ForjeGames } from '@forjegames/sdk'
const fg = new ForjeGames() // reads FORJEGAMES_API_KEY
// or
const fg2 = new ForjeGames({ apiKey: 'fjg_live_...' })Quick start
Generate a game and print the summary:
import { ForjeGames } from '@forjegames/sdk'
const fg = new ForjeGames()
const result = await fg.generate({
mode: 'build',
prompt: 'A cosy log cabin in a snowy forest',
})
console.log(result.output.summary)
console.log(`Used ${result.credits_used} credits`)Streaming generations
Both SDKs expose a stream method that returns an async iterator over SSE events. Use it to show progress in long builds.
for await (const event of fg.generate.stream({
mode: 'build',
prompt: 'A top-down zombie arena',
})) {
switch (event.type) {
case 'thought':
process.stdout.write(event.delta)
break
case 'file':
console.log(`\nWrote ${event.path}`)
break
case 'done':
console.log('\nDone:', event.summary)
break
}
}Working with projects
To keep multiple generations attached to the same game, pass a project_id. Create one with projects.create():
const project = await fg.projects.create({ name: 'Snowy Cabin' })
await fg.generate({ project_id: project.id, mode: 'build', prompt: 'Initial map' })
await fg.generate({ project_id: project.id, mode: 'script', prompt: 'Add a fireplace particle effect' })
const updated = await fg.projects.get(project.id)
console.log(updated.chat_history.length, 'turns')Errors & retries
SDK errors are typed subclasses of ForjeGamesError so you can catch them specifically:
import {
InsufficientCreditsError,
RateLimitError,
} from '@forjegames/sdk'
try {
await fg.generate({ mode: 'build', prompt: 'castle' })
} catch (err) {
if (err instanceof InsufficientCreditsError) {
// top up and retry
} else if (err instanceof RateLimitError) {
await new Promise((r) => setTimeout(r, err.retryAfter * 1000))
} else {
throw err
}
}Both SDKs automatically retry 429 and transient 5xx errors with exponential backoff. You can disable this by passing maxRetries: 0 to the constructor.