Skip to content
Bit Quirky Behavior Trees and
State Machines

Search documentation

All topics and APIs

Close returns focus to Search.

What are you looking for?

Try a common topic or enter a complete API identifier.

Browse the reference instead

Esc closes · Tab reaches results · Enter opens the focused link

v0.11.0
Menu

Variable arguments

Bind a method whose last parameter is params, feed it individual values in the order you want or hand it an array or list you already hold, and let the editor catch a wrong-type entry before Play.

A C# method whose last parameter is params T[] takes as many values as you care to give it. Pick it in the member picker and the Arguments card grows a slot that takes them one at a time, in the order you set, or takes one array or list you already hold. Either way the call gets one array, and your method never knows which form you chose.

The Platformer’s GraphEnemyPatrol has a patrol call that already exists in C#: AdvanceWaypointPatrol(ref PatrolStop nextStop, ref float pauseProgress, params Transform[] waypoints), whose two ref parameters are the graph’s own next_stop and pause_progress progress values, bound as read-write parameters exactly as the combat enemy’s patrol binds them. The designer wants one enemy to walk the waypoints in numbered order and another to run the same three in reverse from a route array the scene fills in. Without a params slot that means a Transform[] variable per enemy, a node to assemble it, or a developer writing AdvanceThreeWaypoints(Transform, Transform, Transform) just to keep the graph happy.

EnemyPatrolParams.bqbehavior binds the method as declared. Its advance the params patrol node lists three individual values, wp0, wp1, wp2, and Enemy Params walks them in that order. Switch the same slot to Collection and point it at altRoute, which the enemy fills with the same three waypoints reversed, and it walks 3, 2, 1 with no other change.

  • A gameplay method ends in params: a patrol over any number of waypoints, a sound cue with any number of layers, a spawn call that takes any number of prefabs.
  • The order matters and you want to author it by eye. Individual values are rows you can drag, so the route reads top to bottom in the rail.
  • The values already live in an array or list on the Blackboard, filled by your code or by a scene owner. Collection hands it over as it is.
  • A member condition asks a question of several values at once. RouteContainsWaypointsInOrder(params Transform[]) takes the same slot a method node does and answers with a yes or a no.
Enemy Params stops at Waypoint 1, then Waypoint 2, then Waypoint 3, the order of the three individual values wp0, wp1, wp2.
Enemy Params stops at Waypoint 1, then Waypoint 2, then Waypoint 3, the order of the three individual values wp0, wp1, wp2.

The shipped node in Individual values with wp0, wp1, wp2. Enemy Params walks to Waypoint 1 under the second ground coin and stops, walks on to Waypoint 2 between the third and fourth coins, then to Waypoint 3 under the fifth, and walks back to the first in one go. The pause is set to a second so each stop reads.

With the altRoute collection, Enemy Params stops at Waypoint 3, then Waypoint 2, then Waypoint 1, the array's own order.
With the altRoute collection, Enemy Params stops at Waypoint 3, then Waypoint 2, then Waypoint 1, the array's own order.

The same node switched to Collection altRoute, nothing else changed. The array holds waypoint 3, 2, 1, so the enemy walks past Waypoint 2 to the far stop first, then comes back through 2 and 1 in reverse.

