코덱스 연동 데스크톱 펫 프로젝트
코덱스 연동 데스크톱 펫 프로젝트
프로젝트 소개
개요
Haluna는 캐릭터와의 상호작용, 대화, 생활 알림을 바탕화면 위에서 연결해주며 코덱스와도 연동 가능한 작업용 Windows 데스크톱 친구 펫 앱입니다
화면 위의 캐릭터가 클릭과 드래그에 반응하고, 걷고 쉬며 사용자와 일상을 함께합니다. 캐릭터 팩과 의상 교체, 집중 타이머, 생활 알림, 선택적인 Codex 연동을 구현했으며, 개발 도구로는 Godot와 GDScript를 중심으로 사용하였습니다. 또한 캐릭터 제작 도구 Lumate Maker를 별도 프로그램으로 확장하고 있습니다.
1. Haluna 처음 사용하기
① 배포받은 압축 파일이 있다면 전체를 원하는 폴더에 풉니다. 보조 파일이 포함된 배포본에서는 실행파일만 따로 이동하지 않고 함께 보관합니다. ② Haluna.exe를 실행하고 첫 실행 안내를 확인합니다. ③ 캐릭터를 드래그해 원하는 위치로 옮깁니다. 클릭하면 위치와 상태에 따른 반응을 볼 수 있습니다. ④ 캐릭터를 우클릭해 대화, 밥, 장난감과 설정 메뉴를 엽니다. ⑤ 설정에서 캐릭터, 크기, UI 테마, 자동 이동과 중력 사용 여부를 조정합니다. 기본 제공 캐릭터 구성은 배포 버전에 따라 확인해야 합니다. 이 소개 자료에서는 반달과 곰달이를 대표 캐릭터로 사용합니다.
2. 대화하기
캐릭터를 빠르게 두 번 클릭하거나 우클릭 메뉴에서 대화를 엽니다. 발밑에 입력창을 표시하면 별도 창을 열지 않고도 짧게 말을 걸 수 있습니다. 빠른 입력창은 우클릭 메뉴에서 켜고 끌 수 있습니다. 로컬 답변은 미리 준비한 규칙을 사용합니다. 모든 주제의 질문에 답하는 소형 언어 모델을 앱 안에 내장한 방식은 아닙니다. 자동 혼합 모드는 앱이 아는 생활 대화를 로컬에서 처리하고, 그 밖의 질문은 연결된 Codex에 요청합니다. 외부 연결이 실패하면 안내 후 로컬 응답으로 돌아가는 흐름이 있습니다. Codex 또는 OpenAI 연동을 선택하면 해당 외부 서비스에 필요한 질문과 문맥을 전달할 수 있습니다. 포트폴리오 시연에는 개인 정보가 없는 시험 대화를 사용합니다.
3. 중력과 자동 이동
중력 켜기: 캐릭터가 바닥을 중심으로 좌우 이동합니다. 공중에 놓으면 낙하와 착지 상태를 거치며, 높은 곳에서 떨어진 경우 추가 반응이 나올 수 있습니다. 중력 끄기: 현재 모니터의 작업 영역 안에서 가로와 세로 방향으로 이동합니다. Codex 작업 표시, 집중 시간, 대화 등 다른 행동이 활성화된 동안은 평소의 자율 행동이 제한될 수 있습니다. 모니터 사이를 스스로 왕복하는 기능으로 설명하지는 않습니다.
4. 밥과 장난감 그리고 물건 가져오기
우클릭 메뉴에서 밥이나 장난감을 선택하고 놓을 위치를 지정합니다. 캐릭터가 접근해 먹거나 노는 반응을 합니다. 물건 가져오기는 공 또는 곰 인형을 대상으로 접근, 줍기, 운반, 내려놓기 동작을 연결합니다. 이 물건은 앱 내부 소품이며, 바탕화면의 실제 파일을 이동하는 기능은 아닙니다.
5. 집중 시간과 생활 알림
생활 기능 화면에서 집중할 시간을 정하고 시작합니다. 일시정지, 계속하기와 취소를 사용할 수 있으며 집중 중에는 일부 자율 대사와 장난을 억제합니다. 물 마시기, 스트레칭, 잠깐 휴식 알림은 지정한 시각에 표시됩니다. 알림은 Haluna가 실행 중일 때 작동합니다. 종료 중 지나간 알림을 다시 켰을 때 몰아서 보여주지 않으며, 진행 중인 집중 타이머도 종료 후 자동으로 이어지지 않습니다. 추억 수첩에는 첫 만남, 집중 완료, 물건 가져오기 같은 사건이 기록됩니다. 대화용 기억과 활동 기록은 별도 기능입니다.
6. Codex 연동
Haluna의 연결 안내에 따라 Codex CLI를 준비하고 로그인한 뒤 답변 방식을 선택합니다. 설치와 로그인 여부, 네트워크와 계정 상태에 따라 사용할 수 있는 기능이 달라집니다. 캐릭터와 대화하기와 Codex에 작업 요청하기는 다릅니다. 작업을 이어 가려면 작업 요청 화면에서 대상 작업을 확인하고 명령을 보냅니다. 이 기능을 Codex 사이드바의 새 프로젝트를 자동 등록하는 기능으로 이해하면 안 됩니다. 작업 중 표시되는 모션과 말풍선은 수집한 이벤트를 단계별로 분류한 안내입니다. AI의 내부 사고를 보여주거나 모든 내용을 실시간으로 요약한 것은 아닙니다. 응답 속도와 연결 상태는 별도로 확인해야 합니다.
7. 실제 화면 터치와 장난 기능
설정의 캐릭터 관리에서 사용할 캐릭터를 선택합니다. 사용자 캐릭터를 추가할 때에는 지원 규격의 통합 시트 또는 동작별 시트와 설정을 사용합니다. 모든 그림을 단순히 한 장에 모은 이미지가 자동으로 호환되는 것은 아닙니다. 프레임 크기, 행 순서, 동작 수와 메타데이터가 중요합니다. 시트 교체는 기존 캐릭터의 애니메이션 이미지를 바꾸는 기능입니다. 의상 변경은 완성된 팩이나 시트를 등록해 외형을 전환하는 기능이며, 임의의 의상 사진을 자동으로 입혀 주는 기능은 아닙니다. 기본 캐릭터와 사용자 캐릭터는 관리 범위가 다릅니다. 삭제 전에는 선택한 사용자 팩이 맞는지 확인하고 필요한 원본을 보관합니다. 설정과 사용자 캐릭터 데이터는 실행파일과 별도 사용자 데이터 폴더에 저장됩니다.
☆. Maker
Maker는 Haluna의 캐릭터 제작툴의 프로토 타입입니다. Haluna의 가이드에 맞게 자동으로 내가 원하는 캐릭터를 만들어주는 프로그램 입니다. 환경 확인 → 참고 이미지와 캐릭터 정보 입력 → 프로젝트별 외형 학습 → 기준 후보 4장 비교와 승인 → 모션 제작과 검수 → 캐릭터 팩 내보내기 구조로 작동합니다 Maker는 ComfyUI 포터블과 필요한 모델을 설치하거나 기존 설치 폴더에 연결합니다. 전용 Python을 사용하는 구조이므로 시스템 Python을 별도로 설치하는 흐름은 아니지만, 모델과 제작 환경의 추가 다운로드는 필요합니다. 현재 프로젝트가 정한 지원 기준은 Windows 10/11, NVIDIA RTX 계열 VRAM 12GB 이상, 시스템 메모리 32GB 이상, SSD 여유 공간 50GB 이상입니다. 이것은 Maker의 제작 환경 기준이며 Haluna 펫 앱의 최소 사양이 아닙니다. 이 사양에서도 생성 시간과 품질을 일정하게 보장하지는 않습니다. 참고 이미지 1~3장과 주 외형 기준을 선택하고 이름, 성격, 말투와 출력 방향을 입력합니다. 생성된 네 후보 중 기준 모습을 승인한 뒤 모션 작업을 시작합니다. 결과는 각 동작과 프레임을 직접 재생해 검수합니다. 안전 모션은 승인 이미지를 변형해 외형을 보존하는 경로입니다. 새로운 관절 포즈를 그리는 경로와는 차이가 있습니다. 현재 내보내기 구현은 동작별 PNG 시트, character.json과 ZIP을 생성합니다. Haluna의 지원 형식과 맞는지 확인한 뒤 가져오기 절차를 진행합니다.