Skip to content

Refactor bevy_gltf#15994

Merged
alice-i-cecile merged 18 commits intobevyengine:mainfrom
hukasu:refactor_load_gltf
Feb 26, 2025
Merged

Refactor bevy_gltf#15994
alice-i-cecile merged 18 commits intobevyengine:mainfrom
hukasu:refactor_load_gltf

Conversation

@hukasu
Copy link
Copy Markdown
Contributor

@hukasu hukasu commented Oct 18, 2024

Objective

Refactor bevy_gltf, the criteria for the split is kind of arbitrary but at least it is not a 2.6k line file.

Solution

Move methods and structs found in bevy_gltf/loader.rs into multiple new modules.

Testing

cargo run -p ci

@github-actions
Copy link
Copy Markdown
Contributor

Welcome, new contributor!

Please make sure you've read our contributing guide and we look forward to reviewing your pull request shortly ✨

@IQuick143 IQuick143 added C-Code-Quality A section of code that is hard to understand or change D-Modest A "normal" level of difficulty; suitable for simple features or challenging fixes S-Needs-Review Needs reviewer attention (from anyone!) to move forward A-glTF Related to the glTF 3D scene/model format labels Oct 19, 2024
@alice-i-cecile alice-i-cecile added this to the 0.16 milestone Oct 19, 2024
@suprohub
Copy link
Copy Markdown

any updates?

@hukasu
Copy link
Copy Markdown
Contributor Author

hukasu commented Dec 16, 2024

The team is focused on 0.15.1, i'm in wait until 0.16 becames the target, then i will merge and do the comments

@BenjaminBrienen BenjaminBrienen added S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Jan 22, 2025
@hukasu hukasu closed this Feb 18, 2025
@hukasu hukasu force-pushed the refactor_load_gltf branch from 3469d1a to 73970d0 Compare February 18, 2025 13:11
@hukasu
Copy link
Copy Markdown
Contributor Author

hukasu commented Feb 18, 2025

there were too many changes on bevy_gltf since my last commit, will restart from main, will reopen when i commit something

@hukasu hukasu reopened this Feb 18, 2025
@hukasu
Copy link
Copy Markdown
Contributor Author

hukasu commented Feb 18, 2025

@alice-i-cecile can we get this moving now? who would be SME on this topic to do the reviews?

Copy link
Copy Markdown
Contributor

@thepackett thepackett left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall this seems like a good PR. Having read through the GltfLoader code before, this is a significant improvement. I ran CI locally successfully and was able to confirm that examples using Gltf assets were working as expected. The only question I have is whether or not the extension traits should be public or not.

@alice-i-cecile alice-i-cecile added S-Needs-Review Needs reviewer attention (from anyone!) to move forward and removed S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged labels Feb 20, 2025
Copy link
Copy Markdown
Contributor

@andriyDev andriyDev left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not a fan of how many extension traits there are. This doesn't seem necessary, and results in a bunch of tiny files which hurts readability IMO. For example crates/bevy_gltf/src/ext/scene.rs is a whopping 14 lines. Jumping to this file just to see "oh this is just an extension trait" is quite underwhelming.

I would prefer just free functions for most of these (like the original implementation), just organized into modules more. For example, rather than node.node_name(), we just have node_name(&node) and node_transform(&node) and so on. But with the important part being that node_name and node_transform should be in a mod node.

One case where "extension traits" is likely desirable is labels - these could all be a single trait ToLabel which Scene, Skin, Texture, etc can implement. Now all these disparate label stuffs can be brought under one roof and we can see how all of these are really the same thing over and over again. Of course whether this really is the way we want to go I'm not sure (for example Skin already breaks this pattern since it wants a inverse_bind_matrics_label version - though this could just sit next to the trait implementations as inverse_bind_matrics_label_for_skin to again keep the similar implementations together.

@alice-i-cecile alice-i-cecile added S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Feb 20, 2025
@hukasu
Copy link
Copy Markdown
Contributor Author

hukasu commented Feb 20, 2025

@andriyDev see if this solution is satisfactory

Copy link
Copy Markdown
Contributor

@rparrett rparrett left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added some specific suggestions about the ext module, though I think I generally agree that this is feeling excessively "enterprise-grade."

I don't really agree with the way the changeset is presented. The current arrangement of "the loader stuff is in loader.rs" is logical and not necessarily worse than an "arbitrary" split.

@pcwalton
Copy link
Copy Markdown
Contributor

@mockersf This PR makes more small files than I personally would, but it's definitely better than the current monster load_gltf function.

@hukasu
Copy link
Copy Markdown
Contributor Author

