Current Version : 2.1.0

UNInject는 Unity를 위해 설계된 고성능 의존성 주입 프레임워크임.
editor-time baking, Roslyn source generation, three-tier scoping,
그리고 타입이 partial로 선언된 경우 reflection 없는 런타임 경로를 목표로 설계되었음.

UNInject는 editor-time dependency baking, Roslyn Source Generation,
그리고 hierarchical scoping을 결합하여 전통적인 DI 구현에서 흔히 발생하는 reflection 병목이나
runtime lookup 오버헤드 없이 매우 효율적인 runtime dependency injection을 가능하게 함.

기존 DI 시스템들이 FindObjectsOfType 호출이나 무거운 reflection 초기화에 의존하는 것과 달리 UNInject는 성능,
결정론적 dependency resolution, 개발자 사용성을 중심으로 설계된 완전한 injection architecture를 제공함.

https://github.com/NightWish-0827/UNInject.git?path=/com.nightwishlab.uninject
UPM Add package from git URL

Table of Contents

• Core Features
• Pure C# service layer
• API Reference & Usage
• Usage patterns: concrete types & MonoBehaviour
• IScope, Registry & Named Bindings
• Per-installer API surface
• Constructor Injection & Create<T>()
• Tickables & Scope Teardown
• User Callbacks — Reference
• Lifecycle & Internal Architecture
• Dynamic Object Support
• Performance & Injection Paths
• Editor Supports
• Common Editor Warnings

Core Features

Editor-Backed Bake Architecture

ObjectInstaller는 [Inject] 필드를 편집 단계에서 hierarchy에 대해 resolve함 (컨텍스트 메뉴 Bake Dependencies).
연결 정보는 serialize되어 저장되므로, 해당 필드에 대해 runtime hierarchy 스캔이 발생하지 않음.

✦ Roslyn Source Generator — IL2CPP 완전 지원

UNInject는 Roslyn Source Generator 기반의 코드 생성 파이프라인을 도입하여
기존 Expression Tree 방식이 갖고 있던 IL2CPP/AOT 환경에서의 제약을 완전히 해소했음.

동작 방식:

Generator는 [GlobalInject] / [SceneInject] 필드를 가진 클래스를 컴파일 타임에 자동 탐지하고,
두 종류의 소스를 메모리 내에서 직접 생성하여 함께 컴파일함 (디스크에 사용자 파일로 저장되지 않음).

코드 저장 → Unity 컴파일 시작
  → UNInjectGenerator 실행 (저장 시마다 자동)
  → ① {TypeName}.UNInject.g.cs  — partial 클래스 확장 + AggressiveInlining setter
  → ② UNInjectPlanRegistry.g.cs — AfterAssembliesLoaded 등록기
  → 함께 컴파일 완료

생성된 코드는 디스크에 저장되지 않으며, Expression.Compile() 을 일절 사용하지 않음.
단순 캐스트와 직접 대입만으로 구성되어 모든 AOT 환경에서 안전하게 동작함.

사용자에게 요구되는 유일한 변경사항:

[GlobalInject] 또는 [SceneInject] 필드를 가진 클래스 (또는 생성된 생성자 플랜이 필요한 타입)에
public partial class 선언 추가.

// 변경 전
public class PlayerController : MonoBehaviour { ... }

// 변경 후
public partial class PlayerController : MonoBehaviour { ... }

partial 없이 Play 진입 시 UNInjectFallbackGuard가 즉시 경고를 출력함.
또한 Roslyn 컴파일 타임에 UNI001 경고가 발행되어, IDE 레벨에서도 인지할 수 있음.

Runtime Injection Tiers

dependency injection 수행 시 런타임 주입 경로는 우선순위 순으로 세 단계로 구성됨.

Three-Tier Deterministic Scoping

전통적인 DI 시스템들은 lifecycle 관리가 모호해지는 문제가 자주 발생함.

UNInject는 이를 해결하기 위해 세 가지 명확한 scope 계층을 강제함.

Scene 언로드 동작은 SceneInstaller의 SceneExitPolicy 로 제어됨.

• Clear — 소멸 시 registry를 비움 (기본값).
• Preserve — 언로드 이후에도 registry 항목을 유지함 (예: additive 로딩).
  소유권 맵은 초기화되므로, stale한 UnregisterByOwner 경로가 preserved 바인딩을 제거하지 않음.

PlayMode Guard Protection

Baked 기반 시스템에서 발생할 수 있는 잠재적 문제들을 두 개의 독립적인 가드로 방어함.

① MasterInstallerPlayModeGuard — 레지스트리 공백 감지

개발자가 PlayMode 진입 전에 global registry를 갱신하지 않았을 때 발생하는
empty registry 문제를 방지함.

• MasterInstaller가 scene에 존재하고 _globalReferrals.arraySize == 0 이면 즉시 warning 로그를 출력함.

[MasterInstaller] Global registry is empty. Did you forget to click 'Refresh Global Registry' before Play?

② UNInjectFallbackGuard — IL2CPP 폴백 타입 감지

partial 선언 없이 Expression Tree 폴백으로 동작할 타입을 Play 진입 시점에 탐지함.
IL2CPP 빌드에서 FieldInfo.SetValue 폴백까지 내려갈 수 있는 타입 목록을 명시적으로 출력함.

[UNInject] 다음 타입은 'partial' 선언이 없어 Roslyn 생성 플랜 대신
Expression Tree 폴백으로 동작합니다.
  • MyGame.PlayerController
  • MyGame.EnemyAI

두 가드는 감시 대상과 검사 방식이 완전히 독립적이므로 별도 파일로 분리되어 있으며,
동일한 Play 진입 시 두 가드가 모두 발동할 수 있음.

Runtime Registry Shape

Registry는 Dictionary<RegistryKey, Component> 구조를 사용하며, RegistryKey = (Type, Id) 임.

Id == string.Empty는 v1.x 방식의 키 없는 등록과 매칭됨.
Named referral은 [Referral] / [SceneReferral] 및 [GlobalInject] / [SceneInject]
(필드와 생성자 파라미터 모두)에서 동일한 Id 를 사용해 매칭됨.

Cache-Friendly Injection Execution

UNInject는 내부적으로 cached structural mapping 구조를 사용함.

global 및 scene registry는 미리 baked된 리스트 구조를 기반으로 생성되며
Awake 시점에 빠른 Dictionary<Type, Component> lookup 구조로 변환됨.

TypeDataCache는 생성 플랜 캐시와 Reflection 캐시를 분리하여 관리함.
생성 플랜이 등록된 타입은 Dictionary 조회 한 번으로 처리가 완료되며, Warmup() 호출조차 사실상 무비용으로 동작함.

이러한 data-oriented 구조는 scene hierarchy를 직접 순회하는 방식보다 훨씬 높은 성능을 제공함.

Pure C# service layer

UNInject는 두 가지 런타임 역할을 명확히 구분함.

Service layer 인스턴스의 특징:

• [InjectConstructor] (또는 public 생성자가 정확히 하나인 경우 attribute 없이도 동작)로 구성되는
  ReferenceType 객체이며, zero-reflection 생성을 위한 Roslyn TryGetGeneratedFactory 경로를 선택적으로 사용함.
• MonoBehaviour와 동일한 RegistryKey 규칙으로 Component 의존성을 resolve함: 생성자 파라미터에
  [GlobalInject] / [SceneInject] (named Id와 optional 포함)를 선언할 수 있음.
• Unity 메시지를 받지 않음 (Update/OnDestroy 없음). 참여는 명시적으로 이루어짐:
  • ITickable / IFixedTickable / ILateTickable → Create를 호출한 MonoBehaviour installer가
    (Update / FixedUpdate / LateUpdate를 포워딩) 구동함.
  • IScopeDestroyable → 해당 installer의 OnDestroy 실행 시 teardown됨 (Tickables & Scope Teardown 참조).
• Lifetime은 소유 scope의 GameObject에 바인딩됨: MasterInstaller / SceneInstaller / ObjectInstaller가 소멸되면 TickableRegistry.ClearWithDestroy()가 등록된 destroyable에 대해 OnScopeDestroy() 를 실행한 뒤 tick 목록을 초기화.

Create<T>()에 사용할 scope 선택 기준

• MasterInstaller.Create<T>() — resolver가 global 먼저 탐색 후 SceneInstaller fallthrough.
  scene 로드 이후에도 살아남아야 하는 game-wide 서비스에 사용 (installer가 DDOL).
• SceneInstaller.Create<T>() — resolver가 scene 먼저 탐색 후 MasterInstaller. session/scene 단위 로직에 사용.
• ObjectInstaller.Create<T>() — resolver가 local registry → _parentScope 체인(선택적) → scene → global 순 탐색.
  서브트리 로컬 서비스 (예: 하나의 UI root 또는 풀링된 서브시스템 하위)에 사용.

Create<T>()에서 지원하지 않는 타입

• MonoBehaviour — Unity가 생성자 기반 구성을 허용하지 않음.
  대신 SpawnInjected / InjectTarget / InjectGameObject 를 사용할 것.

