GFByteCursor¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/foundation/binary/gf_byte_cursor.gd - 模块：
Standard - 继承：
RefCounted - API：
public - 类别：值对象 (
value_object) - 首次版本：
7.0.0
PackedByteArray 读写游标。 提供边界检查、显式字节序和 varuint 编码，适合网络包、存档片段、 二进制配置或工具导入器复用。它只处理字节游标，不规定协议字段或消息语义。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 属性 | little_endian |
var little_endian: bool = false |
| 属性 | max_read_byte_count |
var max_read_byte_count: int = _DEFAULT_MAX_READ_BYTE_COUNT |
| 方法 | _init |
func _init(source_bytes: PackedByteArray = PackedByteArray(), p_little_endian: bool = false) -> void: |
| 方法 | from_bytes |
static func from_bytes(source_bytes: PackedByteArray, offset: int = 0, p_little_endian: bool = false) -> GFByteCursor: |
| 方法 | reset |
func reset(source_bytes: PackedByteArray = PackedByteArray()) -> void: |
| 方法 | get_bytes |
func get_bytes() -> PackedByteArray: |
| 方法 | get_position |
func get_position() -> int: |
| 方法 | set_position |
func set_position(offset: int) -> bool: |
| 方法 | size |
func size() -> int: |
| 方法 | remaining |
func remaining() -> int: |
| 方法 | is_eof |
func is_eof() -> bool: |
| 方法 | has_bytes |
func has_bytes(byte_count: int) -> bool: |
| 方法 | read_u8 |
func read_u8() -> int: |
| 方法 | read_i8 |
func read_i8() -> int: |
| 方法 | try_read_u8 |
func try_read_u8() -> Dictionary: |
| 方法 | try_read_i8 |
func try_read_i8() -> Dictionary: |
| 方法 | read_u16 |
func read_u16() -> int: |
| 方法 | read_i16 |
func read_i16() -> int: |
| 方法 | try_read_u16 |
func try_read_u16() -> Dictionary: |
| 方法 | try_read_i16 |
func try_read_i16() -> Dictionary: |
| 方法 | read_u32 |
func read_u32() -> int: |
| 方法 | read_i32 |
func read_i32() -> int: |
| 方法 | try_read_u32 |
func try_read_u32() -> Dictionary: |
| 方法 | try_read_i32 |
func try_read_i32() -> Dictionary: |
| 方法 | read_var_uint |
func read_var_uint() -> int: |
| 方法 | try_read_var_uint |
func try_read_var_uint() -> Dictionary: |
| 方法 | read_bytes |
func read_bytes(byte_count: int) -> PackedByteArray: |
| 方法 | try_read_bytes |
func try_read_bytes(byte_count: int) -> Dictionary: |
| 方法 | read_utf8 |
func read_utf8(byte_count: int) -> String: |
| 方法 | try_read_utf8 |
func try_read_utf8(byte_count: int) -> Dictionary: |
| 方法 | read_var_utf8 |
func read_var_utf8() -> String: |
| 方法 | try_read_var_utf8 |
func try_read_var_utf8() -> Dictionary: |
| 方法 | write_u8 |
func write_u8(value: int) -> void: |
| 方法 | write_i8 |
func write_i8(value: int) -> void: |
| 方法 | write_u16 |
func write_u16(value: int) -> void: |
| 方法 | write_i16 |
func write_i16(value: int) -> void: |
| 方法 | write_u32 |
func write_u32(value: int) -> void: |
| 方法 | write_i32 |
func write_i32(value: int) -> void: |
| 方法 | write_var_uint |
func write_var_uint(value: int) -> bool: |
| 方法 | write_bytes |
func write_bytes(value: PackedByteArray) -> void: |
| 方法 | write_utf8 |
func write_utf8(value: String) -> void: |
| 方法 | write_var_utf8 |
func write_var_utf8(value: String) -> bool: |
| 方法 | get_last_error |
func get_last_error() -> Error: |
| 方法 | clear_error |
func clear_error() -> void: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
属性¶
little_endian¶
- API：
public - 首次版本：
7.0.0
是否使用小端读写多字节整数。false 表示大端。
max_read_byte_count¶
- API：
public - 首次版本：
7.0.0
单次读取允许的最大字节数。小于等于 0 表示不限制。
方法¶
_init¶
- API：
public - 首次版本：
7.0.0
func _init(source_bytes: PackedByteArray = PackedByteArray(), p_little_endian: bool = false) -> void:
构造字节游标。
参数：
| 名称 | 说明 |
|---|---|
source_bytes |
初始字节。 |
p_little_endian |
是否使用小端。 |
from_bytes¶
- API：
public - 首次版本：
7.0.0
static func from_bytes(source_bytes: PackedByteArray, offset: int = 0, p_little_endian: bool = false) -> GFByteCursor:
从字节创建游标。
参数：
| 名称 | 说明 |
|---|---|
source_bytes |
初始字节。 |
offset |
初始位置。 |
p_little_endian |
是否使用小端。 |
返回：新游标。
reset¶
- API：
public - 首次版本：
7.0.0
替换内部字节并重置位置。
参数：
| 名称 | 说明 |
|---|---|
source_bytes |
新字节。 |
get_bytes¶
- API：
public - 首次版本：
7.0.0
获取字节副本。
返回：当前字节副本。
get_position¶
- API：
public - 首次版本：
7.0.0
获取当前位置。
返回：当前位置。
set_position¶
- API：
public - 首次版本：
7.0.0
设置当前位置。
参数：
| 名称 | 说明 |
|---|---|
offset |
新位置。 |
返回：设置成功返回 true。
size¶
- API：
public - 首次版本：
7.0.0
获取总字节数。
返回：总长度。
remaining¶
- API：
public - 首次版本：
7.0.0
获取剩余可读字节数。
返回：剩余长度。
is_eof¶
- API：
public - 首次版本：
7.0.0
是否已经到达末尾。
返回：到达末尾返回 true。
has_bytes¶
- API：
public - 首次版本：
7.0.0
检查是否还能读取指定长度。
参数：
| 名称 | 说明 |
|---|---|
byte_count |
字节数。 |
返回：可读取返回 true。
read_u8¶
- API：
public - 首次版本：
7.0.0
读取一个无符号 8 位整数。
返回：读取到的值；越界时返回 0。
read_i8¶
- API：
public - 首次版本：
7.0.0
读取一个有符号 8 位整数。
返回：读取到的值；越界时返回 0。
try_read_u8¶
- API：
public - 首次版本：
7.0.0
尝试读取一个无符号 8 位整数，并返回结构化报告。
返回：读取报告。
结构：
return: Dictionary withok: bool,value: int,error: int,position: int,next_position: int.
try_read_i8¶
- API：
public - 首次版本：
7.0.0
尝试读取一个有符号 8 位整数，并返回结构化报告。
返回：读取报告。
结构：
return: Dictionary withok: bool,value: int,error: int,position: int,next_position: int.
read_u16¶
- API：
public - 首次版本：
7.0.0
读取一个无符号 16 位整数。
返回：读取到的值；越界时返回 0。
read_i16¶
- API：
public - 首次版本：
7.0.0
读取一个有符号 16 位整数。
返回：读取到的值；越界时返回 0。
try_read_u16¶
- API：
public - 首次版本：
7.0.0
尝试读取一个无符号 16 位整数，并返回结构化报告。
返回：读取报告。
结构：
return: Dictionary withok: bool,value: int,error: int,position: int,next_position: int.
try_read_i16¶
- API：
public - 首次版本：
7.0.0
尝试读取一个有符号 16 位整数，并返回结构化报告。
返回：读取报告。
结构：
return: Dictionary withok: bool,value: int,error: int,position: int,next_position: int.
read_u32¶
- API：
public - 首次版本：
7.0.0
读取一个无符号 32 位整数。
返回：读取到的值；越界时返回 0。
read_i32¶
- API：
public - 首次版本：
7.0.0
读取一个有符号 32 位整数。
返回：读取到的值；越界时返回 0。
try_read_u32¶
- API：
public - 首次版本：
7.0.0
尝试读取一个无符号 32 位整数，并返回结构化报告。
返回：读取报告。
结构：
return: Dictionary withok: bool,value: int,error: int,position: int,next_position: int.
try_read_i32¶
- API：
public - 首次版本：
7.0.0
尝试读取一个有符号 32 位整数，并返回结构化报告。
返回：读取报告。
结构：
return: Dictionary withok: bool,value: int,error: int,position: int,next_position: int.
read_var_uint¶
- API：
public - 首次版本：
7.0.0
读取 Godot int 可表达范围内的 varuint，使用 7-bit continuation 编码。
返回：读取到的值；损坏或越界时返回 0。
try_read_var_uint¶
- API：
public - 首次版本：
7.0.0
尝试读取 Godot int 可表达范围内的 varuint，并返回结构化报告。
返回：读取报告。
结构：
return: Dictionary withok: bool,value: int,error: int,position: int,next_position: int.
read_bytes¶
- API：
public - 首次版本：
7.0.0
读取指定长度的字节。
参数：
| 名称 | 说明 |
|---|---|
byte_count |
字节数。 |
返回：字节副本；越界时返回空数组。
try_read_bytes¶
- API：
public - 首次版本：
7.0.0
尝试读取指定长度的字节，并返回结构化报告。
参数：
| 名称 | 说明 |
|---|---|
byte_count |
字节数。 |
返回：读取报告。
结构：
return: Dictionary withok: bool,value: PackedByteArray,error: int,position: int,next_position: int.
read_utf8¶
- API：
public - 首次版本：
7.0.0
读取 UTF-8 字符串。
参数：
| 名称 | 说明 |
|---|---|
byte_count |
字节数。 |
返回：解码后的字符串。
try_read_utf8¶
- API：
public - 首次版本：
7.0.0
尝试读取 UTF-8 字符串，并返回结构化报告。
参数：
| 名称 | 说明 |
|---|---|
byte_count |
字节数。 |
返回：读取报告。
结构：
return: Dictionary withok: bool,value: String,error: int,position: int,next_position: int.
read_var_utf8¶
- API：
public - 首次版本：
7.0.0
读取 varuint 长度前缀的 UTF-8 字符串。
返回：解码后的字符串；长度或 UTF-8 校验失败时返回空字符串。
try_read_var_utf8¶
- API：
public - 首次版本：
7.0.0
尝试读取 varuint 长度前缀的 UTF-8 字符串，并返回结构化报告。
返回：读取报告。
结构：
return: Dictionary withok: bool,value: String,error: int,position: int,next_position: int.
write_u8¶
- API：
public - 首次版本：
7.0.0
写入一个无符号 8 位整数。
参数：
| 名称 | 说明 |
|---|---|
value |
要写入的值。 |
write_i8¶
- API：
public - 首次版本：
7.0.0
写入一个有符号 8 位整数。
参数：
| 名称 | 说明 |
|---|---|
value |
要写入的值。 |
write_u16¶
- API：
public - 首次版本：
7.0.0
写入一个无符号 16 位整数。
参数：
| 名称 | 说明 |
|---|---|
value |
要写入的值。 |
write_i16¶
- API：
public - 首次版本：
7.0.0
写入一个有符号 16 位整数。
参数：
| 名称 | 说明 |
|---|---|
value |
要写入的值。 |
write_u32¶
- API：
public - 首次版本：
7.0.0
写入一个无符号 32 位整数。
参数：
| 名称 | 说明 |
|---|---|
value |
要写入的值。 |
write_i32¶
- API：
public - 首次版本：
7.0.0
写入一个有符号 32 位整数。
参数：
| 名称 | 说明 |
|---|---|
value |
要写入的值。 |
write_var_uint¶
- API：
public - 首次版本：
7.0.0
写入 Godot int 可表达范围内的 varuint，使用 7-bit continuation 编码。
参数：
| 名称 | 说明 |
|---|---|
value |
非负整数。 |
返回：写入成功返回 true。
write_bytes¶
- API：
public - 首次版本：
7.0.0
写入字节数组。
参数：
| 名称 | 说明 |
|---|---|
value |
要追加的字节。 |
write_utf8¶
- API：
public - 首次版本：
7.0.0
写入 UTF-8 字符串。
参数：
| 名称 | 说明 |
|---|---|
value |
要写入的字符串。 |
write_var_utf8¶
- API：
public - 首次版本：
7.0.0
写入 varuint 长度前缀的 UTF-8 字符串。
参数：
| 名称 | 说明 |
|---|---|
value |
要写入的字符串。 |
返回：写入成功返回 true。
get_last_error¶
- API：
public - 首次版本：
7.0.0
获取最近错误码。
返回：最近错误码。
clear_error¶
- API：
public - 首次版本：
7.0.0
清除最近错误码。
get_debug_snapshot¶
- API：
public - 首次版本：
7.0.0
获取调试快照。
返回：调试快照。
结构：
return: Dictionary，包含 size、position、remaining、little_endian 和 last_error。