One params slot filled two ways, one array reaches the callThe method AdvanceWaypointPatrol on GraphEnemyPatrol, on the Enemy Params object, takes params Transform[] waypoints. Its Arguments card shows one params slot headed waypoints, Transform, params, and a switch between Individual values and Collection. Individual values holds three ordered rows bound to the Blackboard variables wp0, wp1, and wp2, with an Add value button. Collection holds the array variable altRoute, which holds Waypoint 3, 2, and 1. First Individual values is active: the three rows are packed in order into one Transform array, the method receives it, and Enemy Params visits Waypoint 1, 2, then 3, while the card notes Collection altRoute is retained while inactive. Then the switch flips to Collection: the three rows dim and the card notes 3 individual values are retained while inactive; altRoute goes to the method as it is, and Enemy Params visits Waypoint 3, 2, then 1. Then the switch flips back and the three rows return unchanged. Each switch is one edit and one undo step, and the inactive form is kept, never deleted.GraphEnemyPatrolon Enemy ParamsAdvanceWaypointPatrol(params Transform[] waypoints)waypointsTransformparamsIndividual valuesCollectionBBwp0[0]BBwp1[1]BBwp2[2]Add valuealtRouteTransform[]Collection altRoute is retained while inactive.3 individual values are retained while inactive.waypoints · one Transform[]wp0wp1wp2altRoutepassed as it isholds Waypoint 1, 2, 3holds Waypoint 3, 2, 1AdvanceWaypointPatrol(waypoints)Enemy Params visits, in orderWaypoint 1Waypoint 3Waypoint 2Waypoint 2Waypoint 3Waypoint 1Individual values · wp0, wp1, wp2 packed in orderCollection · altRoute as it is · one undo stepIndividual values · rows restored · one undo stepOne params slot filled two ways, one array reaches the callThe method AdvanceWaypointPatrol on GraphEnemyPatrol, on the Enemy Params object, takes params Transform[] waypoints. Its Arguments card shows one params slot headed waypoints, Transform, params, and a switch between Individual values and Collection. Individual values holds three ordered rows bound to the Blackboard variables wp0, wp1, and wp2, with an Add value button. Collection holds the array variable altRoute, which holds Waypoint 3, 2, and 1. First Individual values is active: the three rows are packed in order into one Transform array, the method receives it, and Enemy Params visits Waypoint 1, 2, then 3, while the card notes Collection altRoute is retained while inactive. Then the switch flips to Collection: the three rows dim and the card notes 3 individual values are retained while inactive; altRoute goes to the method as it is, and Enemy Params visits Waypoint 3, 2, then 1. Then the switch flips back and the three rows return unchanged. Each switch is one edit and one undo step, and the inactive form is kept, never deleted.GraphEnemyPatrolon Enemy ParamsAdvanceWaypointPatrol(params Transform[] waypoints)waypointsTransformparamsIndividual valuesCollectionBBwp0[0]BBwp1[1]BBwp2[2]Add valuealtRouteTransform[]Collection altRoute is retained while inactive.3 individual values are retained while inactive.waypoints · one Transform[]wp0wp1wp2altRoutepassed as it isholds Waypoint 1, 2, 3holds Waypoint 3, 2, 1AdvanceWaypointPatrol(waypoints)Enemy Params visits, in orderWaypoint 1Waypoint 3Waypoint 2Waypoint 2Waypoint 3Waypoint 1Individual values · wp0, wp1, wp2 packed in orderCollection · altRoute as it is · one undo stepIndividual values · rows restored · one undo step
Individual values packs its rows into one array in order, Collection hands over an array you already have, and either way the method receives one array.
The member picker on GraphEnemyPatrol, Methods tab, listing AdvanceWaypointPatrol with its two ref parameters and params Transform[] waypoints, and RouteContainsWaypointsInOrder(params Transform[] waypoints)
Figure 1. Both params methods on the component, each tagged bool; the patrol call also carries 2 REFS for its progress. The picker spells the declaration out with its params keyword and truncates the long ones; a method and a condition with the same slot shape get the same treatment on their cards.
The Arguments card of advance the params patrol: a waypoints Transform slot tagged params, the Individual values and Collection switch on Individual values, three rows for wp0 through wp2 each with a grip plus a C or BB source segment plus a Remove value button, then Add value
Figure 2. The slot header names the parameter, its element type, and the params tag. Below it, one row per value in call order, and Add value at the end.
The same card after choosing Collection: one field holding altRoute and a note reading 3 individual values are retained while inactive
Figure 3. Switching forms is one edit and one undo step. The rows you authored are kept, dimmed to a note, and come back exactly as they were when you switch again.
Switching the waypoints slot between Individual values and Collection keeps the other form: each side names what is retained while inactive.
Switching the waypoints slot between Individual values and Collection keeps the other form: each side names what is retained while inactive.

