Docs still say GC default value is 5 milliseconds


Force the Lua garbage collector to run for at least ms milliseconds every frame, so that garbage doesn’t pile up and cause the game to run out of memory and stall in emergency garbage collection. The default value is 5 milliseconds.

If your game isn’t generating a lot of garbage, it might be advantageous to set a smaller minimum GC time, granting more CPU bandwidth to your game.

1 Like

Hey Matt! We've been investigating some unexpected GC behavior on our game and are trying to understand what the default is here. I'm not finding anything in the PlaydateSDK directory that jumps out to me.

Is the actual default here 0? If so, do you happen to know where that's set in the actual SDK
code? Or is it even lower-level than that?


Good question. I cannot recall.

It must have been changed in the SDK, maybe mentioned in the changelog, around the time of this OP. That would be maybe SDK 1.1.0?

Have tagged Dave.

1 Like

Dang, we never did fix the docs there. :frowning: It's been 1 ms since early last year, changed in 1.1.0 right as you'd guessed. Also, there was a bug fixed in 1.8.0 where it wasn't calculating the scaled GC time correctly.

@shipstar If you haven't seen playdate.setGCScaling(), it's a tool for adjusting how GC scales up with memory pressure, might help here:

playdate.setGCScaling(min, max)

When the amount of used memory is less than min (scaled from 0-1, as a percentage of total system memory), the system will only run the collector for the minimum GC time, as set by playdate.setGCScaling() playdate.setMinimumGCTime(), every frame. If the used memory is more than max , the system will spend all free time running the collector. Between the two, the time used by the garbage collector is scaled proportionally.

For example, if the scaling is set to a min of 0.4 and max of 0.7, and memory is half full, the collector will run for the minimum GC time plus 1/3 of whatever time is left before the next frame (because (0.5 - 0.4) / (0.7 - 0.4) = 1/3).

The default behavior is a scaling of (0.0, 1.0) . If set to (0.0, 0.0) , the system will use all available extra time each frame running GC.

1 Like

Thanks for the clarification!

We were able to solve our specific issue just by tuning the minimum GC time, but we were confused that setting it to 5ms was having such a drastic impact on performance. The default being 1ms makes more sense. :slight_smile:

I'll keep setGCScaling in mind as we get deeper into performance tuning.

Thanks again!


Just want to bump this to note the current docs still say 5ms.


Thanks for the reminder! I filed an issue on that then promptly forgot about it. I'll fix that now. :slight_smile: