Every frame, the physics engine updates all active physics bodies, advancing their position based on their velocity and handling collisions between physics bodies. This is done in processing order - a physics body with a lower processing order is processed before a physics body with a higher processing order.

Dynamic grounds have the lowest processing order, and grounds with smaller IDs (or z-indexes) are processed before grounds with larger IDs (or z-indexes).

Spawned shaman objects have the highest processing order, and shaman objects that were spawned earlier are processed before shaman objects that were spawned later.

Editor-spawned shaman objects and mice lie between these two.

When the update happens, the physics bodies are processed in order. However, when a physics body with a higher processing order collides or is in contact with a physics body with a lower processing order, the physics body with the lower processing order is reprocessed.

Furthermore, when a given physics body is updated, all physics bodies connected to it, whether through direct contact (like a collision) or indirectly (like a joint or balloon anchor), are also updated.

These update quirks are essential to allow teleporting grounds to work.

When two or more physics bodies are jointed to an updated physics bodies, it appears that the joint later in the XML is updated first, followed by the joint earlier in the XML. This means that the joints are updated in reverse XML order.

This update quirk will be necessary to ensure Type-2 stability.

Ground teleportation works by having Ground B Revolute Jointed to both Ground A and Ground C. Using ground update quirks, Ground B remains in its original position, and when Ground A is touched, Ground B teleports a fixed offset as determined by the amount Ground C has moved from its original position.

For example, Ground C was originally placed at (500,340) but, due to a Prismatic Joint, has moved to (600,340), a translation of 100px to the right. When Ground A is touched, Ground B teleports 100px to the right.

This is the most basic implementation of buttons that teleport grounds. Ground C is moved into place by a prismatic motor. When Ground A is touched, Ground B teleports rightwards.

This version of button is not Type-2 or Type-3 stable, but will be useful for explaining the update mechanism.

At rest, the last updated physics body is Ground C as it has the biggest z-index (3). As Ground C is jointed to Ground B via a Revolute Joint, Ground B is also updated. Ground B is Revolute Jointed to Ground A, so that is updated too. As the A-B JR is processed last, the physics engine uses this joint to determine the position of Ground B, so the rest state of the system is A B   C.

When Ground A is touched by a mouse or shaman object, as they both have higher processing orders and are updated after dynamic grounds, it triggers another update on Ground A, which updates Ground B, which updates Ground C (as described above). The B-C JR is processed last, so this joint is used to determine the position of Ground B. The state of the system when Ground A is touched is A   B C.

However, when Ground B is touched, both Ground A and Ground C are updated. As described in Section 2.3, the A-B JR is processed after the B-C JR, so the former is used to determine the position of Ground B. Now, we have a problem, as the state of the system when Ground B is touched is A B   C. Assuming that Ground A is also touched, Ground B will use the A-B joint, and as Ground B is no longer touched after being teleported back, the state uses the B-C joint and Ground B is teleported next to Ground C. This flip-flopping of state causes Ground B to blink when a mouse or shaman object is touching Ground A and another mouse or shaman object is touching Ground B, and the physics body touching Ground B is updated after the physics body touching Ground A. Therefore, this setup is Type-2 unstable.

This XML shows the importance of ground ordering. This XML is identical to that shown in Section 3.2, except that Ground A has been moved to the back. This causes it to be updated last, which then updates Ground B, which updates Ground C. The B-C JR is chosen to determine the location of Ground B, and Ground B ends up following Ground C from the start.

This XML shows the importance of joint ordering. This XML is identical to that shown in Section 3.2, except that the A-B JR is now behind the B-C JR. As described in Section 2.3, the B-C JR is processed after the A-B JR when Ground B is touched, so the former is used to determine the position of Ground B. Thus, the state when Ground B is touched is A   B C. Therefore, using a similar line of logic as is in Section 3.2, the mechanism is now Type-2 unstable if Ground A is not touched, but this is not a problem as the initial state should start with Ground B hidden anyway. When Ground A is touched, the mechanism is now Type-2 stable.

This XML demonstrates a method of instantly moving a ground to a desired position stably at round start. The JP has been modified to have a positive lower limit along the axis, and a negative motor direction. Due to the minimum displacement of Ground C being enforced by the lower limit, Ground B can afford to have a larger mass for a more stable mechanism.

As Ground C does not vibrate when using this method of displacement, the entire teleporting mechanism is also Type-3 stable.

There are some things to take note of when utilising this mechanism in a map. Firstly, due to the state of the mechanism when Ground B is touched being A   B C, touching Ground A, then Ground B, then releasing Ground A will cause the state to remain as A   B C, as if the button is still being touched. To remedy this, it is encouraged that continuous contact with Ground B is hard or impossible, for instance by making it a ground with restitution or making it a conveyor. Secondly, if the entire mechanism becomes idle (when the objects turn red in debug mode), when suddenly updated again, Ground B may blink once or twice. This is a minor issue, though.

I highly encourage reading the entire content of this tutorial in order to gain a better understanding of how the update mechanism works in Transformice and be better equipped to build Type-3 stable mechanisms.

However, the tl;dr is as follows:

Use this XML to build a Type-3 stable button, and be sure to maintain the relative z-indexes of the three coloured grounds and their joints.

If a mechanism fails to be at least Type-2 stable, try playing around with the order of the grounds and joints to see if that will bring stability.