Lib

@probability-nz/lib

Non-React utilities and types for Probability plugins. Usable in Node, server-side validators, or non-React clients.

Build

pnpm build

Shared utilities, types, and pure functions for Probability plugins.

Core

Face

Defined in: packages/types/dist/doc.d.ts:11

A named orientation of a piece (e.g. die face)

Properties

name

name: string

Defined in: packages/types/dist/doc.d.ts:12

rotation

rotation: Vector3Tuple

Defined in: packages/types/dist/doc.d.ts:13

GameState

Defined in: packages/types/dist/doc.d.ts:177

The Automerge document shape — a digital analog of the physical game. Pieces are stacked on each other and positioned relatively.

Example

// A token, sitting on a card, sitting on a chessboard
{
  "$schema": "https://registry.probability.nz/npm/@probability-nz/types/-/types-0.0.0.tgz/dist/analog.json",
  "templates": {},
  "children": [
    {
      "name": "Chess Board",
      "position": [0, 0.1, 0],
      "locked": true,
      "src": "Chess_Board.glb",
      "children": [
        {
          "name": "card",
          "position": [0, 0.002, 0],
          "children": [
            { "name": "pawn", "position": [0, 0.3, 0], "children": [] }
          ]
        }
      ]
    }
  ]
}

Properties

__automergeMoves?

optional __automergeMoves: __AutomergeMoves

Defined in: packages/types/dist/doc.d.ts:185

Tracks Automerge objectId changes when pieces are reparented.

$schema

$schema: "https://registry.probability.nz/npm/@probability-nz/types/-/types-0.0.0.tgz/dist/analog.json"

Defined in: packages/types/dist/doc.d.ts:178

children

children: Piece[]

Defined in: packages/types/dist/doc.d.ts:179

templates

templates: Templates

Defined in: packages/types/dist/doc.d.ts:180

HashProps

Defined in: packages/types/dist/hashroute.d.ts:19

Connection context passed to plugins via the URL hash.

Example

https://example.com/plugin#{"doc":"automerge:...","sync":["wss://..."],"delegation":"..."}

Properties

delegation?

optional delegation: string

Defined in: packages/types/dist/hashroute.d.ts:28

Will be a base64url-encoded KeyHive/Beelay Ed25519 Signed<Delegation>.

doc

doc: AutomergeUrl

Defined in: packages/types/dist/hashroute.d.ts:21

Automerge document URL

sync

sync: [string, ...string[]]

Defined in: packages/types/dist/hashroute.d.ts:23

Sync server WebSocket URLs

Piece

Defined in: packages/types/dist/doc.d.ts:59

A game piece in a manifest or document

Extends

PieceTemplate

Properties

children?

optional children: Piece[]

Defined in: packages/types/dist/doc.d.ts:60

color?

optional color: string | null

Defined in: packages/types/dist/doc.d.ts:46

CSS color string, or null for no tint

Default

"#808080"

Inherited from

PieceTemplate.color

faces?

optional faces: Face[]

Defined in: packages/types/dist/doc.d.ts:53

Named face orientations (e.g. for dice)

Inherited from

PieceTemplate.faces

locked?

optional locked: boolean

Defined in: packages/types/dist/doc.d.ts:51

Make piece non-interactive?

Default

false

Inherited from

PieceTemplate.locked

name?

optional name: string

Defined in: packages/types/dist/doc.d.ts:20

Inherited from

PieceTemplate.name

position?

optional position: Vector3Tuple

Defined in: packages/types/dist/doc.d.ts:31

World position in meters.

Default

[0, 0, 0]

Inherited from

PieceTemplate.position

rotation?

optional rotation: Vector3Tuple

Defined in: packages/types/dist/doc.d.ts:41

Euler rotation (degrees)

Default

[0, 0, 0]

Inherited from

PieceTemplate.rotation

scale?

optional scale: Vector3Tuple

Defined in: packages/types/dist/doc.d.ts:36

Unitless multiplier applied to the model.

Default

[1, 1, 1]

Inherited from

PieceTemplate.scale

src?

optional src: string

Defined in: packages/types/dist/doc.d.ts:22

Path to a glTF/GLB model

Inherited from

PieceTemplate.src

template?

optional template: string

Defined in: packages/types/dist/doc.d.ts:26

Key into the sibling templates object to inherit defaults from

Inherited from

PieceTemplate.template

PieceTemplate

Defined in: packages/types/dist/doc.d.ts:19

Piece template — shared fields for pieces

Extended by

Piece

Properties

color?

optional color: string | null

Defined in: packages/types/dist/doc.d.ts:46

CSS color string, or null for no tint

Default

"#808080"

faces?

optional faces: Face[]

Defined in: packages/types/dist/doc.d.ts:53

Named face orientations (e.g. for dice)

locked?

optional locked: boolean

