WorldFacts

Authoritative key-value fact store with dot-notated/string keys, provenance tracking ({ source, timestamp }), snapshot/restore for save games, and onChange listeners with unbind.

Constructor

new WorldFacts(initialFactsopt)

Parameters:
NameTypeAttributesDefaultDescription
initialFactsRecord.<string, any><optional>
null

Classes

WorldFacts

Members

size

Number of stored authoritative facts.

Methods

allFacts() → {Record.<string, {value: any, source: string, timestamp: number}>}

Returns all authoritative records with provenance.

Returns:
Type: 
Record.<string, {value: any, source: string, timestamp: number}>

clear()

Clears all facts.

delete(key, provenanceopt) → {boolean}

Deletes a fact and notifies listeners.

Parameters:
NameTypeAttributesDefaultDescription
keystring
provenancestring | object<optional>
null
Returns:
Type: 
boolean

entries() → {Array.<Array>}

Returns an array of [key, value] entries.

Returns:
Type: 
Array.<Array>

get(key, defaultValueopt) → {any}

Gets a fact value. Supports exact key, dot-notated sub-path traversal, and namespace aggregation.

Parameters:
NameTypeAttributesDescription
keystring
defaultValueany<optional>
Returns:
Type: 
any

getFact(key) → {Object|null}

Returns full fact record including value and provenance metadata.

Parameters:
NameTypeDescription
keystring
Returns:
Type: 
Object | null

getProvenance(key) → {Object|null}

Returns provenance metadata for a fact.

Parameters:
NameTypeDescription
keystring
Returns:
Type: 
Object | null

has(key) → {boolean}

Checks whether a fact exists (exact key, nested property, or namespace).

Parameters:
NameTypeDescription
keystring
Returns:
Type: 
boolean

keys() → {Array.<string>}

Returns an array of stored fact keys.

Returns:
Type: 
Array.<string>

offChange(unbindOrCallback)

Explicit unbind for a listener or unbind function.

Parameters:
NameTypeDescription
unbindOrCallbackfunction

onChange(patternOrCallback, maybeCallbackopt) → {function}

Registers a change listener with pattern filtering and clean unbind.

  • onChange(callback): global listener (key, newValue, oldValue, provenance)
  • onChange(pattern, callback): filtered listener (newValue, oldValue, provenance, key)
Parameters:
NameTypeAttributesDescription
patternOrCallbackstring | function
maybeCallbackfunction<optional>
Returns:

Unbind function

Type: 
function

restore(snapshot, optionsopt) → {this}

Restores state from a snapshot.

Parameters:
NameTypeAttributesDescription
snapshotobject
optionsobject<optional>
Returns:
Type: 
this

set(key, value, provenanceopt) → {this}

Sets a fact with provenance tracking.

Parameters:
NameTypeAttributesDefaultDescription
keystring
valueany
provenancestring | object<optional>
null
Returns:
Type: 
this

snapshot() → {Object}

Creates a deep-cloned, serializable snapshot for save games.

Returns:
Type: 
Object

toObject() → {Record.<string, any>}

Returns a plain object representation of all stored facts.

Returns:
Type: 
Record.<string, any>