ScriptableObject 관련 주의: Create<T>()는 생성자 호출(또는 생성된 factory)을 사용함.
Unity ScriptableObject 인스턴스는 일반적으로 ScriptableObject.CreateInstance로 생성하므로,
Create<T>()는 non-UnityEngine.Object service 타입을 대상으로 하는 것으로 간주해야 함.

API Reference & Usage

Resolve는 항상 RegistryKey(Type, Id) 를 사용함. 선언된 필드 (또는 생성자 파라미터)의 Type 이 registry가 보유한 키와 일치해야 함.

해당 키는 concrete MonoBehaviour 등록 (“wide” auto-mapping) 또는 narrow [Referral(BindType)] (“expert” 단일 키)에서 비롯될 수 있음. 초보자와 전문가 모두 동일한 Resolve 를 사용하며, 차이는 등록 방식에 있음.

Usage patterns: concrete types & MonoBehaviour

Pattern 1 — Global manager: concrete type만 사용 (interface 불필요)

많은 팀이 AudioManager 나 GameSettings 를 직접 참조함. interface를 반드시 도입할 필요는 없음.

Provider (MasterInstaller에 bake됨):

// [Referral] with no BindType → wide registration: concrete + mappable interfaces + bases
[Referral]
public partial class AudioManager : MonoBehaviour
{
    public void PlaySfx() { /* ... */ }
}

Consumer (partial + generator):

public partial class PlayerController : MonoBehaviour
{
    [GlobalInject] private AudioManager _audio;
}

동등한 “interface-first” 스타일 (동일한 Resolve, 테스트 seam 명확):

public interface IAudioManager { void PlaySfx(); }

[Referral(typeof(IAudioManager))]
public partial class AudioManager : MonoBehaviour, IAudioManager
{
    public void PlaySfx() { /* ... */ }
}

public partial class PlayerController : MonoBehaviour
{
    [GlobalInject] private IAudioManager _audio;
}

Refresh Global Registry 이후, scene에 AudioManager가 하나 존재하면 두 consumer 모두 동일한 인스턴스를 받음.

Pattern 2 — Scene manager: concrete vs SceneReferral(BindType)

[SceneReferral]
public partial class WaveSpawner : MonoBehaviour { /* ... */ }

// 동일 scene의 ObjectInstaller 하위 Consumer
public partial class HordeDirector : MonoBehaviour
{
    [SceneInject] private WaveSpawner _waves;
}

추상화를 사용하는 경우:

public interface IWaveSpawner { }

[SceneReferral(typeof(IWaveSpawner))]
public partial class WaveSpawner : MonoBehaviour, IWaveSpawner { }

public partial class HordeDirector : MonoBehaviour
{
    [SceneInject] private IWaveSpawner _waves;
}

활성 SceneInstaller 에서 Refresh Scene Registry 를 실행할 것.

Pattern 3 — Local subtree: [Inject] + sibling / child MonoBehaviour (global registry 없음)

전형적인 “beginner” hierarchy: 하나의 ObjectInstaller root 하위에 concrete MonoBehaviour 참조만 사용하는 구성.

public partial class HUD : MonoBehaviour
{
    [Inject] [SerializeField] private HealthBar _healthBar;    // 동일 root 하위 child 또는 sibling
    [Inject] [SerializeField] private PlayerController _player; // SerializeField + Bake Dependencies
}

• [Inject] 는 editor에서 resolve됨 (Bake Dependencies); runtime에는 Unity native deserialization이 자동으로
  참조를 복원함 — [GlobalInject] 불필요.
• 동일 타입에 [GlobalInject] / [SceneInject] 필드가 있다면 public partial class 선언 필요.

Pattern 4 — Named bindings: 동일 field type을 공유하는 여러 인스턴스

Id 없이는 키당 하나의 등록만 유효함 (중복 시 경고 로그). AudioManager 오브젝트가 둘 이상이라면 named referral과
매칭 inject Id 를 사용해야 함.

[Referral("music", typeof(AudioManager))]
public partial class MusicManager : AudioManager { }

[Referral("sfx", typeof(AudioManager))]
public partial class SfxManager : AudioManager { }

public partial class MixerHub : MonoBehaviour
{
    [GlobalInject("music")] private AudioManager _music;
    [GlobalInject("sfx")]  private AudioManager _sfx;
}

BindType 을 interface로 지정할 수도 있음; [Referral] 과 [GlobalInject] 의 Id 는 여전히 쌍으로 일치해야 함.

Pattern 5 — Runtime-spawned MonoBehaviour (concrete Register vs Register<IBind>)

bake-time global discovery에 의존하지 않는 enemy prefab 스폰:

public partial class EnemyView : MonoBehaviour, IEnemyView { /* ... */ }

// Instantiate 이후 —
var scope = GetComponent<ObjectInstaller>(); // 또는 캐싱된 참조
scope.Register<EnemyView>(enemyView, owner: this);  // expert: EnemyView 키만 바인딩
scope.Register(enemyView, owner: this);             // beginner-friendly: inspector [Referral]과 동일

prefab 클래스에 [Referral(typeof(IEnemyView))] 가 있다면 Register(enemyView) 가 BindType 을 자동으로 반영함.

concrete class만 있는 경우에도 typeof(EnemyView) 키로 등록되므로,
다른 타입에서 [GlobalInject] private EnemyView _x 를 interface 없이도 사용할 수 있음.

Pattern 6 — ObjectInstaller 참조 방식

다음 방식들 중 어느 것이든, 동일한 인스턴스를 호출하면 유효함.

[SerializeField] private ObjectInstaller _scope;  // inspector에서 드래그 (초보자에게 일반적)

// 또는
private ObjectInstaller Scope => GetComponentInParent<ObjectInstaller>();

// 또는 (scene-local singleton 경로)
SceneInstaller.Instance.Create<MyService>(); // Scene scope에서 서비스 생성 — ObjectInstaller 필드 불필요

local registry + _parentScope 를 고려한 injection이 필요하면 ObjectInstaller 를 사용하고,
서비스가 해당 installer의 native chain만 사용해야 한다면 MasterInstaller / SceneInstaller 를 사용할 것.

Pattern 7 — Create<T>()와 concrete 생성자 파라미터 (service layer)

public partial class SessionStats
{
    [GlobalInject] private IAnalytics _analytics; // ctor body 실행 후 주입됨

    [InjectConstructor]
    public SessionStats([GlobalInject] AudioManager audio, WaveSpawner waves)
    {
        // [GlobalInject] / [SceneInject] 필드에서 얻는 것과 동일한 인스턴스
    }
}

// var stats = sceneInstaller.Create<SessionStats>();

AudioManager / WaveSpawner는 GlobalInject 필드와 완전히 동일하게 registry에서 resolve되는 concrete Component 타입임. 해당 타입들이 interface 키로 등록되어 있다면 interface도 동일하게 동작함.

Provider attributes (registration)

// Expert: 단일 bind type (BindType + Id 키만 등록됨)
[Referral(typeof(IInputService))]
public partial class DesktopInputManager : MonoBehaviour, IInputService { }

// Named expert binding
[Referral("profileA", typeof(IProfileService))]
public partial class ProfileServiceA : MonoBehaviour, IProfileService { }

// Scene expert binding
[SceneReferral(typeof(ILevelRules))]
public partial class LevelRules : MonoBehaviour, ILevelRules { }

// Beginner-friendly: 최소 attribute; Refresh Global Registry가 이 타입을 자동 수집
[Referral]
public partial class AudioManager : MonoBehaviour { /* ... */ }

(Refresh는 component class에 [Referral] / [SceneReferral] 이 있는 타입만 탐지함.
순수 런타임 오브젝트는 attribute 없이 Register 를 직접 사용할 수 있음.)

editor Refresh Global Registry / Refresh Scene Registry 는 scene을 스캔하여 serialize된 리스트를 채우고,
Awake에서 빠른 dictionary를 재구성함.

Consumer attributes

public partial class PlayerController : MonoBehaviour
{
    [Inject] [SerializeField] private Animator _animator;

    [GlobalInject] private IInputService _input;
    [GlobalInject] private AudioManager _audioConcrete;   // AudioManager가 해당 Type으로 등록된 경우 유효

    [GlobalInject("profileA")] private IProfileService _profile;

    [SceneInject(optional: true)] private LevelManager _level;
}

Optional: [GlobalInject(optional: true)] / [SceneInject(optional: true)]
바인딩이 없어도 injection이 실패하지 않으며, 해당 필드에 대한 경고도 출력되지 않음.

Inspector 표기 정책: optional 미바인딩 필드는 회색, 필수 미등록 바인딩은 에러/경고로 표시됨.

Injected State Alarm

각종 Function 이라 불리우는 Start, Awake 와 마찬가지로, UNInject 또한 명시적인 주입 완료 시점 Function을 제공함.

