[TUTORIAL] Métodos importantes da Unity

por **MayLeone** Ter Dez 01, 2020 11:40 pm

Introdução -

Olá pessoal, bem vindos a mais um tópico aqui na comunidade! Hoje irei dar início a um guia rápido para iniciantes sobre Unity em relação a programação!
Cada tópico irá conter informações específicas sobre o que temos na Unity e seus conceitos de programar com as suas APIs!

O que planejo para este guia é que você aprenda de forma rápida e direta diversas funções, propriedades, campos, atributos, eventos e classes da API da Unity, sem precisar perder tempo com longos tutoriais, algo que com uma rápida leitura você consegue aprender diversos conceitos práticos (e teóricos) sobre a Unity, e ainda a sanar as suas dúvidas, como se fosse uma "mini-documentação".

Funções Importantes da Unity:

Para iniciar este guia, vou salientar aqui algumas das funções mais utilizadas e importantes que você poderá estar utilizando quando for programar nesta engine, segue:

Instantiate:

A função Instantiate poderá ser chamada diretamente em qualquer classe que derive de MonoBehavior, ou estaticamente utilizando Object.Instantiate.

Essa função serve para que você possa instanciar (clonar) um objeto ou um componente na cena, em tempo de execução.

Para clonar um objeto é importante que você tenha uma referência do mesmo em seu script, essa referência pode ser feita de várias formas, as mais comuns são feitas através de prefabs ou objetos ativos em cena.

Exemplo do uso do Instantiate:

Nesse exemplo eu vou instanciar um cubo em tempo de execução através de um prefab que foi anexado ao inspector do script:

C #:

Código:: using UnityEngine; public class Test : MonoBehaviour { public GameObject cube; private void Start() { Instantiate(cube); } }

No inspector do objeto com o script eu referencio através do campo "cube" o prefab a ser clonado:

[TUTORIAL] Métodos importantes da Unity 49b05cf4ca1eda3595425667005a96d6

[TUTORIAL] Métodos importantes da Unity 49b05cf4ca1eda3595425667005a96d6

Você pode também referenciar um objeto ativo em cena, através do inspector, o resultado é o mesmo.

Agora temos dois cubos em cena:

[TUTORIAL] Métodos importantes da Unity 38ee7faa562b25d6cc0a9845f708d756

[TUTORIAL] Métodos importantes da Unity 38ee7faa562b25d6cc0a9845f708d756

A função Instantiate também permite que você instancie o objeto em alguma posição e rotação específicas:

C #:

Código:: Instantiate(cube, new Vector3(2, 2, 0), Quaternion.identity);

O resultado em cena seria este (dois cubos - o original e o clone):

[TUTORIAL] Métodos importantes da Unity Aa37dc09ca0ec163be40ad0c8f4d3ae2

Esta função também retorna o objeto clonado para uma variável, assim você pode manipular esse objeto dentro do código em tempo de execução, por exemplo:

C #:

Código:: var clone = Instantiate(cube, new Vector3(2, 2, 0), Quaternion.identity); clone.GetComponent<BoxCollider>().isTrigger = true;

A função instantiate possui as seguintes sobrecargas:

public static Object Instantiate(Object original);
Instancia o objeto nas posições e rotação: (0, 0, 0) na cena

public static Object Instantiate(Object original, Transform parent);
Instancia o objeto como filho de outro objeto

public static Object Instantiate(Object original, Transform parent, bool instantiateInWorldSpace);
Instancia o objeto como filho de outro objeto, e ao deixar o último parâmetro como "true", a posição e rotação deste objeto serão relativos ao mundo, e não localmente, em relação ao objeto-pai.

public static Object Instantiate(Object original, Vector3 position, Quaternion rotation);
Instancia o objeto numa posição e rotação específica.

public static Object Instantiate(Object original, Vector3 position, Quaternion rotation, Transform parent);
Instancia um objeto em uma posição e rotação específica, como filho de outro objeto.

Documentação oficial: https://docs.unity3d.com/ScriptReference/Object.Instantiate.html

Invoke e InvokeRepeating:
Ambas funções apenas podem ser utilizadas em classes que derivam de MonoBehaviour.

Invoke:
A função Invoke irá chamar (invocar) um método dentro do script em um determinado tempo, através do seu nome que deve ser passado como uma string.

Por exemplo, vamos chamar o método "MostrarMensagem" depois de 5 segundos:

C #:

Código:: using UnityEngine; public class Test : MonoBehaviour { private void Start() { Invoke("MostrarMensagem", 5); } private void MostrarMensagem() { Debug.Log("Mensagem exibida após alguns segundos"); } }

