05. Common

이 문서의 목표

Runtime/Common에 있는 범용 유틸리티가 왜 존재하고 언제 쓰는지 이해한다.

왜 필요한가

동일한 유틸 로직(해시, 문자열 처리, 랜덤 등)이 여러 곳에서 중복 구현되는 것을 막기 위해 존재한다. 실제로 MathUtils.DampFactor는 카메라 회전 감쇠 공식이 3곳에서 중복 작성된 것을 발견하고 통합한 사례다.

언제 사용하는가

Gameplay/Framework 어디서든 컬렉션 조작, 수학 계산, 랜덤, ID 생성, 문자열 처리가 필요할 때 항상 먼저 여기서 찾는다. 새로 구현하기 전에 존재 여부를 MCP_Index.md Common 섹션에서 확인한다.

프로젝트에서 어떤 역할인가

Framework/Game 어느 계층에서도 참조 가능한 최하위 유틸리티 계층이다 (System, Pattern이 아니라 순수 함수/구조체 중심).

실제 게임에서는 언제 호출되는가

예: 카메라 회전 보간 -> MathUtils.DampFactor(lambda, dt), 컬렉션에서 마지막 요소 조회 -> GetLast/TryGetLast.

코드 예제

float t = MathUtils.DampFactor(lambda: 10f, dt: Time.deltaTime);
if (list.TryGetLast(out var last)) { /* ... */ }

관련 Sample

Samples/Common/CommonSample.cs

Best Practice

새 유틸을 추가하기 전 CollectionUtils, MathUtils, StringUtils, HashUtils 등 기존 클래스에 동일 책임 함수가 있는지 확인한다.

자주 하는 실수

• 카메라/이동 보간마다 감쇠 공식을 새로 작성 (MathUtils.DampFactor 사용해야 함)
• PopBack 같은 구식 API를 찾음 -> 현재는 GetLast/TryGetLast/RemoveLast로 대체됨

실습 과제

1. CollectionUtils에서 TryGetLast를 사용해 리스트의 마지막 요소를 안전하게 꺼내본다.
2. IdGenerator로 고유 ID를 생성해본다.

이전 문서 / 다음 문서

이전: 04_Dependency_Injection.md 다음: 06_Core.md

관련 API

MCP_Index.md Common 섹션 전체