👨‍💻 오늘의 개발 작업

1단계 첫 항목인 캐릭터 컨트롤러부터 시작. 이동은 뱀서 프로젝트 때 익힌 Input System 방식을 재사용했고, 중간에 Sprint 버튼이 뗄 때 반응 안 하는 버그를 실측으로 잡음. 마우스 조준 방향을 어떻게 캐릭터에 반영할지 설계를 두 번 갈아엎었고, 최종적으로는 사진 기반 캐릭터라는 제약에 맞춰 좌우 반전 + 조준 방향값 분리 구조로 정리함.

💡 오늘의 기록

1. Rigidbody2D 기반 이동

뱀서 프로젝트 노트에 이미 Rigidbody2D 기반 이동 패턴이 정리돼 있어서 그대로 재사용. 다만 뱀서는 생존 게임이라 관성 있는 이동(AddForce/MovePosition)이었고, 우리는 PvP 대전이라 반응성이 더 중요하다고 판단해서 velocity 직접 대입 방식으로 바꿈.

private void FixedUpdate()
{
    float currentSpeed = isRunning ? runSpeed : walkSpeed;
    rigid.linearVelocity = inputVec * currentSpeed; // 관성 없이 즉시 반응
}

2. Sprint 릴리즈 버그 — 실측으로 원인 뒤집힘

Shift를 누르면 달리기 상태로 바뀌는데, 떼도 계속 달리기 속도가 유지되는 버그 발생. 처음 세운 가설은 "바인딩에 Press Only 인터랙션이 걸려서 release 이벤트가 안 온다"였는데, 확인해보니 Interactions 필드는 비어있었음.

Input Debugger로 keyboard leftShift raw 입력 자체를 찍어보니 눌림/뗌 둘 다 정상 반응 — 즉 OS/디바이스 레벨은 문제없고, Action Type(Button 확인됨), Player Input Behavior(Send Messages 확인됨), 코드(isRunning = value.isPressed 확인됨)까지 전부 정상으로 보였는데도 버그가 남아있었음.

실측으로 뒤집힌 부분: 예상과 반대로, 인터랙션이 아예 없는 상태가 문제였음. Press 인터랙션을 명시적으로 추가하고 Trigger Behavior를 Press And Release로 지정하니 바로 해결됨. Button 타입 액션이라고 해서 인터랙션 없이도 press/release를 항상 안전하게 보장하진 않는다는 걸 확인함 — 처음 가설과 정반대 결론이라 기록해둠.

Sprint 액션 → Left Shift 바인딩 → Interactions에 Press 추가
→ Trigger Behavior: Press And Release

3. 마우스 조준 설계 — 4방향 스냅 방식을 짰다가 폐기

처음엔 마우스 방향을 4방향(상/하/좌/우)으로 스냅해서 Animator의 Direction(Int) 파라미터로 방향별 스프라이트를 전환하는 구조로 짬 (RPG류에서 흔한 방식). 그런데 캐릭터가 실사 고양이 사진 기반이라는 걸 다시 짚고 나서 이 방식을 폐기함 — 사진은 방향별로 새로 찍을 수 없으니, 4방향 스프라이트 자체를 준비할 방법이 없었음.

대신 몸은 좌우 반전만 하고, 정밀한 조준 각도는 투척 아이템(감자/맛동산)이 캐릭터 주변에서 마우스 방향으로 떠 있는 것으로 표현하기로 설계 변경. 이동 방향과 조준 방향을 완전히 분리해서, 조준 벡터는 AimDirection이라는 public 프로퍼티로 노출해두고 나중에 만들 투척 인디케이터 스크립트가 그대로 가져다 쓰도록 함.

public Vector2 AimDirection { get; private set; } = Vector2.right;

private void UpdateAimDirectionFromMouse()
{
    Vector3 mouseWorldPos = mainCamera.ScreenToWorldPoint(mouseScreenPos);
    mouseWorldPos.z = transform.position.z;
    Vector2 rawDir = (Vector2)mouseWorldPos - (Vector2)transform.position;
    if (rawDir.sqrMagnitude < 0.0001f) return; // 마우스가 겹치면 이전 방향 유지
    AimDirection = rawDir.normalized;
}

4. 좌우 반전 부호가 반대로 나옴 — 원본 이미지 기준 문제

로직 자체는 맞는데 실제로 테스트해보니 고양이가 반대 방향을 보고 있었음. 원인은 원본 고양이 사진이 기본적으로 왼쪽을 보고 있는 상태였는데, 코드는 "기본이 오른쪽"이라고 가정하고 짜여있었던 것. 새 이미지를 뒤집어서 다시 넣는 대신, 조건문 부호만 반대로 바꿔서 해결.

// 원본 사진이 기본적으로 왼쪽을 보고 있어서 조건을 반대로 잡음
spriteRenderer.flipX = AimDirection.x > 0f;

앞으로 스킨(고양이 사진)을 추가할 때마다 전부 같은 기본 방향(왼쪽)으로 통일해서 넣어야 한다는 규칙이 생김. 스킨 수가 늘어나면 캐릭터별 isBaseFacingRight 플래그로 관리하는 방식도 고려 중.

👨‍💻 오늘의 개발 작업

기능 구현은 끝났고, 죽은 코드/중복 로직을 정리하는 작업을 함. 시작할 때 "이 정도면 끝나겠지" 싶었던 게, 파다 보니 확신했던 결론을 두 번 세 번 뒤집는 일이 계속 생겼음. 특히 하이라이트 색상 처리 하나 때문에 ButtonComponent API를 실측까지 해가며 파고든 게 오늘의 메인 이벤트.

💡 오늘의 기록

1. UIBuffIcon 타이머 — 버그라고 확신했다가 철회

SetTimerRepeat으로 등록한 반복 타이머라, remainingSec이 0이 돼도 타이머 자체는 안 멈추는 게 당연해 보였음. "0이 된 뒤에도 Tick이 계속 불려서 낭비 아닌가?" 싶어서 방어 코드(ClearTimer 명시적 호출)를 제안했는데, 로그 + 브레이크포인트로 직접 찍어보니 remainingSec이 0이 되는 시점엔 Tick이 아예 호출되지 않음을 확인함.

공식 문서에 있는 문구 때문이었음:

예약된 액션의 소유자가 파괴될 경우 내부에서 자동으로 ClearTimer() 함수를 시도합니다.

HideBuff가 부르는 icon:Destroy() 시점에 엔진이 타이머 소유자 파괴를 감지해서 알아서 정리해주고 있었던 것. 정황상 의심스러워 보이는 코드도 실측 없이는 "버그"로 단정하면 안 된다는 걸 다시 확인함. 결국 방어 코드는 추가하지 않고 원래 코드 그대로 유지, 오히려 "혹시 몰라서" 넣어뒀던 방어 코드도 도달 불가능한 지점이라 판단해서 뺐음.

2. 하이라이트 색상 — 컬러 상수 공유부터 시작해서 뒤집힌 결론

처음엔 단순하게 "여러 파일에 중복된 하이라이트 색상 상수를 Logic으로 전역화하자"는 생각으로 시작했는데, 파다 보니 완전히 다른 결론에 도달함.

1단계 — ButtonComponent에 SelectedColor가 있다는 걸 실측으로 확인. 클릭 뗀 뒤에도 색이 유지되고, 다른 버튼 누르면 자동으로 꺼짐. 그래서 디버그 패널의 아이템 버튼(UIDebugItemSlot.SetHighlight)은 이걸로 완전히 대체함 — 단, Scale 확대(1.15배) 연출은 ButtonComponent가 못 해주는 커스텀 연출이라 별도로 유지해야 했음.

2단계 — 같은 논리를 인벤토리 카테고리 탭에도 적용하려다가 실측에서 걸림. 최초 진입 시 기본 탭(장비 탭)은 실제 클릭이 발생한 적이 없어서 SelectedColor가 절대 켜지지 않음. "그럼 최초 1회만 수동으로 색을 칠해주면 되지 않나" 싶어서 SpriteGUIRendererComponent.Color를 직접 대입했는데, 장비 탭만 영원히 노란색으로 박제되는 버그가 남. ButtonComponent가 관리하는 상태와 완전히 별개의 값을 건드린 거라, 나중에 다른 탭을 눌러도 자기가 켠 적 없는 값을 되돌려줄 이유가 없었던 것.

ButtonComponent를 코드로 강제 클릭시키는 API도 찾아봤지만 없었음(ButtonComponent는 출력 기능이 없습니다 — 입력만 받고 상태를 밖에서 주입하는 경로 자체가 설계에 없음). 결국 카테고리 탭은 원래 방식(매번 전체 탭을 순회하며 다시 칠하는 방식)을 그대로 유지하기로 함. 다만 매직넘버 Color(1.0, 0.85, 0.3, 1.0)는 normalTabImageRUID/selectedTabImageRUID(string) 프로퍼티로 바꿔서, 색상 대신 스프라이트를 교체하는 방식으로 전환 — 디자이너가 인스펙터에서 이미지를 갈아끼울 수 있게 됨.

method void UpdateCategoryTabHighlight()
if self._T.categoryTabEntities == nil then return end

for category, tabEntity in pairs(self._T.categoryTabEntities) do
    if tabEntity.SpriteGUIRendererComponent ~= nil then
        tabEntity.SpriteGUIRendererComponent.ImageRUID =
            (category == self.currentCategory) and self.selectedTabImageRUID or self.normalTabImageRUID
    end
end
end

3. Entity로 받아놓고 컴포넌트 하나만 뽑아 쓰던 곳들

UIMyInfo의 hpBar/mpBar/hpText/mpText 등이 전부 Entity 타입 프로퍼티였는데, 실제로는 .UITransformComponent나 .TextComponent를 매번 다시 꺼내 쓰는 용도였음. UIItemSlot처럼 스폰되는 템플릿이면 런타임에 자식을 찾아야 하니 어쩔 수 없지만, UIMyInfo는 화면에 고정으로 하나만 배치되는 싱글턴 UI라 애초에 Component 타입 프로퍼티로 선언하고 에디터에서 직접 연결하면 됐음.

같은 패턴이 ExtendPlayerComponent/ExtendMovementComponent/PlayerStats의 statUIEntity에도 있었음 — 셋 다 .UIMyInfo만 꺼내 쓰고 있어서 Component 타입(statUIInfo)으로 통일. Entity로 받아야 할 이유(SetVisible 같은 엔티티 자체 기능 사용)가 있는지 없는지가 판단 기준이 됨.

📚 개발 참고

• 프로퍼티 — MapleStory Worlds Creator Center _T 프로퍼티의 정확한 정의(선언 시점, 동기화 불가)를 확인한 문서. _T와 정식 프로퍼티 중 무엇을 쓸지 판단하는 근거가 됨.

• TimerService — MapleStory Worlds Creator Center 반복 타이머가 소유자 파괴 시 자동으로 정리 시도된다는 "유의 사항"을 확인한 문서. UIBuffIcon 버그 오판을 바로잡은 근거.

• 기본 UI 컴포넌트 — MapleStory Worlds Creator Center ButtonComponent가 ButtonState(Normal/Hover/Pressed/Released/Clicked)로만 동작하고 "출력 기능이 없다"는 걸 확인한 문서. 카테고리 탭에 SelectedColor를 못 쓰는 이유의 근거가 됨.

👨‍💻 오늘의 개발 작업

기존에는 임시로 삭제 버튼을 만들어서 사용했었는데, 인벤토리 바깥으로 아이템을 드롭하면 버려지는 기능으로 개선함. 이미 만들어져 있던 UIPopup(범용 확인창)을 재사용할 수 있는지부터 검토하고, 드롭 판정 → 수량 입력 팝업 → 서버 삭제 → 토스트 메시지까지 한 흐름으로 엮었음. 중간에 상속 vs 합성을 두고 한 번 갈아엎었고, 클릭 이벤트 시스템마다 마우스 ID 규칙이 다르다는 것도 실측으로 잡아냄.

💡 오늘의 기록

1. UIPopup 재사용 검토 — 상속 시도했다가 합성으로 되돌림

기존 UIPopup은 "메시지 + 확인/취소" 전용이라 수량 입력 필드가 없었음. UIPopup 자체를 고치는 건 SRP 위반(범용 확인창이 "수량 파싱" 책임까지 지게 됨)이라, 수량 입력을 담당할 UIQuantityPopup을 별도로 만들기로 함.

처음엔 상속(UIQuantityPopup extends UIPopup)으로 시도했음 — 커스텀 Logic이 다른 커스텀 Logic을 상속할 수 있다는 걸 실측으로 확인했고, self:Open(...)도 에러 없이 동작함. 그런데 다시 보니 상속받은 프로퍼티(popupGroup/popup/message/btnOk/btnCancel)가 인스펙터에 노출이 안 돼서 에디터 드래그 연결이 불가능했고, 결국 전용 패널을 하나 더 복사해서 GetChildByName으로 코드에서 직접 배선해야 하는 구조가 됨. isOpen도 인스턴스별로 따로 관리돼서, 원본 패널과 실수로 엔티티를 공유하면 버튼 핸들러가 이중 연결되는 위험까지 있었음.

득보다 실이 커서 합성으로 되돌림 — UIQuantityPopup은 Logic으로 그대로 두고, 내부에서 _UIPopup:Open(...)을 전역 호출만 하는 방식. 패널은 하나만 유지되고, 에디터 연결도 그대로 쓸 수 있음. UIPopup·UIQuantityPopup 둘 다 _ItemTooltip, _UIToast처럼 전역 싱글턴 Logic이라 엔티티 참조 없이 _UIQuantityPopup:OpenForDrop(...)로 어디서든 바로 호출 가능.

-- amountInput은 기존 팝업 패널 밑에 추가한 TextInputComponent, 평소엔 Enable=false로 숨겨둠
self.amountInput.Entity.Enable = true
local onOk = function()
    local amount = self:GetValidatedAmount(maxAmount)
    if amount == nil then
        _UIToast:ShowMessage(errorMessage, _UserService.LocalPlayer.PlayerComponent.UserId)
        return false -- 팝업 유지, 재입력 가능
    end
    self.amountInput.Entity.Enable = false
    onConfirm(amount)
end
_UIPopup:Open(message, onOk, onCancel)

2. 드롭 감지 — 좌표 계산 없이 ScreenTouchEvent + IsPointerOverUI

인벤토리가 클릭-토글 방식(실제 드래그 아님)이라, "바깥으로 드롭"은 결국 "아이템을 쥔 상태에서 UI가 아닌 곳을 클릭"으로 판정하면 됨. 새 캐처 엔티티를 배치하는 대신 InputService.ScreenTouchEvent(화면 전체에서 발생, UI 유무 무관) + IsPointerOverUI()(UI 위인지 여부) 조합으로 좌표 계산 없이 처리. 아이템을 쥐고 있는 동안만 구독하고, 놓으면 바로 해제해서 상시 리스너를 피함(OnGhostMouseMove와 동일한 패턴).

실측으로 잡은 것: UITouchDownEvent(슬롯 클릭)는 마우스를 -1로 주는데, ScreenTouchEvent는 마우스를 1로 줌. 처음엔 슬롯 클릭 코드에 있던 -1 규칙을 그대로 가져다 썼다가 드롭이 전혀 안 먹혀서, 디버그 로그로 실제 TouchId 값을 찍어보고 발견함. 공식 문서에도 "마우스 커서의 pointerId는 1"이라고 명시돼 있어서 근거도 확인됨 — 이벤트 시스템마다 규칙이 다를 수 있으니 재사용할 때 값을 그대로 가정하면 안 된다는 교훈.

method void OnScreenTouchWhileHolding(ScreenTouchEvent event)
    local TouchId = event.TouchId
    if TouchId ~= 1 then return end -- 실측: ScreenTouchEvent는 마우스를 1로 준다
    if _InputService:IsPointerOverUI() then return end -- UI 위 클릭은 슬롯/버튼 클릭이 따로 처리
    self:HandleDropOutside()
end

3. 수량 입력 검증 — 조용히 클램프하지 않고 명시적으로 거부

처음엔 무효 입력(빈 값/0/최대 초과)을 그냥 기본값으로 조용히 대체했는데, 테스트해보니 "0을 입력하면 1개가 버려지고 아무것도 입력 안 하면 전부 버려지는" 게 오히려 헷갈렸음. 그래서 무효 입력은 nil을 반환해서 "이 값으론 진행 못 함"을 명확히 신호하도록 바꾸고, 원인별로 다른 토스트 메시지를 띄우게 함.

문제는 UIPopup.OnClickOk가 onOk()의 반환값과 상관없이 무조건 팝업을 닫아버려서, 검증 실패해도 팝업이 닫혀버렸음. onOk가 false를 반환하면 닫지 않고 유지하도록 계약을 확장 — 기존 사용처는 다 onOk에서 아무것도 반환 안 하므로(nil ~= false) 하위 호환은 그대로 유지됨.

local result = self.onOk()
if result == false then
    return -- onOk가 명시적으로 false를 반환하면 팝업을 닫지 않고 유지(재입력 가능)
end
self.onOk = nil
self:Close()

OnClickCancel도 취소로 닫힐 때 self.onOk가 정리 안 되고 남아있던 걸 발견해서 같이 정리함(방어적).

4. Enter 키로 제출 — TextInputSubmitEvent

공식 문서에서 TextInputSubmitEvent가 "Enter 키를 눌렀을 때 호출되는 이벤트"로 TextInputComponent에 정의돼 있는 걸 확인. amountInput이 평소엔 Enable=false라 입력 자체를 못 받으니, OnBeginPlay에서 한 번만 연결해두면 됨(열고 닫을 때마다 connect/disconnect 안 해도 됨).

self.amountInput.Entity:ConnectEvent(TextInputSubmitEvent, function() _UIPopup:OnClickOk() end)

디버그 패널의 아이템 추가 입력창에도 같은 방식으로 Enter → 추가 버튼 클릭을 연결. OnClickAddButton이 이미 amountInput.Text를 직접 읽는 구조라 버튼 클릭이든 Enter든 같은 메서드 호출만으로 충분했음.

5. 서버 DeleteItem — 토스트 + 반환값 검증

기존에 있던 AddItem의 토스트 패턴(_UIToast:ShowMessage(message, userId))을 DeleteItem에도 그대로 적용. 다만 RemoveItem 호출 후엔 슬롯이 비어(itemId = 0) 아이템 이름을 못 찾으니, 삭제 전에 itemId를 스냅샷해둠.

한 번 더 코드를 훑다가 잡은 버그: container:RemoveItem(slotIdx, amount)의 반환값을 안 받고 있어서, 서버 쪽에서 삭제가 실패해도(통신 중 재고가 바뀌었거나 클라이언트 검증을 우회한 경우) 무조건 "N개를 버렸습니다" 토스트가 뜨는 상태였음. 클라이언트 검증만 믿지 않고 서버가 자기 결과를 스스로 확인하도록 고침.

local removed = container:RemoveItem(slotIdx, amount)
self:BroadcastChangedSlots(category, prevSnapshot)
if not removed then return end -- 실패 시 토스트도 안 띄움

📚 개발 참고

• InputService — MapleStory Worlds Creator Center ScreenTouchEvent, IsPointerOverUI(pointerId)의 정확한 동작과 마우스 pointerId가 1이라는 것을 확인한 문서. 드롭 판정 로직의 근거가 됨.

• TextInputSubmitEvent — MapleStory Worlds Creator Center Enter 키 입력을 감지하는 정확한 이벤트명과 발생 시점을 확인. TextInputEndEditEvent(포커스 아웃 포함)와 헷갈리지 않도록 구분하는 근거가 됨.

👨‍💻 오늘의 개발 작업

카테고리 필터를 카테고리별로 InventoryContainer를 별도 소유하는 방식으로 구현했음. 서버 구조 자체는 이미 검증된 패턴(스냅샷 diff, 이벤트 기반 브로드캐스트)을 카테고리 단위로 나누기만 하면 돼서 설계는 금방 끝났고, 드래그 고스트 잔상 두 종류, 숨겨진 슬롯의 유령 터치 이벤트 문제까지 잡아서 스왑(드래그앤드롭) 기능을 카테고리 구조 위에서 다시 안정화했음. 여기에 아이템 추가 팝업, 카테고리 탭 하이라이트까지 마무리.