public partial class PlayerController : MonoBehaviour, IInjected
{
    [GlobalInject] private IInputService _input;
    [SceneInject(true)] private IStageContext _stageContext;    

    public void OnInjected()
    {
        // ObjectInstaller가 이 컴포넌트에 대해 주입을 수행했고,
        // "필수 의존성" 주입이 모두 성공했을 때 자동으로 호출됩니다.

        // 호출 주체: ObjectInstaller.TryInjectTarget() 내부에서 success == true이고  
        // 대상이 IInjected를 구현한 경우 OnInjected()를 호출합니다.
        
        // 호출 조건: 필수(Required) 의존성 주입이 모두 성공했을 때만 호출됩니다.  
        // (Optional로 표시된 의존성 누락은 성공/실패에 영향 없음)
        
        // 호출 시점/횟수: InjectTarget() / InjectGameObject() / Awake()에서  
        // 주입이 실행될 때마다(즉, 주입을 여러 번 호출하면) 그때마다 호출될 수 있습니다.
    }
}

(현재는 IInjected 인터페이스를 상속받아야만 해당 OnInjected 멤버를 사용 가능하지만,
추후 Native 영역으로 이를 추출하여, 별도의 상속 없이도 OnInjected 멤버를 사용할 수 있도록 구조를 변경할 예정임.)

IScope, Registry & Named Bindings

IScope 는 MasterInstaller, SceneInstaller, ObjectInstaller 모두가 구현함.

Register

• Register(Component comp) — comp 타입의 [Referral] / [SceneReferral] 메타데이터(bind type + id)를 사용하여 등록.
• Register(Component comp, MonoBehaviour owner) — 동일; owner 가 소멸되면 해당 owner로 등록된 모든 component가 자동 unregister됨 (ScopeOwnerTracker).
• Register<TBind>(Component comp, MonoBehaviour owner = null) — 코드 우선 바인딩: comp 를 TBind 로 등록 (attribute bind type 선택 사항).

중복 키는 경고 로그를 출력하고 최초 등록을 유지함.

Unregister

• Unregister(Type type) — 키 없는 제거 (Id == default).
• Unregister(Type type, string id) — named 키 제거.
• Unregister(Component comp) — MasterInstaller / SceneInstaller 전용: 값이 comp 인 모든 registry 키를 제거. (ObjectInstaller에는 해당 오버로드 없음; type/id 또는 owner 기반 정리를 사용할 것.)

Resolve

키 없는 방식:

• Resolve(Type type), TryResolve(Type, out Component), Resolve<T>() where T : Component, ResolveAs<T>() where T : class

Named 방식:

• Resolve(Type type, string id), TryResolve(Type, string id, out Component), ResolveAs<T>(string id)

MasterInstaller 는 Instance 위에 ResolveStatic<T>() 도 편의용으로 제공함.

ObjectInstaller resolve chain

ObjectInstaller 는 다음 순서로 resolve함.

1. Local registry (RegistryKey)
2. _parentScope 가 설정된 경우 — 해당 installer의 체인 (재귀)
3. 그 외 — SceneInstaller.Instance 이후 MasterInstaller.Instance

_parentScope 는 선택 사항이며, 중첩 installer 그래프(풀, 격리 서브트리)를 위해 serialize됨.

Per-installer API surface

IScope 외에 존재하는 public 진입점 정리 (editor API는 명시된 경우만 포함):

MasterInstaller

SceneInstaller

ObjectInstaller

ObjectInstaller — injection, spawn, pooling 동작 참조

이 메서드들은 런타임 injection과 동일한 TypeDataCache 필드 플랜을 사용함.
[Inject] (local bake)는 여기에서 적용되지 않으며, [SceneInject] 이후 [GlobalInject] 순으로 처리됨.

Register / Register<TBind> 요점 (local scope): 매핑은 concrete Component 타입의 ReferralAttribute / SceneReferralAttribute 에서 BindType 과 Id 를 가져오며, Register<TBind> 가 지정되면 bind type을 재정의함.

InstallerRegistryHelper 는 concrete 타입, 모든 mappable interface (System.*, UnityEngine.* 등 제외),
MonoBehaviour 직전까지의 base 타입 모두를 동일한 RegistryKey 로 등록함.

TypeDataCache (진단 / warmup)

startup 또는 테스트에서 호출 가능한 public 헬퍼:

• Warmup(Type) / Warmup(params Type[]) — 필드 및 생성자 캐시를 미리 채움.
• HasAnyInjectField, HasGeneratedGlobalPlan, HasGeneratedScenePlan, HasGeneratedFactory — 툴링용 introspection.
• GetGlobalInjectFields / GetSceneInjectFields — 캐싱된 CachedInjectField 목록 반환.

RegisterGenerated* API는 generator 전용 ([EditorBrowsable(Never)]).

Constructor Injection & Create<T>()

IScope.Create<T>() where T : class 는 다음 정확한 순서로 InstallerRegistryHelper.CreateAndInject<T> 를 실행함.

1. Construction — TypeDataCache.TryGetGeneratedFactory 또는 [InjectConstructor] / 단일 public ctor + ConstructorInfo.Invoke. resolve 불가한 필수 ctor 파라미터 → InvalidOperationException.
2. Field injection — 모든 [SceneInject] 필드, 이후 [GlobalInject] 필드 (component와 동일한 optional/required 규칙). 필수 미스 시 내부 success를 false로 설정하고 경고를 출력함.
3. IInjected.OnInjected() — 모든 필수 inject 필드가 성공한 경우 field injection 내부에서 호출됨
   (optional 미스는 성공을 막지 않음).
4. RegisterTickables(object) — T가 ITickable / IFixedTickable / ILateTickable / IScopeDestroyable 를 구현하면, OnInjected 이후 호출 installer의 TickableRegistry 에 등록됨.

ctor/field의 Resolve fallthrough 는 각 installer에 매칭됨 (Master → scene; Scene → master; Object → local → parent → scene → master).

Tickables & Scope Teardown

Create<T>() 로 생성된 plain C# 서비스는 PlayerLoop 조작 없이 Unity 프레임 콜백을 받을 수 있음.

규칙

• host는 항상 Create 를 호출한 MonoBehaviour IScope 임.
• Tick은 부모 scope로 전파되지 않음.
• UnregisterTickable(...) 은 해당 scope에서 제거함; Tick() 은 스냅샷을 사용하므로,
  이터레이션 중 제거는 다음 프레임에 적용됨.
• 하나의 오브젝트가 ITickable / IFixedTickable / ILateTickable 중 여럿을 구현할 수 있으며,
  각 매칭 목록에 모두 등록됨.

Teardown 시 IScopeDestroyable

installer OnDestroy 에서 TickableRegistry.ClearWithDestroy() 가 실행됨.

1. _destroyables 를 순회하며 OnScopeDestroy() 를 호출함 (항목별 try/catch — 하나의 실패가 다른 항목을 건너뛰지 않음).
2. tick 목록 및 내부 스냅샷 상태를 초기화함.

따라서 OnScopeDestroy 는 tick 목록이 초기화되기 전에 실행되며, 프레임 단위 tick 종료 시에는 실행되지 않음.

User Callbacks — Reference

IInjected — 상세

• Required vs optional: optional 의존성 누락은 success를 false로 만들지 않음.
  모든 required 필드가 resolve된 경우 OnInjected 는 정상 실행됨.
• Re-injection: isReinjection: true 는 OnInjected 를 건너뜀. 대상이 IPoolInjectionTarget 을 구현하면
  OnPoolGet 이 대신 실행됨. 그 외에는 해당 패스에서 inject-completion 콜백이 발동되지 않음.
• 재진입성: 성공한 TryInjectTarget / 성공한 Create field phase가 발생할 때마다 OnInjected 가 다시 발동될 수 있음 — “인스턴스당 전역 1회”가 아님.

IPoolInjectionTarget — field semantics

OnPoolRelease 이후 ReleaseTargetToPool 은 TypeDataCache setter를 통해 해당 타입의 [GlobalInject] 및
[SceneInject] 필드 전체를 null 로 할당함 — 풀 인스턴스가 stale Component 참조를 보유하지 않도록 함.

IScopeDestroyable — tick과의 조합

UnityEngine.Object 소멸에 의존하지 않는 plain C#의 해제 (이벤트 구독 취소, 핸들 닫기 등)에 사용함.

동일 서비스에서 ITickable 과 함께 구현할 수 있으며,
destroy 콜백은 ClearWithDestroy 에서 실행되므로 프레임별 tick 스냅샷 규칙과 독립적임.

Lifecycle & Internal Architecture

UNInject는 엄격하게 정렬된 실행 파이프라인을 기반으로 object lifecycle을 관리함.

[Compile]
UNInjectGenerator → partial setter + 플랜 registry 등록

[RuntimeInitialize SubsystemRegistration]
TypeDataCache 정적 캐시 전체 초기화

[AfterAssembliesLoaded]
생성된 플랜을 TypeDataCache에 등록

