new UtilityAI()
UtilityAI component managing utility scoring, candidate action evaluation, deterministic tie-breaking, decision tracing, and action lifecycle cleanup.
- Source
Extends
Classes
Members
actions :Map.<string, UtilityAction>
- Map.<string, UtilityAction>
- Source
currentAction :UtilityAction|null
- UtilityAction |
null
- Source
lastInterruptedAction :Object|null
- Object |
null
- Source
(readonly) properties
The entity that this component is attached to.
- Inherited From
- Source
threshold
Current minimum score threshold to trigger an action.
- Source
threshold
- Source
Methods
clearTraces()
Clears all recorded decision traces.
- Source
deserialize(props)
Populates the component properties from a data object. Override this method for custom property handling.
| Name | Type | Description |
|---|---|---|
props | object | The properties object (usually from JSON). |
- Inherited From
- Source
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.
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
context | Object | <optional> | {} | Context data. |
- Source
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.
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
context | Object | <optional> | {} | Context data. |
- Source
Result object with chosenAction, score, executed, result, and evaluation.
- Type:
- Object
getAction(actionId) → {UtilityAction|null}
Retrieves an action by ID.
| Name | Type | Description |
|---|---|---|
actionId | string |
- Source
- Type:
- UtilityAction |
null
getActions() → {Array.<UtilityAction>}
Returns an array of all registered candidate actions.
- Source
- Type:
- Array.<UtilityAction>
getContext() → {Object}
Resolves the current context for evaluation.
- Source
- Type:
- Object
getDecisionTraces() → {Array.<Object>}
Returns a copy of recorded decision traces.
- Source
Array of decision traces.
- Type:
- Array.<Object>
getLastDecisionTrace() → {Object|null}
Returns the most recent decision trace, or null if empty.
- Source
- Type:
- Object |
null
interrupt(reasonopt, contextopt) → {boolean}
Explicitly interrupts the currently active action with cleanup.
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
reason | string | | <optional> | "interrupted" | Reason for interruption. |
context | Object | <optional> | {} | Context data. |
- Source
True if an active action was interrupted.
- Type:
- boolean
registerAction(action) → {UtilityAction}
Registers a candidate action.
| Name | Type | Description |
|---|---|---|
action | UtilityAction | | Action instance or configuration. |
- Source
Registered action instance.
- Type:
- UtilityAction
removeAction(actionId, contextopt) → {boolean}
Removes an action by identifier. Cleans up if currently active.
| Name | Type | Attributes | Description |
|---|---|---|---|
actionId | string | Identifier of action to remove. | |
context | Object | <optional> | Context for cleanup. |
- Source
True if removed.
- Type:
- boolean
update(deltaTimeopt, overrideContextopt) → {Object}
Updates the UtilityAI component for a game loop tick.
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
deltaTime | number | <optional> | 0 | Delta time in seconds. |
overrideContext | Object | <optional> | null | Optional context override. |
- Source
Result of evaluateAndExecute.
- Type:
- Object