Skip to content

Tools Timer

wcorn edited this page Apr 5, 2026 · 4 revisions

메이플 재획 타이머

메이플스토리 재획/버프 재사용을 돕는 2단계 주기 알림 타이머. Tools 모듈 내 첫 도구.

1. 유스케이스

배경

메이플스토리 사냥 중 재물획득의 비약·재획서 등 시간제 버프를 주기적으로 재사용해야 한다. 두 종류의 쿨타임이 연속으로 순환하는 경우가 많다.

시나리오

  1. 사용자가 타이머 화면에 진입한다.
  2. Timer 1, Splits, Timer 2를 입력한다 (예: 105, 2, 15).
  3. 시작 버튼을 누르면 알림 시퀀스가 순환한다.
  4. 매 알림마다 소리·시각 피드백으로 재사용 타이밍을 알려준다.
  5. 필요 시 일시정지·리셋·정지로 제어한다.
  6. 자주 쓰는 설정은 프리셋으로 저장해 재사용한다.

핵심 가치

  • 화면을 계속 보지 않아도 소리로 알림을 받는다.
  • 여러 중간 알림으로 버프 끝나기 전 미리 준비할 수 있다.

2. 타이머 모델

2.1 입력 파라미터

필드 타입 범위 기본값 설명
time1 number (seconds) > 0 105 첫 번째 시간
splits integer ≥ 1 2 time1 등분 개수
time2 number (seconds) ≥ 0 15 두 번째 시간
  • 입력 단위는 초. 소수점 1자리까지 허용.
  • time2 = 0이면 Timer 2 구간 생략.

2.2 알림 시퀀스 생성 규칙

intervals = [time1/splits] × splits  +  [time2]   (time2 > 0)
intervals = [time1/splits] × splits                (time2 = 0)
  • 사이클당 알림 개수: splits + 1 (time2=0이면 splits)
  • 주기: time1 + time2

2.3 예시

time1 splits time2 알림 간격 시퀀스 주기
105 2 15 52.5, 52.5, 15 120s
105 3 15 35, 35, 35, 15 120s
60 1 0 60 60s
120 4 30 30, 30, 30, 30, 30 150s
105 2 0 52.5, 52.5 105s

2.4 알림 누적 시각

t[0] = 0 (시작 시점)
t[k] = t[k-1] + intervals[(k-1) mod len(intervals)]

사용자 예시 (105, 2, 15)의 알림 누적 시각:

52.5s, 105s, 120s, 172.5s, 225s, 240s, 292.5s, 345s, 360s, ...

3. 상태 머신

     ┌─── start ───┐
     ▼             │
   idle ─────→ running ──── pause ───→ paused
     ▲             │                     │
     │             │ reset              resume
     │             │   ▲                 │
     │             ▼   │                 │
     └── stop ── running ◄──────────────┘
상태 설명 가능 액션
idle 초기 상태. 설정 편집 가능 start
running 알림 루프 동작 중 pause, reset, stop
paused 일시정지. 경과 시간 보존 resume, reset, stop
액션 동작
start 현재 설정으로 타이머 시작. idle → running
pause 현재 경과 시간 유지, 알림 루프 중단. running → paused
resume 중단된 지점부터 이어서 진행. paused → running
reset 경과 시간·알림 카운트 초기화. 상태는 유지
stop 모든 상태 초기화. * → idle

4. 화면 설계

4.1 레이아웃

