Tutorial de scripts para Unity 3d

AddComponent:

function AddComponent (className : String) : Component


Añade un componente a nuestro gameobject. Ese componente ha de ser una instancia de la clase que ponemos en el parámetro className, o bien puede ser el nombre de un script. Es útil para añadir componentes en tiempo de ejecución.

Algunos componentes requieren de la presencia de otros para existir, así que al añadir aquéllos automáticamente se nos añadirán estos. Pej, si añadimos un HingeJoint automáticamente se nos añadirá un Rigidbody.


function AddComponent (componentType : Type) : Component

La única variación es que en lugar de string, introducimos el tipo de componente o el nombre del script sin comillas.

Nótese que no existe la función RemoveComponent o similar. Para destruir un componente al vuelo, usad Object.Destroy


FUNCIONES DE CLASE:

CreatePrimitive:

static function CreatePrimitive (type : PrimitiveType) : GameObject


Crea un gameobject con una malla de tipo primitivo y el apropiado collider.

Los tipos primitivos son sphere, capsule, cylinder, cube y plane.

Veamos algún ejemplo (recordemos que es una función de clase, no vinculada a un objeto concreto)

Eliminemos antes que nada los dos scripts vinculados al cubo.

Y luego editamos miPrimerScript:

function Start() {
  var miCilindro : GameObject = GameObject.CreatePrimitive(PrimitiveType.Cylinder);
  miCilindro.transform.position = Vector3(0,0,-2);
}

Salvamos y arrastramos a PortaScripts. Vemos que hemos creado en ejecución un tipo primitivo (un cilindro en este caso) de entre los que la enum PrimitiveType nos permite), con su malla y su collider. Este cilindro lo almacenamos en una variable de tipo Gameobject que a partir de ahí podemos tratar como un gameobject más, cambiándole, por ejemplo, de ubicación.


FindWithTag:

static function FindWithTag (tag : String) : GameObject


Devuelve un gameobject con el tag que le pasamos a la función como string en su único parámetro. Si no existe ninguno. Devuelve null.

Dado que es una función de clase y no va vinculada a ningún objeto, ha de quedar claro que el gameobject con el tag que buscamos no tiene por qué hacer referencia a ningún gameobject vinculado al script, sino a cualquier gameobject del juego que esté activo.

El tag, eso sí, previamente debe estar declarado en el tag manager del inspector.


FindGameObjectWithTag:

static function FindGameObjectsWithTag (tag : String) : GameObject[]


Esta función de clase devuelve una lista de gameobjects activos que tengan el tag requerido.


Find:

static function Find (name : String) : GameObject


Busca un gameobject por nombre y lo devuelve. Aquí no buscamos por tag, sino por nombre. Hemos de reiterar que es una función de clase, no vinculada a un determinado gameobject, o sea, podemos buscar con esta función cualquier gameobject activo del juego.


Se puede usar el slash (/) para buscar a través de una jerarquía.

Por motivos de rendimiento es aconsejable no usar esta función cada frame. Es mejor o, una vez hallado el gameobject, almacenarlo en una variable, o bien usar la función gameobject.findwithtag. Por poner un ejemplo sencillo, reeditemos una vez más miPrimerScript:

var buscaLaEsfera : GameObject;
buscaLaEsfera = GameObject.Find("Esfera");
Debug.Log(buscaLaEsfera.name.ToString());
buscaLaEsfera.renderer.material.color = Color.green;

Tal como indicábamos en la definición, buscamos con Find un gameobject de nombre Esfera, lo almacenamos en una variable de tipo gameobject, y ya a partir de ahí podemos, por ejemplo, imprimir su nombre o cambiarle el color.

GetComponentInChildren:

function GetComponentInChildren (type : Type) : Component


Devuelve un componente activo de tipo que le pasamos como parámetro que pueda tener o bien el Gameobject que lanza el mensaje o bien sus hijos. La búsqueda empieza por los hijos.


GetComponents:

function GetComponents (type : Type) : Component[]


Esta función devuelve todos los componentes del tipo Type y los devuelve en forma de array del tipo de componente solicitado.