[Order -1000] MasterInstaller.Awake  → baked 리스트로부터 Global Registry 재구성
[Order -900]  SceneInstaller.Awake   → baked 리스트로부터 Scene Registry 재구성
[Order -500]  ObjectInstaller.Awake  → InjectGlobalDependencies (TypeDataCache 플랜 / 폴백)

Safety net (Master / Scene): registry 빌드 후 첫 번째 조회 miss 시 1회 조용한 재빌드를 트리거할 수 있음.
플래그는 명시적 Register / editor refresh / Rebuild*Registry 에서 다시 활성화됨.

Dynamic Object Support

runtime-spawned 오브젝트는 정적 오브젝트와 동일한 TypeDataCache 경로를 사용함.

ObjectInstaller scope = ...;

var instance = Instantiate(enemyPrefab);
scope.InjectTarget(instance);

scope.InjectGameObject(instanceRoot, includeInactive: true);

partial 타입은 런타임에도 생성된 경로를 유지하므로 (generator가 실행된 경우 IL2CPP-safe),
대량의 동적 생성 객체에서도 allocation 없이 매우 빠른 주입이 가능함.

Performance & Injection Paths

[Inject] / bake: 해당 참조에 대해 런타임에서는 deserialization만 발생함.

생성된 setter는 [MethodImpl(AggressiveInlining)] 이 적용되어
JIT/AOT 모두에서 캐스트 + 대입 수준의 비용으로 동작함.

[MethodImpl(MethodImplOptions.AggressiveInlining)]
internal void __UNInject_Global_input(object __v) => _input = (IInputService)__v;

한 번 캐싱되면 10,000개의 객체 injection도 마이크로초 단위로 수행 가능함.

이는 복잡한 UI 생성이나 대규모 레벨 인스턴스 생성 시 발생하는 GC spike 및 frame drop 문제를 방지함.

Editor Supports

dependency graph를 관리하고 시각화하기 위한 직관적인 Inspector 도구를 제공함.

Inspector tooling

커스텀 Editor 스크립트가 MasterInstaller, SceneInstaller, ObjectInstaller inspector를 구동함
(registry refresh 버튼, 의존성 시각화, 읽기 전용 [Inject] drawer, optional 필드 색상 표기).

의존성 목록은 잘리지 않음 — 목록이 길다는 것은 UI 노이즈가 아니라 아키텍처 신호로 취급됨.

런타임 ContextMenu 항목: Bake Dependencies (ObjectInstaller), Refresh Global Registry (MasterInstaller),
Refresh Scene Registry (SceneInstaller) — inspector 워크플로와 동일한 동작.

Dependency Graph (UNInjectGraphWindow)

메뉴: Window > UNInject > Dependency Graph

클래스: UNInjectGraphWindow — 현재 editor 상태 (저장된 asset 아님)에 대한 GraphView (UI Toolkit)를 빌드함.

표시 항목

툴바: Refresh 는 로드된 어셈블리와 scene 컴포넌트를 재스캔함 (registry refresh 또는 코드 변경 후 사용).

Inject target의 어셈블리 스캔은 다른 진단과 동일한 ShouldSkipAssembly 정책을 사용하여 프레임워크 어셈블리를 무시함.

Bake Validator (UNInjectBakeValidator)

메뉴: Window > UNInject > Validate Bake

클래스: UNInjectBakeValidator — IPreprocessBuildWithReport (callbackOrder == 0) 를 구현하므로, 각 player build 전에 자동으로도 실행됨.

알고리즘 요약

1. 로드된 game 어셈블리에서 non-optional [GlobalInject] / [SceneInject] 필드를 스캔함.
   • 키 없는 필드는 field.FieldType 을 기여함.
   • Named 필드는 RegistryKey(field.FieldType, id) 를 기여함 (키 없는 패스와 혼용되지 않음).
2. EditorBuildSettings 에 활성화된 각 scene에 대해 additively 열고 (또는 이미 열린 scene 사용),
   SerializedObject 를 통해 MasterInstaller._globalReferrals / SceneInstaller._sceneReferrals 를 읽어 커버되는 concrete 및 abstract/interface 키를 표시함 (런타임 RegisterTypeMappings widening을 반영).
3. baked 리스트에 매칭 referral이 없는 필수 inject마다 Debug.LogError 를 출력함.

결과

• 기본: 에러가 로그되고 빌드는 계속됨 (strict mode 미적용 시).
• UNINJECT_STRICT_BUILD: 검증 에러 발생 시 BuildFailedException 을 throw하고 빌드를 중단함.

메뉴 커맨드는 DisplayDialog 요약을 표시하며; RunValidation() 은 public static 이므로 CI나 커스텀 editor 버튼에서
동일 검사를 호출할 수 있음.

Play mode guards (editor-only)

두 가드는 독립적 hook이며, 동일한 Play 진입에서 모두 발동될 수 있음.

Scripting define symbols (선택적 툴링)

Profiler public API (symbol이 설정된 경우에만): RecordInjection(Type, double) (TryInjectTarget 에서 호출),
GetStats(), PrintReport(), Reset().

Common Editor Warnings

Empty global registry (Play)
[MasterInstaller] Global registry is empty... — Refresh Global Registry 실행 필요. (MasterInstallerPlayModeGuard)

Missing partial (Play)
[UNInject] ... Expression Tree fallback ... — IL2CPP 전에 표시된 타입에 partial 추가 필요. (UNInjectFallbackGuard)

참고 및 향후 업데이트 방향성

현재 지원하는 컴파일러

IL2CPP / AOT 환경을 공식 지원함.

Roslyn Source Generator가 생성한 코드는 Expression.Compile()을 사용하지 않으므로
모든 AOT 플랫폼(iOS, 콘솔 등)에서 안전하게 동작함.

partial 선언이 없는 타입에 한해 Expression Tree 폴백이 적용되며,
이 경우 UNInjectFallbackGuard가 Play 진입 시 명시적으로 경고를 출력함.

릴리즈 브랜치에서는 UNINJECT_STRICT_BUILD 를 활성화하여,
EditorBuildSettings scene에 serialized registry 리스트에 없는 referral을 참조하는 consumer가 있을 때 빌드가 실패하도록 설정할 것.

──────────────────────────────────────────────────────────────────────
1.1.0 — IL2CPP 완전 지원 (릴리즈 완료)
──────────────────────────────────────────────────────────────────────
Roslyn Source Generator 도입. partial 클래스를 통한 IL2CPP 안전 setter 자동 생성.
UNInjectFallbackGuard 추가. Inspector Optional 3단계 표기. 의존성 전체 목록 표시.

ALL PASSED  (24 + 51 tests)

──────────────────────────────────────────────────────────────────────
1.1.1 — 내부 무결성 강화 (릴리즈 완료)
──────────────────────────────────────────────────────────────────────
공개 API 변경 없음. 동작 결과 변경 없음.
모든 개선은 구조적 견고성과 테스트 커버리지 확보에 집중된 내부 작업임.

InstallerRegistryHelper 도입 (신규 internal 클래스)
  RegisterTypeMappings / IsMappableAbstraction / TryAdd 를
  MasterInstaller, SceneInstaller 양쪽에서 추출하여 단일 헬퍼로 통합.
  정책 변경 시 한 곳만 수정하면 됨.

Safety Net 방어 강화 — MasterInstaller.Resolve()
  기존: 캐시 미스 시마다 _globalReferrals 전체 순회 무조건 실행.
  개선: armed/disarmed 패턴 (_safetyNetArmed) 도입.
  레지스트리 빌드 사이클당 복구 시도 1회 제한, 명시적 리빌드 시 재무장.
  무장 해제 후 미스는 Dictionary 조회 + bool 체크만으로 처리됨.

어셈블리 격리 — 3개 독립 asmdef 단위
  UNInject.Runtime / UNInject.Editor / UNInject.Tests.EditMode
  에디터 코드가 플레이어 빌드에서 구조적으로 제외됨.

EditMode 단위 테스트 43개 신규 추가
  InstallerRegistryHelper (18개): 필터 정책, 충돌/null 처리, 매핑 경로.
  TypeDataCache (25개): 필드 수집, 캐시 동일성, setter 쓰기 검증, Warmup, null 방어.

정적 캐시 오염 수정
  HasGeneratedPlan 테스트가 실행 순서에 따라 비결정론적으로 실패하던 문제 해소.
  읽기 대상과 쓰기 대상을 센티넬 타입으로 구조적으로 분리함.

ALL PASSED  (43 EditMode 단위 테스트)

──────────────────────────────────────────────────────────────────────
2.1.0 — Scope/Lifetime 아키텍처 완성 (릴리즈 완료)
──────────────────────────────────────────────────────────────────────
IScope 인터페이스 도입 (MasterInstaller / SceneInstaller / ObjectInstaller 공통 계약).

Pure C# service layer:
  IScope.Create<T>() — 생성자 주입 + 필드 주입 + Tickable 등록 통합 경로.
  [InjectConstructor] attribute 및 생성자 파라미터 [GlobalInject] / [SceneInject] 지원.
  IScopeDestroyable / ITickable / IFixedTickable / ILateTickable 인터페이스 추가.
  IPoolInjectionTarget (OnPoolGet / OnPoolRelease) 및 풀링 API 추가.