Teste o código acima e perceba que a mensagem será exibida em console após 5 segundos.

Se você definir o tempo de chamada para zero, a função será invocada no próximo ciclo de frames do Update.

Documentação oficial: https://docs.unity3d.com/ScriptReference/MonoBehaviour.Invoke.html

InvokeRepeating:
Assim como a função Invoke, chama um método específico referenciado através de uma string, porém, esta função irá chamar o método repetidamente, com o tempo de chamada definido por você, por exemplo:

C #:

Código:: using UnityEngine; public class Test : MonoBehaviour { private void Start() { InvokeRepeating("MostrarMensagem", 1, .4F); } private void MostrarMensagem() { Debug.Log("Mensagem exibida a cada 0.4 segundos"); } }

A função "MostrarMensagem" será invocada a cada 0.4 segundos, após 1 segundo inicial.
No console teremos algo como isto:

[TUTORIAL] Métodos importantes da Unity 9301882e33cad8f30ce48b5abeced5f4

[TUTORIAL] Métodos importantes da Unity 9301882e33cad8f30ce48b5abeced5f4

Para encerrar o ciclo do InvokeRepeating utilize a função: CancelInvoke.
*No caso de utilizar o CancelInvoke, passe como argumento o nome da função que deseja cancelar a repetição, caso contrário, o CancelInvoke irá cancelar todas as invocações no script (se houver mais de uma).

Documentação oficial¹: https://docs.unity3d.com/ScriptReference/MonoBehaviour.InvokeRepeating.html
Documentação oficial²: https://docs.unity3d.com/ScriptReference/MonoBehaviour.CancelInvoke.html

StartCoroutine, Coroutines, e instruções de suspensão:
A função StartCoroutine inicia uma coroutine.
Antes de entrarmos em detalhes de como utilizar esta função, vamos entender o que é uma Coroutine (Sub-rotina):

Coroutine:
Uma Coroutine na Unity é uma sub-rotina que será executada como uma função qualquer, com a diferença de que poderá ser suspensa em algum momento da aplicação. Ela irá parar de executar até que algum comando a instrua a retornar o processo.
Esse processo fica aguardando por uma instrução "yield" que irá determinar qual será sua condição de continuação de execução.
A rotina fica suspensa paralelamente a outras funções dentro do script de onde ela está contida, não afetando outras rotinas periféricas em execução (algo bem próximo a funções assícronas).

Uma rotina que ficará em suspensão deve SEMPRE retornar um tipo IEnumerator e deve conter em algum momento no escopo o retorno de uma instrução yield, por exemplo:

C #:

Código:: private IEnumerator Aguardar() { yield return new WaitForSeconds(10); Debug.Log("Aguardei 10 segundos"); }

No caso do exemplo acima, a rotina ficará suspensa durante 10 segundos (através da função WaitForSeconds); após esse tempo, o que há após a instrução "yield" será executado, no caso, a mensagem de debug.

StartCoroutine:
Para chamar subrotinas, utilizamos a função "StartCoroutine", passando como argumento o nome da sub-rotina a ser invocada:

C #:

Código:: StartCoroutine("Aguardar");

Se você testar o script perceberá que a mensagem irá aparecer no console após 10 segundos.

Ao invés de passar o nome da coroutine como string, você pode passar também a ação duma vez:

C #:

Código:: StartCoroutine(Aguardar());

Isso te possibilita passar argumentos para dentro da Coroutine, por exemplo, o tempo de espera, que pode variar:

C #:

Código:: using UnityEngine; using System.Collections; public class Test : MonoBehaviour { private void Start() { StartCoroutine(Aguardar(5)); StartCoroutine(Aguardar(2)); StartCoroutine(Aguardar(10)); } private IEnumerator Aguardar(float tempo) { yield return new WaitForSeconds(tempo); Debug.Log($"Aguardei {tempo} segundos"); } }

Note que ao testar o código acima, a coroutine é chamada em três tempos diferentes, e essas chamadas não são executadas paralelamente e sim em fila, ou seja, a coroutine que aguarda 10 segundos precisou esperar o tempo das outras duas coroutines anteriores para ser chamada.
Veja o resultado e o tempo de chamada em console:

[TUTORIAL] Métodos importantes da Unity E03299537d9fff795ca273bdb7b48fdc

[TUTORIAL] Métodos importantes da Unity E03299537d9fff795ca273bdb7b48fdc

Existem diversos comandos que podem suspender uma subrotina além do WaitForSeconds (que suspende a mesma por alguns segundos), temos por exemplo a função "WaitUntil" que suspende a função até que uma condição seja cumprida, por exemplo, uma variável alcançar um determinado valor:

