@geckos.io/snapshot-interpolation

中文文档
1.1.1发布于 2025/02/22BSD-3-ClauseTypeScriptCommonJS零依赖近 30 天下载 5321

A Snapshot Interpolation library for Real-Time Multiplayer Games

原始使用文档
文档目录16 节
  1. A Snapshot Interpolation library for Real-Time Multiplayer …
  2. About
  3. Features
  4. Introduction
  5. Game Example
  6. Install
  7. How to use
  8. server.js
  9. client.js
  10. World State
  11. Linear Interpolation
  12. Degrees, Radians and Quaternions
  13. Multiple States
  14. Vault
  15. Compression
  16. API
logo

Snapshot Interpolation

A Snapshot Interpolation library for Real-Time Multiplayer Games

Easily add Snapshot Interpolation (also called Entity Interpolation or Buffer Interpolation) to your Games.

NPM version Github Workflow GitHub last commit Downloads Codecov build with TypeScript


About

The Interpolation Buffer is by default 3 server frames long (Interpolation between 4 Snapshots). So if the latency is 50ms and one server frame is 50ms, the Interpolation Buffer would be 200ms long.

If you are interested to learn a bit more about Snapshot Interpolation, watch this video.

Features

  • Easily add Client-Side Prediction and Server Reconciliation.
  • Easily add Lag Compensation.
  • Easily compress/encode your snapshots before sending/receiving.

Introduction

Take a look at these YouTube videos:

Game Example

The github repository contains a nice example. Take a look!

# clone the repo
$ git clone https://github.com/geckosio/snapshot-interpolation.git

# cd into it
$ cd snapshot-interpolation

# install all dependencies
$ npm install

# start the example
$ npm start

# play in your browser
http://localhost:8080/

Install

Install from npm.

npm install @geckos.io/snapshot-interpolation

Or use the bundled version.

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

How to use

server.js

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

// initialize the library
const SI = new SnapshotInterpolation()

// your server update loop
update() {
  // create a snapshot of the current world
  const snapshot = SI.snapshot.create(worldState)

  // add the snapshot to the vault in case you want to access it later (optional)
  SI.vault.add(snapshot)

  // send the snapshot to the client (using geckos.io or any other library)
  this.emit('update', snapshot)
}

client.js

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

// initialize the library (add your server's fps)
const SI = new SnapshotInterpolation(serverFPS)