Named bindings — RegistryKey = (Type, Id) 구조로 전환.
  [Referral("id")] / [SceneReferral("id")] / [GlobalInject("id")] / [SceneInject("id")] 지원.

SceneExitPolicy (Clear / Preserve) — SceneInstaller 언로드 동작 정책 제어.

SpawnInjected 오버로드 확장 (GameObject / MonoBehaviour, 위치/부모 지정 변형).
ReleaseTargetToPool — 풀 반환 시 inject 필드 자동 null 처리.

Editor tooling 확장:
  UNInjectGraphWindow — Dependency Graph (GraphView, UI Toolkit).
  UNInjectBakeValidator — IPreprocessBuildWithReport 기반 빌드 전 자동 검증.
  UNINJECT_STRICT_BUILD / UNINJECT_PROFILING scripting define symbol 추가.
  UNInjectProfiler — 타입별 주입 비용 Stopwatch 측정 (UNINJECT_PROFILING 시).

PowerPool은 Unity를 위한 고성능 오브젝트 풀링 프레임워크임. zero-allocation runtime, O(1) 반환 복잡도,
그리고 메모리 안전 라이프사이클 제어를 목표로 설계되었음.

스택 기반 빌더 패턴, 버전 기반 안전 검증, 그리고 캐시 친화적 데이터 구조를 결합하여
PowerPool은 기존 풀링 구현에서 흔히 발생하는 GC 비용이나 런타임 조회 오버헤드 없이 매우 효율적인 객체 생성을 처리.

단순히 오브젝트를 enable/disable 하는 기존 풀링 시스템과 달리 PowerPool은 성능, 메모리 안정성, 개발 편의성을 중심으로
설계된 완전한 라이프사이클 아키텍처를 제공함.

https://github.com/NightWish-0827/PowerPool.git?path=/com.nightwishlab.powerpool

UPM Add package from git URL

Table of Contents

• Core Features

• API Reference & Usage

• Lifecycle & Internal Architecture

• Telemetry & Runtime Statistics

• Performance Comparison

• Editor Supports

• Editor Case

• 마치며

Core Features

Zero Allocation Fluent Builder

PowerPool은 ref struct 기반의 스택 할당 빌더 패턴을 도입했음.

이를 통해 위치, 회전, 부모 Transform, 초기화 콜백 등의 스폰 설정을 fluent API 형태로 구성할 수 있음.

이 과정에서 힙 할당이 전혀 발생하지 않음.

GC-Free Runtime Operation

객체 Rent 및 Return 연산은 완전히 allocation-free로 동작함.

반환 핸들은 경량 구조체인 readonly struct PoolHandle<T>로 구현되어 있음.

이를 통해 풀링 과정에서 GC 스파이크가 발생하지 않도록 보장함.

O(1) Return Complexity

일반적인 풀링 시스템은 객체 반환 시 어떤 풀에 속한 객체인지 판단하기 위해 Dictionary 조회가 필요함.

PowerPool은 이러한 오버헤드를 제거했음.

각 PoolHandle<T>는 내부적으로 자신을 생성한 Pool 인스턴스에 대한 직접 참조를 보유함.

따라서 객체 반환은 항상 O(1) 상수 시간으로 수행됨.

• 해시 조회 없음
• 타입 검사 없음
• 런타임 풀 탐색 없음

Anti-Zombie Object Protection

풀링 시스템에서 가장 위험한 버그 중 하나는 Zombie Reference 문제임.

이는 이미 풀로 반환된 객체를 코드가 계속 접근하는 상황을 의미함.

PowerPool은 generation 기반 검증 시스템을 통해 이 문제를 원천적으로 방지함.

각 풀링 객체는 PowerPoolTracker를 통해 단조 증가하는 Version 값을 관리함.

핸들이 발급될 때

• 현재 Version이 핸들에 복사됨
• 반환 시 Tracker Version이 증가함

이미 반환된 핸들이 접근을 시도하면

• Version 불일치가 감지됨
• 해당 연산이 차단됨
• 설정에 따라 Warning 또는 Exception이 발생함

Cache-Friendly Parallel Array Architecture

PowerPoolCore는 내부적으로 Parallel Array 구조를 사용함.

_items[]      → 풀링된 컴포넌트
_trackers[]   → 라이프사이클 트래커

두 배열은 동일한 인덱스를 공유함.

이를 통해 매우 빠른 조회와 캐시 친화적인 반복 처리가 가능함.

이 데이터 지향 구조(Data-Oriented Structure)는 일반적인 OOP 기반 풀링 구현보다 훨씬 높은 성능을 제공함.

Zero Runtime GetComponent Overhead

IPoolCleanable 인터페이스를 구현한 컴포넌트는 객체 생성 시 단 한 번만 캐싱됨.

GetComponentsInChildren<IPoolCleanable>(true)

이 과정은 prewarm / instantiate 시점에만 수행됨.

객체가 풀로 반환될 때는

OnReturnToPool()

메서드가 캐싱된 배열을 통해 직접 호출됨.

따라서 런타임에서 추가적인 GetComponent 탐색이 발생하지 않음.

Independent Prefab Pool Isolation

PowerPool은 풀을 구분할 때 컴포넌트 타입 <T>뿐 아니라 Prefab InstanceID도 함께 사용함.

prefab.gameObject.GetInstanceID()

이를 통해 동일한 컴포넌트를 사용하더라도 서로 다른 프리팹은 항상 독립된 풀로 관리됨.

예시

SlimePrefab  → Pool A
OrcPrefab    → Pool B

두 프리팹 모두 Monster 스크립트를 사용하더라도 풀은 완전히 분리되어 동작함.

Ghost Object Tracking

풀링 객체가 외부에서 Destroy() 호출로 제거되거나 씬 전환 과정에서 파괴될 경우

PowerPoolTracker가 이를 자동으로 감지함.

OnUnexpectedDestroyed

이를 통해 개발자는

• 라이프사이클 오류
• 메모리 누수 가능성
• 풀 상태 손상

등의 문제를 빠르게 파악할 수 있음.

API Reference & Usage

PowerPool API는 세 가지 핵심 개념을 중심으로 설계되었음.

• Fluent Spawn Builder
• Handle 기반 라이프사이클 관리
• 안전하고 결정적인 객체 반환

기존 풀링 API가 단순한 static 함수 집합을 제공하는 것과 달리 PowerPool은 구조화된 스폰 파이프라인을 제공함.

이를 통해 객체 생성 과정이

• 명확하고
• 안전하며
• 할당 없이 동작하도록 설계되었음

Fluent Spawn Builder

객체는 fluent builder 파이프라인을 통해 생성됨.

빌더는 ref struct로 구현되어 있음.

이는 다음을 보장함.

• 스택 전용 할당
• Zero GC Pressure
• 즉시 실행

ref struct는 저장하거나 캡처할 수 없기 때문에 API 사용 패턴 역시 자연스럽게 one-shot 형태로 유도됨.

PoolHandle<MyComponent> handle =
    PowerPool.Spawn(myPrefab)
        .At(position, rotation)
        .Under(parentTransform)
        .Rent();

이 구조는 가독성을 유지하면서도 중간 힙 할당을 완전히 제거함.

Spawn Configuration Pipeline

최종 Rent() 호출 이전에 빌더를 통해 다양한 스폰 설정을 구성할 수 있음.

Transform Placement

var handle = PowerPool.Spawn(prefab)
    .At(spawnPosition, spawnRotation)
    .Under(parentTransform)
    .Rent();

지원되는 Transform 설정

• spawn position
• spawn rotation
• optional parent transform

Initialization Callbacks

With() 또는 WithState()를 통해 스폰 시점에 추가적인 상태 값을 전달할 수 있음.

var handle = PowerPool.Spawn(prefab)
    .At(pos, rot)
    .WithState(
        state: new SpawnState(color, impulse),
        onInitialize: static (item, s) =>
        {
            var st = (SpawnState)s;
            item.Init(st.Color, st.Impulse);
        })
    .Rent();

이 패턴을 통해

• 추가 컴포넌트 탐색 없이
• 글로벌 상태에 의존하지 않고

객체 초기화 데이터를 직접 주입할 수 있음.

콜백을 static으로 선언할 경우 클로저 할당 또한 발생하지 않음.

Handle-Based Lifecycle

PowerPool은 객체를 직접 반환하지 않고 PoolHandle<T>를 반환함.

PoolHandle<MyComponent> handle = PowerPool.Spawn(prefab).Rent();

핸들에는 다음 정보가 포함됨.

• source pool 참조
• 객체의 tracker
• 발급 시점의 version

이를 통해 시스템은 다음과 같은 잘못된 사용을 감지할 수 있음.

• double return
• zombie reference
• stale handle

Returning Objects

객체 반환은 여러 방식으로 수행할 수 있음.

