======================
Tutorial 1: The Basics
======================

In this tutorial you will be learning
the basics to using PyUnity, and
understanding some key concepts.

What is PyUnity?
================
PyUnity is a Python port of the
UnityEngine_, which was originally written
in C++. PyUnity has been modified to be
easy to use in Python, which means that
some features have been removed.

.. _UnityEngine: https://unity.com/

Basic concepts
==============
In PyUnity, everything will belong to a
GameObject. A GameObject is a named object that
has lots of different things on it that will
affect the GameObject and other GameObjects.
Each GameObject has its own Components, which
are like the hardware in a computer. These
Components can do all sorts of things.

Transforms
==========

Each GameObject has a special component called
a Transform. A Transform holds information about
the GameObject's position, rotation and scale.

A Transform can also have a child. This child is
also a GameObject's component. All transforms will
have a localPosition, localRotation and localScale,
which are all relative to their parent. In addition,
all Transforms will have a ``position``, ``rotation`` and
``scale`` property which is measured in global space.

For example, if there is a Transform at 1 unit up from
the origin, and its child had a ``localPosition`` of
1 unit right, then the child would have a ``position`` of
1 unit up and 1 unit to the right.

Code
====
All of that has now been established, so let's start to
program it all! To start, we need to import PyUnity.

   >>> from pyunity import *
   Loaded config
   Trying GLFW as a window provider
   GLFW doesn't work, trying Pygame
   Trying Pygame as a window provider
   Using window provider Pygame
   Loaded PyUnity version 0.3.1

The output beneath the import is just debug statement, you
can turn it off with the environment variable
``PYUNITY_DEBUG_INFO`` set to ``"0"``.

Now we have loaded the module, we can start creating our
GameObjects. To create a GameObject, use the ``GameObject``
class:

   >>> root = GameObject("Root")

Then we can change its position by accessing its transform.
All GameObjects have references to their transform by the
``transform`` attribute, and all components have a reference
to the GameObject and the Transform that they belong to, by
the ``gameObject`` and ``transform`` attributes. Here's
how to make the GameObject positioned 1 unit up, 2 units to
the right and 3 units forward:

   >>> root.transform.localPosition = Vector3(2, 1, 3)

A Vector3 is just a way to represent a 3D vector. In PyUnity
the coordinate system is a left-hand Y-axis up system, which
is essentially what OpenGL uses, but with the Z-axis flipped.

Then to add a child to the GameObject, specify the parent
GameObject as the second argument:

   >>> child1 = GameObject("Child1", root)
   >>> child2 = GameObject("Child2", root)


**Note**: Accessing the ``localPosition``, ``localRotation`` and
``localScale`` attributes are faster than using the ``position``,
``rotation`` and ``scale`` properties. Use the local attributes
whenever you can.

Rotation
========
Rotation is measured in Quaternions. Do not worry about these,
because they use some very complex maths. All you need to know
are these methods:

#. To make a Quaternion that represents no rotation, use
   ``Quaternion.identity()``. This just means no rotation.
#. To make a Quaternion from an axis and angle, use the
   ``Quaternion.FromAxis()`` method. What this does is it
   creates a Quaternion that represents a rotation around
   an axis clockwise, by ``angle`` degrees. The axis
   does not need to be normalized.
#. To make a Quaternion from Euler angles, use
   ``Quaternion.Euler``. This creates a Quaternion from
   Euler angles, where it is rotated on the Z-axis first,
   then the X-axis, and finally the Y-axis.

Transforms also have ``localEulerAngles`` and ``eulerAngles``
properties, which just represent the Euler angles of the
rotation Quaternions. If you don't know what to do, only use
the ``localEulerAngles`` property.

In the next tutorial, we'll be covering how to render things
and use a Scene.