DO/CTL/OpCodes
From Dark Omen Wiki
init_unit (00)
| Argument | Explanation |
|---|---|
| unk | unknown purpose |
This command initializes some data structures of the unit to it's default values. It should be used as the first command called by a unit script.
wait_for_deploy (01)
Blocks the execution of the units script until the deployment phase is finished.
In the deployment phase it sets bit 31 of unit flag 1. At the end of the phase it clears the bit.
reset_call_stack (02)
Resets the units stack. Don't call this when you have to return from a function or are in a loop.
restore_ip (03)
Restores the state saved with save_ip (execution continues after the save_ip call). All events get marked as handled so unhandled events are lost.
save_ip (04)
Stores the current state of the instruction pointer (current function, position in function, number of free stack slots). Note that the stack itself is not saved!
do (05)
Begins a do-loop (pushes position of next opcode on the stack). This loop is always executed at least once.
always (06)
Usually used at the end of a do-loop. Pops from the stack and continues script execution at this position (this is usually the command following the do-statement).
while (07)
Usually used at the end of a do-loop. Pops from the stack and checks the conditional flag:
| Condition | Result |
|---|---|
| true | Continue execution at stack position |
| false | Continue execution with command after while |
while_not (08)
Usually used at the end of a do-loop. Pops from the stack and checks the conditional flag:
| Condition | Result |
|---|---|
| true | Continue execution with command after while_not |
| false | Continue execution at stack position |
for (09)
Begins a for-loop.
| Argument | Explanation |
|---|---|
| num_loops | How often the loop shall be executed. |
Pushes two elements on the stack: The position of the next opcode and how often loop shall be executed.
next (0A)
Usually used at the end of a for-loop.
Pops the loop counter from the stack and decrements it by one. If it is higher then 0 it's pushed again and the execution continues after the for-command (2nd stack element). Otherwise the 2nd element is popped too and execution continues after the next-command.
goto (0B)
Continues execution at the beginning of a function.
| Argument | Explanation |
|---|---|
| func | Number of the function to execute |
Note that the call stack is not altered. So you shouldn't call this while you are in a loop because it leaves garbage on the stack (call reset_call_stack to clear the stack).
set_return_function_if_not_restart (0C)
Overwrites the function return_from_event_handler returns to by setting the "overwrite return"-flag in the control flag but only when the "restart funtion"-bit was not set.
| Argument | Explanation |
|---|---|
| func | Number of the function to execute |
set_return_function_if_true_and_not_restart (0D)
Overwrites the function return_from_event_handler returns to by setting the "overwrite return"-flag in the control flag but only when the "restart funtion"-flag was not set and the conditional flag indicated true.
| Argument | Explanation |
|---|---|
| func | Number of the function to execute |
set_return_function_with_restart (0E)
Overwrites the function return_from_event_handler returns to by setting the "overwrite return"-flag and the "restart function"-flag.
| Argument | Explanation |
|---|---|
| func | Number of the function to execute |
set_return_function_with_restart_if_true (0F)
Overwrites the function return_from_event_handler returns to by setting the "overwrite return"-flag and the "restart function"-flag if the conditional flag was true.
| Argument | Explanation |
|---|---|
| func | Number of the function to execute |
set_return_function_if_false_and_not_restart (10)
Overwrites the function return_from_event_handler returns to by setting the "overwrite return"-flag in the control flag but only when the "restart funtion"-flag was not set and the conditional flag indicated false.
| Argument | Explanation |
|---|---|
| func | Number of the function to execute |
call (11)
Calls a function (use with return).
| Argument | Explanation |
|---|---|
| func | Number of the function to execute |
Pushes the position of the next opcode and the current function on the stack.
return (12)
Continues execution directly after the call-command (Pops two elements from the stack (function and position)).
Don't call return while you are in a loop because the stack top contains the wrong element!
This function can also be used to return from an event handler (this command ignores the "overwrite return"-flag)
return_from_event_handler (13)
Like return but checks the the "overwrite return" and "restart function"-flag of the CTL control flag:
| Condition | Result |
|---|---|
| "overwrite return" not set | Behaves like a normal return. |
| "overwrite return" set | Returns to the function specified with one of the set_return_function-commands. If the return function is the same as the one on the stack it will behave like a normal return instead. |
| "overwrite return" and "restart function" set | Always returns to the function specified with one of the set_return_function-commands (the stack gets cleaned but the content is ignored). |
Don't call return_from_event_handler while you are in a loop because the stack top contains the wrong element!
sleep (15)
Pauses the script execution (script of next unit gets executed). Next time the execution continues with the command after sleep.
sleep_if_true (16)
Pauses the script execution based on the conditional flag:
| Condition | Result |
|---|---|
| true | Script of next unit is executed. Next time the execution continues with the command after sleep. |
| false | No sleep. Execution continues with the command after sleep_if_true |
skip_if_true (17)
Skips instructions based on the state of the conditional flag.
| Argument | Explanation |
|---|---|
| num_skip | How many commands to skip. This value must be 1 + number of arguments. E.g. if you want to skip a function that takes two arguments num_skip must be 3. |
| Condition | Result |
|---|---|
| true | num_skip commands are skipped |
| false | Execution continues with the next command |
set_timer (18)
Sets a timer for the unit (or overwrites the old). The timer decrements by 1 when the regiments script starts execution again.
| Argument | Explanation |
|---|---|
| timer | New value for the timer |
test_waiting_for_timer (19)
Sets the conditional flag to true if the timer is not 0.
wait_for_timer (1A)
Pauses script execution until the timer is not 0.
set_x_i (1B)
Sets the value of the unknown local register x (= purpose is unknown).
| Argument | Explanation |
|---|---|
| value | Sets x to value. |
add_x_i (1C)
Adds a value to the unknown local register x (= purpose is unknown).
| Argument | Explanation |
|---|---|
| value | Adds value to x. |
test_x_eq_0 (1D)
Sets the conditional flag to true if the unknown local register x is 0.
set_unit_r_i (1E)
Sets a local register to a value.
| Argument | Explanation |
|---|---|
| register | Local register to write |
| value | Sets register to value |
Every unit has 8 registers, so the register parameter should be from 1 to 8. Other values will overwrite other memory!
add_unit_r_i (1F)
Adds a value to a local registers value.
| Argument | Explanation |
|---|---|
| register | Local register to write |
| value | value added to value in register |
Every unit has 8 registers, so the register parameter should be from 1 to 8. Other values will overwrite other memory!
test_unit_r_eq_i (20)
Sets the conditional flag to true if the value in a units register equals a value.
| Argument | Explanation |
|---|---|
| register | Register to check |
| value | Value the registers value is compared against |
Use register -278 to check against the unit Id.
test_unit_r_eq_r (21)
Sets the conditional flag to true if two local registers contain the same value.
| Argument | Explanation |
|---|---|
| register1 | First register |
| register2 | Second register |
Use register -278 to check against the unit Id.
set_unit_r_random1to10 (22)
Assigns a "random" value (the value changes every second) in a range form 1 to 10 to a local register.
| Argument | Explanation |
|---|---|
| register | Register to write |
Every unit has 8 registers, so the register parameter should range from 1 to 8. Other values will overwrite other memory!
set_global_r_i (23)
Assigns a value to a global register.
| Argument | Explanation |
|---|---|
| register | Global register to write |
| value | Value to assign to the register |
There are 8 registers, so the register parameter should range from 1 to 8. Other values will overwrite other memory!
add_global_r_i (24)
Adds a value to the value in a global register.
| Argument | Explanation |
|---|---|
| register | Global register to write |
| value | Value to add to the registers value |
There are 8 registers, so the register parameter should range from 1 to 8. Other values will overwrite other memory!
test_global_r_eq_i (25)
Sets the conditional flag to true if the value in a global register equals a value.
| Argument | Explanation |
|---|---|
| register | Global register to test |
| value | Value to test against |
