Useless Information You Didn't Need to Know About sleep_until

[PiRate 49]

While doing some reversing of Halo to fully integrate client functions into the scripting engine, I came across a curiosity regarding sleep_until.

 

According to the references I can locate, sleep_until can accept two arguments - one required and one optional.

Even the internal reference generated by script_doc affirms this:

 

Quote

(sleep_until <boolean> [<short>])

pauses execution of this script until the specified condition is true, checking once per second unless a different number of ticks is specified.

 

However, sleep_until has 3 parameters, and technically accepts even more arguments.

 

Note: Any addresses below are for the 1.10 PC client, because most of my notes are on the PC client and have yet to be ported to the CE client. However, what I mention below holds true for the CE client. I am posting this under the CE section because I assume more people would be using Halo script in CE rather than PC.

 

Below is the parsing function for sleep_until, in Cish (i.e. no guarantees it is legal C), translated from the assembly:

// Note: I use BOOL below to convey meaning and it does not necessarily
// reflect the width of Halo bools, depending on the compiler.

// Returns TRUE if the script node referred to by node_id can evaluate
// to the value type specified, and FALSE otherwise.
// Has side-effects.
BOOL parse_script_node_expected(identity_type node_id, enum_short type);

BOOL parse_sleep_until(short function_index, identity_type script_node_id)
{
    script_node *primary_node  = get_script_node(script_node_id);
    script_node *function_node = get_script_node(primary_node->value.id);
    
    // ------------------------------
    // condition argument, required
    // type: boolean (enum value 5)
    
    identity_type condition_node_id = function_node->next_script_node_id;
    if (condition_node_id == k_invalid_identity || 
        !parse_script_node_expected(condition_node_id, value_type_boolean))
        return FALSE; // condition argument is required
    
    // ------------------------------
    // period argument, optional
    // type: short (enum value 7)
    
    script_node  *condition_node = get_script_node(condition_node_id);
    identity_type period_node_id = condition_node->next_script_node_id;
    if (period_node_id == k_invalid_identity)
        return TRUE; // period argument is optional
    
    if (!parse_script_node_expected(period_node_id, value_type_short))
        return FALSE; // period argument supplied but could not parse to short
    
    // ------------------------------
    // timeout argument, optional
    // type: long (enum value 8)
    
    script_node  *period_node     = get_script_node(period_node_id);
    identity_type timeout_node_id = period_node->next_script_node_id;
    
    if (timeout_node_id != k_invalid_identity &&
        !parse_script_node_expected(timeout_node_id, value_type_long))
        return FALSE; // timeout argument supplied but could not parse to long
    
    return TRUE;
}

You can probably guess what this third argument and its type is. To confirm its meaning, here is a snippet from sleep_until's evaluation function:

CPU Disasm
Address   Hex dump              Command                                             Comments
00489980  |.  8B00              MOV EAX,DWORD PTR DS:[EAX]                          ; EAX <- timeout (3rd argument)
00489982  |.  83F8 FF           CMP EAX,-1
00489985  |.  74 0E             JE SHORT 00489995                                   ; never timeout!
00489987  |.  8B12              MOV EDX,DWORD PTR DS:[EDX]                          ; EDX <- time of function call in ticks
00489989  |.  03D0              ADD EDX,EAX                                         ; EDX <- timeout + function_call_time
0048998B  |.  A1 6C1D6F00       MOV EAX,DWORD PTR DS:[Globals::lpGameTimeGlobals]
00489990  |.  3950 0C           CMP DWORD PTR DS:[EAX+0C],EDX                       ; lpGameTimeGlobals->game_ticks
00489993  |.  7D 77             JGE SHORT 00489A0C                                  ; jumps to exit sleep_until context if game_ticks >= (timeout + function_call_time)

The third argument is a timeout, in ticks relative to the time when sleep_until would be called! An updated description for the function should resemble:

Quote

(sleep_until <boolean: condition> [<short: period>] [<long: timeout>])

Pauses execution of this script until the specified <condition> is true or (optionally) until the timeout is reached, checking once every <period> ticks.

The period and timeout are optional, defaulting to 30 [ticks] (1 second) and -1 (never times out), respectively - each specified in ticks.

If <timeout> is not -1, then the call to sleep_until returns on the first period after which at least <timeout> ticks have elapsed regardless of the <condition>.

Otherwise, if <timeout> is -1, then a call to this function will return only when the <condition> becomes true.

Example: (sleep_until false 15 3600) ; times out after 3600 ticks (2 minutes)

 

However, because Halo does not verify the number of arguments does not exceed 3, nor their type, Halo will gladly parse, compile, and evaluate the following:

(sleep_until false 15 3600 "foo" 3.14159265359)

 

Fake edit for those that read this post: you can paste text into the client console by pressing F6. I have no idea if this holds for Mac users, but I found this information out while completing documentation of the console line buffer structure. I am also unsure if this works while using HAC2.

Real edit: Turns out the timeout is not in absolute ticks, will slowly edit my post to reflect this (done).

Edited February 22, 2020 by PiRate
made note about BOOL in Cish code

[Vaporeon 224]

Nice, Interesting read.

[TCK 2164]

