0x04 — script_start

Script start/inline-call helper. It can check a condition, call SetScriptNumber, set default character/object names, copy script data, and run StepProcess.

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

At a glance

Opcode	`0x04` (4)
Handler	`CRadiScript::Command_04`
Signature	`CRadiScript::Command_04(int,SCR_DATA*,unsigned int,unsigned int)`
Translation unit	`r_script_run0.cpp`
Address	— debug build; click for all 3
Handler size	`0x3BC` (956 bytes)
Engine name	`script_start`
Family	Script control, flags and values
Command size	`4 + extra_words * 4` bytes

Handler behaviour

Script start/inline-call helper. It can check a condition, call SetScriptNumber, set default character/object names, copy script data, and run StepProcess.

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   |  0x04          |
+----------------+----------------+----------------+----------------+

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

16 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
`arg`	derived	Raw handler argument byte from the command header. It is printed only when it differs from the value the named fields already imply, so seeing it means the command uses an unusual argument encoding.
`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_number`	input	Low 16 bits of the character selector: the character/actor id.
`character_type`	input	Byte 2 of the character selector, where the handler treats it as a type selector rather than a variant.
`cond_base`	derived	Low 7 bits of `condition`: which condition is evaluated.
`condition`	derived	Condition selector byte. The low 7 bits pick the condition (`cond_base`) and bit 7 inverts the result (`invert`). `0` means unconditional.
`default_char`	derived	Character used when the line does not name one explicitly.
`inherit_character`	derived	The started script uses this script's default character instead of its own.
`inherit_values`	derived	The started script inherits this script's event values.
`invert`	input	Bit 7 of `condition`: when `1` the condition result is inverted.
`lookup_script_id`	input	Identifier selecting which `lookup script` to use.
`mode`	input	Handler path selector taken from the argument byte. The meaning is specific to each command.
`script_id`	input	Which script inside the currently loaded event file to start — the handler calls SetScriptNumber, not LoadScriptFile. In file 516, `script_id=5` means 516_05. Use `load_script_file` first to switch files.
`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.
`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*)
CRadiScript::GetAbstractionCharacterNumber(unsigned int&,unsigned int&,const SCR_DATA*)
CRadiScript::SetDefaultCharacter(unsigned int,unsigned int,unsigned int)
CRadiScript::SetDefaultObjectName(int,const char*)
CRadiScript::SetScriptNumber(int,unsigned int,unsigned int,unsigned int,unsigned int,float)
CRadiScript::StepProcess(SCR_DATA*,int)
GetAbstractionCharacterNumber(unsigned int&)
memcpy

Bit masks

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

0x000F 0x00FF 0xFFFF 0x0010 0x0001 0x0002 0x0004 0x0008 0x0080