The limbo bug explained

A couple of days ago, I said I would look into the method speedrunners use to trigger the limbo bug. Now, I'm back with the results. Surprisingly, it all has to do with the camera.

First, I'll post the video again for your convenience. Here's Flying Battery Zone 1 in 0:55 by Zurggriff, on June 16, 2017:

Okay, at the very start of the level, there's a long vertical shaft. When Sonic enters this shaft,

he's forced into a spin by one of the two objects at either end, pictured to the right.

This object forces Sonic into a spin by doing two things. One, it sets Sonic's spin dash flag at byte $3D of his SST. Two, in case he wasn't already spinning, it changes his animation to the spinning animation, and plays the spin sound effect for good measure.

The spin dash flag induces two distinct behaviors, depending on Sonic's current animation. If Sonic is in his spinning animation, then it will give Sonic a small boost of speed when he's moving too slowly. If that sounds familiar, it's because this behavior was used extensively in Sonic 2's Casino Night Zone.

However, if Sonic isn't in his spinning animation, the flag indicates he is currently charging a spin dash, which is released as soon as the player stops holding the down button.

The intended behavior is that when Sonic passes through the bottom object, his spin dash flag is set, forcing him into a spin, and then when he passes through the top one, the flag is cleared again. At the start of the level, though, the top object is far enough from the camera that the object manager elects not to spawn it.

When looking up or down, the camera's max vertical speed is temporarily reduced so that it will gently slide over to its target position. By stepping on the booster pad during this period, Sonic is able to zoom past the object at the top of the shaft before the camera can scroll up enough for it to spawn. This causes Sonic's spin dash flag to remain set.

Another special behavior of the camera is that the game is constantly recording the last few player positions to a buffer. When a spin dash is released, the camera temporarily uses values from this buffer rather than the player's live position, so that the player will briefly outrun the camera.

All of these aspects collide once Sonic reaches the vertical cylinder object. The object sets Sonic's object_control and status bitfields, and bumps him out of his spinning animation. Sonic's spin dash flag is still set, but since he isn't in his spinning animation any more, a spin dash release is triggered, assuming of course the player isn't holding down.

The cylinder object sets player 1's ride flag in own its status bitfield but at the same time, the spin dash release causes the camera to start reading from the player position buffer. The camera quickly snaps to where it was a short while ago, which was quite a ways to the left. So far left, in fact, that the cylinder object scrolls far enough off screen to be deleted.

Of course, when the camera scrolls back to the right, the object is loaded from the object layout again. But the damage is done. The object respawns with a clean status bitfield, and once again has no idea that player 1 was riding it.

Do the limbo, baby.