Definitely interesting. I have always understood the "period" to be how many times per second it checks, rather than an interval of ticks, if I am remembering correctly from the documentation; and that it defaults to once per second if no argument is given. In my experience putting "30" as the period gives much faster results (from stimulus to advancement, theoretically checking every tick) than leaving it default.

Edited February 24, 2020 by TCK

[PiRate 49]

I am unsure how to explain your experience with sleep_until's second parameter. Preliminary testing indicates that omitting the second parameter and setting it to 30 yield the same result. Additionally, evaluating (sleep_until false 1 90) produces 90 evaluations of the condition in 3 seconds, as expected.

Investigation into the code also corroborates this.

 

CPU Disasm
Address       Command                                              Comments
004898F3  |.  MOV EAX,DWORD PTR SS:[LOCAL.2]
004898F7  |.  MOV BYTE PTR DS:[EAX],0                              ; condition value, default 0 (false)
004898FA  |.  MOV EAX,DWORD PTR DS:[Globals::lpGameTimeGlobals]
004898FF  |.  MOV EAX,DWORD PTR DS:[EAX+0C]
00489902  |.  MOV DWORD PTR DS:[EDX],EAX                           ; sets call_time = lpGameTimeGlobals->game_ticks
00489904  |.  MOV EAX,DWORD PTR SS:[LOCAL.3]
00489908  |.  MOV WORD PTR DS:[EDI],0                              ; bool that is set when 2nd and 3rd args are evaluated/defaulted
0048990D  |.  MOV WORD PTR DS:[EBX],1E                             ; period, default 0x1E (30 decimal) ticks
00489912  |.  MOV DWORD PTR DS:[EAX],-1                            ; timeout, default -1

This snippet sets up the period to the value to 30, later taking on the value of the second argument when and if it is evaluated, and remains unchanged if the second argument is omitted.

 

As to how that argument is used:

CPU Disasm
Address       Command                                              Comments
004899BF  |.  MOV EAX,DWORD PTR SS:[LOCAL.1]                       ; EAX <- &period
004899C3  |.  MOV AX,WORD PTR DS:[EAX]                             ; AX <- period
004899C6  |.  CMP AX,1                                             ; AX <- max(period, (short)1)
004899CA  |.  JGE SHORT 004899D3                                   ; ^     ^
004899CC  |.  MOV EAX,1                                            ; ^     ^
004899D1  |.  JMP SHORT 004899D6                                   ; ^     ^
004899D3  |>  MOVSX EAX,AX                                         ; (long)max(period, (short)1)
004899D6  |>  MOV ECX,DWORD PTR DS:[Globals::lpGameTimeGlobals]
004899DC  |.  MOV EDX,DWORD PTR DS:[ECX+0C]                        ; lpGameTimeGlobals->game_ticks
004899DF  |.  MOV ECX,DWORD PTR SS:[LOCAL.3]
004899E3  |.  ADD EAX,EDX                                          ; EAX <- game_ticks + max(period, (short)1)
004899E5  |.  MOV DWORD PTR SS:[EBP+8],EAX                         ; lpThread->wake_tick = game_ticks + max(period, (short)1)

sleep_until's mechanism is implemented by setting a value that indicates to the script engine on what tick the script thread can be updated again, as shown here in the thread update function:

Address      Command                                              Comments
0048A410  |>  /MOV ECX,DWORD PTR DS:[ESI+8]                        ; ECX <- lpScriptThread->wake_tick
0048A413  |.  |TEST ECX,ECX
0048A415  |.  |JL 0048A4FC                                         ; stops thread update if lpThread->wake_tick < 0
0048A41B  |.  |MOV EAX,DWORD PTR DS:[Globals::lpGameTimeGlobals]
0048A420  |.  |CMP BYTE PTR DS:[EAX],0
0048A423  |.  |JE SHORT 0048A43C                                   ; skips time check if game is not ready
0048A425  |.  |MOV DL,BYTE PTR DS:[EAX+1]
0048A428  |.  |TEST DL,DL
0048A42A  |.  |JNZ SHORT 0048A433                                  ; skips time check if game is not running
0048A42C  |.  |MOV DL,BYTE PTR DS:[EAX+2]
0048A42F  |.  |TEST DL,DL
0048A431  |.  |JZ SHORT 0048A43C                                   ; skips time check if game is paused
0048A433  |>  |CMP ECX,DWORD PTR DS:[EAX+0C]                       ; cmp lpThread->wake_tick, lpGameTimeGlobals->game_ticks
0048A436  |.  |JG 0048A4FC                                         ; stops thread update if lpThread->wake_tick > lpGameTimeGlobals->game_ticks

Then, upon waking, the thread will check the condition again. If the condition evaluates to false, the thread is set to sleep another period ticks as indicated in the second snippet. Otherwise, if the condition evaluates to true, the script thread returns from the sleep_until call.

Edited February 24, 2020 by PiRate
silly dereference

[TCK 2164]

Hm I guess it's possible it was placebo. I could have sworn the original description I read of it specifically said, "checks <short> times per second if specified," but the Halo Scripting Bible doesn't say that so maybe I imagined it.

Edited February 24, 2020 by TCK

[DSalimander 214]

I had to do a workaround that accomplished this same result a few times for one of my scripts and hated it. Wasted variables and extra scripts to track the time. Very cool that this function exists. Nice work.