┌──────────────────────────────────────────┐
│  ← 뒤로  |  메이플 재획 타이머  |  테마 ⏻ │  헤더
├──────────────────────────────────────────┤
│  ┌─ 설정 패널 ──────────────────────┐    │
│  │  Timer 1: [  105  ] 초           │    │
│  │  등분:   [   2   ] 회            │    │
│  │  Timer 2: [  15   ] 초           │    │
│  │  미리보기: 52.5s → 52.5s → 15s   │    │
│  │  (주기 120s, 사이클당 3회 알림)   │    │
│  └──────────────────────────────────┘    │
│                                          │
│  ┌─ 실행 뷰 ────────────────────────┐    │
│  │                                  │    │
│  │      00 : 52 . 5                 │    │
│  │   다음 알림까지                   │    │
│  │                                  │    │
│  │  [━━━━━━━━━────────]  60%        │    │
│  │                                  │    │
│  │  3회차 진행 중 · 단계 1/3         │    │
│  └──────────────────────────────────┘    │
│                                          │
│  [▶ 시작]  [⟲ 리셋]  [■ 정지]            │
│                                          │
│  알림 설정                               │
│  ☑ 소리                                  │
│    알림음 [기본 알림     ▼] [▶ 미리듣기]  │
│    볼륨  [━━━━━━──] 70%                  │
│  ☐ 브라우저 알림                         │
│                                          │
│  프리셋                                  │
│  [+ 현재 설정 저장]                      │
│  • 기본 재획 (105/2/15)        [불러오기]│
│  • 빠른 재획 (60/1/0)           [불러오기]│
└──────────────────────────────────────────┘

4.2 설정 패널

  • idle 상태에서만 편집 가능 (running/paused는 비활성화)
  • 숫자 입력 필드 3개 (Timer 1, Splits, Timer 2)
  • 실시간 미리보기: 알림 간격 시퀀스 + 주기 + 사이클당 알림 수
  • 입력값 유효성:
    • Timer 1 > 0
    • Splits ≥ 1 (정수)
    • Timer 2 ≥ 0
    • 최소 알림 간격 1초 이상 (미달 시 경고)

4.3 실행 뷰

  • 카운트다운 (큰 글씨): 다음 알림까지 남은 시간 mm:ss.s
  • 진행률 바: 현재 단계의 경과 비율
  • 사이클 카운트: N회차 진행 중
  • 단계 표시: 단계 k/(splits+1) (또는 "Timer 1 (k/splits)" / "Timer 2")
  • 알림 순간: 카운트다운이 0에 도달하면 피드백 출력 후 다음 단계 시작

4.4 제어 버튼

버튼 상태별 표시
▶ 시작 / ⏸ 일시정지 idle: "시작" / running: "일시정지" / paused: "재개"
⟲ 리셋 항상 활성 (idle에서는 비활성)
■ 정지 idle에서는 비활성

4.5 알림 수단

수단 기본값 동작
소리 ON 공통 사운드 시스템(Shared-Audio)의 mp3 파일 재생. 드롭다운으로 선택, 볼륨 조절, 미리듣기
브라우저 알림 OFF Notifications API. 최초 활성화 시 권한 요청
시각 피드백 ON (항상) 알림 순간 카운트다운 영역 플래시 애니메이션
  • 브라우저 알림 거부 시: 체크박스 자동 해제, 소리만 유지 (에러 메시지 없이 degrade)

소리 선택 UI

설정 패널에 "알림 소리" 드롭다운을 둔다. shared/audio/sounds.ts의 SOUNDS 레지스트리를 목록으로 사용.

알림 소리  [기본 알림       ▼]  [▶ 미리듣기]
볼륨       [━━━━━━──] 70%
  • 선택값(soundId)은 tools:timer:last-config:v1에 저장
  • 저장된 soundId가 레지스트리에 없으면 DEFAULT_ALERT_SOUND_ID로 폴백

4.6 프리셋

항목 내용
저장 "현재 설정 저장" → 이름 입력 모달 → LocalStorage 저장
불러오기 목록에서 클릭 → idle 상태일 때만 입력값 채움
삭제 프리셋 항목 hover 시 ✕ 버튼 노출
제한 최대 10개. 초과 시 가장 오래된 것 자동 삭제

5. 데이터 저장 (LocalStorage)

5.1 키 정의

키 설명
tools:timer:presets:v1 사용자 저장 프리셋 목록
tools:timer:last-config:v1 마지막으로 사용한 설정·알림 옵션

5.2 스키마

// tools:timer:presets:v1
type TimerPresets = TimerPreset[];

