geckos.io Snapshot Interpolation

On the server, you use the SnapshotInterpolation instance to create snapshots of your world state. You can optionally add these snapshots to the vault to access them later (e.g., for lag compensation).

1. Initialize SnapshotInterpolation.
2. In your server update loop, call SI.snapshot.create(worldState).
3. (Optional) Call SI.vault.add(snapshot) to store the snapshot.
4. Emit the snapshot to clients.

import { SnapshotInterpolation } from '@geckos.io/snapshot-interpolation'

const SI = new SnapshotInterpolation()

// your server update loop
update() {
  const snapshot = SI.snapshot.create(worldState)
  SI.vault.add(snapshot)
  this.emit('update', snapshot)
}

To reduce bandwidth, you can compress snapshots using @geckos.io/typed-array-buffer-schema before sending them over the network.

Workflow:

1. Define a schema for your player and snapshot data.
2. Server: Create a snapshot using SI.snapshot.create(), then convert it to a buffer using model.toBuffer(snapshot).
3. Client: Receive the buffer, convert it back to a snapshot using model.fromBuffer(buffer), and add it to the interpolation system using SI.snapshot.add(snapshot).

// server.js
const snapshot = SI.snapshot.create({ players: [...] })
const buffer = snapshotModel.toBuffer(snapshot)
send(buffer)

// client.js
receive(buffer => {
  const snapshot = snapshotModel.fromBuffer(buffer)
  SI.snapshot.add(snapshot)
})

You can install the library via npm for Node.js/TypeScript projects, or use the bundled version via a <script> tag for browser-based projects.

NPM Installation:

npm install @geckos.io/snapshot-interpolation

Browser (Bundled):

<script src="https://unpkg.com/@geckos.io/snapshot-interpolation@1.0.1/bundle/snapshot-interpolation.js"></script>
<script>
  const { SnapshotInterpolation, Vault } = Snap
</script>

The Vault holds and secures snapshots. Each SnapshotInterpolation instance has its own vault. You can also create standalone Vault instances.

Common Vault Operations:

• vault.add(snapshot): Add a snapshot to the vault.
• vault.getById(id): Retrieve a specific snapshot by its ID.
• vault.get(): Get the latest snapshot.
• vault.get(time): Get the two snapshots surrounding a specific timestamp (returns { older, newer }).
• vault.get(time, closest): Get the closest snapshot to a specific time.
• vault.setMaxSize(size) / vault.getMaxSize(): Manage the capacity of the vault.

import { Vault } from '@geckos.io/snapshot-interpolation'

const customVault = new Vault()
// ... use vault methods

The Vault class manages the storage and retrieval of snapshots.

Methods:

• getById(id: ID): Snapshot
• get(): Snapshot | undefined
• get(time: number): { older: Snapshot; newer: Snapshot; } | undefined
• get(time: number, closest: boolean): Snapshot | undefined
• add(snapshot: Snapshot): void
• size(): number
• setMaxSize(size: number): void
• getMaxSize(): number

To use the library, instantiate the SnapshotInterpolation class. You can optionally provide the server's frame rate (FPS) to automatically calculate a default interpolation buffer, or provide a custom configuration object.

If serverFPS is provided, the interpolationBuffer is automatically set to (1000 / serverFPS) * 3 milliseconds.

Config Options:

• autoCorrectTimeOffset (boolean, default: true): If enabled, the library will automatically adjust the client-server timeOffset if the difference exceeds 50ms.

import { SnapshotInterpolation } from './snapshot-interpolation';

// Initialize with server FPS (e.g., 60 FPS)
const interpolation = new SnapshotInterpolation(60);

// Or initialize with custom config
const interpolation = new SnapshotInterpolation(null, { autoCorrectTimeOffset: false });

Use getById(id: ID) to find a specific snapshot within the vault using its unique identifier. Returns the Snapshot if found, or undefined if no match exists.

const snapshot = vault.getById('unique-id-123');

The snapshot property provides methods to manage the lifecycle of snapshots.

1. On the Server: Use snapshot.create(state) to generate a new Snapshot. The state can be an array of entities or an object mapping keys to entity arrays. Each entity must have a unique id (string or number).
2. On the Client: Use snapshot.add(snapshot) to add a received snapshot to the internal vault. This allows the library to calculate interpolation between snapshots.

Note: CreateSnapshot is a static method and can be used independently.

// Server-side: Create a snapshot
const state = [{ id: 'player1', x: 10, y: 20 }];
const snapshot = interpolation.snapshot.create(state);

// Client-side: Add the received snapshot
interpolation.snapshot.add(snapshot);

The interpolationBuffer determines how far in the past the client renders relative to the latest received snapshot. This buffer helps smooth out jitter and network fluctuations.

You can get or set this value in milliseconds.

// Get current buffer
console.log(interpolation.interpolationBuffer.get());

// Set a custom buffer of 100ms
interpolation.interpolationBuffer.set(100);