자주 쓰는 Unity API 한 장

이번 글에서는 아래 내용을 정리한다.

• 등급 기준과 표 읽는 법
• 모르는 명령을 찾는 세 가지 방법, 그리고 Inspector 칸 이름과 코드 이름
• 먼저 외울 최상 8개
• 클래스별 명령 사전: 스크립트 뼈대, 오브젝트, Transform, 물리, 수학, 입력, UI, 그림·애니메이션·소리, 카메라·씬·저장, 코루틴·이벤트·속성, 디버그·풀링·색·레이어
• 에디터 조작, Unity 6에서 바뀐 이름, 2D와 3D 대응표

들어가기에 앞서

레모네이드 가판대 회차 3까지 끝내고 나니 C# 코드는 읽힌다. 그런데 직접 쓰려고 하면 유니티 명령이 떠오르지 않는다. Rigidbody를 코드에서 움직이려면 무엇을 불러야 하는지, Inspector에서 본 그 칸이 코드에서는 무슨 이름인지가 바로 나오지 않는다. 명령어를 모르는 느낌이다.

그래서 자주 쓰는 명령을 한 장에 모았다. 처음에는 대표 명령만 추렸는데 너무 빈약해서, 클래스별 사전으로 다시 만들었다. 자주 쓰는 것일수록 크게 적었다.

기준은 Unity 6(6000.6), 2D URP, 새 Input System이다. 여기 적은 이름은 전부 지금 쓰는 6000.6.2f1 에디터에서 리플렉션으로 있는지, 폐기(Obsolete) 표시가 붙었는지 확인했다. 그 과정에서 FindFirstObjectByType이 6.6에서 폐기 예정이 된 것도 알았다.

등급 기준

표 읽는 법은 이렇다.

• 클래스도 등급을 매겼다. 빨간 상자는 최상 클래스, 주황 상자는 상 클래스, 상자가 없는 표는 중 클래스다.
• 표 안의 명령은 등급 순서로 적었고, 최상과 상은 굵게 적었다.
• 예시는 그 줄만 떼어 읽을 수 있게 짧게 적었다. 변수 이름(rb, sr, cam)은 그 컴포넌트를 필드에 받아 둔 것이다.

모르는 명령을 찾는 법

Inspector 칸 이름과 코드 이름을 나란히 놓으면 이렇다. 대부분 같고, 몇 개만 다르다.

꼭 기억할 것 ⑤ Inspector의 Position은 position이 아니라 localPosition이다

Inspector의 Transform 칸은 부모 기준 값을 보여 준다. 부모가 없으면 둘이 같아서 모르고 지나가다가, 오브젝트를 다른 오브젝트 밑에 넣는 순간 값이 어긋난다. 코드의 transform.position은 월드 좌표다.

먼저 외울 것: 최상 8개

아래 여덟 개는 거의 모든 스크립트에 나온다. 뒤의 사전에도 다시 나오지만, 여기서는 설명과 주의할 점까지 크게 적는다.

라이프사이클: Awake, Start, Update, FixedUpdate

void Awake()       { rb = GetComponent<Rigidbody2D>(); }
void OnEnable()    { stand.Sold += OnSold; }
void OnDisable()   { stand.Sold -= OnSold; }
void Update()      { timer -= Time.deltaTime; }
void FixedUpdate() { rb.MovePosition(rb.position + Vector2.right * speed * Time.fixedDeltaTime); }

[SerializeField]

[SerializeField] private float speed = 2f;   // 숫자는 Inspector에서 조절
[SerializeField] private Stand stand;        // 참조는 Inspector에 끌어다 놓아 연결

꼭 기억할 것 ⑥ 코드의 초기값보다 Inspector 값이 이긴다

= 2f 같은 코드의 초기값은 컴포넌트를 처음 붙일 때나 필드를 새로 추가했을 때만 쓰인다. 그 뒤로는 씬과 프리팹에 저장된 값이 이긴다. 코드에서 초기값을 바꿔도 이미 놓인 오브젝트의 값은 그대로다. 그리고 Play 중에 Inspector에서 바꾼 값은 멈추면 되돌아가지만, Play 밖에서 바꾼 값은 Ctrl+S와 함께 씬에 저장된다.

transform.position

transform.position = new Vector3(0f, 2f, 0f);                   // 그 자리로 순간이동
transform.position += Vector3.right * speed * Time.deltaTime;   // 조금씩 이동
transform.Translate(Vector3.right * speed * Time.deltaTime);    // 회전이 없으면 같은 일. 방향은 자기 기준

GetComponent<T>(), TryGetComponent

rb = GetComponent<Rigidbody2D>();                          // 없으면 null
if (other.TryGetComponent(out Stand stand)) { /* ... */ }  // 없을 수도 있을 때
var sr = GetComponentInChildren<SpriteRenderer>();         // 자식까지 찾기

Time.deltaTime

transform.position += Vector3.right * speed * Time.deltaTime;   // 초당 speed만큼
timer -= Time.deltaTime;                                         // 타이머 줄이기

Instantiate, Destroy

