Quality of life/convenience umbrella

[RossNordby]

v2's API is very low level. It'll let you shoot yourself in the foot, and for the sake of directness or control, it sometimes requires a bit more effort to set things up.

It would be nice to do a couple of things:

1. Where possible, improve the API to be easier to use without any tradeoffs.
2. Where tradeoffs are required, provide an optional convenience layer- or an example of one, given that the ideal form will depend on the use case- that makes things work a little more automagically.

This is an umbrella issue for reporting areas of the API that you find particularly difficult to use (even if you can't pinpoint exactly how to improve them), for API shapes you might like to see in a convenience layer, what kinds of tradeoffs you're willing to accept in convenience layers (GC, performance overhead, etc.), and anything else you think is relevant.

[RossNordby]

To get started:

• Extracting body data for one-off use is a little annoying. The BodyReference gets you 90% of the way there by hiding the indirections, but it's still a level below the v1-style properties since it returns direct references. It can't, say, wake up a body automatically for you when you modify the pose. Those checks do require overhead, but that's something that could exist in a convenience layer or example.
• Accessing constraint data is a little tricky. You can grab/apply constraint descriptions, but there's no way to have property-level access. That's a byproduct of all constraint data being stored in an optimized AOSOA format; the mapping between AOS and AOSOA is manual and mediated by the IConstraintDescription which doesn't play well with per-property access. The ideal form here is unclear, but it seems like beginners would likely benefit from an object with simple properties for things like constraint data and accumulated impulses. Unfortunately all the obvious implementations are a bit work intensive and carry overhead- this is an area where code generation might be wise.
• Defining constraints could be made a bit more rigorous in general. Many currently don't even have a constructor and just expect the user to just fill out all the necessary fields. That's fine for someone who knows exactly what they need, but it's miles away from idiomatic for a beginner. This is a little tricky to fully solve without tradeoffs due to value types always having an empty constructor, and beginners may not fully understand what that means in the context of value types.
• The engine avoids doing a lot of runtime error checking in release mode. Small errors can become scary looking access violations or other forms of explosion. Running in debug mode will tend to catch these issues early, but having more rapid feedback even in release would be helpful in a convenience layer.
• There are probably still areas that could use more asserts. I've been adding them as I've run into them (most recently with constraint description validation), but make sure to report any more obvious cases.

[lidgren]

Here are some (mostly minor) pain points of mine:

• Moving a body from static <-> dynamic and vice versa

• Setting position and/or orientation and/or velocity for a single body

• Compute mass (and inertia) for a shape by specifying density

• Understanding what the different constraints do exactly

• Local issue: I'm using a simple job system that doesn't make the guarantee of progress on all jobs simultaneously - if going fully wide, let's say on 7/7 worker threads; there can be deadlocks when only 6 of the jobs are run on workers and the seventh job is waiting behind some other job that's waiting for physics to finish.

[RossNordby]

Setting position and/or orientation and/or velocity for a single body

Are you referring to the annoyance of setting up a BodyReference from a handle, or the lack of helpers (like automatically waking a sleeping body when changing the pose), or something else? (Or do you just mean that accessing properties through the Bodies sets directly comes with a lot of tedium?)

[RossNordby]

Another one that's a little more work intensive and would imply a rather thick form of convenience layer:
The engine currently can't be used directly from VB due to the rampant use of pointers and other CLS noncompliant features.

[lidgren]

Setting position and/or orientation and/or velocity for a single body

Are you referring to the annoyance of setting up a BodyReference from a handle, or the lack of helpers (like automatically waking a sleeping body when changing the pose), or something else? (Or do you just mean that accessing properties through the Bodies sets directly comes with a lot of tedium?)

Getting the description from the correct set, modifying it, applying and optionally waking the body. Not a huge amount of work, but enough to appreciate a helper method SetPose(CollidableReference, Pose)

[RossNordby]

Latest version now includes:

• Settable BodyReference.Awake property
• BodyReference.BecomeKinematic/SetLocalInertia that fully handle the transition as needed
• BodyReference.Kinematic/HasLockedInertia getters
• Bodies.GetBodyReference to help with discoverability
• BodyReference.Get/ApplyDescription
• BodyReference.SetShape that handle the shapeful-shapeless transition as needed

This brings the BodyReference up to feature parity with the public Bodies API.

The by-ref properties and such still don't force a wakeup (both to avoid issues when waking is undesired and to avoid overhead), but the Awake property being settable makes things easier.

How's that look for a start?

[lidgren]

Hi! I'm writing some serialization code for convex hulls and it turns out there's quite a bit of typing and potentially a bit of copying that could be avoided. Would it be possible to add some helper methods to Buffer and/or QuickList to interact with "normal" spans of integers and Vector3s?

[RossNordby]

Probably! Any particular areas of annoyance?

Most such changes would require adding System.Memory as a dependency since .NET Standard 2.0 doesn't include it (and older Framework runtimes will resort to a 'slow span'), but that's not a huge problem.

[RossNordby]

2f4880c adds span conversions to buffer and collections, and ec9d4ff makes ConvexHullHelper operate on Span for input pointsets. Any other areas?

Edit: and a bit more: f29c5de

[lidgren]

Quick feedback as always; thanks!

[Paulius0706]

Buffer construction is very convoluted.
Now to create buffer we need from BufferPool.Take(int len,out buff), even when we have constructor that we should never use because of of scary memory param.
Insted of that we could do new Buffer(int length, BufferPool bufferPool) that literaly do like all other objects.

[RossNordby]

aight: b91313c

we have constructor that we should never use because of of scary memory param.

Be not afraid! Buffer<T> is meant to represent any blob of unmanaged memory, not just that which comes from a BufferPool. (That's part of the reason why this constructor wasn't there before, but doesn't hurt to add it for consistency with the Quick* collections which have the exact same property.)

[damian-666]

have you looked at FlatPack? https://github.com/jamescourtney/FlatSharp might help with this serialization stuff..