Can we get a better documentation for LowLevel.PlayerLoop?

Hi,

Could we get a complete documentation of the default systems used within the default PlayerLoop?

Right now we just have “A native engine system that the native player loop updates”.

Thanks.

2 Likes

It’s been a while since I dealt directly with it but I do recall the documentation being a bit sparse and spread out. There should be a couple additional pages which even include an (equally unclear) example.

If you have any specific questions, I can probably answer them. But as a quick tip there are two things to know. The first is thay the structure you get from the player loop query is a copy. You can modify its contents any way you like but it won’t take effect until you set it as the new player loop. The other is that you absolutely want some mechanism that reacts to entering and leaving playmode in the editor! Be sure to cache a copy of the original player loop and then set that once you leave edit mode. The structure persists throughout the lifetime of the editor so if you don’t do this you’ll just be stacking changes to the loop every time you run the code that modifies it.

3 Likes

I’ve written a blog post demonstrating how to use the PlayerLoop to add an early and a super-late update, showcasing how Unity’s game loop can be modified by adding or removing certain systems.

You can read it here: https://giannisakritidis.com/blog/Early-And-Super-Late-Update-In-Unity/ and also check the github repo with the code here: https://github.com/meredoth/Early-And-Super-Late-Update-In-Unity.

However, in general, there’s limited flexibility because the PlayerLoop operates in the native layer; you can only add or remove specific systems without altering the behavior of individual systems.

While you might consider executing code before each system by obtaining an unmanaged pointer, this requires unsafe code. I don’t recommend it, as its reliability in the final builds is uncertain.

Hope this helps.

2 Likes

Hi people, first of all thank you for your answers.

@Sluggy1: I already knew about the fact that the structure you get from the player loop query is a copy and that you need a mechanism to restore the original one when leaving playmode. Your pieces of advice are good and I recommend them.

@meredoth: I also already know how to setup a new PlayerLoop, and yes I am familiar with your tutorial, but thank you either way.

I’m actually making a tutorial myself right now, it’s a deep dive in the functioning of Unity’s game loop and comparisons with other game engines. I think I have to cover the PlayerLoop related API but every time I try to get info about a native system, it’s not really generous in information as you may be aware.

I can understand most of them by deduction so I guess I’m going to pick some of them and ask as proposed @Sluggy1, and for the others find a decent explanation:

  • TimeUpdate.

    • TimeUpdate.WaitForLastPresentationAndUpdateTime: I suppose this is where time related data is updated like deltaTime, lastTime, elapsedTime etc…
  • Initialization.

    • Initialization.UpdateCameraMotionVectors: Clear name but I personally handle my camera’s motion (velocity/acc) via script so no idea what this is.
    • Initialization.DirectorSampleTime: I think the word Director is used by all systems related to animations but I’m not sure.
  • EarlyUpdate.

    • EarlyUpdate.PollPlayerConnection: I’m not sure what kind of connections we are talking about here, this is a default system from a blank project so there is no netcode package.

The other systems of the default player loop are quite self explanatory from their name and their behavior can be deduced somewhat easily.

Thank you,
Valentin.

2 Likes

When I was making that blog post, I noticed that Unity’s game loop systems change between versions; some systems are added or removed with each update. I haven’t yet reviewed the differences in Unity 6.

It seems unlikely there’s anyone at Unity with complete knowledge of all these systems. My guess is that systems are added or removed in the game loop as needed by individual teams working on specific functionality for each version.

Unity’s documentation largely covers higher-level concepts or automatically generated scripting API details, so it’s doubtful that anyone at Unity will undertake the task of gathering specific information on each system from each team to offer more detailed explanations.

Some of the names are also unintuitive, for example TimeUpdate.WaitForLastPresentationAndUpdateTime is responsible for waiting for the rendering, sometimes can be seen as a bottleneck from the GPU in the profiler.

I’d definitely be interested in anything you find. Please share it here, or link to your blog post with your findings when it’s ready!

1 Like

Thank you so much for your precious advice @meredoth, this actually helps a lot.
I will update this thread with my new findings.

This is just a wild guess, but I think update camera motion vectors may have something to do with certain post processing effects like motion blur. When you are spinning the camera quickly, I think there is some extra meta data for motion vectors that help with blurring the results of consecutive frames together when the camera is moving quickly. But, that’s just a thought. I could be wrong.

2 Likes

Thank you for your comment @CodeRonnie. I feel like guess work might be our best shot at the moment, interesting nevertheless!

Yeah, it sounds like you’ve investigated about as much as I had so you probably know about as much as me it seems. It was over two years ago that I worked with any of that stuff and I only use it indirectly through a helper library I made to simplify it so my knowledge is pretty faded anyway. I don’t even recognize some of those names so likey meredoth is correct that they’ve changed it over time. Even if I did recognize the names they don’t sound like anything I’d use 99.999% of the time anyway. All I ever really needed was to be able to inject my own pre-update, post-update, and post-late update :melting_face:

1 Like

Yeah definitely, when you use the PlayerLoop in practice once you have setup the callbacks you needed you basically just move on.

Opening this thread was just me trying a final research trick to see if other people had more knowledge but I think in my tutorial I will simply present the facts the way they are, we know what the loop looks like but we can’t be sure about what the callbacks really do.

Thanks for the help anyway, it was a pleasure to exchange about this topic :slightly_smiling_face:.

FWIW you can see every stage of the player loop in the C# source code ref: UnityCsReference/Runtime/Export/PlayerLoop/PlayerLoop.bindings.cs at master · Unity-Technologies/UnityCsReference · GitHub

Everything there is in the order that they take place.

2 Likes

Hey @spiney199. Thanks a lot for that, I didn’t know there was some source code shared like this. It doesn’t tell us more but it is interesting to see the C# wrapper that they built around the native code :slightly_smiling_face:!

But then we’ll lose the feeling of power we get when we drop it at work and blow people’s minds.

1 Like