Defined in: packages/types/dist/doc.d.ts:51

Make piece non-interactive?

Default

false

name?

optional name: string

Defined in: packages/types/dist/doc.d.ts:20

position?

optional position: Vector3Tuple

Defined in: packages/types/dist/doc.d.ts:31

World position in meters.

Default

[0, 0, 0]

rotation?

optional rotation: Vector3Tuple

Defined in: packages/types/dist/doc.d.ts:41

Euler rotation (degrees)

Default

[0, 0, 0]

scale?

optional scale: Vector3Tuple

Defined in: packages/types/dist/doc.d.ts:36

Unitless multiplier applied to the model.

Default

[1, 1, 1]

src?

optional src: string

Defined in: packages/types/dist/doc.d.ts:22

Path to a glTF/GLB model

template?

optional template: string

Defined in: packages/types/dist/doc.d.ts:26

Key into the sibling templates object to inherit defaults from

Templates

Templates = Record<string, PieceTemplate>

Defined in: packages/types/dist/doc.d.ts:83

Reusable piece defaults, keyed by template name. Templates can inherit from other templates via the template field, and share syntax with pieces minus a children property.

Example

{
  "$schema": "https://registry.probability.nz/npm/@probability-nz/types/-/types-0.0.0.tgz/dist/analog.json",
  "templates": {
    "defaults": { "scale": [0.1, 0.1, 0.1] },
    "redToken": { "template": "defaults", "name": "Red token", "src": "redToken.glb" }
  },
  "children": [
    { "template": "redToken", "position": [0.0, 0, 0] },
    { "template": "redToken", "position": [0.1, 0, 0] },
    { "template": "redToken", "position": [0.2, 0, 0] }
  ]
}

parseHashProps()

parseHashProps(hash): HashProps | undefined

Defined in: packages/lib/src/parseHashProps.ts:17

Parse plugin context from the URL hash.

Parameters

hash

string

