Background Script Reference

Overview

The background.ahk script runs as a separate process alongside the main macro, continuously monitoring the Roblox window for critical game events and states. Location: submacros/background.ahk Purpose:

Death detection
Guiding Star buff detection
Pop Star buff monitoring
Night/day cycle detection
Backpack percentage tracking
Emergency balloon handling
Daily reconnect scheduling

Initialization

The background script is launched by the main macro during startup:

if !WinExist("Heartbeat.ahk ahk_class AutoHotkey")
    run '"' exe_path32 '" /script "' A_WorkingDir '\\submacros\\Heartbeat.ahk"'

Requirements

A_Args

array

The script must be launched with command-line arguments from the main macro. Manual execution will show an error.Arguments:

[1] NightLastDetected (unused)
[2] VBLastKilled (unused)
[3] StingerCheck
[4] StingerDailyBonusCheck (unused)
[5] AnnounceGuidingStar
[6] ReconnectInterval
[7] ReconnectHour
[8] ReconnectMin
[9] EmergencyBalloonPingCheck
[10] ConvertBalloon
[11] NightMemoryMatchCheck
[12] LastNightMemoryMatch (unused)

State Management

Global State Variables

resetTime := nowUnix()
LastState := nowUnix()
LastConvertBalloon := nowUnix()
state := 0
MacroState := 2

state

integer

Current macro activity state:

0 - Idle/traveling
1 - Gathering in field
Other values for specific activities

MacroState

integer

Overall macro status:

0 - Stopped
1 - Paused
2 - Running

resetTime

integer

Unix timestamp of last reset/respawn. Used to prevent false death detection immediately after respawn.

OnMessage Handlers

The background script receives commands from the main macro:

OnMessage(0x5552, nm_setGlobalInt, 255)  // Set integer variables
OnMessage(0x5553, nm_setGlobalStr, 255)  // Set string variables  
OnMessage(0x5554, nm_setGlobalNum, 255)  // Set numeric variables
OnMessage(0x5555, nm_setState, 255)      // Update state
OnMessage(0x5556, nm_sendHeartbeat)      // Heartbeat response

Message Handlers

nm_setGlobalNum

function

Updates numeric variables from main script.

nm_setGlobalNum(wParam, lParam, *)

Parameters:

wParam - Variable index in array
lParam - New value

Variables:

Index 1: resetTime
Index 4: StingerCheck
Index 6: LastConvertBalloon
Index 7: NightMemoryMatchCheck

nm_setState

function

Updates the current state from main script.

nm_setState(wParam, lParam, *)

Parameters:

wParam - New state value
lParam - Last state value

Main Loop

The background script runs an infinite loop with 1-second intervals:

loop {
    hwnd := GetRobloxHWND()
    GetRobloxClientPos(hwnd)
    offsetY := GetYOffset(hwnd)
    nm_deathCheck()
    nm_guidCheck()
    nm_popStarCheck()
    nm_CheckNight()
    nm_backpackPercentFilter()
    nm_guidingStarDetect()
    nm_dailyReconnect()
    nm_EmergencyBalloon()
    sleep 1000
}

Detection Functions

Death Detection

nm_deathCheck

function

Detects when the player dies by searching for the death screen image.

nm_deathCheck()

Behavior:

Checks bottom-right quadrant of screen
Requires 20+ seconds since last reset
Requires 10+ seconds since last death detection
Uses ImageSearch with 50 variation tolerance
Sends PostMessage 0x5555, 1, 1 to main script
Sends “You Died” via WM_COPYDATA

Image: nm_image_assets/died.png

Guiding Star Detection

nm_guidCheck

function

Detects when Guiding Star buff is active in fields.

nm_guidCheck()

Behavior:

Searches top portion of screen (offsetY+30 to offsetY+90)
Only triggers when state = 1 (gathering)
Uses confirmation system (5 checks) before declaring buff ended
Sends PostMessage 0x5555, 6, 1 when detected
Sends PostMessage 0x5555, 6, 0 when ended
Sends “Detected: Guiding Star Active” message