C #:

Código:: using UnityEngine; using System.Collections; public class Test : MonoBehaviour { private int variable = 0; private void Start() { StartCoroutine(AguardarCondicao()); } private void Update() { if (Input.GetKeyDown(KeyCode.Space)) variable++; } private IEnumerator AguardarCondicao() { yield return new WaitUntil(() => variable == 4); Debug.Log("Sub-rotina liberada"); } }

No caso do código acima, a sub-rotina "AgurdarComando" só vai exibir a mensagem em console, assim que a variável "variable" ficar igual a 4, que será incrementada cada vez que o jogador pressionar a tecla "Space".

Para parar a execução de espera de uma Coroutine, utilize a função "StopCoroutine" e passe o nome da coroutine que deseja parar, ou a própria sub-rotina como argumento.

Você pode declarar uma coroutine (uma ação que retorna o IEnumerator) em classes que não derivem de MonoBehaviour, porém, só poderá utilizar o "StartCoroutine" em classes que derivem dela.

Documentação oficial: https://docs.unity3d.com/Manual/Coroutines.html
Documentação oficial: https://docs.unity3d.com/ScriptReference/MonoBehaviour.StartCoroutine.html
Documentação oficial: https://docs.unity3d.com/ScriptReference/WaitForSeconds.html
Documentação oficial: https://docs.unity3d.com/ScriptReference/WaitUntil.html
Documentação oficial: https://docs.unity3d.com/ScriptReference/MonoBehaviour.StopCoroutine.html

Funções "Find":

As funções "Find" fazem o que o próprio nome sugere: procura.
No caso, essas funções procuram por objetos ou componentes que estejam ativos em cena, e caso encontrado, retornam esse objeto.

Find:
Temos a função "Find" que pode ser usada em qualquer classe que derive de Object (ou não), e pode ser chamada estaticamente assim: GameObject.Find.
Essa função irá procurar na cena por objetos que contenham o nome passado como argumento e irá retornar esse objeto, caso encontre:

C #:

Código:: using UnityEngine; public class Test : MonoBehaviour { public GameObject player; private void Start() { player = GameObject.Find("Player"); } }

FindObjectWithTag:
Já esta função "find" vai procurar pelo objeto na cena que possui a tag passada como argumento:

C #:

Código:: private void Start() { enemy = GameObject.FindGameObjectWithTag("Enemy"); }

Você pode encontrar mais de um objeto com mesma tag, desde que utilize o GameObject.FindGameObjectsWithTag, que retorna um array com os objetos procurados:

C #:

Código:: using UnityEngine; public class Test : MonoBehaviour { public GameObject[] items; private void Start() { items = GameObject.FindGameObjectsWithTag("Item"); } }

FindObjectOfType:
Talvez a versão "mais segura" dentre as funções "find" seja esta.
Através dessa função (que você pode chamar diretamente dentro de classes derivadas do MonoBehavior), você pode encontrar objetos em cena que sejam de um determinado tipo, em outras palavras, possuam um determinado componente.
No exemplo a seguir, eu vou procurar pelo objeto em cena que possua um componente de "BoxCollider":

C #:

Código:: using UnityEngine; public class Test : MonoBehaviour { public BoxCollider _collider; private void Start() { _collider = FindObjectOfType<BoxCollider>(); } }

Caso exista mais de um objeto em cena do mesmo tipo, o "FindObjectOfType" vai retornar o primeiro que encontrar, dentro da hierarquia da Unity.
Caso queira que retorne todos os objetos do tipo específico, utilize o "FindObjectsOfType":

C #:

Código:: using UnityEngine; public class Test : MonoBehaviour { public BoxCollider[] _colliders; private void Start() { _colliders = FindObjectsOfType<BoxCollider>(); } }

FindObjectsOfTypeAll:
Semelhante a função anterior, a diferença é que esta função encontra objetos que estejam desativados na cena também.

Documentação oficial: https://docs.unity3d.com/ScriptReference/GameObject.Find.html
Documentação oficial: https://docs.unity3d.com/ScriptReference/GameObject.FindWithTag.html
Documentação oficial: https://docs.unity3d.com/ScriptReference/Object.FindObjectOfType.html
Documentação oficial: Unity - Scripting API: Resources.FindObjectsOfTypeAll

