Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
PackedByteArray
字节紧缩数组。
描述
一种专门用来存放字节（byte）的数组。它对数据进行了紧密打包，因此在数组规模很大时能有效节省内存。PackedByteArray 还提供了多种方法，用于将各种类型的数据编码为字节，或者从字节中解码出数据。
这些数值的编码方式属于内部实现细节，在与外部应用程序交互时，不应对其产生依赖。
注意： 打包数组（Packed arrays）始终是通过引用传递的。如果想获取一个可以独立于原数组进行修改的副本，请使用 duplicate() 方法。不过，内置属性和方法不属于这种情况。在这些情况下，返回的打包数组是一个副本，修改它不会影响原始值。如果要更新这种类型的内置属性，需要先修改返回的数组，然后再将其重新赋值给该属性。
注意： 在布尔值（boolean）语境下，如果打包数组为空，它的求值结果为 false；否则，打包数组的求值结果始终为 true。
备注
通过 C# 使用该 API 时会有显著不同，详见 C# API 与 GDScript 的差异。
构造函数
PackedByteArray(from: PackedByteArray) |
|
PackedByteArray(from: Array) |
方法
void |
append_array(array: PackedByteArray) |
void |
|
void |
|
void |
|
void |
clear() |
decode_double(byte_offset: int) const |
|
decode_float(byte_offset: int) const |
|
decode_half(byte_offset: int) const |
|
decode_s16(byte_offset: int) const |
|
decode_s32(byte_offset: int) const |
|
decode_s64(byte_offset: int) const |
|
decode_u16(byte_offset: int) const |
|
decode_u32(byte_offset: int) const |
|
decode_u64(byte_offset: int) const |
|
decode_var(byte_offset: int, allow_objects: bool = false) const |
|
decode_var_size(byte_offset: int, allow_objects: bool = false) const |
|
decompress(buffer_size: int, compression_mode: int = 0) const |
|
decompress_dynamic(max_output_size: int, compression_mode: int = 0) const |
|
duplicate() const |
|
void |
encode_double(byte_offset: int, value: float) |
void |
encode_float(byte_offset: int, value: float) |
void |
encode_half(byte_offset: int, value: float) |
void |
|
void |
encode_s16(byte_offset: int, value: int) |
void |
encode_s32(byte_offset: int, value: int) |
void |
encode_s64(byte_offset: int, value: int) |
void |
|
void |
encode_u16(byte_offset: int, value: int) |
void |
encode_u32(byte_offset: int, value: int) |
void |
encode_u64(byte_offset: int, value: int) |
encode_var(byte_offset: int, value: Variant, allow_objects: bool = false) |
|
void |
|
get_string_from_ascii() const |
|
get_string_from_multibyte_char(encoding: String = "") const |
|
get_string_from_utf8() const |
|
get_string_from_utf16() const |
|
get_string_from_utf32() const |
|
get_string_from_wchar() const |
|
has_encoded_var(byte_offset: int, allow_objects: bool = false) const |
|
hex_encode() const |
|
is_empty() const |
|
void |
|
void |
reverse() |
void |
|
size() const |
|
void |
sort() |
to_color_array() const |
|
to_float32_array() const |
|
to_float64_array() const |
|
to_int32_array() const |
|
to_int64_array() const |
|
to_vector2_array() const |
|
to_vector3_array() const |
|
to_vector4_array() const |
运算符
operator !=(right: PackedByteArray) |
|
operator +(right: PackedByteArray) |
|
operator ==(right: PackedByteArray) |
|
operator [](index: int) |
构造函数说明
PackedByteArray PackedByteArray() 🔗
构造空的 PackedByteArray。
PackedByteArray PackedByteArray(from: PackedByteArray)
构造给定 PackedByteArray 的副本。
PackedByteArray PackedByteArray(from: Array)
构造新 PackedByteArray。你还可以传入通用 Array 进行转换。
方法说明
向数组末尾追加一个元素（push_back() 的别名）。
void append_array(array: PackedByteArray) 🔗
在该数组的末尾追加一个 PackedByteArray。
int bsearch(value: int, before: bool = true) const 🔗
使用二进法查找已有值的索引（如果该值尚未存在于数组中，则为保持排序顺序的插入索引）。传递 before 说明符是可选的。如果该参数为 false，则返回的索引位于数组中该值的所有已有的条目之后。
注意：在未排序的数组上调用 bsearch() 会产生预料之外的行为。
void bswap16(offset: int = 0, count: int = -1) 🔗
对数组中从偏移量为 offset 处开始的 count 个 16 位段落进行字节顺序交换的操作。交换是原地进行的。如果 count 小于零，则会处理到数组结尾为止，如果处理的数据大小不是 2 的倍数，则处理的最后一个 16 位段落之后的字节不会发生修改。
void bswap32(offset: int = 0, count: int = -1) 🔗
对数组中从偏移量为 offset 处开始的 count 个 32 位段落进行字节顺序交换的操作。交换是原地进行的。如果 count 小于零，则会处理到数组结尾为止，如果处理的数据大小不是 4 的倍数，则处理的最后一个 32 位段落之后的字节不会发生修改。
void bswap64(offset: int = 0, count: int = -1) 🔗
对数组中从偏移量为 offset 处开始的 count 个 64 位段落进行字节顺序交换的操作。交换是原地进行的。如果 count 小于零，则会处理到数组结尾为止，如果处理的数据大小不是 8 的倍数，则处理的最后一个 64 位段落之后的字节不会发生修改。
void clear() 🔗
清空数组。相当于调用 resize() 时指定大小为 0。
PackedByteArray compress(compression_mode: int = 0) const 🔗
返回新的 PackedByteArray，其中的数据已压缩。请将压缩模式设置为 CompressionMode 常量。
返回元素在数组中出现的次数。
float decode_double(byte_offset: int) const 🔗
将字节序列解码为 64 位浮点数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
float decode_float(byte_offset: int) const 🔗
将字节序列解码为 32 位浮点数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
float decode_half(byte_offset: int) const 🔗
将字节序列解码为 16 位浮点数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_s8(byte_offset: int) const 🔗
将字节序列解码为 8 位有符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_s16(byte_offset: int) const 🔗
将字节序列解码为 16 位有符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_s32(byte_offset: int) const 🔗
将字节序列解码为 32 位有符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_s64(byte_offset: int) const 🔗
将字节序列解码为 64 位有符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_u8(byte_offset: int) const 🔗
将字节序列解码为 8 位无符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_u16(byte_offset: int) const 🔗
将字节序列解码为 16 位无符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_u32(byte_offset: int) const 🔗
将字节序列解码为 32 位无符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_u64(byte_offset: int) const 🔗
将字节序列解码为 64 位无符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
Variant decode_var(byte_offset: int, allow_objects: bool = false) const 🔗
将字节序列解码为 Variant，起始位置字节偏移量为 byte_offset。如果无法解码有效的变体，或者其值派生自 Object 而 allow_objects 为 false，则返回 null。
int decode_var_size(byte_offset: int, allow_objects: bool = false) const 🔗
将字节序列解码为 Variant 的大小，起始位置字节偏移量为 byte_offset。要求起始位置后至少有 4 个字节的数据，否则会失败。
PackedByteArray decompress(buffer_size: int, compression_mode: int = 0) const 🔗
返回新的 PackedByteArray，其中的数据已解压。请将 buffer_size 设置为数据解压后的大小。请将压缩模式设置为 CompressionMode 常量。
注意：不保证解压缩可以处理未经 Godot 压缩的数据，例如，如果使用 deflate 压缩模式压缩的数据缺少校验和或标头。
PackedByteArray decompress_dynamic(max_output_size: int, compression_mode: int = 0) const 🔗
返回新的 PackedByteArray，其中的数据已解压。请将压缩模式设置为 CompressionMode 常量。这个方法只接受 brotli、gzip 和 deflate 压缩模式。
这个方法可能比 decompress() 慢，因为在解压时可能需要多次重新分配输出缓冲区，而 decompress() 则在一开始就知道输出缓冲区的大小。
GZIP 的最大压缩率为 1032:1，这意味着较小的压缩后负载很有可能解压出非常巨大的输出。为了防止这种情况，你可以通过 max_output_size 提供允许这个函数分配的最大字节数。传入 -1 则不限制输出。传入正数且解压超过该字节数时，会返回错误。
注意：不保证解压缩可以处理未经 Godot 压缩的数据，例如，如果使用 deflate 压缩模式压缩的数据缺少校验和或标头。
PackedByteArray duplicate() const 🔗
创建该数组的副本，并将该副本返回。
void encode_double(byte_offset: int, value: float) 🔗
将 64 位浮点数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 8 个字节的空间。
void encode_float(byte_offset: int, value: float) 🔗
将 32 位浮点数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 4 个字节的空间。
void encode_half(byte_offset: int, value: float) 🔗
将 16 位浮点数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 2 个字节的空间。
void encode_s8(byte_offset: int, value: int) 🔗
将 8 位有符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 1 个字节的空间。
void encode_s16(byte_offset: int, value: int) 🔗
将 16 位有符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 2 个字节的空间。
void encode_s32(byte_offset: int, value: int) 🔗
将 32 位无符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 4 个字节的空间。
void encode_s64(byte_offset: int, value: int) 🔗
将 64 位有符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 8 个字节的空间。
void encode_u8(byte_offset: int, value: int) 🔗
将 8 位无符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 1 个字节的空间。
void encode_u16(byte_offset: int, value: int) 🔗
将 16 位无符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 2 个字节的空间。
void encode_u32(byte_offset: int, value: int) 🔗
将 32 位无符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 4 个字节的空间。
void encode_u64(byte_offset: int, value: int) 🔗
将 64 位无符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 8 个字节的空间。
int encode_var(byte_offset: int, value: Variant, allow_objects: bool = false) 🔗
将 Variant 编码为字节序列，起始位置字节偏移量为 byte_offset。必须分配有足够的空间，空间大小取决于编码后变体的大小。如果 allow_objects 为 false，则不允许派生自 Object 的值，只会将其 ID 进行序列化。
在数组中移除首次出现的某个值并返回 true。如果数组中不存在该值，则不会发生任何事情，返回 false。要按照索引移除元素，请改用 remove_at()。
将数组中的所有元素都设为给定的值。通常与 resize() 一起使用，创建给定大小的数组并初始化元素。
int find(value: int, from: int = 0) const 🔗
在数组中搜索值并返回其索引，如果未找到则返回 -1 。可选地，可以传递起始搜索索引。
返回数组中索引为 index 的字节。如果 index 越界或为负数，则该方法失败并返回 0。
该方法类似于 [] 运算符（但不等价）。最显著的区别就是从编辑器中运行时，该方法失败不会暂停项目运行。
String get_string_from_ascii() const 🔗
将 ASCII/Latin-1 编码的数组转换为 String。如果内容仅为 ASCII/Latin-1，则是比 get_string_from_utf8() 更快的选择。与 UTF-8 函数不同，这个函数会将数组中的每个字节都映射到一个字符。多字节序列无法正确解析。要解析用户的输入内容，请始终使用 get_string_from_utf8()。这是 String.to_ascii_buffer() 的逆运算。
String get_string_from_multibyte_char(encoding: String = "") const 🔗
将使用系统多字节代码页编码的数组转换为 String。如果转换失败，则会返回空字符串。这是 String.to_multibyte_char_buffer() 的逆运算。
encoding 的有效值由系统决定。如果 encoding 为空字符串，则会使用系统默认的编码。
对于 Windows，见代码页标识符 .NET 名称。
对于 macOS 和 Linux/BSD，支持的编码列表见
libiconv库文档及iconv --list。
String get_string_from_utf8() const 🔗
将 UTF-8 编码的数组转换为 String。比 get_string_from_ascii() 慢，但支持 UTF-8 编码的数据。不确定数据来源时请使用此函数。对于用户的输入内容，应始终首选此函数。如果源数组不是有效的 UTF-8 字符串，则返回空字符串。这是 String.to_utf8_buffer() 的逆运算。
String get_string_from_utf16() const 🔗
将 UTF-16 编码的数组转换为 String。如果缺少 BOM，则假定为小端字节序。如果源数组不是有效的 UTF-16 字符串，则返回空字符串。这是 String.to_utf16_buffer() 的逆运算。
String get_string_from_utf32() const 🔗
将 UTF-32 编码的数组转换为 String。如果源数组不是有效的 UTF-32 字符串则返回空字符串。这是 String.to_utf32_buffer() 的逆运算。
String get_string_from_wchar() const 🔗
将宽字符（wchar_t，在 Windows 上为 UTF-16，在其他平台上为 UTF-32）编码的数组转换为 String。如果源数组不是有效的宽字符串，则返回空字符串。这是 String.to_wchar_buffer() 的逆运算。
如果该数组包含 value，则返回 true。
bool has_encoded_var(byte_offset: int, allow_objects: bool = false) const 🔗
如果可以从字节偏移量 byte_offset 处解码出有效的 Variant，则返回 true。其他情况，或者当该值派生自 Object 而 allow_objects 为 false 时，则返回 false。
返回该数组的十六进制表示，类型为 String。
var array = PackedByteArray([11, 46, 255])
print(array.hex_encode()) # 输出“0b2eff”
byte[] array = [11, 46, 255];
GD.Print(array.HexEncode()); // 输出“0b2eff”
int insert(at_index: int, value: int) 🔗
在数组中给定的位置插入一个新元素。这个位置必须是有效的，或者是在数组的末端（idx == size()）。
该数组为空时，返回 true。
在数组的末尾追加一个元素。
从数组中删除位于索引的元素。
设置数组的大小。如果数组增大，则预留数组末端的元素。如果数组缩小，则将数组截断到新的大小。调用一次 resize() 然后赋值比逐个添加新元素要快。
成功时返回 @GlobalScope.OK，失败时返回下列 Error 常量：大小为负数则返回 @GlobalScope.ERR_INVALID_PARAMETER，分配失败则返回 @GlobalScope.ERR_OUT_OF_MEMORY。请使用 size() 获取调整后的实际大小。
void reverse() 🔗
将数组中的元素逆序排列。
int rfind(value: int, from: int = -1) const 🔗
逆序搜索数组。还可以传递起始搜索位置索引。如果为负，则起始索引被视为相对于数组的结尾。
void set(index: int, value: int) 🔗
改变给定索引处的字节。
返回数组中元素的个数。
PackedByteArray slice(begin: int, end: int = 2147483647) const 🔗
返回该 PackedByteArray 的切片，是从 begin（含）到 end（不含）的全新 PackedByteArray。
begin 和 end 的绝对值会按数组大小进行限制，所以 end 的默认值会切到数组大小为止（即 arr.slice(1) 是 arr.slice(1, arr.size()) 的简写）。
如果 begin 或 end 为负，则表示相对于数组的末尾（即 arr.slice(0, -2) 是 arr.slice(0, arr.size() - 2) 的简写）。
void sort() 🔗
将该数组中的元素按升序排列。
PackedColorArray to_color_array() const 🔗
返回数据副本转换得到的 PackedColorArray，会将每 16 个字节的数据块会转换为一个 Color 变体。
注意：输入数组的大小必须为 16（四个 32 位 float 变量的大小）的倍数。新数组的大小是 byte_array.size() / 16。如果原数据无法转换为 Color 变体，则最终的数据未定义。
PackedFloat32Array to_float32_array() const 🔗
返回将数据转换为 PackedFloat32Array 的副本，每 4 个字节块转换为一个 32 位浮点数（C++ 的 float）。
输入数组的大小必须为 4 的倍数（32 位浮点数的大小）。新数组的大小为 byte_array.size() / 4。
如果原始数据无法转换为 32 位浮点数，则最终的数据未定义。
PackedFloat64Array to_float64_array() const 🔗
返回将数据转换为 PackedFloat64Array 的副本，每 8 个字节块转换为一个 64 位浮点数（C++ 的 double）。
输入数组的大小必须为 8 的倍数（64 位浮点数的大小）。新数组的大小为 byte_array.size() / 8。
如果原始数据无法转换为 64 位浮点数，则最终的数据未定义。
PackedInt32Array to_int32_array() const 🔗
返回将数据转换为 PackedInt32Array 的副本，每 4 个字节块转换为一个 32 位有符号整数（C++ 的 int32_t）。
输入数组的大小必须为 4 的倍数（32 位整数的大小）。新数组的大小为 byte_array.size() / 4。
如果原始数据无法转换为 32 位有符号整数，则最终的数据未定义。
PackedInt64Array to_int64_array() const 🔗
返回将数据转换为 PackedInt64Array 的副本，每 8 个字节块转换为一个 64 位有符号整数（C++ 的 int64_t）。
输入数组的大小必须为 8 的倍数（64 位整数的大小）。新数组的大小为 byte_array.size() / 8。
如果原始数据无法转换为 64 位有符号整数，则最终的数据未定义。
PackedVector2Array to_vector2_array() const 🔗
返回数据副本转换得到的 PackedVector2Array，会将每 8 个字节（32 位）或每 16 个字节（64 位）的数据块会转换为一个 Vector2 变体。
注意：输入数组的大小必须为 8 或 16（取决于构建设置，详见 Vector2）的倍数。新数组的大小是 byte_array.size() / (8 或 16)。如果原数据无法转换为 Vector2 变体，则最终的数据未定义。
PackedVector3Array to_vector3_array() const 🔗
返回数据副本转换得到的 PackedVector3Array，会将每 12 个字节（32 位）或每 24 个字节（64 位）的数据块会转换为一个 Vector3 变体。
注意：输入数组的大小必须为 12 或 24（取决于构建设置，详见 Vector3）的倍数。新数组的大小是 byte_array.size() / (12 或 24)。如果原数据无法转换为 Vector3 变体，则最终的数据未定义。
PackedVector4Array to_vector4_array() const 🔗
返回数据副本转换得到的 PackedVector4Array，会将每 16 个字节（32 位）或每 32 个字节（64 位）的数据块会转换为一个 Vector4 变体。
注意：输入数组的大小必须为 16 或 32（取决于构建设置，详见 Vector4）的倍数。新数组的大小是 byte_array.size() / (16 或 32)。如果原数据无法转换为 Vector4 变体，则最终的数据未定义。
运算符说明
bool operator !=(right: PackedByteArray) 🔗
如果数组内容不同，则返回 true。
PackedByteArray operator +(right: PackedByteArray) 🔗
返回新的 PackedByteArray，新数组的内容为此数组在末尾加上 right。为了提高性能，请考虑改用 append_array()。
bool operator ==(right: PackedByteArray) 🔗
如果两个数组的内容相同，即对应索引号的字节相等，则返回 true。
返回索引 index 处的字节。负数索引可以从末尾开始访问元素。使用越界的索引会报错。
请注意，返回的字节是 64 位 int。