Customer c = Instantiate(customerPrefab, spawnPos, Quaternion.identity); // 위치와 회전을 주고 만들기
Customer c2 = Instantiate(customerPrefab, transform);                    // 이 오브젝트의 자식으로 만들기
Destroy(c.gameObject);                                                   // 없애기. 그 프레임 끝에 사라진다
Destroy(effectObject, 2f);                                               // 2초 뒤에 없애기

SetActive

shopPanel.SetActive(true);         // 창 열기
c.gameObject.SetActive(false);     // 풀에 넣을 때
bool on = gameObject.activeSelf;   // 지금 켜져 있나

Debug.Log

Debug.Log($"판매 +{price}");                     // 일반 (흰색)
Debug.LogWarning("재고가 부족하다");               // 경고 (노란색)
Debug.LogError("가판대가 연결되지 않았다", this);   // 에러 (빨간색)

클래스별 명령 사전

MonoBehaviour: 스크립트의 뼈대

GameObject와 Object: 만들고, 찾고, 없애기

Transform: 위치, 회전, 크기, 계층

Rigidbody2D: 물리로 움직이기

꼭 기억할 것 ⑦ Rigidbody가 붙으면 transform이 아니라 Rigidbody로 움직인다

물리 엔진은 자기 틱에서 바디를 움직인다. transform.position을 직접 바꾸면 엔진은 그것을 이동이 아니라 순간이동으로 본다. 그래서 지나가는 길의 충돌과 트리거를 건너뛸 수 있고, 다른 바디와 겹친 자리에 떨어지면 튕겨 나가고, 보간도 안 되어 끊겨 보인다. 스폰처럼 일부러 순간이동할 때만 rb.position을 쓰고, 그것도 주변에 아무것도 없는 자리에서 한다.

Collider2D와 Collision2D: 충돌 모양과 충돌 정보

Physics2D: 영역 검사와 광선

Vector2, Vector3: 위치와 방향

Quaternion: 회전

2D에서 어떤 방향을 바라보게 할 때는 이렇게 한다. 오른쪽이 0도다.

Vector2 dir = target - (Vector2)transform.position;
float angle = Mathf.Atan2(dir.y, dir.x) * Mathf.Rad2Deg;
transform.rotation = Quaternion.Euler(0f, 0f, angle);

Time: 시간

Mathf: 수학 함수

Random: 무작위

Input System: 키보드, 마우스, 터치

UI: uGUI와 TextMeshPro

SpriteRenderer: 2D 그림

Animator: 애니메이션

AudioSource: 소리

ParticleSystem: 파티클

Camera: 카메라와 좌표 변환

씬과 앱

저장: JSON 파일과 PlayerPrefs

주의: JsonUtility는 [System.Serializable]이 붙은 클래스의 public 또는 [SerializeField] 필드만 저장한다. Dictionary와 프로퍼티는 저장되지 않는다. 세이브는 임시 파일에 쓴 다음 교체해야 쓰는 도중에 꺼져도 안전하다.

코루틴과 Awaitable: 기다리기

이벤트: 알리고 구독하기

속성(Attribute): Inspector와 직렬화 조절

ScriptableObject: 데이터 에셋

[CreateAssetMenu(menuName = "Lemonade/Upgrade")]
public class UpgradeData : ScriptableObject
{
    public string title;
    public int cost;
}

Debug와 Gizmos: 확인하기

ObjectPool: 풀링

주의: 같은 객체를 두 번 Release하면 예외가 난다. 풀에 돌려줄 때는 위치, 타이머, 이벤트 구독을 모두 초기화한다.

Color, LayerMask, 태그

꼭 기억할 것 ⑧ gameObject.layer에는 번호, 검사 함수에는 마스크를 넣는다

NameToLayer는 레이어 번호(0~31)를 돌려주고, GetMask는 그 번호 자리의 비트를 켠 마스크를 돌려준다. Physics2D.OverlapCircle(pos, r, LayerMask.NameToLayer("Customer"))처럼 번호를 마스크 자리에 넣으면 에러 없이 엉뚱한 레이어를 검사한다. 번호 3을 마스크로 읽으면 0번과 1번 레이어가 되기 때문이다.

에디터 조작: Hierarchy와 Inspector

명령어뿐 아니라 에디터 조작도 같은 등급으로 나눴다.

Unity 6에서 바뀐 이름

옛 강좌나 AI가 짠 코드에서 왼쪽 이름이 보이면 오른쪽으로 바꿔 읽는다. 아래 옛 이름은 6000.6 에디터에서 전부 폐기 표시가 붙어 있는 것을 확인했다.

2D와 3D 대응표

3D로 넘어가면 이름 끝의 2D가 빠지는 것이 대부분이다. 다만 2D와 3D 물리는 서로 다른 엔진이라 섞어 쓸 수 없다.

마치며

이 표는 외우려고 만든 것이 아니다. 최상은 안 보고 쓸 수 있을 때까지 직접 쳐 보고, 상은 한 번씩 써 보고, 중과 하는 필요할 때 여기서 찾는다.

명령이 떠오르지 않으면 점을 찍어 목록을 훑고, Inspector 칸 이름을 코드 이름으로 바꿔 본다. 대부분은 그것으로 찾아진다.