hukasu commented Feb 25, 2025

I see following code by jumping between different files easier that jumping between different locations on the same file

@mockersf
Copy link
Copy Markdown
Member

I see following code by jumping between different files easier that jumping between different locations on the same file

There's a balance to reach, and this PR takes it too far in the other direction in my opinion

@greeble-dev
Copy link
Copy Markdown
Contributor

Throwing in my 2 cents as someone who's looking to do work on gltf in future:

  • I like the overall direction of the change.
  • I agree that some of the files seem too small.
  • On the other hand, there's still chunks of loader/mod.rs that could be refactored into some of the smaller files?
    • E.g. gltf_ext/mesh.rs is small now, but there's still 100+ lines in the loader that could move there in a follow up PR.
  • Speaking selfishly, I'd much prefer a slightly overdone refactor to no refactor at all.

@hukasu
Copy link
Copy Markdown
Contributor Author

hukasu commented Feb 25, 2025

E.g. gltf_ext/mesh.rs is small now, but there's still 100+ lines in the loader that could move there in a follow up PR.

my first go into this at the tail end of 0.14 was a lot more aggressive with the changes, including breaking the contents of load_gltf, load_material, etc, methods into smaller methods, but there is already pushback with the current changes, so my idea was to leave to a different PR

@alice-i-cecile alice-i-cecile added S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Feb 25, 2025
@alice-i-cecile
Copy link
Copy Markdown
Member

alice-i-cecile commented Feb 25, 2025

I've finally taken a proper look at this, and I'm broadly on board with this. Definitely a bit aggressive, but it's at least clear. It's much better than the status quo, so I'm going to merge this now.

@alice-i-cecile alice-i-cecile added this pull request to the merge queue Feb 25, 2025
@alice-i-cecile alice-i-cecile removed this pull request from the merge queue due to a manual request Feb 25, 2025
Copy link
Copy Markdown
Member

@alice-i-cecile alice-i-cecile left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I changed my mind. I do think this is better than the status quo, but I'm uncomfortable with the single item files, especially since these files feel mostly complete.

Is there another splitting strategy that we can use?

@hukasu
Copy link
Copy Markdown
Contributor Author

hukasu commented Feb 25, 2025

  1. I'm ok with merging the types on assets/ into a single file
  2. I could also merge the types on extensions/ into a single file, but for this one I would vote against, as to have a clearer view of which extensions we already have
  3. I could also merge the methods on gltf_ext/ into a single file, but I would prefer not to, my reasoning for the split was, if the main type of the method is present in gltf::N or gltf::json::N, I put the method in gltf_ext/N, so methods that use gltf::Gltf or gltf::Document would go on the root, and gltf::texture::Texture and gltf::json::texture::Info would go into gltf_ext/texture.rs, etc
  4. gltf_ext/extras.rs I can merge with the module root or implement as From for the components

@hukasu
Copy link
Copy Markdown
Contributor Author

hukasu commented Feb 25, 2025

  1. ImageOrPath and DataUri are in separate modules because I couldn't think of a name for the module that would work

@alice-i-cecile
Copy link
Copy Markdown
Member

alice-i-cecile commented Feb 25, 2025

Let's go with 1 and 4, and then resolve 5 by moving them back into lib.rs for now? I like the extensions being separate too.

@hukasu
Copy link
Copy Markdown
Contributor Author

hukasu commented Feb 25, 2025

4 by moving to mod.rs or impl From?

@alice-i-cecile
Copy link
Copy Markdown
Member

Let's go with the From route. Although if I understand correctly, the conversion is fallible, in which case it should be TryFrom.

@hukasu
Copy link
Copy Markdown
Contributor Author

hukasu commented Feb 26, 2025

is my solution for 4 satisfactory?

@alice-i-cecile
Copy link
Copy Markdown
Member

I quite like your final solution for 4. I think this is a nicer balance now; thanks for your patience. These sorts of reorganization PRs are quite painful due to merge conflicts and bikeshedding, but it's important to do them every now and then.

@alice-i-cecile alice-i-cecile added this pull request to the merge queue Feb 26, 2025
Merged via the queue into bevyengine:main with commit 11db717 Feb 26, 2025
30 checks passed
@hukasu hukasu deleted the refactor_load_gltf branch February 26, 2025 10:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-glTF Related to the glTF 3D scene/model format C-Code-Quality A section of code that is hard to understand or change D-Modest A "normal" level of difficulty; suitable for simple features or challenging fixes S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it X-Contentious There are nontrivial implications that should be thought through

Projects

None yet

Development

Successfully merging this pull request may close these issues.