UtilityAI

new UtilityAI()

UtilityAI component managing utility scoring, candidate action evaluation, deterministic tie-breaking, decision tracing, and action lifecycle cleanup.

Extends

Classes

UtilityAI

Members

actions :Map.<string, UtilityAction>

Type:

currentAction :UtilityAction|null

Type:

lastInterruptedAction :Object|null

Type:
  • Object | null

(readonly) properties

The entity that this component is attached to.

Inherited From

threshold

Current minimum score threshold to trigger an action.

threshold

Methods

clearTraces()

Clears all recorded decision traces.

deserialize(props)

Populates the component properties from a data object. Override this method for custom property handling.

Parameters:
NameTypeDescription
propsobject

The properties object (usually from JSON).

Inherited From

evaluate(contextopt) → {Object}

Evaluates all candidate actions against context and returns winning decision. Applies deterministic tie-breaking (priority then ID) and records a decision trace.

Parameters:
NameTypeAttributesDefaultDescription
contextObject<optional>
{}

Context data.

Returns:

Evaluation result containing chosenAction, score, reason, trace, and candidateScores.

Type: 
Object

evaluateAndExecute(contextopt) → {Object}

Evaluates candidates and executes the highest-scoring action. Cleans up superseded or active action states if interrupted or changed.

Parameters:
NameTypeAttributesDefaultDescription
contextObject<optional>
{}

Context data.

Returns:

Result object with chosenAction, score, executed, result, and evaluation.

Type: 
Object

getAction(actionId) → {UtilityAction|null}

Retrieves an action by ID.

Parameters:
NameTypeDescription
actionIdstring
Returns:
Type: 
UtilityAction | null

getActions() → {Array.<UtilityAction>}

Returns an array of all registered candidate actions.

Returns:
Type: 
Array.<UtilityAction>

getContext() → {Object}

Resolves the current context for evaluation.

Returns:
Type: 
Object

getDecisionTraces() → {Array.<Object>}

Returns a copy of recorded decision traces.

Returns:

Array of decision traces.

Type: 
Array.<Object>

getLastDecisionTrace() → {Object|null}

Returns the most recent decision trace, or null if empty.

Returns:
Type: 
Object | null

interrupt(reasonopt, contextopt) → {boolean}

Explicitly interrupts the currently active action with cleanup.

Parameters:
NameTypeAttributesDefaultDescription
reasonstring | Object<optional>
"interrupted"

Reason for interruption.

contextObject<optional>
{}

Context data.

Returns:

True if an active action was interrupted.

Type: 
boolean

registerAction(action) → {UtilityAction}

Registers a candidate action.

Parameters:
NameTypeDescription
actionUtilityAction | Object

Action instance or configuration.

Returns:

Registered action instance.

Type: 
UtilityAction

removeAction(actionId, contextopt) → {boolean}

Removes an action by identifier. Cleans up if currently active.

Parameters:
NameTypeAttributesDescription
actionIdstring

Identifier of action to remove.

contextObject<optional>

Context for cleanup.

Returns:

True if removed.

Type: 
boolean

update(deltaTimeopt, overrideContextopt) → {Object}

Updates the UtilityAI component for a game loop tick.

Parameters:
NameTypeAttributesDefaultDescription
deltaTimenumber<optional>
0

Delta time in seconds.

overrideContextObject<optional>
null

Optional context override.

Returns:

Result of evaluateAndExecute.

Type: 
Object