KhronosGroup / KhronosGroup/glTF

Define a way to provide unique identifiers for glTF data (nodes/etc)

Open
#2,337 72 comments 188 reactions 0 assignees View on GitHub
Dominant language
HTML
Stars
7.8k
Forks
1.2k
Avg merge
17h 26m
Merged PRs (30d)
5

Description

Continuing from the discussion here: https://github.com/KhronosGroup/glTF/issues/1051#issuecomment-1744560817

The glTF standard does not currently endorse any particular way to define unique identifiers. There are no UIDs, nothing beyond names is provided to identify glTF objects. This can make it tricky for applications to deterministically keep track of objects in glTF files. The problem is not isolated to game engines, it also affects glTFX (formerly glXF) files.

The problem:

* You import a glTF scene into a game engine with node "MyNode".
* In-engine, you alter this node, such as by adding children, changing the materials, etc.
* In your modeling application, you rename to "OtherNode", or reparent to "Parent/MyNode", and re-export a glTF file.
* When the game engine imports this again, it will look for "MyNode" but not find it, so it will not be able to tell where to put the added children or custom materials, so they will be discarded, and they will have to be applied again.

Some options for solutions: (EDIT: Removed number 2)

1. Recommend using node names as unique identifiers, and do not add a UID property. This is in line with what [glTFX](https://github.com/KhronosGroup/glTF-External-Reference) already does, it can reference nodes in a glTF scene by unique name.

* Minor note: Godot already enforces unique node names, but in addition Godot also needs the path to match to be considered the same node, it doesn't follow a node's name around the tree.
* Implication: This would mean that the display name of a node must not change.

```js
"nodes": [
{
"name": "Block", // No other node may have this name, and it is expected to not change.
"mesh": 0
}
]
```

3. Create an extension `KHR_unique_id` that has one property: `"uid"` (and for glTFX, a way to refer to these).

```json
"nodes": [
{
"name": "Block",
"mesh": 0,
"extensions": {
"KHR_unique_id": {
"uid": "ab2e0958-b67d-4f28-8f6f-22e41c23a4cc"
}
}
}
]
```

4. Add a `"uid"` property to the base "core glTF" spec itself. This is probably not the preferred solution given that the glTF spec is pretty much frozen, but if we did add this, it wouldn't break either forward or backward compatibility because it is optional, so it could be done in a hypothetical glTF 2.1 (no need to wait for a hypothetical glTF 3.0).

5. EDIT: Another option, currently my favorite. This is a combination of ideas 1 and 3. Basically, we have an extension that enforces the constraint that glTF files have unique identifiers. By default, use the name as the unique identifier (idea 1), but optionally we can supply a separate UID (idea 3). This allows retroactively adding UIDs to files that didn't start with one (ex: node "A", renamed to "B" with UID "A", then it can track that as the same node).

Regardless of which option is chosen:
* We should define the scope of what glTF intends to support.
* Is pointing to a node or resource inside of a glTF something we want to support?
* Is keeping track of unique identifiers something we want to have in glTF? Why isn't the name suitable?
* Is it acceptable that changing a node name or path can break applications trying to reference that node?
* Is it sensible for applications to "look for" particular parts of a glTF file which it is "tailored" to have, or does this relationship create a new problem of "*My* specific game/engine knows what to do with *this* specific model, when it contains a node that has *this* specific ID"? ([see here](https://github.com/KhronosGroup/glTF/issues/1051#issuecomment-1745987737))
* Is modifying a glTF scene after import in a game engine considered an important use case? (I think yes) ([see here](https://github.com/KhronosGroup/glTF/issues/1051#issuecomment-1747029800))
* We must note that using this field is optional. This field is only to be used when the content creation program has its own UID system and therefore exporting UIDs can be done deterministically. We don't want exporters to generate random UIDs, as that would defeat the whole point of UIDs.
* We should note that UIDs are not guaranteed to be unique between different glTF files, and in fact for the UIDs to function as expected they should keep the same UIDs between different versions of the same file.
* We should ensure the glTFX format is able to refer to nodes using this UID (in addition to the glTFX itself being able to define UIDs for its nodes in case anything wants to reference the contents of a glTFX).
* We should note that UIDs are specifically only useful when the loader already knows what to expect when loading, such as in a game engine or in a glTFX file. UIDs are completely useless for dynamically loading arbitrary content at runtime in most applications which are not looking for UIDs.
* We must work toward solving all of these questions in good faith.

Contributor guide

Open the contributing guide

Research direction

Read the linked discussion in issue #1051 and the glTFX format context first. Compare the listed identifier approaches and resolve scope, persistence, optionality, cross-file uniqueness, and glTFX references; done means the project has a decided, actionable standard or extension proposal.

Written by the indexing model from the issue text.

Assessment

Domain
computer-graphics
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.