Confused about api access

Why are there things like Broadphase.ScheduleBuildJobs() that are public and even talked about in the release notes, but impossible to use because things they rely on are internal?

Fyi to use custom worlds the two things currently that have to be modified are StaticLayerChangeInfo and CollisionWorld.Broadphase.

 

Thats a fair point. Custom worlds are not yet exercised in our demos so we just missed the fact that Broadphase.ScheduleBuildJobs() is public right now but StaticLayerChangeInfo is not.

The plan is absolutely to make more of the API public, but we are currently erring on the side of being conservative by keeping some things internal until we are confident that those APIs won't change afterwards. Broadphase.ScheduleBuildJobs() is also good example of one that likely will change when we do start using it more, since StaticLayerChangeInfo is not a friendly API.

I expect more APIs to become public soon as part of some work to allow creating and stepping worlds within a single job.

 

I think the amount that is restricted is a bit much, I just keep hitting so much of it.

As it is now it's just causing unnecessary pain IMO. A lot is really just unexpected, and by the time you hit it, the correct solution is modify the source. The alternatives will often be far worse. Like either walk away from Unity.Physics or duplicate internal logic.

I think a good measure is if your own tooling needs internal access, it shouldn't be internal.

 

Please, also consider to give access to LowLevel.CollisionEvents and LowLevel.TriggerEvents somehow. They are handy for custom worlds too. For example for collecting events without using Job System, while simulating several step ahead.

 

Hey, as part of the new release we will be adding interfaces to do the Broadphase work through CollisionWorld, so you won't need access to Broadphase at all.

Also, we will be adding support for iterating through events without jobs, but using the foreach loop instead.

 

So looking at the abstraction we have for building isolated static worlds, the current api needs StaticLayerChangeInfo which is internal as you noted above, and that needs the static body count so I'm accessing PhysicsWorld.StaticBodies to get that. I'm also calling PhysicsWorld.Reset but it's been a while and not sure if I actually tested that as being necessary.

I'm assuming that's all now encapsulated through CollisionWorld?

 

So FYI on our flow we are writing directly to PhysicsWorld.StaticBodies. We have our own bodies array that we update first. When it changes we then call PhysicsWorld.Reset to it's length. Then run IJobParallelFor to copy our bodies to PhysicsWorld.StaticBodies which chains into BroadPhase.ScheduleBuildJobs.

 

StaticLayerChangeInfo is going away, so this interface will be much simpler, you won't have to worry about any of that with the coming release. Of course, the ability to skip rebuilding the static tree will still be there, only through a much simpler interface. We are aware that StaticLayerChangeInfo was a bit unintuitive, thus the whole rework.

 

I know I'm lttp on this, but I wanted to make sure we had explicitly addressed this to shed some light on our thinking (feedback of course welcome).

If we have made something part of public API it means that we are committed to maintaining it as best as possible. In addition to fixing bugs and ensuring all behavior is specified, it means that we will add obsolete API updaters when possible if something changes or is removed, and so on. Basically it means (while we're in experimental) that we're pretty confident it will not change, or that we can bear the cost of mitigating user pain if it needs to change.

On the other hand, if something is internal or private, it just means we have not yet had sufficient development resources to vet the design in order to confidently estimate and commit to these maintenance costs. It gives us more flexibility to prioritize other things, break things, make significant/disruptive changes, or only validate behavior with a limited range of use cases because we haven't made explicit contracts with users. (The situation with StaticLayerChangeInfo is one such example.)

The long-term vision is to make as many internal structures public as is reasonable (i.e. adds value for users), but it hasn't been the most urgent priority yet. So for now we continue to recommend that advanced users make and maintain local modifications, and provide feedback about how they're using these internals to solve problems.

 

Thank you for fixes these issues in latest update)
Please, also consider making some internal tools like DisplayBodyColliders.DrawComponent public. This class is perfectly usable outside of ECS and is very handy.

 

Thanks for the feedback! The debug drawing systems in particular are going to be undergoing some changes in the coming releases, so I wouldn't expect any changes to access there until after that work has happened.

 

Please also consider exposing low-level collider functions, for example; if a user wants to make an arbitrary OBB collider and test the distance to points. Collider use outside of the full system could be useful for many things and currently we'll either have to keep our own modified copy of the package or build a secondary system just for these cases and neither are good options.

 

That reminds me. Maybe consider abstracting out iterating over different collider types. It's useful on it's own. We lifted a lot of that code to create geometry collection abstractions that we use in our own navigation mesh system. Probably other uses as well.