exports

exports

Base class to extend in order to create the client-side counterpart of a soundworks plugin.

In the soundworks paradigm, a plugin is a component that allows to extend the framework capabilities by encapsulating common and reusable logic in an application wise perspective. For example, plugins are available to handle clock synchronization, to deal with the file system, etc. Plugin should always have both a client-side and a server-side part.

See https://soundworks.dev/guide/ecosystem for more information on the available plugins.

Creating new plugins should be considered an advanced usage.

Constructor

new exports(client, id)

Source:
Parameters:
Name Type Description
client Client

A soundworks client instance.
id string

User defined id of the plugin as defined in ClientPluginManager#register.

Extends

Members

(readonly) id :string

Description:

  • User defined ID of the plugin.

Source:
Overrides:
See:

User defined ID of the plugin.

Type:
  • string

(protected) state :object

Description:

  • Placeholder that stores internal (local) state of the plugin. The state should be modified through the propagateStateChange method to ensure the change to be properly propagated to manager onStateChange callbacks.

Source:
Overrides:
See:
  • ClientPlugin#onStateChange
  • ServerPlugin#onStateChange
  • ClientPlugin#propagateStateChange
  • ServerPlugin#propagateStateChange

Placeholder that stores internal (local) state of the plugin. The state should be modified through the propagateStateChange method to ensure the change to be properly propagated to manager onStateChange callbacks.

Type:
  • object

status :'idle'|'inited'|'started'|'errored'

Description:

  • Current status of the plugin.

Source:
Overrides:

Current status of the plugin.

Type:
  • 'idle' | 'inited' | 'started' | 'errored'

(readonly) type :string

Description:

  • Type of the plugin, i.e. the ClassName.

    Useful to do perform some logic based on certain types of plugins without knowing under which id they have been registered. (e.g. creating some generic views, etc.)

Source:
Overrides:

Type of the plugin, i.e. the ClassName.

Useful to do perform some logic based on certain types of plugins without knowing under which id they have been registered. (e.g. creating some generic views, etc.)

Type:
  • string

(static) averageNetworkLatency

Description:

  • Average latency in seconds computed from ping/pong information.

Source:

Average latency in seconds computed from ping/pong information.

(static) averageNetworkLatencyPeriod

Description:

  • Period in second at which the average latency is computed. Defaults to 2

Source:

Period in second at which the average latency is computed. Defaults to 2

(static) averageNetworkLatencyWindow

Description:

  • Time window in second used to compute the average latency. Defaults to 5

Source:

Time window in second used to compute the average latency. Defaults to 5

(static) numClients

Description:

  • Number of connected clients by role.

Source:

Number of connected clients by role.

Example
{
  player: 12,
  controller: 1,
}

Methods

onStateChange(callback) → {pluginDeleteOnStateChangeCallback}

Description:

  • Listen to the state changes propagated by BasePlugin.propagateStateChange

Source:
Overrides:
Example
const unsubscribe = plugin.onStateChange(pluginState => console.log(pluginState));
// stop listening state changes
unsubscribe();
Parameters:
Name Type Description
callback pluginOnStateChangeCallback

Callback to execute when a state change is propagated.
Returns:
Type
pluginDeleteOnStateChangeCallback

propagateStateChange(updates)

Description:

  • Apply updates to the plugin state and propagate the updated state to the onStateChange listeners. The state changes will also be propagated through the PluginManager#onStateChange listeners.

Source:
Overrides:
See:
Parameters:
Name Type Description
updates object

Updates to be merged in the plugin state.

(async) start()

Description:

  • Start the plugin.

    This method is automatically called during the client or server init() lifecycle step. After start() is fulfilled the plugin should be ready to use.

Source:
Overrides:
Example
// server-side counterpart of a plugin that creates a dedicated global shared
// state on which the server-side part can attach.
class MyPlugin extends ServerPlugin {
  constructor(server, id) {
    super(server, id);

    this.server.stateManager.defineClass(`my-plugin:${this.id}`, {
      someParam: {
        type: 'boolean',
        default: false,
      },
      // ...
    });
  }

  async start() {
    await super.start()
    this.sharedState = await this.server.stateManager.create(`my-plugin:${this.id}`);
  }

  async stop() {
    await this.sharedState.delete();
  }
}

(async) stop()

Description:

  • Stop the plugin.

    This method is automatically called during the client or server stop() lifecycle step.

Source:
Overrides:
Example
// server-side counterpart of a plugin that creates a dedicated global shared
// state on which the client-side part can attach.
class MyPlugin extends ServerPlugin {
  constructor(server, id) {
    super(server, id);

    this.server.stateManager.defineClass(`my-plugin:${this.id}`, {
      someParam: {
        type: 'boolean',
        default: false,
      },
      // ...
    });
  }

  async start() {
    await super.start()
    this.sharedState = await this.server.stateManager.create(`my-plugin:${this.id}`);
    this.sharedState.onUpdate(updates => this.doSomething(updates));
  }

  async stop() {
    await this.sharedState.delete();
  }
}