Explicit Return

PowerPool.Return(ref handle);

ref 반환 패턴을 사용하여 반환 즉시 핸들이 무효화되도록 보장함.

Instance Method Return

handle.Return();

핸들이 지역 변수로 존재할 때 가장 일반적으로 사용되는 방식임.

Scoped Lifetime (using)

핸들은 IDisposable을 구현하고 있음.

using (var fx = PowerPool.Spawn(effectPrefab).Rent())
{
    // temporary effect
}

스코프가 종료되면 객체는 자동으로 풀로 반환됨.

Resetting Objects with IPoolCleanable

객체는 IPoolCleanable 인터페이스를 구현하여 자신의 초기화 로직을 정의할 수 있음.

public class MyEntity : MonoBehaviour, IPoolCleanable
{
    public void OnReturnToPool()
    {
        // Reset state
        // Clear buffs
        // Restore HP
    }
}

PowerPool은 반환 과정에서 OnReturnToPool()을 자동 호출함.

이 과정에서 런타임 비용을 줄이기 위해 필요한 컴포넌트는 객체 생성 시점에 한 번만 캐싱됨.

Prewarming and Pool Registration

풀은 최초 Spawn 시 Lazy Initialization으로 생성될 수 있음.

하지만 일반적으로는 초기화 단계에서 Prewarm을 수행하는 것이 권장됨.

PowerPool.Register(prefab, initialCapacity, poolRoot);

선택 파라미터를 통해 다음을 설정할 수 있음.

• initial capacity
• pool root transform
• maximum pool size
• overflow policy

예시

PowerPool.Register(
    prefab,
    initialCapacity: 32,
    poolRoot: poolTransform,
    maxPoolSize: 256,
    overflowPolicy: PowerPoolOverflowPolicy.Expand);

Prewarm을 통해 런타임 Instantiate로 인한 프레임 스파이크를 방지할 수 있음.

Runtime Statistics

PowerPool은 PowerPoolStats를 통해 상세한 런타임 통계를 제공함.

if (PowerPool.TryGetStats(prefab, out var stats))
{
    Debug.Log(
        $"Created={stats.TotalCreated}, " +
        $"InPool={stats.InPool}, " +
        $"Active={stats.ActiveEstimated}");
}

제공되는 통계

• 생성된 총 객체 수
• 활성 객체 수
• 풀 내부 객체 수
• rent / return 호출 횟수
• pool capacity
• expansion 이벤트
• overflow 정책

이를 통해 개발자는 런타임 풀 동작과 메모리 사용량을 분석할 수 있음.

Asynchronous / Delayed Return Patterns

코루틴, 타이머, async 로직 등 지연 반환이 필요한 경우 핸들을 안전하게 저장할 수 있음.

var handle = PowerPool.Spawn(prefab).Rent();

StartCoroutine(ReturnLater(handle, 2f));

코루틴 내부

PowerPool.Return(ref handle);

핸들은 내부적으로 version 및 ownership 정보를 추적하기 때문에 잘못된 반환이나 중복 반환 상황에서도 시스템 안전성이
유지됨.

In Practice

PowerPool은 의도적으로 유연한 설계를 채택했음.

다음과 같은 다양한 상황에서 활용 가능함.

• 수동 라이프사이클 관리
• scoped temporary objects
• coroutine 기반 이펙트
• 고빈도 projectile 스폰
• 대규모 엔티티 시스템

Fluent Builder와 Handle 시스템은 성능, 안정성, API 가독성을 동시에 유지하도록 설계되었음.

Lifecycle & Internal Architecture

PowerPool은 구조화된 런타임 파이프라인을 통해 객체 라이프사이클을 관리함.

Pool Initialization
-------------------
PowerPool.Spawn(prefab)
→ Locate or create pool instance
→ Lazy initialization if necessary

Prewarm Phase
-------------
EnsureCapacity / PrewarmAdditional
→ Allocate pool memory ahead of time
→ Prevent runtime allocation spikes

Rent Phase
----------
PoolBuilder<T>.Rent()
→ Retrieve inactive object
→ Assign tracker version
→ Activate object

Return Phase
------------
PoolHandle.Return()
→ Version validation
→ Call IPoolCleanable reset hooks
→ Disable and return to pool

Overflow Handling
-----------------
When pool reaches MaxPoolSize:

Expand
→ dynamically allocate additional objects

DestroyOnReturn
→ destroy objects when returned if capacity exceeded

Telemetry & Runtime Statistics

PowerPool은 PowerPoolStats 구조체를 통해 런타임 텔레메트리를 제공함.

개발자는 다음 정보를 모니터링할 수 있음.

• 생성된 총 객체 수
• 현재 풀 내부 객체 수
• 씬에서 활성 상태인 객체 수
• 예상치 못한 파괴 이벤트
• 런타임 풀 확장 횟수

이를 통해 팀은 메모리 사용량과 풀 동작을 실시간으로 분석할 수 있음.

Performance Comparison

가비지 컬렉션 할당 비용 제거

PowerPool은 ref struct 기반의 스택 할당 빌더 패턴을 도입하여
객체 스폰 설정 시 힙 할당이 전혀 발생하지 않음.

객체의 Rent 및 Return 연산 또한 완전히 allocation-free로 동작하며,
이를 통해 풀링 과정에서 발생하는 GC 스파이크를 원천 방지함.

O(1) 반환 복잡도

일반적인 풀링 시스템은 객체 반환 시 어떤 풀에 속한 객체인지 찾기 위해
Dictionary 조회 등의 추가적인 런타임 탐색이 필요.

반면 PowerPool은 각 PoolHandle<T> 이 자신을 생성한 Pool 인스턴스에 대한 직접 참조를 보유하고 있어
해시 조회, 타입 검사, 런타임 풀 탐색이 일절 필요 없는 O(1) 상수 시간으로 반환이 수행됨.

런타임 Resolve (Getter) 제거

IPoolCleanable 인터페이스로 구현한 컴포넌트는 객체 생성 시점에서
단 한 번만 캐싱

객체가 풀로 반환될 때 캐싱된 배열을 통해 직접 OnReturnToPool() 메서드가 호출되므로, 런타임 중에 추가적인 GetComponent 가 요구되지 않음.

Editor Supports

에디터 레벨에서 Tracker Window를 제공함. 이를 통해 객체 상태를 추적할 수 있음.

Editor Case

Editor에서 PlayMode 테스트를 수행할 경우 다음과 같은 오류 또는 경고가 발생할 수 있음.

[Powerful] An object that failed to pass through the pool was forcibly destroyed.

LogWarning

