Better starting point/documentation

Discuss any questions about BEPUphysics or problems encountered.
Post Reply
JusTiCe8
Posts: 52
Joined: Mon Jun 01, 2015 9:02 am

Better starting point/documentation

Post by JusTiCe8 »

Hi Norbo,

I new to games development with C#/XNA and BEPU appears to be one of the best physics engine available but there is one point I think which could be seriously improved: documentation.

I means, the so called "tutorial" is everything but a tutorial and it doesn't work as-is ! (with VS 2010 express/XNA GS 4.0 and BEPU 1.3.0 main version) As I need to add "using Vector3 = BEPUutilities.Vector3;" statement to get something which works.

IMHO, it's quite a shame to achieve such an amazing engine and... stop right there without providing enough to integrate it to a real code (game or anything else).
What I feel as a beginner is a lack of proper documentation and I think the chosen path (play with demos and try to learn) is not very good BECAUSE BEPU demos use their own all-in-one system mostly (camera, display, ... even the proprietary custom type as Vector3 or Matrix, and everything is linked) which makes very hard to extract only relevant stuff outside to add to a more common/basic XNA (or DirectX) code. I see demos examples as a web of dependencies and nothing works well without some code which needs other code which needs...

A very welcomed code could be a simple 3D display of an object (like the excellent RB Whitaker's loading 3D models tutorial or one sample from Microsoft like collision_3d_heightmap), and add physics stuff on it step by step (world, a force like gravity, physical object like a mere bounding box and a ground to collide with, and so on, one feature after another maybe).
It's not up to the others to fit to BEPU, it's to BEPU to fit to the others, which make a lot more sense (as games are not usually added to a physic engine, instead physic engine is added to games).

Also, I haven't found yet an answer to why BEPU use it's own Vector3 and other type (is that because reference is not the same, kind of DirectX/XNA difference with z axis) ?

Don't misunderstand me, I'm aware it sounds quite negative but I'm really impressed by demo and I found performances are quite amazing despite the lack of proper complete game to be able to really compare to the competitors, Unity for example) and I'm willing offer to help as much as I could, if you wish.
Norbo
Site Admin
Posts: 4929
Joined: Tue Jul 04, 2006 4:45 am

Re: Better starting point/documentation

Post by Norbo »

I means, the so called "tutorial" is everything but a tutorial and it doesn't work as-is ! (with VS 2010 express/XNA GS 4.0 and BEPU 1.3.0 main version) As I need to add "using Vector3 = BEPUutilities.Vector3;" statement to get something which works.
Are you referring to the downloadable demos? Those work fine for me out of the box, so I'm not sure what you're encountering.

If you mean the instructions on the documentation page omitting some details, I didn't really intend them to be a guide to getting started from little to no experience with visual studio and C#. In hindsight, it was a mistake to include some of the tiny details like adding a reference to the project, since that set up the expectation that all similar level details would be covered. There are better resources out there about the basics. Physics engines aren't simple, and I've found that pretending that they are to be counterproductive.
IMHO, it's quite a shame to achieve such an amazing engine and... stop right there without providing enough to integrate it to a real code (game or anything else).
Quite a few games have used it successfully :)
What I feel as a beginner is a lack of proper documentation and I think the chosen path (play with demos and try to learn) is not very good BECAUSE BEPU demos use their own all-in-one system mostly (camera, display, ... even the proprietary custom type as Vector3 or Matrix, and everything is linked) which makes very hard to extract only relevant stuff outside to add to a more common/basic XNA (or DirectX) code. I see demos examples as a web of dependencies and nothing works well without some code which needs other code which needs...
I can understand why it feels that way, and there is definitely some complexity associated with how the non-physics stuff is handled. It could use some improvement (see later comments). The demos are primarily intended as a way to showcase different isolated parts of the physics API (e.g. the EntityConstructionDemo), and not as a reusable framework to base a game on.
Also, I haven't found yet an answer to why BEPU use it's own Vector3 and other type (is that because reference is not the same, kind of DirectX/XNA difference with z axis) ?
XNA is not supported on all of BEPUphysics's target platforms, and it was a huge pain maintaining separate branches for different math libraries.

Note that the new SIMD-accelerated types will be replacing most of the BEPUutilities math soon.
It's not up to the others to fit to BEPU, it's to BEPU to fit to the others, which make a lot more sense (as games are not usually added to a physic engine, instead physic engine is added to games).
...compare to the competitors...
1) I make essentially no money from BEPUphysics being public.
2) Competition doesn't matter from my perspective.
3) Having an open source project does not obligate me to meet anyone's needs.

