ES 스테이션 커스텀 메뉴 만들기

에뮬스테이션 하이브리드 커스텀 메뉴 구축 가이드 (1).pdf

0.51MB

 

에뮬스테이션 하이브리드 커스텀 메뉴 구축 가이드

gamelist.xml 메타데이터 매핑 및 확장자별 통합 분기(launcher.sh) 시스템 빌드

개정일: 2026년 6월 | 대상 플랫폼: RetroPie, Batocera, EmuELEC 기반 시스템

본 가이드는 에뮬스테이션(EmulationStation)에서 쉘 스크립트(.sh) 파일만 노출되어 UI가 투박해지는 한계를 극복하고, 멋진 타이틀 이름, 스크린샷, 로고, 상세 가이드 설명이 미디어 파일과 완벽히 믹싱된 하이브리드 메뉴판을 제작하는 고급 커스텀 기법을 다룹니다.

1. 하이브리드 매핑 시스템의 핵심 원리

실제 백엔드에서는 볼륨 조절 스크립트나 이미지 뷰어가 돌아가더라도, 에뮬스테이션 프론트엔드 화면에는 gamelist.xml 데이터를 강제로 파싱하여 정갈한 한글 이름과 아이콘, 설명으로 치환해 노출시키는 구조입니다.

• 실제 파일 구조: vol_setting.sh, jamma_pinout.png, readme.txt
• 사용자 체감 화면: 테마 레이아웃에 맞춰 스크린샷 썸네일과 조작 안내가 포함된 고화질 커스텀 휠 메뉴판

2. 구체적인 단계별 구현 절차

STEP 1시스템 설정 파일 (es_systems.cfg) 수정

스크립트 외에 이미지나 텍스트 문서 파일도 파일 목록(롬 리스트)으로 인식할 수 있도록 확장자를 추가하고, 중앙 집중형 매핑 런처인 launcher.sh를 호출하도록 커맨드를 수정합니다.

파일 경로: /opt/retropie/configs/all/emulationstation/es_systems.cfg

<system>
    <name>arcade_tools</name>
    <fullname>아케이드 기통 설정 및 매뉴얼</fullname>
    <path>/home/pi/RetroPie/roms/arcade_tools</path>
    <extension>.sh .SH .png .PNG .txt .TXT .pdf .PDF</extension>
    <command>bash /home/pi/RetroPie/roms/arcade_tools/launcher.sh %ROM%</command>
    <platform>arcade_tools</platform>
    <theme>arcade_tools</theme>
</system>

STEP 2디렉토리 및 파일 배치

지정한 메뉴 롬 폴더(/home/pi/RetroPie/roms/arcade_tools/)를 생성하고 구동할 다양한 리소스 파일을 자유롭게 배치합니다.

• vol_setting.sh : 볼륨 조절 리눅스 스크립트
• jamma_pinout.png : 잠마 표준 28핀 배열 회로도 이미지
• readme.txt : 기통 구동 전 필독 주의사항 텍스트 문서

STEP 3gamelist.xml 작성을 통한 파일과 UI 바인딩

해당 폴더 내부에 gamelist.xml 파일을 생성하고 아래 구조로 작성하여 스크립트와 일반 파일이 완벽하게 하나의 '게임 선택 목록'처럼 믹싱되도록 설계합니다.

<?xml version="1.0"?>
<gameList>
    <!-- 1. 쉘 스크립트 매핑 (볼륨 설정) -->
    <game>
        <path>./vol_setting.sh</path>
        <name>🔊 디지털 시스템 볼륨 설정</name>
        <desc>아케이드 기통의 내부 메인 사운드 볼륨을 디지털로 정밀 조절합니다.</desc>
        <image>./media/images/volume_thumb.png</image>
    </game>

    <!-- 2. 이미지 파일 매핑 (회로도 보기) -->
    <game>
        <path>./jamma_pinout.png</path>
        <name>🔌 JAMMA 28핀 배열 회로도</name>
        <desc>버튼 배선 및 전원 공급 라인 확인을 위한 아케이드 표준 잠마 핀배열도입니다.</desc>
        <image>./jamma_pinout.png</image>
    </game>

    <!-- 3. 텍스트 파일 매핑 (안내 문구) -->
    <game>
        <path>./readme.txt</path>
        <name>⚠️ 기통 구동 전 필독 주의사항</name>
        <desc>초기 부팅 전압 설정 및 모니터 주파수(15kHz/31kHz) 변경 시 주의사항 안내문.</desc>
        <image>./media/images/warning_thumb.png</image>
    </game>
</gameList>

3. 확장자별 백엔드 실행 명령어 고도화 (launcher.sh)