Esto nos permitiría hacer cosas como las del ejemplo que nos brinda el manual de referencia (no es preciso seguir el ejemplo, es sólo a modo oritentativo):

//Vamos a desconectar la variable spring de todos los HingeJoints que tenga este
//gameobject. Primero crearemos un array de tipo HingeJoint y lo almacenamos  
//en la variable bisagras. 


var bisagras : HingeJoint[];

//Y colocamos todos los HingeJoint que encontremos en el array.

bisagras = gameObject.GetComponents (HingeJoint);

//Recorremos ahora en un bucle for in todos los componentes hallados y les  
//desactivamos la variable spring.

for (var joint : HingeJoint in bisagras) {
joint.useSpring = false;
}

GetComponentsInChildren:

function GetComponentsInChildren (type : Type, includeInactive : boolean = false) : Component[]


Devuelve todos los componentes del tipo pasado como primer parámetro que tenga ese gameobjects y sus hijos. La peculiaridad es que la función incluye un segundo parámetro opcional de tipo booleano que si establecemos en true nos permite recuperar también los componentes inactivos de ese tipo.


SetActiveRecursively:

function SetActiveRecursively (state : boolean) : void


Función que activa o desactiva el estado del gameobject que la invoca y de todos sus hijos, en función de si el bolean que tiene como parámetro está en true o false.


CompareTag:

function CompareTag (tag : String) : boolean


Esta función nos permite averiguar si un determinado gameobjet tiene como tag el string colocado como parámetro de la función. Si lo tiene, la función devuelve true.


SendMessageUpwards:

function SendMessageUpwards (methodName : String, value : object = null, options : SendMessageOptions = SendMessageOptions.RequireReceiver) : void


Esta función llama a una función cuyo nombre pasamos en el parámetro methodName y que se encuentre en cualquier script que tengamos vinculado al gameobject que hace la llamada o en los "padres" de dicho gameobject. Le podemos, si procede, pasar un valor a dicho método (value). El parámetro options es del tipo SendMessageOptions, que es un enum con dos valores = requireReceiver (que necesita respuesta) y dontRequireReceiver, que no la requiere.

Por defecto la función requiere respuesta, lo cual quiere decir que si se le pasa un argumento a la función receptora y ésta no precisa ninguno, imprimirá un mensaje de error. Si no lo requiriera (dontRequireReceiver), puede optar por ignorar dicho argumento sin más.

Vamos a intentar aclararlo un poco más con un ejemplo. Previamente eliminemos el script que tenemos vinculado en PortaScripts. Acto seguido, editamos miPrimerScript y lo dejamos como sigue:

function DameColor (tono : Color) {
renderer.material.color= tono;
}
DameColor(Color.black);

La función no requiere más explicación. La arrastramos al cubo y al darle al play éste se torna de color negro.

Ahora vamos a editar el script miSegundoScript, que si hemos seguido las lecciones debemos tener en Proyecto. (y si no creamos uno, tampoco nos volvamos locos). Tecleamos:

function OnMouseEnter() {
gameObject.SendMessageUpwards ("DameColor", Color.cyan);
}

Arrastramos tras salvar este script también al cubo. De esta manera y a través de SendMessageUpwards podemos acceder a la función DameColor de miPrimersScript y usarla a nuestro gusto. En este caso nos limitamos a cambiar el color del cubo al pasar el ratón por éste, pero obviamente y en caso de gameobjects con un montón de scripts vinculados (que a eso llegaremos) esta posibilidad de acceder desde un scripts a las funciones que hay en otros es toda una ventaja.


SendMessage:

function SendMessage (methodName : String, value : object = null, options : SendMessageOptions = SendMessageOptions.RequireReceiver) : void


Igual que la función anterior, con la diferencia de que en esta sólo podemos llamar a funciones que estén en scripts vinculados al gameobject, pero no en sus ancestros.


BroadcastMessage:

function BroadcastMessage (methodName : String, parameter : object = null, options : SendMessageOptions = SendMessageOptions.RequireReceiver) : void


Llama a un método con nombre methodName que esté en cualquier script vinculado a ese game object o a cualquiera de sus hijos, a diferencia de las funciones anteriores.

