Members

(constant) ABILITY_NODE_VOCABULARY

Fixed node vocabulary supported by the Larissa ability composition runtime.

(constant) ARCHETYPES

Built-in archetype profiles with configured perception and memory budgets.

(constant) AUTHORED_UI_VERSION

Small, declarative HTML UI layer for scene data. This is intentionally a safe subset: no HTML strings, CSS strings, scripts, or arbitrary URLs.

(constant) BUILTIN_MATERIALS

Standard built-in material definitions.

(constant) CollisionLayers

Built-in standard collision layer flags for 2D bitmask filtering.

(constant) EQUIPMENT_SLOTS :Array.<string>

Designated equipment slots supported by the equipment system.

Type:
  • Array.<string>

(constant) FACTION_DISPOSITION

Standard faction dispositions.

(constant) FALLBACK_MATERIAL

Fallback material used when an unknown material is queried.

(constant) InteractionType

Interaction types applicable to materials.

(constant) MaterialState

Standard material interaction states.

(constant) ROUTINE_ACTIVITIES

Standard routine activity types supported by NPC schedules.

(constant) SEMANTIC_LAYER_TYPES

Standard semantic tile types for world definitions

(constant) UtilityCurves

Common normalized consideration curve functions mapping [0, 1] input to [0, 1] output.

Methods

applyEffects(effects, facts)

Applies consequences/effects to WorldFacts.

Parameters:
NameTypeDescription
effectsObject | Array | function
factsWorldFacts

assertResourceReference()

Validate a serialized resource reference without checking the filesystem.

boxColliderToCollider()

Adapt the engine's legacy BoxCollider dimensions to Nereid's overlap contract.

canLayersCollide(layerA, maskA, layerB, maskB, optionsopt) → {boolean}

Checks whether two collision layers/masks match according to symmetric or asymmetric rules. In symmetric mode, both A must mask B and B must mask A. In asymmetric mode, evaluates whether candidate A detects candidate B: (maskA & layerB) !== 0.

Parameters:
NameTypeAttributesDescription
layerAnumber
maskAnumber
layerBnumber
maskBnumber
optionsObject<optional>
Properties
NameTypeAttributesDefaultDescription
symmetricboolean<optional>
true
Returns:
Type: 
boolean

clamp01(value) → {number}

Clamps a number to the [0, 1] range.

Parameters:
NameTypeDescription
valuenumber

Numeric value to clamp.

Returns:

Clamped value between 0 and 1.

Type: 
number

collectRenderableRoots()

Collect top-level renderables, descending through non-renderable layer entities.

createCollisionMask(…layers) → {number}

Create a bitmask from multiple layer bit flags.

Parameters:
NameTypeAttributesDescription
layersnumber<repeatable>
Returns:
Type: 
number

createDefaultActions(optionsopt) → {Array.<UtilityAction>}

Creates built-in candidate action templates: attack, flee, heal, patrol, rest.

Parameters:
NameTypeAttributesDescription
optionsObject<optional>

Optional overrides.

Returns:

Array of candidate actions.

Type: 
Array.<UtilityAction>

createHTMLUIClient()

Build the browser-side HTML UI client, exposing only explicitly allowed actions.

createRPGSnapshot(context) → {Object}

Helper to create a unified snapshot for inventory, equipment, and currency.

Parameters:
NameTypeDescription
contextObject
Returns:
Type: 
Object

createUIBridge(options) → {Object}

Create a typed, serializable event bridge between the game runtime and an HTML UI. Events use { type: 'neptune:ui', version: 1, direction, name, payload }.

Parameters:
NameTypeDescription
optionsobject
Properties
NameTypeAttributesDescription
windowWindow<optional>

Window-like message target (defaults to globalThis.window).

parentWindow<optional>

Parent window accepted for incoming parent messages.

originstring<optional>

Exact allowed parent origin; defaults to current origin.

targetOriginstring<optional>

Exact destination origin; defaults to origin.

actionsArray.<string><optional>

Allowed UI-to-engine action names.

Returns:
Type: 
Object

deepFreeze(value) → {Object}

