Skip to content

sweetbean.stimulus.Foraging

Foraging

Bases: _BaseStimulus

Visual Foraging stimulus (wraps @sweet-jspsych/plugin-foraging)

Arrays-only API
  • targets: list[ItemSpec]
  • distractors: list[ItemSpec]

ItemSpec fields (each item defines ONE of {html|text|shape|src}, plus options): - html: str - text: str - shape: Literal["circle","square","triangle"] - src: str - color: str # overrides overlay_pool sampling - rotationDeg: int # overrides rotation_pool sampling - pos: dict # {mode:"abs"|"grid"|"circle", ...} - size: str # e.g., "12vmin" - fontSize: str - id: str - attrs: dict[str,str]

Notes
  • By default, randomized non-overlapping placement in a centered square arena.
  • Trial ends when all targets found unless you change end_when_found=False or set an explicit trial_duration.
Source code in sweetbean/stimulus/Foraging.py
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
class Foraging(_BaseStimulus):
    """
    Visual Foraging stimulus (wraps @sweet-jspsych/plugin-foraging)

    Arrays-only API:
      - targets:     list[ItemSpec]
      - distractors: list[ItemSpec]

    ItemSpec fields (each item defines ONE of {html|text|shape|src}, plus options):
      - html: str
      - text: str
      - shape: Literal["circle","square","triangle"]
      - src: str
      - color: str                      # overrides overlay_pool sampling
      - rotationDeg: int                # overrides rotation_pool sampling
      - pos: dict                       # {mode:"abs"|"grid"|"circle", ...}
      - size: str                       # e.g., "12vmin"
      - fontSize: str
      - id: str
      - attrs: dict[str,str]

    Notes:
      - By default, randomized non-overlapping placement in a centered square arena.
      - Trial ends when all targets found unless you change `end_when_found=False`
        or set an explicit `trial_duration`.
    """

    # IMPORTANT: For SweetBean, keep a string "type" so SweetBean emits
    # a declarative config object. The browser bundle must set window.jsPsychForaging.
    type = "jsPsychForaging"

    def __init__(
        self,
        # Required-ish (can be empty)
        targets: Optional[Union[List[Dict[str, Any]], TimelineVariable]] = None,
        distractors: Optional[Union[List[Dict[str, Any]], TimelineVariable]] = None,
        # Layout & placement
        position_mode: str = "random",  # "random" | "grid" | "circle"
        grid_cols: Optional[int] = None,
        grid_rows: Optional[int] = None,
        ring_radius_vmin: float = 30,
        randomize_positions: bool = True,  # grid/circle only
        # Arena & spacing
        arena_size_vmin: float = 92,  # centered square side (vmin)
        placement_inset_vmin: float = 6,  # inner margin
        min_gap_vmin: float = 2.5,  # extra pairwise gap
        # Visuals
        background: str = "#000000",  # default black
        color: str = "#ffffff",  # default foreground (text/border)
        token_box_size: str = "12vmin",
        token_font_size: str = "10vmin",
        # Pools (defaults are in the plugin too; pass to control sampling)
        overlay_pool: Optional[List[str]] = None,
        rotation_pool: Optional[List[int]] = None,
        # Timing & control
        trial_duration: Optional[
            int
        ] = None,  # None => ends when all targets found (if end_when_found=True)
        end_when_found: bool = True,
        response_ends_trial: bool = False,
        # Determinism
        seed: Optional[int] = None,
        # Feedback
        show_star_feedback: bool = False,  # OFF by default
        star_color: str = "#f6b500",
        # Hooks / triggers
        # Example: {"on_all_targets_collected": "end_trial"}
        triggers: Optional[Dict[str, Any]] = None,
        # SweetBean convenience
        duration: Optional[int] = None,  # mirrors RSVP: alias for trial_duration
        side_effects: Optional[Dict[str, Any]] = None,
    ):
        """
        Arguments:
            targets (list[dict] | TimelineVariable | None):
                Trial’s target items. Accepts a concrete list or a TimelineVariable
                that evaluates per trial to a list. Each item is an ItemSpec dict
                that defines exactly ONE of {html | text | shape | src} plus
                optional styling/placement fields:

                  Content (choose exactly one)
                  - html (str): Raw HTML.
                  - text (str): Plain text (rendered in a token box).
                  - shape (str): One of "circle", "square", "triangle".
                  - src (str): Image URL/path.

                  Optional appearance/identity
                  - color (str): CSS color; overrides overlay_pool sampling.
                  - rotationDeg (int): Rotation in degrees; overrides rotation_pool.
                  - size (str): CSS size of the token box (e.g., "12vmin").
                  - fontSize (str): For text content (e.g., "10vmin").
                  - id (str): Opaque label copied to data.
                  - attrs (dict[str,str]): Arbitrary HTML attributes.

                  Placement override (optional; else global placement rules apply)
                  - pos (dict): One of the following shapes:
                        {"mode": "abs", "x_vmin": <float>, "y_vmin": <float>}
                        {"mode": "grid", "row": <int>, "col": <int>}
                        {"mode": "circle", "angle_deg": <float>, "radius_vmin": <float>}

            distractors (list[dict] | TimelineVariable | None):
                Same ItemSpec structure as `targets`. May be empty.

            position_mode (str):
                Global placement policy when items don’t provide an explicit `pos`.
                One of "random" | "grid" | "circle". Default "random".
            grid_cols (int | None):
                Number of columns for "grid" placement. If None, inferred from count.
            grid_rows (int | None):
                Number of rows for "grid" placement. If None, inferred from count.
            ring_radius_vmin (float):
                Ring radius for "circle" placement, in vmin units. Default 30.
            randomize_positions (bool):
                If True, jitter positions within the grid cell / along the ring for
                "grid"/"circle" modes. Default True.

            arena_size_vmin (float):
                Side length (vmin) of the centered square arena. Default 92.
            placement_inset_vmin (float):
                Inner safety margin from arena edges. Default 6.
            min_gap_vmin (float):
                Extra minimum pairwise spacing between item centers. Default 2.5.

            background (str):
                Arena background color. Default "#000000".
            color (str):
                Default foreground color (text/borders). Default "#ffffff".
            token_box_size (str):
                Default token box size (CSS). Default "12vmin".
            token_font_size (str):
                Default font size for text tokens (CSS). Default "10vmin".

            overlay_pool (list[str] | None):
                Optional pool of overlay symbols/colors; sampled per item unless the
                ItemSpec provides an explicit `color`. Omit/None to use plugin defaults.
            rotation_pool (list[int] | None):
                Optional pool of rotations in degrees; sampled per item unless the
                ItemSpec provides `rotationDeg`. Omit/None to use plugin defaults.

            trial_duration (int | None):
                Hard timeout in ms. If None and `end_when_found=True`, the trial ends
                when all targets are collected. Default None.
            end_when_found (bool):
                If True, automatically end the trial once all targets are found.
                Default True.
            response_ends_trial (bool):
                If True, any user interaction that counts as a response ends the trial,
                even if not all targets are collected. Default False.

            seed (int | None):
                Seed for deterministic placement/sampling. Default None.

            show_star_feedback (bool):
                If True, briefly show a star animation on successful target clicks.
                Default False.
            star_color (str):
                Star feedback color. Default "#f6b500".

            triggers (dict | None):
                Optional event→action mapping, e.g.,
                {"on_all_targets_collected": "end_trial"}.
                Default: {"on_all_targets_collected": "end_trial"}.

            duration (int | None):
                SweetBean convenience alias mirrored to `trial_duration` during build
                (consistent with RSVP). If provided, `trial_duration` is set to this
                value. Default None.
            side_effects: Optional side-effect configuration passed to the runtime. This expects
                a list of SideEffect definitions (see SweetBean docs) which can be
                used to update global data like overall score or trial counter.

        Emits (added to jsPsych data):
            - clicks (list[dict]): Raw click events ({kind, index, id?, t}).
            - n_targets (int): Number of target items in the trial.
            - n_collected (int): Number of targets collected.
            - tps (list[number]): Timestamps for target pickups.
            - bean_clicks (list[dict]): Mirror of `clicks`.
            - bean_n_targets (int): Mirror of `n_targets`.
            - bean_n_found (int): Mirror of `n_collected`.
            - bean_tps (list[number]): Mirror of `tps`.
            - bean_all_found (bool): Convenience flag (n_collected >= n_targets).

        Notes:
            - Provide item-level `pos` to bypass global placement for specific items.
            - If both `duration` and `trial_duration` are given, `duration` takes
              precedence by being copied into `trial_duration`.
            - Null/None optionals are dropped so the plugin falls back to its defaults.

        Example:
            from sweetbean import Block, Experiment
            from sweetbean.variable import TimelineVariable

            timeline = [
                {
                    "targets": [
                        {"text": "T", "color": "#66ff66"},
                        {"shape": "circle", "color": "#66ff66"},
                    ],
                    "distractors": [
                        {"text": "L", "color": "#ff6666"},
                        {"shape": "square", "color": "#ff6666"},
                        {"shape": "triangle", "color": "#ff6666"},
                    ],
                }
            ]

            stim = Foraging(
                targets=TimelineVariable("targets"),
                distractors=TimelineVariable("distractors"),
                position_mode="grid",
                grid_cols=6, grid_rows=4,
                arena_size_vmin=90, min_gap_vmin=2.5,
                background="#000000", color="#ffffff",
                token_box_size="10vmin", token_font_size="8vmin",
                end_when_found=True, response_ends_trial=False,
                show_star_feedback=True, star_color="#f6b500",
            )

            block = Block([stim], timeline=timeline)
            Experiment([block]).to_html("foraging.html")
        """

        if targets is None:
            targets = []
        if distractors is None:
            distractors = []
        if triggers is None:
            triggers = {"on_all_targets_collected": "end_trial"}

        super().__init__(locals(), side_effects)

    # ---- SweetBean hooks ----

    def _add_special_param(self):
        # Use SweetBean `duration` as jsPsych `trial_duration` (consistent with RSVP).
        if self.arg_js.get("duration") not in (None, "null"):
            self.arg_js["trial_duration"] = self.arg_js["duration"]

        # If user didn’t specify pools, omit them; plugin will fall back to its defaults.
        if not self.arg_js.get("overlay_pool"):
            self.arg_js.pop("overlay_pool", None)
        if not self.arg_js.get("rotation_pool"):
            self.arg_js.pop("rotation_pool", None)

        # Keep `type` as string so SweetBean emits declarative config
        self.arg_js["type"] = self.type

    def _process_response(self):
        # Convenience mirrors (prefixed with bean_)
        # clicks is already an array of {kind,index,id?,t}
        self.js_data += 'data["bean_clicks"] = data["clicks"];'
        self.js_data += 'data["bean_n_targets"] = data["n_targets"];'
        self.js_data += 'data["bean_n_found"] = data["n_collected"];'
        self.js_data += 'data["bean_tps"] = data["tps"];'
        # quick all-found boolean
        self.js_data += (
            'data["bean_all_found"] = (data["n_collected"] >= data["n_targets"]);'
        )

    def _set_before(self):
        # No extra on_load code required; SweetBean preamble already sets document bg.
        pass

    # Language mode not supported (same as RSVP)
    def process_l(self, prompts, get_input, multi_turn, datum=None):
        raise NotImplementedError