All that said, better documentation is always nice. BEPUphysics is going to undergo a pretty massive rewrite over the next year or so, so a lot of the documentation is going to need to be rewritten to match. The BEPUphysicsDemos will be one of the first bits to be revamped- no more XNA dependency, among other things.

However... I don't think all the new stuff will be quite as easy as the current version of BEPUphysics. It's going to assume the user knows what they're doing in a lot of places for performance reasons, and a lot of redundant 'convenience' APIs are disappearing. It's unlikely that gamedev-beginner-friendly "tutorials" will exist for this level of API, simply because some experience is required to use it properly across the board. A more beginner-friendly layer could be built on top of the lowest layer, but I'm not sure I'll be the one building it unless it somehow speeds up our own development.
JusTiCe8
Posts: 52
Joined: Mon Jun 01, 2015 9:02 am

Re: Better starting point/documentation

Post by JusTiCe8 »

This is not because all other physics engine are complicated, undocumented, etc that you have to follow the same way you know.
I see a bunch of physics engines/libraries, most of the free ones are now dead/discontinued, like Jitter or Farseer for example, and just a few has been actually used in a released game. It's really unfortunate to waste a great potential.

Anyway, I decide to dive myself into and make a little sample from the XNA BEPU fork demo, using only wall demo and removing a lot's of features like the two camera control scheme classes, demo switching, character & vehicle, etc and put it into a fresh XNA game project class.
Feel free to add it to the main page or anywhere else.

My next work will be to remove entirely the use of ModelDrawer class and use "basic" rendering code instead.
Attachments
EasyBEPU.zip
A simple demo (wall demo) in a stand alone XNA game project
(518.83 KiB) Downloaded 260 times
Norbo
Site Admin
Posts: 4929
Joined: Tue Jul 04, 2006 4:45 am

Re: Better starting point/documentation

Post by Norbo »

This is not because all other physics engine are complicated, undocumented, etc that you have to follow the same way you know.
I see a bunch of physics engines/libraries, most of the free ones are now dead/discontinued, like Jitter or Farseer for example, and just a few has been actually used in a released game. It's really unfortunate to waste a great potential.
The reason why a lot of physics engines and open source projects don't have great documentation (especially for beginners) is not that we're all trying to be just as bad as everyone else. That would be exceptionally silly!

It turns out that writing documentation is very time consuming and not entertaining. I have a finite number of hours in my day, and even more documentation is just not nearly as important as everything else I have to do, and it's not nearly fun enough to do in my limited free time. Once the documentation reaches 'good enough' for a reasonably experienced audience (which appears to be the case for BEPUphysics, based on the number of games successfully using it), it becomes very hard to justify hundreds of additional hours spent refining and adding bits and pieces. For free. With no obligation to provide anything to anyone.

As for the rewrite, I don't intend to add complexity for complexity's sake. In fact, the new API should actually be significantly simpler, though possibly not to the eyes of a person totally new to the field. The current engine jumps through an enormous number of hoops in an attempt to make things look simple. It sometimes succeeds, but as soon as you start digging even a little bit, you run the risk of encountering massive sheer cliffs of complexity that only exist to support the mismatched 'simple' layer. In some ways, it's similar to the move from DX11/OpenGL and thick drivers to DX12/Vulkan/Mantle's minimal API and more user responsibility.

Further, the changes are happening in direct response to the needs of rather large games that just won't work otherwise. I wouldn't just suddenly decide to rewrite everything if there were not a darn good reason for it :)
Anyway, I decide to dive myself into and make a little sample from the XNA BEPU fork demo, using only wall demo and removing a lot's of features like the two camera control scheme classes, demo switching, character & vehicle, etc and put it into a fresh XNA game project class.
Feel free to add it to the main page or anywhere else.

My next work will be to remove entirely the use of ModelDrawer class and use "basic" rendering code instead.
I appreciate the effort, but this appears to be covering the same ground as the BasicSetupDemo and GettingStartedDemo. Those two demos already have a stripped down introduction of a series of basic concepts without involving the ModelDrawer.
JusTiCe8
Posts: 52
Joined: Mon Jun 01, 2015 9:02 am

Re: Better starting point/documentation

Post by JusTiCe8 »

