Add wait_idle_frames()

[marcinn]

Versions

What versions of Godot do you want to use this feature in?
4.3+

The Feature

wait_idle_frames()

Currently wait_frame() is implemented top of a physics process, which is less or more related to IDLE frames handled in _process(). Physics frame ticks are also dependent on project settings (physics/common/physics_ticks_per_second, physics/common/max_physics_steps_per_frame and probably physics/common/physics_jitter_fix).

As a result, to wait for IDLE frame you don't know how much physics frames you must wait, so you're sticking with a wait_seconds(), slowing down your tests and praying that one IDLE frame will take less than one second.

The proposal is about adding awaiter for exact idle frames. When I want wait for a two IDLE frames, I should call:
await wait_idle_frames(2).

Possible implementation

 func wait_idle_frames(frames):                                                                                                                                        
     while frames > 0:                                                                                                                                                 
         await Engine.get_main_loop().process_frame                                                                                                                    
         frames -= 1

Thank you.

---

TBH: if not really needed, it would be better to implement awaiters on _process than _physics_process.

[bitwes]

There was another issue, that I can't remember now, that made it seem like _process would be better to use. I think maybe wait_frames should be used with _process and wait_physics_frames should be added. Your proposed wait_idle_frames seems pretty useful as well.

I usually just used await wait_frames(10). Waiting 1 frame almost never works and I think 5 is flakey.

[marcinn]

I think maybe wait_frames should be used with _process and wait_physics_frames should be added.

+1 I don't know all the details, but that's what it looks like. _process is more predictable. We also intuitively assume that "wait_frames" refers to idle frames instead of physics.

This change would be great in my opinion. It shouldn't break compatibility since people currently have to use higher numbers of frames.

[bitwes]

I've been thinking about this and for the sake of backwards compatibility I think the following should be done:

• Add wait_ticks which will count ticks in _process.
• Add wait_physics_tics which will count ticks in _physics_process
• Add wait_idle_ticks which will would use your possible implementation.
• Deprecate wait_frames.

[marcinn]

Deprecation of the wait_frames is a smart idea! You can preserve full compatibility and slowly depreciate this func.

You can consider staying with "frames" instead of "ticks", because "frames" are more intuitive and people know GUT's naming convention already.

So I suggest:

• depreciate wait_frames
• introduce wait_idle_frames and wait_physics_frames
• let wait_frames be an alias to wait_physics_frames

Idle and Physics keywords are very verbose/explicite. They are also used in Godot's nomenclature to explain differences between these two processes: https://docs.godotengine.org/en/4.3/tutorials/scripting/idle_and_physics_processing.html

What do you think?