Skip to content

Behavior Components ​

A Behavior Component is a reusable custom component authored as a project script. It uses the same registry, Inspector fields, Object Flow nodes, lifecycle, and runtime host as Opal's built-ins.

The high-level track starts with typed OpalScript (class Foo : Component). Use opal.component(...) when you want Inspector fields and Flow actions without types. Both attach from Add Component.

The workflow stays close to the object:

  1. Create or edit the definition in Scripts.
  2. Select an object in Arrange.
  3. Attach the component from the Inspector's Components card.
  4. Configure that object's field values.
  5. Use Edit Source on the attached component when you need to change its shared definition.

Create a Behavior Component ​

Open Scripts, choose New → Behavior Component, and edit the generated opal.component(...) source. The engine starter is a spinner:

js
export default opal.component("Spinner", {
  label: "Spinner",
  category: "Behaviors",
  fields: {
    speed: { type: "number", default: 90, label: "Speed (deg/sec)" },
  },
  onTick: { spin: "self.speed" },
});

Save & Apply. Spinner appears in the Inspector's Add Component menu. Attach it, press Play — the object turns. That is the same first recipe as the OpalScript spinner, in the untyped form.

Fields, actions, and events ​

A counter shows the rest of the declaration:

js
export default opal.component("VisitCounter", {
  label: "Visit Counter",
  category: "Gameplay",
  description: "Counts visits or interactions on the host object.",
  fields: {
    count: { type: "number", default: 0 },
  },
  events: { changed: {} },
  actions: {
    increment: {
      label: "Increment",
      params: { amount: { type: "number", default: 1 } },
      body: "self.count += params.amount; if (self.count < 0) self.count = 0; emit('changed');",
    },
    reset: {
      label: "Reset",
      body: "self.count = 0; emit('changed');",
    },
  },
  conditions: {
    atLeast: {
      label: "At Least",
      params: { target: { type: "number", default: 1 } },
      body: "self.count >= params.target",
    },
  },
});

Script Studio validates the source and keeps the last successfully compiled definition active when a new edit has an error.

Definition options ​

OptionPurpose
label, category, icon, descriptionIdentity and authoring UI
fieldsTyped, per-attachment values shown in the Inspector
eventsSignals the component can emit to Flow
actionsNamed operations exposed as Component Action nodes
conditionsNamed checks exposed as Component Condition nodes
requiresComponent IDs that should be attached first
onStart, onTick, onEndPlay lifecycle behavior

Field specs use the same types as built-ins, including number, boolean, string, enum, vector, color, objectRef, componentRef, assetRef, and eventKey. Add label, default, and (for numbers) min / max / step as needed.

Action and condition bodies ​

An action body can mutate fields, call sibling components, or emit declared events. Its available names include:

NameMeaning
selfThis attachment's field values
paramsValues passed by the caller or Flow node
statePrivate runtime scratch for this attachment
thingThe object that owns the component
get, run, checkRead, call, or query sibling components
emitFire a declared component event
source, target, eventCurrent event context when available

Condition bodies evaluate to a boolean.

Lifecycle behavior ​

HookRuns
onStartOnce when Play begins
onTickEvery frame during Play; dt is available
onEndOnce when Play stops

Lifecycle string bodies can use state for per-instance scratch during the current Play session. Common onTick object forms such as { spin: "self.speed" } and { drift: { x: "60", y: "0" } } expand to Opal's motion-safe helpers. String bodies can also use helpers.spin, helpers.moveBy, and angle conversion helpers.

Attach and edit instances ​

  1. Select an object in Arrange.
  2. Open the Inspector's Components card.
  3. Choose Add Component and search by label, category, or component ID.
  4. Edit the generated field controls on the attached card.

Those values belong to that object. Attaching the same Behavior Component to two objects gives each its own field values and runtime scratch state.

Use Edit Source on a script-authored component card to open its project script. Definition edits apply to every attachment after a successful compile; instance field values remain object-owned.

Use from Object Flow ​

Behavior Components extend the selected object's Flow catalog exactly like built-ins:

  • Actions become Component Action nodes.
  • Conditions become Component Condition nodes.
  • Declared events can start or feed rules.
  • Fields can be exposed to component value nodes and expressions according to their field spec.

Attach the component before authoring its object graph so its entries appear near the top of the catalog.

Persistence and identity ​

The source definition is stored once in the project's script records. Scenes do not store a separate custom-component definition list. Each object serializes only its attachment:

json
{
  "type": "spinner",
  "version": 1,
  "fields": {
    "speed": 90
  }
}

Component IDs are the link between definitions and attachments. Renaming an ID changes that identity, so update or reattach existing instances deliberately. Removing the source removes the registered custom type; clean up attachments that still reference it.