Deep-freeze a plain object or array to ensure immutability.

Parameters:
NameTypeDescription
valueObject
Returns:
Type: 
Object

detectContradictions(conditions) → {Array.<{fact: string, message: string}>}

Detects logical contradictions in a set of conditions.

Parameters:
NameTypeDescription
conditionsArray | Object
Returns:
Type: 
Array.<{fact: string, message: string}>

evaluateConditions(conditions, facts, contextopt) → {boolean}

Evaluates conditions against WorldFacts. Supports single condition or array (AND).

Parameters:
NameTypeAttributesDescription
conditionsObject | Array | function
factsWorldFacts
contextObject<optional>
Returns:
Type: 
boolean

evaluateSingleCondition(condition, facts, contextopt) → {boolean}

Evaluates a single condition against WorldFacts.

Parameters:
NameTypeAttributesDefaultDescription
conditionObject | function
factsWorldFacts
contextObject<optional>
null
Returns:
Type: 
boolean

exponential(x, exponentopt) → {number}

Exponential response: f(x) = x^exponent.

Parameters:
NameTypeAttributesDefaultDescription
xnumber

Normalized input.

exponentnumber<optional>
2

Power exponent.

Returns:
Type: 
number

extractCanHeal(context) → {boolean}

Checks whether healing resource is available.

Parameters:
NameTypeDescription
contextObject

Game context.

Returns:

True if healing resource or ability is available.

Type: 
boolean

extractDangerLevel(context) → {number}

Safely extracts danger/threat level (0..1) from context.

Parameters:
NameTypeDescription
contextObject

Game context.

Returns:

Danger level between 0 and 1.

Type: 
number

extractFacing(obj) → {number}

Safely extracts facing angle in radians from an observer.

Parameters:
NameTypeDescription
objObject
Returns:
Type: 
number

extractHealthFraction(context) → {number}

Safely extracts normalized health fraction (0..1) from context.

Parameters:
NameTypeDescription
contextObject

Game context.

Returns:

Health fraction between 0 and 1.

Type: 
number

extractPosition(obj) → {Object|null}

Safely extracts a 2D coordinate from an object, component, or entity.

Parameters:
NameTypeDescription
objObject
Returns:
Type: 
Object | null

extractRangeScore(context) → {number}

Safely extracts target range suitability score (0..1).

Parameters:
NameTypeDescription
contextObject

Game context.

Returns:

Range score between 0 and 1.

Type: 
number

extractStaminaFraction(context) → {number}

Safely extracts stamina/energy fraction (0..1) from context.

Parameters:
NameTypeDescription
contextObject

Game context.

Returns:

Stamina fraction between 0 and 1.

Type: 
number

finiteNumber(value, name) → {number}

Validates finite number.

Parameters:
NameTypeDescription
valuenumber
namestring
Returns:
Type: 
number

finiteNumber(value, name, minopt) → {number}

Validates that a value is a finite number greater than or equal to a minimum.

Parameters:
NameTypeAttributesDefaultDescription
valuenumber
namestring
minnumber<optional>
0
Returns:
Type: 
number

finiteNumber(value, name) → {number}

Validates finite number.

Parameters:
NameTypeDescription
valuenumber
namestring
Returns:
Type: 
number

finiteNumber(value, name) → {number}

Validates finite number.

Parameters:
NameTypeDescription
valuenumber
namestring
Returns:
Type: 
number

finiteNumber(value, name, minopt) → {number}

Validates finite number.

Parameters:
NameTypeAttributesDefaultDescription
valuenumber
namestring
minnumber<optional>
0
Returns:
Type: 
number

getActorPosition(actor) → {Object}

Helper to get 2D position from an actor or position object.

Parameters:
NameTypeDescription
actorObject
Returns:
Type: 
Object

getNested(obj, parts) → {any}

Safely traverses an object along path segments.

Parameters:
NameTypeDescription
objobject
partsArray.<string>
Returns:
Type: 
any

getNode(abilityDef, nodeId) → {Object|null}

Lookup a node in ability definition nodes by id. Supports both Map/Object map and Array schemas.

Parameters:
NameTypeDescription
abilityDefObject
nodeIdstring
Returns:
Type: 
Object | null

getOutgoingEdges(node) → {Array.<{targetId: string, field: string}>}

Returns all outgoing reference edges from a node for flow & cycle tracking.

Parameters:
NameTypeDescription
nodeObject
Returns:
Type: 
Array.<{targetId: string, field: string}>

getPointKey(point) → {string|null}

Derives a string identifier for a destination point or object.

Parameters:
NameTypeDescription
pointObject | string | number

Destination point.

Returns:

String key or null if invalid.

Type: 
string | null

getResourceReferenceTarget()

Return the usable string target from a serialized reference.

installHTMLUI()

Create a ready-to-use window.neptuneUI client for an embedded HTML interface.

installUINavigation(root, options) → {function}

Attach focus-based keyboard/controller navigation to a UI root. The injected adapter can translate gamepad buttons to the same directional commands.

Parameters:
NameTypeDescription
rootElement
optionsObject

Navigation callbacks and optional controller adapter.

Returns:

cleanup callback

Type: 
function

inverseLinear(x) → {number}

Inverse linear response: f(x) = 1 - x.

Parameters:
NameTypeDescription
xnumber

Normalized input.

Returns:
Type: 
number

inverseQuadratic(x) → {number}

Inverse quadratic response: f(x) = (1 - x)^2.

Parameters:
NameTypeDescription
xnumber

Normalized input.

Returns:
Type: 
number

inverseStep(x, thresholdopt) → {number}

Inverse binary step threshold response: 1 if x < threshold, else 0.

Parameters:
NameTypeAttributesDefaultDescription
xnumber

Normalized input.

thresholdnumber<optional>
0.5

Cutoff threshold.

Returns:
Type: 
number

isActorAlive(actor) → {boolean}

Helper to check whether an actor is alive.

Parameters:
NameTypeDescription
actorObject
Returns:
Type: 
boolean

isDestroyed(entity) → {boolean}

Determines whether an entity has been destroyed or flagged as dead.

Parameters:
NameTypeDescription
entityObject
Returns:
Type: 
boolean

isEntityActive()

Whether this entity and every ancestor are enabled for runtime processing.

isHourInSlot(hour, start, end) → {boolean}

Checks whether a given hour falls inside a slot with optional midnight wraparound.

Parameters:
NameTypeDescription
hournumber

Hour to test [0, 24).

startnumber

Slot start hour [0, 24).

endnumber

Slot end hour [0, 24).

Returns:

True if the hour falls within the slot interval.

Type: 
boolean

isValidEquipmentSlot(slot) → {boolean}

Validate that an equipment slot name is one of the designated slots.

Parameters:
NameTypeDescription
slotstring
Returns:
Type: 
boolean

linear(x) → {number}

Linear identity response: f(x) = x.

Parameters:
NameTypeDescription
xnumber

Normalized input.

Returns:
Type: 
number

logistic(x, steepnessopt, midpointopt) → {number}

Logistic (sigmoidal) S-curve response.

Parameters:
NameTypeAttributesDefaultDescription
xnumber

Normalized input.

steepnessnumber<optional>
10

Curve steepness factor.

midpointnumber<optional>
0.5

Inflection midpoint.

Returns:
Type: 
number

matchesPattern(pattern, key) → {boolean}

Matches a key against a pattern with wildcard support.

Parameters:
NameTypeDescription
patternstring | null
keystring
Returns:
Type: 
boolean

mountAuthoredUI()

Mount versioned authored UI. Preview mode never runs gameplay actions.

nonEmptyString(value, name) → {string}

Validates non-empty string.

Parameters:
NameTypeDescription
valuestring
namestring
Returns:
Type: 
string

nonEmptyString(value, name) → {string}

Validates that a value is a non-empty string.

Parameters:
NameTypeDescription
valuestring
namestring
Returns:
Type: 
string

nonEmptyString(value, name) → {string}

Validates non-empty string.

Parameters:
NameTypeDescription
valuestring
namestring
Returns:
Type: 
string