GetComponent:
Esta função talvez seja a mais "famosa" dentre todas.
Com ela você pode ter acesso a componentes dentro de um GameObject, acessando assim campos, propriedades, eventos e funções contidas neste componente.
Vamos supor que seu GameObject possua um componente de Rigibody anexado a ele, e em outro script você deseja alterar o campo "Mass" do rigibody.
Para fazer acesso ao componente de "Rigibody" você pode utilizar a função "GetComponent", ela irá retornar o tipo especificado (genérico) e assim você terá acesso a tudo o que for público deste componente, para ler ou alterar dentro de outro script:

C #:

Código:: using UnityEngine; public class Test : MonoBehaviour { private void Start() { GetComponent<Rigidbody>().mass = 800; } }

É uma boa prática armazenar o valor retornado do 'GetComponent' dentro de uma variável, não só para poder utilizar esse valor em outros pontos do código, como também porque é uma má prática usar o "GetComponent" diretamente em outras funções como Update, por exemplo, pois pode influenciar na performace do código:

C #:

Código:: using UnityEngine; public class Test : MonoBehaviour { private Rigidbody _rigidbody; private void Start() { _rigidbody = GetComponent<Rigidbody>(); _rigidbody.mass = 800; } }

Esse script acima deve estar anexado a um GameObject em cena que possui um componente de "Rigidbody" que é requerido no nosso código, caso ele não tenha, o script nos retornará um erro.
Você pode utilizar o atributo "RequireComponent" para garantir que o objeto terá esse componente utilizado no script, e caso não tenha, ele será adicionado ao objeto:

C #:

Código:: using UnityEngine; [RequireComponent(typeof(Rigidbody))] public class Test : MonoBehaviour { private Rigidbody _rigidbody; private void Start() { _rigidbody = GetComponent<Rigidbody>(); _rigidbody.mass = 800; } }

Lembre-se que os scripts do tipo MonoBehavior que você cria, também serão considerados componentes, isso significa que você pode fazer acesso a scripts externos no GameObject, também utilizando o "GetComponent".

Caso queria fazer acesso a um componente de um objeto que não seja o objeto do script que está solicitando acesso, você pode referenciar esse objeto no seu script de diversas formas (através do inspector, prefabs, ou através das funções "Find") e utilizar o GetComponent para fazer acesso ao componente desejado:

C #:

Código:: using UnityEngine; public class Test : MonoBehaviour { private Rigidbody _rigidbody; private void Start() { _rigidbody = GameObject.Find("Player").GetComponent<Rigidbody>(); _rigidbody.mass = 800; } }

Se quiser fazer acesso a componentes de um mesmo tipo, você pode utilizar a função "GetComponents" e armazenar o valor retornado dentro de um array:

C #:

Código:: using UnityEngine; using System.Collections; [RequireComponent(typeof(Collider))] public class Test : MonoBehaviour { private Collider[] _colliders; private void Start() { _colliders = GetComponents<Collider>(); foreach(var _collider in _colliders) { _collider.isTrigger = true; } } }

No exemplo acima, temos um GameObject que contém diversos componentes de Colliders diferentes, então fazemos acesso a todos eles através do GetComponents, mudando o campo 'isTrigger' do collider para verdadeiro.

Documentação oficial: https://docs.unity3d.com/ScriptReference/GameObject.GetComponent.html
Documentação oficial: https://docs.unity3d.com/ScriptReference/RequireComponent.html
Documentação oficial: https://docs.unity3d.com/ScriptReference/GameObject.GetComponents.html

Destroy:
A função "Destroy" fará com que um objeto em cena seja destruído imediatamente.
Você pode utilizar essa função diretamente dentro de classes que derivem de MonoBehaviour, ou pode chamá-la estaticamente dessa forma: Object.Destroy.
Você deve passar como argumento o objeto a ser destruído, por exemplo:

C #:

Código:: private void Start() { Destroy(this.gameObject); }

Essa instrução vai destruir o próprio objeto.

Você pode destruir o objeto após alguns segundos, basta passar um segundo argumento à função contendo o tempo em segundos da destruição:

C #:

Código:: Destroy(this.gameObject, 3);

O objeto será destruído após 3 segundos.

Você pode destruir (remover) um componente de um GameObject, basta utilizar o "GetComponent" dentro da função:

C #:

Código:: Destroy(this.gameObject.GetComponent<BoxCollider>());

Documentação oficial: https://docs.unity3d.com/ScriptReference/Object.Destroy.html

Finalização:
E aí está! Essas funções são muito importantes na Unity e tenho certeza que você vai utilizá-las com bastante frequência em seus códigos! Caso queria solicitar alguma função que você deseje saber como funciona, ou sugerir alguma outra que você julgue importante, deixe nos comentários!