National Park of Minnesota

    grapevinejs

    2.0.0 • Public • Published

    grapevine

    Integration for the Grapevine game protocol, a scrappy startup inter-MUD communication protocol.

    Installation

    npm install grapevinejs

    Debugging

    Run with DEBUG=grapevine to see debug messages:

    $ DEBUG=grapevine node example.js

    Example

    const grapevine = require('grapevinejs')
    
    run()
    
    async function run() {
      try {
        // initialize with a configuration object.  your client_id and
        // client_secret are the minimum required parameters.
        let emitter = grapevine.init({
          client_id: '12345678-1234-1234-1234-123456789abc',
          client_secret: '12345678-1234-1234-1234-123456789abc'
        })
    
        // catch asynchronous errors
        emitter.on('error', (err) => {
          console.log(err.stack)
        })
    
        // handle channel broadcasts
        emitter.on('channels/broadcast', (payload) => {
          console.log(payload)
        })
    
        // handle tells
        emitter.on('tells/receive', (payload) => {
          console.log(payload)
        })
    
        // connect to grapevine and retrieve current game status
        await grapevine.connect()
    
        // an array of other games connected to the grapevine network with their
        // currently authenticated players
        console.log(grapevine.games)  
    
        // notify grapevine of a new player authenticated into your game
        let result = await grapevine.addPlayer('SomePlayer')
    
        // subscribe your game to the 'secrets' channel
        result = await grapevine.send('channels/subscribe', {
          channel: 'secrets'
        })
    
        // send a message to the 'secrets' channel
        result = await grapevine.send('channels/send', {
          channel: 'secrets',
          name: 'SomePlayer',
          message: 'shhh'
        })
    
        // unsubscribe from the 'secrets' channel
        result = await grapevine.send('channels/unsubscribe', {
          channel: 'secrets'
        })
    
        // returns {name: 'SomeOtherPlayer', game: 'SomeGame'} if that remote
        // player identifier is currently signed in on the remote game
        result = grapevine.findPlayer('someotherplayer@somegame')
    
        // send a tell to a remote user
        result = await grapevine.send('tells/send', {
          from_name: 'SomePlayer',
          to_game: 'SomeGame',
          to_name: 'SomeOtherPlayer',
          sent_at: new Date(),
          message: 'test'
        })
    
        // true
        console.log('isAlive: ' + grapevine.isAlive())
    
        // notify grapevine of a new player logged out of your game
        result = await grapevine.removePlayer('SomePlayer')
    
        // forcibly close the connection
        grapevine.close()
    
        // false
        console.log('isAlive: ' + grapevine.isAlive())
    
      } catch (err) {
        console.log(err.stack)
      }
    }

    API

    grapevine.init(config)

    Initializes grapevine configuration. Returns an event emitter object that will report asynchronous errors. You should listen for the error event of this emitter object to catch asynchronous errors (ie. socket unexpectedly closed, reconnection failures).

    • config.client_id {string} Your game's grapevine client_id (required)
    • config.client_secret {string} Your game's grapevine client_secret (required)
    • config.statusWait {Number} How long to wait and collect status messages on connect before resolving (in ms), default: 100
    • config.url {string} grapevine websocket url, default: wss://grapevine.haus/socket
    • config.supports {Array.} Supported methods, default: ['channels', 'players', 'tells']
    • config.channels {Array.} Channels to subscribe to, default: ['testing', 'grapevine']
    • config.version {string} API version number to use, default not set
    • config.user_agent {string} Game user agent, default not set

    async grapevine.connect()

    Connects to grapevine, authenticates, and gets the status of current remotely connected games. Returns a promise that resolves after config.statusWait. The delay allows remote game status to accumulate and be available when the promise resolves.

    async grapevine.close()

    Closes the connection with grapevine. Sends sign-off messages for each locally connected player grapevine knows about. Connection can be re-established with grapevine.connect().

    async grapevine.send(event, payload, ref = true)

    Sends an event to grapevine. See the documentation for information on the messages that can be sent. Returns a promise that resolves with the acknowledgement packet.

    • event {string} The grapevine event name (required)
    • payload {Object} The grapevine event payload object (required)
    • ref {boolean} If a ref id should be generated with this request, default: true

    async grapevine.addPlayer(name)

    Adds a player to your local game and informs the grapevine network. This should be called when a user logs in to your game. You should use this method instead of calling send('players/sign-in') directly so that heartbeat responses have an up-to-date player list.

    • name {string} The player's name (required)

    async grapevine.removePlayer(name)

    Removes a player from your local game and informs the grapevine network. This should be called when a user logs out of your game. You should use this method instead of calling send('players/sign-out') directly so that heartbeat responses have an up-to-date player list.

    • name {string} The player's name (required)

    grapevine.findPlayer(rpi)

    Verifies that a remote player identifier (ie. someplayer@somegame) is logged in. Case-insensitive but returns the proper capitalization. Useful when targeting remote players (ie. a remote tell command). Returns an object of the form {name: 'SomePlayer', game: 'SomeGame'}.

    • rpi {string} The remote player identifier, ie. someplayer@somegame (required)

    grapevine.isAlive()

    Returns true if we are connected and authenticated to grapevine and ready to send messages.

    grapevine.games

    An array of remote game objects. This object will be initialized as part of the connect() method and will be kept in sync when remote players/sign-in and players/sign-out messages are received. The config.statusWait parameter controls how long to wait for this object to be populated.

    Install

    npm i grapevinejs

    DownloadsWeekly Downloads

    2

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    21.4 kB

    Total Files

    5

    Last publish

    Collaborators

    • dinchak