__init__(targets=None, distractors=None, position_mode='random', grid_cols=None, grid_rows=None, ring_radius_vmin=30, randomize_positions=True, arena_size_vmin=92, placement_inset_vmin=6, min_gap_vmin=2.5, background='#000000', color='#ffffff', token_box_size='12vmin', token_font_size='10vmin', overlay_pool=None, rotation_pool=None, trial_duration=None, end_when_found=True, response_ends_trial=False, seed=None, show_star_feedback=False, star_color='#f6b500', triggers=None, duration=None, side_effects=None)

Parameters:

Name Type Description Default
targets list[dict] | TimelineVariable | None

Trial’s target items. Accepts a concrete list or a TimelineVariable that evaluates per trial to a list. Each item is an ItemSpec dict that defines exactly ONE of {html | text | shape | src} plus optional styling/placement fields:

Content (choose exactly one) - html (str): Raw HTML. - text (str): Plain text (rendered in a token box). - shape (str): One of "circle", "square", "triangle". - src (str): Image URL/path.

Optional appearance/identity - color (str): CSS color; overrides overlay_pool sampling. - rotationDeg (int): Rotation in degrees; overrides rotation_pool. - size (str): CSS size of the token box (e.g., "12vmin"). - fontSize (str): For text content (e.g., "10vmin"). - id (str): Opaque label copied to data. - attrs (dict[str,str]): Arbitrary HTML attributes.

