soundworks | plugin sketch manager

soundworks plugin for managing multi-sketch experiences.

Table of Contents

• Installation
• Usage
• Credits
• License

Installation

npm install @mobilizing/soundworks-plugin-sketch-manager --save

Usage

Creating a sketch

A sketch's structure follows the general soundworks project structure with clients and server scripts, but each client must extend the plugin's ClientSketch class, and each server must extend the plugin's ServerSketch class.

By default, all schemas in a sketche's server/schemas directory are automatically registered on sketch activation and deleted on sketch deactivation. This can be changed via the plugins's 'autoRegisterSchemas' option on the server side.

To prevent schema name conflicts, when auto-registering a sketch's schemas, the name is prefixed with the sketche's name. The helper function 'getLocalSchemaName' can be used to get the generated name.

// sketches/a-sketch/server/schemas/mobile.js
export default {
  id: {
    type: "integer",
    default: null,
    nullable: true,
  },
  color: {
    type: "string",
    default: "#00ff00",
  },
};

// sketches/a-sketch/server/index.js
import ServerSketch from "@mobilizing/soundworks-plugin-sketch-manager/ServerSketch.js";

export default class extends ServerSketch {
  #mobileStates;

  async start() {
    await super.start();

    const mobileSchemaName = this.getLocalSchemaName("mobile");
    this.#mobileStates = await this.server.stateManager.getCollection(
      mobileSchemaName
    );
    this.#mobileStates.onAttach((state) => {
      // ...
    });
    this.#mobileStates.onUpdate((state, newValues, oldValues) => {
      // ...
    });
    this.#mobileStates.onDetach((state) => {
      // ...
    });

    // ...
  }

  async stop() {
    await super.stop();

    // ...
  }
}

// sketches/a-sketch/clients/mobile/index.js
import ClientSketch from "@mobilizing/soundworks-plugin-sketch-manager/ClientSketch.js";

export default class extends ClientSketch {
  async start() {
    await super.start();

    // Create a schema instance.
    const mobileSchemaName = this.getLocalSchemaName("mobile");
    const mobileState = await this.client.stateManager.create(
      mobileSchemaName,
      { id: this.client.id }
    );

    mobileState.onUpdate((newValue, oldValues) => {
      // ...
    });

    // ...
  }

  async stop() {
    await super.stop();

    // ...
  }
}

Server installation

Registering the plugin

// server/index.js
import { Server } from "@soundworks/core/server.js";
import pluginSketchManager from "@mobilizing/soundworks-plugin-sketch-manager/server.js";

const server = new Server();
server.pluginManager.register("sketch-manager", pluginSketchManager, {
  directory: resolve(dirname(fileURLToPath(import.meta.url)), "../sketches"),
});

Using the plugin

// Get the list of available sketches
const sketches = sketchManager.sketches;

// Activate a sketch
sketchManager.activateSketch("a-sketch");

// Deactivate a sketch
sketchManager.deactivateSketch("another-sketch");

// Get the list of active sketches
const activeSketches = sketchManager.activeSketches;

Client installation

Registering the plugin

// clients/mobile/index.js
import { loadConfig } from "@soundworks/helpers/node.js";
import { Client } from "@soundworks/core/client.js";
import pluginSketchManager from "@mobilizing/soundworks-plugin-sketch-manager/client.js";

const config = loadConfig(process.env.ENV, import.meta.url);
const client = new Client(config);
client.pluginManager.register("sketch-manager", pluginSketchManager, {
  root: $container,
  import: async (sketch) => {
    const { default: SketchClass } = await import(
      `../../sketches/${sketch}/clients/${client.role}$/index.js`
    );
    return SketchClass;
  },
});

Requiring the plugin

await client.start();

const sketchManager = await client.pluginManager.get("sketch-manager");
sketchManager.on("sketchactivated", (sketchName, sketchInstance) => {
  // Do something when a sketch is activated
});
sketchManager.on("sketchdeactivated", (sketchName, sketchInstance) => {
  // Do something when a sketch is deactivated
});
sketchManager.activeSketches.forEach((sketchName) => {
  const sketchInstance = sketchManager.getSketchInstance(sketchName);
  // Do something with already active sketches
});

Credits

This code has been written thanks to fundings from PSL Valorisation for the MobColl prematuration project program and the CPCFQ cooperation funds.

License

LGPL-3.0