> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/korean/development/api-reference/classes/configservice.md).

# ConfigService

ConfigService : `Instance`

## Overview

ConfigService는 월드에 설정된 구성 값(config)을 서버 스크립트에서 읽을 수 있게 하는 서비스입니다.

GetConfigAsync()나 GetConfigForPlayerAsync()를 호출하면 그 시점의 구성 값을 담은 ConfigSnapshot이 반환되며, 값은 ConfigSnapshot의 GetValue()로 읽습니다. 이후 구성 값이 갱신되면 ConfigSnapshot의 UpdateAvailable 이벤트가 발생하고, Refresh()를 호출해야 새 값이 적용됩니다.

이 서비스는 서버 Script에서만 사용할 수 있으며, LocalScript에서 호출하면 오류가 발생합니다.

**주의사항**

* Studio에서는 실제 구성 값을 불러오지 않습니다. Studio에서 반환되는 ConfigSnapshot에는 SetTestingValue()로 지정한 테스트 값만 들어 있습니다.
* SetTestingValue()로 지정한 테스트 값은 현재 세션에서만 유지되며, 실제 저장된 구성 값을 변경하지 않습니다.

## Properties

## Methods

### ClearTestingValue

SetTestingValue()로 지정한 테스트 값을 제거합니다.

테스트 값이 제거되면 이미 반환된 ConfigSnapshot에는 원래 구성 값이 준비되어 Outdated가 true가 되고 UpdateAvailable 이벤트가 발생합니다. 실제 값은 Refresh()를 호출해야 적용됩니다. 해당 키에 지정된 테스트 값이 없으면 아무 동작도 하지 않습니다.

#### Parameters

| `Value` Key | <p>테스트 값을 제거할 구성 값의 키입니다.</p><ul><li>영문자, 숫자, <code>.</code>, <code>-</code>, <code>*</code>로 이루어진 1\~250자의 문자열이어야 하며, <code>*</code>로 시작할 수 없습니다.</li><li>규칙에 맞지 않는 키를 전달하면 오류가 발생합니다.</li></ul> |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

### GetConfigAsync

월드 공통 구성 값을 불러와 ConfigSnapshot으로 반환합니다.

이 메서드는 구성 값을 불러올 때까지 호출한 스크립트를 일시 중단(yield)합니다. 월드 세션 정보가 아직 준비되지 않았거나 구성 값 조회에 실패하면 오류가 발생하므로 pcall로 감싸 호출하는 것이 좋습니다.

반환된 ConfigSnapshot은 존재하는 동안 주기적으로 새 버전의 구성 값이 있는지 확인합니다.

#### Parameters

#### Return

| `ConfigSnapshot` | 호출 시점의 월드 공통 구성 값을 담은 ConfigSnapshot입니다. |
| ---------------- | ---------------------------------------- |

#### Code Samples

### GetConfigForPlayerAsync

지정한 플레이어를 기준으로 평가한 구성 값을 불러와 ConfigSnapshot으로 반환합니다.

GetConfigAsync()와 달리 호출할 때마다 해당 플레이어에게 적용될 구성 값을 다시 조회합니다. 이 메서드는 구성 값을 불러올 때까지 호출한 스크립트를 일시 중단(yield)하며, 조회에 실패하면 오류가 발생하므로 pcall로 감싸 호출하는 것이 좋습니다.

#### Parameters

| `Value` Player | <p>구성 값을 조회할 대상 Player입니다.</p><ul><li>현재 월드에 있는 Player가 아니거나, 유효한 계정 정보를 가진 Player가 아니면 오류가 발생합니다.</li></ul> |
| -------------- | ------------------------------------------------------------------------------------------------------------ |

#### Return

| `ConfigSnapshot` | 호출 시점에 해당 플레이어를 기준으로 평가된 구성 값을 담은 ConfigSnapshot입니다. |
| ---------------- | ---------------------------------------------------- |

#### Code Samples

### SetTestingValue

테스트용으로 특정 키의 구성 값을 지정합니다.

지정한 테스트 값은 불러온 구성 값보다 우선 적용되며, 이후 GetConfigAsync()나 GetConfigForPlayerAsync()로 반환되는 ConfigSnapshot에 바로 반영됩니다. 이미 반환된 ConfigSnapshot에는 새 값이 준비되어 Outdated가 true가 되고 UpdateAvailable 이벤트가 발생하며, 실제 값은 Refresh()를 호출해야 적용됩니다.

테스트 값은 현재 세션에서만 유지되며 실제 저장된 구성 값을 변경하지 않습니다. 기존 테스트 값과 같은 값을 지정하면 아무 동작도 하지 않습니다.

#### Parameters

| `Value` Key   | <p>테스트 값을 지정할 구성 값의 키입니다.</p><ul><li>영문자, 숫자, <code>.</code>, <code>-</code>, <code>*</code>로 이루어진 1\~250자의 문자열이어야 하며, <code>*</code>로 시작할 수 없습니다.</li><li>규칙에 맞지 않는 키를 전달하면 오류가 발생합니다.</li></ul>                                                                                                                                                                                                                                                   |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Value` Value | <p>지정할 테스트 값입니다.</p><ul><li>string, boolean, number 또는 table을 전달할 수 있습니다. table은 문자열 키를 가진 테이블이어야 하며, 배열은 테이블 내부에서만 사용할 수 있습니다.</li><li>nil, 함수, Instance 등 지원하지 않는 타입의 값을 전달하면 오류가 발생합니다. 테스트 값을 제거하려면 ClearTestingValue()를 사용합니다.</li><li>NaN이나 무한대, 절댓값이 2^53을 넘는 정수는 사용할 수 없습니다.</li><li>순환 참조가 있는 테이블, 문자열 키와 숫자 인덱스가 섞인 테이블, 중간이 비어 있는 배열, 유효한 UTF-8이 아닌 문자열은 사용할 수 없습니다.</li><li>JSON으로 변환한 크기가 UTF-16 기준 100,000자를 넘으면 오류가 발생합니다.</li></ul> |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

## Events
