From febc674f4818dd1185b2e43e899115f70f55b4f5 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Mon, 8 May 2023 07:00:33 +0200 Subject: [PATCH] Document caveats related to exported project binary resource conversion --- doc/classes/DirAccess.xml | 1 + doc/classes/ProjectSettings.xml | 3 ++- doc/classes/ResourceLoader.xml | 1 + modules/gdscript/doc_classes/@GDScript.xml | 1 + 4 files changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/classes/DirAccess.xml b/doc/classes/DirAccess.xml index b6e17a1a2d1b..d26b839e6441 100644 --- a/doc/classes/DirAccess.xml +++ b/doc/classes/DirAccess.xml @@ -173,6 +173,7 @@ Returns a [PackedStringArray] containing filenames of the directory contents, excluding directories. The array is sorted alphabetically. Affected by [member include_hidden]. + [b]Note:[/b] When used on a [code]res://[/code] path in an exported project, only the files actually included in the PCK at the given folder level are returned. In practice, this means that since imported resources are stored in a top-level [code].godot/[/code] folder, only paths to [code]*.gd[/code] and [code]*.import[/code] files are returned (plus a few files such as [code]project.godot[/code] or [code]project.binary[code] and the project icon). In an exported project, the list of returned files will also vary depending on whether [member ProjectSettings.editor/export/convert_text_resources_to_binary] is [code]true[/code]. diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index f06e6e5da1d4..23e790c20f04 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -734,7 +734,8 @@ Changing this value allows setting up a multi-project scenario where there are multiple [code].csproj[/code]. Keep in mind that the Godot project is considered one of the C# projects in the workspace and it's root directory should contain the [code]project.godot[/code] and [code].csproj[/code] next to each other. - If [code]true[/code] text resources are converted to binary format on export. + If [code]true[/code], text resources are converted to a binary format on export. This decreases file sizes and speeds up loading slightly. + [b]Note:[/b] If [member editor/export/convert_text_resources_to_binary] is [code]true[/code], [method @GDScript.load] will not be able to return the converted files in an exported project. Some file paths within the exported PCK will also change, such as [code]project.godot[/code] becoming [code]project.binary[/code]. If you rely on run-time loading of files present within the PCK, set [member editor/export/convert_text_resources_to_binary] to [code]false[/code]. diff --git a/doc/classes/ResourceLoader.xml b/doc/classes/ResourceLoader.xml index 97cba0dcacef..f804b5a25d58 100644 --- a/doc/classes/ResourceLoader.xml +++ b/doc/classes/ResourceLoader.xml @@ -71,6 +71,7 @@ The [param cache_mode] property defines whether and how the cache should be used or updated when loading the resource. See [enum CacheMode] for details. Returns an empty resource if no [ResourceFormatLoader] could handle the file. GDScript has a simplified [method @GDScript.load] built-in method which can be used in most situations, leaving the use of [ResourceLoader] for more advanced scenarios. + [b]Note:[/b] If [member ProjectSettings.editor/export/convert_text_resources_to_binary] is [code]true[/code], [method @GDScript.load] will not be able to read converted files in an exported project. If you rely on run-time loading of files present within the PCK, set [member ProjectSettings.editor/export/convert_text_resources_to_binary] to [code]false[/code]. diff --git a/modules/gdscript/doc_classes/@GDScript.xml b/modules/gdscript/doc_classes/@GDScript.xml index 0e51230cd0a6..e3129e848c82 100644 --- a/modules/gdscript/doc_classes/@GDScript.xml +++ b/modules/gdscript/doc_classes/@GDScript.xml @@ -170,6 +170,7 @@ [b]Important:[/b] The path must be absolute. A relative path will always return [code]null[/code]. This function is a simplified version of [method ResourceLoader.load], which can be used for more advanced scenarios. [b]Note:[/b] Files have to be imported into the engine first to load them using this function. If you want to load [Image]s at run-time, you may use [method Image.load]. If you want to import audio files, you can use the snippet described in [member AudioStreamMP3.data]. + [b]Note:[/b] If [member ProjectSettings.editor/export/convert_text_resources_to_binary] is [code]true[/code], [method @GDScript.load] will not be able to read converted files in an exported project. If you rely on run-time loading of files present within the PCK, set [member ProjectSettings.editor/export/convert_text_resources_to_binary] to [code]false[/code].