본문으로 건너뛰기

AchTimer

AchTimer는 async/await 기반의 타이머 유틸리티입니다. 단순 대기부터 실시간 진행 추적까지 두 가지 사용 방식을 제공합니다.

단순 대기​

완료만 기다리면 될 때는 Wait 또는 WaitRealtime을 사용하세요.

// 게임 시간 기준 3초 대기
await AchTimer.Wait(3f);

// 실제 시간 기준 3초 대기 (Time.timeScale 영향 없음)
await AchTimer.WaitRealtime(3f);
메서드설명
Wait(seconds)게임 시간(Time.deltaTime) 기준으로 대기
WaitRealtime(seconds)실제 시간(Time.unscaledDeltaTime) 기준으로 대기. 슬로우모션·일시정지에도 영향 없음

진행 추적 (AchTimerHandle)​

진행률 표시, 남은 시간 조회, 수동 취소가 필요하면 AchTimer.Start()를 사용하세요. 반환된 AchTimerHandle을 직접 await할 수 있습니다.

var timer = AchTimer.Start(5f);
await timer;

AchTimerHandle 프로퍼티​

프로퍼티타입설명
Durationfloat타이머 총 지속 시간(초)
Elapsedfloat현재까지 경과한 시간(초)
Remainingfloat남은 시간(초). 0 미만이 되지 않음
Progressfloat완료 비율 (0 = 시작, 1 = 완료)
IsDonebool완료 또는 취소 여부
IsCancelledbool취소 여부
TaskTask완료를 나타내는 Task 객체

await handle vs await handle.Task​

두 형태는 동일하게 동작합니다. 취소 시 TaskCanceledException이 발생합니다.

// 두 방법 모두 동일
await timer;
await timer.Task;

Task를 직접 참조하면 다른 곳에서 완료를 처리하거나 Task.WhenAny 등에 활용할 수 있습니다.

var timer = AchTimer.Start(5f);

// 진행률은 다른 Update 로직에서 참조하고
// 완료는 별도로 처리
_ = timer.Task.ContinueWith(_ => Debug.Log("완료"));

Cancel()​

Cancel()을 호출하면 타이머가 즉시 중단되고 IsCancelled가 true가 됩니다. 이미 완료된 핸들에는 아무 효과가 없습니다.

var timer = AchTimer.Start(10f);

// 조건 충족 시 수동 취소
if (playerDied)
    timer.Cancel();

useUnscaledTime 파라미터​

AchTimer.Start()의 useUnscaledTime을 true로 설정하면 Time.timeScale에 관계없이 실제 경과 시간을 기준으로 동작합니다.

// 슬로우모션 중에도 정상 속도로 진행
var timer = AchTimer.Start(3f, useUnscaledTime: true);

CancellationToken 지원​

외부 CancellationToken을 전달하면 토큰이 취소될 때 타이머도 함께 취소됩니다.

var cts = new CancellationTokenSource();

// 10초 대기 — cts.Cancel() 호출 시 즉시 중단
await AchTimer.Wait(10f, cts.Token);

// Start()에도 동일하게 사용 가능
var timer = AchTimer.Start(10f, cancellationToken: cts.Token);

UIAchTimer 컴포넌트​

UIAchTimer는 AchTimerHandle의 진행 상황을 Text와 Slider에 실시간으로 표시하는 MonoBehaviour입니다.

Inspector 필드

필드설명
Time Text시간 값을 표시할 Text 컴포넌트 (선택)
Progress Slider진행률(0~1)을 표시할 Slider 컴포넌트 (선택)
Show Remainingtrue면 남은 시간, false면 경과 시간을 표시
Format시간 표시 포맷 문자열. {0}이 시간 값으로 대체됨 (기본값: {0:F1})

스크립트에서 연결

var timer = AchTimer.Start(5f);
GetComponent<UIAchTimer>().Bind(timer);
await timer;

타이머가 완료되면 컴포넌트가 자동으로 Unbind()를 호출합니다. 수동으로 해제하려면 Unbind()를 직접 호출하세요.

전체 사용 예시​

// 단순 대기
await AchTimer.Wait(3f);

// 진행 상황 추적
var timer = AchTimer.Start(5f);
timerDisplay.Bind(timer);
await timer;

// CancellationToken으로 취소
var cts = new CancellationTokenSource();
await AchTimer.Wait(10f, cts.Token);
// 스킬 시전 중 이동하면 취소되는 예시
var cts = new CancellationTokenSource();
var castTimer = AchTimer.Start(2f, cancellationToken: cts.Token);
castBar.Bind(castTimer);

try
{
    await castTimer;
    // 시전 완료
    FireSkill();
}
catch (TaskCanceledException)
{
    // 이동으로 취소됨
    ShowCancelMessage();
}

관련 문서​

최종 수정: 에