Merge tag 'release/6.1.0' into openupm

Release 6.1.0

.yamato/project.metafile

@@ -18,8 +18,8 @@ upm_test_platforms:
   - name: win
     type: Unity::VM
     flavor: b1.large
-    image: package-ci/win10:stable
+    image: package-ci/win10:v4
   - name: mac
     type: Unity::VM::osx
-    image: package-ci/mac:stable
+    image: package-ci/macos-13:v4
     flavor: m1.mac

.yamato/upm-ci.yml

@@ -6,7 +6,7 @@ upm_ci_pack:
   name: "Pack"
   agent:
     type: Unity::VM
-    image: package-ci/ubuntu:stable
+    image: package-ci/ubuntu-22.04:v4
     flavor: b1.small
   commands:
     - npm install upm-ci-utils@stable -g --registry {{upm_ci_registry}}
@@ -43,7 +43,7 @@ upm_ci_publish_dry_run:
   name: "Dry Run Publish to Internal Registry"
   agent:
     type: Unity::VM
-    image: package-ci/win10:stable
+    image: package-ci/win10:v4
     flavor: b1.small
   commands:
     - npm install upm-ci-utils@stable -g --registry {{ upm_ci_registry }}
@@ -67,7 +67,7 @@ upm_ci_publish:
   name: "Publish to Internal Registry"
   agent:
     type: Unity::VM
-    image: package-ci/win10:stable
+    image: package-ci/win10:v4
     flavor: b1.small
   commands:
     - npm install upm-ci-utils@stable -g --registry {{ upm_ci_registry }}

CHANGELOG.md

@@ -4,15 +4,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.1.0] - 2024-01-17
+
+### Added
+- (Documentation) Explanation and user case for the add-on API
+- `GltfImport.IsTextureYFlipped` to support non-default texture orientations
+
+### Changed
+- Documentation improvements
+- Auto-formatted all markdown, USS, UXML and shader code
+- CI maintenance
+
+### Fixed
+- Updated references to *KTX for Unity*
+
 ## [6.0.1] - 2023-10-11
 
 ### Fixed
 - Compilation error when Animation module is disabled and Newtonsoft JSON package installed.
+- Compilation on Unity 2020 LTS
 
 ## [6.0.0] - 2023-10-04
 
 ### Added
-- Custom Extension API (`GLTFast.Extensions` namespace)
+- Custom Add-On API (`GLTFast.Addons` namespace)
 - Support for alternative JSON parsing via Newtonsoft JSON
 - `Accessor.ElementByteSize`: Byte size of one element of that accessor
 - `Accessor.ByteSize`: Overall byte size
@@ -27,6 +42,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - (Export) Clearcoat material export support for HDRP Lit shader
 
 ### Changed
+- Bumped minimum Unity version to 2020.3.48f1
 - Renamed `GltfAnimation` to `Animation` for consistent naming.
 - Bumped Burst dependency version to 1.8.4
 - Bumped Mathematics dependency version to 1.3.1
@@ -41,10 +57,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Runtime tests
 - (Export) Setting for deterministic export (limits concurrency to ensure consistent output)
 - (DOTS) Support for [Entities 1.0][Entities1.0]
+
 ### Changed
 - Optimized `Accessor.GetAccessorAttributeType`
 - Optimized `GltfEntityAsset.ClearScenes` via Burst
-- Bump minimum unity version from 2019.4.7f1 to 2019.4.40f1
+- Bump minimum Unity version from 2019.4.7f1 to 2019.4.40f1
 
 ### Fixed
 - Compiler errors and warnings on Unity 2023.2 (and newer) due to using obsolete types.
@@ -489,7 +506,7 @@ This release contains multiple breaking changes. Please read the [upgrade guide]
 ## [4.3.4] - 2021-10-26
 
 ### Added
