godotengine
/
godot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
godot/doc/classes/ResourceUID.xml

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

83 lines
3.3 KiB
XML
Raw Normal View History

Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
<?xml version="1.0" encoding="UTF-8" ?>
Add an XML schema for documentation This makes it easier to spot syntax errors when editing the class reference. The schema is referenced locally so validation can still work offline. Each class XML's schema conformance is also checked on GitHub Actions.
2022-02-14 13:18:53 +00:00
<class name="ResourceUID" inherits="Object" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
<brief_description>
Overhaul the top sections of the class reference (Core classes) (cherry picked from commit 04562662d38a83e1ac1fde2af9572ca38147e772)
2023-04-27 23:35:33 +00:00
A singleton that manages the unique identifiers of all resources within a project.
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
</brief_description>
<description>
Overhaul the top sections of the class reference (Core classes) (cherry picked from commit 04562662d38a83e1ac1fde2af9572ca38147e772)
2023-04-27 23:35:33 +00:00
Resource UIDs (Unique IDentifiers) allow the engine to keep references between resources intact, even if files can renamed or moved. They can be accessed with [code]uid://[/code].
[ResourceUID] keeps track of all registered resource UIDs in a project, generates new UIDs, and converts between their string and integer representations.
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
</description>
<tutorials>
</tutorials>
<methods>
<method name="add_id">
doc: Use self-closing tags for `return` and `argument` For the time being we don't support writing a description for those, preferring having all details in the method's description. Using self-closing tags saves half the lines, and prevents contributors from thinking that they should write the argument or return documentation there.
2021-07-30 13:28:05 +00:00
<return type="void" />
Rename the argument tag to param in XML documentation
2022-08-06 18:11:48 +00:00
<param index="0" name="id" type="int" />
<param index="1" name="path" type="String" />
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
<description>
Add ResourceUID documentation
2022-08-03 17:59:11 +00:00
Adds a new UID value which is mapped to the given resource path.
Fails with an error if the UID already exists, so be sure to check [method has_id] beforehand, or use [method set_id] instead.
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
</description>
</method>
[ResourceUID] Use CryptoCore::RandomGenerator for IDs.
2022-02-07 17:42:46 +00:00
<method name="create_id">
doc: Use self-closing tags for `return` and `argument` For the time being we don't support writing a description for those, preferring having all details in the method's description. Using self-closing tags saves half the lines, and prevents contributors from thinking that they should write the argument or return documentation there.
2021-07-30 13:28:05 +00:00
<return type="int" />
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
<description>
Add ResourceUID documentation
2022-08-03 17:59:11 +00:00
Generates a random resource UID which is guaranteed to be unique within the list of currently loaded UIDs.
In order for this UID to be registered, you must call [method add_id] or [method set_id].
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
</description>
</method>
<method name="get_id_path" qualifiers="const">
doc: Use self-closing tags for `return` and `argument` For the time being we don't support writing a description for those, preferring having all details in the method's description. Using self-closing tags saves half the lines, and prevents contributors from thinking that they should write the argument or return documentation there.
2021-07-30 13:28:05 +00:00
<return type="String" />
Rename the argument tag to param in XML documentation
2022-08-06 18:11:48 +00:00
<param index="0" name="id" type="int" />
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
<description>
Add ResourceUID documentation
2022-08-03 17:59:11 +00:00
Returns the path that the given UID value refers to.
Fails with an error if the UID does not exist, so be sure to check [method has_id] beforehand.
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
</description>
</method>
<method name="has_id" qualifiers="const">
doc: Use self-closing tags for `return` and `argument` For the time being we don't support writing a description for those, preferring having all details in the method's description. Using self-closing tags saves half the lines, and prevents contributors from thinking that they should write the argument or return documentation there.
2021-07-30 13:28:05 +00:00
<return type="bool" />
Rename the argument tag to param in XML documentation
2022-08-06 18:11:48 +00:00
<param index="0" name="id" type="int" />
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
<description>
Add ResourceUID documentation
2022-08-03 17:59:11 +00:00
Returns whether the given UID value is known to the cache.
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
</description>
</method>
<method name="id_to_text" qualifiers="const">
doc: Use self-closing tags for `return` and `argument` For the time being we don't support writing a description for those, preferring having all details in the method's description. Using self-closing tags saves half the lines, and prevents contributors from thinking that they should write the argument or return documentation there.
2021-07-30 13:28:05 +00:00
<return type="String" />
Rename the argument tag to param in XML documentation
2022-08-06 18:11:48 +00:00
<param index="0" name="id" type="int" />
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
<description>
Add ResourceUID documentation
2022-08-03 17:59:11 +00:00
Converts the given UID to a [code]uid://[/code] string value.
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
</description>
</method>
ResourceUID: Fix `remove_id` binding Fixes #50833.
2021-07-25 09:54:48 +00:00
<method name="remove_id">
doc: Use self-closing tags for `return` and `argument` For the time being we don't support writing a description for those, preferring having all details in the method's description. Using self-closing tags saves half the lines, and prevents contributors from thinking that they should write the argument or return documentation there.
2021-07-30 13:28:05 +00:00
<return type="void" />
Rename the argument tag to param in XML documentation
2022-08-06 18:11:48 +00:00
<param index="0" name="id" type="int" />
ResourceUID: Fix `remove_id` binding Fixes #50833.
2021-07-25 09:54:48 +00:00
<description>
Add ResourceUID documentation
2022-08-03 17:59:11 +00:00
Removes a loaded UID value from the cache.
Fails with an error if the UID does not exist, so be sure to check [method has_id] beforehand.
ResourceUID: Fix `remove_id` binding Fixes #50833.
2021-07-25 09:54:48 +00:00
</description>
</method>
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
<method name="set_id">
doc: Use self-closing tags for `return` and `argument` For the time being we don't support writing a description for those, preferring having all details in the method's description. Using self-closing tags saves half the lines, and prevents contributors from thinking that they should write the argument or return documentation there.
2021-07-30 13:28:05 +00:00
<return type="void" />
Rename the argument tag to param in XML documentation
2022-08-06 18:11:48 +00:00
<param index="0" name="id" type="int" />
<param index="1" name="path" type="String" />
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
<description>
Add ResourceUID documentation
2022-08-03 17:59:11 +00:00
Updates the resource path of an existing UID.
Fails with an error if the UID does not exist, so be sure to check [method has_id] beforehand, or use [method add_id] instead.
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
</description>
</method>
<method name="text_to_id" qualifiers="const">
doc: Use self-closing tags for `return` and `argument` For the time being we don't support writing a description for those, preferring having all details in the method's description. Using self-closing tags saves half the lines, and prevents contributors from thinking that they should write the argument or return documentation there.
2021-07-30 13:28:05 +00:00
<return type="int" />
Rename the argument tag to param in XML documentation
2022-08-06 18:11:48 +00:00
<param index="0" name="text_id" type="String" />
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
<description>
Add ResourceUID documentation
2022-08-03 17:59:11 +00:00
Extracts the UID value from the given [code]uid://[/code] string.
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
</description>
</method>
</methods>
<constants>
<constant name="INVALID_ID" value="-1">
Add ResourceUID documentation
2022-08-03 17:59:11 +00:00
The value to use for an invalid UID, for example if the resource could not be loaded.
Its text representation is [code]uid://&lt;invalid&gt;[/code].
Implement Resource UIDs * Most resource types now have unique identifiers. * Applies to text, binary and imported resources. * File formats reference both by text and UID (when available). UID always has priority. * Resource UIDs are 64 bits for better compatibility with the engine. * Can be represented and used textually, example `uuid://dapwmgsmnl28u`. * A special binary cache file is used and exported, containing the mappings. Example of how it looks: ```GDScript [gd_scene load_steps=2 format=3 uid="uid://dw86wq31afig2"] [ext_resource type="PackedScene" uid="uid://bt36ojelx8q6c" path="res://subscene.scn" id="1_t56hs"] ``` GDScript, shaders and other special resource files can't currently provide UIDs, but this should be doable with special keywords on the files. This will be reserved for future PRs.
2021-07-23 19:01:18 +00:00
</constant>
</constants>
</class>