// when receiving the snapshot on the client
this.on('update', (snapshot) => {
  // read the snapshot
  SI.snapshot.add(snapshot)
}

// your client update loop
update() {
  // calculate the interpolation for the parameters x and y and return the snapshot
  const snapshot = SI.calcInterpolation('x y') // [deep: string] as optional second parameter

  // access your state
  const { state } = snapshot

  // apply the interpolated values to you game objects
  const { id, x, y } = state[0]
  if (hero.id === id) {
    hero.x = x
    hero.y = y
  }
}

World State

The World State has to be an Array with non nested Objects (except for Quaternions). You can name you keys as you want. For degree, radian or quaternion values add key(deg), key(rad) or key(quat).

Linear Interpolation

// the worldState on the server
const worldState = [
  { id: 'heroBlue', x: 23, y: 14, z: 47 },
  { id: 'heroRed', x: 23, y: 14, z: 47 },
  { id: 'heroGreen', x: 23, y: 14, z: 47 }
]

// calc interpolation on the client
SI.calcInterpolation('x y z')

Degrees, Radians and Quaternions

// the worldState on the server
const worldState = [
  {
    id: 'myHero',
    direction: Math.PI / 2,
    rotationInDeg: 90,
    q: { x: 0, y: 0.707, z: 0, w: 0.707 }
  }
]

// calc interpolation on the client
SI.calcInterpolation('direction(rad) rotationInDeg(deg) q(quat)')

Multiple States

// the players state
const playersState = [
  { id: 0, x: 65, y: -17 },
  { id: 1, x: 32, y: 9 }
]

// the towers state
const towersState = [
  { id: 0, health: 100, type: 'blizzardCannon' },
  { id: 1, health: 89, type: 'flameThrower' }
]

const worldState = {
  players: playersState,
  towers: towersState
}

// create snapshot
SI.snapshot.create(worldState)

// we only want to interpolate x and y on the players object
SI.calcInterpolation('x y', 'players')

Vault

The Vault holds and secures all your Snapshots. Each SnapshotInterpolation instance holds one Vault, but you can easily create more if you need:

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

const customVault = new Vault()

Compression

You can use the package @geckos.io/typed-array-buffer-schema to compress your snapshots before sending them to the client.

// schema.js
const playerSchema = BufferSchema.schema('player', {
  id: uint8,
  x: { type: int16, digits: 1 },
  y: { type: int16, digits: 1 }
})

const snapshotSchema = BufferSchema.schema('snapshot', {
  id: { type: string8, length: 6 },
  time: uint64,
  state: { players: [playerSchema] }
})

export const snapshotModel = new Model(snapshotSchema)

// server.js
const snapshot = SI.snapshot.create({
  players: [
    { id: 0, x: 17.5, y: -1.1 },
    { id: 1, x: 5.8, y: 18.9 }
  ]
})

const buffer = snapshotModel.toBuffer(snapshot)
send(buffer)

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

API

This looks very TypeScriptisch, but you can of course use it in JavaScript as well.

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

// types
type Value = number | string | Quat | undefined
type ID = string
type Time = number
type State = Entity[]
type Quat = { x: number; y: number; z: number; w: number }

// interfaces
export interface Entity {
  id: string
  [key: string]: Value
}
export interface Snapshot {
  id: ID
  time: Time
  state: State | { [key: string]: State }
}
export interface InterpolatedSnapshot {
  state: State
  percentage: number
  older: ID
  newer: ID
}

// static methods
/** Create a new Snapshot */
SnapshotInterpolation.CreateSnapshot(state: State): Snapshot

/** Create a new ID */
SnapshotInterpolation.NewId(): string

/** Get the current time in milliseconds. */
SnapshotInterpolation.Now(): number

// class SnapshotInterpolation
const SI = new SnapshotInterpolation(serverFPS?: number)

/** Access the vault. */
SI.vault: Vault

/** Get the Interpolation Buffer time in milliseconds. */
SI.interpolationBuffer.get(): number

/** Set the Interpolation Buffer time in milliseconds. */
SI.interpolationBuffer.set(milliseconds: number): void

/** Create the snapshot on the server. */
SI.snapshot.create(state: State): Snapshot

/** Add the snapshot you received from the server to automatically calculate the interpolation with calcInterpolation() */
SI.snapshot.add(snapshot: Snapshot): void

/** Interpolate between two snapshots give the percentage or time. */
SI.interpolate(snapshotA: Snapshot, snapshotB: Snapshot, timeOrPercentage: number, parameters: string, deep: string): InterpolatedSnapshot

/** Get the calculated interpolation on the client. */
SI.calcInterpolation(parameters: string, deep: string): InterpolatedSnapshot | undefined

// class Vault
const vault = new Vault()

/** Get a Snapshot by its ID. */
vault.getById(id: ID): Snapshot

/** Get the latest snapshot */
vault.get(): Snapshot | undefined;

/** Get the two snapshots around a specific time */
vault.get(time: number): { older: Snapshot; newer: Snapshot; } | undefined

/** Get the closest snapshot to e specific time */
vault.get(time: number, closest: boolean): Snapshot | undefined

/** Add a snapshot to the vault. */
vault.add(snapshot: Snapshot): void

/** Get the current capacity (size) of the vault. */
vault.size(): number

/** Set the max capacity (size) of the vault. */
vault.setMaxSize(size: number): void

/** Get the max capacity (size) of the vault. */
vault.getMaxSize(): number

版本与发布记录

@geckos.io/snapshot-interpolation 共发布 10 个版本,首次发布于 2020/06/03;过去 12 个月发布了 0 个版本。

版本发布日期距今
1.1.1latest2025/02/221.7 年前
1.1.02021/11/294 年前
1.0.22021/01/315 年前
1.0.12020/08/126 年前
1.0.02020/07/306 年前
0.0.52020/06/206 年前

关于 @geckos.io/snapshot-interpolation 的常见问题

@geckos.io/snapshot-interpolation 是什么?

A Snapshot Interpolation library for Real-Time Multiplayer Games

如何安装 @geckos.io/snapshot-interpolation?

在项目目录运行 npm install @geckos.io/snapshot-interpolation,或使用 pnpm add / yarn add / bun add。

@geckos.io/snapshot-interpolation 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@geckos.io/snapshot-interpolation 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@geckos.io/snapshot-interpolation 可以商用吗?

@geckos.io/snapshot-interpolation 使用 BSD-3-Clause 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括,不构成法律意见,请以许可原文为准。

@geckos.io/snapshot-interpolation 的下载量有多少?

根据 npm 官方下载统计,@geckos.io/snapshot-interpolation 在 2026/10/16 – 2026/11/14 这 30 天内被下载 5,321 次,日均约 177 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geckos.io/snapshot-interpolation 还在维护吗?

最新版本 1.1.1 发布于 2025/02/22(1.7 年前);至今共发布 10 个版本,其中过去 12 个月发布了 0 个;首次发布于 2020/06/03。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。