File

Inherits: Reference < Object

Escriba para manejar las operaciones de lectura y escritura de archivos.

Descripción

File type. This is used to permanently store data into the user device's file system and to read from it. This can be used to store game save data or player configuration files, for example.

Here's a sample on how to write and read from a file:

func save(content):
    var file = File.new()
    file.open("user://save_game.dat", File.WRITE)
    file.store_string(content)
    file.close()

func load():
    var file = File.new()
    file.open("user://save_game.dat", File.READ)
    var content = file.get_as_text()
    file.close()
    return content

In the example above, the file will be saved in the user data folder as specified in the Data paths documentation.

Note: To access project resources once exported, it is recommended to use ResourceLoader instead of the File API, as some files are converted to engine-specific formats and their original source files might not be present in the exported PCK package.

Note: Files are automatically closed only if the process exits "normally" (such as by clicking the window manager's close button or pressing Alt + F4). If you stop the project execution by pressing F8 while the project is running, the file won't be closed as the game process will be killed. You can work around this by calling flush at regular intervals.

Tutoriales

Propiedades

bool

endian_swap

false

Métodos

void

close ( )

bool

eof_reached ( ) const

bool

file_exists ( String path ) const

void

flush ( )

int

get_16 ( ) const

int

get_32 ( ) const

int

get_64 ( ) const

int

get_8 ( ) const

String

get_as_text ( ) const

PoolByteArray

get_buffer ( int len ) const

PoolStringArray

get_csv_line ( String delim="," ) const

float

get_double ( ) const

Error

get_error ( ) const

float

get_float ( ) const

int

get_len ( ) const

String

get_line ( ) const

String

get_md5 ( String path ) const

int

get_modified_time ( String file ) const

String

get_pascal_string ( )

String

get_path ( ) const

String

get_path_absolute ( ) const

int

get_position ( ) const

float

get_real ( ) const

String

get_sha256 ( String path ) const

Variant

get_var ( bool allow_objects=false ) const

bool

is_open ( ) const

Error

open ( String path, ModeFlags flags )

Error

open_compressed ( String path, ModeFlags mode_flags, CompressionMode compression_mode=0 )

Error

open_encrypted ( String path, ModeFlags mode_flags, PoolByteArray key )

Error

open_encrypted_with_pass ( String path, ModeFlags mode_flags, String pass )

void

seek ( int position )

void

seek_end ( int position=0 )

void

store_16 ( int value )

void

store_32 ( int value )

void

store_64 ( int value )

void

store_8 ( int value )

void

store_buffer ( PoolByteArray buffer )

void

store_csv_line ( PoolStringArray values, String delim="," )

void

store_double ( float value )

void

store_float ( float value )

void

store_line ( String line )

void

store_pascal_string ( String string )

void

store_real ( float value )

void

store_string ( String string )

void

store_var ( Variant value, bool full_objects=false )

Enumeraciones

enum ModeFlags:

  • READ = 1 --- Opens the file for read operations. The cursor is positioned at the beginning of the file.

  • WRITE = 2 --- Opens the file for write operations. The file is created if it does not exist, and truncated if it does.

  • READ_WRITE = 3 --- Opens the file for read and write operations. Does not truncate the file. The cursor is positioned at the beginning of the file.

  • WRITE_READ = 7 --- Opens the file for read and write operations. The file is created if it does not exist, and truncated if it does. The cursor is positioned at the beginning of the file.

enum CompressionMode:

  • COMPRESSION_FASTLZ = 0 --- Utiliza el método de compresión FastLZ.

  • COMPRESSION_DEFLATE = 1 --- Utiliza el método de compresión DEFLATE.

  • COMPRESSION_ZSTD = 2 --- Utiliza el método de compresión Zstandard.

  • COMPRESSION_GZIP = 3 --- Utiliza el método de compresión gzip.

Descripciones de Propiedades

Default

false

Setter

set_endian_swap(value)

Getter

get_endian_swap()

If true, the file is read with big-endian endianness. If false, the file is read with little-endian endianness. If in doubt, leave this to false as most files are written with little-endian endianness.

Note: endian_swap is only about the file format, not the CPU type. The CPU endianness doesn't affect the default endianness for files written.

Note: This is always reset to false whenever you open the file. Therefore, you must set endian_swap after opening the file, not before.

Descripciones de Métodos

  • void close ( )

Closes the currently opened file and prevents subsequent read/write operations. Use flush to persist the data to disk without closing the file.

  • bool eof_reached ( ) const

Returns true if the file cursor has already read past the end of the file.

Note: eof_reached() == false cannot be used to check whether there is more data available. To loop while there is more data available, use:

while file.get_position() < file.get_len():
    # Read data

Returns true if the file exists in the given path.

Note: Many resources types are imported (e.g. textures or sound files), and their source asset will not be included in the exported game, as only the imported version is used. See ResourceLoader.exists for an alternative approach that takes resource remapping into account.

  • void flush ( )

Writes the file's buffer to disk. Flushing is automatically performed when the file is closed. This means you don't need to call flush manually before closing a file using close. Still, calling flush can be used to ensure the data is safe even if the project crashes instead of being closed gracefully.

Note: Only call flush when you actually need it. Otherwise, it will decrease performance due to constant disk writes.

  • int get_16 ( ) const

Devuelve los siguientes 16 bits del archivo como un número entero. Ver store_16 para detalles sobre qué valores pueden ser almacenados y recuperados de esta manera.

  • int get_32 ( ) const

Devuelve los siguientes 32 bits del archivo como un número entero. Ver store_32 para detalles sobre qué valores pueden ser almacenados y recuperados de esta manera.

  • int get_64 ( ) const

Devuelve los siguientes 64 bits del archivo como un entero. Ver store_64 para detalles sobre qué valores pueden ser almacenados y recuperados de esta manera.

  • int get_8 ( ) const

Devuelve los siguientes 8 bits del archivo como un entero. Ver store_8 para detalles sobre qué valores pueden ser almacenados y recuperados de esta manera.

  • String get_as_text ( ) const

Devuelve todo el archivo como una String.

El texto se interpreta como codificado en UTF-8.

Returns next len bytes of the file as a PoolByteArray.

Returns the next value of the file in CSV (Comma-Separated Values) format. You can pass a different delimiter delim to use other than the default "," (comma). This delimiter must be one-character long, and cannot be a double quotation mark.

Text is interpreted as being UTF-8 encoded. Text values must be enclosed in double quotes if they include the delimiter character. Double quotes within a text value can be escaped by doubling their occurrence.

For example, the following CSV lines are valid and will be properly parsed as two strings each:

Alice,"Hello, Bob!"
Bob,Alice! What a surprise!
Alice,"I thought you'd reply with ""Hello, world""."

Note how the second line can omit the enclosing quotes as it does not include the delimiter. However it could very well use quotes, it was only written without for demonstration purposes. The third line must use "" for each quotation mark that needs to be interpreted as such instead of the end of a text value.

  • float get_double ( ) const

Devuelve los siguientes 64 bits del archivo como un real.

  • Error get_error ( ) const

Devuelve el último error que ocurrió al intentar realizar las operaciones. Compare con las constantes ERR_FILE_* de Error.

  • float get_float ( ) const

Devuelve los siguientes 32 bits del archivo como un número real.

  • int get_len ( ) const

Devuelve el tamaño del archivo en bytes.

Devuelve la siguiente línea del archivo como una String.

El texto se interpreta como codificado en UTF-8.

Devuelve una string MD5 que representa el archivo en la ruta dada o una String vacía al fallar.

  • int get_modified_time ( String file ) const

Devuelve la última vez que se modificó el archivo file en formato de marca de tiempo unix o devuelve un String "ERROR EN EL file". Esta marca de tiempo unix puede ser convertida en fecha y hora usando el OS.get_datetime_from_unix_time.

  • String get_pascal_string ( )

Devuelve una String guardada en formato Pascal del archivo.

El texto se interpreta como codificado en UTF-8.

Devuelve la ruta como una String para el archivo abierto actual.

  • String get_path_absolute ( ) const

Devuelve la ruta absoluta como una String para el archivo abierto actual.

  • int get_position ( ) const

Devuelve la posición del cursor del archivo.

  • float get_real ( ) const

Devuelve los siguientes bits del archivo como un número real.

Devuelve un SHA-256 String que representa el archivo en la ruta dada o un String vacío al fallar.

Devuelve el siguiente valor Variant del archivo. Si allow_objects es true, se permite la decodificación de objetos.

Advertencia: Los objetos deserializados pueden contener código que se ejecuta. No utilice esta opción si el objeto serializado proviene de fuentes no fiables para evitar posibles amenazas a la seguridad, como la ejecución remota de código.

  • bool is_open ( ) const

Devuelve true si el archivo está actualmente abierto.

Abre el archivo para escribir o leer, dependiendo de las flags.

Opens a compressed file for reading or writing.

Note: open_compressed can only read files that were saved by Godot, not third-party compression formats. See GitHub issue #28999 for a workaround.

Abre un archivo encriptado en modo de escritura o lectura. Necesitas pasar una clave binaria para encriptarlo/desencriptarlo.

Nota: La clave proporcionada debe tener 32 bytes de longitud.

Abre un archivo encriptado en modo de escritura o lectura. Necesitas pasar una contraseña para encriptarlo/desencriptarlo.

  • void seek ( int position )

Cambia el cursor de lectura/escritura del archivo a la posición especificada (en bytes desde el principio del archivo).

  • void seek_end ( int position=0 )

Cambia el cursor de lectura/escritura del archivo a la posición especificada (en bytes desde el final del archivo).

Nota: Se trata de un desplazamiento, por lo que debe utilizar números negativos o el cursor estará al final del archivo.

  • void store_16 ( int value )

Almacena un entero como 16 bits en el archivo.

Nota: El valor value debe estar en el intervalo [0, 2^16 - 1]. Cualquier otro valor se desbordará y se envolverá.

Para almacenar un entero con signo, use store_64 o almacene un entero con signo del intervalo [-2^15, 2^15 - 1] (es decir, manteniendo un bit para el signo) y calcule su signo manualmente al leer. Por ejemplo:

const MAX_15B = 1 << 15
const MAX_16B = 1 << 16

func unsigned16_to_signed(unsigned):
    return (unsigned + MAX_15B) % MAX_16B - MAX_15B

func _ready():
    var f = File.new()
    f.open("user://file.dat", File.WRITE_READ)
    f.store_16(-42) # Esto envuelve y almacena 65494 (2^16 - 42).
    f.store_16(121) # En los límites, almacenará 121.
    f.seek(0) #  Vuelve al comienzo a leer el valor almacenado.
    var lectura1 = f.get_16() # 65494
    var lectura2 = f.get_16() # 121
    var convertido1 = unsigned16_to_signed(lectura2) # -42
    var convertido2 = unsigned16_to_signed(lectura2) # 121

  • void store_32 ( int value )

Almacena un entero como 32 bits en el archivo.

Nota: El valor value debe estar en el intervalo [0, 2^32 - 1]. Cualquier otro valor se desbordará y se envolverá.

Para almacenar un entero con signo, usa store_64, o conviértelo manualmente (ver store_16 para un ejemplo).

  • void store_64 ( int value )

Almacena un entero como 64 bits en el archivo.

Nota: El value debe estar en el intervalo [-2^63, 2^63 - 1] (es decir, ser un valor int válido).

  • void store_8 ( int value )

Almacena un entero como 8 bits en el archivo.

Nota: El value debe estar en el intervalo [0, 255]. Cualquier otro valor se desbordará y se envolverá.

Para almacenar un entero firmado, usa store_64, o conviértelo manualmente (ver store_16 para un ejemplo).

Almacena el array de bytes dados en el archivo.

Store the given PoolStringArray in the file as a line formatted in the CSV (Comma-Separated Values) format. You can pass a different delimiter delim to use other than the default "," (comma). This delimiter must be one-character long.

Text will be encoded as UTF-8.

  • void store_double ( float value )

Almacena un número de punto flotante como 64 bits en el archivo.

  • void store_float ( float value )

Almacena un número de real como 32 bits en el archivo.

  • void store_line ( String line )

Appends line to the file followed by a line return character (\n), encoding the text as UTF-8.

  • void store_pascal_string ( String string )

Almacena la String dada como una línea en el archivo en formato Pascal (es decir, también almacena la longitud de la string).

El texto será codificado como UTF-8.

  • void store_real ( float value )

Almacena un número de real en el archivo.

  • void store_string ( String string )

Appends string to the file without a line return, encoding the text as UTF-8.

Note: This method is intended to be used to write text files. The string is stored as a UTF-8 encoded buffer without string length or terminating zero, which means that it can't be loaded back easily. If you want to store a retrievable string in a binary file, consider using store_pascal_string instead. For retrieving strings from a text file, you can use get_buffer(length).get_string_from_utf8() (if you know the length) or get_as_text.

  • void store_var ( Variant value, bool full_objects=false )

Stores any Variant value in the file. If full_objects is true, encoding objects is allowed (and can potentially include code).

Note: Not all properties are included. Only properties that are configured with the @GlobalScope.PROPERTY_USAGE_STORAGE flag set will be serialized. You can add a new usage flag to a property by overriding the Object._get_property_list method in your class. You can also check how property usage is configured by calling Object._get_property_list. See PropertyUsageFlags for the possible usage flags.