안내 (작업 중 · 개발 서버 반영 및 검증 단계): 본 개발일기에 기록된 캐시 얼굴장식 표정 오버레이(emotion_name) 및 표정 얼굴장식 25종 동기화 설계는 현재 개발 환경에 반영되어 실데이터 교차 검증을 진행 중인 항목(IN_PROGRESS)입니다. 정식 배포 시점에 상태가 적용 완료로 전환됩니다.

관련 페이지 바로가기: 캐릭터 룩 & 코디 둘러보기 (/character) · 통합 아카이브 (/archive) · 개발일기 목록 (/community/dev-diary)

1. 배경 및 문제 의식: 넥슨 API는 정상 지원하는데, 왜 너공마는 특별히 다르게 구현했는가?

메이플스토리의 캐시 코디에서 얼굴장식(Face Accessory) 슬롯은 볼터치·안대·가면처럼 얼굴 위에 도트 이미지를 얹는 기능뿐 아니라, 기존 얼굴장식 위에 특정 표정을 덧씌우는 표정 오버레이(Emotion Overlay)와 캐릭터의 기본 표정을 상시 고정하는 표정 얼굴장식 25종(1012877~1012901) 시스템을 함께 담당합니다.

1-1. 넥슨 오픈 API 기본 제공 이미지(character_image)의 구조적 한계

결론부터 말하면 넥슨 오픈 API 자체는 얼굴장식 표정 오버레이를 정상적으로 지원합니다. 실제로 캐릭터 기본 정보(/maplestory/v1/character/basic)의 character_image는 오버레이된 표정이 반영된 이미지를 반환하며, 캐시 장비 조회(/maplestory/v1/character/cashitem-equipment)에서도 얼굴장식 슬롯 내부에 emotion_name 필드를 내려줍니다.

그러나 넥슨 API에서 제공하는 캐릭터 이미지는 구조적으로 다음과 같은 치명적인 표현 한계를 가지고 있습니다.

• 제한된 프레임 수와 단일 평면 이미지의 강제 동시 재생: 넥슨 API가 제공하는 이미지는 캐릭터의 신체, 성형, 얼굴장식, 무기, 망토, 반지·모자·세트 이펙트가 모두 한 장의 단일 이미지로 합쳐진(Flattened) 형태이며, 호출 가능한 프레임 수도 제한되어 있습니다.
• 따로 움직여야 하는 독립 객체들의 프레임 표현 불가: 실제 인게임에서는 캐릭터의 신체 호흡 동작(예: stand1 4프레임), 얼굴 표정 및 눈 깜빡임 애니메이션(예: blink 비주기 깜빡임, glitter·blaze 등의 고유 표정 주기), 그리고 장비·세트·캐시 이펙트(각기 다른 프레임 수와 딜레이를 가진 독립 객체들)가 서로 완전히 다른 타이밍과 프레임 주기로 따로 움직입니다. 하지만 단일 이미지 방식에서는 모든 요소가 한 프레임 번호에 묶여 동시에 재생되어야 하므로, 따로 움직여야 하는 객체들의 고유 프레임과 자연스러운 비동기 움직임이 원천적으로 표현되지 않습니다.

1-2. 메애기 등 기존 API 이미지 기반 서비스의 한계와 오버레이 누락 문제

메애기를 비롯한 기존 코디·아바타 서비스들은 넥슨 API가 제공하는 이미지를 그대로 불러와 재생하거나 정적 프레임 단위로 묶어 처리하기 때문에 다음과 같은 문제가 발생합니다.

• 객체별 독립 애니메이션 표현의 한계: API 이미지에 의존하므로 프레임이 제한되고 모든 레이어가 동시에만 넘어가는 한계에 갇혀, 캐릭터 본체와 표정·이펙트 객체들이 각자의 속도로 살아 움직이는 인게임 코디 화면을 재현할 수 없습니다.
• 일부 환경 및 프리셋·커스텀 화면에서의 표정 오버레이 미표시: 넥슨 API의 기본 character_image는 현재 장착 활성화된 단 하나의 프리셋만 이미지로 제공할 뿐, 비활성 프리셋(1·2·3번 프리셋 개별 확인)이나 자유 코디 시뮬레이션, 아이템 교체 미리보기 이미지는 별도로 만들어 주지 않습니다. 이 때문에 기존 서비스나 일부 코디 화면에서는 프리셋을 전환하거나 코디를 조합할 때 얼굴장식 표정 오버레이(emotion_name)나 표정 얼굴장식이 아예 표시되지 않고 기본 무표정(default)으로 풀려버리는 문제가 발생합니다.

1-3. 너공마의 해결책: 독립 멀티 타임라인 코디 엔진 + 표정 오버레이 전 구간 동기화

구분	넥슨 오픈 API 기본 이미지 / 메애기 등 기존 방식	너공마 실시간 코디 엔진
렌더링 방식	단일 평면 합성 이미지 호출 (모든 부위가 한 장으로 묶임)	부위·레이어별 실시간 캔버스 분리 합성
프레임 및 객체 움직임	프레임 수 제한 및 강제 동시 재생으로 따로 움직여야 하는 객체(몸통·표정·이펙트) 프레임 표현 불가	신체 동작 클럭 · 표정 클럭 · 이펙트 클럭을 분리해 각 객체가 고유 프레임과 딜레이로 독립 재생
얼굴장식 표정 오버레이	현재 대표 이미지만 반영되거나, 프리셋 전환·시뮬레이터 등 일부 화면에서 오버레이 미표시	emotion_name 및 표정 얼굴장식 25종을 엔진 표정 타임라인에 직결해 전 프리셋·코디엔진·아카이브에서 누락 없이 표시
특수 서브프레임 표정	감은눈(blink/1), 게슴츠레(blink/2) 등 세부 프레임 제어 한계	<action>/<frame> 서브프레임 고정 합성 및 오드아이·믹스렌즈 동시 적용

즉 너공마는 "따로 움직여야 하는 객체들의 프레임을 인게임 그대로 표현하기 위해" 자체 멀티 타임라인 아바타 엔진을 구축했으며, 여기에 넥슨 오픈 API의 emotion_name 응답과 표정 얼굴장식 25종 시스템을 정밀 연동함으로써 기존 API 이미지 방식의 프레임 표현 한계와 일부 서비스의 표정 오버레이 미표시 문제를 동시에 해결했습니다.

---