KhronosGroup / KhronosGroup/glTF-Sample-Assets
Folder and File Structure standards?
- Dominant language
- TypeScript
- Stars
- 1.1k
- Forks
- 107
- Avg merge
- 9h 39m
- Merged PRs (30d)
- 4
Description
I think we could use some standardization for folders and files.
There are a few of the unwritten rules I learned from other contributors a few years ago, when I started submitting assets to these repos.
I think these rules should be codified into the SubmittingModels.md documentation, but I would like feedback from other contributors before we add this additional section. There are also a few typos in the md, but those shouldn't require discussion.
I propose to add this section to SubmittingModels.md :
### Folder and File Structure
Folder and file names must be consistent as this helps with tooling and automation.
* Asset top folder should use the same name as the `.gltf` file in the `/glTF` subfolder.
- For example `Models/ABeautifulGame` matches `Models/ABeautifulGame/glTF/ABeautifulGame.gltf`
* `metadata.json` file containing the asset metadata (see below).
* `README.body.md` file containing the asset description (see below).
* `/glTF` subfolder is mandatory, it should contain the asset with JSON .gltf, .bin, and all individual resources (such as textures).
- PNG textures are preferred to avoid compression artifacts; if a variant is desired with .jpeg resources it can be provided in a `/glTF-JPG` subfolder (see below).
* `/screenshot` subfolder is mandatory, it should contain the screenshot plus any other resources used in the README.md.
* `/glTF-Binary` subfolder is optional, if a variant is included for a [binary .glb](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#file-extensions-and-media-types).
* `/glTF-Draco` subfolder is optional, if a variant is included with compressed geometry using the extension [KHR_draco_mesh_compression](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_draco_mesh_compression).
* `/glTF-Embedded` subfolder is optional, if a variant is included for an [embedded .gltf](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#gltf-basics).
* `/glTF-IBL` subfolder is optional, if a variant is included using custom image-based lighting; for example with the extension [EXT_lights_image_based](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Vendor/EXT_lights_image_based).
* `/glTF-JPG` subfolder is optional, if a variant is included using resources in compressed .jpeg format.
* `/glTF-KTX-BasisU` subfolder is optional, if a variant is included with compressed textures using the extension [KHR_texture_basisu](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_texture_basisu).
* `/glTF-Quantized` subfolder is optional, if a variant is included with compressed geometry using the extension [KHR_mesh_quantization](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_mesh_quantization).
Contributor guide
Research direction
Start with SubmittingModels.md and review the proposed “Folder and File Structure” section, along with the typos mentioned in the issue. Confirm the folder and file rules with contributors, then update the documentation so the agreed standards and typo fixes are included.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100