React

@probability-nz/react

React SDK for building Probability plugins. Plugins are web apps that can help with gameplay, act as an AI opponent, manage decks, enforce rules, etc.

A plugin is launched via a URL hash carrying a HashProps object. Once mounted, <ProbProvider> connects to the sync server; useProbDocument handles the game state and usePresenceState broadcasts presence.

A working example lives at examples/example-plugin — see its README for run/launch instructions.

Errors:

1. Invalid URL hash: parseHashProps() returned undefined; consumer should render a fallback.
2. Automerge sync: doc never loads (~60s timeout). WebSocket errors are silent.
3. changeDoc(): doc schema validation failed
4. useProbDocument: document deleted by peer
5. Doc update: invalid mutation (eg undefined, non-serializable values)
6. Peer presence: Warning: peer broadcasted an invalid presence state. Currently silent — TODO.
7. update(): local presence schema validation failed

SDK for building probability.nz plugins (React).

Core

ProbProviderProps

Defined in: react/ProbProvider.tsx:8

Properties

children

children: ReactNode

Defined in: react/ProbProvider.tsx:11

sync?

optional sync: string[]

Defined in: react/ProbProvider.tsx:10

WebSocket sync server URLs.

---

ProbProvider()

ProbProvider(__namedParameters): Element

Defined in: react/ProbProvider.tsx:18

Wrap your plugin to enable document sync and SDK hooks.

Parameters

__namedParameters

ProbProviderProps

Returns

Element

---

useHashProps()

useHashProps(): HashProps | undefined

Defined in: react/useHashProps.ts:19

Parsed HashProps from location.hash, reactive to hashchange. Returns undefined if the hash is missing or unparseable.

Returns

HashProps | undefined

---

useProbDocument()

useProbDocument<T>(id): [Doc<T>, ChangeDocFn<T>]

Defined in: react/useProbDocument.ts:16

Schema-validated access to the shared game document.

Type Parameters

T

T extends object

Parameters

id

AnyDocumentId

Returns

[Doc<T>, ChangeDocFn<T>]

Throws

On schema validation failure.

Remarks

Suspends until loaded.

Presence

usePresenceState()

usePresenceState<T>(docUrl, __namedParameters): object

Defined in: react/usePresenceState.ts:29

Share ephemeral state with peers (e.g. cursors, intended moves).

Type Parameters

T

T extends PresenceState

Parameters

docUrl

AnyDocumentId

__namedParameters

UsePresenceStateOptions<T>

Returns

object

localState

localState: Store<T>

peerStates

peerStates: PeerStateView<T>

update()

update: (updater) => void

Parameters

updater

(prev) => T

Returns

void

Default Value

tickRate — DEFAULT_TICK_RATE

Throws

On schema validation failure.

Remarks

Suspends until loaded.

Advanced

createGame()

createGame(repo, manifest, scenarioIndex): DocHandle<GameState>

Defined in: createGame.ts:10

Create a new game document from a manifest and scenario index.

Parameters

repo

Repo

manifest

GameManifest

scenarioIndex

number

Returns

DocHandle<GameState>

Throws

If scenarioIndex is out of bounds.

See

buildGameState for building state without creating a document.