The rail during a switch each way: the rows give way to the collection field and a retained-values note, then come back when Individual values is chosen again, with the collection named in its own note.

  1. Open Assets/Platformer/Behavior/EnemyPatrolParams.bqbehavior in Static. Hover patrol and decide, click its +, and choose method under ACTIONS. Name it and press Enter.

  2. In Target, Agent is selected. Click Choose a component…, type GraphEnemyPatrol, and press Enter. Enemy Params carries that component on its own GameObject.

  3. In Member, click Change, open Methods, and pick AdvanceWaypointPatrol. An Arguments card appears with one slot, waypoints Transform tagged params, the switch on Individual values, the reading 0 values, and Add value, beside a Read-write parameters card for nextStop and pauseProgress; bind those to the graph’s next_stop and pause_progress as Arguments and results shows, and this page stays on the params slot.

    The Arguments card of a freshly bound AdvanceWaypointPatrol: the waypoints Transform params slot, the switch on Individual values, the notice 0 values, and the Add value button
    Figure 4. Zero rows is a legal call. The method receives an empty array.
  4. Click Add value three times. On each new row click BB and pick wp0, then wp1, then wp2. The picker offers only variables that fit one element: the three Transform variables are offered, and altRoute is struck through because an array is not one Transform.

    The Blackboard variable picker for a params value row: wp0, wp1 and wp2 offered, altRoute struck through with the reason that a Transform array is not a Transform
    Figure 5. Each row wants one element, so an array is ruled out with the reason on its row. The Collection form is where an array belongs.
  5. Read the card on the canvas. Under the method name it lists the Blackboard values the slot reads, wp0, wp1, wp2, in row order. Drag a row by its grip, or focus the grip and press Alt+Up or Alt+Down, and the order on the card and in the call follow.

    The canvas card of advance the params patrol in Individual values, tagged ACTION · METHOD, listing wp0 through wp2 as Blackboard chips under the method name
    Figure 6. The canvas card of advance the params patrol in Individual values, tagged ACTION · METHOD, listing wp0 through wp2 as Blackboard chips under the method name
  6. Press Cmd/Ctrl+S. The toolbar reads Bindings valid and the status bar Saved. Saving regenerates the member provider, which is what packs the rows into one array for Play.

A member condition bound to a bool method with a params tail gets the identical slot, and the result goes to Comparison like any other condition. EnemyPatrolParams.bqbehavior carries two of them under its two route decisions: individual waypoints match route passes wp0, wp1, wp2 and succeeds because the enemy’s patrol holds them in that order, and waypoint array matches route passes altRoute and fails because the reversed array is not in route order, so that Selector falls through to its different route branch.

The rail of the member condition waypoint array matches route: the Arguments card with the waypoints params slot on Collection reading altRoute, and the Comparison card testing the bool return against true
Figure 9. A decision with a params slot. Comparison reads the method’s bool, so true continues the branch and false sends the Selector to its next child.

Result

Success
The method returned, and on a method node its Result mapping or a Comparison on a condition held. An empty Individual values list is a successful call with an empty array.
Failure
The Comparison did not hold, the Result mapping said so, or the target did not resolve this evaluation. A method that throws is a recorded fault, never an authored Failure.
Running
Only when the method itself returns a coroutine or awaitable; see waiting and cancellation. The packing of values never waits.

The slot

  • Exactly one slot, for the declaration’s trailing params parameter. Ordinary parameters ahead of it keep their ordinary rows, and ref, out, and optional parameters on the same signature keep their own cards.
  • The header reads the parameter name, the element type, and params. The switch offers Individual values and Collection. There is no Default for a params parameter.
  • The slot appears on method nodes and member condition nodes alike, with the same forms, the same rows, and the same validation words.

