space.cursors.subscribe().
Set cursor position
Set the position of a member’s cursor using theset() method. A position must contain an X-axis value and a Y-axis value to set the cursor position on a 2D plane. Calling set() will emit a cursor event so that other members are informed of the cursor movement in realtime.
A member must have been entered into the space to set their cursor position.
The set() method takes the following parameters:
| Parameter | Description | Type |
|---|---|---|
| position.x | The position of the member’s cursor on the X-axis. | Number |
| position.y | The position of the member’s cursor on the Y-axis. | Number |
| data | An optional arbitrary JSON-serializable object containing additional information about the cursor, such as a color. | Object |
set() method:
Subscribe to cursor events
Subscribe to cursor events by registering a listener. Cursor events are emitted whenever a member moves their cursor by callingset(). Use the subscribe() method on the cursors object of a space to receive updates.
The following is an example of subscribing to cursor events:
The following is an example payload of a cursor event. Cursor events are uniquely identifiable by the connectionId of a cursor.
The following are the properties of a cursor event payload:
| Property | Description | Type |
|---|---|---|
| connectionId | The unique identifier of the member’s connection. | String |
| clientId | The client identifier for the member. | String |
| position | An object containing the position of a member’s cursor. | Object |
| position.x | The position of the member’s cursor on the X-axis. | Number |
| position.y | The position of the member’s cursor on the Y-axis. | Number |
| data | An optional arbitrary JSON-serializable object containing additional information about the cursor. | Object |
Unsubscribe from cursor events
Unsubscribe from cursor events to remove previously registered listeners. The following is an example of removing a listener for cursor update events: Or remove all listeners:Cursor options
Cursor options are set when creating or retrieving aSpace instance. They are used to control the behavior of live cursors.
outboundBatchInterval
TheoutboundBatchInterval is the interval at which a batch of cursor positions are published, in milliseconds, for each client. This interval increases as the number of members in a space grows, adjusting based on groups of 100 members.
The default value is 25ms which is optimal for the majority of use cases. If you wish to optimize the interval further, then decreasing the value will improve performance by further ‘smoothing’ the movement of cursors at the cost of increasing the number of events sent. Be aware that at a certain point the rate at which a browser is able to render the changes will impact optimizations.
paginationLimit
The volume of messages sent can be high when using live cursors. Because of this, the last known position of every members’ cursor is obtained from history. ThepaginationLimit is the number of pages that should be searched to find the last position of each cursor. The default is 5.
Retrieve cursors
Cursor positions can be retrieved in one-off calls. These are local calls that retrieve the latest position of cursors retained in memory by the SDK. The following is an example of retrieving a member’s own cursor position: The following is an example payload returned byspace.cursors.getSelf():
The following is an example of retrieving the cursor positions for all members other than the member themselves:
The following is an example payload returned by space.cursors.getOthers():
The following is an example of retrieving the cursor positions for all members, including the member themselves. getAll() is useful for retrieving the initial position of members’ cursors.
The following is an example payload returned by space.cursors.getAll():
Example usage
The following is an example of the steps involved in implementing live cursors.Live cursor foundations
The Spaces SDK is built upon existing Ably functionality available in Ably’s Core SDKs. Understanding which core features are used to provide the abstractions in the Spaces SDK enables you to manage space state and build additional functionality into your application. Live cursors build upon the functionality of the Ably Pub/Sub presence feature. Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own channel. The other features of the Spaces SDK, such as avatar stacks, member locations and component locking all share a single channel. For this same reason, cursor position updates are not included in the space state and may only be subscribed to on thecursors namespace.
The channel is only created when a member calls space.cursors.set(). The live cursors channel object can be accessed through space.cursors.channel. To monitor the underlying state of the cursors channel, the channel object can be accessed through space.cursors.channel.