interface TimerPreset {
  id: string;           // uuid
  name: string;         // 사용자 입력 이름
  time1: number;        // seconds
  splits: number;       // integer
  time2: number;        // seconds
  createdAt: string;    // ISO8601
}

// tools:timer:last-config:v1
interface LastConfig {
  time1: number;
  splits: number;
  time2: number;
  soundEnabled: boolean;
  soundId: string;              // shared/audio SOUNDS 레지스트리의 id
  soundVolume: number;          // 0.0 ~ 1.0
  notificationEnabled: boolean;
}

5.3 복원 정책

  • 화면 진입 시 last-config를 읽어 설정 패널에 주입
  • 실행 상태(running/paused)는 복원하지 않음 (의도적. 페이지 이탈 시 정지)

6. 기술 구현 노트

6.1 시간 정확도

  • setInterval은 드리프트 발생 → 사용 금지
  • 시작 시각(performance.now())을 기준으로 목표 시각 비교 방식 사용
  • requestAnimationFrame 루프에서 매 프레임 now - startAt 계산
  • 알림은 목표 시각을 지난 첫 프레임에 발생시키고, 다음 목표 시각으로 갱신

6.2 백그라운드 탭

  • requestAnimationFrame은 백그라운드 탭에서 정지 → 복귀 시 경과 시간 계산 보정
  • 대안: 보정 로직으로 누락된 알림을 복귀 시 한꺼번에 fire (구현 단순성 우선)
  • Web Worker 기반 정확 타이머는 v2 검토 항목

6.3 오디오

  • 공통 사운드 시스템(Shared-Audio) 사용 — shared/audio/useSound 훅
  • mp3 파일 재생 (HTMLAudioElement 기반)
  • 첫 사용자 인터랙션(시작 버튼 클릭) 이후 재생 가능 (브라우저 자동재생 정책)
  • 연속 재생 시 currentTime = 0으로 리셋 후 play
  • 미리듣기 버튼은 사용자 클릭 이벤트이므로 언제든 재생 가능

6.4 알림 시퀀스 생성 함수

function buildIntervals(time1: number, splits: number, time2: number): number[] {
  const unit = time1 / splits;
  const first = Array.from({ length: splits }, () => unit);
  return time2 > 0 ? [...first, time2] : first;
}

7. 에지 케이스

케이스 처리
splits = 1 중간 알림 없이 time1 종료 시 1회 알림
time2 = 0 Timer 2 구간 생략, time1만 반복
너무 짧은 간격 (<1s) 설정 저장 시 경고 표시. 그래도 진행은 허용
브라우저 알림 권한 거부 체크박스 해제, 소리 피드백만
탭 백그라운드 복귀 경과 시간 재계산, 누락 알림 1회로 합쳐 fire
페이지 이탈·새로고침 실행 상태 파기. 설정만 복원
LocalStorage 가득참 가장 오래된 프리셋부터 삭제

8. 접근성

  • 키보드: Space = 시작/일시정지, R = 리셋 (옵션)
  • 스크린 리더: 알림마다 aria-live="assertive" 영역에 "3회차 단계 2 알림" 같은 메시지
  • 카운트다운 숫자는 충분히 큰 폰트·고대비
  • 버튼은 아이콘 + 텍스트 병기

9. 디자인 시스템 적용

UI-Design의 공통 디자인 시스템을 따른다.

  • 주 색상: #8b00ff
  • 폰트: Pretendard
  • 컴포넌트: shadcn/ui (Button, Input, Card, Switch, Slider)
  • 다크모드 지원 필수

10. 향후 확장 (v2+)

현재 범위에서 제외하지만 기록:

  • 알림 소리 종류 선택 (여러 톤)
  • 음성 카운트 ("3초 전!" 등)
  • 실행 이력 로그 (몇 사이클 돌았는지 누적)
  • BE 동기화 (기기 간 프리셋 공유)
  • 3개 이상의 Timer 단계 지원

Clone this wiki locally