FUNCIONES:

GameObject:

static function GameObject (name : String) : GameObject


La función constructora de gameobject tiene tres prototipos diferentes. El primero, como vemos, nos permite crear un nuevo gameobject y pasarle un parámetro que constituirá el nombre de dicho gameobject. Veamos un ejemplo sencillo.

Editamos MiPrimerScript:

var nuevoGameObject: GameObject;

nuevoGameObject = new GameObject("miNuevoObjeto");

Lo salvamos. Si no lo estaba, lo arrastramos a PortaScripts. Le damos al play.

Aparentemente no ocurre nada. No aparece ningún objeto en la escena ni en la ventana del juego. Esto es porque nuestro nuevo gameobject está vacío, como podremos comprobar si -con el juego reproduciéndose- seleccionamos el nuevo gameobject de nombre miNuevoObjeto que aparece en la jerarquía. Observamos que tan sólo tiene un elemento transform (que se crea por defecto).

Pero, ya teniendo un gameobject creado en tiempo de ejecución (y volveremos sobre este concepto pasado no demasiado tiempo), podemos de la misma forma añadirle componentes:

var nuevoGameObject: GameObject;

nuevoGameObject = new GameObject("miNuevoObjeto");
nuevoGameObject.AddComponent ("BoxCollider");
nuevoGameObject.AddComponent ("MeshRenderer");

En este caso le añadimos un collider de cubo y una meshrenderer. Seguirá sin verse nuestro nuevo gameobject -salvo que lo seleccionemos en la jerarquía, en cuyo caso veremos la malla) porque para ello le deberíamos haber creado una malla desde cero, pero a los efectos de este ejemplo con esto debería bastar.

static function GameObject () : GameObject


Crea un gameobject, pero sin nombre nombre, lo cual no obsta para que luego se le pueda asignar uno.


static function GameObject (name : String, params components : Type[]) : GameObject

Esta variante del constructor crea un gameobject con nombre y ya vinculado a una serie de componentes prefijados.


GetComponent:

function GetComponent (type : Type) : Component


Esta función devuelve el componente de tipo Type que tenga el gameobject. En caso de que el gameobject que lanza el mensaje no tenga ningún componente de ese tipo, devuelve null.

Además de acceder a componentes Standard de unity, puedes acceder a scripts por esta vía. En este caso, el nombre del script equivaldrá al Type del parámetro de búsqueda. Ojo, porque aunque pongamos el nombre del script, como en realidad sustituye y equivale a un tipo de componente, lo escribiremos sin comillas (no es un string)

Es decir, si por ejemplo quisiéramos -no hace falta que realicéis este ejemplo, es sólo para aclarar conceptos- hacer algo en caso de que un determinado gameobject tenga un determinado script, haríamos algo como esto:

var unObjetoCualquiera : GameObject;

if(unObjetoCualquiera.GetComponent(miPrimerScript) {
   HazAlgunaCosa();
}

Arrastraríamos luego el gameobject que quisiéramos consultar, y si éste tuviera vinculado un script de nombre miPrimerScript -en caso contrario devolvería null- se ejecuta la función HazAlgunaCosa.

Esta función nos permite además acceder a variables públicas (no private ni dentro de funciones) y funciones que se hallen en otro script que esté vinculado al mismo gameobject. Pongamos que el script del ejemplo lo vinculamos directamente a un gameobject (no como el anterior, en que arrastramos el gameobject a la variable expuesta) y dicho gameobject a su vez tiene vinculado otro script llamado otroScript. Podemos capturarlo con esta función y asignarlo a una variable de tipo ScriptName.

var unSegundoScript : ScriptName = gameObject.GetComponent(otroScript);
 
// Una vez ya hemos capturado ese script, como decimos, podemos acceder a sus  
//funciones y variables públicas. 

unSegundoScript.HazOtraCosa ();
unSegundoScript.tengoUnaVariable = 5;
}

function GetComponent (name : String) : Component

Es identica a la anterior, pero en lugar de acceder a un componente por su tipo, lo hacemos por su nombre a través de un string (aquí sí colocaremos comillas). Es preferible la primera firma por motivos de rendimiento, pero si no recordamos el tipo del componente, podemos buscar por el nombre.

