0x02 — branch

Reads a branch word at SCR_DATA+0x0C. The high byte is a condition id. If nonzero, it reads the next 8 bytes as condition payload and calls CRadiScript::CheckCondition(unsigned char,unsigned long,const SCR_DATA*). If the condition passes, or if there is no condition id, it sign-extends the low 24 bits of the branch word as a relative word offset, writes the new cursor to SCR_DATA+0x0C, and returns 2.

proven— handler traced, and exercised by at least one shipped script.

At a glance

Opcode	`0x02` (2)
Handler	`CRadiScript::Command_02`
Signature	`CRadiScript::Command_02(int,SCR_DATA*,unsigned int,unsigned int)`
Translation unit	`r_script_run0.cpp`
Address	— debug build; click for all 3
Handler size	`0xB8` (184 bytes)
Family	Script control, flags and values
Command size	`4 + extra_words * 4` bytes

Documented forms

This opcode is documented under more than one name, one per branch of the handler. They are the same opcode and the same handler; which branch runs is chosen by the argument byte or a control word.

Form	Engine name	What it does
`branch`	—	Jumps to a label, unconditionally or when a condition holds.
`if_flag`	—	Jumps when a game flag matches. Written as a block, it runs the block instead of jumping.
`if_value`	—	Jumps when a script event value matches. Written as a block, it runs the block instead of jumping.
`jump`	—	Jumps to a label unconditionally.
`unless_flag`	—	Jumps when a game flag does not match - the opposite of if_flag.
`unless_value`	—	Jumps when a script event value does not match - the opposite of if_value.

Handler behaviour

Encoding

The command header is one 32-bit word, as described in §3 Instruction encoding:

 31            24 23            16 15             8 7              0
+----------------+----------------+----------------+----------------+
|  flags         |  argument byte |  extra words   |  0x02          |
+----------------+----------------+----------------+----------------+

Bits 8–15 give the number of 32-bit operand words that follow. Bits 16–23 are handed to the handler as a bitfield; on character commands bit 0 normally says whether a character selector word is present. Bit 31 is the keep-going bit.

Operand fields

41 documented fields. input fields are read from the command's operand words; derived fields are computed from other fields rather than stored separately.

Field	Role	Meaning
`category_selector`	input	Selects which `category` the handler acts on.
`character`	input	The packed 32-bit character selector word. Its low half is the character id and byte 2 is a secondary class/variant input; see `character_number` and `character_variant`.
`character_raw`	input	Raw field preserved verbatim; its meaning is not yet traced.
`character_source`	input	Where `character` is read from.
`compare_control`	input	Bitmask controlling which optional `compare` values follow.
`compare_from_event`	input	Whether `compare` is read from an event value instead of being a literal on this line.
`cond_base`	input	Low 7 bits of `condition`: which condition is evaluated.
`condition`	input	Condition selector byte. The low 7 bits pick the condition (`cond_base`) and bit 7 inverts the result (`invert`). `0` means unconditional.
`condition_args`	input	The condition's operand words, kept verbatim when no structured form applies.
`condition_word1`	input	Word 1 of the packed `condition` entry.
`count`	input	How many entries this command carries.
`event_value`	input	Script event-value id that the condition or command reads.
`expected`	input	Value the condition compares against.
`first_flag`	input	Id of the first event flag the condition reads.
`flag`	input	Config/event flag id this line reads or writes.
`flag_count`	input	How many `flag` entries follow on this line.
`goto`	input	Label to jump to when the condition holds (or always, for `jump`).
`invert`	input	Bit 7 of `condition`: when `1` the condition result is inverted.
`is`	input	Jump when the tested value equals this.
`item_or_state`	input	Item or object-state operand, depending on the selector on this line.
`item_or_state_selector`	input	Selects which `item or state` the handler acts on.
`kind`	derived	Readable name for the variant this line selects, derived from its selector byte. It is cross-checked on compile, so it cannot disagree with the selector.
`lookup_mode`	derived	Mode selector for `lookup`; the handler branches on it.
`lookup_script_id`	input	Identifier selecting which `lookup script` to use.
`mask_mode`	input	Mode selector for `mask`; the handler branches on it.
`object_state_selector`	input	Selects which `object state` the handler acts on.
`property_offset`	derived	Offset applied to `property`.
`property_selector`	input	Selects which `property` the handler acts on.
`required_mask`	input	Bitmask selecting which parts of `required` apply.
`requires_all`	derived	Whether every `all` must match rather than any one of them.
`script_lookup_control`	input	Bitmask controlling which optional `script lookup` values follow.
`selector`	input	Sub-selector byte choosing which variant of the command's behaviour runs.
`state_selector`	input	Selects which `state` the handler acts on.
`status_selector`	input	Selects which `status` the handler acts on.
`target`	input	Label this branch jumps to.
`time_component_mask`	derived	Bitmask selecting which parts of `time component` apply.
`time_components`	derived	Human-readable breakdown of the compared time value.
`time_control`	input	Bitmask controlling which optional `time` values follow.
`time_source_selector`	derived	Selects which `time source` the handler acts on.
`value`	input	The value the condition compares against.
`yield`	derived	Pause the script here for one game frame; the next command runs on the following update. Lines without it keep running immediately.

Engine calls

Engine functions this handler was observed calling:

CRadiScript::CheckCondition(unsigned char,unsigned long,const SCR_DATA*)

Bit masks

Masks the handler applies to its argument byte or operand words:

0x00FF