You might have already seen a "Torus" map before... Did you ever play Pacman? Do you remember how there was a "tunnel" on the edges where you could go from the left side of the map to the right side? and also the other way around? Well that was similar to a "toroidal surface".

In any case here is the definition from wikipedia about Torus:

But that just sounds too complicated, hopefully when you finish reading this you will understand better what that means!

Here is another example of a "toroidal surface" in this case all the edges are connected, unlike pacman where there were walls.
This means that the map has no ending, its fully connected and all tiles are surrounded fully. When you visually go over the "edge" you appear on the other side, this is the "essence" of a Torus surface.

See the example below (credits to: https://github.com/lemunozm/torophy?tab=readme-ov-file)

To be honest I find it very interesting to study the "Torus" because it's a very creative and interesting surface. You might think that it's impossible to find this surface in the real world but you might just be missing the big picture.

Consider a "Torus surface" but only horizontally, imagine the north and south are NOT connected. Can you think what this represent in the real world? It's a Cylinder. 

But if we wanted to represent a fully connected Torus that's different... it looks more like a doughnut.

Which makes sense... taking the cylinder as an example, that solves the horizontal connection (East to West) and how can you connect the top and bottom of the cylinder (so north and south is connected) then just extend the cylinder and connect it!
So it's basically a long cylinder connected, and that's why it looks like a doughnut, but this is only an abstraction to help us understand how the "torus" surface can be modelled in a three-dimensional space!

We will also explore how we can compute the "Torus" and the tiles, as well as how to rotate horizontally and vertically the "Torus" projection.

I've prepared this live demo so you can play with a "Torus" doughnut yourself! https://pulgamecanica.github.io/torus-grid-viewer/

Now, we should talk about maps. In game development one of the most basic components is the map, but it doesn't necessarily defines the game dynamics.
While the map defines the space where we are situated, it doesn’t limit how we can represent the space.
A 2d map be a a top-down view, or horizontal, isometric; etc.

But in any case, usually maps have a linear transformation that allows us to represent the perspective we want. 

Here is the formula to translate any point from our 2d map to the 3d "doughnut"

I will explain easily what this formula means and why it works.

First of all let's demonstrate how the "Torus" can be defined with circles alone.

Look at the image bellow.

Take for example the following section of the Torus:

It represents a column of our map.

If the map was:

It can represent

That means that the height of the map, 3 in this case represents 2π (2 pi), that is the circumference of a circle.
A=0, D=π and G=2π
Since we are talking about columns, that means this represents the y in our map, and the same for the column

A=0, B=π and C=2π

This will allow us to represent ALL the map coordinates within the two circles that correspond to each column and row, and this means that:

If it's easier for you to think of it in terms of percentage % you can. 2PI represents the circumference (this is the whole area of our column/row) so the width or height should represent also 2PI, this way ALL points in the row/column will be inside the circumference! Easy, no? :D

So we've found out what u and v mean in the formula, it's just a simple rule of 3 :)

I'll continue defining the formula bellow having this in mind.

Finally by applying that transformation to any point in your map, you can find the position in the "Torus Surface" with ease.

If you want to rotate horizontally or vertically, you can just vary the correspondence of the interval. The formula for x, y, and z stays the same, it's just the formula of u and v that will change, by adding your deplacement factor and applying modulo to the result to make sure it's within bounds. 

Bellow you can see a simulation I did using spheres, where you can rotate the bagel.

You can visit all the code examples I've done:

a. https://github.com/pulgamecanica/torus-grid-viewer

b. https://github.com/pulgamecanica/torus-viewer