Thanks for the reply.

Regarding the code, I just forgot those two examples, thanks to remind me, they're are basic enough to get some interesting and helpful inputs.
Anyway, stripping down the demo was quite a good start for me as I have to understand a thing or two. And as you say (despite I don't want to trust you first, I admit) playing with demo is a good way to learn the basics, as adding/modifying features of something which already work is a good way to learn.
(But I have to say "play with the demos" is quite very frustrating answer for a beginner just wanting some help, and also is a good "test of will" as people who giving up just there would give up sooner than later, game development being maybe one of the biggest coding challenge and it's full of disappointments and frustrations).

About writing documentation, have you already think of how much time you spend on the forum answering many times the same questions over and over ? You may think it's just 10m here, 5m there, but at the end of a week, a month, a year, it could be huge !

What about using all the knowledge on these forums to write a cookbook ?
It's not a full doc, but it could be very useful and easy to fill, as each time you answer a question regarding one thing, you could add the recipe to the cookbook, so later, people looking for a similar answer will (with hope :) ) take a look at it first, then ask if... (they don't understand, it doesn't work for them, whatever).

(I've already started to gather recipes if you're interested).

Because as good as it can be, a forum is the worth place to share knowledge, as most of the people just ask for an immediate help to their very own issue without doing any research first, not very helped by the default PhpBB search engine which sucks (I've seen people using google search engine to search on such forum !).
The other common issue is people just do "help me please I need help right now !!!", answer given, ... then no follow-up. They usually never get back and write something like "I did this and that and it helps me solve my issue", instead, we just get "thanks, problem solved" (at best) :x .

Finally, a simple XNA 3D tutorial with BEPU added to it is included. It can be use as a starting point. I've added some exercises for beginners.
Attachments
Using3DModels.zip
RB Whitaker's Using 3D Models tutorial with BEPU added to it.
(27.55 KiB) Downloaded 261 times
Norbo
Site Admin
Posts: 4929
Joined: Tue Jul 04, 2006 4:45 am

Re: Better starting point/documentation

Post by Norbo »

About writing documentation, have you already think of how much time you spend on the forum answering many times the same questions over and over ? You may think it's just 10m here, 5m there, but at the end of a week, a month, a year, it could be huge !
When a well-defined question gets repeated a few times, I typically do write a piece of documentation about it. Shape recentering was the most notable example of that. Other than that, there aren't all that many pure repeats. (And I track all my time, so I'm very aware of how much time the forum consumes :))
What about using all the knowledge on these forums to write a cookbook ?
It's not a full doc, but it could be very useful and easy to fill, as each time you answer a question regarding one thing, you could add the recipe to the cookbook, so later, people looking for a similar answer will (with hope :) ) take a look at it first, then ask if... (they don't understand, it doesn't work for them, whatever).
The forum basically is the cookbook. Yes, the default phpBB search is crappy, but google works well. I suspect trying to compress the questions down would miss out on keyword context that the forum has, so a dedicated cookbook could actually end up harder to search if it included more than a few entries.

If you'd like to gather and post such recipes on the forum (even in this thread, since the context would probably make it a bit easier to find), feel free.
mcmonkey
Posts: 92
Joined: Fri Apr 17, 2015 11:42 pm

Re: Better starting point/documentation

Post by mcmonkey »

I personally found BEPU fantastic to work with and learn, though I had prior experience in other physics engines. Anything you're not certain about, just come to this forum and enjoy some of the best support/help/whatever-you-call-it available. I've seen very few places where the developers give support of this high quality. And it seems to be Norbo on his own doing it, making it a thousand times more impressive.

And if that's not enough for you, I've learned a lot about BEPU and my only remaining questions are of general physics trickery (EG building a rope object that acts realistically is my current target) rather than any confusion with using the engine itself. If I ever spot a question on this forum or StackOverflow or wherever before Norbo gets to it, I intend to offer my own support (assuming I have a quality answer I can give, of course).

@Norbo: If you ever want someone to write up docs for something in the engine and don't want to do the first version [usually the hardest] yourself, just ping me and I'll do it :)
Norbo
Site Admin
Posts: 4929
Joined: Tue Jul 04, 2006 4:45 am

Re: Better starting point/documentation

Post by Norbo »

If you ever want someone to write up docs for something in the engine and don't want to do the first version [usually the hardest] yourself, just ping me and I'll do it
Thanks for the offer :)
Post Reply