-- Option to turn off Editor import by adding `GLTFAST_EDITOR_IMPORT_OFF` to the project's *Scripting Define Symbols* in the *Player Settings* (#256)  
+- Option to turn off Editor import by adding `GLTFAST_EDITOR_IMPORT_OFF` to the project's *Scripting Define Symbols* in the *Player Settings* (#256)
 
 ### Fixed
 - Import of glTFs with no meshes (#257)
@@ -675,7 +692,7 @@ This release contains multiple breaking changes. Please read the [upgrade guide]
 - Support for unsigned byte joint indices
 
 ### Changed
-- Accelerated loading meshes by obtaining and setting bounds from accessors min/max values instead of recalculating them  
+- Accelerated loading meshes by obtaining and setting bounds from accessors min/max values instead of recalculating them
 - Improved log message when DracoUnity/KtxUnity packages are missing
 - Restored/simplified `GLTFast.LoadGltfBinary`, allowing users to load glTF binary files from byte arrays directly (also added documentation; fixes #148)
 

CONTRIBUTING.md

@@ -7,36 +7,55 @@ of guidelines to ensure that your extensions can be easily integrated.
 
 ## Communication
 
-First, please read through our [code of conduct](CODE_OF_CONDUCT.md), as we
+Please read through our [code of conduct][COC], as we
 expect all our contributors to follow it.
 
-Second, before starting on a project that you intend to contribute in any form, we
-**strongly** recommend posting on our
-[Issues page](https://github.com/atteneder/glTFast/issues) and
-briefly outline the changes you plan to make. This will enable us to provide
-some context that may be helpful for you. This could range from advice and
-feedback on how to optimally perform your changes or reasons for not doing it.
+For inquiries of all sorts, feel free to raise an issue by going to the
+[issues page][issues] and click the *New issue* button.
 
-Lastly, if you're looking for input on what to contribute browse the GitHub
-issues, especially ones with the `help wanted` or `good first issue` label.
+If you're looking for ideas on ways to contribute browse the [issues][issues],
+especially ones with the `help wanted` or `good first issue` label.
 
-## Git Branches
+## Preparation
 
-The main branch corresponds to the most recent version of the project. Note
-that this branch may be unstable and may be newer that the latest release.
+Before starting to work on a contribution we recommend searching within the
+existing [issues][issues] and [pull requests][pulls] for similar topics to
+avoid redundant efforts and make sure you got all contextual information.
 
-When contributing to the project, please make sure that your Pull Request (PR)
-contains the following:
+Feel free to propose ideas upfront via an [issue][issues] that briefly outlines
+your intended changes. We'll then try to give you advice and feedback on how to
+optimally implement those changes or, if justifiable, reasons to abandon an
+idea. This pre-evaluation can raise the chances of getting a contribution
+accepted.
+
+## Version Control
+
+*glTFast* uses [Git][Git] and [GitHub][repo] for version control.
+
+## Submission via Pull Request
+
+Changes can be proposed via [pull requests (PR)][GithubDocPR] on the [pull requests][pulls] page.
+
+Please make sure that your PR contains the following:
 
 - Detailed description of the changes performed
 - Corresponding changes to documentation, changelog and unit tests
 - Summary of the tests performed to validate your changes
 - Issue numbers that the PR resolves (if any)
 
+PRs will be transferred to an internal, mirrored repository to undergo review and (automated) tests that use Unity's internal tools and infrastructure. If those tests and reviews are not successful, we'll help you resolve remaining issues and merge your work, once it passes all tests. The merge will happen on the mirrored repository and the original pull requests will get closed with a proper notification about expected release version and date.
+
 ## Contributor License Agreements
 
 When you open a pull request, you will be asked to acknowledge our Contributor
 License Agreement. You will have to confirm that your Contributions are your
 original creation and that you have complete right and authority to make your
-Contributions. We allow both individual contributions and contributions made on
+contributions. We allow both individual contributions and contributions made on
 behalf of companies.
+
+[COC]: (CODE_OF_CONDUCT.md)
+[Git]: https://git-scm.com/
+[repo]: https://github.com/Unity-Technologies/com.unity.cloud.gltfast
+[issues]: https://github.com/Unity-Technologies/com.unity.cloud.gltfast/issues
+[pulls]: https://github.com/Unity-Technologies/com.unity.cloud.gltfast/pulls
+[GithubDocPR]: https://docs.github.com/pull-requests

Documentation~/ExportRuntime.md

@@ -35,7 +35,7 @@ public class TestExport : MonoBehaviour {
 
         // Example of gathering GameObjects to be exported (recursively)
         var rootLevelNodes = GameObject.FindGameObjectsWithTag("ExportMe");
-        
+
         // GameObjectExport lets you create glTFs from GameObject hierarchies
         var export = new GameObjectExport();
 
@@ -76,14 +76,14 @@ public class TestExport : MonoBehaviour {
 
         // ExportSettings and GameObjectExportSettings allow you to configure the export
         // Check their respective source for details
-        
+
         // ExportSettings provides generic export settings
         var exportSettings = new ExportSettings {
             Format = GltfFormat.Binary,
             FileConflictResolution = FileConflictResolution.Overwrite,
             // Export everything except cameras or animation
             ComponentMask = ~(ComponentType.Camera | ComponentType.Animation),
-            // Boost light intensities 
+            // Boost light intensities
             LightIntensityFactor = 100f,
         };
 

Documentation~/ImportRuntime.md

@@ -27,7 +27,7 @@ async void LoadGltfBinaryFromMemory() {
     byte[] data = File.ReadAllBytes(filePath);
     var gltf = new GltfImport();
     bool success = await gltf.LoadGltfBinary(
-        data, 
+        data,
         // The URI of the original data is important for resolving relative URIs within the glTF
         new Uri(filePath)
         );
@@ -92,7 +92,7 @@ async void Start() {
 
     if (success) {
         // Here you can customize the post-loading behavior
-        
+
         // Get the first material
         var material = gltf.GetMaterial();
         Debug.LogFormat("The first material is called {0}", material.name);
@@ -186,22 +186,22 @@ async void Start()
     var instantiator = new GameObjectInstantiator(gltfImport,transform);
     var success = await gltfImport.InstantiateMainSceneAsync(instantiator);
     if (success) {
-    
+
         // Get the SceneInstance to access the instance's properties
         var sceneInstance = instantiator.SceneInstance;
 
         // Enable the first imported camera (which are disabled by default)
         if (sceneInstance.Cameras is { Count: > 0 }) {
             sceneInstance.Cameras[0].enabled = true;
         }
-    
+
         // Decrease lights' ranges
         if (sceneInstance.Lights != null) {
             foreach (var glTFLight in sceneInstance.Lights) {
                 glTFLight.range *= 0.1f;
             }
         }
-    
+
         // Play the default (i.e. the first) animation clip
         var legacyAnimation = instantiator.SceneInstance.LegacyAnimation;
         if (legacyAnimation != null) {
@@ -219,7 +219,7 @@ When loading a glTF file, *Unity glTFast* logs messages of varying severity (err
 - Feed the information into an analytics framework
 - Display details to the users
 
-The provided component `GltfAsset` logs all of those messages to the console by default.  
+The provided component `GltfAsset` logs all of those messages to the console by default.
 
 You can customize logging by providing an implementation of [`ICodeLogger`][ICodeLogger] to methods like `GltfImport.Load` or `GltfImport.InstantiateMainScene`.
 
@@ -258,7 +258,7 @@ async Task CustomDeferAgentPerGltfImport() {
     deferAgent = new UninterruptedDeferAgent();
 
     var tasks = new List<Task>();
-    
+
     foreach( var url in manyUrls) {
         var gltf = new GLTFast.GltfImport(null,deferAgent);
         var task = gltf.Load(url).ContinueWith(

Documentation~/TableOfContents.md

@@ -1,14 +1,17 @@
-* [Overview](index.md)
+* [Unity glTFast](index.md)
+  * [Installation](installation.md)
+  * [Upgrade guides](UpgradeGuides.md)
 * [Features](features.md)
 * Runtime
-    * [Import](ImportRuntime.md)
-    * [Export](ExportRuntime.md)
+  * [Import](ImportRuntime.md)
+  * [Export](ExportRuntime.md)
 * Editor
-    * [Import](ImportEditor.md)
-    * [Export](ExportEditor.md)        
+  * [Import](ImportEditor.md)
+  * [Export](ExportEditor.md)
 * [Project Setup](ProjectSetup.md)
+* Use Cases
+  * [Use glTFast Add-on API to import custom data](UseCaseCustomExtras.md)
 * More Information
-    * [Upgrade Guides](UpgradeGuides.md)
-    * [Known Issues](KnownIssues.md)
-    * [Physical Light Units in glTF](LightUnits.md)
-    * [Implementation Details](ImplementationDetails.md)
+  * [Known Issues](KnownIssues.md)
+  * [Physical Light Units in glTF](LightUnits.md)
+  * [Implementation Details](ImplementationDetails.md)

Documentation~/UpgradeGuides.md

@@ -20,7 +20,7 @@ For now, both the Unity variant and the original version will receive updates.
 The C# namespaces are identical between the variants, so all you need to do is:
 
 - Removed original *glTFast* (with package identifier `com.atteneder.gltfast`).
-- Add *Unity glTFast* (`com.unity.cloud.gltfast`).
+- [Install *Unity glTFast*](installation.html) (`com.unity.cloud.gltfast`).
 - Update assembly definition references (if your project had any).
 - Update any dependencies in your packages manifest (if your package had any)
 
@@ -30,7 +30,7 @@ Unity forks have been created for *KtxUnity* and *DracoUnity* as well. If you've
 
 See their respective upgrade guides
 
-- Upgrade to [*KTX for Unity*](https://docs.unity3d.com/Packages/com.unity.cloud.ktx@3.0/manual/upgrade-guide.html)
+- Upgrade to [*KTX for Unity*](https://docs.unity3d.com/Packages/com.unity.cloud.ktx@3.2/manual/upgrade-guide.html)
 - Upgrade to *Draco for Unity* (coming soon)
 
 ### Keep using the original glTFast
@@ -153,7 +153,7 @@ async void Start() {
     var instantiator = new GameObjectInstantiator(gltfImport,transform);
     var success = gltfImport.InstantiateMainScene(instantiator);
     if (success) {
-        
+
         // Get the SceneInstance to access the instance's properties
         var sceneInstance = instantiator.SceneInstance;