Expand description
A bounded reader over a byte slice with the semantics of UnityPy’s
EndianBinaryReader: the memory reader, EndianBinaryReader_Memoryview
(streams/EndianBinaryReader.py:231-284), or the stream reader,
EndianBinaryReader_Streamable (:287-324), which UnityPy reads a file
it loads from a path with (ReaderKind; kind’s module docs list
what it reads that way and its rules).
Container and metadata parsers read through it; the value walker has its
own cursor (UnityPyBoost’s bounds rule differs, plan section 3.10), which
takes the same ReaderKind. No method panics: every read UnityPy
refuses is an Error::OutOfBounds, or the stream reader’s
StreamRefusal as an Error::Malformed.
Positions are signed (plan section 3.3). A Python Position is an
unbounded integer that UnityPy moves with plain arithmetic, so on the
memory reader it can go negative (a negative node_count in
parse_blob, file_size - metadata_size below format 9, Length - compressedSize for blocks-info at the end, a negative TypelessData
length on the pure-Python path) or past the end, and the reads after it
go on with Python’s rules, which this module’s helpers implement once
and an oracle fixture pins (tests/fixtures/scaffold/reader.json, from
tools/fixtures/scaffold.py):
py_read:read(n), a Python slice (negative indexes count from the end; a reversed range is empty); the position moves bynwhatever the slice held;py_unpack_from: every fixed-width read of 2, 4 or 8 bytes isstruct.unpack_from(view, Position)(:340-343): a negative offset counts from the end, and the read must fit;- one-byte reads (
read_u8,read_i8,read_bool) areunpack(fmt, read(1))(:93-97,:126-127): the slice ofpy_readmust hold exactly one byte, and the position has moved by 1 even when it raises (at-1,view[-1:0]is empty); py_align:align_stream, Python’s floor modulo (-7aligns to-4);py_string_to_null:re.searchclamps its start and end into the buffer, a hit sets the absolute position after the NUL, and a miss readsmax_lengthbytes as a slice unlesspos + max_length >= len.
The stream reader’s position is never negative and stops at the end; the
same fixture pins its rules (its stream_ cases), which ReaderKind
implements.
Owner: package C. The free functions and Reader::read_i32_array are
the scaffold’s (implemented).
Structs§
- Reader
- A cursor over
data, read by the rules of one of UnityPy’s readers (ReaderKind). Positions are absolute withindataand signed, as a PythonPosition(module docs): on the memory reader every read follows the helper of its Python primitive at whatever position it is, negative or past the end; the stream reader’s position is never negative. - Short
Array - What
read(N)returns where UnityPy keeps the bytes as they are (a GUID, a hash): thepy_readslice, inline. It holdsNbytes, or fewer where the slice is short: none at a position in-N..0(the sliceview[p:p+N]runs from the end back to the start, so it is empty, though the position moves top + N), the rest at the end.
Enums§
- Endian
- Byte order of a reader or a file.
- Reader
Kind - Which of UnityPy’s readers a file is read with (module docs).
- Stream
Refusal - An exception the stream reader raises where the memory reader reads on (module docs). Its text is UnityPy’s message.
Constants§
- STREAM_
READER - The
whatof ancrate::Error::MalformedaStreamRefusalbecomes. - STRING_
TO_ NULL_ WINDOW read_string_to_null’s defaultmax_length(EndianBinaryReader.py:275). Within the window the string runs to its NUL. With no NUL in the window it is cut at the window when more bytes follow, and raises otherwise.
Functions§
- py_
align align_stream(n)(streams/EndianBinaryReader.py:155-156):pos + (n - pos % n) % nwith Python’s floor modulo, so a negative position aligns towards zero (-7to-4forn = 4).n0 leaves the position (Python would raise; no caller passes 0). Implemented by the scaffold.- py_read
- The memoryview reader’s
read(size)atposoverlenbytes (streams/EndianBinaryReader.py:249-256), with Python’s arithmetic: size 0 reads nothing and leaves the position; size -1 reads to the end; any other size is the sliceview[pos : pos + size], where a negative index counts from the end, indexes clamp to0..=lenand a reversed range is empty. Returns the byte range and the new position,pos + size(lenfor -1), which may be negative or past the end, as a PythonPositioncan be. A bundle entry (File.py:78-81),parse_blob’s node area and string buffer, and the pure-Python reader’sTypelessDataall read this way (plan section 3.6). Implemented by the scaffold. - py_
string_ to_ null read_string_to_null(max_length)of the memoryview reader (streams/EndianBinaryReader.py:275-284) atposoverdata: the string’s byte range and the new position, orNonewhere it raises (“String not terminated”).re.search(view, pos, pos + max_length)clamps both bounds into0..=len(py_string_window), so a negative start searches from 0; a hit returns the bytes up to the first NUL in the window and sets the position after that NUL (an absolute index). With no NUL in the window it raises whenpos + max_length >= len, and otherwise returnsread(max_length), a slice fromposthat may hold a NUL or nothing at all (py_string_to_null_found, which a caller that indexed the buffer’s NULs answers with). Implemented by the scaffold.- py_
unpack_ from struct.unpack_from(fmt, view, pos)for a format ofnbytes overlenbytes (CPython’ss_unpack_from): the start index of the bytes it reads, orNonewhere it raisesstruct.error. A negativeposcounts from the end and must leave the whole read before the end (pos + n <= 0) and inside the buffer (pos + len >= 0). Every fixed-width read of 2, 4 or 8 bytes UnityPy’s memoryview reader makes through its own methods (reader.read_int()) takes this path, then moves the position byn(only on success). The pure-Python typetree reader’s primitive nodes do not: they read through the base class’sunpack(fmt, read(n))(walk::python, plan 3.10). Implemented by the scaffold.