Image: nm_image_assets/boostguidingstar.png Tolerance: 50 variation

Pop Star Detection

nm_popStarCheck

function

Monitors Pop Star amulet stacks and active state.

nm_popStarCheck()

Behavior:

Checks bottom 1/4 of screen
Detects pop star counter to determine if buff is available
Tracks two states: HasPopStar (has stacks) and PopStarActive (buff active)
When counter visible: has stacks but not active
When counter disappears during gathering: buff is active
Sends state updates to main macro and StatMonitor

Messages:

PostMessage 0x5555, 7, 1 - Has pop star stacks
PostMessage 0x5555, 8, 1 - Pop star active
PostMessage 0x5555, 8, 0 - Pop star ended

Image: nm_image_assets/popstar_counter.png Tolerance: 30 variation

Night Detection

nm_CheckNight

function

Detects the night/day cycle for stinger spawns and night memory match.

nm_CheckNight()

Behavior:

Only runs if StingerCheck or NightMemoryMatchCheck enabled
Scans bottom half of screen for lighting conditions
Uses confidence system (6 consecutive detections)
Distinguishes between day (0), night (1), and dusk (2)
Maintains detection for 5 minutes after initial trigger
Loads bitmaps from nm_image_assets/night/ and nm_image_assets/offset/

States:

0 - Day (nightConfidence <= 1)
1 - Night (nightConfidence >= 6 or within 5min of last detection)
2 - Dusk/transition (nightConfidence > 1 but < 6)

Messages:

PostMessage 0x5552, 368, night to main macro
PostMessage 0x5552, 367, night to PlanterTimers
Sends “Detected: Night” via WM_COPYDATA

Detection Method:

CheckBitmap(time, variation)  // Searches for day/night bitmaps

Backpack Percentage Detection

nm_backpackPercent

function

Calculates backpack fill percentage using pixel color analysis.

nm_backpackPercent()

Behavior:

Samples pixel at windowX+windowWidth//2+59+3, windowY+offsetY+6
Analyzes RGB color channels to determine fill level
Returns percentage in 5% increments (0, 5, 10, … 95, 100)
Bar is 220 pixels wide = 11 pixels per 5%

Color Analysis:

Red channel increases as backpack fills
Green/Blue channels decrease as backpack fills
Uses bitwise AND with masks (0xFF0000, 0x00FFFF)
Specific color thresholds for each 5% increment

Returns: Integer percentage (0-100) or 0 if unable to determine

nm_backpackPercentFilter

function

Applies rolling average filter to backpack percentage for stability.

nm_backpackPercentFilter()

Behavior:

Maintains 6-sample rolling window (6 seconds @ 1Hz)
Calculates rounded average of samples
Updates StatMonitor every 6 seconds
Sends updates to main macro when value changes

Messages:

PostMessage 0x5555, 4, BackpackPercent (raw value)
PostMessage 0x5555, 5, BackpackPercentFiltered (filtered value)
PostMessage 0x5557, BackpackPercentFiltered, timestamp (to StatMonitor)

Guiding Star Field Detection

nm_guidingStarDetect

function

Detects which field has a Guiding Star and announces it.

nm_guidingStarDetect()

Behavior:

Only runs if AnnounceGuidingStar = 1
Rate limited to once per 10 seconds
Searches center-to-bottom-right area of screen
Checks two different guiding star icon variations
Searches each of 17 fields for field name image
Sends notification to main macro when found

Fields Checked: PineTree, Stump, Bamboo, BlueFlower, MountainTop, Cactus, Coconut, Pineapple, Spider, Pumpkin, Dandelion, Sunflower, Clover, Pepper, Rose, Strawberry, MushroomImages:

nm_image_assets/guiding_star_icon1.png
nm_image_assets/guiding_star_icon2.png
Field images in nm_image_assets/fields/

Daily Reconnect

nm_dailyReconnect

function

Triggers scheduled reconnect at specified time.

nm_dailyReconnect()

Behavior:

