Repository navigation
Tools Timer
wcorn edited this page Apr 5, 2026
·
4 revisions
메이플스토리 재획/버프 재사용을 돕는 2단계 주기 알림 타이머. Tools 모듈 내 첫 도구.
- 상위 모듈: Tools-Module
- 경로:
/tools/timer
메이플스토리 사냥 중 재물획득의 비약·재획서 등 시간제 버프를 주기적으로 재사용해야 한다. 두 종류의 쿨타임이 연속으로 순환하는 경우가 많다.
- 사용자가 타이머 화면에 진입한다.
- Timer 1, Splits, Timer 2를 입력한다 (예: 105, 2, 15).
- 시작 버튼을 누르면 알림 시퀀스가 순환한다.
- 매 알림마다 소리·시각 피드백으로 재사용 타이밍을 알려준다.
- 필요 시 일시정지·리셋·정지로 제어한다.
- 자주 쓰는 설정은 프리셋으로 저장해 재사용한다.
- 화면을 계속 보지 않아도 소리로 알림을 받는다.
- 여러 중간 알림으로 버프 끝나기 전 미리 준비할 수 있다.
| 필드 | 타입 | 범위 | 기본값 | 설명 |
|---|---|---|---|---|
time1 |
number (seconds) | > 0 | 105 | 첫 번째 시간 |
splits |
integer | ≥ 1 | 2 | time1 등분 개수 |
time2 |
number (seconds) | ≥ 0 | 15 | 두 번째 시간 |
- 입력 단위는 초. 소수점 1자리까지 허용.
-
time2 = 0이면 Timer 2 구간 생략.
intervals = [time1/splits] × splits + [time2] (time2 > 0)
intervals = [time1/splits] × splits (time2 = 0)
- 사이클당 알림 개수:
splits + 1(time2=0이면splits) - 주기:
time1 + time2
| 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 |
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, ...
┌─── 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
|
┌──────────────────────────────────────────┐
│ ← 뒤로 | 메이플 재획 타이머 | 테마 ⏻ │ 헤더
├──────────────────────────────────────────┤
│ ┌─ 설정 패널 ──────────────────────┐ │
│ │ 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) [불러오기]│
└──────────────────────────────────────────┘
- idle 상태에서만 편집 가능 (running/paused는 비활성화)
- 숫자 입력 필드 3개 (Timer 1, Splits, Timer 2)
- 실시간 미리보기: 알림 간격 시퀀스 + 주기 + 사이클당 알림 수
- 입력값 유효성:
- Timer 1 > 0
- Splits ≥ 1 (정수)
- Timer 2 ≥ 0
- 최소 알림 간격 1초 이상 (미달 시 경고)
-
카운트다운 (큰 글씨): 다음 알림까지 남은 시간
mm:ss.s - 진행률 바: 현재 단계의 경과 비율
-
사이클 카운트:
N회차 진행 중 -
단계 표시:
단계 k/(splits+1)(또는 "Timer 1 (k/splits)" / "Timer 2") - 알림 순간: 카운트다운이 0에 도달하면 피드백 출력 후 다음 단계 시작
| 버튼 | 상태별 표시 |
|---|---|
| ▶ 시작 / ⏸ 일시정지 | idle: "시작" / running: "일시정지" / paused: "재개" |
| ⟲ 리셋 | 항상 활성 (idle에서는 비활성) |
| ■ 정지 | idle에서는 비활성 |
| 수단 | 기본값 | 동작 |
|---|---|---|
| 소리 | ON | 공통 사운드 시스템(Shared-Audio)의 mp3 파일 재생. 드롭다운으로 선택, 볼륨 조절, 미리듣기 |
| 브라우저 알림 | OFF | Notifications API. 최초 활성화 시 권한 요청 |
| 시각 피드백 | ON (항상) | 알림 순간 카운트다운 영역 플래시 애니메이션 |
- 브라우저 알림 거부 시: 체크박스 자동 해제, 소리만 유지 (에러 메시지 없이 degrade)
설정 패널에 "알림 소리" 드롭다운을 둔다. shared/audio/sounds.ts의 SOUNDS 레지스트리를 목록으로 사용.
알림 소리 [기본 알림 ▼] [▶ 미리듣기]
볼륨 [━━━━━━──] 70%
- 선택값(
soundId)은tools:timer:last-config:v1에 저장 - 저장된
soundId가 레지스트리에 없으면DEFAULT_ALERT_SOUND_ID로 폴백
| 항목 | 내용 |
|---|---|
| 저장 | "현재 설정 저장" → 이름 입력 모달 → LocalStorage 저장 |
| 불러오기 | 목록에서 클릭 → idle 상태일 때만 입력값 채움 |
| 삭제 | 프리셋 항목 hover 시 ✕ 버튼 노출 |
| 제한 | 최대 10개. 초과 시 가장 오래된 것 자동 삭제 |
| 키 | 설명 |
|---|---|
tools:timer:presets:v1 |
사용자 저장 프리셋 목록 |
tools:timer:last-config:v1 |
마지막으로 사용한 설정·알림 옵션 |
// 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;
}- 화면 진입 시
last-config를 읽어 설정 패널에 주입 - 실행 상태(running/paused)는 복원하지 않음 (의도적. 페이지 이탈 시 정지)
-
setInterval은 드리프트 발생 → 사용 금지 - 시작 시각(
performance.now())을 기준으로 목표 시각 비교 방식 사용 -
requestAnimationFrame루프에서 매 프레임now - startAt계산 - 알림은 목표 시각을 지난 첫 프레임에 발생시키고, 다음 목표 시각으로 갱신
-
requestAnimationFrame은 백그라운드 탭에서 정지 → 복귀 시 경과 시간 계산 보정 - 대안: 보정 로직으로 누락된 알림을 복귀 시 한꺼번에 fire (구현 단순성 우선)
- Web Worker 기반 정확 타이머는 v2 검토 항목
- 공통 사운드 시스템(Shared-Audio) 사용 —
shared/audio/useSound훅 - mp3 파일 재생 (
HTMLAudioElement기반) - 첫 사용자 인터랙션(시작 버튼 클릭) 이후 재생 가능 (브라우저 자동재생 정책)
- 연속 재생 시
currentTime = 0으로 리셋 후 play - 미리듣기 버튼은 사용자 클릭 이벤트이므로 언제든 재생 가능
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;
}| 케이스 | 처리 |
|---|---|
splits = 1 |
중간 알림 없이 time1 종료 시 1회 알림 |
time2 = 0 |
Timer 2 구간 생략, time1만 반복 |
| 너무 짧은 간격 (<1s) | 설정 저장 시 경고 표시. 그래도 진행은 허용 |
| 브라우저 알림 권한 거부 | 체크박스 해제, 소리 피드백만 |
| 탭 백그라운드 복귀 | 경과 시간 재계산, 누락 알림 1회로 합쳐 fire |
| 페이지 이탈·새로고침 | 실행 상태 파기. 설정만 복원 |
| LocalStorage 가득참 | 가장 오래된 프리셋부터 삭제 |
- 키보드:
Space= 시작/일시정지,R= 리셋 (옵션) - 스크린 리더: 알림마다
aria-live="assertive"영역에 "3회차 단계 2 알림" 같은 메시지 - 카운트다운 숫자는 충분히 큰 폰트·고대비
- 버튼은 아이콘 + 텍스트 병기
디자인 시스템의 공통 토큰·컴포넌트를 따른다.
- 색상·타이포그래피: 토큰으로만 지정 (하드코딩 금지)
- 브랜드 컬러:
--brand(OKLCH 297.5° 보라) - 컴포넌트: shadcn/ui (
Button,Input,Card,Switch,Slider) - 다크모드 지원 필수
메이플 재획 시나리오는 화면을 보지 않고 소리 알림에 의존하는 대표 유스케이스다. 따라서 백그라운드 동작 보장이 중요하다.
| 상황 | 동작 |
|---|---|
| 같은 탭 활성화 중 |
requestAnimationFrame 정확 동작 |
| 다른 탭으로 전환 |
requestAnimationFrame 일시정지. 복귀 시 경과 시간 보정 |
| 브라우저 최소화 | 위와 동일 |
| 폰 화면 꺼짐 | 동작 보장 안 됨 (Web Audio/HTMLAudio 정지) |
wcorn/orino#177 FE: PWA 구성이 구현되면 다음을 재검토:
- 서비스 워커 기반 정확 타이머: 탭 비활성/화면 꺼짐 상태에서도 시간 측정 유지
- Web Push API: 알림 시점에 OS 수준 푸시 알림 발송 (폰 화면 꺼져도 수신)
- Wake Lock API: 타이머 실행 중 화면 꺼짐 방지 옵션 (사용자 토글)
- Periodic Background Sync: 실험적 API, 긴 타이머용 (브라우저 지원 제한)
PWA 기본 구성(#177) 완료 후, 타이머 실제 사용 중 백그라운드 동작 한계를 체감하면 별도 Issue로 확장 기획.
현재 범위에서 제외하지만 기록:
- 알림 소리 종류 선택 (여러 톤) — 방식 B 도입 시 해결
- 음성 카운트 ("3초 전!" 등)
- 실행 이력 로그 (몇 사이클 돌았는지 누적)
- BE 동기화 (기기 간 프리셋 공유)
- 3개 이상의 Timer 단계 지원
- Wake Lock으로 화면 꺼짐 방지 (PWA 연계)