Individual values

  • One row per value, in call order. A row’s source is C (a typed constant) or BB (a compatible Blackboard variable). Element types stay exact; a CLR-safe reference upcast is also available, such as an int[] or List<int> supplied as one object in params object[]. This passes the collection as one element, not its contents. Project is not offered on a params row.
  • Add value appends a row. Remove value deletes exactly that row. The grip reorders by pointer drag or with Alt+Up and Alt+Down; a reorder is one undo step.
  • A row with no value reads Required. A constant the element type cannot represent reads Incompatible with the reason, names parameter[index], and blocks Save, bake, and graph start. The Validation card offers Remove value for that exact row.
  • Zero rows is valid and calls the method with an empty array.

Collection

  • One field, Blackboard only, holding an array of the element type or a List<T> of the element type. The picker rules out everything else with its reason.
  • A saved collection that no longer resolves reads Missing; one whose type no longer fits reads Incompatible. Both keep the saved name so you can see what it was.
  • A managed-companion array is passed directly. A managed-companion list is copied into one cached array that is reallocated only when the list’s count changes, so unchanged-size conversion reuses its allocation. Native-backed arrays use a fresh exact-sized snapshot for each call, and native-backed lists convert straight from their buffer into an exact-sized array without an intermediate list. Those native snapshots allocate even when the count is unchanged.

Switching and saving

  • The switch is one edit and one undo step. The inactive payload is retained, shown as a note, and never validated while inactive: a bad constant in a retained row does not block a Collection call.
  • The graph file records the active form, each individual value’s source and position, and the collection’s name, in source format bitquirky.behavior/1.8. A reopen restores both payloads and the active form exactly as authored. See graph files.
  • The canvas card lists the Blackboard values the active form reads, each row’s variable in order or the one collection, so the route is readable without opening the rail. The exact index of a faulty row lives on the rail and in the Validation card.

At runtime

  • The generated provider allocates the outer Individual values array once when the graph starts and refills it on every call. That packed outer array is reused; this does not make every source read allocation-free. A native array supplied as one element materializes a fresh snapshot, shared with other reads of that same native array during the call. A native list uses its existing typed source materializer and commits supported element mutations within the authored capacity after a normal return.
  • The entity path refuses a params parameter, naming the modifier. Bind it on a GameObject agent.
  • An indexed property with a trailing params index parameter is a different case: it gets one required row holding a single array value, never this multi-row slot. See indexed property.

When it goes wrong

SymptomCheckFix
The method is in the picker but the Arguments card has no Add value button.Read the switch. It is on Collection, which shows one field instead of rows.Click Individual values. Any rows you authored before are still there.
The variable I want is struck through on a row.A row takes one element. An array or list variable is ruled out with that reason.Switch the slot to Collection for an array or list, or pick a variable of the element type for the row.
Save is refused with one binding issue.Open the Validation card. It names the parameter and the index, waypoints[0], and the constant that does not reach the element type.Give that row a value of the element type, or click Remove value on the finding.
The enemy visits the waypoints in the wrong order.The rows are the order. Read them top to bottom on the rail, or the array variable in Live.Drag the rows by their grips, or Alt+Up and Alt+Down with a grip focused.
I switched to Collection and my rows vanished.They are retained. The note under the field counts them.Click Individual values and they return in their order. Undo also reverses the switch in one step.
The entity picker refuses the method.The refusal names params. The Burst path admits only unmanaged by-value and ref parameters.Bind it on the GameObject path, or offer a fixed-arity static overload for entities.
The call runs but the method sees an empty array.Zero rows is a legal call. Select the node: the Arguments card reads 0 values.Add the values, or switch to a Collection that is filled before the graph ticks.
Full-size image