ahmed-shehata / spark-state

Facebook Spark AR State Management JS module in AR Library

Spark State

The Spark State library introduces a solution to manage effects' states by creating globally synchronized data signals and making them available within an effect's JavaScript.

Contents

• Getting started
  • Installation
  • Spark AR project setup
  • Loading the module
• Documentation
  • GlobalCounterSignal
  • GlobalStringSignal
  • GlobalPeersMap
• Example
• Additional resources
• License

Getting started

Spark AR project setup

1. Download or upgrade to Spark AR Studio v128 or higher.
2. Open your project in Spark AR Studio.
3. Open the AR Library from within the Assets panel and select the Script Packages tab.
4. Import the spark-state package to the project.
5. In the project's Properties, add the Scripting Writeable Signal Source capability.

Loading the module

1. Add a new Javascript script to the project from the Assets panel, or open an existing one.

2. At the top of the script, load the module using the following line of code:

   const State = require('spark-state');

3. The current implementation also requires that you load the Multipeer and Participants modules in your script in order to enable the two associated capabilities:

   const Multipeer = require('Multipeer');
   const Participants = require('Participants');

Documentation

GlobalCounterSignal

GlobalCounterSignal is a wrapper object for the ScalarSignal class from the Spark AR API's ReactiveModule. However, the scalar value contained by the signal is synchronized globally across all peers in a multipeer effect.

Additionally, it's possible to subscribe to a GlobalCounterSignal like you would with an EventSource:

GlobalCounterSignal.subscribe(() => {
  // Code here will run when the value of the signal changes
});

Methods	Description
createGlobalCounterSignal(startValue: number, signalName: string)	Creates a new GlobalCounterSignal with a globally unique name as specified by signalName, and with the initial value set by startValue.
increment(i: number)	Increases the value of the GlobalCounterSignal by the value of i.
decrement(i: number)	Decreases the value of the GlobalCounterSignal by the value of i.
set(val: number)	Sets the value of the GlobalCounterSignal to val.

GlobalCounterSignal extends the ScalarSignal class. As such, methods exposed by ScalarSignal can also be called on GlobalCounterSignal.

Example

const State = require('spark-state');

(async function () {

    // Initializes a new global counter signal with the initial value: 1
    const globalCounter = await State.creatCounterGlobalSignal(1, 'globalCounter');

    // Increments the counter signal value by 2
    globalCounter.increment(2);
})();

GlobalStringSignal

GlobalStringSignal is a wrapper object for the StringSignal class from the Spark AR API's ReactiveModule. However, the string value contained by the signal is synchronised globally across all peers in a multipeer effect.

Additionally, it's possible to subscribe to a GlobalStringSignal like you would with an EventSource:

GlobalStringSignal.subscribe(() => {
  // Code here will run when the value of the signal changes
});

Methods	Description
createGlobalStringSignal(startValue: string, signalName: string)	Creates a new GlobalStringSignal with a globally unique name as specified by signalName, and with the initial value set by startValue.
set(val: string)	Sets the value of the GlobalStringSignal to val.

GlobalStringSignal extends the StringSignal class. As such, methods exposed by StringSignal can also be called on GlobalStringSignal.

Example

const State = require('spark-state');

(async function () {

    // Initializes a new global string signal with the initial value: 'Hello'
    const globalString = await State.creatStringGlobalSignal('Hello', 'globalString');

    // Sets the value of the signal to 'Hello world'
    globalString.set('Hello world');
})();

GlobalPeersMap

GlobalPeersMap is a key-value pair data type which contains the IDs of all participants in a multipeer effect as keys, and their global signals as values.

Values of types GlobalCounterSignal and GlobalStringSignal are supported.

The participantId parameters in the method calls refer to each effect participant's unique ID string as returned by the Participant.id property from the Spark AR API.

Methods	Description
createGlobalPeersMap(participantsStartValue: number | string, signalName: string)	Creates a new GlobalPeersMap with a globally unique name as specified by signalName, and with the initial value set by participantsStartValue.
get(participantId: string)	Returns the GlobalCounterSignal or GlobalStringSignal from the Participant specified by participantId.
set(participantId: string, val: number | string)	Sets the value of the GlobalCounterSignal or GlobalStringSignal to the value specified by val, for the Participant specified by participantId.
keys()	Returns all of the keys from the GlobalPeersMap, as participantIds.
setOnNewPeerCallback(callback: Function)	Sets a callback function to call whenever a new peer is added to the GlobalPeersMap.

Example

const State = require('spark-state');
const Participants = require('Participants');

(async function () {

    // Initializes a new global peer map
    const points = await State.createPeersGlobalMap(0, 'points');

    // Retrieve the ID for the self participant
    const myParticipantId = await.Participants.self.id;

    // Get the GlobalCounterSignal from the specified participant
    const pointCounter = await points.get(myParticipantId);

})();

Full Spark AR API documentation is available on the main documentation site.

Example

The sample code found in the script.js file shows practical usage for all of the global types currently supported by the Spark State library.

Additional resources

The following resources are available on the Spark AR Studio documentation site:

• ParticipantsModule
• MultipeerModule
• Scripting your first multipeer effect
• Creating turn-based experiences

License

The Spark State library is MIT licensed.