normalizeAngle(angle) → {number}

Helper to normalize an angle between -PI and PI.

Parameters:
NameTypeDescription
anglenumber
Returns:
Type: 
number

normalizeAngle(rad) → {number}

Normalize an angle into [-PI, PI].

Parameters:
NameTypeDescription
radnumber
Returns:
Type: 
number

normalizeCellData(data, defaults) → {object}

Normalizes cell coordinates and data.

Parameters:
NameTypeDescription
datastring | object

Material ID or partial cell data.

defaultsobject

Default configuration values.

Returns:

Normalized cell state object.

Type: 
object

normalizeProvenance(provenance) → {Object}

Normalizes provenance metadata.

Parameters:
NameTypeDescription
provenancestring | object | null
Returns:
Type: 
Object

parseHour(time) → {number}

Normalizes and parses a game hour into a 24-hour float [0, 24). Supports numbers, strings like "14:30" or "06:00", or GameClock instances.

Parameters:
NameTypeDescription
timenumber | string | Object

The time value to parse.

Returns:

Normalized hour from 0 up to (exclusive) 24.

Type: 
number

quadratic(x) → {number}

Quadratic response (accelerating / ease-in): f(x) = x^2.

Parameters:
NameTypeDescription
xnumber

Normalized input.

Returns:
Type: 
number

rayIntersectsObstacle(p1, p2, obstacle) → {boolean}

Checks whether a line segment from p1 to p2 intersects an obstacle.

Parameters:
NameTypeDescription
p1Object
p2Object
obstacleObject
Returns:
Type: 
boolean

restoreRPGSnapshot(snapshot, context) → {boolean}

Helper to restore a unified snapshot for inventory, equipment, and currency.

Parameters:
NameTypeDescription
snapshotObject
contextObject
Returns:
Type: 
boolean

segmentIntersectsAABB(p1, p2, left, top, right, bottom) → {boolean}

Tests ray segment intersection against an axis-aligned bounding box.

Parameters:
NameTypeDescription
p1Object
p2Object
leftnumber
topnumber
rightnumber
bottomnumber
Returns:
Type: 
boolean

segmentIntersectsCircle(p1, p2, cx, cy, radius) → {boolean}

Tests ray segment intersection against a circle obstacle.

Parameters:
NameTypeDescription
p1Object
p2Object
cxnumber
cynumber
radiusnumber
Returns:
Type: 
boolean

segmentIntersectsSegment(p1, p2, p3, p4) → {boolean}

Tests 2D line segment intersection.

Parameters:
NameTypeDescription
p1Object
p2Object
p3Object
p4Object
Returns:
Type: 
boolean

setNested(obj, parts, value)

Sets a nested property on an object, creating intermediate objects as needed.

Parameters:
NameTypeDescription
objobject
partsArray.<string>
valueany

smoothstep(x) → {number}

Smoothstep curve (Hermite interpolation): f(x) = 3x^2 - 2x^3.

Parameters:
NameTypeDescription
xnumber

Normalized input.

Returns:
Type: 
number

sortRenderables()

Stable scene-local sort: finite renderOrder first, then original traversal order.

step(x, thresholdopt) → {number}

Binary step threshold response: 1 if x >= threshold, else 0.

Parameters:
NameTypeAttributesDefaultDescription
xnumber

Normalized input.

thresholdnumber<optional>
0.5

Activation threshold.

Returns:
Type: 
number

validateMaterialDefinition(id, def) → {object}

Validates a material definition object.

Parameters:
NameTypeDescription
idstring

The material ID.

defobject

The material definition.

Returns:

Normalized and frozen material definition.

Type: 
object

validateSceneResourceReferences()

Validate resource references in a serialized scene before instantiation.

Type Definitions

Item

Item definition.

Type:
  • Object
Properties
NameTypeDescription
idstring

Unique item ID.

namestring

Display name.

typestring

Item type (consumable, weapon, armor, key).

valuenumber

Sell value.

statsObject

Stat modifiers when equipped.

stackablenumber

Max stack size (1 for non-stackable).