soundworks

Appearance

soundworks | plugin position ​

npm version

soundworks plugin for locating people in an area.

When registered the soundworks launcher will automatically provide an interface so that people can give give their approximate position on a map or area.

Table of Contents ​

Installation ​

sh
npm install @soundworks/plugin-position --save

Usage ​

Server ​

js
// index.js
import { Server } from '@soundworks/core/server.js';
import ServerPluginPosition from '@soundworks/plugin-position/server.js';

const server = new Server();
server.pluginManager.register('position', ServerPluginPosition, {
  // these values define the coordinates system of the area, they have
  // no special meaning and could be in any unit you find useful for
  // your application, defaults to [0, 1]
  xRange: [0, 2],
  yRange: [-1, 1],
  // define a background image that will be displayed by the launcher view
  backgroundImage: 'public/path/to/map.png'
}, []);

await server.start();

Client ​

js
// index.js
import { Client } from '@soundworks/core/client.js';
import ClientPluginPosition from '@soundworks/plugin-position/client.js';

const client = new Client();
client.pluginManager.register('position', ClientPluginPosition, {}, []);

await client.start();

const position = await client.pluginManager.get('position');
const clientPosition = position.getPosition();

API ​

Table of Contents ​

ClientPluginPosition ​

Extends ClientPlugin

Client-side representation of the position plugin.

The constructor should never be called manually. The plugin will be instantiated by soundworks when registered in the pluginManager

Available options:

  • randomize {Boolean} - Automatically give a random position to the client. Useful for testing

Examples ​

javascript
client.pluginManager.register('position', ClientPluginPosition, { randomize: true });

setPosition ​

Set the x and y position of the client in the given ranges units.

By default, this method is automatically called by the soundworks launcher, you should not have to call it manually in most cases.

Parameters ​

  • x Number x position in the given ranges units.
  • y Number y position in the given ranges units.

getPosition ​

Retrieve the given position in the given ranges units.

Returns Object x / y position of the client.

setNormalizedPosition ​

Set the x and y position of the client in normalized units.

By default, this method is automatically called by the soundworks launcher, you should not have to call it manually in most cases.

Parameters ​

  • normX
  • normY
  • x Number x position in normalized units.
  • y Number y position in normalized units.

getNormalizedPosition ​

Retrieve the given position in normalized units.

Returns Object normalized x / y position of the client.

ServerPluginPosition ​

Extends ServerPlugin

Server-side representation of the position plugin.

The constructor should never be called manually. The plugin will be instantiated by soundworks when registered in the pluginManager

Available options:

  • [xRange=[0, 1]] {Array} - Range of the area in the x axis.
  • [yRange=[0, 1]] {Array} - Range of the area in the y axis.
  • [backgroundImage=null] {String} - Path to a background image to be displayed by the launcher view.

Examples ​

javascript
server.pluginManager.register('position', ServerPluginPosition, {
  xRange: [0, 2],
  yRange: [-1, 1],
  backgroundImage: 'public/path/to/map.png',
});

Credits ​

https://soundworks.dev/credits.html

License ​

BSD-3-Clause