Improving Bullet Experience (Generally)

[cuppajoeman]

Introduction

When I first started figuring out Bullet I was confused on how to even use the library, initially I thought this might have been the repository for pybullet, but I wasn't sure.

Eventually I figured it out it's the home of both pybullet and the c++ source code for bullet. Next I wanted to get started with bullet, I was looking for a minimally working example, and I found one, but I had hours of trouble figuring out how to use the library as a external library with cmake.

Eventually I figured out what commands to use to build this as an external library, and things were relatively ok since then.

Now I want to make a kinematic character controller and I found btKinematicCharacterController, but then only found out through a closed issue that was linked on a reddit post that it's no longer supported. I could have easily spun my wheels for hours on this one trying to get that controller to work.

I'm not sure how others have been using bullet, but to me it has been stumbling all the way. Once it's working it works great, but getting to that point I've found a bit challenging. I want this to change.

Organization

Lack of centralized resources and organization. When I use bullet, the following situation happens over and over.

I look up how to do something with bullet, I find a link on the fourm, reddit or somone's blog, it has a semi-working example that needs to be tweaked, potentially links to a broken link to the wiki or just someone's explanation without real working code.

Because of this I find it really easy to get overwhelmed on how to do something since there's a bunch of different sources each one of which say something different and then you just feel even more lost.

Activity

I also find that the issues page on github makes my heart sink when I look at it. Sometimes I feel like posting an issue to the bullet repo and then I see that there are 150 issues and most of them have no response or just like one comment and I'm just like what's the point.

Additionally on top of that I tried making a pull request and I got no response, not even a comment or anything saying if this is in the right direction or anything like that. Making a pull request and getting no response is just sad, because it's like trying to improve something and then nothing happens and then the work you just did was for nothing. Seeing a bunch of pull requests just sitting there definitely makes it hard for potential developers to collaborate.

Just to build on this point if we look at the insights for this repository we can see the activity spiking in 2020, and then just sinking back down:

Also I'm pretty sure that @erwincoumans is the only one who has the ability to merge pull requests, and it seems as if his activity with the bullet repository has been decreasing since 2020 this year only reaching 7 contributions in bullet repo, which I believe were merge's:

Proposed Solution

Consolidated Documentation

I am proposing that we consolidate all of our knowledge into one resource. I believe that a good solution to this is using Doxygen documentation because it allows us to reference actual code.

I see the future of the doxygen documentation as a place where users can find working runnable code examples along with methods of doing certain things or setting up certain simulations. I also see this knowledge base as a place where developers can see what users are doing and potentially implement them into the engine itself as a source of inspiration.

PS: Even though this is just a proposal I've started working on this doxygen documentation here, eventually if @erwincoumans or anyone else thinks this is a good direction, I'll make a pull request that will move everything from that repo to the main bullet repo

Maintainers

I'm not sure what @erwincoumans current status is, but I think in order to revive things, we'd need active maintainers who can help improve the code through merging pull requests.

In this regard, I believe we'd need users who are familiar with how the bullet engine works to help with the pull requests that are technical in nature, along with maintainers who could merge pull requests that are not directly related to bullet, but help with any infrastructure such as building the project, and documentation, so that changes get merged in and contributors efforts feel real.

Clearly adding a bunch of maintainers at once could be a recipe for disaster, so maybe starting with one or two and then assessing how things are going would be good first step.

Communication

Right now I see that github discussions are being used for communication as well as the fourm personally I have never been able to find a sign up button on the fourms, so I've never been able to ask a question there.

I'm not sure what the best solution to the communication would be, but I think it would be good to decided on one place for any discussion and direct any new users to go there. Many young programmers these days use discord, but I think it's easy to lose information on discord, so I'm not sure what people would prefer.

Maybe having a poll would be the best way to find out...

Conclusion

I am not trying to call out Erwin or anyone here, I'm truly only mentioning these things because I want the bullet physics engine experience to improve, I think it's a great physics engine, wish it the best and want to make it as nice as possible.

But I believe if we don't start fixing these issues, this repository is going to stagnate and it's going to be hard to pull in new users.

So far I've made 2 issues relating to what I've talked about today #4547 and #4546 so feel free to go check those out.