npm package: @soundworks/plugin-position
Description: soundworks plugin for locating people in an area
Latest version: 5.0.1

# soundworks | plugin position

[![npm version](https://badge.fury.io/js/@soundworks%2Fplugin-position.svg)](https://badge.fury.io/js/@soundworks%2Fplugin-position)

[`soundworks`](https://soundworks.dev) 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

<!-- toc -->

- [Installation](#installation)
- [Usage](#usage)
- [API](#api)
- [ClientPluginPosition](#clientpluginposition)
- [ServerPluginPosition](#serverpluginposition)
- [Credits](#credits)
- [License](#license)

<!-- tocstop -->

## 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

<!-- api -->
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

### Table of Contents

*   [ClientPluginPosition][1]
    *   [Examples][2]
    *   [setPosition][3]
    *   [getPosition][4]
    *   [setNormalizedPosition][5]
    *   [getNormalizedPosition][6]
*   [ServerPluginPosition][7]
    *   [Examples][8]

## 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][9]** x position in the given ranges units.
*   `y` **[Number][9]** y position in the given ranges units.

### getPosition

Retrieve the given position in the given ranges units.

Returns **[Object][10]** 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` &#x20;
*   `normY` &#x20;
*   `x` **[Number][9]** x position in normalized units.
*   `y` **[Number][9]** y position in normalized units.

### getNormalizedPosition

Retrieve the given position in normalized units.

Returns **[Object][10]** 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',
});
```

[1]: #clientpluginposition

[2]: #examples

[3]: #setposition

[4]: #getposition

[5]: #setnormalizedposition

[6]: #getnormalizedposition

[7]: #serverpluginposition

[8]: #examples-1

[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number

[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object

<!-- apistop -->

## Credits

[https://soundworks.dev/credits.html](https://soundworks.dev/credits.html)

## License

[BSD-3-Clause](./LICENSE)