Neuro Game SDK for TypeScript and JavaScript

A TypeScript and JavaScript SDK for integrating games with Neuro-sama AI streamer, allowing developers to write games that Neuro-sama can interact.

This SDK is based on the original Neuro Game SDK and provides an implementation compatible with both Node.js and browser environments. It is designed to work seamlessly in both JavaScript and TypeScript projects.

Please note that this package is for integrating a game to Neuro. If you're making a server-side implementation of the Neuro API in JavaScript/TypeScript, there is another package called neuro-game-api to help.

Installation

# Install from npm (https://npmx.dev/package/neuro-game-sdk)
npm install neuro-game-sdk
yarn install neuro-game-sdk
pnpm install neuro-game-sdk
# etc...

# Install from JSR (https://jsr.io/@neurosama/game-sdk)
npx jsr add @neurosama/game-sdk
yarn install jsr:@neurosama/game-sdk
pnpm install jsr:@neurosama/game-sdk
# etc...

Usage

In Node.js

import { NeuroClient } from 'neuro-game-sdk'

const NEURO_SERVER_URL = 'ws://localhost:8000'
const GAME_NAME = 'Guess the Number'

const neuroClient = new NeuroClient(NEURO_SERVER_URL, GAME_NAME, () => {
  // Game initialization code. Check the example code
})

In the Browser

Using unpkg:

<script src="https://unpkg.com/neuro-game-sdk/dist/browser/neuro-game-sdk.min.js"></script>

Using jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/neuro-game-sdk/dist/browser/neuro-game-sdk.min.js"></script>

This will load the SDK into the global namespace as NeuroGameSdk. You can then use it in your scripts:

<script>
  const { NeuroClient } = NeuroGameSdk

  const NEURO_SERVER_URL = 'ws://localhost:8000'
  const GAME_NAME = 'Guess the Number'

  const neuroClient = new NeuroClient(NEURO_SERVER_URL, GAME_NAME, () => {
    // Game initialization code. Check the example code
  })
</script>

Quick Start Example

Here's an example of a simple game where Neuro-sama tries to guess a number between 1 and 10. When she guesses correctly, a new number is generated.

import { NeuroClient } from 'neuro-game-sdk'

const NEURO_SERVER_URL = 'ws://localhost:8000'
const GAME_NAME = 'Guess the Number'

const neuroClient = new NeuroClient(NEURO_SERVER_URL, GAME_NAME, () => {
  neuroClient.registerActions([
    {
      name: 'guess_number',
      description: 'Guess the number between 1 and 10.',
      schema: {
        type: 'object',
        properties: {
          number: { type: 'integer', minimum: 1, maximum: 10 },
        },
        required: ['number'],
      },
    },
  ])

  let targetNumber = Math.floor(Math.random() * 10) + 1

  neuroClient.onAction(actionData => {
    if (actionData.name === 'guess_number') {
      const guessedNumber = actionData.params.number
      if (
        typeof guessedNumber !== 'number' ||
        guessedNumber < 1 ||
        guessedNumber > 10
      ) {
        neuroClient.sendActionResult(
          actionData.id,
          false,
          'Invalid number. Please guess a number between 1 and 10.'
        )
        return
      }

      if (guessedNumber === targetNumber) {
        neuroClient.sendActionResult(
          actionData.id,
          true,
          `Correct! The number was ${targetNumber}. Generating a new number.`
        )
        targetNumber = Math.floor(Math.random() * 10) + 1
        promptNeuroAction()
      } else {
        neuroClient.sendActionResult(
          actionData.id,
          true,
          `Incorrect. The number is ${
            guessedNumber < targetNumber ? 'higher' : 'lower'
          }. Try again.`
        )
        promptNeuroAction()
      }
    } else {
      neuroClient.sendActionResult(actionData.id, false, 'Unknown action.')
    }
  })

  neuroClient.sendContext(
    'Game started. I have picked a number between 1 and 10.',
    false
  )

  function promptNeuroAction() {
    const availableActions = ['guess_number']
    const query = 'Please guess a number between 1 and 10.'
    const state = 'Waiting for your guess.'
    neuroClient.forceActions(query, availableActions, state)
  }

  promptNeuroAction()
})

Happy coding! <3 - ArieX

Known issues

"Updating to version 1.0.11+ and running/compiling throws an error about WebSocket not being defined."

This error is caused because your Node version is too old. As of Node 21, the WebSocket global is available behind a flag. From Node 22.4.0 onwards, this is available without requiring a flag to be passed. Node 20 is marked as EoL from 30/04/2026, and Node 21 has already been EoL as of the writing of this section.

If you're on Node 20 or earlier, you must use version 1.0.10 or earlier. If you're between Node 21 and Node 22.4.0 and you can't update for whatever reason, use the experimental flag for enabling the WebSocket global.

Projects using this SDK

The following integrations use this SDK:

• NeuroPilot by VSC-NeuroPilot (Pasu4, KTrain5369, Frogneko)