Pattern API for Bee Swarm Simulator

Lookup for the Lua calls you use when writing a gather pattern. Each entry has a signature, what it does, and a short example.

Start here

• Learning from scratch → Writing your first gather pattern
• Installing a finished .lua, copying field-card settings, or testing with the console (devmode / execpattern) → Custom patterns
• Looking up a call → pick a section below

At a glance

• Name and field-card defaults
• Move
• Wait
• Keys and camera (Jump options table included)
• Read the field card
• Test and stop
• When a pattern fails

Save your script under the patterns gather folder, then restart Revolution so the name appears in Gather → Fields → Select pattern.

Windows

patterns\gather next to the Revolution app, or %APPDATA%\RevolutionMacro\patterns\gather

macOS

Patterns/gather under ~/Library/Application Support/RevolutionMacro/

Name and field-card defaults

Put these near the top of the file. Revolution reads them when it loads the script and fills defaults on the field card. If you omit size values, defaults are Length 4, Width 4, backpack percent 95, and Seconds 15 minutes (900).

SetName(name)

Sets the display name in the Gather pattern picker.

Parameter	Type	Meaning
name	string	Exact label shown under Select pattern

SetName("MyFirstPattern")

Size and stop defaults

These only set field-card defaults. They do not move the character while gather runs.

Call	Parameter	Meaning
SetLength(n)	number	Default Length on the field card
SetWidth(n)	number	Default Width on the field card
SetDistance(n)	number	Default Distance on the field card
SetAlignment(n)	number	Default Alignment amount on the field card
SetRepetitions(n)	number	Default repeat count on the field card
SetPosition("…")	string	Default sprinkler position (for example "bottom-right")
SetBackpackPercent(n)	number	Default backpack percent stop
SetSeconds(n)	number	Default gather seconds
SetWalkReturn(on)	boolean	Prefer walking back to hive
SetDriftComp(on)	boolean	Default drift-compensation flag
SetInvertFB(on)	boolean	Swap forward/backward for this pattern
SetInvertLR(on)	boolean	Swap left/right for this pattern
SetZoom(level)	number	Default zoom on the field card (does not zoom during a gather run)

SetName("MyFirstPattern")
SetLength(4)
SetWidth(4)
SetDistance(3)
SetWalkReturn(true)

Also acts while the pattern runs

These set field-card defaults and change the character during the run when you call them in the body of the script:

Call	Parameter	Meaning
SetPitch(angle)	number	Sets camera pitch
SetYaw(angle)	number (0–7)	Sets camera yaw. Use only SetYaw to change facing — not rotate-key presses. Even headings: 0 away from hives, 2 toward red HQ, 4 toward the hives, 6 toward blue HQ.
SetShiftLock(on)	boolean	Turns shift lock on or off

SetYaw(0)   -- away from the hives
SetShiftLock(true)

Move

Distances are in studs. One flower tile is about 4 studs, so authors often write n * 4. Timing follows Player Movespeed under Settings → Game → Movement — match in-game speed with no buffs.

Direction constants: Forward, Backward, Left, Right (also Direction.Forward, and so on).

Walk(direction, studs)

Walks one direction for a distance, then continues. Blocks until the walk finishes.

Parameter	Type	Meaning
direction	direction	Forward, Backward, Left, or Right
studs	number	Distance to cover

Walk(Forward, 4 * 4)
Walk(Right, 16)

Walk({dirA, dirB}, studs)

Starts both directions together and waits until that many studs of walk-time have passed. Useful for short diagonals without separate KeyDown / KeyUp pairs.

Walk({Forward, Right}, 3 * 4)

WalkAsync(direction, studs)

Starts a walk in the background and returns immediately. Pair it with another Walk when you want two axes at once (common for wall / corner compensation).

WalkAsync(Left, 8)
Walk(Backward, 8)
Sleep(20)

WalkAlign(direction, studs [, factor])

Walks like Walk, then adds extra studs from the current alignment level (and optional factor). Use when a leg needs to push further into a wall or corner under high alignment.

WalkAlign(Forward, 32)

Wait

Sleep(ms)

Waits a fixed number of milliseconds.

Walk(Forward, 16)
Sleep(20)

SleepStuds(studs)

Waits as long as walking that many studs would take at the current movespeed. Use with KeyDown / KeyUp when you hold keys yourself.

KeyDown(Key.Forward)
KeyDown(Key.Right)
SleepStuds(3 * 4)
KeyUp(Key.Forward)
KeyUp(Key.Right)

