Helper Pattern

Abstract

헬퍼는 프레임워크 코드를 고치지 않고 동작을 바꾸는 손잡이입니다. "로그를 파일에도 남기고 싶다", "엔티티를 다른 방식으로 인스턴스화하고 싶다" 같은 요구가 생기면 프레임워크 소스를 여는 대신 헬퍼 클래스를 하나 만들어 갈아 끼웁니다.

언제 쓰나

•

플랫폼마다 구현이 달라야 하는 부분 (로그, 압축, JSON)

•

프레임워크의 기본 동작이 내 게임과 맞지 않는 부분 (UI 정렬 방식, 사운드 에이전트)

•

프레임워크를 업데이트해도 내 수정이 날아가지 않게 하고 싶을 때

직접 해 보기 — 로그에 시각 붙이기

using GameFramework;
using UnityEngine;

namespace MyGame
{
    public class TimestampLogHelper : GameFrameworkLog.ILogHelper
    {
        public void Log(GameFrameworkLogLevel level, object message)
        {
            string line = Utility.Text.Format("[{0:F2}] {1}", Time.realtimeSinceStartup, message);

            switch (level)
            {
                case GameFrameworkLogLevel.Warning: Debug.LogWarning(line); break;
                case GameFrameworkLogLevel.Error:   Debug.LogError(line);   break;
                default:                            Debug.Log(line);        break;
            }
        }
    }
}

복사

GameFramework.prefab 루트의 BaseComponent 에서 Log Helper Type Name 을 MyGame.TimestampLogHelper 로 바꾸면 끝입니다. 네임스페이스까지 포함한 전체 타입 이름을 적습니다. 이후 Log.Info(...) 를 부르는 모든 코드가 새 헬퍼를 거칩니다.

ToyboxNightmare 에서 헬퍼가 필요했던 지점

기본 UI 그룹 헬퍼(DefaultUIGroupHelper)의 SetDepth 는 빈 구현입니다. 그래서 UI 그룹의 depth 값을 바꿔도 화면 순서가 바뀌지 않습니다. 예제는 각 폼 Canvas 의 Sorting Order 로 순서를 정했지만(HUD 0, 일시정지 100), 그룹 depth 로 제어하고 싶다면 UIGroupHelperBase 를 상속해 SetDepth(int depth) 를 구현한 헬퍼를 만들면 됩니다. 프레임워크가 "기본값은 주되 정책은 강요하지 않는다"는 것을 보여 주는 예입니다.

이 에디션에서 다른 점: 아래 본문은 인스펙터의 드롭다운으로 헬퍼를 고른다고 설명합니다(BaseComponentInspector, HelperInfo). 그 에디터 확장은 이 에디션에 들어 있지 않습니다. 대신 인스펙터에 보이는 ... Helper Type Name 문자열 필드에 타입 이름을 직접 입력합니다. 동작은 같습니다. 본문에서 "Diagram: ..." 이라고만 적히고 그림이 없는 곳은 원본 다이어그램이 누락된 자리입니다.

Helper Pattern

Pattern Overview

Unity Game Framework에서 구현된 Helper Pattern은 일관된 구조를 따릅니다:

•

인터페이스 또는 추상 기본 클래스가 필요한 기능을 정의한다.

•

공통 사용 사례를 처리하는 기본 구현이 제공된다.

•

시스템은 필요할 때 개발자가 커스텀 구현으로 대체할 수 있도록 한다.

이 패턴은 플랫폼별 구현이 필요할 수 있는 기능이나, 개발자가 커스텀 동작으로 확장하고 싶어할 수 있는 기능에 특히 중요합니다.

Diagram: Helper Pattern Class Structure

출처:

Scripts/Runtime/Sound/SoundAgentHelperBase.cs 1-189

Scripts/Runtime/Sound/DefaultSoundAgentHelper.cs 1-435

Helper Registration and Management

프레임워크는 컴포넌트 인스펙터를 통해 헬퍼를 관리하여, 개발자가 기본 구현과 커스텀 구현 중에서 선택할 수 있도록 합니다. 이 설정은 일반적으로 Unity 에디터에서 수행됩니다.

Diagram: Helper Selection and Registration Flow

출처:

Scripts/Editor/Inspector/BaseComponentInspector.cs 46-170

Global Helpers

BaseComponent는 프레임워크 전반에서 기본적인 기능을 제공하는 여러 코어 헬퍼들을 관리합니다:

•

Text Helper – 텍스트 처리 유틸리티

•

Version Helper – 버전 정보와 비교

•

Log Helper – 로깅 기능

•

Compression Helper – 데이터 압축 및 해제

•

JSON Helper – JSON 직렬화 및 역직렬화

이 헬퍼들은 BaseComponent 인스펙터에서 설정할 수 있으며, 개발자는 기본 구현을 선택하거나 커스텀 구현을 제공할 수 있습니다.

Diagram: Global Helpers in BaseComponent

출처:

Scripts/Editor/Inspector/BaseComponentInspector.cs 64-103

Scripts/Runtime/Utility/DefaultVersionHelper.cs 1-41

Scripts/Runtime/Utility/DefaultJsonHelper.cs 1-52

Helper Selection in Inspector

