Breaking Change Meta Issue

[atteneder]

This is a collection of API or behavior breaking changes that are subject to be addressed in the next major release.

Preparations

• Add Async suffix to all async methods (gh issue) and deprecate the old names.
• Go through accepted SonarQube issues and evaluate if they can be resolved or require breaking changes.

7.0

Maintenance

• Bump minimum required version to 2021 LTS (Enterprise EOL mid-October 2025) or 2022 LTS (Enterprise EOL mid-April 2026)
• Update all dependencies and soft dependency versions
• Drop support for com.unity.rendering.hybrid and Entities versions 0.x
• Remove
  • Everything tagged with Obsolete attribute
  • Schema.MeshPrimitiveBase: GetHashCode,Equals
  • Schema.Attributes: GetHashCode,Equals
  • Schema.MorphTarget: GetHashCode,Equals
  • Schema.TextureBase: GetHashCode,Equals
• Remove Legacy Shader Graphs (if feasible).
• Consistent nodeId type uint in GltfWriter
  • AddMeshToNode

Behavioral

• Change default logger to be ConsoleLogger without taking away the opportunity to unset the logger to null.
• Finish Builder construction for GltfImport?
• Consider making all asmdefs auto-referenced to avoid users not getting how to setup manual references in their asmdefs.

Code Style and Refactorings

• Seal all classes not intended for inheritance.
  • GltfEntityAsset ?
  • GltfImport ? potentially after refactoring it.
• IInstantiator.AddPrimitive
  • Rename IInstantiator.AddPrimitive to IInstantiator.AddMesh(Result). Not (glTF) primitives are added/assigned, but MeshResults.
  • AddPrimitive parameter morphTargetWeights can arguably be part of MeshResult.
  • Remove MeshResult.materialIndices. Users should instead use MeshResult.primitiveIndices to query the material from the MeshPrimitive.
  • If you then also remove the meshIndex from MeshResult (and re-add it as AddPrimitive paramter), it becomes identical to MeshAssignment. Consequently MeshAssignment could be replaced with MeshResult.
• (TBD) Remove GltfImport.GetSource* and instead offer RootBase GltfImport.GetSourceRoot and add all kinds of query methods to RootBase. E.g.: RootBase.GetMesh(index).
• IInstantiator.CreateNode: Add node name as parameter instead of IInstantiator.SetNodeName.
• Don't hard-code node name fallback to mesh primitive name in GltfImport. Implement it in (GameObject)Instantiator instead.
• GltfImport.InstantiateScene should return a generic SceneInstance type (GameObjectSceneInstance or EntitySceneInstance).
• Use NativeArray<T>.ReadOnly wherever it's not required or dangerous to change the data.

Schema Classes

• Settle JsonUtility/Newtonsoft discrepancy
• Ensure metadata round-trip
  • Finish arbitrary access (via Newtonsoft or similar)
• Add schema classes required for Animation Pointer (iirc animation clip extensions?)
• If Newtonsoft stays, add extension classes to everything, so that adding it later on won't introduce API breaks.

Vague Technical Debt (to be triaged)

• Remove as many scripting defines as possible.
  • Investigate if they can be turned into runtime settings.
  • Remove package/version define dependant API alternations.
  • Evaluate if GLTFAST_THREADS is still required (for Web builds).
• Go through all TODO, FIXME, HACK comments
• Go through all Unity version scripting defines and remove if possible
  • #if UNITY_202x_y_OR_NEWER
• Go through Monobehavior methods (Awake,Start,...) that are async void and see if they can be turned to async Task (removes SonarQube complaint).