Expects location.hash format (with # prefix).

Returns

HashProps | undefined

undefined if the hash is missing or unparseable.

Presence

FocusOp

Defined in: packages/types/dist/presence.d.ts:27

Cursor focus (what the user is looking at) — no automerge equivalent

Properties

action

action: "focus"

Defined in: packages/types/dist/presence.d.ts:28

path

path: AnchoredPath

Defined in: packages/types/dist/presence.d.ts:29

MoveOp

Defined in: packages/types/dist/presence.d.ts:45

Move — no automerge equivalent yet (planned feature)

Properties

action

action: "move"

Defined in: packages/types/dist/presence.d.ts:46

path

path: AnchoredPath

Defined in: packages/types/dist/presence.d.ts:47

to

to: AnchoredPath

Defined in: packages/types/dist/presence.d.ts:48

PresenceState

Defined in: packages/types/dist/presence.d.ts:54

Presence state broadcast between peers

Properties

client?

optional client: string

Defined in: packages/types/dist/presence.d.ts:56

color?

optional color: string

Defined in: packages/types/dist/presence.d.ts:55

cursors?

optional cursors: Record<string, { position?: Vector3Tuple; rotation?: Vector3Tuple; }>

Defined in: packages/types/dist/presence.d.ts:59

op?

optional op: FocusOp | MoveOp | PutOp

Defined in: packages/types/dist/presence.d.ts:57

PutOp

Defined in: packages/types/dist/presence.d.ts:35

Anchored version of automerge’s PutPatch

Properties

action

action: "put"

Defined in: packages/types/dist/presence.d.ts:36

conflict?

optional conflict: boolean

Defined in: packages/types/dist/presence.d.ts:39

path

path: AnchoredPath

Defined in: packages/types/dist/presence.d.ts:37

value

value: JsonValue

Defined in: packages/types/dist/presence.d.ts:38

Client

Client = string

Defined in: packages/types/dist/presence.d.ts:16

Client identifier in npm format: name@version or name#commit (e.g. "my-plugin@1.0.0", "@garbo-succus/probability-nz#c0mM1t").

Color

Color = string

Defined in: packages/types/dist/presence.d.ts:10

Any valid CSS color string (e.g. "red", "#abc", "rgb(0,0,0)").

getPeerName()

getPeerName(peerId): string

Defined in: packages/lib/src/peerName.ts:43

Deterministic, friendly peer name from a peer id (e.g. “Brave Penguin”). Seeded with FNV-1a to compensate for the upstream generator’s weak string seeding.

Parameters

peerId

string

Returns

string

toColor()

toColor(seed): string

Defined in: packages/lib/src/toColor.ts:33

Deterministic, visually distinct color from a string.

Parameters

seed

string

Returns

string

Example

toColor('player-1'); // '#a4c032'

Advanced

GameManifest

Defined in: packages/types/dist/doc.d.ts:141

Static game definition — imported to create a new GameState. Similar to a GameState but with a scenarios array on the root instead of children.

Example

// 2-4 and 4-8 player scenarios
{
  "$schema": "https://registry.probability.nz/npm/@probability-nz/types/-/types-0.0.0.tgz/dist/analog.json",
  "templates": { "token": { "src": "token.glb" } },
  "scenarios": [
    {
      "name": "2-4 player setup",
      "children": [
        {
          "name": "Game board",
          "src": "gameboard.glb",
          "children": [
            { "template": "token" },
            { "template": "token" },
            { "template": "token" },
            { "template": "token" }
          ]
        }
      ]
    },
    {
      "name": "4-8 player setup",
      "children": [
        {
          "name": "Game board",
          "src": "gameboard.glb",
          "children": [
            { "template": "token" },
            { "template": "token" },
            { "template": "token" },
            { "template": "token" },
            { "template": "token" },
            { "template": "token" },
            { "template": "token" },
            { "template": "token" }
          ]
        }
      ]
    }
  ]
}

Properties

$schema

$schema: "https://registry.probability.nz/npm/@probability-nz/types/-/types-0.0.0.tgz/dist/analog.json"

Defined in: packages/types/dist/doc.d.ts:142

scenarios

scenarios: Scenario[]

Defined in: packages/types/dist/doc.d.ts:144

templates

templates: Templates

Defined in: packages/types/dist/doc.d.ts:143

Scenario

Defined in: packages/types/dist/doc.d.ts:88

A named starting arrangement of pieces

Properties

children

children: Piece[]

Defined in: packages/types/dist/doc.d.ts:90

name?

optional name: string

Defined in: packages/types/dist/doc.d.ts:89

Vector3Tuple

Vector3Tuple = [number, number, number]

Defined in: packages/types/dist/doc.d.ts:6

[x, y, z] — right-handed Y-up coordinate system (from Three.js).

loadManifest()

loadManifest(url): Promise<GameManifest>

Defined in: packages/lib/src/manifest.ts:37

Fetch a game manifest, resolving asset URLs.

Parameters

url

string

Must end with /.

Returns

Promise<GameManifest>

Throws

On network errors, missing main field, or schema validation failure.

Example

const manifest = await loadManifest('https://registry.probability.nz/games/chess/');

See

buildGameState for the next step after loading.

objectIdToPath()

objectIdToPath(doc, objId): Prop[] | undefined

Defined in: packages/lib/src/objectIdToPath.ts:12

Find the path to an object in an Automerge document by its ID. Will be removed when Automerge adds native support.

Parameters

doc

Doc<unknown>

objId

string

Returns

Prop[] | undefined

Functions

assertGameState()

assertGameState(schema, value): asserts value is GameState

Defined in: packages/lib/src/validate.ts:36

Assert that value is a valid GameState for the given schema.

Parameters

schema

JsonSchema

value

unknown

Returns

asserts value is GameState

Throws

On validation failure.

assertPresenceState()

assertPresenceState(schema, value): asserts value is PresenceState

Defined in: packages/lib/src/validate.ts:48

Assert that value is a valid PresenceState for the given schema.

Parameters

schema

JsonSchema

value

unknown

Returns

asserts value is PresenceState

Throws

On validation failure.

buildGameState()

buildGameState(__namedParameters, scenarioIndex): GameState

Defined in: packages/lib/src/buildGameState.ts:8

Build a GameState from a loaded manifest and scenario index.

Parameters

__namedParameters

GameManifest

scenarioIndex

number

Returns

GameState

Throws

If scenarioIndex is out of bounds.

See

loadManifest for fetching the manifest.

Type Aliases

AnchoredPath

AnchoredPath = [string, ...Prop[]]

Defined in: packages/types/dist/presence.d.ts:22

A path anchored to a specific Automerge object. First element is always an ObjID string.

Example

`["2@abc123", "children", 0, "position"]`

AutomergeUrl

AutomergeUrl = RepoAutomergeUrl & `automerge:${string}`

Defined in: packages/types/dist/hashroute.d.ts:3

Automerge document URL (e.g. automerge:111111111111111111).

JsonValue

JsonValue = string | number | boolean | null | JsonArray | JsonObject

Defined in: packages/types/dist/hashroute.d.ts:10

JSON-serializable value

Prop

Prop = string | number

Defined in: node_modules/.pnpm/@automerge+automerge@3.2.4/node_modules/@automerge/automerge/dist/wasm_types.d.ts:8

Variables

SCHEMA_URL

const SCHEMA_URL: "https://registry.probability.nz/npm/@probability-nz/types/-/types-0.0.0.tgz/dist/analog.json" = "https://registry.probability.nz/npm/@probability-nz/types/-/types-0.0.0.tgz/dist/analog.json"

Defined in: packages/types/dist/doc.d.ts:1