Placement override (optional; else global placement rules apply) - pos (dict): One of the following shapes: {"mode": "abs", "x_vmin": , "y_vmin": } {"mode": "grid", "row": , "col": }

None
distractors list[dict] | TimelineVariable | None

Same ItemSpec structure as targets. May be empty.

None
position_mode str

Global placement policy when items don’t provide an explicit pos. One of "random" | "grid" | "circle". Default "random".

'random'
grid_cols int | None

Number of columns for "grid" placement. If None, inferred from count.

None
grid_rows int | None

Number of rows for "grid" placement. If None, inferred from count.

None
ring_radius_vmin float

Ring radius for "circle" placement, in vmin units. Default 30.

30
randomize_positions bool

If True, jitter positions within the grid cell / along the ring for "grid"/"circle" modes. Default True.

True
arena_size_vmin float

Side length (vmin) of the centered square arena. Default 92.

92
placement_inset_vmin float

Inner safety margin from arena edges. Default 6.

6
min_gap_vmin float

Extra minimum pairwise spacing between item centers. Default 2.5.

2.5
background str

Arena background color. Default "#000000".

'#000000'
color str

Default foreground color (text/borders). Default "#ffffff".

'#ffffff'
token_box_size str

Default token box size (CSS). Default "12vmin".

'12vmin'
token_font_size str

