Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[RFC] Move from cgmath to nalgebra #942

Closed
Moxinilian opened this issue Sep 13, 2018 · 16 comments
Closed

[RFC] Move from cgmath to nalgebra #942

Moxinilian opened this issue Sep 13, 2018 · 16 comments

Comments

@Moxinilian
Copy link
Member

@Moxinilian Moxinilian commented Sep 13, 2018

This RFC discusses the possibility of migrating Amethyst from a cgmath backend to an nalgebra backend.

While cgmath seems to be the most popular crate for maths in the Rust gamedev ecosystem, it seems like it is starting to lose speed: issues are no longer being answered too, pull requests are ignored and commit history has been very sparse lately. The lack of maintenance could become a critical issue in the long run.

Therefore, I suggest we consider dropping cgmath entirely from Amethyst and moving to nalgebra.
nalgebra is a mature linear algebra crate (it has been around since 2013), and seems to be tending towards becoming a standard for Rust gamedev.

Following are some of the advantages of nalgebra over cgmath:

  • Invested maintainer(s) financially supported by patrons, suggesting longevity
  • nphysics, the most advanced Rust physics library
  • Well documented with a large panel of features

Here are some cons:

  • cgmath is well in use in the Rust gamedev ecosystem (but that ecosystem remains in its infancy)
  • it seems that nalgebra is very generic, although the implications of this remain unclear
  • Rhuagh can no longer brag about having his name in the physics library

I still do believe it would be worth it in the long run, and again, nothing prevents us from contributing to nalgebra to fix what we believe to be cons.

If you have any other point you want me to add to this first post (be it in favor or against this proposal), please comment.

@dotellie

This comment has been minimized.

Copy link
Contributor

@dotellie dotellie commented Sep 13, 2018

In my opinion, the only reason to be afraid of the generic part of nalgebra is the documentation. I've never had any generics problems when using nalgebra and it functioned basically the same as cgmath does in Amethyst. When looking at the documentation however, there's lots of room for improvement to avoid user confusion. Take for example Vector3. When you go onto its documentation page you just see that it's a type declaration. It's not until you go onto VectorN that you actually see what functions it contains. Even then, you still have to filter out among the functions that Vector3 doesn't actually get and you also have to take into account a bunch of other traits that add functions to the vector. That's not a good experience and needs to be worked around somehow.

@randomPoison

This comment has been minimized.

Copy link
Member

@randomPoison randomPoison commented Sep 13, 2018

Personally I feel that both cgmath and nalgebra are pretty user-hostile (though I agree with @magnonellie that better documentation would go a long way towards resolving that issue). I don't feel like either library is well suited for gameplay code, HOWEVER I do think it would be a good idea to move Amethyst to use nalgebra for the reasons listed in the proposal. I'm especially interested in cleaner integration with nphysics, which seems like the most robust solution for collision detection and physics for Rust games. Being able to more easily get ncollide and nphysics integrated into Amethyst would be a big win in my opinion.

@azriel91

This comment has been minimized.

Copy link
Member

@azriel91 azriel91 commented Sep 14, 2018

Even then, you still have to filter out among the functions that Vector3 doesn't actually get and you also have to take into account a bunch of other traits that add functions to the vector. That's not a good experience and needs to be worked around somehow.

Rustdoc was improved at the end of july, and if I interpret this post correctly, I think you'll be able to see the relevant traits on the Vector3 page.

@dotellie

This comment has been minimized.

Copy link
Contributor

@dotellie dotellie commented Sep 14, 2018

I just tried cloning nalgebra and built its documentation with Rust 1.29. It's unfortunately not fixed. 😢

@erlend-sh

This comment has been minimized.

Copy link
Contributor

@erlend-sh erlend-sh commented Sep 14, 2018

Very glad to see the Amethyst devs rolling with this! By the way I split that discussion out to its own topic.

@sebcrozet will soon be moving his assorted math & physics libraries into a proper organisation. I expect that'll help Sébastien gradually onboard more collaborators with a stake in his libraries, such as you fine folks. There's plenty of room for contribution aside from the math stuff as well. For instance, Amethyst does a great job with "good first issue" labelling, something that could greatly benefit nalgebra & co as well. One good candidate would be API refactoring.

For introducing Amethyst users to game math without having to push them deep into the depths of nalgebra, I highly recommend borrowing whatever you want from the math tutorial we did for jMonkeyEngine:

https://wiki.jmonkeyengine.org/tutorials/math/assets/fallback/index.html

Please feel free to re-create those slides pretty much verbatim. I can only make some sense of it myself but I heard from literally hundreds of budding game devs who felt much more comfortable with basic game maths after going through this tutorial.

@sebcrozet

This comment has been minimized.

Copy link
Contributor

@sebcrozet sebcrozet commented Sep 15, 2018

I have created the github organization suggested by @erlend-sh: https://www.rustsim.org (github link: https://github.com/rustsim). It is called rustsim, meaning "rust simulation".

The idea of amethyst migrating to nalgebra is very interesting! If this migration does happen, feel free to ask me questions or ping me to review pull requests (even if they are not completely finished) if guidance is needed!

