@gamedevagents/sdk-web

Part of GameDevAgents, AI-agent + human-curated game QA. · Platform · Docs · Other engines (Godot, Unity, Unreal)

The browser/web integration for GameDevAgents automated + human-assisted game QA. It's a small, dependency-free bridge you drop into your web game so the QA platform can both observe it (version, errors, crashes, custom events) and drive it (synthetic keyboard / mouse / gamepad / touch input). QA-relevant signals you route through the SDK are judged from your game's own truth instead of inferred from the outside.

Install

npm install @gamedevagents/sdk-web

Use

import { GDA } from '@gamedevagents/sdk-web'

// Once, at boot. Registers global error/crash hooks and connects the input bridge.
await GDA.init({
  version: '1.4.2',          // the exact build under test (regression tracking keys on this)
  titleId: 'my-game',
  // workerEndpoint?: 'http://localhost:8787'  // defaults to the local worker bridge
})

// Emit notable game state as it happens, so QA judges from your truth:
await GDA.emit('spin', { bet: 5, result: 'win', payout: 20 })
await GDA.emit('scene_change', { to: 'shop' })

// Errors/unhandled rejections are captured automatically once init() runs.
// For SDK validation you can force a crash event:
await GDA.triggerTestCrash()

The semantic decision loop is the recommended integration (reliable, no vision guessing):

// At every point a player would act:
const choice = await GDA.turn('main menu', [
  'PLAY',
  { name: 'OPTIONS', label: 'Options', tags: ['passive'] },
])
executeAction(choice.name, choice.data)

// At every terminal state (round/level/game over, win or loss):
await GDA.over('win', { score: 9000 })

turn(state, actions) advertises the game's REAL choices and resolves with the platform's pick (the promise never resolves without a worker attached, gate on your QA-mode flag). actions entries are strings or { name, label?, group?, data?, tags? }; tags use the personality vocabulary (reckless | aggressive | tactical | passive | exploitative) so player personalities bias selection without the platform interpreting game meaning. over(outcome) is the SDK-authoritative end-of-run signal; always pair the last turn with an over.

Full runtime surface: init, turn, over, emit (custom events), sendEvent (low-level), and triggerTestCrash. Global error/unhandledrejection and a session_start announcement are wired by init. The platform can also drive raw input (commands become real DOM/gamepad events) and request viewport screenshots (<canvas> to PNG); your game needs no input-side code for either.

Strip from shipping builds

All SDK calls should be excluded from production/release bundles (dead-code-eliminated behind a flag). See SPEC.md → Build config.

Docs

• SPEC.md, the full SDK contract (all engines, the target API).
• ONBOARDING-KIT.md, the one-shot prompt to wire the SDK + emit your game profile, run from inside your game's repo.
• Platform docs & dashboard: gamedevagents.com.

License

MIT, see LICENSE.