Heroic Lands

Class SohlActionContext<S>

The execution context passed to every SoHL action.

Every intrinsic action — the methods discovered via sohl.core.logic.SohlLogic.getContextOptions and dispatched through the action system — receives a SohlActionContext. It bundles the four things an action needs to know to run and report its result:

  • who is acting — the sohl.core.logic.SohlSpeaker (speaker), resolved from a token/actor/user and used as the chat-message speaker;
  • what is being acted upon — the target token, if any (a raw Token, a SohlTokenDocument, or a SohlActor is normalized to the actor's first active token);
  • how to run — skipDialog (bypass the action's configuration dialog) and noChat (suppress the chat-card output);
  • action-specific input/output — type and title for labelling, plus a generic scope bag (S) that carries arbitrary per-action data (selected options, intermediate results) through the call.

The context is a runtime value, not a persisted entity: it is built fresh at every action dispatch and never revived from its own JSON. Only its scope crosses the client boundary — carried in the chat-card data-* attributes and rehydrated per-payload by the result machinery. clone produces a modified copy so an action can fork the context (e.g. to retarget or adjust scope) without mutating the original.

Example

// Build a context naming who is acting, then run an action with it.
const ctx = new SohlActionContext({ speaker: actor.getSpeaker() });
await action.execute(ctx);

Example

// Fork a received context to retarget it, leaving the original untouched.
const retargeted = context.clone({ target: someToken });

Example

// Build a context naming who is acting, then run an action with it.
const ctx = new SohlActionContext({ speaker: actor.getSpeaker() });
await action.execute(ctx);

Example

// Fork a received context to retarget it, leaving the original untouched.
const retargeted = context.clone({ target: someToken });

Type Parameters

  • S extends UnknownObject = UnknownObject

    Shape of the scope payload for this action.

Constructors

constructor

Properties

noChat scope skipDialog speaker target? thisLogic? title type

Accessors

character token

Methods

clone

Constructors

constructor

  • new SohlActionContext<S extends object = object>(
        data?: Partial<sohl.entity.action.SohlActionContext.Data<S>>,
    ): sohl.entity.action.SohlActionContext<S>

  • Build a context from SohlActionContext.Data.

    The speaker is required: a sohl.core.logic.SohlSpeaker is used directly, while a plain data object is wrapped in one. A target given as a Token, TokenDocument, or Actor is normalized to a SohlTokenDocument (for an actor, its first active token).

    Type Parameters

    • S extends object = object

    Parameters

    • data: Partial<sohl.entity.action.SohlActionContext.Data<S>> = {}

      Initial context values; all but speaker are optional.

      • speaker

        The speaker who initiated this action (required). A plain data object is automatically wrapped in a sohl.core.logic.SohlSpeaker.

      • target

        The token or actor that is the action's target; normalized to a SohlTokenDocument. Defaults to null.

      • skipDialog

        When true, bypass any interactive dialog and use values from scope directly. Defaults to false.

      • noChat

        When true, suppress the resulting chat card. Defaults to false.

      • type

        A string type label for the action. Defaults to "".

      • title

        A human-readable title for the action dialog/card. Defaults to "".

      • scope

        Action-specific scope values (e.g. modifiers, results). Defaults to {}.

    Returns sohl.entity.action.SohlActionContext<S>

    Throws

    Error if no speaker is provided, or if target is neither a token nor an actor.

Properties

noChat

noChat: boolean

When true, suppress chat-card output for the action.

scope

scope: S

Arbitrary per-action payload carried through execution.

skipDialog

skipDialog: boolean

When true, skip the action's configuration dialog and use defaults.

speaker

speaker: sohl.core.logic.SohlSpeaker

Who is performing the action (resolved chat-message speaker).

Optionaltarget

target?: SohlTokenDocumentLogic

The token being acted upon, or undefined when the action has no target.

OptionalthisLogic

thisLogic?: SohlLogic<any>

The Logic of the document on which this action is running — the stand-in for the this pointer inside a Script Action's macro (whose real this is the Foundry Macro, not the Logic). Every executor, intrinsic method or macro, receives the same single ctx; the macro reaches the intrinsic it overrides through this handle: ctx.thisLogic.<executor>(ctx). Stamped by sohl.entity.action.SohlAction.execute at dispatch.

title

title: string

Human-readable title used in dialogs and chat cards.

type

type: string

Action type discriminator (e.g. the action name).

Accessors

character

token

Methods

clone

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods