# sephiria_inv_program

세피리아(Sephiria) 인벤토리 석판 배치 최적화 도구.

내가 보유한 석판 목록을 넣으면, 인벤토리 격자에 어떻게 배치해야 효과 합이
가장 높아지는지 계산하고 결과 이미지를 만들어 줍니다.

## 기능

- 보유 석판 입력 → 효과 합이 최대가 되는 슬롯 배치 자동 계산
- 결과를 PNG 이미지로 저장 (각 셀의 효과 수치를 함께 표시)
- 회전 가능한 석판은 회전까지 포함해 탐색
- GUI(Tkinter) + CLI 둘 다 제공
- 게임 스크린샷에서 보유 석판 자동 인식 (베타, 템플릿 매칭)
- 단일 파일 포터블 EXE 빌드 지원 (PyInstaller)

## 데이터 출처

석판 카탈로그와 효과 식은 오픈소스 팬위키
[WhiteDog1004/sephiria](https://github.com/WhiteDog1004/sephiria) 의
`src/features/simulator/config/` 에 있는 정의를 그대로 포팅한 것이며,
석판 이미지는 같은 사이트가 사용하는 CDN(`https://img.sephiria.wiki`)에서
필요할 때 받아 캐시합니다. 게임 내부 메모리에서 데이터를 직접 읽어오지는
않습니다 (공개 API가 없음).

## 빠른 사용 - GUI

```bash
python -m sephiria_inv
```

GUI 는 두 가지 탭으로 구성됩니다.

**스크린샷 탭 (권장)**
1. 게임을 인벤토리 화면 상태로 띄워둔다
2. `화면 캡처` 버튼을 누른다 (또는 `이미지 열기…` 로 미리 찍어둔 PNG)
3. 인벤토리 격자의 좌상단/우하단을 한 번씩 클릭해 영역을 지정한다
4. 자동으로 템플릿 매칭이 돌면서 각 셀의 석판을 인식한다
5. 오인식된 셀이 있으면 클릭해서 직접 교체하고 `이 구성으로 계산` 을 누른다

**수동 선택 탭**
좌측 카탈로그에서 보유한 석판 옆 `+` 버튼으로 개수를 올리고
`최적 배치 계산`을 누르면 됩니다. 결과 이미지는 `이미지 저장…` 으로
PNG 저장이 가능합니다.

## CLI

```bash
# 일반/고급/희귀/전설 석판 목록 보기
python -m sephiria_inv --list

# 직접 지정 (value:count 형식)
python -m sephiria_inv --cli \
  -s harvesting:2 -s binary_star -s thorn -s sheen -s base \
  --slots 24 --seed 7 -o layout.png

# 스크린샷에서 인식 (CLI - bbox 수동 지정)
python -m sephiria_inv --cli \
  --screenshot ./game.png --bbox 320,180,1024,720 \
  --slots 34 -o layout.png
```

CLI 에서는 `--bbox left,top,right,bottom` 으로 격자 영역을 직접 줘야 합니다.
GUI 에서는 두 번 클릭으로 같은 일을 할 수 있습니다. 인식 정확도는 스크린샷
해상도/UI 스타일에 따라 다르므로 잘못된 셀은 GUI 에서 클릭해 교정하세요.

## 포터블 EXE 빌드

Windows 게임 PC 에서:

```bat
build.bat
```

Python 3.10 이상이 PATH 에 있어야 합니다. 결과물은 `dist\sephiria_inv.exe`
한 파일이며, 다른 의존성 없이 그대로 실행됩니다.

리눅스 테스트용 단일 바이너리:

```bash
./build.sh
```

## 점수 함수

기본 점수는 `Σ effects[slab_cell]` 입니다 — 즉 "내가 놓은 석판의 칸에 다른
석판들이 만들어주는 효과 합". 게임에서 아티팩트가 그 칸에 있을 때 받는
보너스와 동일한 양입니다. 어느 칸에 아티팩트를 놓을지 모르므로, 모든
석판 칸을 잠재 아티팩트 위치로 가정합니다.

`flag = "ignore"` 가 적용된 칸(예: 환대, 이음, 고양)은 합에서 제외합니다.

## 솔버

순열 전체 탐색은 슬롯 수가 30 을 넘으면 불가능하므로, 다음과 같이 동작합니다:

1. 슬롯에 석판을 랜덤 배치
2. swap/move/rotate 세 가지 작은 변화 중 하나를 시도
3. 점수가 오르면 채택, 아니면 되돌림 (1차 개선 힐 클라이밍)
4. 시간 한도 안에서 여러 번 재시작해 최고 해를 기록

기본 4초 정도면 슬롯 34 / 석판 20 규모는 충분히 수렴합니다.

## 한계

- 게임 메모리 / 세이브 파일에서 직접 데이터 읽기는 지원하지 않음
- 스크린샷 인식은 템플릿 매칭이라 흐릿하거나 압축이 강한 이미지에서는
  오인식이 생길 수 있음
- 아티팩트 효과(레벨 보너스, 조건부 효과)는 점수에 반영하지 않음 — 순수
  석판 효과 합만 본다. 향후 v2 에 아티팩트 슬롯 지정 옵션을 넣을 예정
- "석판 합치기"(같은 등급 석판 결합) 기능은 향후 작업

## 라이선스

석판 이름/효과식/이미지 자산의 저작권은 원작 게임 *Sephiria* 의 개발자에게
있습니다. 본 도구는 팬 메이드 보조 도구이며, 데이터 사용 가이드라인은
WhiteDog1004/sephiria 의 정책을 따릅니다.