Checks if current time matches ReconnectHour:ReconnectMin
Only triggers once per minute window
Sends PostMessage 0x5555, 3, 1 to main macro
Resets after 60 seconds to prevent multiple triggers

Emergency Balloon

nm_EmergencyBalloon

function

Forces balloon conversion based on time since last convert.

nm_EmergencyBalloon()

Behavior:

Only runs if EmergencyBalloonPingCheck = 1
Activates if ConvertBalloon = "Every" or ConvertBalloon = "Never"
Checks if 2+ hours since last balloon conversion
Sends emergency balloon notification
Updates LastConvertBalloon timestamp

Bitmap Loading

The background script loads detection bitmaps during initialization:

pToken := Gdip_Startup()
bitmaps := Map()
bitmaps.CaseSense := 0
#Include "%A_ScriptDir%\\..\\nm_image_assets\\offset\\bitmaps.ahk"
#Include "%A_ScriptDir%\\..\\nm_image_assets\\night\\bitmaps.ahk"

bitmaps

Map

Case-insensitive map storing GDI+ bitmap pointers for image detection.Categories:

offset - UI offset detection bitmaps
night - Night/day detection bitmaps
Other detection images loaded as needed

Communication Protocol

Sending to Main Macro

// PostMessage format
PostMessage 0x5555, eventType, eventData, , "natro_macro ahk_class AutoHotkey"

// WM_COPYDATA format  
Send_WM_COPYDATA(message, "natro_macro ahk_class AutoHotkey")

Event Types (0x5555)

eventType

integer

Values:

1 - Death detected
3 - Daily reconnect time reached
4 - Backpack percent (raw)
5 - Backpack percent (filtered)
6 - Guiding Star state (lParam: 1=active, 0=inactive)
7 - Has Pop Star stacks
8 - Pop Star active state

Window Management

The background script uses Roblox window detection functions from the library:

hwnd := GetRobloxHWND()           // Get Roblox window handle
GetRobloxClientPos(hwnd)          // Update window position globals
offsetY := GetYOffset(hwnd)       // Calculate GUI offset

These functions handle both regular Roblox client and UWP version.

Coordinate System

CoordMode "Pixel", "Screen"
DetectHiddenWindows 1

All pixel and image searches use screen coordinates, and the script can detect hidden windows for inter-process communication.

Cleanup

OnExit((*) => ProcessClose(DllCall("GetCurrentProcessId")))

The script forcefully terminates its own process on exit to ensure clean shutdown.

AutoHotkey Scripts

Fields & Locations

Background Script Reference

Overview

Initialization

Requirements

State Management

Global State Variables

OnMessage Handlers

Message Handlers

Main Loop

Detection Functions

Death Detection

Guiding Star Detection

Pop Star Detection

Night Detection

Backpack Percentage Detection

Guiding Star Field Detection

Daily Reconnect

Emergency Balloon

Bitmap Loading

Communication Protocol

Sending to Main Macro

Event Types (0x5555)

Window Management

Coordinate System

Cleanup

See Also

Build docs developers (and LLMs) love

AutoHotkey Scripts

Fields & Locations

​Overview

​Initialization

​Requirements

​State Management

​Global State Variables

​OnMessage Handlers

​Message Handlers

​Main Loop

​Detection Functions

​Death Detection

​Guiding Star Detection

​Pop Star Detection

​Night Detection

​Backpack Percentage Detection

​Guiding Star Field Detection

​Daily Reconnect

​Emergency Balloon

​Bitmap Loading

​Communication Protocol

​Sending to Main Macro

​Event Types (0x5555)

​Window Management

​Coordinate System

​Cleanup

​See Also

Build docs developers (and LLMs) love

Overview

Initialization

Requirements

State Management

Global State Variables

OnMessage Handlers

Message Handlers

Main Loop

Detection Functions

Death Detection

Guiding Star Detection

Pop Star Detection

Night Detection

Backpack Percentage Detection

Guiding Star Field Detection

Daily Reconnect

Emergency Balloon

Bitmap Loading

Communication Protocol

Sending to Main Macro

Event Types (0x5555)

Window Management

Coordinate System

Cleanup

See Also