위와 같이 믹스했을 때, .sh 파일 외에 일반 이미지나 텍스트 파일은 에뮬스테이션이 자체적으로 열 수 없습니다. 따라서 중앙 실행 런처(launcher.sh)가 인자값(%ROM%)을 받아 확장자별 최적의 리눅스 콘솔 앱으로 안전하게 분기 호출하도록 설계해야 합니다.

런처 스크립트 경로: /home/pi/RetroPie/roms/arcade_tools/launcher.sh

#!/bin/bash
ROM_FILE="$1"
EXTENSION="${ROM_FILE##*.}"

case "$EXTENSION" in
    sh|SH)
        # 스크립트 파일은 그대로 bash 쉘로 독립 실행
        bash "$ROM_FILE"
        ;;
    png|PNG|jpg|JPG)
        # 이미지 파일은 프레임버퍼 뷰어(fbv)를 호출하여 화면 전체에 다이렉트 출력
        fbv -f "$ROM_FILE"
        ;;
    txt|TXT)
        # 텍스트 파일은 ncurses 기반 터미널 대화창(dialog) 텍스트박스로 출력
        dialog --textbox "$ROM_FILE" 22 70
        ;;
    *)
        echo "지원하지 않는 메뉴 포맷입니다."
        ;;
esac

🛠️ 최종 활성화 필수 권한 설정 명령

