module documentation

Disassemble NCS (compiled script) files.

While the language bytecode is principally game-agnostic, the supported opcodes describe the default NWN:EE instruction set.

Class Auxcode Undocumented
Class Instr Undocumented
Class Opcode Undocumented
Function disasm Disassembles bytecode from a file-ish.
Function read_extra Parses additional data based on the opcode and auxiliary code.
Function read_instr Reads an instruction from the given input stream.
Constant _AUXCODE_TO_CANONICAL Undocumented
Constant _NCS_HEADER Undocumented
Constant _OPCODE_TO_CANONICAL Undocumented
def disasm(file: BinaryIO): (source)

Disassembles bytecode from a file-ish.

Skips any encountered NCS header as a convenience.

Parameters
file:BinaryIOA file-ish containing the bytecode to disassemble.
Yields
InstrThe next instruction read from the bytecode stream.
def read_extra(file: BinaryIO, op: Opcode, aux: Auxcode) -> tuple: (source)

Parses additional data based on the opcode and auxiliary code.

Note: This will re-parse embedded extra data every time it's called: For example, JSON payloads will be evaluated.

Parameters
file:BinaryIOA binary stream from which to read the data.
op:OpcodeThe opcode of the instruction.
aux:AuxcodeThe auxiliary code providing additional context for the operation.
Returns
tupleA variable length tuple containing the parsed data, or empty.
Raises
struct.errorIf the data cannot be read from the stream.
ValueErrorVarious error conditions.
def read_instr(file: BinaryIO) -> Instr: (source)

Reads an instruction from the given input stream.

Parameters
file:BinaryIOA binary stream from which the instruction is read.
Returns
InstrThe instruction read from the input stream.
Raises
struct.errorIf the data cannot be read from the stream.
ValueErrorIf the opcode or auxiliary code is invalid.
_NCS_HEADER: bytes = (source)

Undocumented

Value
b'NCS V1.0'
_OPCODE_TO_CANONICAL = (source)

Undocumented

Value
{Opcode.ASSIGNMENT: 'CPDOWNSP',
 Opcode.RUNSTACK_ADD: 'RSADD',
 Opcode.RUNSTACK_COPY: 'CPTOPSP',
 Opcode.CONSTANT: 'CONST',
 Opcode.EXECUTE_COMMAND: 'ACTION',
 Opcode.LOGICAL_AND: 'LOGAND',
 Opcode.LOGICAL_OR: 'LOGOR',
...