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...

Завантаження та збереження виконавчого файлу

Дивись також

Перегляньте Збереження ігор для отримання інформації про збереження та завантаження прогресу гри.

Іноді exporting packs, patches, and mods не ідеальний, якщо ви хочете, щоб гравці могли завантажувати створений користувачем вміст у вашому проекті. Він вимагає від користувачів створити файл PCK або ZIP через редактор Godot, який містить ресурси, імпортовані Godot.

Приклади використання для завантаження та збереження файлів під час виконання включають:

  • Завантаження текстурних пакетів, розроблених для гри.

  • Завантаження звукових доріжок, наданих користувачем, і їх відтворення на ігровій радіостанції.

  • Завантаження користувацьких рівнів або 3D-моделей, які можна розробити за допомогою будь-якого 3D DCC, що підтримує експорт у glTF або FBX (включаючи сцени glTF, збережені Godot під час виконання).

  • Використання наданих користувачами шрифтів для меню та HUD.

  • Збереження/завантаження файлу у форматі, який може містити декілька файлів, але його легко читати іншими програмами (ZIP).

  • Завантаження файлів, створених іншою грою чи програмою, або навіть файлів даних гри з іншої гри, створеної не за допомогою Godot.

Завантаження файлів під час виконання можна поєднати з HTTP requests для безпосереднього завантаження ресурсів з Інтернету.

Попередження

Не використовуйте цей підхід до завантаження під час виконання, щоб завантажувати ресурси, які є частиною проекту, оскільки він менш ефективний і не дозволяє отримати вигоду від функцій обробки ресурсів Godot (наприклад, перевідображення перекладу). Докладніше див. Процес імпорту.

Дивись також

Ви можете побачити, як збереження та завантаження працює в дії, використовуючи демонстраційний проект «Збереження та завантаження файлів під час виконання (серіалізація)».

Звичайний текст і двійкові файли

Клас Godot FileAccess надає методи доступу до файлів у файловій системі для читання та запису:

func save_file(content):
    var file = FileAccess.open("/path/to/file.txt", FileAccess.WRITE)
    file.store_string(content)

func load_file():
    var file = FileAccess.open("/path/to/file.txt", FileAccess.READ)
    var content = file.get_as_text()
    return content

Для роботи з власними двійковими форматами (наприклад, завантаження форматів файлів, які не підтримуються Godot), FileAccess надає кілька методів для читання/запису цілих чисел, чисел з плаваючою точкою, рядків тощо. Ці методи FileAccess мають імена, які починаються з get_ і store_.

Якщо вам потрібно більше контролювати читання двійкових файлів або потрібно читати двійкові потоки, які не є частиною файлу, class_PackedByteArray надає кілька допоміжних методів для декодування/кодування серії байтів у цілі числа, числа з плаваючою точкою, рядки тощо. Ці методи PackedByteArray мають імена, які починаються з decode_ і encode_. Дивіться також API бінарної серіалізації.

Зображення

Статичний метод Image.load_from_file обробляє все, від визначення формату на основі розширення файлу до читання файлу з диска.

Якщо вам потрібна обробка помилок або більше контролю (наприклад, зміна масштабу завантаження SVG), скористайтеся одним із наведених нижче методів залежно від формату файлу:

Кілька форматів зображень також можна зберегти Godot під час виконання за допомогою таких методів:

Методи з суфіксом to_buffer зберігають зображення в PackedByteArray замість файлової системи. Це корисно, щоб надіслати зображення через мережу або в ZIP-архів без необхідності записувати його у файлову систему. Це може збільшити продуктивність за рахунок зменшення використання вводу-виводу.

Примітка

У разі відображення завантаженого зображення на 3D-поверхні обов’язково викликайте Image.generate_mipmaps, щоб текстура не виглядала зернистою при перегляді з відстані. Це також корисно в 2D, якщо слідувати інструкціям щодо reducing aliasing when downsampling.

Приклад завантаження зображення та його відображення у вузлі class_TextureRect (який вимагає перетворення на ImageTexture):

# Load an image of any format supported by Godot from the filesystem.
var image = Image.load_from_file(path)
# Optionally, generate mipmaps if displaying the texture on a 3D surface
# so that the texture doesn't look grainy when viewed at a distance.
#image.generate_mipmaps()
$TextureRect.texture = ImageTexture.create_from_image(image)

# Save the loaded Image to a PNG image.
image.save_png("/path/to/file.png")

# Save the converted ImageTexture to a PNG image.
$TextureRect.texture.get_image().save_png("/path/to/file.png")

Аудіо/відео файли

Godot підтримує завантаження аудіо Ogg Vorbis, MP3 та WAV під час виконання. Зверніть увагу, що не всі файли з розширенням .ogg є файлами Ogg Vorbis. Деякі з них можуть бути відео Ogg Theora або містити аудіо Opus у контейнері Ogg. Ці файли не завантажуватимуться коректно як аудіофайли в Godot.

Приклад завантаження аудіофайлу Ogg Vorbis у вузлі AudioStreamPlayer:

$AudioStreamPlayer.stream = AudioStreamOggVorbis.load_from_file(path)

Приклад завантаження відеофайлу Ogg Theora у вузол class_VideoStreamPlayer:

var video_stream_theora = VideoStreamTheora.new()
# File extension is ignored, so it is possible to load Ogg Theora videos
# that have a `.ogg` extension this way.
video_stream_theora.file = "/path/to/file.ogv"
$VideoStreamPlayer.stream = video_stream_theora

# VideoStreamPlayer's Autoplay property won't work if the stream is empty
# before this property is set, so call `play()` after setting `stream`.
$VideoStreamPlayer.play()

3D сцени

