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
位元組緊縮陣列。
說明
An array specifically designed to hold bytes. Packs data tightly, so it saves memory for large array sizes.
PackedByteArray also provides methods to encode/decode various types to/from bytes. The way values are encoded is an implementation detail and shouldn't be relied upon when interacting with external apps.
Note: Packed arrays are always passed by reference. To get a copy of an array that can be modified independently of the original array, use duplicate(). This is not the case for built-in properties and methods. In these cases the returned packed array is a copy, and changing it will not affect the original value. To update a built-in property of this type, modify the returned array and then assign it to the property again.
Note: In a boolean context, a packed array will evaluate to false if it's empty. Otherwise, a packed array will always evaluate to 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) 🔗
Swaps the byte order of count 16-bit segments of the array starting at offset. Swap is done in-place. If count is less than zero, all segments to the end of array are processed, if processed data size is not a multiple of 2, the byte after the last processed 16-bit segment is not modified.
void bswap32(offset: int = 0, count: int = -1) 🔗
Swaps the byte order of count 32-bit segments of the array starting at offset. Swap is done in-place. If count is less than zero, all segments to the end of array are processed, if processed data size is not a multiple of 4, bytes after the last processed 32-bit segment are not modified.
void bswap64(offset: int = 0, count: int = -1) 🔗
Swaps the byte order of count 64-bit segments of the array starting at offset. Swap is done in-place. If count is less than zero, all segments to the end of array are processed, if processed data size is not a multiple of 8, bytes after the last processed 64-bit segment are not modified.
void clear() 🔗
清空陣列。相當於呼叫 resize() 時指定大小為 0。
PackedByteArray compress(compression_mode: int = 0) const 🔗
返回新的 PackedByteArray，其中的資料已壓縮。請將壓縮模式設定為 CompressionMode 常數。
返回元素在陣列中出現的次數。
float decode_double(byte_offset: int) const 🔗
Decodes a 64-bit floating-point number from the bytes starting at byte_offset. Fails if the byte count is insufficient. Returns 0.0 if a valid number can't be decoded.
float decode_float(byte_offset: int) const 🔗
Decodes a 32-bit floating-point number from the bytes starting at byte_offset. Fails if the byte count is insufficient. Returns 0.0 if a valid number can't be decoded.
float decode_half(byte_offset: int) const 🔗
Decodes a 16-bit floating-point number from the bytes starting at byte_offset. Fails if the byte count is insufficient. Returns 0.0 if a valid number can't be decoded.
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 個位元組的資料，否則返回 null。
PackedByteArray decompress(buffer_size: int, compression_mode: int = 0) const 🔗
Returns a new PackedByteArray with the data decompressed. Set buffer_size to the size of the uncompressed data. Set the compression mode using one of CompressionMode's constants.
Note: Decompression is not guaranteed to work with data not compressed by Godot, for example if data compressed with the deflate compression mode lacks a checksum or header.
PackedByteArray decompress_dynamic(max_output_size: int, compression_mode: int = 0) const 🔗
Returns a new PackedByteArray with the data decompressed. Set the compression mode using one of CompressionMode's constants. This method only accepts brotli, gzip, and deflate compression modes.
This method is potentially slower than decompress(), as it may have to re-allocate its output buffer multiple times while decompressing, whereas decompress() knows it's output buffer size from the beginning.
GZIP has a maximal compression ratio of 1032:1, meaning it's very possible for a small compressed payload to decompress to a potentially very large output. To guard against this, you may provide a maximum size this function is allowed to allocate in bytes via max_output_size. Passing -1 will allow for unbounded output. If any positive value is passed, and the decompression exceeds that amount in bytes, then an error will be returned.
Note: Decompression is not guaranteed to work with data not compressed by Godot, for example if data compressed with the deflate compression mode lacks a checksum or header.
PackedByteArray duplicate() const 🔗
建立該陣列的副本，並將該副本返回。
void encode_double(byte_offset: int, value: float) 🔗
Encodes a 64-bit floating-point number as bytes at the index of byte_offset bytes. The array must have at least 8 bytes of allocated space, starting at the offset.
void encode_float(byte_offset: int, value: float) 🔗
Encodes a 32-bit floating-point number as bytes at the index of byte_offset bytes. The array must have at least 4 bytes of space, starting at the offset.
void encode_half(byte_offset: int, value: float) 🔗
Encodes a 16-bit floating-point number as bytes at the index of byte_offset bytes. The array must have at least 2 bytes of space, starting at the offset.
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 進行序列化。
Removes the first occurrence of a value from the array and returns true. If the value does not exist in the array, nothing happens and false is returned. To remove an element by index, use remove_at() instead.
將陣列中的所有元素都設為給定的值。通常與 resize() 一起使用，建立給定大小的陣列並初始化元素。
int find(value: int, from: int = 0) const 🔗
在陣列中搜索值並返回其索引，如果未找到則返回 -1 。可選地，可以傳遞起始搜索索引。
Returns the byte at the given index in the array. If index is out-of-bounds or negative, this method fails and returns 0.
This method is similar (but not identical) to the [] operator. Most notably, when this method fails, it doesn't pause project execution if run from the editor.
String get_string_from_ascii() const 🔗
將 ASCII/Latin-1 編碼的陣列轉換為 String。如果內容僅為 ASCII/Latin-1，則是比 get_string_from_utf8() 更快的選擇。與 UTF-8 函式不同，這個函式會將陣列中的每個位元組都對應到一個字元。多位元組序列無法正確解析。要解析使用者的輸入內容，請始終使用 get_string_from_utf8()。
String get_string_from_multibyte_char(encoding: String = "") const 🔗
Converts system multibyte code page encoded array to String. If conversion fails, empty string is returned. This is the inverse of String.to_multibyte_char_buffer().
The values permitted for encoding are system dependent. If encoding is empty string, system default encoding is used.
For Windows, see Code Page Identifiers .NET names.
For macOS and Linux/BSD, see
libiconvlibrary documentation andiconv --listfor a list of supported encodings.
String get_string_from_utf8() const 🔗
將 UTF-8 編碼的陣列轉換為 String。比 get_string_from_ascii() 慢，但支援 UTF-8 編碼的資料。不確定資料來源時請使用此函式。對於使用者的輸入內容，應始終首選此函式。如果源陣列不是有效的 UTF-8 字串，則返回空字串。
String get_string_from_utf16() const 🔗
Converts UTF-16 encoded array to String. If the BOM is missing, little-endianness is assumed. Returns empty string if source array is not valid UTF-16 string. This is the inverse of String.to_utf16_buffer().
String get_string_from_utf32() const 🔗
Converts UTF-32 encoded array to String. Returns empty string if source array is not valid UTF-32 string. This is the inverse of String.to_utf32_buffer().
String get_string_from_wchar() const 🔗
將寬字元（wchar_t，在 Windows 上為 UTF-16，在其他平臺上為 UTF-32）編碼的陣列轉換為 String。如果源陣列不是有效的寬字串，則返回空字元串。
如果該陣列包含 value，則返回 true。
bool has_encoded_var(byte_offset: int, allow_objects: bool = false) const 🔗
如果可以從位元組偏移量 byte_offset 處解碼出有效的 Variant，則返回 true。其他情況，或者當該值衍生自 Object 而 allow_objects 為 false 時，則返回 false。
Returns a hexadecimal representation of this array as a String.
var array = PackedByteArray([11, 46, 255])
print(array.hex_encode()) # Prints "0b2eff"
byte[] array = [11, 46, 255];
GD.Print(array.HexEncode()); // Prints "0b2eff"
int insert(at_index: int, value: int) 🔗
在陣列中給定的位置插入一個新元素。這個位置必須是有效的，或者是在陣列的末端（idx == size()）。
該陣列為空時，返回 true。
在陣列的末尾追加一個元素。
從陣列中刪除位於索引的元素。
Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling resize() once and assigning the new values is faster than adding new elements one by one.
Returns @GlobalScope.OK on success, or one of the following Error constants if this method fails: @GlobalScope.ERR_INVALID_PARAMETER if the size is negative, or @GlobalScope.ERR_OUT_OF_MEMORY if allocations fail. Use size() to find the actual size of the array after resize.
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 🔗
Returns a copy of the data converted to a PackedColorArray, where each block of 16 bytes has been converted to a Color variant.
Note: The size of the input array must be a multiple of 16 (size of four 32-bit float variables). The size of the new array will be byte_array.size() / 16. If the original data can't be converted to Color variants, the resulting data is undefined.
PackedFloat32Array to_float32_array() const 🔗
Returns a copy of the data converted to a PackedFloat32Array, where each block of 4 bytes has been converted to a 32-bit float (C++ float).
The size of the input array must be a multiple of 4 (size of 32-bit float). The size of the new array will be byte_array.size() / 4.
If the original data can't be converted to 32-bit floats, the resulting data is undefined.
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 🔗
Returns a copy of the data converted to a PackedVector2Array, where each block of 8 bytes or 16 bytes (32-bit or 64-bit) has been converted to a Vector2 variant.
Note: The size of the input array must be a multiple of 8 or 16 (depending on the build settings, see Vector2 for more details). The size of the new array will be byte_array.size() / (8 or 16). If the original data can't be converted to Vector2 variants, the resulting data is undefined.
PackedVector3Array to_vector3_array() const 🔗
Returns a copy of the data converted to a PackedVector3Array, where each block of 12 or 24 bytes (32-bit or 64-bit) has been converted to a Vector3 variant.
Note: The size of the input array must be a multiple of 12 or 24 (depending on the build settings, see Vector3 for more details). The size of the new array will be byte_array.size() / (12 or 24). If the original data can't be converted to Vector3 variants, the resulting data is undefined.
PackedVector4Array to_vector4_array() const 🔗
Returns a copy of the data converted to a PackedVector4Array, where each block of 16 or 32 bytes (32-bit or 64-bit) has been converted to a Vector4 variant.
Note: The size of the input array must be a multiple of 16 or 32 (depending on the build settings, see Vector4 for more details). The size of the new array will be byte_array.size() / (16 or 32). If the original data can't be converted to Vector4 variants, the resulting data is undefined.
運算子說明
bool operator !=(right: PackedByteArray) 🔗
如果陣列內容不同，則返回 true。
PackedByteArray operator +(right: PackedByteArray) 🔗
返回新的 PackedByteArray，新陣列的內容為此陣列在末尾加上 right。為了提高性能，請考慮改用 append_array()。
bool operator ==(right: PackedByteArray) 🔗
如果兩個陣列的內容相同，即對應索引號的位元組相等，則返回 true。
返回索引 index 處的位元組。負數索引可以從末尾開始存取元素。使用越界的索引會報告有錯。
請注意，返回的位元組是 64 位元 int。