node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

trail-client-sdk

Trail Client SDK

This is the SDK which lives together with the game client and acts as a bridge between the game and the Trail Platform.

Assumptions

  • The SDK lives inside an iframe next to the game-client on the Trail Platform.
  • The SDK is included in the source document through either a <script> tag or is bundled directly with the source files, likely installed through the means of npm or bower.
  • Initialisation of the SDK is on an opt-in base by the developer. Merely including the SDK should never result in initialisation.

Usage

Installation

Install the SDK in your project:

npm install trail-client-sdk --save

Including the script

// ES6 import syntax 
import TrailSDK from 'trail-client-sdk';
 
// ES5 module/require syntax 
const TrailSDK = require('trail-client-sdk');

Initialising the SDK

Before you can start using the SDK you must call the init() method:

// Initialise the SDK, allowing it to get set-up with the Trail Platform 
TrailSDK.init().then((trail) => {
  // Print logged in user's username 
  console.log('Hello there, %s!', trail.user.username);
 
  // Connect to a Pigeoneer-enabled gameserver 
  const connection = trail.net.connectTo({ host: 'localhost', port: 9500 });
 
  connection.onOpen = () => {
    console.info('The connection has been established.');
  };
 
  connection.onStreamMessage = (message) => {
    // pass incoming message to your game 
  };
 
  // Update game downloading progress to 40% 
  trail.game.setLoadingProgress(0.4);
 
  // Listen for changes to the user 
  trail.on('user_updated', () => {
    console.log('Got yourself an update, %s?', trail.user.username);
  });
});

Alternatively, you can install the latest version through the unpkg CDN:

<script async src="https://unpkg.com/trail-client-sdk/dist/trail.web.js"></script>
<script>
  // Synchronously loaded 
  TrailSDK.init().then(function(trail) {
    // ... 
  });
 
  // Asynchronously loaded   
  window.trailAsyncInit = function(TrailSDK) {
    TrailSDK.init().then(function(trail) {
      // ... 
    });
  };
</script> 

Configuration

TrailSDK.init() takes the following parameters:

debug (bool)

Whether to print extended debug logs. (default: false)

skipPointerLock (bool)

Whether to invoke Pointer Lock when the "Play" button is pressed. (default: false)

supportQualityDecrease (bool)

Whether the game supports decreasing the graphics quality when the FPS falls below a threshold. (default: false)

forceWebSocket (bool)

Whether to force the use of WebSockets, regardless of whether the browser supports Pigeoneer. (default: false)

gameVersion (string)

The game's current version. (default: null)

API

The following methods are available, assuming the instance returned from TrailSDK.init() is named trail.

trail.net.connectTo(options = {}) (Promise)

options takes the following parameters:

  • host the hostname or IP to connect to.
  • port the target port.

It returns a Promise which resolves with a Connection.

trail.game.version (string)

The game's version.

trail.game.fps (int)

Average FPS.

trail.game.setDownloaded() (void)

Indicate the game has finished downloading all assets and started to load.

trail.game.setLoaded() (void)

Indicate the game has finished loading and is ready for play.

trail.user.uuid (string)

The current logged in user's unique ID.

trail.user.username (string)

The current logged in user's username.

Contributing

Prerequisites

You will need the following things properly installed on your computer.

Installation / Development

  • git clone git@github.com:trailgames/trail-client-sdk.git this repository
  • cd trail-client-sdk
  • npm install

Running

  • Run webpack-dev-server inside the main directory

Linking the NPM package

  • Run npm link inside the main directory
  • Run npm link trail-client-sdk inside the project including the SDK

Deployment

  • npm version <major|minor|patch>
  • npm publish
  • git push --tags