Godot має першокласну підтримку glTF 2.0 як у редакторі, так і в експортованих проектах. Використовуючи разом GLTFDocument і GLTFState, Godot може завантажувати та зберігати файли glTF в експортованих проектах як у текстовому (.gltf), так і в двійковому (.glb) форматах. Слід віддати перевагу двійковому формату, оскільки він швидший для запису та менший, але текстовий формат легше налагодити.

Починаючи з Godot 4.3, сцени FBX також можна завантажувати (але не зберігати) під час виконання за допомогою класів FBXDocument та FBXState. Код для цього такий самий, як і в glTF, але вам потрібно буде замінити всі екземпляри GLTFDocument та GLTFState на FBXDocument та FBXState у наведених нижче прикладах коду.

Приклад завантаження сцени glTF і додавання її кореневого вузла до сцени:

# Load an existing glTF scene.
# GLTFState is used by GLTFDocument to store the loaded scene's state.
# GLTFDocument is the class that handles actually loading glTF data into a Godot node tree,
# which means it supports glTF features such as lights and cameras.
var gltf_document_load = GLTFDocument.new()
var gltf_state_load = GLTFState.new()
var error = gltf_document_load.append_from_file("/path/to/file.gltf", gltf_state_load)
if error == OK:
    var gltf_scene_root_node = gltf_document_load.generate_scene(gltf_state_load)
    add_child(gltf_scene_root_node)
else:
    show_error("Couldn't load glTF scene (error code: %s)." % error_string(error))

# Save a new glTF scene.
var gltf_document_save := GLTFDocument.new()
var gltf_state_save := GLTFState.new()
gltf_document_save.append_from_scene(gltf_scene_root_node, gltf_state_save)
# The file extension in the output `path` (`.gltf` or `.glb`) determines
# whether the output uses text or binary format.
# `GLTFDocument.generate_buffer()` is also available for saving to memory.
gltf_document_save.write_to_filesystem(gltf_state_save, path)

Примітка

Під час завантаження сцени glTF потрібно встановити базовий шлях, щоб зовнішні ресурси, такі як текстури, могли завантажуватися правильно. Під час завантаження з файлу основний шлях автоматично встановлюється до папки, що містить файл. Під час завантаження з буфера цей базовий шлях потрібно встановити вручну, оскільки Godot не може визначити цей шлях.

Щоб встановити базовий шлях, установіть GLTFState.base_path на вашому екземплярі GLTFState перед викликом GLTFDocument.append_from_buffer або GLTFDocument.append_from_file.

Шрифти

FontFile.load_dynamic_font підтримує такі формати файлів шрифтів: TTF, OTF, WOFF, WOFF2, PFB, PFM

З іншого боку, FontFile.load_bitmap_font підтримує формат BMFont (.fnt або . шрифт).

Крім того, можна завантажити будь-який шрифт, встановлений у системі, використовуючи підтримку Godot для Системні шрифти.

Приклад автоматичного завантаження файлу шрифту відповідно до його розширення, а потім додавання його як перевизначення теми до вузла Label:

var path = "/path/to/font.ttf"
var path_lower = path.to_lower()
var font_file = FontFile.new()
if (
        path_lower.ends_with(".ttf")
        or path_lower.ends_with(".otf")
        or path_lower.ends_with(".woff")
        or path_lower.ends_with(".woff2")
        or path_lower.ends_with(".pfb")
        or path_lower.ends_with(".pfm")
):
    font_file.load_dynamic_font(path)
elif path_lower.ends_with(".fnt") or path_lower.ends_with(".font"):
    font_file.load_bitmap_font(path)
else:
    push_error("Invalid font file format.")

if not font_file.data.is_empty():
    # If font was loaded successfully, add it as a theme override.
    $Label.add_theme_font_override("font", font_file)

ZIP архіви

Godot підтримує читання та запис ZIP-архівів за допомогою класів class_zipreader і class_zippacker. Це підтримує будь-який ZIP-файл, включно з файлами, створеними за допомогою функції «Експорт PCK/ZIP» Godot (хоча вони міститимуть імпортовані ресурси Godot, а не оригінальні файли проекту).

Примітка

Використовуйте ProjectSettings.load_resource_pack, щоб завантажити файли PCK або ZIP, експортовані Godot як additional data packs. Цей підхід є кращим для DLC, оскільки він забезпечує безперебійну взаємодію з додатковими пакетами даних (віртуальна файлова система).

Цю підтримку архіву ZIP можна поєднати із завантаженням зображень під час виконання, 3D-сцени та аудіо, щоб забезпечити бездоганний досвід моддингу, не вимагаючи від користувачів проходити через редактор Godot для створення файлів PCK/ZIP.

Приклад, який перераховує файли в ZIP-архіві у вузлі ItemList, а потім записує прочитаний із нього вміст у новий ZIP-архів (по суті, дублюючи архів):

# Load an existing ZIP archive.
var zip_reader = ZIPReader.new()
zip_reader.open(path)
var files = zip_reader.get_files()
# The list of files isn't sorted by default. Sort it for more consistent processing.
files.sort()
for file in files:
    $ItemList.add_item(file, null)
    # Make folders disabled in the list.
    $ItemList.set_item_disabled(-1, file.ends_with("/"))

# Save a new ZIP archive.
var zip_packer = ZIPPacker.new()
var error = zip_packer.open(path)
if error != OK:
    push_error("Couldn't open path for saving ZIP archive (error code: %s)." % error_string(error))
    return

# Reuse the above ZIPReader instance to read files from an existing ZIP archive.
for file in zip_reader.get_files():
    zip_packer.start_file(file)
    zip_packer.write_file(zip_reader.read_file(file))
    zip_packer.close_file()

zip_packer.close()