Recordemos que el nombre de un script ajeno pero vinculado al gameobject que hace la consulta es también su tipo, lo cual no obsta a que siga siendo su nombre y podamos consultarlo por él, aunque con comillas (“otroScript”, sería en este caso la manera de escribir el parámetro de búsqueda)

guiText:

var guiText : GUIText

El guiText (de próximo estudio) vinculado al gameobject. Nulo si no existe.


networkView:

var networkView : NetworkView

El networkView (a estudiar mucho más adelante) vinculado al gameobject. Nulo si no existe.


guiTexture:

var guiTexture : GUITexture


El guiTEXture (en breve) vinculado al gameobject. Null si carece de él.


collider:

var collider : Collider


El collider vinculado al gameobject, si lo tiene. Null en caso contrario.


hingeJoint:

var hingeJoint : HingeJoint


El hingeJoint vinculado al gameobject, o null.


particleEmitter:

var particleEmitter : ParticleEmitter


El particleEmitter vinculado al gameobject, null si no tiene.


layer:

var layer : int


Es una variable de tipo int comprendida entre el rango 0 y 31 que indica/coloca la capa en la que el gameobject se encuentra.

El layer sirve entre otras cosas para realizar un renderizado selectivo de lo que una cámara debe mostrar o para determinar si a un determinado gameobject les afectará o no un raycast.


active:

var active : boolean


¿Está el gameobject activo?. Podemos habilitarlo/deshabilitarlo cambiando a true o false este booleano.


tag:

var tag : String


El tag (etiqueta) de este game object. Puede ser usado para identificar a un gameobject. Hemos de recordar que antes de poder usar esta variable debemos haber declarado el tag en el inspector

animation:

var animation : Animation


La animación vinculada al gameobject. Null si no tiene.

No hemos tratado aún nada relacionado con animaciones, clips y sonidos, ya que he preferido reservarlo para más adelante y tratarlo todo junto.



constantForce:

var constantForce : ConstantForce


la constantForce vinculada a este gameobject. Null si no tiene ninguna vinculada.

No habíamos tratado todavía la miniclase ConstantForce, pero vamos a subsanar ese pequeño lapsus ahora mismo:

La clase ConstantForce deriva de Behaviour (como camera, light, animation...) y cuenta sólo con cuatro variables/propiedades (amén de las heredadas), que son:

force:  var force : Vector3
  La fuerza aplicada al rigidbody cada frame. Esto último es lo que la diferencia de
  rigidbody.AddForce(). En AddForce se aplica la fuerza al rigidbody una vez por 
  frame, lo que obliga a llamar a la función varias veces (por ejemplo dentro de una
  función fixedUpdate). constantForce.force aplicará la fuerza indicada cada frame 
  hasta que cambiemos el contenido de la variable force a un nuevo valor. Esto es 
  aplicable a las cuatro variables de esta clase.

relativeForce:  var relativeForce : Vector3 
  La fuerza -relativa al sistema de coordenadas local del rigidbody- aplicada cada 
  frame.

torque:  var torque : Vector3 
  La torsión aplicada al rigidbody cada frame.

relativeTorque:  var relativeTorque : Vector3 
  La torsión -relativa al sistema de coordenadas local del rigidbody- aplicada cada 
  frame.

Pongamos un ejemplo global: Antes que nada seleccionamos el cubo, y nos vamos al menú=>Component=>Physics=>Constant Force.

Editamos una vez más MiPrimerScript:

var unGameObject: GameObject;

unGameObject.constantForce.force = Vector3(3,10,0);
unGameObject.constantForce.torque = Vector3(0,8,0);

Salvamos. Recordemos que este script lo tenemos vinculado al gameobject PortaScripts, así que lo seleccionamos. Arrastramos el cubo a la variable expuesta. Observemos que ambos atributos están fuera de toda función o bucle, esto es, que tal como hemos dicho, tanto la fuerza (hacia la derecha y hacia arriba) como la torsión (sobre el eje Y) que le aplicamos tendrán carácter periódico debido única y exclusivamente a las propias características de la clase constantForce. Play.


