diff --git a/doc/classes/File.xml b/doc/classes/File.xml index f04e95186b6..f7b15c50149 100644 --- a/doc/classes/File.xml +++ b/doc/classes/File.xml @@ -115,7 +115,7 @@ - Returns the last error that happened when trying to perform operations. Compare with the [code]ERR_FILE_*[/code] constants from [@GlobalScope]. + Returns the last error that happened when trying to perform operations. Compare with the [code]ERR_FILE_*[/code] constants from [enum @GlobalScope.Error]. @@ -241,7 +241,7 @@ - Opens a compressed file for reading or writing. Use COMPRESSION_* constants to set [code]compression_mode[/code]. + Opens a compressed file for reading or writing. Use [enum CompressionMode] constants to set [code]compression_mode[/code]. diff --git a/doc/classes/Resource.xml b/doc/classes/Resource.xml index d4210cd26c2..45d40334dde 100644 --- a/doc/classes/Resource.xml +++ b/doc/classes/Resource.xml @@ -4,7 +4,7 @@ Base class for all resources. - Resource is the base class for all resource types, serving primarily as data containers. They are reference counted and freed when no longer in use. They are also loaded only once from disk, and further attempts to load the resource will return the same reference (all this in contrast to a [Node], which is not reference counted and can be instanced from disk as many times as desired). Resources can be saved externally on disk or bundled into another object, such as a [Node] or another resource. + Resource is the base class for all Godot-specific resource types, serving primarily as data containers. They are reference counted and freed when no longer in use. They are also cached once loaded from disk, so that any further attempts to load a resource from a given path will return the same reference (all this in contrast to a [Node], which is not reference counted and can be instanced from disk as many times as desired). Resources can be saved externally on disk or bundled into another object, such as a [Node] or another resource. https://docs.godotengine.org/en/3.1/getting_started/step_by_step/resources.html @@ -14,6 +14,7 @@ + Virtual function which can be overridden to customize the behavior value of [method setup_local_to_scene]. @@ -29,6 +30,7 @@ + If [member resource_local_to_scene] is enabled and the resource was loaded from a [PackedScene] instantiation, returns the local scene where this resource's unique copy is in use. Otherwise, returns [code]null[/code]. @@ -42,6 +44,8 @@ + This method is called when a resource with [member resource_local_to_scene] enabled is loaded from a [PackedScene] instantiation. Its behavior can be customized by overriding [method _setup_local_to_scene] from script. + For most resources, this method performs no base logic. [ViewportTexture] performs custom logic to properly set the proxy texture and flags in the local viewport. @@ -50,12 +54,13 @@ - Sets the path of the resource. Differs from [code]set_path()[/code], if another [code]Resource[/code] exists with "path" it over-takes it, instead of failing. + Sets the path of the resource, potentially overriding an existing cache entry for this path. This differs from setting [member resource_path], as the latter would error out if another resource was already cached for the given path. + If [code]true[/code], the resource will be made unique in each instance of its local scene. It can thus be modified in a scene instance without impacting other instances of that same scene. The name of the resource. This is an optional identifier. diff --git a/doc/classes/ResourceFormatLoader.xml b/doc/classes/ResourceFormatLoader.xml index 29973836a44..8cad7968598 100644 --- a/doc/classes/ResourceFormatLoader.xml +++ b/doc/classes/ResourceFormatLoader.xml @@ -4,9 +4,9 @@ Loads a specific resource type from a file. - Godot loads resources in the editor or in exported games using ResourceFormatLoaders. They get queried when you call [code]load[/code], or when a resource with internal dependencies is loaded. Each file type may load as a different resource type, so multiple ResourceFormatLoader are registered in the engine. - Extending this class allows you to define your own. You should give it a global class name with [code]class_name[/code] for it to be registered. You may as well implement a [ResourceFormatSaver]. - Note: You can also extend [EditorImportPlugin] if the resource type you need exists but Godot is unable to load its format. Choosing one way over another depends if the format is suitable or not for the final exported game. Example: it's better to import .PNG textures as .STEX first, so they can be loaded with better efficiency on the graphics card. + Godot loads resources in the editor or in exported games using ResourceFormatLoaders. They are queried automatically via the [ResourceLoader] singleton, or when a resource with internal dependencies is loaded. Each file type may load as a different resource type, so multiple ResourceFormatLoaders are registered in the engine. + Extending this class allows you to define your own loader. Be sure to respect the documented return types and values. You should give it a global class name with [code]class_name[/code] for it to be registered. Like built-in ResourceFormatLoaders, it will be called automatically when loading resources of its handled type(s). You may also implement a [ResourceFormatSaver]. + Note: You can also extend [EditorImportPlugin] if the resource type you need exists but Godot is unable to load its format. Choosing one way over another depends if the format is suitable or not for the final exported game. For example, it's better to import [code].png[/code] textures as [code].stex[/code] ([StreamTexture]) first, so they can be loaded with better efficiency on the graphics card. @@ -19,7 +19,7 @@ - If implemented, gets the dependencies of a given resource. If [code]add_types[/code] is [code]true[/code], paths should be appended [code]::TypeName[/code], where [code]TypeName[/code] is the class name of the dependency. Note that custom resource types defined by scripts aren't known by the [ClassDB], so you might just return [code]Resource[/code] for them. + If implemented, gets the dependencies of a given resource. If [code]add_types[/code] is [code]true[/code], paths should be appended [code]::TypeName[/code], where [code]TypeName[/code] is the class name of the dependency. Note that custom resource types defined by scripts aren't known by the [ClassDB], so you might just return [code]"Resource"[/code] for them. @@ -55,7 +55,7 @@ - Loads a resource when the engine finds this loader to be compatible. If the loaded resource is the result of an import, [code]original_path[/code] will target the source file. Returns a resource object if succeeded, or an [code]ERR_*[/code] constant listed in [@GlobalScope] if it failed. + Loads a resource when the engine finds this loader to be compatible. If the loaded resource is the result of an import, [code]original_path[/code] will target the source file. Returns a [Resource] object on success, or an [enum @GlobalScope.Error] constant in case of failure. @@ -66,7 +66,8 @@ - If implemented, renames dependencies within the given resource and saves it. [code]renames[/code] is a dictionary [code]{ String => String }[/code] mapping old dependency paths to new paths. Returns [code]OK[/code] on success, or an [code]ERR_*[/code] constant listed in [@GlobalScope] in case of failure. + If implemented, renames dependencies within the given resource and saves it. [code]renames[/code] is a dictionary [code]{ String => String }[/code] mapping old dependency paths to new paths. + Returns [constant @GlobalScope.OK] on success, or an [enum @GlobalScope.Error] constant in case of failure. diff --git a/doc/classes/ResourceFormatSaver.xml b/doc/classes/ResourceFormatSaver.xml index 820faa20318..c88eefb8f88 100644 --- a/doc/classes/ResourceFormatSaver.xml +++ b/doc/classes/ResourceFormatSaver.xml @@ -4,8 +4,8 @@ Saves a specific resource type to a file. - The engine can save resources when you do it from the editor, or when you call [method ResourceSaver.save]. This is accomplished with multiple [code]ResourceFormatSaver[/code]s, each handling its own format. - By default, Godot saves resources as [code].tres[/code], [code].res[/code] or another built-in format, but you can choose to create your own format by extending this class. You should give it a global class name with [code]class_name[/code] for it to be registered. You may as well implement a [ResourceFormatLoader]. + The engine can save resources when you do it from the editor, or when you use the [ResourceSaver] singleton. This is accomplished thanks to multiple [ResourceFormatSaver]s, each handling its own format and called automatically by the engine. + By default, Godot saves resources as [code].tres[/code] (text-based), [code].res[/code] (binary) or another built-in format, but you can choose to create your own format by extending this class. Be sure to respect the documented return types and values. You should give it a global class name with [code]class_name[/code] for it to be registered. Like built-in ResourceFormatSavers, it will be called automatically when saving resources of its recognized type(s). You may also implement a [ResourceFormatLoader]. @@ -16,7 +16,7 @@ - Gets the list of extensions for files this saver is able to write. + Returns the list of extensions available for saving the resource object, provided it is recognized (see [method recognize]). @@ -25,7 +25,7 @@ - Returns [code]true[/code] if the given resource object can be saved by this saver. + Returns whether the given resource object can be saved by this saver. @@ -38,7 +38,8 @@ - Saves the given resource object to a file. [code]flags[/code] is a bitmask composed with [code]FLAG_*[/code] constants defined in [ResourceSaver]. Returns [code]OK[/code] on success, or an [code]ERR_*[/code] constant listed in [@GlobalScope] if it failed. + Saves the given resource object to a file at the target [code]path[/code]. [code]flags[/code] is a bitmask composed with [enum ResourceSaver.SaverFlags] constants. + Returns [constant @GlobalScope.OK] on success, or an [enum @GlobalScope.Error] constant in case of failure. diff --git a/doc/classes/ResourceInteractiveLoader.xml b/doc/classes/ResourceInteractiveLoader.xml index a19700ad78a..6aa1f36f37d 100644 --- a/doc/classes/ResourceInteractiveLoader.xml +++ b/doc/classes/ResourceInteractiveLoader.xml @@ -1,10 +1,10 @@ - Interactive Resource Loader. + Interactive [Resource] loader. - Interactive Resource Loader. This object is returned by ResourceLoader when performing an interactive load. It allows to load with high granularity, so this is mainly useful for displaying load bars/percentages. + Interactive [Resource] loader. This object is returned by [ResourceLoader] when performing an interactive load. It allows to load with high granularity, so this is mainly useful for displaying loading bars/percentages. @@ -13,14 +13,14 @@ - Returns the loaded resource (only if loaded). Otherwise, returns null. + Returns the loaded resource if the load operation completed successfully, [code]null[/code] otherwise. - Returns the load stage. The total amount of stages can be queried with [method get_stage_count] + Returns the load stage. The total amount of stages can be queried with [method get_stage_count]. @@ -34,13 +34,19 @@ - Poll the load. If OK is returned, this means poll will have to be called again. If ERR_FILE_EOF is returned, them the load has finished and the resource can be obtained by calling [method get_resource]. + Polls the loading operation, i.e. loads a data chunk up to the next stage. + Returns [constant @GlobalScope.OK] if the poll is successful but the load operation has not finished yet (intermediate stage). This means [method poll] will have to be called again until the last stage is completed. + Returns [constant @GlobalScope.ERR_FILE_EOF] if the load operation has completed successfully. The loaded resource can be obtained by calling [method get_resource]. + Returns another [enum @GlobalScope.Error] code if the poll has failed. + Polls the loading operation successively until the resource is completely loaded or a [method poll] fails. + Returns [constant @GlobalScope.ERR_FILE_EOF] if the load operation has completed successfully. The loaded resource can be obtained by calling [method get_resource]. + Returns another [enum @GlobalScope.Error] code if a poll has failed, aborting the operation. diff --git a/doc/classes/ResourceLoader.xml b/doc/classes/ResourceLoader.xml index 13d333429e5..6d4d6427e25 100644 --- a/doc/classes/ResourceLoader.xml +++ b/doc/classes/ResourceLoader.xml @@ -1,10 +1,12 @@ - Resource Loader. + Singleton used to load resource files. - Resource Loader. This is a static object accessible as [code]ResourceLoader[/code]. GDScript has a simplified load() function, though. + Singleton used to load resource files from the filesystem. + It uses the many [ResourceFormatLoader] classes registered in the engine (either built-in or from a plugin) to load files into memory and convert them to a format that can be used by the engine. + 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. @@ -17,6 +19,8 @@ + Returns whether a recognized resource exists for the given [code]path[/code]. + An optional [code]type_hint[/code] can be used to further specify the [Resource] type that should be handled by the [ResourceFormatLoader]. @@ -25,6 +29,7 @@ + Returns the dependencies for the resource at the given [code]path[/code]. @@ -42,6 +47,7 @@ + Deprecated method. Use [method has_cached] or [method exists] instead. @@ -50,6 +56,8 @@ + Returns whether a cached resource is available for the given [code]path[/code]. + Once a resource has been loaded by the engine, it is cached in memory for faster access, and future calls to the [method load] or [method load_interactive] methods will use the cached version. The cached resource can be overridden by using [method Resource.take_over_path] on a new resource for that same path. @@ -62,6 +70,11 @@ + Loads a resource at the given [code]path[/code], caching the result for further access. + The registered [ResourceFormatLoader]s are queried sequentially to find the first one which can handle the file's extension, and then attempt loading. If loading fails, the remaining ResourceFormatLoaders are also attempted. + An optional [code]type_hint[/code] can be used to further specify the [Resource] type that should be handled by the [ResourceFormatLoader]. + If [code]no_cache[/code] is [code]true[/code], the resource cache will be bypassed and the resource will be loaded anew. Otherwise, the cached resource will be returned if it exists. + Returns an empty resource if no ResourceFormatLoader could handle the file. @@ -72,7 +85,8 @@ - Load a resource interactively, the returned object allows to load with high granularity. + Starts loading a resource interactively. The returned [ResourceInteractiveLoader] object allows to load with high granularity, calling its [method ResourceInteractiveLoader.poll] method successively to load chunks. + An optional [code]type_hint[/code] can be used to further specify the [Resource] type that should be handled by the [ResourceFormatLoader]. diff --git a/doc/classes/ResourcePreloader.xml b/doc/classes/ResourcePreloader.xml index ba44d1ec62b..397606ae14d 100644 --- a/doc/classes/ResourcePreloader.xml +++ b/doc/classes/ResourcePreloader.xml @@ -5,6 +5,7 @@ This node is used to preload sub-resources inside a scene, so when the scene is loaded, all the resources are ready to use and can be retrieved from the preloader. + GDScript has a simplified [method @GDScript.preload] built-in method which can be used in most situations, leaving the use of [ResourcePreloader] for more advanced scenarios. diff --git a/doc/classes/ResourceSaver.xml b/doc/classes/ResourceSaver.xml index 89985836278..f1a968a132d 100644 --- a/doc/classes/ResourceSaver.xml +++ b/doc/classes/ResourceSaver.xml @@ -1,10 +1,11 @@ - Resource saving interface. + Singleton for saving Godot-specific resource types. - Resource saving interface, used for saving resources to disk. + Singleton for saving Godot-specific resource types to the filesystem. + It uses the many [ResourceFormatSaver] classes registered in the engine (either built-in or from a plugin) to save engine-specific resource data to text-based (e.g. [code].tres[/code] or [code].tscn[/code]) or binary files (e.g. [code].res[/code] or [code].scn[/code]). @@ -28,24 +29,33 @@ - Saves a resource to disk. + Saves a resource to disk to the given path, using a [ResourceFormatSaver] that recognizes the resource object. + The [code]flags[/code] bitmask can be specified to customize the save behavior. + Returns [constant @GlobalScope.OK] on success. + Save the resource with a path relative to the scene which uses it. + Bundles external resources. + Change the [member Resource.resource_path] of the saved resource to match its new location. + Do not save editor-specific metadata (identified by their [code]__editor[/code] prefix). + Save as big endian (see [member File.endian_swap]). + Compress the resource on save using [constant File.COMPRESSION_ZSTD]. Only available for binary resource types. + Take over the paths of the saved subresources (see [method Resource.take_over_path]). diff --git a/modules/gdnative/config.py b/modules/gdnative/config.py index a36e76287a7..708504306bf 100644 --- a/modules/gdnative/config.py +++ b/modules/gdnative/config.py @@ -6,6 +6,7 @@ def configure(env): def get_doc_classes(): return [ + "@NativeScript", "ARVRInterfaceGDNative", "GDNative", "GDNativeLibrary", diff --git a/doc/classes/@NativeScript.xml b/modules/gdnative/doc_classes/@NativeScript.xml similarity index 100% rename from doc/classes/@NativeScript.xml rename to modules/gdnative/doc_classes/@NativeScript.xml diff --git a/modules/gdscript/config.py b/modules/gdscript/config.py index 95b40d90af0..a525eedaaa0 100644 --- a/modules/gdscript/config.py +++ b/modules/gdscript/config.py @@ -6,6 +6,7 @@ def configure(env): def get_doc_classes(): return [ + "@GDScript", "GDScript", "GDScriptFunctionState", "GDScriptNativeClass", diff --git a/doc/classes/@GDScript.xml b/modules/gdscript/doc_classes/@GDScript.xml similarity index 100% rename from doc/classes/@GDScript.xml rename to modules/gdscript/doc_classes/@GDScript.xml diff --git a/modules/visual_script/config.py b/modules/visual_script/config.py index 07a04507345..04e1a40b816 100644 --- a/modules/visual_script/config.py +++ b/modules/visual_script/config.py @@ -6,6 +6,7 @@ def configure(env): def get_doc_classes(): return [ + "@VisualScript", "VisualScriptBasicTypeConstant", "VisualScriptBuiltinFunc", "VisualScriptClassConstant", diff --git a/doc/classes/@VisualScript.xml b/modules/visual_script/doc_classes/@VisualScript.xml similarity index 100% rename from doc/classes/@VisualScript.xml rename to modules/visual_script/doc_classes/@VisualScript.xml