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

.. contents:: Table of Contents
   :depth: 1
   :local:

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

What is PyUnity?
================
PyUnity is a Python implementation of the
UnityEngine_, which was originally written
in C++. PyUnity has been modified to be as
easy to use in Python as possible, without
sacrificing the flexibility and the
versatilility of Unity.

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

Basic concepts
==============
In PyUnity, everything belongs to a
``GameObject``. A GameObject is a named
object that has lots of Components on it, each
affecting the GameObject and other GameObjects.
Components are Python objects that do a specific
job, like rendering an object or deleting other
GameObjects.

Transforms
==========

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

A Transform also manages the hierarchy system in PyUnity.
Each transforms can have multiple children, which are all
Transforms attached to the children GameObjects.
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
programing 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 PySDL2
   Trying PySDL2 as a window provider
   Using window provider PySDL2
   Loaded PyUnity version 0.4.0

Note: the output beneath the import is debug info, you
can turn it off with the environment variable
``PYUNITY_DEBUG_INFO`` set to ``"0"``. For example:

   >>> import os
   >>> os.environ["PYUNITY_DEBUG_INFO"] = "0"
   >>> from pyunity import *
   >>> # No output

Now we've 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 how Quaternions work, only use
the ``eulerAngles`` property.

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