@hcikn/colibri
v1.1.1
Published
Communication Library for Research Prototyping - Allows object synchronization, networking, and voice chat with little to no code required
Downloads
6
Readme
Colibri - Web Client
Installation
- NPM:
npm install @hcikn/colibri
- Yarn:
yarn add @hcikn/colibri
Configuration
Initialize Colibri once with:
import { Colibri } from '@hcikn/colibri';
Colibri.init('app_name', 'server_address');
// if using a custom port:
Colibri.init('app_name', 'server_address', 9011);
For server setup, refer to colibri-server.
Usage
Web Interface for Logging
Colibri provides a web logger with web interface to send diagnostic data (currently: console logs) to the server. This may be useful for devices (e.g., VR devices, smartphones) where access to the console is not easily available.
To setup, import the RemoteLogger
and call its init()
method. Any subsequent console
calls should now also appear on your colibri server's web interface, which can be accessed via http://<your-server-ip>:9011
.
import { RemoteLogger } from '@hcikn/colibri';
RemoteLogger.init();
See also the remote-logging sample (run sample with npm run sample/remote-logging
).
Sending Data between Clients
Colibri supports simple data transmission via pub/sub communication. Data can be published from anywhere in
the executed code, as illustrated with the following simple example of sending a boolean value on a "click" channel:
import { Sync } from '@hcikn/colibri';
Sync.sendBool('myChannel', true);
The sent data can then be received anywhere by registering a listener:
Sync.receiveBool('myChannel', (value) => {
// Will be called whenever a bool on "click" channel is received
});
The listener can be deregistered via:
Sync.unregister('myChannel', MyMethod);
The following built-in types are available for sync: bool, int (as number), float (as number), string, Vector2, Vector3, Quaternion, Color
and arrays thereof. For arbitrary data, you can use JSON:
Sync.sendJson('myChannel', { foo: 'bar' });
Sync.receiveJson('myChannel', (json) => { /* ... */ });
See also the broadcast sample (run sample with npm run sample/broadcast
).
Limitations:
- You have to register the listener before sending out data
- Type and channel must match between Listener and Sender (
number
will be converted to float for Unity clients, i.e., usefloat
listener on Unity clients for sending numbers!) - Remember to unregister your listener where necessary!
SyncModel
(Counterpart to SyncBehaviour in Unity client)
For more complex scenarios, Colibri supports synchronization of data models (e.g., for use in model-view-controller architectures). For this, we need extend the Model with SyncModel
:
import { SyncModel, Synced } from '@hcikn/colibri';
export class SampleClass extends SyncModel<SampleClass> {
@Synced()
get name() { return this._name; }
set name(val: string) { this._name = val; }
private _name = '';
@Synced()
private age = 0;
@Synced('billingAddress')
private address = '';
}
and enable experimentalDecorators
in the tsconfig.json
:
{
"compilerOptions": {
"experimentalDecorators": true
}
}
Any property or field marked with @Synced()
will be synchronized across all network clients. Note: Synchronization of fields (e.g., @Synced() private age = 0;
does not work on some frameworks such as React for some reason.
Lastly, we need to register the class with the Synchronization mechanism by calling RegisterModelSync
:
import { RegisterModelSync } from '@hcikn/colibri';
const [ SampleClasses$, registerExampleClass ] = RegisterModelSync<SampleClass>({ type: SampleClass });
The first return value (e.g., SampleClasses$
) is a BehaviorSubject that will be updated whenever a new instance of SampleClass is added, updated, or deleted. The second return value (e.g., registerExampleClass
) can be used to sync new instantiations:
const mySample = new SampleClass('myId'); // mySample is not synchronized across clients yet
registerExampleClass(mySample); // mySample is sent out to all other clients and will be synchronized
See also the model-sync sample (run sample with npm run sample/model-sync
).
Samples
See Sample folder for more examples on how to use the Colibri web client.