Unity 에디터는 각 컴포넌트에 대한 헬퍼를 선택하고 구성할 수 있는 커스텀 인터페이스를 제공합니다. 이를 통해 개발자는 기본 구현을 선택하거나 직접 만든 커스텀 헬퍼를 지정할 수 있습니다.

BaseComponentInspector는 글로벌 헬퍼를 위한 이 UI를 구현합니다:

TextHelper 선택 드롭다운

VersionHelper 선택 드롭다운

LogHelper 선택 드롭다운

CompressionHelper 선택 드롭다운

JsonHelper 선택 드롭다운

각 드롭다운은 프로젝트 어셈블리에서 발견된 사용 가능한 헬퍼 구현들로 채워집니다.

출처:

Scripts/Editor/Inspector/BaseComponentInspector.cs 64-103

Helper Implementation Discovery

프레임워크는 런타임에 사용 가능한 헬퍼 구현을 찾기 위해 리플렉션을 사용합니다. Type.GetRuntimeTypeNames() 메서드는 특정 헬퍼 인터페이스를 구현하는 클래스를 지정된 어셈블리에서 검색합니다.

Diagram: Helper Implementation Discovery Process

출처:

Scripts/Editor/Misc/Type.cs 78-91

Scripts/Editor/Misc/Type.cs 93-125

Example: Sound Agent Helper

프레임워크에서 Helper Pattern의 구체적인 예시는 오디오 재생을 다루는 Sound Agent Helper 시스템입니다.

Diagram: Sound Agent Helper Class Hierarchy

출처:

Scripts/Runtime/Sound/SoundAgentHelperBase.cs 1-189

Scripts/Runtime/Sound/DefaultSoundAgentHelper.cs 1-435

Creating Custom Helpers

커스텀 헬퍼를 만들려면:

적절한 헬퍼 인터페이스를 구현하거나 헬퍼 기본 클래스를 상속한다.

구현을 적절한 Unity 어셈블리에 추가한다.

인스펙터를 통해 컴포넌트를 설정하여 커스텀 헬퍼를 사용한다.

예: 커스텀 JSON 헬퍼를 만들려면:

•

Utility.Json.IJsonHelper를 구현하는 클래스를 만든다.

•

필요한 메서드(ToJson, ToObject<T> 등)를 구현한다.

•

BaseComponent 인스펙터에서 커스텀 구현을 선택한다.

Component-Specific Helpers

BaseComponent가 관리하는 글로벌 헬퍼 외에도, 많은 프레임워크 컴포넌트들은 각각 고유한 헬퍼를 가지고 있습니다. 예시:

•

Sound 컴포넌트는 SoundAgentHelper 사용

•

Resource 컴포넌트는 ResourceHelper와 LoadResourceAgentHelper 사용

•

Web Request 컴포넌트는 WebRequestAgentHelper 사용

•

File System 컴포넌트는 FileSystemHelper 사용

각각은 기본 구현을 제공하면서 커스텀 교체도 가능하게 동일한 패턴을 따릅니다.

Helper Selection Implementation

프레임워크는 인스펙터에서 헬퍼를 표시하고 선택하는 과정을 단순화하기 위해 유틸리티 클래스를 제공합니다.

Diagram: Helper Info Class Used in Inspectors

출처:

Scripts/Editor/Misc/HelperInfo.cs 1-98

HelperInfo<T> 클래스는 인스펙터 UI를 처리하여, 헬퍼 구현들 중에서 선택할 수 있는 드롭다운 메뉴와 필요할 경우 커스텀 헬퍼 필드를 표시합니다.

Default Helper Implementations

프레임워크는 필요한 모든 헬퍼의 기본 구현을 제공합니다. 이 구현들은 대부분의 공통 사용 사례에서 작동하는 기본 기능을 제공합니다.

Default Version Helper

DefaultVersionHelper는 Unity Application의 버전을 기반으로 버전 정보를 제공합니다:

•

게임 버전은 Application.version 반환

•

내부 게임 버전은 0 반환

출처:

Scripts/Runtime/Utility/DefaultVersionHelper.cs 1-41

Default JSON Helper

DefaultJsonHelper는 Unity의 내장 JsonUtility를 사용하여 JSON 직렬화/역직렬화를 수행합니다:

•

직렬화에는 JsonUtility.ToJson 사용

•

역직렬화에는 JsonUtility.FromJson 사용

출처:

Scripts/Runtime/Utility/DefaultJsonHelper.cs 1-52

Summary

Helper Pattern은 Unity Game Framework에서 시스템 동작의 커스터마이징과 확장을 가능하게 하는 근본적인 아키텍처 접근 방식입니다. 인터페이스와 구현을 분리하고, 기본 및 커스텀 옵션 모두를 제공함으로써 프레임워크는 사용의 용이성과 유연성 사이의 균형을 달성합니다.

Helper Pattern의 주요 이점은 다음과 같습니다:

•

일반적인 사용 사례를 위한 합리적인 기본값 제공

•

플랫폼별 요구 사항에 대한 커스터마이징 허용

•

특수 기능으로의 확장 가능

•

의존성 주입을 통한 테스트 용이성 제공

•

관심사의 명확한 분리 생성

이 패턴은 프레임워크 전반에서 일관되게 사용되며, 시스템 커스터마이징을 위한 통일된 접근 방식을 형성합니다.