@magnonellie @azriel91 Actually, if no generic programming is needed, almost no feature of nalgebra (except for rustsim/nalgebra.org#6) require the user to import a trait anymore. I think those issues are the main source of confusion regarding the rustdoc-generated documentation: rust-lang/rust#32077 and rust-lang/rust#14072. That would ensure all methods available for type aliases are listed. (Looks like there is currently an ICE when trying to compile the doc of nalgebra though.)

@sebcrozet

This comment has been minimized.

Copy link
Contributor

@sebcrozet sebcrozet commented Sep 23, 2018

You may be interested by a crate I've just released nalgebra-glm and that will be maintained in the long term! You will find the rustdoc documentation there.

If you happen to migrate Amethyst to nalgebra, this could be a good starting point as it provides a simpler interface to nalgebra if you prefer to use 4x4 matrices instead of explicit transformation types. Also, all the types defined by nalgebra-glm are just aliases to nalgebra types, so you don't have to worry about interoperability with, e.g., nphysics in the future (besides converting 4x4 matrices to Isometry3 and vice-versa if you stick with matrices. Conversion methods are provided by nalgebra-glm too.)

@Moxinilian

This comment has been minimized.

Copy link
Member Author

@Moxinilian Moxinilian commented Sep 23, 2018

Regarding nphysics, another thing I think would be interesting to think about is its integration with specs. Rhusics had a whole thing for it to support the ECS, but the detached world of nphysics might make integration a bit tricky.

@simonpuchert

This comment has been minimized.

Copy link

@simonpuchert simonpuchert commented Sep 23, 2018

I noticed that an Amethyst build pulls in 3 different versions of cgmath. It might be a good idea to fix some of the "culprits" first. If cgmath itself is badly maintained, then surely old versions of it are even worse?
Fortunately, the worst "offender", specs (which uses cgmath 0.14) seems to have largely the same set of contributors as Amethyst and, from a quick search, only uses it for a benchmark (?).

@Moxinilian

This comment has been minimized.

Copy link
Member Author

@Moxinilian Moxinilian commented Sep 23, 2018

There is no reason for specs to use cgmath, so it's probably indeed just an example or a benchmark. This should be easy to remove.

@Moxinilian Moxinilian added this to the 0.10 milestone Sep 23, 2018
@Rhuagh

This comment has been minimized.

Copy link
Member

@Rhuagh Rhuagh commented Oct 2, 2018

Specs only include cgmath as a dev dependency so that shouldnt matter.

@ldesgoui

This comment has been minimized.

Copy link
Contributor

@ldesgoui ldesgoui commented Oct 2, 2018

Some discussion about nphysics and specs/ECS happened here:
https://discordapp.com/channels/425678876929163284/425679992244928512/496752768971833366

Summary:
sebcrozet is willing to permit integration into an ECS, a third party crate would integrate nphysics and specs and would be maintainted by someone else (Rhuagh volunteered), some experimentation is required (Rhuagh volunteered too)

@torkleyy

This comment has been minimized.

Copy link
Member

@torkleyy torkleyy commented Oct 3, 2018

I've never used nalgebra, but the fact that most things work with simple methods now sounds good! I'd like to avoid dropping rhusics though. How difficult would it be to accept nalgebra types there @Rhaugh?

@brendanzab

This comment has been minimized.

Copy link

@brendanzab brendanzab commented Oct 14, 2018

I'm just going to jump in and say I'd really support this move! It kinda spooked me when Amethyst started using cgmath... I hadn't done much work building a community around it, and the internals are quite icky! It was one of my early OSS libs, and I had no idea what I was doing six years ago. 😅

I've been really impressed with the great work @sebcrozet has done, and has continued to do in support of the maths and physics ecosystem for Rust!

@dotellie

This comment has been minimized.

Copy link
Contributor

@dotellie dotellie commented Oct 15, 2018

I haven't really said much about it, but I have started working on this and I'm almost done. 😄

@torkleyy

This comment has been minimized.

Copy link
Member

@torkleyy torkleyy commented Nov 11, 2018

Implemented by #1066 🎉

@torkleyy torkleyy closed this Nov 11, 2018
azriel91 added a commit to azriel91/amethyst that referenced this issue Nov 16, 2018
azriel91 added a commit to azriel91/amethyst that referenced this issue Nov 16, 2018
azriel91 added a commit to azriel91/amethyst that referenced this issue Nov 17, 2018
azriel91 added a commit to azriel91/amethyst that referenced this issue Nov 18, 2018
azriel91 added a commit to azriel91/amethyst that referenced this issue Nov 19, 2018
bors bot added a commit that referenced this issue Nov 22, 2018
Merge #1155
1155: Added nalgebra migration notes to book. r=magnonellie,Moxinilian,torkleyy a=azriel91

*Yes, we have docs!*

Issue #942

Should we link people to these:
* https://github.com/amethyst/amethyst/pull/1066/files
* http://nalgebra.org/rustdoc/nalgebra/index.html

Co-authored-by: Azriel Hoh <azriel91@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
You can’t perform that action at this time.