Default font size for text tokens (CSS). Default "10vmin".

'10vmin'
overlay_pool list[str] | None

Optional pool of overlay symbols/colors; sampled per item unless the ItemSpec provides an explicit color. Omit/None to use plugin defaults.

None
rotation_pool list[int] | None

Optional pool of rotations in degrees; sampled per item unless the ItemSpec provides rotationDeg. Omit/None to use plugin defaults.

None
trial_duration int | None

Hard timeout in ms. If None and end_when_found=True, the trial ends when all targets are collected. Default None.

None
end_when_found bool

If True, automatically end the trial once all targets are found. Default True.

True
response_ends_trial bool

If True, any user interaction that counts as a response ends the trial, even if not all targets are collected. Default False.

False
seed int | None

Seed for deterministic placement/sampling. Default None.

None
show_star_feedback bool

If True, briefly show a star animation on successful target clicks. Default False.

False
star_color str

Star feedback color. Default "#f6b500".

'#f6b500'
triggers dict | None

Optional event→action mapping, e.g., {"on_all_targets_collected": "end_trial"}. Default: {"on_all_targets_collected": "end_trial"}.

None
duration int | None

SweetBean convenience alias mirrored to trial_duration during build (consistent with RSVP). If provided, trial_duration is set to this value. Default None.

None
side_effects Optional[Dict[str, Any]]

Optional side-effect configuration passed to the runtime. This expects a list of SideEffect definitions (see SweetBean docs) which can be used to update global data like overall score or trial counter.

None

Emits (added to jsPsych data): - clicks (list[dict]): Raw click events ({kind, index, id?, t}). - n_targets (int): Number of target items in the trial. - n_collected (int): Number of targets collected. - tps (list[number]): Timestamps for target pickups. - bean_clicks (list[dict]): Mirror of clicks. - bean_n_targets (int): Mirror of n_targets. - bean_n_found (int): Mirror of n_collected. - bean_tps (list[number]): Mirror of tps. - bean_all_found (bool): Convenience flag (n_collected >= n_targets).

Notes
  • Provide item-level pos to bypass global placement for specific items.
  • If both duration and trial_duration are given, duration takes precedence by being copied into trial_duration.
  • Null/None optionals are dropped so the plugin falls back to its defaults.
Example

from sweetbean import Block, Experiment from sweetbean.variable import TimelineVariable

timeline = [ { "targets": [ {"text": "T", "color": "#66ff66"}, {"shape": "circle", "color": "#66ff66"}, ], "distractors": [ {"text": "L", "color": "#ff6666"}, {"shape": "square", "color": "#ff6666"}, {"shape": "triangle", "color": "#ff6666"}, ], } ]