SleepAlign(ms)

Waits ms scaled by alignment level — about 1× low, 1.25× medium, 1.5× high.

SleepAlign(40)

Keys and camera

Movement keys respect SetInvertFB / SetInvertLR on the field card.

KeyPress(key)

Taps a key once.

KeyPress(Key.RotLeft)
Sleep(30)

KeyDown(key) / KeyUp(key)

Holds or releases a key. Always pair them so a key is not left down.

KeyDown(Key.Backward)
KeyDown(Key.Left)
SleepStuds(4 * 4)
KeyUp(Key.Backward)
KeyUp(Key.Left)

Camera

Call	Meaning
SetYaw(angle)	Sets yaw during the run (0–7). Prefer this over RotLeft / RotRight key presses.
SetPitch(angle)	Sets pitch during the run
SetShiftLock(on)	Toggles shift lock during the run

For gather movement keys use Forward, Backward, Left, Right, plus ZoomIn / ZoomOut, Shift / LShift, Space, and number keys (One–Seven, Zero) for hotbar slots. Do not steer pattern facing with RotLeft / RotRight — call SetYaw instead (see Writing your first gather pattern).

SetYaw(6)   -- toward blue HQ

Jump(...)

Jumps (holds Space) and optionally walks while airborne. Used on field exits and ledges. The same call works in gather scripts when you need a hop.

Short forms: Jump(), Jump(Forward), Jump(Left, 200) (direction + delay in ms), Jump(250) (delay only, still walks Forward).

Pass a table when you need more control. Omit keys you do not need — defaults fill in.

Key	Type	Default	Meaning
Direction	table of directions	{Forward}	One or more of Forward, Backward, Left, Right. Several entries walk a diagonal while jumping.
Delay	number (ms)	300	Timing between pressing Space and walking. Under 100, walking starts while Space is still held. At 100 and above, Space releases first, then walking starts after the remaining wait.
Distance	number (studs)	4	How far to keep walking after the jump timing (uses movespeed, same stud timing as Walk).
WalkBefore	number (studs)	0	Walk in Direction this far before pressing Space. If Delay is greater than 0, those keys release before the jump. If Delay is 0, they stay held into the jump.
KeepWalking	boolean	false	When true, leaves the Direction keys held after Distance so you can chain another walk without a gap.

Jump({
    Direction = {Backward},
    WalkBefore = 20,
    Delay = 200,
    Distance = 80,
})
Sleep(600)

Prefer Jump({...}) when you need more than a single direction or delay. For a bare Space tap without the walk timing, use KeyPress(Key.Space) instead.

Read the field card

During a gather run, Pattern holds the settings from the active field card. The table is read-only — change Length or Alignment on the card in Gather, not by assigning to Pattern.

Field	Meaning
Pattern.Length	Length from the field card
Pattern.Width	Width from the field card
Pattern.Distance	Distance from the field card
Pattern.Alignment	Alignment amount from the field card
Pattern.Repetitions	Repeat count from the field card

local step = Pattern.Length * 4
local align = Pattern.Alignment

Walk(Forward, step + align)
Walk(Right, step)

Advanced status fields

Field	Meaning
Pattern.Iteration	Which gather pass you are on (starts at 1 for many scripts’ first-pass setup)
Pattern.Interrupt	true when gather should yield to an interrupt

if Pattern.Iteration == 1 then
    WalkAlign(Left, 65)
end

if Pattern.Interrupt then
    Exit()
end

Test and stop

Status(text)

Updates the Status line and writes the same text to the log. Handy while testing a path.

Status("Corner reach")

Exit()

Ends the script cleanly before the rest of the file runs.

if Pattern.Interrupt then
    Exit()
end

When a pattern fails

Message	What to do
Failed to compile Lua pattern	Fix the syntax error, save, restart
Failed to extract metadata from Lua pattern	Keep SetName("…") as a string literal near the top. Fix other Set* arguments
Pattern Execution Failed	Open Status logs, fix the Lua error, save, restart

If the character walks the wrong path after converts rather than failing outright, fix Size, Position, and Tilt on the field card and match Player Movespeed first — see Choose fields and patterns and Macro resets or gets stuck.

Limits

Patterns run as Lua scripts. Stick to the calls listed here plus normal Lua control flow (if, for, local).

Related

Writing your first gather pattern

Custom patterns

Choose fields and patterns