💡 오늘의 기록

1. 카테고리 "완전 분리 방식" — 서버 구조

PlayerInventory가 카테고리별 InventoryContainer를 각각 소유하도록 구조 변경. InventoryContainer(StructType) 자체는 카테고리 개념을 몰라도 되게 애초에 설계해뒀어서(DIP, maxStack 외부 주입) 수정 없이 그대로 재사용됨.

프로퍼티 설계는 한 번 갈아엎음: 처음엔 equipContainer/consumeContainer/... 카테고리당 프로퍼티를 각각 5개씩(컨테이너용, 용량용) 뒀는데, 이러면 카테고리 문자열 → 프로퍼티 라우팅용 map을 GetContainer/GetCapacity가 호출될 때마다 새로 만들어야 했음. 다시 보니 굳이 그럴 이유가 없어서 containers/capacities table 프로퍼티 하나씩으로 정리 — 인스펙터에서 카테고리별로 개별 확인은 안 되지만, 라우팅 메서드가 한 줄로 줄고 카테고리가 늘어도 코드 수정이 필요 없어짐.

-- GetContainer/GetCapacity 최종 형태
method InventoryContainer GetContainer(string category)
local container = self.containers[category]
if container == nil then
    log_error("[PlayerInventory] GetContainer: 알 수 없는 카테고리 " .. tostring(category))
end
return container
end

이벤트 재설계: OnInventoryModified엔 category 필드 추가 — 유저 액션 하나는 항상 카테고리 하나만 건드리므로 "카테고리당 이벤트 하나"는 자연스러운 결과. OnInventoryInitialized(로그인 시 전체 스냅샷)는 처음엔 이것도 카테고리별로 5번 나눠 보내려다가, 5개 컨테이너가 애초에 동시에(하나의 저장 데이터에서) 준비되는데 굳이 나눠 보낼 이유가 없다는 걸 깨닫고 하나의 이벤트로 합침. 다만 중첩 테이블({category: {slotIdx: slot}})로 합치려던 1차안은 MSW 공식 튜토리얼 예제가 전부 1차원 데이터만 다루는 걸 확인하고 폐기 — 대신 카테고리별 프로퍼티 5개(equipSlots~cashSlots)를 한 이벤트에 나란히 실어서, "이벤트 하나 = 전체 원자적 전달"이라는 목표는 유지하면서 검증 안 된 구조는 피함.

저장 포맷도 {slots:[...]} → {categories:{["소비"]=[...], ...}}로 변경. 모르는 카테고리 키는 조용히 스킵(구버전 세이브 방어).

⚠️ 코드 다시 훑다가 잡은 버그 2개: RestoreFromSaveData의 파싱 실패 체크가 옛 필드(data.slots) 그대로 남아있어서 저장 데이터 복원이 항상 실패하던 것, capacities 기본값이 빈 테이블이라 모든 카테고리 용량이 0이 되던 것. 둘 다 실행 전에 코드만 봐도 걸리는 버그였는데, 리팩터링 도중엔 놓치기 쉬웠음.

2. 카테고리 문자열 전역화 — InventoryConstants

"장비"/"소비"/"기타"/"설치"/"캐시" 5개 문자열을 스크립트마다 로컬 상수로 반복 선언하다가(mLua는 최상단 local을 메서드 간에도 공유 안 함), 서버(PlayerInventory)뿐 아니라 클라이언트(UIInventory)도 같은 문자열을 참조해야 하는 시점이 오면서 Logic으로 전역화함(_ItemData와 동일 패턴).

이름은 프로퍼티(property string EQUIP = "장비" 등)로 선언하되, 일부러 UPPER_SNAKE_CASE로 지음 — 컨벤션표 기준으로는 프로퍼티가 원래 camelCase지만, 이 값들은 디자이너가 튜닝할 값이 아니라 "코드가 참조하는 게임 규칙 정의"라 상수 표기가 더 정확한 신호를 줌. 인스펙터에도 노출 안 함(표시 안 함).

3. 드래그 고스트 잔상 — 두 종류를 따로 잡음

① 위치 잔상: 아이템을 집을 때 고스트가 "이전 위치"에서 한 틱 보였다가 정상 위치로 튀는 현상. Show()가 Visible=true를 반영하는 시점이 SetScreenPos()의 위치 반영(레이아웃 갱신)보다 먼저 화면에 나타나는 게 원인으로 보였음. 처음엔 _TimerService:SetTimer(self, fn, 0, false, 0)로 한 틱 늦춰서 우회했다가, 최종적으로는 Show() 내부에서 커서 위치 계산 → SetScreenPos → 이미지 세팅 → Visible=true 순서를 전부 통합해서 호출부(UIInventory)가 순서를 신경 쓸 필요 없게 정리함.

② 아이콘 잔상: 다른 아이템을 연달아 집을 때 이전 아이템 아이콘이 아주 짧게 겹쳐 보이는 현상. Enable만 껐다 켜는 방식으론 ImageRUID가 그대로 남아있어서, 리소스 교체가 반영되는 타이밍에 이전 이미지가 살짝 노출되는 게 원인. Hide()/SetEmpty() 양쪽 다 Enable=false 하기 전에 ImageRUID=""로 리소스 자체를 비우는 패턴으로 통일(UIDragGhost, UIItemSlot 둘 다 적용).

패턴 정리: 리소스 ID(ImageRUID 등)를 교체할 땐 Enable만 토글하지 말고, 끌 때는 리소스 자체를 비우고, 켤 때는 리소스를 먼저 확정한 뒤 Enable=true를 켜는 순서로 통일.

③ (별개 방어 코드) 숨겨진 슬롯의 잔여 데이터: 위 잔상 버그의 원인을 찾던 중 "숨긴 슬롯이 터치 이벤트를 계속 받아서 그런가"라는 가설도 세웠었는데(SetVisible(false)는 렌더링만 끄지 UITouchReceiveComponent의 터치 수신까지는 안 끔), 디버그 로그(TouchEnter slotIdx=12 itemId=0)로 확인해보니 실제 원인은 아니어서 기각함. 다만 "숨겨진 엔티티도 터치는 계속 받는다"는 사실 자체는 실제라 별도로 방어해둘 가치가 있어서, RenderCurrentCategory에서 숨기는 슬롯도 RefreshSlot(slotIdx, 0, 0)으로 캐시를 같이 비우는 코드는 남겨둠(예: 숨겨진 슬롯에서 툴팁이 열리는 것 방지).

4. 아이템 추가 팝업 + 카테고리 탭 하이라이트

팝업: 새로 만들지 않고 이미 있던 UIToast(_UIToast:ShowMessage(message, userId))를 재사용. container:AddItem이 반환하는 InventoryUpdateResult(success, amount)를 활용해 완전 성공/부분 성공(공간 부족)/완전 실패 세 갈래 메시지 분기.

탭 하이라이트: 이전에 썼던 UIItemSlot.SetHighlight와 같은 패턴(SpriteGUIRendererComponent.Color 틴트)을 탭 버튼에도 적용. 탭 엔티티를 OnBeginPlay에서 연결할 때 self._T.categoryTabEntities에 카테고리별로 캐싱해두고, 탭 전환/최초 접속 시 UpdateCategoryTabHighlight()로 일괄 갱신.

5. 그 외 코드 정리한 것들