stim = Foraging( targets=TimelineVariable("targets"), distractors=TimelineVariable("distractors"), position_mode="grid", grid_cols=6, grid_rows=4, arena_size_vmin=90, min_gap_vmin=2.5, background="#000000", color="#ffffff", token_box_size="10vmin", token_font_size="8vmin", end_when_found=True, response_ends_trial=False, show_star_feedback=True, star_color="#f6b500", )

block = Block([stim], timeline=timeline) Experiment([block]).to_html("foraging.html")

Source code in sweetbean/stimulus/Foraging.py
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
def __init__(
    self,
    # Required-ish (can be empty)
    targets: Optional[Union[List[Dict[str, Any]], TimelineVariable]] = None,
    distractors: Optional[Union[List[Dict[str, Any]], TimelineVariable]] = None,
    # Layout & placement
    position_mode: str = "random",  # "random" | "grid" | "circle"
    grid_cols: Optional[int] = None,
    grid_rows: Optional[int] = None,
    ring_radius_vmin: float = 30,
    randomize_positions: bool = True,  # grid/circle only
    # Arena & spacing
    arena_size_vmin: float = 92,  # centered square side (vmin)
    placement_inset_vmin: float = 6,  # inner margin
    min_gap_vmin: float = 2.5,  # extra pairwise gap
    # Visuals
    background: str = "#000000",  # default black
    color: str = "#ffffff",  # default foreground (text/border)
    token_box_size: str = "12vmin",
    token_font_size: str = "10vmin",
    # Pools (defaults are in the plugin too; pass to control sampling)
    overlay_pool: Optional[List[str]] = None,
    rotation_pool: Optional[List[int]] = None,
    # Timing & control
    trial_duration: Optional[
        int
    ] = None,  # None => ends when all targets found (if end_when_found=True)
    end_when_found: bool = True,
    response_ends_trial: bool = False,
    # Determinism
    seed: Optional[int] = None,
    # Feedback
    show_star_feedback: bool = False,  # OFF by default
    star_color: str = "#f6b500",
    # Hooks / triggers
    # Example: {"on_all_targets_collected": "end_trial"}
    triggers: Optional[Dict[str, Any]] = None,
    # SweetBean convenience
    duration: Optional[int] = None,  # mirrors RSVP: alias for trial_duration
    side_effects: Optional[Dict[str, Any]] = None,
):
    """
    Arguments:
        targets (list[dict] | TimelineVariable | None):
            Trial’s target items. Accepts a concrete list or a TimelineVariable
            that evaluates per trial to a list. Each item is an ItemSpec dict
            that defines exactly ONE of {html | text | shape | src} plus
            optional styling/placement fields:

              Content (choose exactly one)
              - html (str): Raw HTML.
              - text (str): Plain text (rendered in a token box).
              - shape (str): One of "circle", "square", "triangle".
              - src (str): Image URL/path.

              Optional appearance/identity
              - color (str): CSS color; overrides overlay_pool sampling.
              - rotationDeg (int): Rotation in degrees; overrides rotation_pool.
              - size (str): CSS size of the token box (e.g., "12vmin").
              - fontSize (str): For text content (e.g., "10vmin").
              - id (str): Opaque label copied to data.
              - attrs (dict[str,str]): Arbitrary HTML attributes.

              Placement override (optional; else global placement rules apply)
              - pos (dict): One of the following shapes:
                    {"mode": "abs", "x_vmin": <float>, "y_vmin": <float>}
                    {"mode": "grid", "row": <int>, "col": <int>}
                    {"mode": "circle", "angle_deg": <float>, "radius_vmin": <float>}

        distractors (list[dict] | TimelineVariable | None):
            Same ItemSpec structure as `targets`. May be empty.

        position_mode (str):
            Global placement policy when items don’t provide an explicit `pos`.
            One of "random" | "grid" | "circle". Default "random".
        grid_cols (int | None):
            Number of columns for "grid" placement. If None, inferred from count.
        grid_rows (int | None):
            Number of rows for "grid" placement. If None, inferred from count.
        ring_radius_vmin (float):
            Ring radius for "circle" placement, in vmin units. Default 30.
        randomize_positions (bool):
            If True, jitter positions within the grid cell / along the ring for
            "grid"/"circle" modes. Default True.

        arena_size_vmin (float):
            Side length (vmin) of the centered square arena. Default 92.
        placement_inset_vmin (float):
            Inner safety margin from arena edges. Default 6.
        min_gap_vmin (float):
            Extra minimum pairwise spacing between item centers. Default 2.5.

        background (str):
            Arena background color. Default "#000000".
        color (str):
            Default foreground color (text/borders). Default "#ffffff".
        token_box_size (str):
            Default token box size (CSS). Default "12vmin".
        token_font_size (str):
            Default font size for text tokens (CSS). Default "10vmin".

        overlay_pool (list[str] | None):
            Optional pool of overlay symbols/colors; sampled per item unless the
            ItemSpec provides an explicit `color`. Omit/None to use plugin defaults.
        rotation_pool (list[int] | None):
            Optional pool of rotations in degrees; sampled per item unless the
            ItemSpec provides `rotationDeg`. Omit/None to use plugin defaults.

        trial_duration (int | None):
            Hard timeout in ms. If None and `end_when_found=True`, the trial ends
            when all targets are collected. Default None.
        end_when_found (bool):
            If True, automatically end the trial once all targets are found.
            Default True.
        response_ends_trial (bool):
            If True, any user interaction that counts as a response ends the trial,
            even if not all targets are collected. Default False.

        seed (int | None):
            Seed for deterministic placement/sampling. Default None.

        show_star_feedback (bool):
            If True, briefly show a star animation on successful target clicks.
            Default False.
        star_color (str):
            Star feedback color. Default "#f6b500".

        triggers (dict | None):
            Optional event→action mapping, e.g.,
            {"on_all_targets_collected": "end_trial"}.
            Default: {"on_all_targets_collected": "end_trial"}.

        duration (int | None):
            SweetBean convenience alias mirrored to `trial_duration` during build
            (consistent with RSVP). If provided, `trial_duration` is set to this
            value. Default None.
        side_effects: Optional side-effect configuration passed to the runtime. This expects
            a list of SideEffect definitions (see SweetBean docs) which can be
            used to update global data like overall score or trial counter.

    Emits (added to jsPsych data):
        - clicks (list[dict]): Raw click events ({kind, index, id?, t}).
        - n_targets (int): Number of target items in the trial.
        - n_collected (int): Number of targets collected.
        - tps (list[number]): Timestamps for target pickups.
        - bean_clicks (list[dict]): Mirror of `clicks`.
        - bean_n_targets (int): Mirror of `n_targets`.
        - bean_n_found (int): Mirror of `n_collected`.
        - bean_tps (list[number]): Mirror of `tps`.
        - bean_all_found (bool): Convenience flag (n_collected >= n_targets).

    Notes:
        - Provide item-level `pos` to bypass global placement for specific items.
        - If both `duration` and `trial_duration` are given, `duration` takes
          precedence by being copied into `trial_duration`.
        - Null/None optionals are dropped so the plugin falls back to its defaults.

    Example:
        from sweetbean import Block, Experiment
        from sweetbean.variable import TimelineVariable

        timeline = [
            {
                "targets": [
                    {"text": "T", "color": "#66ff66"},
                    {"shape": "circle", "color": "#66ff66"},
                ],
                "distractors": [
                    {"text": "L", "color": "#ff6666"},
                    {"shape": "square", "color": "#ff6666"},
                    {"shape": "triangle", "color": "#ff6666"},
                ],
            }
        ]

        stim = Foraging(
            targets=TimelineVariable("targets"),
            distractors=TimelineVariable("distractors"),
            position_mode="grid",
            grid_cols=6, grid_rows=4,
            arena_size_vmin=90, min_gap_vmin=2.5,
            background="#000000", color="#ffffff",
            token_box_size="10vmin", token_font_size="8vmin",
            end_when_found=True, response_ends_trial=False,
            show_star_feedback=True, star_color="#f6b500",
        )

        block = Block([stim], timeline=timeline)
        Experiment([block]).to_html("foraging.html")
    """

    if targets is None:
        targets = []
    if distractors is None:
        distractors = []
    if triggers is None:
        triggers = {"on_all_targets_collected": "end_trial"}

    super().__init__(locals(), side_effects)