September 8, 2016

# The Circle Tutorial

#### Vectors and the Known Universe

So sooner or later it had to happen and here it comes the “Mathy Stuff!” ZR competitions are played on the inside of the International Space Station (until the day one sneaks out.) As such the playing field or The Known Universe has a very finite size based on the dimensions of the Japanese Science module. In space we have to simply agree on the orientation of the dimensions and things go like this… the play field is ~1.28 meters wide, ~1.6 meters long and ~1.3 meters high. Since the origin is at the center of the universe, we compete in a volume that has the following limits: -.64<x<.64, -.8<y

In recent games you will find that the axes are labeled in the simulator window. Not so lucky in FreeMode, and just to keep things interesting, they are not intuitive. The positive x axis goes “into” your screen with negative x “coming out.” The positive y axis is to the right and the negative y axis is to the left. Finally, following the right hand rule, the positive z axis runs down and the negative runs up. Interestingly, in many cases if we write code that is based on the relationships between the objects, none of this matters. Remembering this orientation will sometimes help you interpret what is happening as you watch a simulation.

To represent positions, velocities, orientations and rotation rates we use collections of x,y and z values called vectors. In general vectors can have any number of dimensions, but for the rest of this tutorial we will be talking about 3D or 3-dimensional vectors. Positions in space are represented by a vector reaching from the origin of the universe to the location we want to represent. Velocities are represented by vectors made up of the changes in position of each axis that occur per second. Orientations are represented by a unit vector (a vector with a length or magnitude of one) originating in the center of the SPHERE and pointing in the same direction as the SPHERE is pointing. Rotation rates are represented by vectors containing the rotation rates around the x-, y- and z-axis respectively. Rotation rates are expressed in the frame of the satellite itself not in the global frame.

This can be difficult to imagine, but a little practice will make this second nature.

When we created our vector “vec” in the Run Away section we used this same vector in many ways. The data structure we use, an array of three floats, is the same regardless of what the vector represents, so when we used it with setPositionTarget it was interpreted as a position in space or an offset from the center of the universe. When we used it with setVelocityTarget, it was interpreted as the change in position each second of our SPHERE. So here we will treat vectors as both an array of three floats and a mathematical construct. There is a more formal discussion of vectors and vector math on the ZR site here, that will complement what we’re doing in this tutorial.

### Just say “no” to 2D.

A quick note for those of you who have read the rules for the previous games or have come across mention of the “2D game.” There is a 2D game phase in which the SPHEREs are locked into the X/Y plane. It is better to get used to thinking in 3D and thinking of the 2D game as simply having a Z-axis value of 0. The reason is that the ZR navigation API functions all use 3D vectors – passing them 2D vectors can have random and disastrous results. So in the 2D game you still use 3D vectors. Ironically, if you want to rotate your SPHERE to point at some point in the X/Y plane you need to rotate about the Z-axis and in general we need a 3D vector to do that. So even the 2D game uses 3D stuff. Also in the tutorial we will talk about 2D/3D navigation in terms of vector manipulation. While many problems in the 2D phase can be solved other ways (i.e. trig) if you use vector manipulation from the start you often find that your methods don’t need to change between the 2D and 3D phases. This will be an immense savings in time and energy. Often simple 2D trigonometry solutions turn into very complex 3D solutions, while simple vector methods don’t change at all. Trig. functions also consume large amounts of memory which you will soon find is in short supply on a SPHERE satellite. The lesson is to learn to think in vectors!