Client API

The Krmx client implementation is a NodeJS client and is written in TypeScript.

Take a look at the TypeScript SDK reference and source code (opens in a new tab) to learn more about the Client API.

If you need help setting up a project with Krmx, then please following the instructions at Getting Started.

Creating a Client

A Krmx client can be created using the createClient method.

import { createClient, Props } from '@krmx/client';
 
const props: Props = { /* configure here */ }
const client = createClient(props);

Props

When creating a client, configuration properties can be passed to configure it. The exported Props interface describes these properties.

The Krmx client doesn't connect to a client until client.connect(<client-url>) is invoked.

Client Lifetime

During the client lifetime, the client status can be used to identify the current state us of the client.

import { Client, Status } from '@krmx/client';
declare const client: Client;
 
const status: Status = client.getStatus();

The different status are described by the Status type. The client can change status by using the connect, link, unlink, leave and disconnect methods on the client.

Connect

The connect method is used to connect to a server.

import { Client } from '@krmx/client';
declare const client: Client;
 
// connect to a server
const serverUrl = 'ws://localhost:8082'
client.connect(serverUrl);

For the serverUrl argument you have to provide the ws:// or wss:// url of the websocket endpoint where your Krmx server is running.

For example: ws://my-subdomain.example.org:3002/my-game or ws://localhost:1234.

Link

The link field is a method that can be used to link the connection to a user.

The method require the first argument to be set to the username. For example: link('simon').

The method optionally takes a second argument with the authentication of your application as a string. This token is send to the server and will be available in the on('authenticate', ...) listener under the info.auth field.

import { Client } from '@krmx/client';
declare const client: Client;
 
// link to a user
const username = 'simon';
client.link(username, 'my-authentication');

The link method returns a promise that resolves when the server has linked the connection to the user. Or rejects when the server has rejected the connection. The rejection is an Error with message that represents the latest reason why linking the connection to a user was not successful. Some examples: 'user is already linked to a connection' or custom messages such as 'server is full'.

Unlink, Leave and Disconnect

The unlink, leave and disconnect methods are used to unlink from a user, leave the server, and disconnect from the server.

import { Client } from '@krmx/client';
declare const client: Client;
 
// leave the server
client.leave();
 
// unlink from a user
client.unlink();
 
// disconnect from the server
client.disconnect();

List Users

You can list all users that are joined on the server.

import { Client, User } from '@krmx/client';
declare const client: Client;
 
// get all users
const users: User[] = server.getUsers();
console.info(users); // [{ username: 'simon', isLinked: true }, ... ]

Send Messages

Once a client is connected and linked, you can send messages to the server.

import { Client } from '@krmx/client';
declare const client: Client;
 
// send a message to the server
const message = { type: 'my/custom', payload: 3 };
client.send(message);

See the Client interface for more information about these methods.

Events

You can listen to events, such as joining of new users, using an event listener. To do this you can use the client's on(eventName, listener): void; method.

See the client Events type for more information about the available events.

Krmx Events

Krmx emits events whenever: a user joins, a connection links to a user, a connection unlinks from a user, a user leaves, and more.

import { Client } from '@krmx/client';
declare const client: Client;
 
// example of listening to the 'link' event with an event listener
client.on('link', (username) => {
  console.info('A connection was linked to ', username);
});

You can find the explanation of each event type in the event-based documentation and in the TypeScript SDK reference.

Messages (from the server)

When the server send messages, these will be emitted as a message event. You can listen to these message using the client's on('message', <listener>) method.

import { Client } from '@krmx/client';
declare const client: Client;
 
client.on('message', (message) => {
  console.info('server sent:', message);
});

TypeScript SDK Reference

Take a look at the TypeScript SDK reference and source code (opens in a new tab) to learn more about the Client API.