renderer:

var renderer : Renderer


El renderer vinculado al gameobject. Null si no tiene.


audio:

var audio : AudioSource


el audiosource vinculado al gameobject. Null si no tiene.

Estamos en la clase central, en la clase con mayúsculas de Unity. De hecho, muchas de las clases que hasta la fecha hemos estudiado (y algunas que nos faltan) no son más que diferentes mimbres cuya función primordial era confluir en esta clase.

No deberá sorprendernos, por tanto, que buena parte de las variables o propiedades de la clase GameObject no son sino instancias de las clases que ya hemos estudiado, de tal forma que cualquier gameobject en la escena (recordemos que todo lo que está en la escena son gameobjects) tenga la más amplia funcionalidad.


VARIABLES:

isStatic:

var isStatic : boolean

Variable sólo utilizable vía interface que especifica si un objeto es estático.

Esto es útil cuando estemos trabajando con occlusion culling, para determinar si un objeto puede ser considerado un oclusor estático.

Para quien no sepa qué diantres es lo de occlusion culling, decir que es una característica que deshabilita el renderizado de objetos cuando no están siendo actualmente vistos por la cámara porque son oclusionados/tapados por otros objetos.

El proceso de occlusion culling va a travé de la escena usando una cámara virtual construyendo una jerarquía de objetos potencialmente visibles. Estos datos serán usados en tiempo de ejecución por cada cámara para identificar qué es visible y qué no.

Necesitamos etiquetar todos los objetos de la escena que queramos que sean parte de la occlusion como Static en el inspector. La manera más rápida de hacerlo es convertir todos los objetos que queramos marcar como estáticos en hijos de un GameObject vacío y establecer éste como Static, eligiendo luego en la opción de diálogo que la condición de static afecte también a todos sus hijos. Después de eso, ya podemos tranquilamente desparentarlos del gameobject vacío, y seguirán teniendo la consideración de static.


transform:

var transform : Transform


El transform del gameobject, si lo tiene. Null si no tiene ningún transform vinculado.

Tal como explicaba antes, ésta va a ser la tónica de la mayoría de propiedades de la clase Gameobject: integrar objetos/instancias de diferentes clases para conformar la utilidad básica de nuestro juego: los gameobjects. Podemos demostrar que todo lo que está en la escena es un gameobject:

Eliminamos antes que nada el gameobject particulas que creamos en la clase anterior. Si tenemos algún script vinculado al cubo o la esfera, los eliminamos.

Vamos a editar ahora MiPrimerScript:

var unGameObject: GameObject;

function Update() {
  unGameObject.transform.Rotate(0,5,0);
}

El script debería resultarnos fácil a estas alturas. Declaramos una variable expuesta de tipo Gameobject, de tal manera que posteriormente podamos acceder al transform de la que arrastremos y rotar el gameobject sobre el eje Y.

Salvamos. Arrastramos el script a PortaScripts en la jerarquía. Con PortaScripts seleccionado, arrastramos el cubo a la variable expuesta. Play.

Tal como era de esperar, el cubo comienza a girar. Pero vamos a ver qué otros elementos en la escena son considerados por Unity Gameobjects, y por tanto susceptibles de tener un transform. Si con PortaScripts seleccionado nos vamos al inspector, observaremos que a la derecha de la variable expuesta que hemos inicializado con el cubo hay una pequeña flecha. Si hacemos click sobre ella, se nos abre un menú emergente con TODOS los gameobjects de la escena. De hecho hasta nuestro PortaScripts -a pesar de no ser ni visible- es considerado un gameobject. Así, si en ese mismo popup hacemos doble click en main camera y le damos al play, observaremos en la vista del juego que lo que empieza a girar es la cámara.


rigidbody:

var rigidbody : Rigidbody


El rigidbody vinculado a nuestro gameobject, o null si éste no tiene rigidbody.


camera:

var camera : Camera



La cámara vinculada a nuestro gameobject, o null si éste no tiene una cámara. Por ejemplo, nuestra main camera es un gameobject que tiene vinculado una cámara (y un transform).


light:

var light : Light


La luz vinculada al gameobject. Null si no tiene.