[Powerful] Handle is invalid or has already been returned. (Tracer not found (default handle or external manipulation)

LogError

이는 Editor Stop 호출 시 발생하는 노이즈 로그이며 무시해도 안전함.

다만 Dev Build 또는 정상 종료 상황에서 해당 메시지가 발생한다면
설계된 Pool Manager 또는 객체 반환 사이클 설계를 잘못했음을 의미함

마치며

굉장히 오랫동안 사용하던 패턴을 SDK화 해서 제공하게 되었는데…. ‘LeanPool’ 이라는 Pool SDK 신뢰도가 굉장히
높다길래 제작해봄.

WEBGL, 기타 프로젝트에서 TC 는 정상적으로 진행했으며,
내부에 예제도 충분히 구현되어있음.

당장 Prefab에 묵직한 걸 넣고, Profiler 켜서 커브를 확인해보자

결과적으로, 이 SDK는 Unity 오브젝트 풀링을
안전하고, 결정적이며, 극도로 빠르게 만들기 위해 설계된 런타임 시스템임.

Zero-allocation 패턴, Generation 기반 안전성 검증, 캐시 최적화 데이터 구조를 결합하여

해당 SDK는 고부하 런타임 환경에서도 안정적으로 동작하는 풀링 아키텍처를 제공함.

Current Version : 2.0.0

UNFinder는 Unity를 위한 고성능 조회 및 쿼리 프레임워크.
이름 기반 조회(GameObject.Find 스타일), 컴포넌트 접근,
타입/태그 기반 필터링을 결정적 런타임 동작으로 가속함.

UNFinder는 FNV-1a 해싱, 순수 C# 버킷, 풀링 기반 쿼리 파이프라인을 결합해
네이티브 브리지 비용과 런타임 할당을 줄임.
또한 이름/태그/컴포넌트 변경 시 캐시 무결성을 유지하도록 라이프사이클 안전 API를 제공함.

빌드 과정에서 SDK는 숨겨진 트래커와 씬 레지스트리를 자동 삽입함.
런타임에서는 오브젝트를 이름/타입/태그 버킷으로 인덱싱하여 전체 씬 스캔 없이 조회함.

https://github.com/NightWish-0827/UNFinder.git?path=/com.nightwishlab.unfinder
UPM Add package from git URL

Table of Contents

• Core Features
• API Reference \& Usage
• Lifecycle \& Callback Mechanism
• Operational Notes
• Performance Comparison

Core Features

O(1) 이름 조회 경로

UN.Find(name)은 해시된 이름 버킷을 먼저 조회하고,
필요할 때만 네이티브 조회를 1회 지연 수행하여 캐시에 기록함.
캐시 히트 경로는 순수 C# 메모리에서 동작함.

쿼리 기반 타입/태그 필터링

UN.Query()는 With, Without, Tag, Scene 필터를 지원함.
엔진은 후보 버킷 중 가장 작은 집합을 기준으로 순회해 탐색 비용을 줄임.

저할당 런타임

UNFinder는 쿼리 빌더와 쿼리 결과를 풀링함.
프레임 반복 호출이 많은 핫패스에서 불필요한 임시 할당을 줄임.

라이프사이클 안전 캐시 무결성

전용 API(Rename, SetTag, AddComponent, NotifyComponentChanged, Destroy)를 통해
실제 Unity 오브젝트 상태와 인덱스를 동기화함.

빌드 타임 오토 베이킹

빌드 처리 시 [UNBake]가 지정된 컴포넌트를 하나 이상 가진 오브젝트에
숨김 트래커를 자동 부착함.

API Reference & Usage

API는 Unity에서 자주 사용하는 조회 패턴을 그대로 확장할 수 있도록 설계되었음.

Object & Component Lookup

// GameObject.Find("Player") 대체
GameObject player = UN.Find("Player");

// 컴포넌트 조회 + 캐싱
PlayerController controller = UN.FindComponent<PlayerController>("Player");

Scene-Aware Lookup

Additive 씬 환경처럼 이름/타입 충돌이 가능한 구조에서 유용함.

using UnityEngine.SceneManagement;

Scene combatScene = SceneManager.GetSceneByName("Combat");
GameObject boss = UN.FindInScene(combatScene, "Boss");
BossController bossCtrl = UN.FindComponentInScene<BossController>(combatScene, "Boss");

Dynamic Instantiation & Destroy

생성된 인스턴스는 즉시 등록되며 기본 "(Clone)" 접미사는 제거됨.
컴포넌트 오버로드도 지원함.

GameObject enemyInstance =
    UN.Instantiate(enemyPrefab, spawnPos, Quaternion.identity);

EnemyAI ai =
    UN.Instantiate<EnemyAI>(enemyAIPrefab, spawnPos, Quaternion.identity);

// Destroy 래퍼로 라이프사이클 동작을 명시적으로 유지
UN.Destroy(enemyInstance);
UN.Destroy(ai);

Rename, Binding, and State Sync

인덱스에 영향을 주는 가변 상태는 UN API를 통해 변경하는 것을 권장함.

// 수동 등록
UN.Bind(dynamicObject, "DynamicBoss");

// 이름 캐시 무결성을 유지하며 이름 변경
UN.Rename(dynamicObject, "DynamicBoss_Phase2");

// 태그 인덱스를 동기화하며 태그 변경
UN.SetTag(dynamicObject, "Respawn");

// 타입 인덱스 재빌드를 포함한 안전한 컴포넌트 추가
UN.AddComponent<FrozenState>(dynamicObject);

// Unity 기본 API로 컴포넌트를 바꿨다면 UNFinder에 변경 통지
UN.NotifyComponentChanged(dynamicObject);

Fluent Query API

using var result = UN.Query()
    .WithComponent<IDamageable>()
    .WithoutComponent<IFrozen>()
    .WithTag("Enemy")
    .Execute();

foreach (var go in result)
{
    // 결과 오브젝트 사용
}

추가 종료 연산:

// 씬 필터
using var sceneOnly = UN.Query()
    .WithComponent<IEnemy>()
    .WithScene(combatScene)
    .Execute();

// 콜백 순회
UN.Query()
  .WithComponent<ITickable>()
  .ForEach(go => go.GetComponent<ITickable>().Tick(Time.deltaTime));

// 조기 종료
bool completed = UN.Query()
    .WithComponent<IEnemy>()
    .TryForEach(go =>
    {
        if (!go.activeInHierarchy) return true; // continue
        return false;                            // break
    });

// 첫 번째 매치만 빠르게 조회
GameObject firstEnemy = UN.Query().WithComponent<IEnemy>().First();

Cached Query Mode

캐시 모드는 동일 프레임에서 동일 지문(fingerprint)의 쿼리 결과를 재사용함.
프레임 경계 또는 오브젝트 그래프 변경 시 자동 무효화됨.

using var result = UN.Query()
    .WithComponent<IDamageable>()
    .WithScene(combatScene)
    .Cached()
    .Execute();

Cached()는 의도적으로 Execute()만 노출하는 UNCachedQuery를 반환함.

Lifecycle & Callback Mechanism

UNFinder는 Unity의 빌드/런타임 콜백과 트래커 라이프사이클 훅을 통해 자동 동기화됨.

Build Phase
-----------
IProcessSceneWithReport.OnProcessScene
→ 씬 루트 스캔
→ [UNBake] 대상에 숨김 UNTracker 부착
→ 베이크된 트래커 참조를 가진 ~UN_AutoRegistry 생성

Bootstrapping Phase
-------------------
DefaultExecutionOrder(-32000)
→ UNSceneRegistry.Awake()
→ 베이크된 트래커 초기화
→ 이름/타입/태그 인덱스 등록

Runtime Mutation
----------------
UN.Bind / UN.Rename / UN.SetTag / UN.AddComponent / UN.Destroy
→ 캐시와 인덱스 동기화 유지

Destroy Phase
-------------
UNTracker.OnDestroy()
→ 이름/타입/태그 버킷에서 제거
→ Stale 참조 방지

Operational Notes

메인 스레드 전용

UNFinder API는 Unity 메인 스레드 사용을 전제로 설계되었음.
Worker Thread 또는 Job에서 호출하지 말 것.

가변 인덱스 상태는 UN API 우선

트래킹된 오브젝트에서 go.name, go.tag를 직접 수정하지 않는 것을 권장함.
UN.Rename, UN.SetTag를 사용하면 쿼리/인덱스 정합성이 유지됨.

Query 결과는 using 사용 권장

UNQueryResult와 UNCachedQuery는 풀링/해제 가능한 타입.
즉시 반환되도록 using을 사용하는 것을 권장함.

using var result = UN.Query().WithComponent<IEnemy>().Execute();

메모리 트리밍 (선택)

대량 파괴 웨이브나 씬 전환 후 버킷 메모리를 회수할 수 있음.

int trimmedBuckets = UN.TrimTypeBuckets();

Performance Comparison

씬 규모가 커질수록 네이티브 조회 API는 계층 순회 비용이 커지는 경향이 있음.
UNFinder는 인덱스 기반 조회와 버킷 기반 후보 축소로 전체 씬 스캔을 피함.

Default Unity API

• 네이티브 C++ 브리지 및 계층 순회 비용
• 반복 호출이 누적될수록 총 순회 오버헤드 증가
• 필터 중심 로직에서 씬 전체 재탐색이 반복됨

UNFinder SDK

• 해시 기반 C# 이름 버킷 조회
• 인덱스 기반 타입/태그 쿼리
• 동일 프레임 재요청에 대한 쿼리 캐시 모드
• 풀 기반 쿼리/결과 객체로 예측 가능한 런타임 동작

마치며

UNFinder는 조회 중심 게임플레이 코드를 인덱스 기반 런타임 워크플로우로 전환함.
기존 사용 패턴을 유지하면서도 더 결정적이고 확장 가능한 접근 경로를 제공함.

화제의 D2G 장르. 독일 개발사 Lessmore의 Forge Master 게임을 클로닝 했습니다.

리소스는 Forge Master 원작을 Dotpeek 활용하여 분해 후 사용했습니다.

이를 상업적으로 활용한 사례가 일체 없음을 밝힙니다.

Forge Master

Are you ready for this adventure?.

https://play.google.com/store/apps/details?id=com.hariwn.legendofcivilizations&hl=en

Screen Shots & Videos

My Package List

Open Source SDK List

Test Device

간단한 후기

잉여 시간에 SDK TC 진행겸 제작하게 된 게임입니다.

원작의 리소스가 단순함을 넘어, 특이점이 온 수준의 표현 억제가 특징입니다.
하지만 의외로 게임 자체가 중독성이 매우 강하여, 개발 하면서도 제법 즐겁게 진행했습니다.

주식회사 111% 재직 중 개발을 진행했습니다.

단순 영상만을 포트폴리오 및 이력서에 게시하며, 코드 레벨 및 런타임의 구조 공개가 이뤄지지 않습니다.

이를 상업적으로 활용한 사례가 일체 없음을 밝힙니다.

Screen Shots & Videos

업무

해당 프로젝트에서 단독 클라이언트 프로그래머를 담당했습니다.

• 아트 리소스를 제외한 모든 업무를 수행했습니다.

간단한 후기

정말 간만에 쉐이더를 극한으로 다뤄가며 제작한 프로젝트입니다.

개인적으로 이러한 아트 스타일을 굉장히 선호하기 때문에, 최대한 아름답게 제작하고 싶었습니다.

본디 모바일에서는 투명 쉐이더나 굴절은 거의 회피하며 제작을 진행하지만,
최적화를 극한의 극한까지 하여.. 10장 가까이 겹쳐 사용했습니다.

성능은 로우 ~ 미드 티어 기기에서 안정적으로 60프레임이 보장되었습니다.

짧은 기간이었지만, 수려한 아트 리소스 작업 해주신 팀원분께 무한한 감사를 드립니다. 🥹

청강 크로니클 전시회에 출품하기 위해 개발이 진행되었습니다.

3개의 주무기, 각종 스킬과 증강 및 아이템을 활용하여 전투하는 2D 멀티 액션 대전 게임입니다.
각 무기 및 스테이지 마다 고유한 기믹과 스킬이 존재하며, 20개가 넘는 증강 시스템을 통해 색다른 게임성을 자랑합니다.

꼬마 해적 이라는 핵심 컨셉을 통해 귀여운 캐릭터들과, 개성있는 여러 스테이지를 통해 캐주얼한 세계관으로 표현되었습니다.

독특한 특징으로는 ‘라운드 패자에게 증강의 기회가 주어진다.’ 라는 게임의 룰을 통해 플레이 방식이 정형화 되지 않고,
매 라운드마다 다른 플레이 경험을 즐길 수 있습니다.

레거시 Fusion 2.0 의 라이브 서버가 다소 불안정한 탓에 원활하진 않으나, 해당 링크에서 다운로드 및 플레이가 가능합니다.

아르르! 야르르! | STOVE 스토어

바다에서, 동굴에서 펼쳐지는 쌍둥이 해적의 2D 하이퍼 캐주얼 멀티 슈팅 대전 게임 입니다.

https://store.onstove.com/games/4518

Screen Shots & Videos

업무

해당 프로젝트에서 PD를 담당했습니다.

• 프로젝트 코어 설계
• 스테이지 싱커 구현
• 각종 스테이지 기믹 구현
• 각종 쉐이더 및 스테이지 이펙트, 파티클 구현
• PC 전반 구현
• 서버 동기화 및 네트워크 인자 안정화 & 최적화
• 아이템 및 각종 강화 요소 구현

• 사운드 디자인 및 제작

• 작업 지시, 작업 보고 등의 PD 대외 업무

간단한 후기

14명 모두가 3개월이라는 짧은 개발 기간 동안, 최대한의 퍼포먼스를 보여줬다고 생각되는 이상적인 게임 개발이었습니다.

즐거웠습니다. 감사합니다.

Farewell 언덕 위의 개들

바다 속을 배경으로 하는 동양풍 3D 액션 어드벤쳐 게임입니다.

기본 3 마리의 소환수 친구들과 본인 고유의 능력을 활용해 적들을 해치우고 나아가며,
추가 소환수 친구들을 만나거나 필요한 속성의 소환수를 엔트리에서 조합하여, 최종 보스까지 클리어하는 스토리 게임입니다.

용궁 선녀 라는 동양풍 컨셉과, 심해 바다를 표현하기 위한 섬세한 TA 요소들이 잘 어우러져 감도 높은 환경이 구축되었습니다.

Screen Shots & Videos

업무

클라이언트 프로그래머, 사운드 디자이너, (인계) PD를 담당했습니다.

• 프로젝트 메인 코어 설계 및 구현
• PC 3D 물리 모듈 설계 및 구현
• 인 게임 FSM
• 보스 패턴 에디터 구현
• 사운드 디자인 및 제작
• FMOD 에디터 개발

• 중간 보스 전반 개발

• PD 인수인계 이후 기타 대외 업무

간단한 후기

각 게임 요소 최적화와 사운드 디자인에 매우 많은 시간을 들인 게임입니다.

특히, 시놉시스를 살리기 위한 사운드를 제작하기 매우 어려웠던 기억이 납니다.
미들웨어를 폭력적으로 다뤄야 할 만큼 난이도 있는 오퍼가 매 주차마다 추가되었던…

이제는 그 일련의 과정마저 추억으로 느껴질 만큼 숱한 경험을 했지만.. 이 게임이 가장 강력한 적이었던 것 같습니다…

즐거웠습니다. 감사합니다.

Farewell 바다의 보배

국가 지원 사업인 XR 캡스톤 프로젝트에 출품하기 위해 개발이 진행되었습니다.

그래피티를 통해 스테이지를 클리어 하는 굉장히 독특한 2D 퍼즐 플랫포머 게임입니다.

지옥이라는 환경에서 엄숙하게 행동하지 못하고 그래피티를 마구 그리는 주인공. 공주 ‘루시’와,
이를 막으려는 하인, 하녀 그리고 아버지와의 한 판 승부라는 귀엽고 흥미로운 시놉시스를 표현하였습니다.

왕과 공주의 승부라는 컨셉 덕분에 해당 게임에는 독특하게도, 공격 이라는 개념이 존재하지 않습니다.
넉백과 색칠만으로 서로를 골려먹는 유쾌한 퍼즐 게임입니다.

Screen Shots & Videos

업무

클라이언트 프로그래머, 사운드 디자이너를 담당했습니다.

• 프로젝트 코어 설계
• 각종 인 게임 요소 제작
• 인 게임 몬스터 구현
• 사운드 디자인 및 제작
• 사운드 에디터 개발

간단한 후기

색칠을 통해 플랫폼을 만들고,
그래피티를 통해 스테이지의 진행도를 높여 나가는 퍼즐 플랫포머라는 아이디어 자체는 매우 흥미로운 시도였습니다.

다만 스토리 기반 게임을 단기간에 완성해야 했던 프로젝트 특성상,
해당 시스템을 충분히 확장하거나 더 다양한 방식으로 활용해 보지 못한 점은 다소 아쉬움으로 남습니다.

그럼에도 불구하고 프로젝트는 큰 문제 없이 마무리되었으며, 각자의 위치에서 최선을 다한 결과라고 생각합니다.

즐거웠습니다. 감사합니다.

Farewell 어둠의 자식들

리듬에 맞춰서 탄막이 발생하고, 이를 회피하는 2D 리듬 탄막 게임입니다.

Window XP 라는 빈티지한 컨셉에 맞춰 게임의 핵심 요소들이 윈도우 XP의 테마를 따라 제작되었습니다.

버튼이 아닌 커맨드를 통해 설정 및 각종 스테이지를 로드하거나, 각 스테이지를 클리어 할 때 마다 오류가 하나씩 픽스된다는
흥미로운 컨셉을 통해 게임을 표현하였습니다.

리듬에 맞춰 탄막의 패턴 및 탄환이 상태 변화하는 하드코어 Bullet Hell 시스템을 갖고 있습니다.

Screen Shots & Videos

간단한 후기

Matf 심벌에 각종 연산을 추가시켜, 패턴의 구현을 최소한의 라인으로 제작하기 위한 SDK를 제작하며 개발을 병행한 게임입니다.

LinQ 구문과 유사하게 패턴 선언이 가능하도록 해뒀지만,
당시에는 코드레벨 이해도가 다소 부족하여 확장성을 고려하지 않은 SDK로 남게 되었습니다.

FMOD를 사용하여 오디오 이벤트를 구축했는데,
FMOD의 네이티브 언어인 C++ 와 유니티 런타임과의 [A.O.T]를 처음 시도한 프로젝트입니다.
난이도는 있었으나, 구현을 성공하니 효과가 상당했으며. 이를 통해 FMOD를 적극 사용하기 시작했습니다.

2019 당시에는 지금처럼 개발 커뮤니티가 크지도 않고,
이런 SDK들이 제공되지 않았기에 이런 기능을 손수 제작하는 것이 당연했던 시기입니다.

현재는 갖가지 다양한 SDK들과 AI가 발전해서 예전 만큼의 개발 재미도가 높진 않기에, 향수를 부르는 그런 게임입니다..

인디 게임 VVVVVV 의 팬 게임 프로젝트로,
원작의 부족한 UX 개선과 다양한 스테이지 패턴 변경 및 연장 등에 초점을 맞춰 제작하였습니다.

추가적으로, 2018년도 당시에 유행했던 아트 스타일 [네온 빈티지]와, [Hide UI] 등을 사용하여 차별성을 주었습니다.

이를 상업적으로 활용한 사례가 일체 없음을 밝힙니다.

VVVVVV

https://play.google.com/store/apps/details?id=air.com.distractionware.vvvvvvmobile&hl=en

Screen Shots & Videos

간단한 후기

첫 협업 작품입니다.

언어가 안 통하던 영어권 분들 밖에 없던 공식 커뮤니티에서, Git 사용법과 원작 엔진에 대한 많은 가르침을 받았습니다.

원작 엔진은 Direct X 기반의 엔진이었는데, 모바일 포팅이 다소 어려웠던 기억이 납니다.

GUI가 아예 없는 환경에서 개발을 했기 때문에, 코드 자체와 친해질 수 있었던 그런 프로젝트였습니다.