• 죽은 코드 제거: "슬롯 선택 + 삭제 버튼" 방식은 드래그/드롭 완성으로 대체됐는데 정리가 안 돼있었음(selectedSlotIdx/SelectSlot이 호출되는 곳 자체가 없었음) — 삭제는 나중에 "인벤토리 밖으로 드롭하면 버려짐" 방식으로 재구현 예정이라 일단 통째로 제거.
• 디버깅 과정에서 남긴 주석 처리된 실험 코드(SetTimer 우회, 초기 SetScreenPos 순서 실험) 정리.
• UIDragGhost.Hide/SetScreenPos에 @ExecSpace("ClientOnly") 명시 누락된 것 — 다른 메서드와 일관성 맞춤.
• Color(167/255, 167/255, 167/255, 1.0) 형태로 헥스 색상(#A7A7A7)을 표현 — Color는 0255가 아니라 01 float를 받음.

📚 개발 참고

• InputService — MapleStory Worlds Creator Center ConnectEvent/DisconnectEvent의 정확한 반환 타입(EventHandlerBase)을 확인한 문서. MouseMoveEvent 리스너 해제 코드를 정상 동작하게 고치는 근거가 됨.

• 인벤토리 스크립트 작성하기 — MapleStory Worlds Creator Center OnInventoryInitialized 이벤트로 인벤토리 데이터를 통째로 전달하는 공식 예제. SyncTable<V>가 1차원 인덱스 기반 컬렉션이라는 걸 확인하고, 중첩 테이블 대신 카테고리별 명시적 프로퍼티로 이벤트를 설계하는 근거가 됨.

👨‍💻 오늘의 개발 작업

인벤토리에 스왑(드래그앤드롭) 기능을 붙였음. 서버 로직 자체는 기존 MergeSlot/MergeItems 패턴을 거의 그대로 복사해서 금방 끝났는데, 진짜 시간을 잡아먹은 건 "클릭 한 번으로 아이템을 들고, 다시 클릭하면 놓는" 메이플 특유의 인터랙션을 재현하는 과정이었음.

💡 오늘의 기록

1. 서버 로직 — 기존 패턴 재사용이라 리스크 낮음

InventoryContainer에 SwapSlot(fromIdx, toIdx), PlayerInventory에 SwapItems(ServerOnly)/RequestSwapItems(Server) 세 개만 추가하면 끝. MergeSlot/MergeItems/RequestMergeItems와 시그니처·검증 흐름이 거의 대칭이라 새로 설계할 게 거의 없었음.

같은 아이템끼리 스왑하는 경우는 SwapItems에서 걸러내고 RequestMergeItems로 넘기도록 유도함 — MergeSlot의 min(fromCnt, maxStack-toCnt) 공식이 "from이 이미 최대치라 사실상 자리만 바뀌는 경우"까지 자동으로 커버해준다는 걸 검증했기 때문에, 별도 예외 분기 없이 하나로 충분했음.

-- PlayerInventory.SwapItems (ServerOnly)
local EMPTY_ITEM_ID = 0
local fromSlot = self.invenContainer.slots[fromIdx]
if fromSlot == nil then return end
local toSlot = self.invenContainer.slots[toIdx]
if toSlot == nil then return end

if fromSlot.itemId ~= EMPTY_ITEM_ID and fromSlot.itemId == toSlot.itemId then
    return -- 같은 아이템은 MergeItems 영역
end

local prevSnapshot = self:SnapshotSlots()
self.invenContainer:SwapSlot(fromIdx, toIdx)
self:BroadcastChangedSlots(prevSnapshot)

2. 클릭 토글 + 더블클릭 충돌 ⚠️

holdingSlotIdx 상태 하나로 집기/놓기를 토글하도록 재설계함. 문제는 기존에 있던 "더블클릭으로 아이템 즉시 사용" 기능과 어떻게 공존시키느냐였음.

1차 시도: 더블클릭 판정을 UIItemSlot이 자기 타이머로 독자 판단 → 첫 클릭이 이미 "집기"를 실행해버리므로, 두 번째 클릭에서 그 집기를 취소(CancelHold)하고 사용 요청을 보내는 방식으로 맞춤.

여기까지는 동작했는데, 아래와 같은 시나리오에서 실제 기대와 다른 결과가 나온다는 걸 검증 과정에서 발견함:

A 클릭 → 집기 (holdingSlotIdx=A)
B 클릭 (A 쥔 상태) → 놓기(스왑 A↔B)
C 클릭 → 집기 (holdingSlotIdx=C)
B를 빠르게 다시 클릭 (C 쥔 상태) → B의 클릭 타이머가 아직 300ms 안이라 "더블클릭"으로 오판됨
→ 지금 실제로 쥐고 있는 C가 엉뚱하게 취소돼버림

원인: "이 클릭이 더블클릭인가"를 슬롯 자신의 타이밍만으로 판단하면, 현재 홀드 상태를 전혀 모른 채 판정하게 됨. 더블클릭이라는 개념 자체가 사실 "쥔 게 없거나, 쥔 게 지금 클릭한 슬롯 자신일 때"만 의미가 있는 건데, 그 조건을 확인할 수 있는 쪽은 슬롯이 아니라 홀드 상태를 갖고 있는 UIInventory뿐이었음.

최종 규칙

더블클릭 판정은 (isDoubleClick) AND (holdingSlotIdx == nil OR holdingSlotIdx == slotIdx) 일 때만 유효
다른 슬롯을 쥔 채로의 클릭은 무조건 "놓기"로 처리, 그 슬롯의 타이머는 건드리지 않음

더블클릭 타이머 자체도 UIItemSlot에서 UIInventory(lastClickTimeBySlot)로 옮김. "놓기" 액션은 타이머를 절대 갱신하지 않는다는 대칭 규칙까지 맞추고 나서야 위 시나리오가 "손에 뭔가 쥔 상태로 자연스럽게 끝나는" 정상 동작으로 바뀜.

3. 이게 아키텍처적으로 맞는 선택인지 재검토

더블클릭 판정 로직을 위젯(UIItemSlot)이 아니라 컨트롤러(UIInventory)에 두는 게 이상하게 느껴질 수 있어서 다시 짚어봄. 결론은 — 이 타이밍 데이터 자체가 이미 "홀드 상태"라는 도메인 지식에 종속돼 있어서, 순수 위젯이 혼자 판단할 수 없는 문제였음. 프로젝트에 이미 있던 selectedSlotIdx 패턴("슬롯 하나짜리가 아니라 인벤토리 전체 관점의 상태는 UIInventory가 소유한다")을 더블클릭 판정까지 일관되게 확장한 셈이라, SRP 관점에서도 맞는 방향이라고 판단함.

4. 드래그 고스트 UI 구현

커서를 따라다니는 아이템 아이콘을 붙이는 과정에서 두 번 연속으로 잘못 짚음.

처음엔 MouseMoveEvent도 다른 이벤트들처럼 EventName을 정적으로 선언하는 핸들러로 구현했음. 그런데 상시 리스너로 계속 켜놓는 것보다, 툴팁이 이미 쓰고 있던 "쥐고 있는 동안에만 구독하고, 놓으면 해제하는" 방식(_InputService:ConnectEvent/DisconnectEvent)이 불필요한 리스너를 안 만든다는 점에서 더 낫다고 판단해서 그 패턴으로 갈아탐.

1차: MouseDelta 누적 방식

self._T.ghostPosition += Vector2(MouseDelta.x, MouseDelta.y)
self.dragGhostEntity.UIDragGhost:SetScreenPos(self._T.ghostPosition)

호출은 되는데 커서 옆에 뜨지도 않고 이동폭도 너무 작았음. MouseDelta의 단위/좌표계와 UITransformComponent.Position이 기대하는 좌표계가 서로 다른 게 원인이었음 — 이번 세션 전에 이미 툴팁 기능을 만들면서 "Screen 좌표와 UI 좌표(anchoredPosition)는 원점이 다르다"는 걸 겪고 해결한 적이 있었는데, 그 교훈을 처음에 반영 안 하고 새로 짜다가 똑같은 함정에 다시 빠짐.

2차: 툴팁 코드 그대로 포팅 — 해결 이미 검증된 UpdateTooltipPosition 코드를 그대로 가져와서, 델타 누적을 완전히 버리고 _InputService:GetCursorPosition()으로 절대 좌표를 매번 직접 조회 + Anchor 비율 방식으로 교체함.

local screenSize = Vector2(_UILogic.ScreenWidth, _UILogic.ScreenHeight)
local anchorRatio = Vector2(cursorPoint.x / screenSize.x, cursorPoint.y / screenSize.y)

transform.AnchorsMin = anchorRatio
transform.AnchorsMax = anchorRatio
transform.Pivot = Vector2(0.5, 0.5)
transform.anchoredPosition = Vector2.zero

📚 개발 참고

• 기본 UI 컴포넌트 — MSW 공식 크리에이터 센터 UITransformComponent가 Anchor Preset에 따라 요구하는 프로퍼티가 달라진다는 걸 확인한 문서. 좌표 대입 버그를 짚어볼 때 기준으로 참고함

• 월드 좌표와 스크린 좌표 — MSW 공식 크리에이터 센터 Screen 좌표계와 UI 좌표계의 원점이 다르다는 걸 설명하는 문서. 툴팁 때도, 이번 드래그 고스트 때도 같은 함정에 빠진 근본 원인이 여기 있었음

👨‍💻 오늘의 개발 작업

슬롯에 마우스를 올리면 아이템 이름/설명이 커서 근처에 뜨는 툴팁을 만들었음. 단순히 "보였다 안 보였다"만 만드는 걸로 끝날 줄 알았는데, ①좌표계 변환, ②호버(hover) 감지 방식, ③UI 입력 히트 판정이라는 세 가지 별개의 문제를 순서대로 만났고, 세 번째는 겉으로 드러난 증상(아이콘 위에서만 안 뜸)만 보면 원인을 완전히 잘못 짚기 쉬운 문제였음.

💡 오늘의 기록

1. 문제 상황 파악

슬롯에 커서를 올리면 그 아이템의 이름/설명이 담긴 패널이 커서 근처에 뜨고, 커서를 움직이면 따라오고, 벗어나면 사라져야 함. 추가로 "동시에 여러 슬롯의 툴팁이 겹쳐 뜨는" 상황은 막아야 했음

-- 최초 접근 (기각)
-- UIItemSlot.Show(itemId, touchPoint)
self.Entity:SetEnable(true)
self.tooltipTransform.anchoredPosition = touchPoint + offset

동작은 했지만 위치가 커서와 계속 어긋났음. 처음엔 offset 값을 조정하면 될 거라 생각했는데, 알고 보니 훨씬 근본적인 문제였음

2. Screen 좌표계와 UI 좌표계는 원점이 다르다

UITouchEnterEvent가 넘겨주는 TouchPoint(Screen 좌표)를 UITransformComponent.anchoredPosition(UI 좌표)에 그대로 대입하고 있었음. 공식 문서를 다시 확인해보니 이 둘은 애초에 원점이 다른 별개의 좌표계였음

월드 좌표와 스크린 좌표 — MSW 공식 문서 UI 좌표계의 원점은 Safe Area 중앙, Screen 좌표계의 원점은 화면 좌측-하단

즉 "Screen 좌표 값을 UI 좌표에 그대로 꽂아 넣기"는 두 좌표계가 우연히 같은 스케일을 쓰지 않는 이상 애초에 성립할 수 없는 방식이었음. 공식 문서가 권장하는 방식은 커서 위치를 화면 대비 0~1 비율로 변환해서 AnchorsMin/AnchorsMax에 "점 앵커"로 꽂고 anchoredPosition은 Vector2.zero로 두는 것이었음. 화면 가장자리에서 툴팁이 잘리지 않도록 Pivot도 커서 위치에 따라 반전시키는 로직을 추가함

-- UIItemSlot.UpdateTooltipPosition (ExecSpace: ClientOnly)
if self._T.tooltipTransform == nil then return end

local screenSize = Vector2(_UILogic.ScreenWidth, _UILogic.ScreenHeight)
local cursorPoint = _InputService:GetCursorPosition()
local anchorRatio = Vector2(cursorPoint.x / screenSize.x, cursorPoint.y / screenSize.y)

local transform = self._T.tooltipTransform
transform.AnchorsMin = anchorRatio
transform.AnchorsMax = anchorRatio
transform.Pivot = self:GetEdgeAwarePivot(transform, self._T.tooltipCanvasSize)
transform.anchoredPosition = Vector2.zero

3. 호버 감지를 어떤 이벤트로 할 것인가

UITouchEnterEvent/UITouchExitEvent로 호버를 감지했는데, 가만히 있으면 안 뜨고 움직여야만 뜨는 등 불안정했음. "이 이벤트가 드래그류 이벤트와 묶여 있어서 순수 호버(마우스 눌지 않은 상태)엔 안 맞는 게 아닐까" 의심하고 ButtonComponent + ButtonStateChangeEvent(state == ButtonState.Hover)로 바꿔봄

-- 대안으로 시도 (최종적으로 기각)
if state == ButtonState.Hover then
    self:ShowTooltip()
end

이 과정에서 이름이 비슷한 이벤트 세 개(ButtonStateChangeEvent, ButtonStateChangeEditorEvent, EditorGUIButtonStateEvent)를 혼동해서 API 문서로 구분함 — 실제 런타임에서 쓸 건 ButtonStateChangeEvent 하나뿐이고 나머지는 에디터 전용/무관한 API였음

ButtonComponent 방식은 동작은 했지만 위치 정보를 안 주기 때문에 Show() 시점에 커서 위치를 한 번만 스냅샷하는 식이 되어 커서를 계속 따라다니지 못했고, 간헐적으로 호버가 씹히는 현상도 남아있었음. 결국 UITouchReceiveComponent를 버릴 이유가 없었다는 결론으로 원점 회귀함

(돌아보며 남기는 의문: 이 시점의 불안정 증상은 시점상 6번에서 찾은 RaycastTarget 문제와 겹침 — 즉 "이벤트 자체가 순수 호버엔 안 맞는다"는 진단이 처음부터 틀렸고, 툴팁 패널의 RaycastTarget만 그때 껐어도 UITouchReceiveComponent만으로 안정적으로 동작해서 ButtonComponent로 갈아탈 필요 자체가 없었을 가능성이 있음. 실제로 되돌아가 재검증하지는 않아서 확정할 수는 없음)

4. 재설계 — Logic 기반 뮤텍스 + 이벤트 기반 연속 추적

동작이 검증된 참고 구현을 스터디하면서 세 가지를 다시 확인함

• Entity:SetVisible()과 Entity:SetEnable()은 별개다 — 전자는 시각적 표시만, 후자는 로직 활성화까지 끈다. "한 번 뜨고 다시는 안 뜨는" 예전 버그의 원인이 여기 있었을 가능성이 높음
• 여러 슬롯이 동시에 툴팁을 열려는 상황을 막으려면 툴팁 자체를 전역 싱글턴(Logic)으로 두고 isUsing 플래그로 상호배제하는 게 깔끔함
• 커서를 계속 따라다니려면 매 프레임 폴링이 아니라 _InputService:ConnectEvent(MouseMoveEvent, ...)로 호버 중에만 구독하고 벗어나면 해제하면 됨

-- ItemTooltip (Logic, ExecSpace: ClientOnly)
method CanOpen() -> boolean
    return not self.isUsing
end

method Open(itemId) -> Entity
    if not self:CanOpen() then return nil end
    if not _ItemData.isInitialized then return nil end

    local itemInfo = _ItemData.itemTable[itemId]
    if itemInfo == nil then return nil end

    self.nameText.Text = itemInfo.name
    self.descText.Text = itemInfo.description
    self.tooltipEntity:SetVisible(true)
    self.isUsing = true
    return self.tooltipEntity
end

method Close()
    self.tooltipEntity:SetVisible(false)
    self.isUsing = false
end

-- UIItemSlot.HandleUITouchEnterEvent (Sender: UITouchReceiveComponent, Space: Client)
local EMPTY_ITEM_ID = 0
if self._T.itemId == nil or self._T.itemId == EMPTY_ITEM_ID then return end

local tooltipEntity = _ItemTooltip:Open(self._T.itemId)
if tooltipEntity == nil then return end  -- 다른 슬롯이 사용 중

self._T.tooltipTransform = tooltipEntity.UITransformComponent
self._T.tooltipCanvasSize = tooltipEntity.Parent.UITransformComponent.RectSize
self:UpdateTooltipPosition()

self._T.mouseMoveHandlerId = _InputService:ConnectEvent(MouseMoveEvent, function()
    self:UpdateTooltipPosition()
end)

여기까지 오니 위치도 맞고, 씹힘도 없어졌음. 그런데 곧바로 새로운 증상이 나타남

5. 가장자리에서만 뜨고 아이템 이미지 위에서는 안 뜬다

슬롯의 빈 여백(패딩)에 커서를 두면 툴팁이 뜨는데, 정작 아이템 아이콘(ItemImg) 위로 커서를 옮기면 뜨질 않았음. 처음엔 "자식 엔티티(ItemImg, ItemCnt)가 부모 슬롯의 UITouchReceiveComponent로 가는 터치 입력을 통째로 가로막고 있다"고 판단했음

이 가설을 검증하려던 중, 같은 슬롯에서 더블클릭으로 아이템을 사용하는 기능(UITouchDownEvent)은 아이콘 위에서도 멀쩡히 동작한다는 반례를 만남. 같은 엔티티, 같은 UITouchReceiveComponent인데 Down은 되고 Enter/Exit만 안 되는 상황이라 "자식이 입력을 통째로 막는다"는 가설로는 설명이 안 됐음. "Down은 좌표가 영역 안인지만 보는 단순 판정이고, Enter/Exit는 커서 아래 가장 위에 그려진 요소가 누구인지 매 프레임 추적하는 방식이라 그 차이가 갈린다"는 쪽으로 가설을 수정하고 있던 시점에, 실측으로 진짜 원인을 확인함

6. 진짜 원인 — RaycastTarget

ItemImg, ItemCnt(그리고 툴팁 패널 자신)의 RaycastTarget이 켜져 있었던 게 원인이었음. SpriteGUIRendererComponent/TextComponent가 공통으로 상속하는 ImageComponent에 있는 프로퍼티로, 공식 문서 설명은 다음과 같음

ImageComponent — MSW 공식 API 레퍼런스 RaycastTarget(boolean): "true로 설정할 경우 화면 터치 또는 마우스 클릭 대상이 되며, 뒤에 가려진 UI는 화면 터치와 마우스 클릭 입력을 받지 못합니다."

즉 ItemImg가 기본값(true)인 채로 슬롯 위에 그려져 있었으니, 그 영역에서는 ItemImg가 입력을 먼저 가로채고 뒤에 있는 슬롯의 UITouchReceiveComponent까지 전달되지 않았던 것임. ItemImg/ItemCnt/툴팁 패널 세 곳의 RaycastTarget을 전부 끄니 아이콘 위에서도 정상적으로 Enter/Exit가 발생함

이 발견으로 5번의 가설(Down과 Enter/Exit의 판정 방식이 다르다)이 왜 절반만 맞았는지도 설명됨: Down은 원래 RaycastTarget을 켠 자식이 있어도 부모까지 도달하는 반면(혹은 우연히 이번 케이스에서 영향이 없었던 것으로 추정), Enter/Exit는 RaycastTarget=true인 자식에 그대로 가로막힌 것. 그리고 이 원인은 훨씬 이전에 겪었던 "툴팁이 뜨자마자 바로 사라지는" self-occlusion 버그와도 사실상 같은 뿌리였음 — 툴팁 패널 자신의 RaycastTarget이 켜져 있어서, 슬롯 위에 겹쳐 그려지는 순간 슬롯의 Exit를 유발했던 것

📚 개발 참고

• 월드 좌표와 스크린 좌표 — MSW 공식 크리에이터 센터
• ImageComponent — MSW 공식 API 레퍼런스
• UITouchReceiveComponent — MSW 공식 API 레퍼런스
• ButtonStateChangeEvent — MSW 공식 API 레퍼런스

👨‍💻 오늘의 개발 작업

오늘은 크게 두 갈래로 진행함 — ① 아이템을 먹어도 아무 효과가 없던 걸 발견해서 실제 효과 적용 로직 구현, ② HP/MP/공격력/이동속도를 화면에 보여주는 스탯 UI 구현. 그 과정에서 "Sync 프로퍼티인데 게임을 켜자마자는 초기값이 화면에 안 뜨는" 버그를 만났고, 원인을 추적하다 MSW 생명주기 함수들의 보장 범위를 다시 제대로 이해하게 됨.

💡 오늘의 기록

1. 문제 발견 - 아이템 효과가 미구현 상태였음

ItemEffectData의 Apply/Revert가 전부 function(playerEntity, value) end짜리 빈 스텁이었음. 포션을 먹으면 수량은 줄어드는데 HP/MP/이동속도/공격력은 아무것도 안 바뀌는 상태. 추가로 PlayerEffect.ApplyBuff를 다시 보니, 지속시간 안에 같은 버프를 재사용하면 Revert 없이 Apply만 한 번 더 불려서 효과가 영구히 남는 실제 버그도 같이 발견함.

2. 설계 - MP/공격력은 어디에 저장해야 하나

HP(PlayerComponent.Hp)와 이동속도(MovementComponent.InputSpeed)는 엔진 네이티브 값이라 그대로 쓰면 되는데, MP와 공격력은 MSW에 대응하는 값 자체가 없었음. API 문서를 뒤져봐도 PlayerComponent에 Mp 프로퍼티가 없고, Components 목록에도 스탯 개념의 컴포넌트가 아예 없음 — MSW는 HP 외의 RPG 스탯을 제공하지 않는 범용 플랫폼이라는 걸 확인. 처음엔 기존 컴포넌트에 얹으려다, SRP 위반이라 판단해 PlayerStats라는 새 컴포넌트로 분리함.

3. Sync vs 이벤트

MP/공격력 UI 갱신 방식을 두고 "커스텀 이벤트"로 설계했다가, "그냥 Sync만 걸고 바뀐 시점만 알려주면 안 되나?"라는 생각을 함. 처음엔 "인벤토리도 이벤트 방식이니까"로 반박했는데, 다시 확인해보니 인벤토리(InventoryContainer.slots)는 애초에 table 타입이라 Sync 자체가 불가능한 자료구조였던 거고, 스칼라 값(HP/MP 등)에는 해당 안 되는 얘기였음. 원칙을 잘못 일반화하고 있었던 것.

4. OnSyncProperty 발견

Sync된 값이 바뀌었을 때 신호를 주는 방법을 고민하던 중, 넥슨 강의 스크립트에서 몬스터 체력바 예제를 확인함 — "싱크 프로퍼티"라는 콜백으로 프로퍼티 이름을 받아 분기하는 코드였음. 공식 문서에서 정확한 시그니처(OnSyncProperty(string name, any value))를 확인하고, 커스텀 이벤트 계획을 폐기하고 이걸로 통일함.

5. PlayerComponent를 Extend할 수 있는가

HP UI도 같은 패턴으로 만들려고 PlayerComponent를 Extend하려 했는데, 넥슨 공식 포럼에서 "기본 플레이어 엔티티에 이미 있는 PlayerComponent가 삭제되지 않아 적용이 안 된다"는 글을 발견. 넥슨 자체 기본 템플릿(UIMyInfo)도 OnSyncProperty 대신 OnUpdate 폴링을 쓰는 걸 보고 "Extend가 막혀있어서 그런 것"이라 결론 내리고 폴링 방식으로 설계를 바꿈. 그런데 실제로 에디터에서 시도해보니 Extend가 되는 걸 확인해서, 폴링 버전을 버리고 다시 OnSyncProperty + Extend 버전으로 되돌림.

6. 새 버그 - 초기값이 화면에 안 보임

ExtendPlayerComponent/ExtendMovementComponent/PlayerStats까지 다 붙이고 실행했는데, 게임을 막 켰을 때 HP/MP 바가 초기 상태(빈 값)로 안 그려짐. 원인은 OnSyncProperty가 "값이 실제로 바뀌는 순간"에만 호출되는 콜백이라, 최초 상태(기본값)는 애초에 "변경"이 아니라서 한 번도 안 불렸던 것.

📚 개발 참고

• MSW 기본 이벤트 함수 — MapleStory Worlds Creator Center OnSyncProperty(string name, any value)의 정확한 시그니처와 호출 시점(값이 실제로 바뀔 때만)을 확인한 문서. OnBeginPlay가 "존재는 보장하지만 다른 컴포넌트가 계산해 넣은 값은 보장 안 한다"는 차이도 여기서 확인함
• 엔티티의 생성과 삭제, 유효성 체크 — MapleStory Worlds Creator Center isvalid()가 컴포넌트 메서드가 아니라 전역 함수이고, nil까지 안전하게 처리해준다는 걸 확인한 문서

👨‍💻 오늘의 개발 작업

인벤토리 정렬(Sort) 버튼을 눌렀을 때 같은 아이템을 최대한 합치면서 재배치하도록 구현함. 기능 자체는 동작했지만, 실제 플레이 화면 스크린샷을 보니 같은 아이템 중 수량이 적은 자투리 슬롯이 맨 앞에 와 있는 걸 발견함

💡 오늘의 기록

1. 문제 상황 파악

파란 포션을 여러 번 사용/획득해 99, 99, 98개로 세 칸에 나뉜 상태에서 정렬 버튼을 눌렀더니, 정렬은 되는데 자투리(98개)가 있는 슬롯이 맨 앞 칸에 오고 꽉 찬 칸(99개)들이 그 뒤에 오는 걸 스크린샷으로 확인함. 기대한 건 꽉 찬 슬롯이 먼저 오고 자투리가 맨 뒤로 가는 것이었음

2. 원인이 된 코드

InventoryContainer.SortSlots가 병합 후 마지막에 한 번 더 정렬하는 비교 함수

table.sort(self.slots, function(a, b)
    if a.itemCnt <= 0 then return false end
    if b.itemCnt <= 0 then return true end
    return a.itemId < b.itemId
end)

3. 원인 분석

이 비교 함수는 itemId가 같으면 "동등하다"고만 판단함. 그런데 Lua의 table.sort는 불안정 정렬(unstable sort) 이라, 비교 함수가 "동등"하다고 판단한 원소들끼리는 원래 순서가 보장되지 않음. 그래서 같은 파란 포션이라도 99/99/98 세 슬롯 사이의 상대 순서는 정렬 전 배열 상태에 따라 우연히 결정되고 있었던 것 — 지금까지 자투리가 뒤로 갔던 건 우연이었을 뿐, 코드가 그렇게 보장하고 있던 게 아니었음

4. 해결

같은 아이템일 때 수량 내림차순이라는 2차 정렬 기준을 추가해, 비교 함수가 사실상 완전한 순서(total order)를 만들도록 수정함

local function CompareSlot(a, b)
    if a.itemCnt <= 0 then return false end
    if b.itemCnt <= 0 then return true end
    if a.itemId ~= b.itemId then
        return a.itemId < b.itemId
    end
    return a.itemCnt > b.itemCnt -- 같은 아이템이면 꽉 찬 슬롯이 앞, 자투리 수량은 뒤로 밀림
end

📚 성과와 개선 효과

• ✅ 불안정 정렬의 함정 이해: "같다고 판단되는 원소가 있다"는 건 그 원소들 사이의 순서가 미정의라는 뜻이고, 결과를 예측 가능하게 하려면 비교 함수 자체가 사실상 모든 경우의 우선순위를 정해줘야 한다는 걸 체감함
• ✅ 실제 사용자 화면(스크린샷) 기반 버그 발견: 로그나 콘솔이 아니라 실제 플레이 결과물을 눈으로 보고서야 잡아낸 버그라, 기능 구현 후 실제 화면으로 검증하는 과정의 중요성을 재확인함

👨‍💻 오늘의 개발 작업

아이템 사용 시 화면에 버프 아이콘(아이콘 + 카운트다운 텍스트)을 띄우는 기능을 구현함. 아이콘 자체는 잘 스폰되고 보였는데, 카운트다운 숫자만 표시가 안 되고 에러가 발생함. 스폰(복제) 직후 코드 실행 순서에 숨어있던 문제였음

💡 오늘의 기록

1. 문제 상황 파악

UIBuffPanel.ShowBuff에서 버프 아이콘 템플릿을 스폰하고, 곧바로 UIBuffIcon:Init(iconRUID, durationSec)을 호출해 아이콘 이미지와 카운트다운을 세팅하도록 구현함. 실행하니 아이콘은 보이는데 아래 에러가 발생함

[CLIENT] [LEA-2007] AttemptToIndex : 'durationText'을 인덱싱할 수 없습니다. 'durationText'은 nil입니다.
UIBuffIcon.SetDuration (at MyDesk/UIBuffIcon:32)
UIBuffIcon.Init (at MyDesk/UIBuffIcon:21)
UIBuffPanel.ShowBuff (at MyDesk/UIBuffPanel:36)

2. 원인이 된 코드

local iconEntity = _SpawnService:SpawnByEntity(self.buffIconTemplateEntity, "BuffIcon", Vector3.zero, self.buffContentEntity)
iconEntity.UIBuffIcon:Init(itemData.iconRUID, durationSec)  -- ① 먼저 호출
iconEntity:SetEnable(true)                                  -- ② 그 다음 활성화

durationText는 UIBuffIcon.OnBeginPlay에서 GetChildByName으로 찾아 채워주는 값인데, 정작 Init(①)이 활성화(②)보다 먼저 호출되고 있었음

3. 원인 분석

이 프로젝트에서 이미 확인해뒀던 사실이 있었음 — "템플릿은 평소 Enable=false라 스폰된 복제본도 비활성 상태로 시작하고, OnBeginPlay는 SetEnable(true)로 활성화된 뒤에야 실행된다." 즉 ①번 시점엔 OnBeginPlay가 아직 안 돌아서 durationText가 nil인 채로 남아있었고, 그 상태에서 SetDuration이 durationText.Text = ...를 시도하다 터진 것

4. 해결

활성화와 데이터 주입 순서를 맞바꿈

local iconEntity = _SpawnService:SpawnByEntity(self.buffIconTemplateEntity, "BuffIcon", Vector3.zero, self.buffContentEntity)
iconEntity:SetEnable(true)
iconEntity.UIBuffIcon:Init(itemData.iconRUID, durationSec)

📚 성과와 개선 효과

• ✅ 스폰 직후 초기화 패턴 확립: "템플릿이 비활성 상태로 스폰되고, 활성화 시점에 OnBeginPlay가 실행된다"는 조건이 있는 프로젝트에서는, 스폰 → 활성화 → 데이터 주입 순서를 항상 지켜야 한다는 걸 명문화함
• ✅ 에러 로그로 호출 스택을 역추적하는 습관: SetDuration → Init → ShowBuff 순으로 찍힌 스택을 거슬러 올라가며 "어디서 최초로 nil이 만들어졌는가"를 찾는 방식으로 원인을 좁힘

👨‍💻 오늘의 개발 작업

인벤토리 슬롯을 더블클릭하면 아이템을 사용하도록 UITouchDownEvent 기반 더블클릭 판정 로직을 구현함. 코드 자체는 문법 오류를 다 고친 상태였는데도 클릭에 아무 반응이 없었고, 로그 한 줄조차 찍히지 않았음. 여러 층의 가설을 세우고 하나씩 좁혀가다, 이름이 비슷한 컴포넌트를 잘못 붙였다는 사소하지만 결정적인 실수를 마지막에 확인함.

💡 오늘의 기록

1. 문제 상황 파악

UIItemSlot에 HandleUITouchDownEvent 핸들러를 만들고, TouchId == -1일 때 직전 클릭 시각과 비교해 더블클릭이면 RequestUseItem을 호출하도록 구현함. 슬롯을 더블클릭해도 수량 변화도, 에러도, 아무 로그도 없었음

2. 1차 가설 - 실행 공간(ExecSpace) 문제

핸들러에 @ExecSpace("ClientOnly")를 명시적으로 붙였는데도 반응이 없어서, 혹시 이 태그 자체가 핸들러엔 안 맞는 문법이거나 조용히 무시되는 게 아닌지 의심함. 핸들러 맨 위에 무조건 찍히는 임시 로그를 추가해 확인하기로 함

handler HandleUITouchDownEvent(UITouchDownEvent event)
log("[UIItemSlot] 터치 이벤트 도달! TouchId=" .. tostring(event.TouchId))  -- 임시 디버그용
...

이 로그조차 안 찍혀서, 핸들러 코드 문제가 아니라 이벤트 자체가 이 엔티티까지 안 오고 있다는 게 확인됨

3. 2차 가설 - ButtonComponent가 입력을 가로채고 있다

슬롯 엔티티에 이미 ButtonComponent가 붙어있었던 걸 확인하고, 이게 터치 입력을 먼저 소비해서 UITouchDownEvent 자체가 발생 안 하는 것으로 의심함. 공식 문서에서 두 컴포넌트의 상호작용에 대한 명시적인 설명은 찾지 못해, ButtonComponent를 아예 떼고 UITouchReceiveComponent만 남기는 방향으로 진행하기로 함

4. 결정적 확인 - 예전에 검증됐던 원본 코드와 대조

이전에 비슷한 더블클릭 로직을 만들어봤던 다른 프로젝트의 원본 스크립트를 다시 찾아보니, 핸들러의 실행 공간 설정이 지금과 다르게 Scope: 0, ExecSpace: 0(사용하지 않음)으로 되어 있었음. UITouchDownEvent 자체가 클라이언트에서만 발생하는 이벤트라 핸들러에 실행 공간을 강제로 태깅할 필요가 없었던 것

5. 근본 원인 확정

여러 가설을 검토하던 중 실제로 확인해보니, 슬롯 엔티티에 붙인 게 UITouchReceiveComponent가 아니라 TouchReceiveComponent(접두사 UI 누락)였음. 이름이 비슷해서 붙일 때는 맞게 붙인 줄 알았지만, UITouchDownEvent를 발신하는 건 UITouchReceiveComponent뿐이라 다른 컴포넌트를 붙인 이상 이벤트 자체가 발생할 수 없었던 것. ButtonComponent 충돌이나 ExecSpace 설정은 전혀 문제가 아니었음

6. 해결

슬롯 엔티티에 붙어있던 TouchReceiveComponent를 떼고 UITouchReceiveComponent로 교체하자 즉시 더블클릭 감지 및 아이템 사용이 정상 동작함

📚 성과와 개선 효과

• ✅ 디버깅 우선순위 교훈: "에러도 없이 조용히 아무 일도 안 일어난다"는 증상을 마주하면, 복잡한 가설(컴포넌트 간 충돌, 실행 공간 설정 등)로 바로 들어가기 전에 "이 이벤트를 발신하는 컴포넌트가 정확히 그 이름/타입으로 붙어있는가" 같은 가장 기본적인 전제부터 확인하는 게 우선순위가 더 높다는 걸 체감함 (이름이 비슷한 컴포넌트끼리는 특히 더)
• ✅ 격리된 디버그 로그의 가치: 핸들러 맨 위에 무조건 찍히는 로그 한 줄이 "코드 문제 vs 이벤트 미도달 문제"를 즉시 갈라줌 — 이후 다른 이슈에서도 같은 패턴을 재사용함

👨‍💻 오늘의 개발 작업

아이템 획득 방식으로 확정한 "디버그 버튼 패널"을 구현함. 스크롤에 나열된 아이템 아이콘을 클릭해 선택하고, 수량을 입력한 뒤 추가 버튼을 누르면 서버에 RPC 요청을 보내 인벤토리에 반영하는 흐름. 기존에 만들어둔 UIItemSlot(아이콘 렌더링 컴포넌트)을 그대로 재사용하는 구조로 설계했는데, 이 과정에서 엔진 API를 다루는 방식과 리소스 자체의 한계에서 비롯된 문제 세 가지를 순서대로 만남.

💡 오늘의 기록

1. ConnectEvent는 Component가 아니라 Entity의 메서드였다

현상: 추가 버튼의 클릭 이벤트를 연결하려는데 실행하자마자 에러가 뜸.

AttemptToCall : 'ConnectEvent'을 호출할 수 없습니다. 'ConnectEvent'은 nil입니다.

처음엔 버튼을 아래처럼 받고 있었음:

property ButtonComponent addButtonComp = nil
...
self.addButtonComp:ConnectEvent(ButtonClickEvent, function() self:OnClickAddButton() end)

조사 과정: self.addButtonComp == nil 방어 코드는 이미 통과한 상태라, 인스펙터 연결 자체는 문제가 없었음. 즉 "연결이 안 된 것"이 아니라 "연결된 컴포넌트에 그 메서드가 없는 것"으로 원인을 좁힘. MSW에서는 하나의 오브젝트가 엔티티(Entity) 하나에 여러 컴포넌트가 얹히는 구조인데, 이벤트 구독을 위한 ConnectEvent는 각 컴포넌트가 아니라 엔티티 자신에게 있는 메서드라는 걸 확인함. 클릭 이벤트를 발생시키는 주체는 ButtonComponent이지만, 그 이벤트를 "구독"하는 진입점은 엔티티 쪽으로 통일되어 있는 구조였던 것.

해결: 프로퍼티 타입 자체를 Entity로 바꾸고, 인스펙터에서도 컴포넌트가 아니라 엔티티 자체를 다시 연결함.

property Entity addButtonEntity = nil
...
self.addButtonEntity:ConnectEvent(ButtonClickEvent, function() self:OnClickAddButton() end)

같은 실수가 아이템 버튼을 동적 생성하는 루프(CreateItemButtons) 안에도 있었어서 함께 수정함.

교훈: 다른 엔진(예: Unity, Unreal)에서 "버튼 컴포넌트에 리스너를 붙인다"는 습관이 있으면, MSW에서도 무의식중에 컴포넌트 타입으로 프로퍼티를 받기 쉬움. 하지만 이 엔진은 이벤트 구독의 주체가 컴포넌트가 아니라 엔티티라는 점이 명확히 달랐음.

2. RPC 요청 메서드의 ExecSpace를 Server로 지정해야 하는 이유

현상: 서버 검증 로직 자체는 이미 완성해뒀는데, 클라이언트에서 버튼을 눌러 호출하자 다시 nil 에러가 뜸.

AttemptToCall : 'RequestAddItemFromButton'을 호출할 수 없습니다. 'RequestAddItemFromButton'은 nil입니다.

당시 이 메서드는 ServerOnly로 선언되어 있었음:

@ExecSpace("ServerOnly")
method void RequestAddItemFromButton(integer itemId, integer amount)
    self:AddItem(itemId, amount)
end

조사 과정: ExecSpace 옵션(사용하지 않음/Client/ClientOnly/Server/ServerOnly/Multicast)의 의미를 다시 짚어봄. ServerOnly는 그 메서드 자체가 서버 공간에만 존재한다는 뜻이라, 클라이언트 스크립트 입장에서는 애초에 그런 이름의 메서드가 없는 것과 같음(그래서 "실행 실패"가 아니라 "이름 자체가 nil"로 나타남). 반면 Server는 클라이언트에서 호출하되 실제 실행은 서버에서 되도록 RPC로 전달해주는 옵션이라는 걸 확인함. 지금 필요한 건 "클라이언트 버튼 클릭 → 서버 실행"이었으므로 Server가 맞는 선택이었음.

해결:

@ExecSpace("Server")
method void RequestAddItemFromButton(integer itemId, integer amount)
    -- 검증 없이 AddItem으로 위임 (검증은 AddItem(ServerOnly)이 전담)
    self:AddItem(itemId, amount)
end

교훈: "서버에서만 실행되어야 한다"는 요구사항과 "클라이언트에서 호출 가능해야 한다"는 요구사항은 서로 다른 축이라, ServerOnly와 Server를 목적에 맞게 구분해서 써야 함. 클라이언트가 진입점으로 삼는 Request* 계열 메서드는 전부 Server, 실제 검증/처리를 전담하는 내부 메서드는 ServerOnly로 나누는 패턴을 이후 다른 기능(정렬/합치기/삭제)에도 동일하게 적용함.

3. 장비 아이템 아이콘만 안 뜨는 문제

현상: 소비 아이템(포션 등)은 아이콘이 정상적으로 표시되는데, 장비 아이템만 아이콘이 안 뜸. 에러나 경고 로그도 전혀 없이 그냥 빈 칸으로 보임.

조사 과정: 에러가 없다는 게 오히려 단서였음. 먼저 다음 가설들을 하나씩 배제함.

• *"itemCnt가 0이라 SetEmpty 처리된 게 아닐까?"* → 디버그 버튼은 itemCnt를 무조건 1로 고정해서 넘기는 구조라 배제.
• *"장비는 스택이 1개뿐이라 어딘가에서 걸러지는 게 아닐까?"* → 코드 전체를 봐도 스택 관련 필터링 로직 자체가 없어서 배제.
• *"RUID 형식이 다른 게 아닐까?"* → 소비 아이템과 장비 아이템의 RUID를 나란히 비교했으나(둘 다 32자리 동일 형식) 형식 차이는 없었음.
• 직접 테스트: 빈 엔티티에 SpriteGUIRendererComponent를 붙이고 장비 RUID를 인스펙터에서 직접 넣어봐도 안 뜸 → 코드 문제가 아니라 리소스 자체의 문제로 좁힘.

여기서 Claude를 통해 문제 원인을 찾아보다가 유사한 사례를 다룬 글을 발견함. 다만 그 글을 지금 다시 확인할 수 있는 링크는 아니라서, 확정된 근거로 삼기보다는 추정으로만 남김: 장비 아이템만 아이콘이 안 뜨고 에러 로그도 없다는 것, 그리고 리소스 종류(착용용/아이콘용)의 차이가 원인일 가능성이 있다는 것까지가 이번에 확인한 전부임.

해결: 실제 착용용 리소스 대신, MSW의 "기타 아이템" 카테고리 리소스 중 옷/무기처럼 생긴 이미지를 찾아 아이콘으로 대체 적용함.

📚 성과와 개선 효과

• ✅ 엔진 API의 책임 소재 구분: 이벤트 구독(ConnectEvent)은 엔티티, 이벤트를 발생시키는 로직은 컴포넌트라는 역할 분리를 명확히 이해함
• ✅ ExecSpace 선택 기준 확립: "서버 전용 실행"과 "클라이언트에서 호출 가능한 RPC"는 다른 옵션이라는 걸 실제 에러로 체감하고, 이후 Request*/내부 처리 메서드 쌍 패턴을 전 기능에 일관되게 적용

👨‍💻 오늘의 개발 작업

인벤토리 슬롯 24개를 풀링 방식으로 스폰해 테스트하던 중, 빈 슬롯인데도 텍스트가 계속 표시되는 이상 현상을 발견함. 표면적 증상 뒤에 원인이 두 겹으로 겹쳐 있었고, 하나를 걷어내자 그 아래 진짜 문제가 드러났음. 최종적으로 이 엔진의 스폰(복제) API가 컴포넌트 참조를 다루는 방식 자체에 있는 비직관적인 함정을 찾아냄

💡 오늘의 기록

1. 문제 상황 파악

inventoryCapacity(24)만큼 슬롯을 미리 스폰해두고 재사용하는 구조로 설계함. 슬롯 템플릿(Scroll_Image)엔 아이콘(ItemImg)과 수량 텍스트(ItemImg/ItemCnt)가 자식으로 있고, UIItemSlot 컴포넌트가 이를 인스펙터에서 Component 타입 프로퍼티로 미리 연결해두는 방식으로 짜여있었음

테스트 결과: 아이템이 하나도 없는 빈 상태인데도 슬롯마다 텍스트가 계속 보임

2. 1차 조사 - "슬롯 1개만 다르다"의 원인은 안 꺼진 원본 템플릿

"첫 번째 슬롯만 텍스트가 안 보이고 나머지는 다 보인다"는 걸 발견하고, 스폰용 원본 템플릿(Scroll_Image)의 Enable이 꺼져있지 않아서 실제로는 24개가 아니라 25개(원본 1 + 스폰본 24)가 떠 있는 것 아닌지 의심함. 직접 확인해보니 맞았음 — Scroll_Image를 Enable=false로 끄니 정확히 24개로 줄어듦. 원본은 한 번도 Refresh()를 거친 적이 없어서 에디터에서 마지막으로 남겨뒀던 상태(우연히 텍스트가 꺼져있던 상태)를 그대로 보여주고 있었을 뿐, 실제 스폰된 24개와는 무관한 별개의 원인이었음

3. 원본을 제거하니 드러난 진짜 문제 - 24개 전부 텍스트가 보임

원본 템플릿을 끄고 나니, "일부만 이상하다"는 착시가 사라지고 스폰된 24개 전부가 똑같이 텍스트를 잘못 보여주고 있다는 게 명확해짐. 처음 발견했던 "슬롯 1개만 다르다"는 현상은 원본 템플릿이라는 별개의 원인 때문이었고, 그걸 걷어내고 나서야 그 아래 숨어있던 진짜 문제(24개 전체에 공통으로 걸린 버그)가 드러난 것

4. 결정적 단서 - 각 슬롯의 참조 경로를 직접 로그로 확인

슬롯마다 실제로 어떤 텍스트 컴포넌트를 참조하고 있는지, 그 엔티티 경로를 직접 찍어봄

method void Refresh(integer slotIdx, integer itemId, integer itemCnt)
-- ⚠️ 임시 테스트 코드
local path = "nil"
if self.cntText ~= nil then
    path = self.cntText.Entity.Path
end
log("[TEST] slotIdx=" .. tostring(slotIdx) .. " cntText 경로=" .. path)
-- ⚠️ 여기까지
...

결과: slotIdx=1인데 경로가 .../Scroll_Layout/Scroll_Image/ItemImg/ItemCnt — 원본 템플릿의 경로 그대로였음. 스폰된 복제본(Slot_1)의 참조인데, 원본(Scroll_Image)을 가리키고 있었던 것

5. 근본 원인 확정

인스펙터에서 Component 타입 프로퍼티(예: property TextComponent cntText)를 드래그로 미리 연결해두면, 이 값은 "그 특정 컴포넌트 인스턴스"에 대한 하드 레퍼런스로 저장됨. 그런데 _SpawnService:SpawnByEntity로 엔티티를 복제할 때, 이 프로퍼티 값은 복제본 자신의 새로운 자식으로 재배선되지 않고, 원본이 가리키던 참조를 그대로 복사해버림

그 결과 스폰된 24개 슬롯의 cntText가 전부 원본 템플릿의 텍스트 컴포넌트 단 하나를 공유하게 됨. 매번 RefreshSlot을 호출할 때마다 사실상 같은 객체를 24번 덮어쓰는 셈이었고(그마저도 원본은 Enable=false라 화면에 안 보임), 정작 화면에 보이는 각 복제본 고유의 텍스트는 한 번도 코드로 제어된 적 없이 에디터에서 마지막으로 넣어둔 플레이스홀더 값 그대로 남아있었던 것

6. 해결 - 인스펙터 배선 폐기, 런타임 조회로 전환

OnBeginPlay에서 자기 자신의 하이라키를 GetChildByName으로 직접 탐색해 할당하는 방식으로 변경함. 이러면 복제본마다 각자 자기 자식을 찾으므로 문제가 없음

@ExecSpace("ClientOnly")
method void OnBeginPlay()
local iconEntity = self.Entity:GetChildByName("ItemImg")
if iconEntity == nil then
    log_error("[UIItemSlot] ItemImg 자식을 찾을 수 없음")
    return
end
self.iconImage = iconEntity.SpriteGUIRendererComponent

local cntEntity = iconEntity:GetChildByName("ItemCnt")
if cntEntity == nil then
    log_error("[UIItemSlot] ItemCnt 자식을 찾을 수 없음")
    return
end
self.cntText = cntEntity.TextComponent
end

📚 성과와 개선 효과

• ✅ 비직관적인 엔진 제약 발견: "인스펙터로 미리 연결해둔 컴포넌트 참조는 스폰 복제 시 재배선되지 않는다"는, 문서화되어 있지 않던 동작을 실측으로 확인
• ✅ 재사용 가능한 규칙 확립: 앞으로 스폰되는 모든 프리팹(슬롯, 디버그 버튼 등)에 "자식 컴포넌트 참조가 필요하면 인스펙터 배선 대신 OnBeginPlay + GetChildByName 런타임 조회"라는 원칙을 세워 재사용

📚 개발 참고

공식 문서에서 명시적으로 확인된 내용은 아니며, 실측 테스트(스폰된 인스턴스의 컴포넌트 소유 엔티티 경로를 직접 로그로 추적)를 통해 확인한 엔진 동작임. 별도 참고 문서 없음

👨‍💻 오늘의 개발 작업

인벤토리 UI(슬롯 렌더링)를 테스트하다가 아이콘이 전혀 표시되지 않는 문제를 발견함. 처음엔 단순 배선 실수인 줄 알았으나, 파고들수록 "서버 권위 원칙을 어디까지 적용해야 하는가"라는 설계 판단 문제와, "서버-클라이언트 간 초기화 순서는 보장되지 않는다"는 구조적 문제, 두 겹으로 얽힌 이슈였음을 확인함

💡 오늘의 기록

1. 문제 상황 파악

인벤토리를 열면 슬롯은 정상적으로 생성되는데, 아이템을 넣어도 아이콘이 뜨지 않음. UIItemSlot.SetItem에서 _ItemData.itemTable[itemId]를 조회해 아이콘 리소스를 가져오는 구조인데, 여기서 뭔가 어긋나고 있다고 추정함

2. 1차 원인 확인 - _ItemData가 클라이언트에서 아예 로드되지 않음

바로 코드를 고치기 전에, 실제로 클라이언트 쪽 _ItemData 상태가 어떤지부터 로그로 직접 확인함

-- UIInventory.OnBeginPlay에 임시로 삽입
log("[TEST] 클라 isInitialized = " .. tostring(_ItemData.isInitialized))
log("[TEST] 클라 itemTable 데이터 있음 = " .. tostring(next(_ItemData.itemTable) ~= nil))

결과: 둘 다 false. ItemData.OnBeginPlay가 ServerOnly로 설정돼있어서, 클라이언트 쪽 _ItemData 인스턴스는 애초에 OnBeginPlay 자체가 실행된 적이 없었고, 그래서 초기값({}, false)에 계속 머물러 있었던 것

3. 설계 판단 - 마스터 데이터를 클라이언트에서 직접 로드해도 되는가

ExecSpace를 바꾸기 전에, 이게 서버 권위 원칙을 깨는 건 아닌지부터 짚어봄

• 서버 권위가 지켜야 하는 건 "플레이어가 실제로 무엇을 얼마나 갖고 있는가" 같은 개별 상태값 (예: PlayerInventory의 슬롯 데이터)
• ItemData.itemTable은 "이 게임에 어떤 아이템이 존재하고, 아이콘/이름/최대스택이 뭔지" 같은 정적 정의(마스터 데이터)
• 이건 애초에 숨길 이유가 없는 공개 정보임 — 클라이언트 UI가 아이콘을 그리려면 어차피 클라가 이 정보를 들고 있어야 하고, 서버가 숨긴다 해도 결국 화면에 다 드러나는 정보라 숨길 실익이 없음

→ "숨겨야 하는 상태값" vs "공개돼도 되는 규칙 정의"를 구분하는 기준을 세우고, ItemData.OnBeginPlay의 ExecSpace를 ServerOnly → "사용 안 함"(제한 없음)으로 변경. 서버/클라가 각자 독립적으로 같은 CSV를 읽어 itemTable을 캐싱하게 됨(네트워크 전송이 아니라 각자 로드하는 방식이라 서버 부하나 보안 노출도 없음)

4. 그런데 여전히 남아있는 문제 - 초기화 순서 레이스 컨디션

ExecSpace를 고쳐도, "서버가 보낸 인벤토리 이벤트가 클라이언트 자신의 _ItemData 로딩 완료보다 먼저 도착할 수 있다"는 문제는 그대로 남음. 서버의 _ItemData 완료 여부와 클라이언트의 _ItemData 완료 여부는 완전히 별개의 비동기 프로세스라서, 어느 쪽이 먼저 끝날지 보장할 방법이 없음

5. 해결 - 서버 쪽에서 이미 쓰던 방어 패턴을 클라이언트에 대칭 적용

사실 이 문제는 처음이 아니었음. PlayerInventory(서버)도 ItemData(Logic)와의 OnBeginPlay 순서가 보장 안 돼서, 이미 아래 패턴으로 방어하고 있었음

-- PlayerInventory.OnBeginPlay (서버, 기존 코드)
if _ItemData.isInitialized then
    self:InitInventory()
end
-- 아직이면 아무것도 안 함 — HandleOnItemDataInitialized가 늦게 온 초기화 완료를 대신 처리

같은 구조를 클라이언트(UIInventory)에도 그대로 대칭 적용함. 다만 서버 쪽은 "초기화를 지연시키는" 방식이었다면, 클라이언트 쪽은 이미 들어온 슬롯 데이터를 버릴 수 없어서 "캐시해두고 나중에 몰아서 그리는" 방식으로 변형함

method void ApplySlotData(integer slotIdx, integer itemId, integer itemCnt)
-- pendingSlots 캐시엔 무조건 기록. _ItemData가 아직 준비 안 됐으면 렌더링은 건너뛰고
-- 나중에 HandleOnItemDataInitialized가 캐시 전체를 몰아서 그림
self._T.pendingSlots = self._T.pendingSlots or {}
self._T.pendingSlots[slotIdx] = { itemId = itemId, itemCnt = itemCnt }

if _ItemData.isInitialized then
    self:RefreshSlot(slotIdx, itemId, itemCnt)
end
end

@EventSender("Logic", "ItemData")
handler HandleOnItemDataInitialized(OnItemDataInitialized event)
-- _ItemData가 인벤토리 이벤트보다 늦게 준비된 경우 대비: 캐시된 전체 슬롯을 한꺼번에 렌더링
if self._T.pendingSlots == nil then return end
for slotIdx, slotData in pairs(self._T.pendingSlots) do
    self:RefreshSlot(slotIdx, slotData.itemId, slotData.itemCnt)
end
end

6. 검증 범위

이 방어 로직이 실제로 "아직 준비 안 된 상태"를 캐치해 렌더링을 미룬 사례를 로그로 직접 관측하진 못함 — 어디까지나 "타이밍이 보장 안 되니 생길 수 있는 상황"이라는 논리적 추론에 따라 미리 방어적으로 설계한 것. 참고로 테스트 도중 OnInventoryModified 이벤트가 Initialized보다 먼저 도착함 경고를 본 적은 있으나, 이건 별개의 원인 — 임시 테스트 코드에서 BroadcastInitialized()보다 AddItem()을 먼저 호출해 생긴 순서 실수였고 _ItemData 로딩 타이밍과는 무관함

📚 성과와 개선 효과

• ✅ 원인 특정: 추측 대신 상태값을 직접 로그로 찍어서 "클라에서 로드가 아예 안 되고 있다"는 사실을 먼저 확정한 뒤 수정에 들어감
• ✅ 설계 기준 확립: "서버 권위로 지켜야 할 상태"와 "공개돼도 되는 규칙 정의"를 구분하는 기준을 세워, 이후 비슷한 판단(다른 마스터 데이터 추가 시)에도 재사용 가능
• ✅ 구조적 일관성: 서버/클라 양쪽에 동일한 "초기화 순서 미보장 대응 패턴"을 대칭적으로 적용해, 앞으로 이런 종류의 Logic-Component 간 로딩 순서 문제가 생겨도 같은 패턴을 재사용할 수 있음

📚 개발 참고

이번 트러블슈팅은 특정 공식 문서보다는, 서버 권위 원칙의 적용 범위(상태값 vs 규칙 정의)를 직접 판단하며 진행함. 별도 참고 문서 없음

👨‍💻 오늘의 개발 작업

인벤토리 정렬(SortSlots) 기능을 검토하다가, 지금 구현이 "슬롯 순서만 바꿀 뿐, 여러 슬롯에 흩어진 같은 아이템을 합쳐주지 않는다"는 걸 뒤늦게 발견함. 이를 보완하는 과정에서 처음 접근(이중 루프)이 비효율적이라는 걸 깨닫고, 알고리즘을 다시 설계해 시간복잡도를 개선함. 더불어 이 로직을 어느 컴포넌트가 소유해야 하는지에 대한 책임 소재 문제까지 같이 정리함

💡 오늘의 기록

1. 문제 상황 파악

기존 SortSlots()는 itemId 오름차순으로 슬롯을 정렬하고 빈 슬롯을 뒤로 몰아주는 기능만 있었음

table.sort(self.slots, function(a, b)
    if a.itemCnt <= 0 then return false end
    if b.itemCnt <= 0 then return true end
    return a.itemId < b.itemId
end)

문제는, 같은 아이템이 포션이 3번/7번/15번 슬롯처럼 여러 슬롯에 나뉘어 있는 경우 정렬을 해도 "순서만 옆으로 나란히" 될 뿐, 슬롯 3개를 여전히 차지하고 있다는 점. 실제 게임에서 "정렬" 버튼을 누르면 합칠 수 있는 건 합쳐서 빈 칸을 확보해주는 게 일반적인 기대 동작인데, 이 부분이 빠져있었음

2. 첫 번째 접근 - 이중 루프 방식 (기각)

처음엔 모든 슬롯 쌍을 비교하며 같은 아이템끼리 합치는 방식으로 접근함

-- i,j 이중 루프로 모든 슬롯 쌍을 비교하며 병합
for i = 1, self.slotCnt do
    local slot = self.slots[i]
    if slot.itemCnt > 0 then
        for j = i + 1, self.slotCnt do
            local otherSlot = self.slots[j]
            if otherSlot.itemId == slot.itemId and otherSlot.itemCnt > 0 then
                self:MergeSlot(j, i, maxStack)
            end
        end
    end
end

기각한 이유

• 슬롯 개수를 n이라 하면 이 방식은 O(n²). 슬롯 규모(수십 개) 자체는 작아서 실질적 성능 문제는 크지 않을 수 있지만, 굳이 더 간단하고 빠른 방법이 있는데 이걸 쓸 이유가 없음

3. 두 번째 접근 - 정렬 후 인접 병합으로 전환 (O(n))

"정렬을 먼저 하면 같은 아이템이 어차피 옆으로 붙는데, 그럼 인접한 것끼리만 한 번 훑으면 되지 않나?"라는 관점으로 다시 설계함

-- 1차 정렬로 같은 아이템을 인접시킨 뒤, writeIdx/readIdx 투 포인터로 한 번만 스캔
local writeIdx = 1
for readIdx = 2, self.slotCnt do
    local readSlot = self.slots[readIdx]
    if readSlot.itemCnt <= 0 then
        break -- 정렬 후 빈 슬롯은 전부 뒤로 몰려있으므로 여기부터는 전부 빈 슬롯
    end

    local writeSlot = self.slots[writeIdx]
    if writeSlot.itemId == readSlot.itemId then
        self:MergeSlot(readIdx, writeIdx, maxStack)
        if readSlot.itemCnt > 0 then
            writeIdx = readIdx -- writeIdx가 가득 차서 남은 수량이 있으면 readIdx가 새 병합 대상
        end
    else
        writeIdx = readIdx -- 다른 아이템 종류 시작
    end
end

정렬(O(n log n)) + 한 번의 선형 스캔(O(n))으로, 이중 루프 없이 같은 결과를 얻을 수 있게 됨

4. 세부 최적화 - 압축 후 생기는 빈 슬롯 처리

병합을 하면 슬롯 중간중간에 빈 자리가 생김(예: [A:30, 빈칸, 빈칸, B:28, 빈칸]). 이걸 다시 뒤로 밀어야 완전히 압축된 결과가 나오는데, 별도의 O(n) "당기기" 로직을 새로 짜는 대신 이미 있는 SortSlots를 한 번 더 호출하는 방식을 채택함

table.sort(self.slots, function(a, b) ... end) -- 1차: 인접시키기
-- ... 압축 루프 ...
table.sort(self.slots, function(a, b) ... end) -- 2차: 압축으로 생긴 빈 슬롯 마무리

정렬이 O(n log n)이라 슬롯 규모(수십 개)에서 두 번 돌아도 비용이 무시할 수준이라, 별도 로직을 추가하는 복잡성보다 이 방식이 더 실용적이라 판단함

추가로, "비어있는지"를 정렬 전에 확인해서 아예 정렬 자체를 건너뛰는 최적화도 검토함. 다만 정렬 전에는 "빈 슬롯이 뒤로 몰려있다"는 전제가 아직 성립하지 않아서, 1번 슬롯만 보고 판단할 수 없고 전체를 훑어야(O(n)) 함. 슬롯 규모가 작아 이 전체 스캔을 추가하는 이득이 거의 없다고 보고, 결국 "정렬 후 1번 슬롯만 확인"하는 원래 방식을 유지함

5. 아키텍처 재조정 - 이 로직을 누가 가져야 하는가

압축 로직에 필요한 maxStack(아이템별 최대 스택 수)은 Container가 모르는 외부 정보라서, 처음엔 이 로직을 호출부(PlayerInventory)에 직접 구현했음. 그런데 이렇게 두면 슬롯을 직접 조작하는 로직이 Container 밖으로 새어나가는 셈이라 SRP에 어긋난다는 걸 깨달음

maxStack 하나씩 개별 전달하는 대신, "이번에 등장한 아이템들의 itemId → maxStack 대응표(maxStackTable)"를 통째로 넘기는 방식으로 바꿔서, Container가 여전히 아이템 메타데이터의 출처(_ItemData)를 몰라도 전체 정렬+압축 과정을 스스로 소유할 수 있게 재조정함

-- Container가 소유 (PlayerInventory는 maxStackTable만 만들어서 넘김)
method void SortSlots(table maxStackTable)
    -- 정렬 + 압축 + 마무리 정렬 전부 여기서 처리
end

별도 메서드(SortAndCompact)로 새로 만들려고도 했으나, "정렬은 원래 같은 아이템을 최대한 합치면서 재배치한다"는 게 이 장르의 인벤토리에서 '정렬'이 의미하는 바 자체라는 걸 되짚고, 기존 SortSlots에 매개변수 하나(maxStackTable)만 추가해 통합하는 쪽으로 최종 결정함

Container가 _ItemData(전역 싱글턴)를 직접 참조하면 안 되는 이유도 이 참에 다시 정리함:

-- 만약 Container가 이렇게 짜여있다면
method void AddItem(itemId, amount)
    local maxStack = _ItemData.itemTable[itemId].maxStack  -- 전역 싱글턴 직접 참조
    -- ...
end

이 코드는 _ItemData라는 이름의 Logic이 그 월드 어딘가에 반드시 존재해야만 실행 가능함. Container 혼자서는 절대 못 돌아감. 왜 문제가 되는지 세 가지로 정리함

1. 독립적으로 테스트/재사용할 수 없음 — InventoryContainer()를 만들어서 슬롯 계산 로직만 따로 검증하고 싶어도, _ItemData(전체 아이템 테이블을 CSV에서 로드하는 무거운 싱글턴)가 먼저 초기화돼 있어야만 동작함. "슬롯에 아이템을 넣고 빼고 정렬하는 순수 계산 로직"을 확인하는 데 "게임 전체 아이템 데이터베이스"까지 딸려와야 하는 건 부담스러운 의존성임
2. 서비스 로케이터(Service Locator) 패턴이 됨 — _ItemData처럼 어디서든 접근 가능한 전역 참조를, 코드 내부 아무 데서나 끌어다 쓰는 방식은 의존성이 코드 표면에 안 드러나고 숨어있는 패턴임. AddItem(itemId, amount)만 봐서는 이 메서드가 _ItemData에 의존한다는 걸 알 수 없음 — 함수 몸통을 다 읽어봐야 알 수 있음. 반면 AddItem(itemId, amount, maxStack)처럼 매개변수로 받으면, 함수 시그니처만 봐도 "이 함수가 뭘 필요로 하는지"가 그대로 드러남
3. 데이터 출처가 바뀔 가능성에 대비 — 지금은 _ItemData가 CSV 기반이지만, 나중에 "이벤트 기간 한정 아이템은 다른 테이블에서 온다"거나 "테스트용 목업 데이터로 바꿔서 실행해보고 싶다" 같은 상황이 생기면, Container가 _ItemData를 직접 알고 있으면 그 변경이 Container 코드까지 건드리게 됨. 매개변수로 받으면 Container는 "누가 무슨 값을 주든" 신경 안 써도 되니 이런 변화에 영향을 안 받음

6. 성과와 개선 효과

• ✅ 시간복잡도 개선: 이중 루프(O(n²)) → 정렬+선형스캔(O(n log n) + O(n))
• ✅ 책임 분리(SRP) 재정비: 슬롯을 직접 조작하는 로직 전부 Container로 이전, PlayerInventory는 필요한 외부 정보(maxStackTable)를 모아 넘기는 오케스트레이션 역할만 남음
• ✅ DIP 유지: Container는 여전히 _ItemData를 직접 모른 채로 정렬+압축을 전부 처리 가능
• ✅ 개념적 일관성 확보: "정렬"과 "합치기"를 억지로 나눈 두 개의 API가 아니라, 원래 하나였던 개념("정렬 = 합치면서 재배치")에 맞게 기존 API 하나로 통합

📚 개발 참고

이번 트러블슈팅은 특정 공식 문서를 근거로 삼기보다, 알고리즘 시간복잡도와 책임 분리 원칙(SRP/DIP)을 직접 검토하며 진행함. 별도 참고 문서 없음

👨‍💻 오늘의 개발 작업

인벤토리 컨테이너(InventoryContainer)의 AddItem/MergeSlot 메서드를 구현하면서, "성공 여부"와 "실제 처리된 수량"을 동시에 반환해야 하는데 에디터가 경고를 띄우는 문제를 발견하고 해결했음

💡 오늘의 기록

1. 문제 상황 - 리턴값 두 개를 반환하려다 발생한 경고

AddItem은 인벤토리가 가득 차서 일부만 추가된 경우를 호출부가 구분할 수 있어야 해서, 처음엔 값을 두 개 반환하도록 짰음

-- AddItem 내부
return isFullySucceeded, totalAdded  -- success, amount 두 값 반환

Lua는 애초에 return a, b처럼 값 여러 개를 한 번에 반환하는 걸 언어 차원에서 기본 지원한다. 그래서 이 문법 자체를 쓰는 데는 아무 문제가 없다고 생각하고 그대로 짰음

문제는 MSW 에디터에서 메서드를 정의할 때, Return 타입 설정란은 boolean 하나만 선택해둔 상태였다는 것. 매개변수는 "Add Parameter" 버튼으로 여러 개를 자유롭게 추가할 수 있어서, Return도 당연히 같은 방식으로 여러 개 선언할 수 있을 거라 생각했는데, 실제로 확인해보니 Return 쪽에는 그 "추가" 버튼 자체가 없었음

그 상태로 호출부에서 값 두 개를 받으니 에디터가 경고를 띄웠음

local success, addedAmount = self._T.container:AddItem(itemId, amount, maxStack)
-- ⚠️ 리턴값이 1개인데 변수 2개에 할당하려 함

2. 해결 과정 - 경고의 정체를 실측으로 확인 ⚠️

경고가 뜨는 게 "정말 두 번째 값이 유실된다"는 뜻인지, 아니면 "타입 선언과 실제 반환 개수가 안 맞는다"는 정적 경고일 뿐인지가 불확실했음. Lua 언어 자체는 다중 반환을 지원하는 게 맞지만, MSW의 mLua 에디터가 메서드 하나당 함수 몸통(Code)만 코드로 작성하고, 실제 함수 시그니처(function Name(...))는 에디터가 Name/Arguments/Return 설정을 조합해 자동으로 생성하는 구조라, 이 자동 생성된 시그니처가 선언된 Return 타입 개수로 강제되는지가 관건이었음

말로 추측하지 않고 별도의 임시 테스트 컴포넌트를 만들어 직접 실측함

-- TestFunc, Return 타입은 boolean 하나만 선언
return true, 999

-- OnBeginPlay (server only)
local success, extra = self:TestFunc()
log(success)
log(extra)

콘솔에 true와 999가 둘 다 정상적으로 찍힘을 확인함. 즉 mLua 자체가 다중 반환을 막는 게 아니라, 에디터의 Return 타입 선언란(UI)이 1개 슬롯만 제공할 뿐이고, 그 밑에서 실제로 실행되는 Lua 런타임은 선언된 개수와 무관하게 다중 반환을 그대로 통과시킴. 경고는 "타입 선언과 실제 동작이 다르다"는 정적 경고였을 뿐, 실행에는 문제가 없었음

3. 최종 해결 - 결과 전용 StructType으로 감싸기

동작 자체는 문제없지만, 선언(boolean 하나)과 실제 반환(두 값)이 다른 채로 두면 나중에 코드를 다시 볼 때(또는 다른 사람이 볼 때) 두 번째 값의 존재를 코드를 직접 열어보기 전엔 알 수 없고, 호출할 때마다 경고도 계속 떠서 정리하기로 함

값 두 개를 각각 반환하는 대신, success/amount 필드를 가진 InventoryUpdateResult라는 StructType 하나를 만들어 통째로 반환하도록 변경함

-- InventoryUpdateResult (StructType)
-- success: boolean, amount: integer

-- AddItem
local result = InventoryUpdateResult()
result.success = (remaining == 0)
result.amount = totalAdded
return result

Return 타입도 InventoryUpdateResult 하나로 선언하니 실제 반환값과 정확히 일치해서 경고가 사라짐. AddItem과 MergeSlot이 둘 다 "성공 여부 + 처리 수량"이라는 같은 모양의 결과가 필요해서, 타입 하나를 공유해 중복도 줄임

4. 성과와 개선 효과

• ✅ 경고 제거: Return 타입 선언과 실제 반환값이 일치하게 되어 정적 경고가 사라짐
• ✅ 인터페이스 명시성 확보: 메서드 시그니처만 봐도 success/amount 두 값이 반환된다는 게 드러남
• ✅ 중복 제거: AddItem, MergeSlot이 같은 결과 타입을 공유해 별도 타입을 두 개 만들 필요가 없어짐
• ✅ 원인의 정확한 이해: "Lua 언어가 다중 반환을 지원하는 것"과 "MSW 에디터의 Return 타입 선언 UI가 1개만 지원하는 것"은 서로 다른 레이어의 문제라는 걸 추측이 아니라 실측으로 확인함

📚 개발 참고

• 함수 — MSW 공식 크리에이터 센터 함수의 Return 타입 설정 방법을 다루는 문서. 매개변수와 달리 Return 타입에는 "추가" 절차 자체가 언급되지 않아, 에디터가 1개만 지원한다는 것의 근거로 참고함

👨‍💻 오늘의 개발 작업

오늘은 인벤토리 시스템의 데이터 계층(ItemData)을 만들면서, 서로 다른 스크립트 간 OnBeginPlay 실행 순서가 보장되지 않는 문제를 발견하고 해결했음

PlayerInventory가 ItemData의 아이템 테이블을 참조해야 하는데, 어느 쪽이 먼저 초기화를 끝낼지 확신할 수 없는 상황이었음. 폴링(wait()) 없이, 이벤트 기반으로 안전하게 처리하는 방식으로 마무리함

💡 오늘의 기록

1. 문제 상황 파악

아이템 데이터(ItemDataTable)를 매번 셀 단위로 조회하면 성능이 아깝다고 판단해서, 게임 시작 시 1회만 로드해 메모리에 캐싱하는 ItemData(Logic, 전역 싱글턴)를 만들었음

-- ItemData.OnBeginPlay
local itemDataSet = _DataService:GetTable("ItemDataTable")
local rowCnt = itemDataSet:GetRowCount()

for i = 1, rowCnt do
    local data = ItemInfo()
    -- ... 필드 채우기
    self.itemTable[id] = data
end

그런데 이 itemTable을 실제로 쓰는 쪽은 플레이어별로 붙는 PlayerInventory(Component)였음. 여기서 곧바로 참조하는 코드를 짜다가 의문이 들었음:

PlayerInventory.OnBeginPlay가 실행되는 시점에, ItemData.OnBeginPlay는 이미 끝나 있다고 확신할 수 있나?

2. 근거 없이 넘겨짚었던 부분

처음엔 "Logic은 전역 싱글턴이니까 당연히 먼저 초기화되겠지"라고 가정하고 넘어가려 했음. 하지만 이 가정을 뒷받침할 근거가 없다는 걸 스스로 깨닫고, MSW 공식 문서를 다시 확인해봄

확인된 사실 (MSW 공식 문서)

"각 컴포넌트 내 OnBeginPlay의 호출 순서는 보장되지 않기 때문에,
특정 컴포넌트의 OnBeginPlay로 설정이 완료된 값을 다른 컴포넌트가
참조하면 오작동할 가능성이 있다"

공식 예제 코드(ClearInventoryOnBeginPlay)에서도 다른 컴포넌트(LiteInventory)의 초기화 완료를 기다리기 위해 IsInitialized 플래그를 확인하는 방식을 쓰고 있었음. 즉 "먼저 실행되겠지"라는 가정 자체가 애초에 성립하지 않는 환경이었음

3. 첫 번째 접근 - 폴링 방식 (기각)

MSW 공식 예제에 나온 방식을 그대로 적용해보려 했음

-- 공식 문서 예제 패턴
local inven = self.Entity.LiteInventory
while not inven.IsInitialized do
    wait(0.5)
end

기각한 이유

• wait()은 코루틴을 점유한 채 일정 주기(0.5초)마다 계속 깨어나 플래그를 재확인하는 방식이라, 대기 중인 시간 동안 불필요한 컨텍스트 스위칭·검사 연산이 반복 발생함
• 접속자가 늘어날수록 플레이어 수만큼 폴링 루프가 동시에 돌아가는 구조라, 서버 부하가 인원수에 비례해서 커짐 — 과제 요구사항인 "서버 최적화"와 정면으로 배치됨
• 폴링 주기(0.5초) 때문에 실제 초기화가 끝난 시점과 이를 감지하는 시점 사이에 최대 0.5초의 불필요한 지연이 생김. 이벤트 방식이면 완료되는 즉시(지연 없이) 콜백이 실행됨
• 결국 "값이 준비됐는지 반복해서 찔러보는" 방식이라, 값의 변화를 스스로 알려주는(이벤트 발행) 방식보다 근본적으로 비효율적인 구조임

4. 두 번째 접근 - 순수 이벤트 방식의 함정 ⚠️

폴링 대신 이벤트로 완전히 대체하려 했는데, 여기서 진짜 문제를 발견함

-- 문제가 될 수 있는 방식
-- PlayerInventory에서 이벤트 핸들러만 등록해두고 기다림

핵심 문제

• 이벤트는 "구독한 시점 이후에 발생한 것"만 받을 수 있음
• 만약 ItemData가 PlayerInventory보다 먼저 끝나버리면, PlayerInventory가 핸들러를 등록했을 땐 이미 이벤트가 지나가버린 뒤라 영원히 못 받는 상황이 생길 수 있음

즉 "이벤트 기반이냐 폴링이냐"가 핵심이 아니라, "이미 끝난 경우를 어떻게 감지하느냐"가 진짜 문제였음

5. 최종 해결 - 플래그 우선 확인 + 이벤트 보완

폴링 없이, 놓치는 경우도 없이 처리하기 위해 두 가지를 조합함

ItemData 쪽 — 완료 시 플래그 + 이벤트 둘 다 발행

-- ItemData.OnBeginPlay 마지막
self.isInitialized = true
local event = OnItemDataInitialized()
self:SendInitializedEvent(event)

PlayerInventory 쪽 — 플래그 먼저 확인, 아니면 이벤트로 보완

-- PlayerInventory.OnBeginPlay
if _ItemData.isInitialized then
    -- 이미 끝나 있었던 경우: 이벤트 기다릴 필요 없이 즉시 진행
    self:InitInventory()
end
-- OnItemDataInitialized 이벤트 핸들러도 별도 등록해서
-- 늦게 끝나는 경우까지 커버 (else 분기 불필요)

이 방식이면:

• ItemData가 먼저 끝난 경우 → 플래그가 이미 true이니 즉시 진행
• PlayerInventory가 먼저 끝난 경우 → 아직 false이므로 이벤트 핸들러가 나중에 잡아줌
• 어느 쪽이든 wait() 반복 확인 없이 처리됨

6. 성과와 개선 효과

개선 결과

• ✅ 레이스 컨디션 제거: 실행 순서와 무관하게 항상 안전하게 초기화됨
• ✅ 폴링 없음: 지침서 원칙(이벤트 기반 우선) 그대로 유지
• ✅ 이벤트 구멍 없음: "이미 끝난 경우"까지 플래그로 커버해서 이벤트만 썼을 때의 함정을 회피
• ✅ 재사용 가능한 패턴 확립: 앞으로 다른 초기화 순서 문제에도 동일 패턴 적용 예정

📚 개발 참고

• 인벤토리 스크립트 작성하기 — MSW 공식 크리에이터 센터 다른 컴포넌트의 초기화 완료를 기다릴 때 IsInitialized 플래그를 확인하는 예제(ClearInventoryOnBeginPlay)가 실려 있음. 이번 문제의 대응 패턴을 잡을 때 기준으로 삼음

• InventoryComponent API Reference — MSW 공식 문서 MSW 내장 인벤토리 시스템도 IsInitialized 프로퍼티 + InventoryItemInitEvent 이벤트를 함께 제공한다는 걸 확인. "플래그+이벤트 조합"이 MSW 생태계에서 실제로 쓰이는 패턴이라는 근거로 참고함

• 멋쟁이사자처럼 X 넥슨 MOD Supporters Hackathon 2주차 회고 / MSW 기본 이벤트 함수 — MSW 공식 문서 이번에 겪은 문제와 비슷한 사례를 코드 예시로 다룸. 공식 문서에서 OnInitialize(엔티티/컴포넌트 생성 직후, OnBeginPlay 이전 1회 호출)를 활용해 참조당하는 쪽(A)은 OnInitialize에서 값을 설정하고, 참조하는 쪽(C)은 OnBeginPlay에서 읽으면 항상 값이 채워져 있음을 보장하는 패턴을 제시함. 하지만 Logic인 ItemData에는 OnInitialize가 없어서 이 대안을 적용할 수 없고, 지금 쓴 "isInitialized 플래그 + OnItemDataInitialized 이벤트" 조합이 Logic 타입 기준으로는 사실상 유일하게 성립하는 해법으로 최종 확정됨.

Logic ↔ Component 간 초기화 시 체크리스트

-- (완료를 알리는 쪽)
property boolean isInitialized = false

method void OnBeginPlay()
    -- ... 초기화 로직
    self.isInitialized = true
    local event = OnXxxInitialized()
    self:SendXxxInitializedEvent(event)
end

-- (참조하는 쪽)
method void OnBeginPlay()
    if _Xxx.isInitialized then
        self:DoInit()  -- 이미 끝났으면 즉시 진행
    end
    -- 이벤트 핸들러는 별도 등록, else 분기 불필요
end

🔸 set (집합)

기본 특징

• Red-Black Tree (레드-블랙 트리)로 구현
• 중복 불가 - 각 요소는 유일해야 함
• 자동 정렬 - 삽입 시 자동으로 정렬된 상태 유지
• Balanced BST 특성상 모든 연산이 O(log n) 보장

시간 복잡도

메모리 구조 (Red-Black Tree)

레드-블랙 트리 속성:
1. 모든 노드는 Red 또는 Black
2. 루트는 항상 Black
3. 모든 리프(NULL)는 Black
4. Red 노드의 자식은 모두 Black
5. 모든 경로의 Black 노드 개수는 동일

예시: {10, 20, 30, 40, 50}
         30(B)
        /     \
     20(B)    40(B)
      /         \
   10(R)       50(R)

Stack:
┌──────────────────┐
│ root (pointer)  │ → 루트 노드
│ size            │ → 요소 개수
└──────────────────┘

Heap (각 노드):
┌────────────────────┐
│ color (R/B)       │
│ data              │
│ left (pointer)    │
│ right (pointer)   │
│ parent (pointer)  │
└────────────────────┘

사용 예시

#include <set>
#include <iostream>

std::set<int> s;

// ✅ 삽입 - O(log n)
s.insert(30);
s.insert(10);
s.insert(20);
s.insert(10);  // 중복 - 삽입 안 됨!

// ✅ 자동 정렬됨
for (int val : s) {
    std::cout << val << " ";  // 10 20 30
}

// ✅ 검색 - O(log n)
auto it = s.find(20);
if (it != s.end()) {
    std::cout << "Found: " << *it;
}

// ✅ 삭제 - O(log n)
s.erase(20);

// ✅ 범위 기반 검색
auto lower = s.lower_bound(15);  // >= 15인 첫 요소
auto upper = s.upper_bound(25);  // > 25인 첫 요소

커스텀 비교 함수

// 내림차순 정렬
std::set<int, std::greater<int>> descSet;

// 커스텀 비교자
struct Person {
    std::string name;
    int age;
};

struct CompareByAge {
    bool operator()(const Person& a, const Person& b) const {
        return a.age < b.age;
    }
};

std::set<Person, CompareByAge> people;

🔸 multiset (중복 허용 집합)

기본 특징

• set과 동일하게 Red-Black Tree로 구현
• 중복 허용 - 동일한 값을 여러 번 삽입 가능
• 자동 정렬 유지
• 시간 복잡도는 set과 동일

set vs multiset

std::set<int> s;
s.insert(10);
s.insert(10);
s.insert(10);
std::cout << s.size();  // 1 (중복 무시)

std::multiset<int> ms;
ms.insert(10);
ms.insert(10);
ms.insert(10);
std::cout << ms.size();  // 3 (중복 허용)

중복 요소 처리

std::multiset<int> ms = {10, 20, 20, 30, 30, 30};

// ✅ 특정 값의 개수 세기 - O(log n + k), k는 중복 개수
int count = ms.count(30);  // 3

// ✅ 특정 값의 범위 찾기
auto range = ms.equal_range(30);
for (auto it = range.first; it != range.second; ++it) {
    std::cout << *it << " ";  // 30 30 30
}

// ✅ 특정 값 하나만 삭제
auto it = ms.find(30);
if (it != ms.end()) {
    ms.erase(it);  // 30 하나만 삭제
}

// ✅ 특정 값 모두 삭제
ms.erase(30);  // 30 모두 삭제

🔸 map (키-값 쌍)

기본 특징

• Red-Black Tree로 구현
• 키(Key)는 중복 불가, 값(Value)은 중복 가능
• 키 기준으로 자동 정렬
• set과 동일한 시간 복잡도

시간 복잡도

메모리 구조

Heap (각 노드):
┌────────────────────┐
│ color (R/B)       │
│ pair<Key, Value>  │ ← key와 value를 함께 저장
│ left (pointer)    │
│ right (pointer)   │
│ parent (pointer)  │
└────────────────────┘

사용 예시

#include <map>
#include <string>

std::map<std::string, int> ages;

// ✅ 삽입 방법 1: operator[] - O(log n)
ages["Alice"] = 25;
ages["Bob"] = 30;

// ✅ 삽입 방법 2: insert - O(log n)
ages.insert({"Charlie", 35});
ages.insert(std::make_pair("David", 40));

// ✅ 검색 - O(log n)
auto it = ages.find("Alice");
if (it != ages.end()) {
    std::cout << it->first << ": " << it->second;  // Alice: 25
}

// ⚠️ operator[]의 주의점
int age = ages["Eve"];  // 키가 없으면 자동 생성! (value는 0으로 초기화)
std::cout << ages.size();  // 5 (Eve가 추가됨)

// ✅ 안전한 검색: at() 사용
try {
    int age = ages.at("Frank");  // 키가 없으면 예외 발생
} catch (const std::out_of_range& e) {
    std::cout << "Key not found!";
}

iterator 활용

std::map<std::string, int> scores = {
    {"Alice", 90},
    {"Bob", 85},
    {"Charlie", 95}
};

// ✅ 순회 (키 기준 정렬된 순서)
for (const auto& [name, score] : scores) {
    std::cout << name << ": " << score << "\n";
}
// Alice: 90
// Bob: 85
// Charlie: 95

🔸 multimap (중복 키 허용)

기본 특징

• map과 동일하게 Red-Black Tree로 구현
• 키 중복 허용
• operator[] 사용 불가 (어떤 값을 반환할지 모호)

사용 예시

std::multimap<std::string, int> scores;

scores.insert({"Alice", 90});
scores.insert({"Alice", 85});  // 같은 키에 다른 값
scores.insert({"Bob", 95});

// ✅ 특정 키의 모든 값 찾기
auto range = scores.equal_range("Alice");
for (auto it = range.first; it != range.second; ++it) {
    std::cout << it->second << " ";  // 85 90 (정렬됨)
}

🔸 unordered_set (해시 집합)

기본 특징

• Hash Table로 구현
• 중복 불가
• 정렬되지 않음 (순서 보장 안 됨)
• 평균 O(1), 최악 O(n) 시간 복잡도

시간 복잡도

메모리 구조 (Hash Table with Separate Chaining)

Hash Table 구조:

해시 함수: hash(value) % bucket_count

Bucket Array (vector):
┌─────┬─────┬─────┬─────┬─────┐
│  0 │  1  │  2  │  3  │  4  │
└──┬──┴──┬──┴──┬──┴──┬──┴──┬──┘
   │     │     │     │     │
   ↓     ↓     ↓     ↓     ↓
  [10]  [21]  NULL [13]  [24]
   ↓     ↓           ↓     ↓
  [30]  NULL        [33]  NULL

각 버킷은 Linked List로 구현 (Separate Chaining)
해시 충돌 발생 시 같은 버킷에 연결

Stack:
┌──────────────────┐
│ buckets (array) │ → 버킷 배열
│ size            │ → 요소 개수
│ bucket_count    │ → 버킷 개수
│ max_load_factor │ → 최대 로드 팩터 (기본 1.0)
└──────────────────┘

해시 함수와 충돌 처리

// 해시 값 계산 예시
hash<int> hashFunc;
size_t hashValue = hashFunc(42);

// 버킷 인덱스 = hash(value) % bucket_count
size_t bucketIndex = hashValue % bucket_count;

// ✅ Separate Chaining
// 같은 버킷에 여러 요소가 linked list로 연결됨

Load Factor와 Rehashing

std::unordered_set<int> us;

// Load Factor = size / bucket_count
// 기본 max_load_factor = 1.0

us.insert(10);
us.insert(20);
us.insert(30);

std::cout << "Size: " << us.size() << "\n";
std::cout << "Bucket count: " << us.bucket_count() << "\n";
std::cout << "Load factor: " << us.load_factor() << "\n";
std::cout << "Max load factor: " << us.max_load_factor() << "\n";

// ⚠️ load_factor > max_load_factor 되면 Rehashing 발생!
// Rehashing: O(n) - 모든 요소를 새 버킷에 재배치

Rehashing 최적화

std::unordered_set<int> us;

// ✅ 미리 버킷 예약 - rehashing 방지
us.reserve(1000);  // 최소 1000개 요소를 담을 수 있도록 버킷 확보

// ✅ max_load_factor 조정
us.max_load_factor(0.5);  // 로드 팩터를 낮춰서 충돌 감소 (메모리 trade-off)

사용 예시

#include <unordered_set>

std::unordered_set<int> us;

// ✅ 삽입 - 평균 O(1)
us.insert(10);
us.insert(20);
us.insert(30);

// ✅ 검색 - 평균 O(1)
if (us.find(20) != us.end()) {
    std::cout << "Found!";
}

// ⚠️ 순서 보장 안 됨!
for (int val : us) {
    std::cout << val << " ";  // 순서 예측 불가
}

커스텀 타입을 위한 Hash Function 정의

방법 1: Hash Function Object 생성

struct Person {
    std::string name;
    int age;

    bool operator==(const Person& other) const {
        return name == other.name && age == other.age;
    }
};

// 커스텀 해시 함수 객체
struct PersonHash {
    size_t operator()(const Person& p) const {
        // 여러 필드를 조합한 해시 값 계산
        size_t h1 = std::hash<std::string>{}(p.name);
        size_t h2 = std::hash<int>{}(p.age);
        return h1 ^ (h2 << 1);  // XOR과 shift 조합
    }
};

// 사용
std::unordered_set<Person, PersonHash> people;
people.insert({"Alice", 25});

방법 2: std 네임스페이스에 특수화 주입

struct Person {
    std::string name;
    int age;

    bool operator==(const Person& other) const {
        return name == other.name && age == other.age;
    }
};

// std::hash 특수화
namespace std {
    template<>
    struct hash<Person> {
        size_t operator()(const Person& p) const {
            size_t h1 = hash<string>{}(p.name);
            size_t h2 = hash<int>{}(p.age);
            return h1 ^ (h2 << 1);
        }
    };
}

// 사용 (추가 템플릿 인자 불필요)
std::unordered_set<Person> people;
people.insert({"Alice", 25});

커스텀 Equality Operator

// 방법 1: 클래스 내부에 operator== 정의 (위 예시 참고)

// 방법 2: 별도의 함수 객체
struct PersonEqual {
    bool operator()(const Person& a, const Person& b) const {
        return a.name == b.name && a.age == b.age;
    }
};

std::unordered_set<Person, PersonHash, PersonEqual> people;

🔸 unordered_map (해시 맵)

기본 특징

• Hash Table로 구현
• 키 중복 불가
• unordered_set과 동일한 시간 복잡도
• 실무에서 가장 많이 사용됨
• 알고리즘 면접에서 자주 출제됨

시간 복잡도

메모리 구조

Bucket Array:
┌──────┬──────┬──────┬──────┐
│  0   │  1  │  2   │  3  │
└───┬──┴──┬───┴──┬───┴──┬───┘
   │     │      │      │
   ↓     ↓      ↓      ↓
 {k1:v1} NULL {k2:v2} NULL
   ↓                   ↓
 {k3:v3}             {k4:v4}

각 노드는 pair<Key, Value> 저장

사용 예시

#include <unordered_map>
#include <string>

std::unordered_map<std::string, int> phoneBook;

// ✅ 삽입 - 평균 O(1)
phoneBook["Alice"] = 1234;
phoneBook["Bob"] = 5678;
phoneBook.insert({"Charlie", 9012});

// ✅ 검색 - 평균 O(1)
auto it = phoneBook.find("Alice");
if (it != phoneBook.end()) {
    std::cout << it->first << ": " << it->second;
}

// ✅ operator[] - 평균 O(1)
int number = phoneBook["Alice"];  // 1234

// ⚠️ 키가 없으면 자동 생성
int unknown = phoneBook["David"];  // David 키 생성, value = 0

// ✅ 성능 최적화
phoneBook.reserve(10000);  // 예상 크기 미리 예약

실무 활용 예시

// 빈도수 카운팅
std::unordered_map<char, int> freq;
std::string text = "hello world";
for (char c : text) {
    freq[c]++;
}

// 캐싱 (Memoization)
std::unordered_map<int, int> cache;
int fibonacci(int n) {
    if (n <= 1) return n;
    if (cache.find(n) != cache.end()) {
        return cache[n];
    }
    cache[n] = fibonacci(n-1) + fibonacci(n-2);
    return cache[n];
}

// 그래프 인접 리스트
std::unordered_map<int, std::vector<int>> graph;
graph[1] = {2, 3};
graph[2] = {4};

커스텀 타입 예시

struct Point {
    int x, y;
    bool operator==(const Point& other) const {
        return x == other.x && y == other.y;
    }
};

struct PointHash {
    size_t operator()(const Point& p) const {
        return std::hash<int>{}(p.x) ^ (std::hash<int>{}(p.y) << 1);
    }
};

std::unordered_map<Point, std::string, PointHash> locations;
locations[{0, 0}] = "Origin";
locations[{10, 20}] = "Point A";

🔸 unordered_multiset / unordered_multimap

기본 특징

• 각각 unordered_set, unordered_map의 중복 허용 버전
• 시간 복잡도 동일
• unordered_multimap은 operator[] 사용 불가

사용 예시

std::unordered_multiset<int> ums = {10, 20, 20, 30, 30, 30};

// 특정 값의 개수
int count = ums.count(30);  // 3

// 특정 값 모두 찾기
auto range = ums.equal_range(30);
for (auto it = range.first; it != range.second; ++it) {
    std::cout << *it << " ";
}

🔸 set vs unordered_set 비교

성능 비교

선택 가이드

// ✅ set을 사용해야 하는 경우:
// 1. 정렬된 순서가 필요할 때
std::set<int> sorted = {30, 10, 20};
for (int val : sorted) {
    std::cout << val << " ";  // 10 20 30 (정렬됨)
}

// 2. 범위 검색이 필요할 때
auto lower = sorted.lower_bound(15);
auto upper = sorted.upper_bound(25);

// 3. 최악의 경우에도 일정한 성능이 필요할 때 (O(log n) 보장)

// ✅ unordered_set을 사용해야 하는 경우:
// 1. 빠른 검색이 최우선일 때 (평균 O(1))
std::unordered_set<int> fast;

// 2. 순서가 중요하지 않을 때

// 3. 데이터 크기를 미리 알고 reserve 가능할 때
fast.reserve(10000);

map vs unordered_map 비교

🔸 Hash Function 설계 원칙

좋은 해시 함수의 조건

1. 결정론적 (Deterministic): 같은 입력은 항상 같은 해시 값
2. 균등 분포 (Uniform Distribution): 해시 값이 고르게 분포
3. 효율성 (Efficient): 계산이 빠름 (O(1))
4. 충돌 최소화: 서로 다른 입력에 대해 다른 해시 값

해시 조합 기법

// ❌ 나쁜 예: 단순 더하기 (충돌 많음)
size_t badHash = hash<int>{}(x) + hash<int>{}(y);

// ✅ 좋은 예 1: XOR + Shift
size_t goodHash1 = hash<int>{}(x) ^ (hash<int>{}(y) << 1);

// ✅ 좋은 예 2: Boost 스타일
size_t goodHash2 = hash<int>{}(x);
goodHash2 ^= hash<int>{}(y) + 0x9e3779b9 + (goodHash2 << 6) + (goodHash2 >> 2);

// ✅ 좋은 예 3: 여러 필드 조합
struct Data {
    int a, b, c;
};

size_t hash_value(const Data& d) {
    size_t seed = 0;
    seed ^= hash<int>{}(d.a) + 0x9e3779b9 + (seed << 6) + (seed >> 2);
    seed ^= hash<int>{}(d.b) + 0x9e3779b9 + (seed << 6) + (seed >> 2);
    seed ^= hash<int>{}(d.c) + 0x9e3779b9 + (seed << 6) + (seed >> 2);
    return seed;
}

🔸 핵심 정리

컨테이너 선택 가이드

순서가 필요한가?
├─ YES → set / map
│         - 정렬된 순서 보장
│         - 범위 검색 가능
│         - O(log n) 성능 보장
│
└─ NO → unordered_set / unordered_map
          - 평균 O(1) 성능
          - 메모리 사용량 높음
          - rehashing 주의

중복이 필요한가?
├─ YES → multiset / multimap / unordered_multiset / unordered_multimap
└─ NO → set / map / unordered_set / unordered_map

키-값 쌍이 필요한가?
├─ YES → map / unordered_map
└─ NO → set / unordered_set

성능 최적화 팁

1. unordered_* 사용 시:

   • 예상 크기를 아는 경우 reserve() 사용
   • max_load_factor 조정으로 충돌 제어
   • 좋은 해시 함수 설계

2. set/map 사용 시:

   • 커스텀 비교 함수로 정렬 순서 제어
   • lower_bound, upper_bound 활용

3. 일반적인 권장사항:

   • 대부분의 경우: unordered_map (실무 표준)
   • 정렬이 필요한 경우: map
   • 중복이 필요한 경우: multiset / multimap

실무에서 자주 쓰이는 패턴

// 1. 빈도수 카운팅
unordered_map<string, int> wordCount;

// 2. 중복 제거
unordered_set<int> uniqueValues;

// 3. 캐싱/메모이제이션
unordered_map<int, Result> cache;

// 4. 그래프 표현
unordered_map<Node, vector<Node>> adjacencyList;

// 5. 빠른 조회 테이블
unordered_map<string, UserData> userDatabase;

<참고 자료>

코드없는 프로그래밍 std::set std::map std::unordered_set std::unordered_map Red-Black Tree Hash Table

🔸 list (이중 연결 리스트)

기본 특징

• Doubly-Linked List로 구현
• 각 노드는 이전/다음 노드를 가리키는 두 개의 포인터 보유
• Insertion/Deletion: O(1) (위치를 알고 있을 때)
• Random Access: O(n) (순차 탐색 필요)

메모리 구조

Stack:
┌──────────────────┐
│ first (pointer) │ → 첫 번째 노드
│ last (pointer)  │ → 마지막 노드
│ size            │ → 요소 개수
└──────────────────┘

Heap:
┌────┬────┬────┐    ┌────┬────┬────┐    ┌────┬────┬────┐
│prev│data│next│ ↔ │prev│data│next│ ↔ │prev│data│next│
└────┴────┴────┘    └────┴────┴────┘    └────┴────┴────┘

• 스택에는 first 포인터, last 포인터, size 정보 저장
• 실제 데이터는 힙(Heap)에 동적 할당

정렬

std::list<int> myList = {3, 1, 4, 1, 5};

// ✅ list 전용 sort() 멤버 함수 사용 (O(n log n))
myList.sort();  

// ❌ std::sort() 사용 불가 (Random Access Iterator 필요)
// std::sort(myList.begin(), myList.end());  // 컴파일 에러!

주요 연산 시간 복잡도

🔸 forward_list (단일 연결 리스트)

기본 특징

• Singly-Linked List로 구현
• 각 노드는 다음 노드만 가리킴 (이전 노드 포인터 없음)
• list보다 메모리 효율적 (포인터 하나만 필요)
• Random Access: O(n)

메모리 구조

Stack:
┌──────────────────┐
│ front (pointer) │ → 첫 번째 노드
└──────────────────┘

Heap:
┌────┬────┐    ┌────┬────┐    ┌────┬────┐
│data│next│ → │data│next│ → │data│next│ → nullptr
└────┴────┘    └────┴────┘    └────┴────┘

• 스택에는 front 포인터 하나만 저장
• last 포인터나 size 정보는 저장하지 않음 (메모리 절약)

제한 사항

std::forward_list<int> fList = {1, 2, 3, 4, 5};

// ✅ 가능한 연산
fList.push_front(0);
fList.pop_front();
fList.insert_after(fList.begin(), 10);

// ❌ 불가능한 연산
// fList.push_back(6);   // back 포인터 없음
// fList.size();         // size 저장 안 함 (O(n)으로 계산 가능)
// fList[2];             // Random Access 불가

🔸 vector vs list vs forward_list

성능 비교

실제 find() 성능

// 둘 다 O(n)이지만 실제로는 vector가 훨씬 빠름!
std::vector<int> vec(1000000);
std::list<int> lst(1000000);

// vector의 find: 메모리가 연속적 → 캐시 히트율 높음 ✅
auto it1 = std::find(vec.begin(), vec.end(), 999999);

// list의 find: 메모리가 분산 → 캐시 미스 많음 ❌
auto it2 = std::find(lst.begin(), lst.end(), 999999);

왜 vector가 더 빠를까? (캐시 지역성)

• CPU는 메모리에서 데이터를 가져올 때 캐시 라인 단위로 가져옴
• vector: 메모리가 연속 → 한 번에 여러 요소를 캐시에 로드 ✅
• list: 메모리가 분산 → 각 노드마다 캐시 미스 발생 ❌

병렬 프로그래밍에서의 문제

// ❌ list는 병렬화가 어려움
// 각 노드가 분산되어 있어서 동시 접근 시 동기화 오버헤드 큼
std::list<int> lst;

// ✅ vector는 병렬화가 용이함
// 메모리가 연속적이라 분할하기 쉬움
std::vector<int> vec;
#pragma omp parallel for
for (int i = 0; i < vec.size(); i++) {
    // 병렬 처리
}

선택 가이드

• 대부분의 경우: vector 사용 ✅
• 중간 삽입/삭제가 빈번: list 고려
• 메모리 최소화 + 단방향만 필요: forward_list

🔸 stack (스택)

기본 특징

• LIFO (Last In First Out) 구조
• Container Adapter (다른 컨테이너를 감싸서 구현)
• 기본 컨테이너: deque (변경 가능)

지원 컨테이너

// ✅ 기본 (deque)
std::stack<int> s1;

// ✅ vector로 구현
std::stack<int, std::vector<int>> s2;

// ✅ list로 구현
std::stack<int, std::list<int>> s3;

// ❌ forward_list는 불가 (back 접근 필요)
// std::stack<int, std::forward_list<int>> s4;  // 컴파일 에러!

주요 연산

std::stack<int> s;

s.push(10);     // O(1) - 삽입
s.pop();        // O(1) - 제거 (값 반환 안 함!)
int top = s.top();  // O(1) - 최상단 접근
bool empty = s.empty();  // O(1)
size_t sz = s.size();    // O(1)

성능 최적화가 필요한 경우

// 직접 구현 예시 (vector 기반)
template<typename T>
class FastStack {
private:
    std::vector<T> data;
public:
    void push(const T& value) {
        data.push_back(value);
    }
    void pop() {
        data.pop_back();
    }
    T& top() {
        return data.back();
    }
    // ...
};

🔸 queue (큐)

기본 특징

• FIFO (First In First Out) 구조
• Container Adapter
• 기본 컨테이너: deque (변경 가능)

지원 컨테이너

// ✅ 기본 (deque)
std::queue<int> q1;

// ✅ list로 구현
std::queue<int, std::list<int>> q2;

// ❌ vector는 불가 (front에서 pop이 O(n))
// std::queue<int, std::vector<int>> q3;  // 컴파일 에러!

// ❌ forward_list는 불가 (back 접근 필요)
// std::queue<int, std::forward_list<int>> q4;  // 컴파일 에러!

주요 연산

std::queue<int> q;

q.push(10);     // O(1) - 뒤에 삽입
q.pop();        // O(1) - 앞에서 제거
int front = q.front();  // O(1) - 앞 요소 접근
int back = q.back();    // O(1) - 뒤 요소 접근
bool empty = q.empty(); // O(1)
size_t sz = q.size();   // O(1)

🔸 priority_queue (우선순위 큐)

기본 특징

• Max Heap으로 구현 (기본값)
• 가장 큰 원소가 항상 top에 위치
• Container Adapter (기본: vector)

시간 복잡도

힙 구조 (배열 기반)

인덱스:  0   1   2   3   4   5   6
값:    [100, 50, 80, 30, 20, 60, 70]

트리 구조:
           100 (idx=0)
          /   \
        50     80
       /  \   /  \
      30  20 60  70

부모-자식 관계:
- 부모 노드: (idx - 1) / 2
- 왼쪽 자식: 2 * idx + 1
- 오른쪽 자식: 2 * idx + 2

힙 속성

• Max Heap: 부모 노드 ≥ 자식 노드
• Min Heap: 부모 노드 ≤ 자식 노드

사용 예시

#include <queue>

// ✅ Max Heap (기본)
std::priority_queue<int> maxHeap;
maxHeap.push(30);
maxHeap.push(100);
maxHeap.push(50);
std::cout << maxHeap.top();  // 100

// ✅ Min Heap (greater 사용)
std::priority_queue<int, std::vector<int>, std::greater<int>> minHeap;
minHeap.push(30);
minHeap.push(100);
minHeap.push(50);
std::cout << minHeap.top();  // 30

// ✅ 커스텀 비교 함수
auto cmp = [](int a, int b) { return a > b; };  // Min Heap
std::priority_queue<int, std::vector<int>, decltype(cmp)> customHeap(cmp);

인덱스 계산 예시

// 인덱스 3의 부모: (3 - 1) / 2 = 1
// 인덱스 1의 왼쪽 자식: 2 * 1 + 1 = 3
// 인덱스 1의 오른쪽 자식: 2 * 1 + 2 = 4

🔸 heap 알고리즘 (Algorithm Library)

기본 특징

• <algorithm> 헤더에 포함된 힙 관련 함수들
• 기존 컨테이너(주로 vector)를 힙으로 변환/관리
• priority_queue와 동일한 내부 구조

주요 함수

사용 예시

#include <algorithm>
#include <vector>

std::vector<int> vec = {30, 100, 50, 20, 80};

// ✅ 힙 생성 - O(n)
std::make_heap(vec.begin(), vec.end());
// vec: [100, 80, 50, 20, 30] (Max Heap)

// ✅ 최대값 확인
std::cout << vec.front();  // 100 (O(1))

// ✅ 최대값 제거
std::pop_heap(vec.begin(), vec.end());  // O(log n)
// 최대값을 맨 뒤로 이동
// vec: [80, 30, 50, 20, 100]
vec.pop_back();  // 실제 제거 - O(1)
// vec: [80, 30, 50, 20]

// ✅ 새 요소 추가
vec.push_back(90);  // O(1)
std::push_heap(vec.begin(), vec.end());  // O(log n)
// vec: [90, 80, 50, 20, 30]

make_heap이 O(n)인 이유

Naive 방식 (위에서 아래로): O(n log n)
- 각 요소를 하나씩 삽입: n번
- 각 삽입마다 heapify: O(log n)
- 총 시간: O(n log n)

Floyd 알고리즘 (아래에서 위로): O(n) ✅
- 리프 노드는 이미 힙 속성 만족
- 아래에서 위로 올라가며 heapify
- 높이 h인 노드 개수: n / 2^(h+1)
- 각 노드의 작업량: O(h)
- 총 시간: Σ(n / 2^(h+1) * h) = O(n)

priority_queue vs heap 알고리즘

// priority_queue: 편리하지만 유연성 낮음
std::priority_queue<int> pq;
pq.push(10);
// 내부 데이터 직접 접근 불가

// heap 알고리즘: 유연하지만 수동 관리 필요
std::vector<int> vec = {10, 20, 30};
std::make_heap(vec.begin(), vec.end());
// 벡터에 직접 접근 가능 ✅
vec[0];  // 최대값 확인

언제 heap 알고리즘을 사용할까?

• 기존 컨테이너를 힙으로 변환해야 할 때
• 힙 내부 데이터에 직접 접근이 필요할 때
• 부분 정렬이 필요할 때 (Top K 문제 등)

🔸 핵심 정리

컨테이너 선택 가이드

1. 대부분의 경우: vector 사용 (캐시 효율, 랜덤 액세스)
2. 중간 삽입/삭제 빈번: list 고려
3. 메모리 최소화: forward_list
4. LIFO 필요: stack
5. FIFO 필요: queue
6. 우선순위 관리: priority_queue
7. 힙 직접 제어: heap 알고리즘

성능 최적화 팁

• 대부분의 경우 vector가 가장 빠름 (캐시 지역성)
• 병렬 프로그래밍에서는 vector 사용 권장
• 성능이 매우 중요하면 직접 구현 고려
• 힙 생성은 make_heap이 삽입보다 빠름 (O(n) vs O(n log n))

<참고 자료>

코드없는 프로그래밍 C++ Standard Containers std::list std::forward_list std::priority_queue Heap Algorithms Container Adapters

🔸 C-Style 문자열의 메모리 위치

char 배열 vs char 포인터

int main()
{
    char a[] = "hello";      // 스택에 할당
    char* b = "hello";       // 포인터는 스택, 문자열은 read-only 영역

    // 수정 테스트
    a[0] = 'd';              // ✅ 성공: "dello"
    // b[0] = 'd';           // ❌ Segmentation Fault!

    return 0;
}

메모리 레이아웃

스택 (Stack):
┌──────────────┐
│ a[] 배열     │
│ 'h''e''l''l' │
│ 'o' '\0'     │
└──────────────┘
  ↑ 수정 가능

스택 (Stack):
┌──────────────┐
│ b (포인터)   │
│ 0x400000 ────┼───→ Read-Only Data Segment:
└──────────────┘     ┌──────────────────┐
                    │ "hello\0"       │
                    └──────────────────┘
                      ↑ 수정 불가능!

문자열 리터럴은 read-only data segment에 저장되며, 수정 시도 시 segmentation fault 발생

const char*에는 반드시 const 사용

// ❌ 나쁜 코드: 경고 발생 (C++11 이후 deprecated)
char* b = "hello";
b[0] = 'd';  // Undefined Behavior (대부분 Segmentation Fault)

// ✅ 좋은 코드: const로 명시
const char* b = "hello";  // 수정 불가능함을 명시
// b[0] = 'd';  // 컴파일 에러로 실수 방지!

🔸 std::string의 메모리 할당

Small String Optimization (SSO)

std::string은 항상 힙에 할당되는 것이 아니라, SSO를 통해 짧은 문자열은 스택에, 긴 문자열만 힙에 저장

#include <string>

int main()
{
    // 짧은 문자열 (SSO 적용, 보통 15-22자 이하)
    std::string short_str = "hello";
    // → 스택에 저장 (힙 할당 없음)

    // 긴 문자열 (SSO 한계 초과)
    std::string long_str = "This is a very long string that exceeds SSO";
    // → 힙에 동적 할당

    return 0;
}

SSO 동작 방식

std::string 객체 (스택):
┌────────────────────────┐
│ 포인터 / 데이터        │ ← SSO 버퍼 (15-22자)
│ 길이                  │
│ 용량 / SSO 플래그      │
└────────────────────────┘

짧은 문자열 ("hello"):
┌─────────────────────────┐
│ "hello\0"... (여유공간)│ ← 스택 내부에 직접 저장
│ 길이: 5                │
│ 플래그: SSO 사용 중     │
└─────────────────────────┘

긴 문자열:
┌───────────────┐
│ 포인터 ───────┼───→ 힙 메모리
│ 길이: 50     │    "This is a very long..."
│ 용량: 64     │
└───────────────┘

구현에 따라 GCC/MSVC는 15자, Clang은 22자까지 SSO 적용

🔸 std::string_view (C++17)

std::string_view란?

• std::span과 비슷한 개념
• 포인터 + 길이 정보만 저장 (16 bytes)
• 소유권 없이 문자열을 참조만 함

메모리 구조

template<typename CharT>
class basic_string_view
{
    const CharT* ptr;   // 데이터 시작 주소 (8 bytes)
    size_t length;      // 문자열 길이 (8 bytes)
};

// sizeof(std::string_view) == 16 bytes

🔸 함수 파라미터로 문자열 전달하기

const std::string& 사용 시 문제

void print(const std::string& str)
{
    std::cout << str << std::endl;
}

int main()
{
    const char* c_str = "hello";

    // ❌ 비효율: 임시 std::string 객체 생성!
    print(c_str);

    // 실제 동작:
    // 1. 임시 std::string tmp(c_str) 생성
    // 2. 힙 메모리 할당 (SSO 초과 시)
    // 3. "hello" 복사
    // 4. print(tmp) 호출
    // 5. tmp 소멸, 메모리 해제

    return 0;
}

const char*나 문자열 리터럴을 const std::string& 파라미터로 전달하면 임시 std::string 객체가 생성되어 메모리 할당과 복사 발생

std::string_view 사용

void print(std::string_view str)  // ✅ 효율적!
{
    std::cout << str << std::endl;
}

int main()
{
    // 모두 임시 객체 생성 없이 전달 가능

    // C 문자열 배열
    char arr[] = "hello";
    print(arr);  // 포인터 + 길이만 전달

    // const char* 포인터
    const char* c_str = "world";
    print(c_str);  // 포인터 + 길이만 전달

    // std::string
    std::string cpp_str = "string";
    print(cpp_str);  // string의 내부 포인터 + 길이만 전달

    return 0;
}

string_view는 포인터와 길이만 저장하므로 임시 객체 생성이나 메모리 할당 없이 전달 가능

성능 차이

// const std::string& 사용
void old_print(const std::string& str) { }

old_print("hello");
// → 임시 std::string 생성
// → 힙 할당 (SSO 초과 시)
// → 메모리 복사
// → 함수 호출
// → 소멸 및 메모리 해제

// std::string_view 사용
void new_print(std::string_view str) { }

new_print("hello");
// → 포인터와 길이만 전달 (16 bytes 복사)
// → 끝!

벤치마크 결과 string_view 사용 시 문자열 리터럴 전달에서 100배 이상 성능 향상 가능

🔸 std::string_view 주의사항

Dangling Reference

std::string_view get_view()
{
    std::string temp = "temporary";
    return std::string_view(temp);  // ❌ 위험!
}  // temp 소멸

int main()
{
    auto view = get_view();
    std::cout << view << std::endl;  // ❌ Undefined Behavior

    return 0;
}

std::string 재할당 시 무효화

std::string str = "short";
std::string_view view = str;

std::cout << view << std::endl;  // ✅ "short"

str = "This is a very long string that causes reallocation";
// → str의 내부 버퍼가 재할당됨

std::cout << view << std::endl;  // ❌ Undefined Behavior
                                 // view는 여전히 옛날 주소를 가리킴

임시 객체 바인딩

void process(std::string_view view)
{
    // view 사용...
}

int main()
{
    std::string get_string() { return "temp"; }

    // ❌ 위험: 임시 객체의 view
    process(get_string());  // get_string() 반환 후 즉시 소멸

    // ✅ 안전: 수명 연장
    std::string str = get_string();
    process(str);

    return 0;
}

string_view는 임시 객체도 받아들이므로, 수명 관리에 주의 필요

🔸 char[], const char*, std::string 비교

🔸 함수 파라미터 선택 가이드

// 읽기 전용, 다양한 타입 받기
void read_only(std::string_view str)  // ✅ 권장 (C++17 이상)
{
    std::cout << str << std::endl;
}

// std::string만 받기
void string_only(const std::string& str)
{
    std::cout << str.size() << std::endl;
}

// 소유권 획득
void take_ownership(std::string str)  // 복사 또는 이동
{
    // str을 멤버 변수에 저장하거나 수정
}

// 수정이 필요한 경우
void modify(std::string& str)
{
    str += " modified";
}

// C 라이브러리와 호환 필요
void c_compat(const char* str)
{
    printf("%s\n", str);  // C 함수 사용
}

🔸 핵심 정리

char 배열 vs char 포인터

• char a[] = "hello": 스택에 복사본 생성, 수정 가능
• const char* b = "hello": read-only 영역 참조, 수정 불가 (const 필수)

std::string의 메모리

• 짧은 문자열 (15-22자): 스택 (SSO)
• 긴 문자열: 힙 동적 할당
• 자동 메모리 관리 (RAII)

std::string_view

• 포인터 + 길이만 저장 (16 bytes)
• const char*, std::string 모두 임시 객체 없이 전달
• 읽기 전용, 소유권 없음
• 주의: 원본 수명 관리 필요

함수 파라미터 권장사항 (C++17 이상)

• 읽기 전용: std::string_view
• 수정 필요: std::string&
• 소유권 획득: std::string (값 전달)

<참고 자료>

코드없는 프로그래밍 C++ std::string Implementation C++ std::string_view

🔸 배열과 컨테이너 비교

5가지 메모리 관리 방법 비교

#include <array>
#include <vector>

int main()
{
    // 1. C 정적 배열
    int cArray[5] = {1, 2, 3, 4, 5};  
    // 스택, 컴파일 타임 크기, 자동 관리

    // 2. C++ 동적 배열 (new/delete)
    int* cppDynArray = new int[5]{1, 2, 3, 4, 5};
    // 힙, 런타임 크기, 수동 할당/해제
    // ✅ 타입 안전
    // ❌ 메모리 누수 위험
    delete[] cppDynArray;

    // 3. std::array
    std::array<int, 5> stdArray{1, 2, 3, 4, 5};  
    // 스택, 컴파일 타임 크기, 자동 관리
    // ✅ 타입 안전, 크기 정보 유지

    // 4. std::vector (권장!)
    std::vector<int> vec{1, 2, 3, 4, 5};  
    // 힙, 런타임 크기, 자동 관리
    // ✅ 동적 크기 조정
    // ✅ 메모리 자동 해제
    // ✅ 타입 안전

    return 0;
}

메모리 할당 위치 정리

왜 std::vector를 사용해야 하는가?

// ❌ C++ 동적 배열의 문제점
int* arr2 = new int[5];
// delete[] 깜빡하면 메모리 누수
// 크기 변경 불가
delete[] arr2;

// ✅ std::vector의 장점
std::vector<int> vec(5);
// 자동 메모리 관리
// 크기 정보 포함 (vec.size())
// 동적 크기 조정 (vec.push_back())
// 타입 안전
// RAII (자동 소멸)

🔸 std::array

std::array란?

• 컴파일 타임에 크기가 고정된 배열
• 스택 메모리에 할당
• C 스타일 배열을 안전하게 감싼 래퍼

std::array의 장점

std::array<int, 5> arr{1, 2, 3, 4, 5};

// 경계 검사
arr.at(10);  // std::out_of_range 예외 발생

// 크기 확인
std::cout << arr.size() << std::endl;  // 5

// 반복자 사용
for (auto it = arr.begin(); it != arr.end(); ++it)
{
    std::cout << *it << " ";
}

// Range-based for
for (const auto& elem : arr)
{
    std::cout << elem << " ";
}

std::array vs C 배열

// C 배열
int cArr[5];
// sizeof(cArr) == 20 (5 * 4)
// 함수에 전달 시 포인터로 decay
// 크기 정보 손실

void func(int arr[])  // 실제로는 int*
{
    // sizeof(arr) == 8 (포인터 크기)
}

// std::array
std::array<int, 5> stdArr;
// sizeof(stdArr) == 20 (5 * 4)
// 함수에 전달 시 크기 정보 유지

void func(std::array<int, 5>& arr)
{
    // sizeof(arr) == 20
    // arr.size() == 5
}

🔸 다차원 배열과 벡터

메모리 레이아웃 차이

1. 다차원 배열 (스택, 연속된 메모리)

int arr[3][4] = {
    {1, 2, 3, 4},
    {5, 6, 7, 8},
    {9, 10, 11, 12}
};

// 메모리 레이아웃 (연속적):
// [1][2][3][4][5][6][7][8][9][10][11][12]
//  ↑ 스택에 한 번에 할당

2. 다차원 벡터 (힙, 분산된 메모리)

std::vector<std::vector<int>> vec = {
    {1, 2, 3, 4},
    {5, 6, 7, 8},
    {9, 10, 11, 12}
};

// 메모리 레이아웃 (비연속적):
// vec (스택):
// [ptr1][ptr2][ptr3]
//   ↓     ↓     ↓
// 힙:
// [1][2][3][4]  (첫 번째 행)
// [5][6][7][8]  (두 번째 행)
// [9][10][11][12]  (세 번째 행)

연속된 메모리를 사용하는 Wrapper

벡터를 사용하되 연속된 메모리를 유지하려면 1차원 벡터로 관리하고 인덱스 변환을 사용:

class Matrix
{
public:
    Matrix(size_t rows, size_t cols)
        : mRows{rows}, mCols{cols}, mData(rows * cols)
    {
    }

    int& operator()(size_t row, size_t col)
    {
        return mData[row * mCols + col];  // 2D → 1D 인덱스 변환
    }

    const int& operator()(size_t row, size_t col) const
    {
        return mData[row * mCols + col];
    }

private:
    size_t mRows;
    size_t mCols;
    std::vector<int> mData;  // 1차원 벡터로 연속 메모리 보장
};

int main()
{
    Matrix mat(3, 4);

    // 사용
    mat(0, 0) = 1;
    mat(0, 1) = 2;
    mat(1, 0) = 5;

    return 0;
}

🔸 캐시 최적화 (Cache Hit/Miss)

캐시 라인 (Cache Line)

• CPU 캐시의 최소 단위 (보통 64 bytes)
• 메모리를 읽을 때 캐시 라인 단위로 가져옴
• 연속된 메모리는 캐시에 함께 로드됨

잘못된 루프 (Cache Miss 많음)

const size_t ROWS = 1000;
const size_t COLS = 1000;
int arr[ROWS][COLS];

// ❌ 열 우선 순회 (Column-major)
for (size_t col = 0; col < COLS; col++)
{
    for (size_t row = 0; row < ROWS; row++)
    {
        arr[row][col] = 0;  // 메모리 점프 발생!
    }
}

메모리 접근 패턴:

arr[0][0] → arr[1][0] → arr[2][0] → ...
               ↓         ↓ (COLS * 4 bytes 떨어짐)
            캐시 미스!

올바른 루프 (Cache Hit 많음)

// ✅ 행 우선 순회 (Row-major)
for (size_t row = 0; row < ROWS; row++)
{
    for (size_t col = 0; col < COLS; col++)
    {
        arr[row][col] = 0;  // 연속된 메모리 접근!
    }
}

메모리 접근 패턴:

arr[0][0] → arr[0][1] → arr[0][2] → ...
                ↓         ↓ (4 bytes 떨어짐, 같은 캐시 라인)
             캐시 히트!

핵심 규칙: Inner Loop는 Cache Line에 맞춰라

• C/C++ 배열은 row-major 순서로 저장됨
• Inner loop에서 연속된 메모리를 접근하도록 설계
• 열(column) 순회를 inner loop에 배치

🔸 std::deque (Double-Ended Queue)

std::deque란?

• 양쪽 끝에서 삽입/삭제가 O(1)인 컨테이너
• 실무에서는 거의 사용하지 않음
• Vector와 List의 중간 형태

std::deque vs std::vector

#include <deque>
#include <vector>

std::vector<int> vec;
vec.push_back(1);   // 뒤에 추가: O(1) (amortized)
// vec.push_front(0);  // ❌ vector는 push_front 없음

std::deque<int> deq;
deq.push_back(1);   // 뒤에 추가: O(1)
deq.push_front(0);  // ✅ 앞에 추가: O(1)

deque의 메모리 구조 (Chunk Array)

Deque:
┌─────────────────────┐
│ Chunk 포인터들      │ (중앙 배열)
│ [ptr1][ptr2][ptr3] │
└────┬─────┬─────┬────┘
     ↓     ↓     ↓
   청크   청크   청크 (힙)
[▢▢▢▢][■■■■][▢▢▢▢]
           ↑
         데이터

Vector의 재할당 vs Deque의 확장

Vector:

std::vector<int> vec{1, 2, 3, 4};
// 메모리: [1][2][3][4] (capacity: 4)

vec.push_back(5);  // capacity 부족!
// → 새 공간 할당 (capacity: 8)
// → 기존 데이터 전체 복사/이동
// → 기존 공간 해제

Deque:

std::deque<int> deq{1, 2, 3, 4};
// Chunk1: [1][2][3][4]

deq.push_back(5);  // 현재 청크가 가득 찬 경우
// → 새 청크만 할당
// → 기존 데이터는 그대로!
// Chunk1: [1][2][3][4]
// Chunk2: [5][▢][▢][▢]

Deque의 장점

1. push_front() / push_back() 모두 O(1)
2. 재할당 시 기존 데이터를 복사/이동하지 않음
3. Iterator invalidation이 적음 (중간 삽입 제외)

Deque의 단점

1. 두 번의 포인터 역참조 필요

   deq[i];
   // 1. 어느 청크인지 계산
   // 2. 청크 포인터 배열에서 청크 주소 읽기
   // 3. 청크 내에서 오프셋 계산
   // 4. 실제 데이터 접근

2. 캐시 미스 가능성

   • 청크들이 메모리상 분산되어 있음
   • 연속된 접근 시 캐시 효율 떨어짐

3. 메모리 오버헤드

   • 청크 포인터 배열 관리
   • 각 청크마다 약간의 낭비 공간

성능 비교

// 랜덤 접근
vec[1000];   // O(1), 빠름 (한 번의 역참조)
deq[1000];   // O(1), 느림 (두 번의 역참조)

// 앞쪽 삽입
// vec.push_front()  // 없음 (구현하려면 O(n))
deq.push_front(x);   // O(1)

// 뒤쪽 삽입
vec.push_back(x);    // O(1) amortized
deq.push_back(x);    // O(1)

언제 Deque를 사용할까?

• 양쪽 끝에서 삽입/삭제가 빈번할 때
• 중간 접근은 드물 때
• 하지만 대부분의 경우 std::vector가 더 나음

🔸 push_back vs emplace_back

기본 차이

struct Student {
    std::string name;
    int age;
    Student(std::string n, int a) : name(n), age(a) {
        std::cout << "생성자 호출\n";
    }
    Student(const Student& other) : name(other.name), age(other.age) {
        std::cout << "복사 생성자 호출\n";
    }
    Student(Student&& other) : name(std::move(other.name)), age(other.age) {
        std::cout << "이동 생성자 호출\n";
    }
};

std::vector<Student> v;

// push_back: 임시 객체 생성 → 이동 → 소멸
v.push_back(Student("Alice", 20));
// 출력: 생성자 호출 → 이동 생성자 호출

// emplace_back: 컨테이너 내부에서 직접 생성
v.emplace_back("Bob", 21);
// 출력: 생성자 호출 (끝)

언제 emplace_back이 확실히 유리한가?

1. 복사/이동이 비용이 큰 경우

struct BigData {
    std::vector<int> data;
    BigData(int size) : data(size, 42) {}
};

std::vector<BigData> v;

// push_back: 생성 → 이동 (vector 내부 데이터도 이동)
v.push_back(BigData(10000));

// emplace_back: 바로 생성 (이동 없음)
v.emplace_back(10000);  // ✅ 더 효율적

2. 복사 생성자가 delete된 경우

struct NonCopyable {
    NonCopyable(int x) {}
    NonCopyable(const NonCopyable&) = delete;
    NonCopyable(NonCopyable&&) = delete;
};

std::vector<NonCopyable> v;

// v.push_back(NonCopyable(42));  // ❌ 컴파일 에러
v.emplace_back(42);               // ✅ 작동

3. 생성자 인자가 여러 개일 때 (코드 간결성)

struct Point3D {
    double x, y, z;
    Point3D(double x, double y, double z) : x(x), y(y), z(z) {}
};

std::vector<Point3D> points;

// push_back: 임시 객체 명시적 생성
points.push_back(Point3D(1.0, 2.0, 3.0));

// emplace_back: 인자만 전달 (더 간결)
points.emplace_back(1.0, 2.0, 3.0);

C++17 이후의 현실: Copy Elision

std::vector<Student> v;

// C++17 이후: 컴파일러가 임시 객체 생성을 최적화
v.push_back(Student("Alice", 20));
// → 실제로는 vector 내부에 바로 생성될 수 있음 (RVO)

v.emplace_back("Alice", 20);
// → 거의 동일한 코드로 컴파일됨

간단한 타입에서는 차이가 거의 없음:

std::vector<int> v;

v.push_back(42);     // 성능 차이 없음
v.emplace_back(42);  // 성능 차이 없음

주의사항: explicit 생성자

struct Widget {
    explicit Widget(int x) {}
};

std::vector<Widget> v;

// v.push_back(42);     // ❌ 컴파일 에러 (explicit 생성자)
v.emplace_back(42);     // ✅ 작동 (의도치 않은 변환 가능)

실전 가이드

// ✅ emplace_back 사용 권장
std::vector<ComplexType> v;
v.emplace_back(arg1, arg2, arg3);  // 생성자 인자 직접 전달

// ✅ push_back도 괜찮음 (C++17 이후)
std::vector<int> numbers;
numbers.push_back(42);  // 간단한 타입은 가독성 우선

// ✅ 이미 생성된 객체는 push_back
Student s("Alice", 20);
v.push_back(std::move(s));  // 명시적 의도

결론

• 복잡한 객체나 여러 인자: emplace_back 사용
• 간단한 타입이나 가독성 우선: push_back도 OK
• 현대 C++에서는 큰 차이 없는 경우 많음
• 일관성 있게 사용하는 것이 중요

🔸 std::span (C++20)

std::span이란?

• 연속된 메모리 공간을 참조하는 경량 뷰
• 소유권 없이 데이터를 참조만 함
• 배열, vector, array 등을 통일된 인터페이스로 다룸

기본 사용법

#include <span>

void print(std::span<int> data)  // 배열, vector, array 모두 받음
{
    for (int val : data)
    {
        std::cout << val << " ";
    }
    std::cout << std::endl;
}

int main()
{
    // C 배열
    int arr[] = {1, 2, 3, 4, 5};
    print(arr);

    // std::array
    std::array<int, 5> stdArr{1, 2, 3, 4, 5};
    print(stdArr);

    // std::vector
    std::vector<int> vec{1, 2, 3, 4, 5};
    print(vec);

    return 0;
}

std::span의 구조

template<typename T>
class span
{
    T* ptr;      // 데이터 시작 주소 (8 bytes)
    size_t size; // 원소 개수 (8 bytes)
};

// sizeof(std::span<int>) == 16 bytes

메모리 레이아웃

Vector:
┌──────────┐
│ vec      │ (스택)
│ ptr ─────┼───────→ [1][2][3][4][5] (힙)
│ size: 5  │
│ cap: 5   │
└──────────┘

Span:
┌──────────┐
│ span     │ (스택)
│ ptr ─────┼───────→ [1][2][3][4][5] (vec의 데이터를 참조)
│ size: 5  │
└──────────┘
  ↑ 소유권 없음!

주의사항: Dangling Span

std::span<int> createSpan()
{
    std::vector<int> vec{1, 2, 3, 4, 5};
    return std::span{vec};  // ❌ 위험!
}  // vec 소멸

int main()
{
    auto sp = createSpan();
    // sp는 이미 소멸된 vec의 메모리를 가리킴 (Dangling)
    std::cout << sp[0] << std::endl;  // ❌ Undefined Behavior

    return 0;
}

재할당 시 문제

std::vector<int> vec{1, 2, 3};
std::span<int> sp{vec};

std::cout << sp[0] << std::endl;  // ✅ 1

vec.push_back(4);
vec.push_back(5);  // capacity 부족 → 재할당!

// sp는 여전히 옛날 메모리를 가리킴
std::cout << sp[0] << std::endl;  // ❌ Undefined Behavior

안전한 사용법

void process(std::span<int> data)
{
    // data 사용
    for (int& val : data)
    {
        val *= 2;
    }
}  // span 소멸, 하지만 원본 데이터는 유지

int main()
{
    std::vector<int> vec{1, 2, 3, 4, 5};

    // ✅ 안전: process 내부에서만 사용
    process(vec);

    // vec는 여전히 유효
    for (int val : vec)
    {
        std::cout << val << " ";  // 2 4 6 8 10
    }

    return 0;
}

std::span의 장점

1. 통일된 인터페이스

   • 배열, vector, array를 동일하게 처리
   • 함수 오버로딩 불필요

2. 효율적

   • 복사 비용 없음 (16 bytes만)
   • 소유권 없이 참조만

3. 부분 뷰 생성

   std::vector<int> vec{1, 2, 3, 4, 5};
   
   std::span<int> all{vec};                    // 전체
   std::span<int> first3 = all.first(3);       // 처음 3개
   std::span<int> last2 = all.last(2);         // 마지막 2개
   std::span<int> middle = all.subspan(1, 3);  // 중간 3개

std::span vs const T&

// ❌ 배열은 받을 수 없음
void process(const std::vector<int>& data) { }

int arr[] = {1, 2, 3};
// process(arr);  // 컴파일 에러

// ✅ 배열도 받을 수 있음
void process(std::span<int> data) { }
process(arr);  // OK

🔸 핵심 정리

배열과 컨테이너 선택 가이드

• C 배열: 레거시 코드나 성능이 극도로 중요한 경우만
• C++ 동적 배열 (new/delete): ❌ 사용하지 말 것 (std::vector 사용 권장)
• std::array: 컴파일 타임 고정 크기, 스택 할당 필요시
• std::vector: 대부분의 경우 이것을 사용 (권장)

다차원 배열 vs 벡터

• 배열: 연속 메모리 (캐시 효율 좋음)
• 벡터: 분산 메모리 (유연함)
• Wrapper로 연속 메모리 유지 가능

캐시 최적화

• Inner loop는 연속된 메모리 접근
• Row-major 순서 (행 우선)
• 10배 이상 성능 차이 가능

std::deque

• 양쪽 끝 O(1) 삽입/삭제
• 재할당 시 복사 불필요
• 두 번의 포인터 역참조, 캐시 비효율
• 실무에서 거의 사용 안 함

push_back vs emplace_back

• 복잡한 객체: emplace_back 권장
• 간단한 타입: 둘 다 OK
• C++17 이후 성능 차이 줄어듦
• 일관성 있게 사용

std::span (C++20)

• 연속 메모리 참조 뷰
• 소유권 없음 (16 bytes)
• Dangling 주의
• 재할당 시 무효화

<참고 자료>

코드없는 프로그래밍 C++ std::array C++ std::deque C++ std::span