exports

Base class to extend in order to create the server-side counterpart of a soundworks plugin.

In the soundworks paradigm, a plugin is a component that allows to extend the framework capabilities by encapsulating common and reusable logic in an application wise perspective. For example, plugins are available to handle clock synchronization, to deal with the file system, etc. Plugin should always have both a client-side and a server-side part.

See https://soundworks.dev/guide/ecosystem for more information on the available plugins.

Creating new plugins should be considered an advanced usage.

Constructor

new exports(server, id)

Source:
Parameters:
Name Type Description
server Server

The soundworks server instance.
id string

User defined id of the plugin as defined in ServerPluginManager#register.

Extends

Members

(readonly) id :string

Description:

  • User defined ID of the plugin.

Source:
Overrides:
See:

User defined ID of the plugin.

Type:
  • string

(protected) state :object

Description:

  • Placeholder that stores internal (local) state of the plugin. The state should be modified through the propagateStateChange method to ensure the change to be properly propagated to manager onStateChange callbacks.

Source:
Overrides:
See:
  • ClientPlugin#onStateChange
  • ServerPlugin#onStateChange
  • ClientPlugin#propagateStateChange
  • ServerPlugin#propagateStateChange

Placeholder that stores internal (local) state of the plugin. The state should be modified through the propagateStateChange method to ensure the change to be properly propagated to manager onStateChange callbacks.

Type:
  • object

status :'idle'|'inited'|'started'|'errored'

Description:

  • Current status of the plugin.

Source:
Overrides:

Current status of the plugin.

Type:
  • 'idle' | 'inited' | 'started' | 'errored'

(readonly) type :string

Description:

  • Type of the plugin, i.e. the ClassName.

    Useful to do perform some logic based on certain types of plugins without knowing under which id they have been registered. (e.g. creating some generic views, etc.)

Source:
Overrides:

Type of the plugin, i.e. the ClassName.

Useful to do perform some logic based on certain types of plugins without knowing under which id they have been registered. (e.g. creating some generic views, etc.)

Type:
  • string

(static) averageNetworkLatency

Description:

  • Average latency in seconds computed from ping/pong information.

Source:

Average latency in seconds computed from ping/pong information.

(static) averageNetworkLatencyPeriod

Description:

  • Period in second at which the average latency is computed. Defaults to 2

Source:

Period in second at which the average latency is computed. Defaults to 2

(static) averageNetworkLatencyWindow

Description:

  • Time window in second used to compute the average latency. Defaults to 5

Source:

Time window in second used to compute the average latency. Defaults to 5

(static) numClients

Description:

  • Number of connected clients by role.

Source:

Number of connected clients by role.

Example
{
  player: 12,
  controller: 1,
}

Methods

onStateChange(callback) → {pluginDeleteOnStateChangeCallback}

Description:

  • Listen to the state changes propagated by BasePlugin.propagateStateChange

Source:
Overrides:
Example
const unsubscribe = plugin.onStateChange(pluginState => console.log(pluginState));
// stop listening state changes
unsubscribe();
Parameters:
Name Type Description
callback pluginOnStateChangeCallback

Callback to execute when a state change is propagated.
Returns:
Type
pluginDeleteOnStateChangeCallback

propagateStateChange(updates)

Description:

  • Apply updates to the plugin state and propagate the updated state to the onStateChange listeners. The state changes will also be propagated through the PluginManager#onStateChange listeners.

Source:
Overrides:
See:
Parameters:
Name Type Description
updates object

Updates to be merged in the plugin state.

(async) start()

Description:

  • Start the plugin.

    This method is automatically called during the client or server init() lifecycle step. After start() is fulfilled the plugin should be ready to use.

Source:
Overrides:
Example
// server-side counterpart of a plugin that creates a dedicated global shared
// state on which the server-side part can attach.
class MyPlugin extends ServerPlugin {
  constructor(server, id) {
    super(server, id);

    this.server.stateManager.defineClass(`my-plugin:${this.id}`, {
      someParam: {
        type: 'boolean',
        default: false,
      },
      // ...
    });
  }

  async start() {
    await super.start()
    this.sharedState = await this.server.stateManager.create(`my-plugin:${this.id}`);
  }

  async stop() {
    await this.sharedState.delete();
  }
}

(async) stop()

Description:

  • Stop the plugin.

    This method is automatically called during the client or server stop() lifecycle step.

Source:
Overrides:
Example
// server-side counterpart of a plugin that creates a dedicated global shared
// state on which the client-side part can attach.
class MyPlugin extends ServerPlugin {
  constructor(server, id) {
    super(server, id);

    this.server.stateManager.defineClass(`my-plugin:${this.id}`, {
      someParam: {
        type: 'boolean',
        default: false,
      },
      // ...
    });
  }

  async start() {
    await super.start()
    this.sharedState = await this.server.stateManager.create(`my-plugin:${this.id}`);
    this.sharedState.onUpdate(updates => this.doSomething(updates));
  }

  async stop() {
    await this.sharedState.delete();
  }
}