런처 및 내부 스크립트가 리눅스 커널 상에서 정상 기동하도록 반드시 터미널에 아래 커맨드를 입력하여 실행 권한을 활성화해야 합니다.
chmod +x /home/pi/RetroPie/roms/arcade_tools/*.sh

4. 기대효과 및 트러블슈팅

본 고도화 아키텍처를 도입하면 에뮬스테이션 UI 상에서는 파일 포맷에 무관하게 통일감 있는 하나의 고품질 메뉴 시스템이 빌드됩니다. 만약 목록 수정 후 정상 노출되지 않는다면 에뮬스테이션 내 UI Settings ➔ Parse Gamelist Only 옵션을 해제한 뒤 리스타트하여 파싱 로그를 확인하십시오.

---

5. 정석 시나리오: runcommand.sh 기반 독립 기능 메뉴 구성

비디오 재생, 매뉴얼 출력, 볼륨 조절 등 에뮬레이터와 무관한 독립된 기능 화면을 에뮬스테이션에 구성하는 가장 정석적이고 구체적인 시나리오입니다. 이 방식은 레트로파이(RetroPie)의 핵심 백엔드 구동기인 runcommand.sh를 응용하여, 롬 파일 자리에 쉘 스크립트(.sh)를 밀어 넣고 구동하는 매커니즘입니다. 순서대로 따라 하면 나만의 시스템 메뉴를 빌드할 수 있습니다.

🛠 [1단계] 가상 시스템 등록 (es_systems.cfg)

에뮬스테이션이 내 커스텀 메뉴 폴더와 쉘 스크립트 실행 명령어를 인식하도록 시스템 파일에 새 기종을 선언합니다.

수정할 파일 경로: /opt/retropie/configs/all/emulationstation/es_systems.cfg

파일 가장 아래쪽 </systemList> 바로 위에 아래 코드를 추가합니다.

<system>
    <name>arcade_tools</name>
    <fullname>아케이드 기통 설정 및 매뉴얼</fullname>
    <path>/home/pi/RetroPie/roms/arcade_tools</path>
    <extension>.sh .SH</extension>
    <command>bash /opt/retropie/supplementary/runcommand/runcommand.sh 0 _SYS_ arcade_tools %ROM%</command>
    <platform>arcade_tools</platform>
    <theme>arcade_tools</theme>
</system>

핵심 포인트

<command> 태그를 보면 일반 에뮬레이터(MAME 등) 대신 runcommand.sh를 호출합니다. 뒤에 붙은 인자들은 이 스크립트가 실행될 때 레트로파이 시스템 환경을 유지하며 안전하게 터미널 백엔드에서 돌아가도록 만들어 줍니다.

💡 es_systems.cfg 파일 생성 및 수정 가이드

1) 새로 만들어야 할 때의 파일 정보

• 확장자까지 포함한 전체 파일명: es_systems.cfg
• 파일 성격: 일반 텍스트 파일 (메모장이나 Notepad++ 등으로 편집 가능)

2) 파일이 이미 있을 때 수정하는 위치 (정석)

기존 es_systems.cfg 파일을 메모장으로 열면 아래와 같은 구조로 되어 있습니다. 가장 밑바닥으로 내려가서 </systemList> 바로 위에 제공된 코드를 삽입하시면 됩니다.

<?xml version="1.0"?>
<systemList>

    <system>
        <name>arcade_tools</name>
        <fullname>아케이드 기통 설정 및 매뉴얼</fullname>
        <path>/home/pi/RetroPie/roms/arcade_tools</path>
        <extension>.sh .SH</extension>
        <command>bash /opt/retropie/supplementary/runcommand/runcommand.sh 0 _SYS_ arcade_tools %ROM%</command>
        <platform>arcade_tools</platform>
        <theme>arcade_tools</theme>
    </system>
</systemList>

3) 만약 경로에 파일이 아예 없어서 "새로" 만들어야 한다면?

경로가 텅 비어있다면 메모장을 켜고 위의 전체 구조(<?xml ...>부터 </systemList>까지)를 모두 적어주신 후, 저장할 때 파일 형식을 모든 파일(*.*)로 바꾸고 파일명을 es_systems.cfg라고 정확히 입력하여 저장하시면 됩니다.

요약: 최종 결과물 파일명은 es_systems.cfg 입니다!

🎨 [2단계] 테마(Theme) 레이아웃 구성

시스템 등록이 끝나면 게임기 선택 화면에서 내 메뉴가 멋지게 표시되도록 UI 폴더를 매핑해야 합니다.

• 폴더 생성: 현재 사용 중인 테마 폴더 안으로 이동하여 새로운 폴더를 만듭니다. 경로 예시: /etc/emulationstation/themes/사용중인테마폴더/arcade_tools/
• 리소스 복사 및 수정: 맨땅에서 XML을 짜면 좌표 잡기가 어려우므로, 기존에 있던 retropiemenu 폴더나 ports 폴더 안에 있는 theme.xml 파일을 그대로 복사해서 새 폴더에 붙여넣습니다.
• 디자인 변경: 폴더 내에 있는 로고 이미지 파일(logo.png)을 아케이드 툴이나 매뉴얼 느낌이 나는 커스텀 투명 PNG 파일로 교체합니다.

📜 [3단계] 기능 구현을 위한 쉘 스크립트(.sh) 작성

이제 1단계에서 지정한 롬 경로(/home/pi/RetroPie/roms/arcade_tools) 폴더를 생성하고, 게임기 안에서 메뉴 리스트로 뜰 실행 파일들을 작성합니다. 파일 이름이 곧 에뮬스테이션 화면에 텍스트 목록으로 출력됩니다.

예시 1) 아케이드 기통 가이드 영상 플레이어 (1_기통 사용 가이드.sh)

롬 폴더에 파일을 만들고 아래 코드를 넣습니다. (mpv나 omxplayer 등 리눅스 콘솔 플레이어 활용)

#!/bin/bash
# 에뮬스테이션 화면을 잠시 숨기고 풀스크린 가이드 영상 재생
mpv --fullscreen /home/pi/RetroPie/roms/arcade_tools/assets/guide_video.mp4

예시 2) 프레임버퍼 기반 매뉴얼 이미지 뷰어 (2_전체 회로도 보기.sh)

X윈도우(데스크톱) 없이 아케이드 화면에 직접 이미지를 풀스크린으로 띄우는 fbv(Framebuffer Viewer) 도구를 활용합니다.

#!/bin/bash
# 16:9 비율로 맞춘 회로도 PNG 파일을 화면 전체에 출력
fbv -f /home/pi/RetroPie/roms/arcade_tools/assets/schematic.png

예시 3) 아케이드 볼륨 디지털 조절기 (3_시스템 볼륨 설정.sh)

텍스트 기반의 편리한 리눅스 오디오 설정 창인 alsamixer를 띄워 기통 내부 볼륨을 키보드/조이스틱 방향키로 조절하게 만듭니다.

#!/bin/bash
alsamixer

🔄 [4단계] 권한 부여 및 확인

스크립트 파일 작성이 완료되었다면, 에뮬스테이션이 이 파일들을 '실행 가능한 프로그램'으로 인지할 수 있도록 터미널에서 실행 권한(Chmod)을 반드시 부여해야 합니다.

chmod +x /home/pi/RetroPie/roms/arcade_tools/*.sh

모든 작업이 끝난 후 에뮬스테이션을 재시작(Restart EmulationStation)하면, 기존 MAME나 네오지오 게임기 목록 사이에 "아케이드 기통 설정 및 매뉴얼" 기종이 당당하게 자리 잡고 있으며, 안으로 들어가면 내가 만든 스크립트 목록이 게임 리스트처럼 정갈하게 뜨게 됩니다. 고른 후 실행하면 검은 화면의 리눅스 터미널 유출 없이 깔끔하게 풀스크린으로 해당 툴이 구동됩니다.

EmulationStation Custom Menu Build & Advanced Mixing Guide