> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/sdk7/networking/authoritative-servers.md).

# 멀티플레이어 서버

헤드리스 멀티플레이어 서버를 사용해 멀티플레이어 Decentraland 씬을 구축합니다.

**📔 참고**: 멀티플레이어 서버는 이전에 **권위 서버**(Authoritative Server)라고 불렸습니다. 이름만 변경되었으며 기능은 동일합니다. 설치할 SDK 브랜치 이름은 여전히 `auth-server`, 자세한 내용은 [설정](#setup).

## 개요

Decentraland는 플레이어의 기기에서 씬을 로컬로 실행합니다. 기본적으로 플레이어는 서로를 보고 직접 상호작용할 수 있지만, 각 플레이어는 환경과 개별적으로 상호작용합니다. 기본 설정에서는 환경의 변경 사항이 플레이어 간에 공유되지 않습니다.

모든 플레이어가 동일한 콘텐츠와 상태의 씬을 볼 수 있도록 하는 것은 플레이어들이 더욱 의미 있는 방식으로 상호작용하는 데 매우 중요합니다. 그렇지 않으면 한 플레이어가 문을 열고 집 안으로 들어가도 다른 플레이어에게는 문이 닫힌 상태로 보이며, 첫 번째 플레이어는 다른 플레이어에게 닫힌 문을 그대로 통과하는 것처럼 보입니다.

다음 **멀티플레이어 서버** 는 씬 코드를 실행하고 상태 변경을 검증한 뒤, 그 결과를 연결된 모든 플레이어에게 브로드캐스트하는 헤드리스 서버 프로세스입니다. 권위 서버 아키텍처를 따르므로, 각 클라이언트가 자신의 동작을 보고하도록 믿는 대신 서버가 단일 정보 소스 역할을 합니다. 따라서 멀티플레이어 씬을 동기화하는 데 권장되는 방식입니다.

게임 메커니즘의 공정성이 중요한 경우 멀티플레이어 서버를 사용하는 것이 이상적입니다. 서버 측에서 실행되는 정교한 부정행위 방지 검증을 구현할 수 있기 때문입니다. 또한 비밀 키와 기타 민감한 정보를 서버에 저장할 수 있어 사용자에게 직접 노출할 필요가 없습니다.

멀티플레이어 서버는 실제 문제도 해결합니다. 피어 투 피어 환경에서는 두 플레이어가 부유 플랫폼 같은 대상을 조작할 때 서로 충돌하는 결과가 생길 수 있습니다. 각 클라이언트가 플랫폼의 높이를 서로 다르게 설정해도 어느 쪽이 맞는지 결정할 권한이 없습니다. 멀티플레이어 서버는 모든 변경을 한곳에서 처리하므로, 모든 클라이언트가 동일한 상태에 수렴합니다.

또한 다음을 위한 공간도 제공합니다. **세션 간 데이터 유지**: 순위표, 플레이어 진행 상황, 잠금 해제한 업적, 문이 열린 상태나 아이템이 배치된 상태 같은 환경 변화 등이 여기에 해당합니다. 플레이어가 다시 돌아오면 이전에 일어난 일이 반영된 세계를 확인할 수 있습니다.

Decentraland가 서버를 호스팅하고 배포해 드립니다. 일반적인 절차로 씬을 게시하면 추가 단계나 호스팅 비용 없이 서버도 원활하게 게시됩니다.

## 설정

### 1. auth-server SDK 버전을 설치합니다

네이티브 멀티플레이어 서버 API(`isServer`, `registerMessages`, `Storage`, `EnvVar`, 등)는 별도의 SDK 브랜치에서 사용할 수 있습니다.

**Creator Hub에서**, 씬 설정을 열고 다음 항목을 선택하세요. **멀티플레이어 서버 사용** 에서 **고급** 의 섹션 **설정**  탭. Creator Hub가 적절한 SDK를 설치하고 다음을 설정합니다. `scene.json` 을(를) 대신 설정합니다. 자세한 내용은 [씬 설정의 멀티플레이어 서버](https://docs.decentraland.org/creator/content-creator-ko/scene-editor/configure/scene-settings.md#multiplayer-server).

**명령줄에서**, 표준 SDK 브랜치 대신 프로젝트에 설치하려면 다음 명령을 실행합니다.

```bash
npm install --save-exact @dcl/sdk@auth-server @dcl/js-runtime@auth-server
```

{% hint style="warning" %}
**📔 참고**: 다음을 유지하세요:  `--save-exact`. 이 옵션이 없으면 npm은 다음과 같은 버전 범위를 저장합니다:  `^7.x.y-...` 의 `package.json`에 저장되며, 이후 정식 SDK 릴리스도 해당 범위에 포함됩니다. 나중에 실행한  `npm install` 이 인증 서버 빌드를 서버 API가 없는 정식 빌드로 바꿀 수 있으며, 그러면 서버 코드가 더 이상 빌드되지 않습니다.
{% endhint %}

### 2. scene.json 구성

멀티플레이어 서버는 다음 플래그로 활성화됩니다. `"authoritativeMultiplayer": true` 의 `scene.json` 루트 수준에 추가합니다. 직접 추가할 필요는 없습니다. SDK의 auth-server 브랜치를 사용하면 씬을 처음 빌드하거나 미리 볼 때 자동으로 추가됩니다. 이 항목을 삭제하지 않도록 주의하세요. 이 플래그가 없으면 서버가 실행되지 않으며 `isServer()` 는 항상 *false*.

원한다면 다음 항목을 `scene.json` 의 루트 수준에 추가할 수도 있습니다.

```json
{
  "logsPermissions": ["0xYourWalletAddress"]
}
```

배포 후 다음 지갑에 서버 로그와 메트릭에 대한 액세스 권한을 부여하려면 `logsPermissions` 를 추가하세요. Creator Hub의 씬 설정에 있는 **로그 액세스 및 저장소** 목록에서 이 필드를 편집할 수 있습니다. 월드 소유자와 배포 권한이 있는 협업자도 액세스할 수 있으며, Genesis City 소유자와 씬의 기본 구획을 위임받아 관리하는 LAND 관리자도 액세스할 수 있습니다. 권한, 로그인, 명령에 대한 자세한 내용은 [씬 인사이트](https://docs.decentraland.org/creator/content-creator-ko/sdk7/debugging/scene-insights.md) 를 참조하세요.

### 3. 미리 보기 실행

표준 미리 보기 명령을 사용하면 됩니다. 별도의 단계는 필요하지 않습니다. SDK의 auth-server 브랜치를 사용하면 미리 보기 실행 시 로컬 버전의 멀티플레이어 서버가 백그라운드에서 자동으로 시작됩니다.

서버의 로컬 세션은 프로덕션 환경의 세션에 연결되지 않으므로, 게시된 씬에 접속한 플레이어에게 영향을 주지 않고 자유롭게 테스트할 수 있습니다.

## 서버/클라이언트 분기

프로젝트의 `src`  폴더에 있는 씬 코드는 서버와 클라이언트 양쪽에서 실행됩니다. 다음 `isServer()`  함수를 사용해 실행 경로를 분리하세요.

```typescript
import { isServer } from "@dcl/sdk/network"
import { initServer } from "./server/server"
import { initClient } from "./client/setup"
import { setupUi } from "./client/ui"

function main() {
  if (isServer()) {
    // 서버 전용: 게임 로직, 검증, 상태 관리
    initServer()
    return
  } else {
    // 클라이언트 전용: UI, 입력 처리, 메시지 전송
    initClient()
    setupUi()
  }
}
```

서버는 렌더링 없이 씬을 헤드리스 모드로 실행합니다. 서버는 `PlayerIdentityData` 를 통해 모든 플레이어의 위치, 웨어러블 및 기타 데이터에 검증된 방식으로 액세스하며, 게임 상태에 대한 유일한 권한을 가집니다.

## 동기화 컴포넌트 및 검증

### 모든 클라이언트에 엔티티 동기화

다음 `syncEntity` 를 사용하면 해당 엔티티의 지정된 컴포넌트에 대한 변경 사항을 브로드캐스트할 수 있습니다.

```typescript
import { isServer, syncEntity } from "@dcl/sdk/network"

if (isServer()) {
  syncEntity(
    entity,
    [Transform.componentId, GameState.componentId],
    /* enumId */ 1
  )
}
```

다음에서 사용하는 것과 구문이 동일합니다. [서버리스 멀티플레이어](https://docs.decentraland.org/creator/content-creator-ko/sdk7/networking/serverless-multiplayer.md) 기능이므로, 이 아키텍처를 사용하는 씬을 멀티플레이어 서버를 사용하도록 손쉽게 업그레이드할 수 있습니다. 씬에서 멀티플레이어 서버를 사용하면 더 이상 모든 플레이어 간에 상태 업데이트를 전송하지 않습니다. 대신 모든 상태 업데이트가 서버를 통해 라우팅되고 검증됩니다.

{% hint style="warning" %}
**📔 참고**: 멀티플레이어 서버에서는 서버만 `syncEntity`를 호출하는 것이 이상적인 패턴입니다. 이렇게 하면 엔터티 ID의 일관성을 걱정할 필요가 없습니다. 대신 서버가 엔터티를 인스턴스화하고 공유하면 모든 클라이언트가 해당 인스턴스에 대한 동기화 정보를 받습니다. 항상 `isServer()`로 호출을 보호하세요. 이는 다음과 다릅니다. [서버리스 멀티플레이어](https://docs.decentraland.org/creator/content-creator-ko/sdk7/networking/serverless-multiplayer.md), 각 클라이언트가 자체적으로 `syncEntity` 를 호출합니다.
{% endhint %}

### 변경 사항 검증

사용하세요. `validateBeforeChange()` 를 사용하면 엔터티의 특정 구성 요소에서 상태 업데이트를 제한할 수 있습니다. 사용자 지정 검증 함수를 실행할 수 있으며, 검증 조건을 충족해야 변경이 적용됩니다.

검증 결과가 *true*이면 변경이 승인되어 모든 플레이어에게 전파됩니다. 검증 결과가 *false*, 그러면 변경 사항이 거부됩니다. 거부된 변경 사항은 다른 플레이어에게 전달되지 않으며, 변경을 시도한 플레이어의 상태도 되돌려집니다.

#### 값 검증

가장 간단한 경우는 새 *값* 이 특정 매개변수 범위 내에 있는지 검증하는 것입니다. 예를 들어, 새 Y 좌표가 0보다 큰 경우에만 `Transform` 에 대한 변경을 허용합니다:

```typescript
import { engine, Transform } from "@dcl/sdk/ecs"
import { Vector3 } from "@dcl/sdk/math"
import { isServer } from "@dcl/sdk/network"

const entity = engine.addEntity()
Transform.create(entity, { position: Vector3.create(10, 2, 10) })

if (isServer()) {
  Transform.validateBeforeChange(entity, (value) => {
    // Y = 0 이하에 엔티티를 배치하는 업데이트는 모두 거부합니다
    return value.newValue.position.y > 0
  })
}
```

validateBeforeChange()는 `validateBeforeChange()` 서버에서만 의미가 있으므로 항상 `isServer()`로 감싸야 합니다. 클라이언트에서는 이 호출이 아무런 효과도 없습니다.

게임 로직에 어긋나는 변경을 방지하는 안티 치트 메커니즘으로 사용할 수 있습니다.

#### 플레이어와의 거리 검증

다음을 함께 사용할 수 있습니다. `validateBeforeChange()` 서버에서 검증된 플레이어 위치를 사용하면 플레이어가 오브젝트와 상호작용하도록 허용하기 전에 충분히 가까이 있는지 확인할 수 있습니다. 예를 들어 플레이어가 오브젝트의 `Transform`을 변경해 오브젝트를 줍으려 할 때, 오브젝트가 플레이어로부터 5미터 이상 떨어져 있으면 변경을 거부할 수 있습니다.

```typescript
import { engine, Transform, PlayerIdentityData } from "@dcl/sdk/ecs"
import { Vector3 } from "@dcl/sdk/math"
import { isServer } from "@dcl/sdk/network"

const pickableEntity = engine.addEntity()
Transform.create(pickableEntity, { position: Vector3.create(8, 1, 8) })

if (isServer()) {
  Transform.validateBeforeChange(pickableEntity, (value) => {
    // 이 변경을 보낸 플레이어 찾기
    for (const [playerEntity, identity] of engine.getEntitiesWith(
      PlayerIdentityData
    )) {
      if (identity.address.toLowerCase() !== value.senderAddress.toLowerCase())
        continue

      const playerTransform = Transform.getOrNull(playerEntity)
      if (!playerTransform) return false

      // 변경 전 객체의 현재 위치 가져오기
      const objectTransform = Transform.getOrNull(pickableEntity)
      if (!objectTransform) return false

      const distance = Vector3.distance(
        playerTransform.position,
        objectTransform.position
      )

      // 플레이어가 5미터 이내에 있을 때만 변경 허용
      return distance <= 5
    }

    // 연결된 플레이어 중 보낸 사람을 찾지 못함 — 거부
    return false
  })
}
```

이 패턴은 치트 방지 메커니즘으로 유용합니다. 플레이어가 씬을 가로질러 손이 닿지 않아야 하는 물체를 잡지 못하게 합니다.

#### 관리자만 변경 허용

변경을 보내는 *사용자가 누구인지* 를 기준으로도 유효성을 검사할 수 있습니다. 수신되는 모든 값에는 보낸 사람의 지갑 주소가 담긴 `senderAddress` 필드가 포함됩니다. 이 필드를 사용해 특정 플레이어의 변경만 허용할 수 있습니다. 예를 들어 씬 관리자만 `VideoPlayer` 컴포넌트를 수정하도록 허용할 수 있습니다:

```typescript
import { engine, VideoPlayer } from "@dcl/sdk/ecs"
import { isServer } from "@dcl/sdk/network"
import { isPreview } from "@dcl/asset-packs/dist/admin-toolkit-ui/fetch-utils"
import { getSceneAdmins } from "@dcl/asset-packs/dist/admin-toolkit-ui/ModerationControl/api"

// 씬 관리자 목록에서 갱신하는 관리자 지갑 주소 캐시
let adminAddresses = new Set<string>()

async function updateAdminAddresses() {
  if (isPreview()) return
  try {
    const [error, response] = await getSceneAdmins()
    if (error) {
      console.error("[SERVER] Error fetching admin list:", error)
      adminAddresses = new Set()
      return
    }
    adminAddresses = new Set(
      (response ?? []).map((admin) => admin.admin.toLowerCase())
    )
    console.log(
      "[SERVER] Updated admin addresses cache:",
      Array.from(adminAddresses)
    )
  } catch (error) {
    console.error("[SERVER] Error updating admin addresses:", error)
    adminAddresses = new Set()
  }
}

export async function main() {
  const videoEntity = engine.addEntity()
  VideoPlayer.create(videoEntity, { src: "videos/intro.mp4" })

  if (isServer()) {
    // 유효성 검사를 설정하기 전에 캐시 채우기
    await updateAdminAddresses()

    VideoPlayer.validateBeforeChange(videoEntity, (value) => {
      // 미리보기 실행 중에는 항상 변경을 허용해 로컬 테스트를 더 쉽게 할 수 있도록 합니다
      if (isPreview()) return true

      const senderAddress = value.senderAddress.toLowerCase()
      if (!adminAddresses.has(senderAddress)) {
        console.log(
          "[SERVER] Unauthorized VideoPlayer change blocked from:",
          senderAddress
        )
        return false
      }
      return true
    })
  }
}
```

참조 [Scene Admin](https://docs.decentraland.org/creator/content-creator-ko/scene-editor/operate-live/scene-admin.md) 를 통해 플레이어가 씬의 관리자가 되는 방식에 대한 자세한 내용을 확인하세요.

#### 결과가 아닌 의도를 보내세요

점수, 상품 또는 공유 리소스가 걸려 있을 때는 클라이언트 메시지를 플레이어가 무엇을 **하려는지**를 기준으로 설계하고 결과를 기준으로 설계하지 마세요. 클라이언트는 `claimPoint` 또는 `harvest`를 보냅니다. "내 점수는 이제 40이다"라고 보내지는 않습니다.

그러면 서버가 메시지를 검증합니다. 누가 보냈는지, 게임이 해당 동작을 허용하는 단계인지, 플레이어가 충분히 가까운지, 획득할 것이 남아 있는지 확인합니다. 그 후에야 새 값을 계산해 기록합니다. 게임 상태를 기록하는 주체는 서버뿐입니다.

자신의 점수를 지정할 수 있는 클라이언트는 어떤 점수든 지정할 수 있습니다.

#### 서버만 변경할 수 있도록 허용하기

가장 엄격한 방법은 서버 자체에서 비롯된 쓰기만 허용하고 클라이언트에서 오는 변경은 모두 거부하는 것입니다. 점수, 게임 단계, 생성된 엔티티 등 완전히 권위 있는 상태에 주로 사용하는 패턴입니다.

수신되는 모든 값에는 `senderAddress` 필드가 포함됩니다. 발신자가 서버이면 이 필드의 값은 상수 `AUTH_SERVER_PEER_ID`와 일치합니다. 이 상수는 `@dcl/sdk/network/message-bus-sync`.

아래 예시에서는 이 검사를 특정 엔티티의 하나 이상의 컴포넌트에 적용하는 간단한 `protectServerEntity()` 헬퍼를 정의합니다. 한 번의 호출로 여러 컴포넌트(예: `Transform` 및 `GltfContainer`)를 보호할 수 있어 편리합니다.

```typescript
import { engine, Entity, Transform, GltfContainer } from "@dcl/sdk/ecs"
import { Vector3 } from "@dcl/sdk/math"
import { isServer } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"

type ComponentWithValidation = {
  validateBeforeChange: (
    entity: Entity,
    cb: (value: { senderAddress: string }) => boolean
  ) => void
}

function protectServerEntity(
  entity: Entity,
  components: ComponentWithValidation[]
) {
  for (const component of components) {
    component.validateBeforeChange(entity, (value) => {
      return value.senderAddress === AUTH_SERVER_PEER_ID
    })
  }
}

if (isServer()) {
  // 서버에서 관리하는 엔티티를 생성한 후:
  const entity = engine.addEntity()
  Transform.create(entity, { position: Vector3.create(10, 5, 10) })
  GltfContainer.create(entity, { src: "assets/model.glb" })
  protectServerEntity(entity, [Transform, GltfContainer])
}
```

{% hint style="warning" %}
**📔 참고**: 항상 `protectServerEntity()` 를 `isServer()` 블록 안에서 호출하세요. 이 함수는 `validateBeforeChange()`를 감싸는 함수로, 서버에서만 의미가 있습니다. 클라이언트에서 호출하면 오류가 발생합니다.
{% endhint %}

#### 사용자 지정 컴포넌트

씬에서 정의한 사용자 지정 컴포넌트에도 `validateBeforeChange()` 를 적용할 수 있습니다.

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"
import { isServer } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"

export const GameState = engine.defineComponent("game:State", {
  phase: Schemas.String,
  score: Schemas.Int,
  timeRemaining: Schemas.Int,
})

// 이 컴포넌트는 서버만 수정할 수 있습니다
if (isServer()) {
  GameState.validateBeforeChange((value) => {
    return value.senderAddress === AUTH_SERVER_PEER_ID
  })
}
```

## 메시지

동기화된 컴포넌트는 위치, 점수, 게임 단계처럼 모든 플레이어가 계속 확인해야 하는 상태에 적합합니다. 하지만 모든 상황이 이 방식에 들어맞는 것은 아닙니다. 플레이어가 서버에 "이 버튼을 클릭했어요" 또는 "게임에 참가하고 싶어요"라고 알리고, 서버가 "라운드가 시작됐어요" 또는 "여기 플레이어의 통계가 있어요"와 같은 일회성 응답을 보내야 할 때도 있습니다. 이는 지속적인 상태가 아니라 이벤트입니다.

이럴 때 메시지를 사용합니다. 클라이언트와 서버 간에 타입이 지정되고 스키마 검증을 거치는 통신에는 `registerMessages()` 를 사용하세요. 메시지는 전송 후 별도의 처리를 기다리지 않는 방식입니다. 클라이언트가 서버에 메시지를 보내면 서버가 이를 처리하고 필요에 따라 응답을 보냅니다. 메시지 자체가 지속 상태를 만들지는 않습니다.

### 메시지 정의

서버와 클라이언트가 모두 가져오는 공유 파일에 모든 메시지를 정의하세요. 이렇게 하면 양쪽에서 사용할 수 있는 메시지와 메시지에 포함된 데이터가 항상 일치합니다. 각 메시지는 페이로드를 설명하는 `Schemas.Map` 입니다.

```typescript
import { Schemas } from "@dcl/sdk/ecs"
import { registerMessages } from "@dcl/sdk/network"

export const Messages = {
  // 클라이언트 → 서버
  playerReady: Schemas.Map({ displayName: Schemas.String }),
  playerAction: Schemas.Map({ action: Schemas.String, targetId: Schemas.Int }),
  giveCoins: Schemas.Map({ to: Schemas.String, amount: Schemas.Int }),

  // 서버 → 클라이언트
  gameStarted: Schemas.Map({ roundNumber: Schemas.Int }),
  gameEnded: Schemas.Map({ winnerId: Schemas.String }),
}

export const room = registerMessages(Messages)
```

{% hint style="warning" %}
**📔 참고**: `registerMessages()` 는 위 예시처럼 공유 모듈의 최상위 수준에서 한 번 호출하세요. 그러면 서버와 클라이언트 모두 모듈이 처음 로드될 때 실행됩니다. 조건문 안이나 함수 내부에서는 호출하지 마세요. 양쪽에서 항상 동일한 메시지를 등록해야 합니다.
{% endhint %}

### 메시지 전송

클라이언트는 서버에만 메시지를 보낼 수 있습니다. 클라이언트끼리 직접 메시지를 주고받는 기능은 없습니다. 서버는 모든 클라이언트에 메시지를 브로드캐스트하거나 주소를 지정해 특정 플레이어에게 보낼 수 있습니다.

```typescript
import { room } from "./shared/messages"

// 클라이언트 → 서버(브로드캐스트, 서버에서 수신)
room.send("playerReady", { displayName: "Alice" })

// 서버 → 모든 클라이언트
room.send("gameStarted", { roundNumber: 1 })

// 서버 → 특정 클라이언트(지갑 주소 기준)
room.send("gameEnded", { winnerId: "Alice" }, { to: [playerAddress] })
```

{% hint style="warning" %}
**📔 참고**: 메시지의 최대 크기는 약 13KB입니다. 더 큰 메시지는 오류 없이 전송 계층에서 조용히 삭제됩니다. 페이로드를 작게 유지하세요. 더 큰 데이터를 공유해야 한다면 여러 메시지로 나누거나 동기화된 컴포넌트를 사용하세요.
{% endhint %}

### 메시지 수신

```typescript
import { room } from "./shared/messages"

// 클라이언트에서 서버로부터 수신
room.onMessage("gameStarted", (data) => {
  console.log(`Round ${data.roundNumber} started!`)
})

// 서버에서 클라이언트로부터 수신
room.onMessage("playerReady", (data, context) => {
  if (!context) return
  const senderAddress = context.from // 확인된 지갑 주소
  console.log(`[Server] ${data.displayName} is ready (${senderAddress})`)
})
```

서버에서 수신하는 각 메시지에는 발신자의 확인된 지갑 주소가 담긴 `context` 객체가 포함됩니다. 이를 사용해 어떤 플레이어가 메시지를 보냈는지 확인하세요(페이로드에 포함된 자체 보고 신원 정보에 의존하지 마세요).

`context.from` 은 네트워크에서 보고한 그대로 대소문자 변경 없이 전달됩니다. 한 번 소문자로 변환한 뒤(`context.from.toLowerCase()`), 모든 맵, 세트 및 Storage 호출에서 해당 값을 사용하세요. 그래야 한 플레이어의 데이터가 두 개의 키로 나뉘어 저장되지 않습니다.

### 전송 전에 상태 동기화 기다리기

참가 시 발생할 수 있는 경쟁 상태를 방지하려면 클라이언트는 첫 메시지를 보내기 전에 씬 상태가 동기화될 때까지 기다려야 합니다.

```typescript
import { engine } from "@dcl/sdk/ecs"
import { isStateSyncronized } from "@dcl/sdk/network"
import { room } from "./shared/messages"

engine.addSystem(() => {
  if (!isStateSyncronized()) return

  // 이제 안전하게 메시지를 보낼 수 있습니다
  room.send("playerReady", { displayName: "Alice" })
})
```

{% hint style="info" %}
**💡 팁**: `isStateSyncronized()` 는 클라이언트의 상태가 동기화되었는지만 알려 주며, 서버의 초기화가 완료되었음을 보장하지는 않습니다. 더 확실하게 준비 상태를 확인하려면 서버가 "ready" 메시지나 하트비트를 브로드캐스트하도록 하고, 클라이언트는 게임플레이 메시지를 보내기 전에 이를 기다리도록 하세요.
{% endhint %}

### 사용 가능한 스키마 유형

모든 메시지 페이로드와 사용자 지정 컴포넌트는 바이너리 직렬화에 `Schemas` 를 사용합니다. 사용 가능한 유형은 다음과 같습니다.

```typescript
import { Schemas } from "@dcl/sdk/ecs"

// 기본 유형
Schemas.String // "hello"
Schemas.Int // 42
Schemas.Float // 3.14
Schemas.Boolean // true / false
Schemas.Int64 // Date.now()

// 벡터 유형
Schemas.Vector3 // { x: 1, y: 2, z: 3 }
Schemas.Quaternion // { x, y, z, w }

// 복합 유형
Schemas.Array(Schemas.String) // ["a", "b", "c"]
Schemas.Entity // 엔티티 참조
Schemas.Optional(Schemas.String) // "hello" 또는 undefined
Schemas.Optional(Schemas.Int) // 42 또는 undefined

// 중첩 객체
Schemas.Map({
  name: Schemas.String,
  health: Schemas.Int,
  position: Schemas.Vector3,
  playerId: Schemas.Optional(Schemas.String),
})
```

{% hint style="warning" %}
**📔 참고**: 메시지는 *반드시* 다음을 사용해 정의해야 합니다 `Schemas.Map(...)`. 일반 JavaScript 객체는 보낼 수 없습니다. 이 경우 이진 직렬화에 실패합니다.
{% endhint %}

## 서버에서 플레이어 위치 읽기

서버는 **검증된** 플레이어 위치를 읽을 수 있으며, 클라이언트는 이를 위조할 수 없습니다. 이는 위치 기반 부정행위 방지의 토대입니다:

```typescript
import { engine, PlayerIdentityData, Transform } from "@dcl/sdk/ecs"

engine.addSystem(() => {
  for (const [entity, identity] of engine.getEntitiesWith(PlayerIdentityData)) {
    const transform = Transform.getOrNull(entity)
    if (!transform) continue

    const address = identity.address
    const position = transform.position
    // 이 위치는 서버에서 검증되었습니다. 클라이언트가 보고한 위치를 절대 신뢰하지 마세요.
  }
})
```

{% hint style="warning" %}
**📔 참고**: 플레이어 위치를 가져올 때는 항상 서버에서 `PlayerIdentityData` + `Transform` 를 사용하세요. 클라이언트가 직접 보고한 값은 절대 신뢰하지 마세요.
{% endhint %}

## 데이터 저장소

서버를 재시작한 후에도 데이터를 유지할 수 있습니다. 저장소는 **서버 전용**이므로 호출할 때는 항상 `isServer()`로 감싸세요. 서버는 이 데이터를 읽고 쓸 수 있습니다.

```typescript
import { Storage } from "@dcl/sdk/server"
```

데이터는 두 가지 수준으로 저장할 수 있습니다:

* **월드**: 순위표나 지속적인 환경 변경처럼 모든 플레이어와 관련된 데이터에 사용하세요.
* **플레이어**: 진행 상황이나 해당 플레이어의 환경설정 저장처럼 플레이어별 데이터에 사용하세요.

{% hint style="info" %}
**💡 팁**: 저장소 값은 JSON 형식입니다. 숫자, 문자열, 배열 또는 일반 객체를 그대로 저장하고 같은 값으로 다시 읽을 수 있습니다. JSON.stringify() `JSON.stringify()` 또는 `JSON.parse()`를 사용할 필요가 없습니다. 예외는 두 가지입니다. Date `Date` 는 ISO 텍스트(`"2026-10-27T13:05:12.000Z"`)로 저장되며, `undefined` 로 설정된 객체 속성은 제외됩니다. 이전에 저장한 값이 `JSON.stringify()` 로 저장된 경우 문자열이므로 다시 읽으면 해당 문자열로 반환됩니다.

로컬 개발 중에는 저장소가 다음 위치에 기록됩니다 `node_modules/@dcl/sdk-commands/.runtime-data/server-storage.json`.
{% endhint %}

{% hint style="warning" %}
**📔 참고**: Storage 호출이 문제를 알리는 방식:

* `Storage.set()` 와 `Storage.player.set()` 은 다음 값을 반환하도록 이행됩니다: **불리언 값**. `false` 는 값이 영구 저장되지 **않았음** 을 의미합니다. 예를 들어 네트워크 오류가 발생했거나 너무 많은 요청이 동시에 실행된 경우입니다(아래 참조). 항상 결과를 확인하세요. 무시된 `false` 는 저장 데이터가 아무런 알림 없이 유실되었음을 의미합니다.
* `set()` 은 다음과 같이 값을 JSON으로 변경 없이 저장할 수 없는 경우 `TypeError` 를 발생시킵니다: `undefined`, `NaN` 또는 `Infinity`, 함수, `Map` 또는 `Set`등이 해당합니다. 키를 삭제하려면 다음을 사용하세요: `delete()`.
* `get()` 은 저장된 값을 반환하도록 이행되며, 키가 존재하지 않는 경우에만 `null` 을 반환합니다. 읽기에 실패하면 예외를 발생시키므로 실패를 키가 없는 경우로 오인할 일이 없습니다.
* 각 `delete()` 메서드는 요청이 실패하면 예외를 발생시킵니다. 키가 존재하지 않았던 경우에만 `false` 를 반환하도록 이행됩니다.
  {% endhint %}

### 변경할 때마다 저장하지 말고 체크포인트에서 저장하기

Storage는 서버 재시작과 재배포 후에도 유지되어야 하는 데이터를 영구 저장하는 수단입니다. 실시간 데이터 저장소가 아닙니다. 현재 게임 상태는 서버 메모리에 유지하세요. 이 방식이 더 빠르며 서버에 적합합니다. Storage에는 꼭 필요한 경우에만, 의미 있는 체크포인트에서 기록하세요.

{% hint style="warning" %}
**⚠️ 경고**: 서버 런타임에서는 동시에 최대 **40개의 진행 중인 호스트 호출** 을 허용하며, 이 한도는 씬이 런타임에 요청하는 *모든 작업* 에 걸쳐 공유됩니다. 모든 스토리지 요청, `signedFetch`, 기타 런타임 API 호출이 모두 같은 한도에 포함됩니다. 한도를 초과하는 호출은 **대기열에 들어가지 않습니다**. 대신 즉시 다음 오류와 함께 거부됩니다: `too many concurrent host calls` . SDK는 이 거부를 포착하고 다음 값을 반환하도록 이행합니다: `Storage.set` promise to `false` 를 던지는 대신 반환합니다. 코드에서 이 불리언 값을 무시하면 저장 실패를 알 수 없고, 저장된 데이터가 오래된 상태로 남거나 손실됩니다. 모든 쓰기 작업의 결과를 확인하세요(위 참고 참조).
{% endhint %}

저장하기 좋은 시점:

* 게임 종료 또는 라운드 종료 시.
* 플레이어가 떠날 때.
* 주기적으로 디바운스된 저장(예: 30초마다 한 번). 매 프레임마다 저장하지 마세요.

재시작이나 재배포 후에도 유지해야 하는 데이터만 저장하세요. 그 밖의 데이터는 모두 메모리에 보관할 수 있습니다.

아래 예제에서는 점수를 획득할 때마다 저장하는 대신 체크포인트에서만 저장하고, 점수는 메모리에 보관합니다.

```typescript
import { Storage } from "@dcl/sdk/server"

// 작업 상태는 메모리에 보관하고, 이벤트가 발생할 때마다 업데이트합니다
const scores: Record<string, number> = {}

function onPointScored(address: string) {
  scores[address] = (scores[address] ?? 0) + 1
  // 여기서는 Storage를 호출하지 않고 메모리만 업데이트합니다
}

// 플레이어가 떠날 때처럼 체크포인트에서만 저장합니다
async function onPlayerLeave(address: string) {
  const saved = await Storage.player.set(address, "score", scores[address] ?? 0)
  if (!saved) {
    // 쓰기가 저장되지 않았습니다. 값을 메모리에 유지하고 나중에 다시 시도합니다
    console.error(`Failed to save score for ${address}`)
  }
}
```

동시에 많은 플레이어가 있는 씬에서는 저장되지 않은 변경 사항이 있는 키(“더티 세트”)를 추적하고, 실패한 쓰기를 다음 플러시 때 재시도하는 방식이 더 견고합니다.

```typescript
import { engine } from "@dcl/sdk/ecs"
import { Storage } from "@dcl/sdk/server"

// 작업 상태는 메모리에 보관하고, 이벤트가 발생할 때마다 업데이트합니다
const scores: Record<string, number> = {}
const dirty = new Set<string>()

function onPointScored(address: string) {
  scores[address] = (scores[address] ?? 0) + 1
  dirty.add(address) // 나중에 플러시하도록 표시합니다. 여기서는 Storage를 호출하지 않습니다
}

// 더티 키를 주기적으로(예: 약 30초마다) 그리고 체크포인트에서 플러시합니다
async function flush() {
  for (const address of dirty) {
    const ok = await Storage.player.set(address, "score", scores[address])
    if (ok) {
      dirty.delete(address) // 저장 성공
    }
    // ok가 false이면 해당 키는 더티 상태로 남아 다음 플러시 때 재시도됩니다
  }
}

// dt 누산기를 사용해 타이머로 플러시를 실행합니다
let flushTimer = 0
engine.addSystem((dt) => {
  flushTimer += dt
  if (flushTimer > 30) {
    flushTimer = 0
    flush()
  }
})
```

### 월드 스토리지 — 모든 플레이어 간 공유

```typescript
import { Storage } from "@dcl/sdk/server"

type Entry = { name: string; score: number }

// 쓰기 — 값이 저장되지 않으면 set()은 false를 반환합니다
const ok = await Storage.set("leaderboard", [
  { name: "Alice", score: 100 },
  { name: "Bob", score: 85 },
])
if (!ok) {
  console.error("Failed to save leaderboard — retry later")
}

// 읽기: 키가 존재하지 않으면 null
const leaderboard = (await Storage.get<Entry[]>("leaderboard")) ?? []

// 삭제
await Storage.delete("leaderboard")
```

명령줄에서도 다음을 사용해 씬 저장소를 관리할 수 있습니다. `npx sdk-commands storage scene`:

```bash
# 값 설정
npx sdk-commands storage scene set high_score --value 100

# 값 가져오기
npx sdk-commands storage scene get high_score

# 값 삭제
npx sdk-commands storage scene delete high_score

# 씬 저장소 데이터 모두 삭제
npx sdk-commands storage scene clear --confirm
```

### 플레이어 저장소 — 지갑 주소별

```typescript
import { Storage } from "@dcl/sdk/server"

type Progress = { level: number; coins: number }

// 쓰기 — 값이 저장되지 않으면 set()은 false를 반환합니다
const ok = await Storage.player.set(playerAddress, "progress", {
  level: 5,
  coins: 250,
})
if (!ok) {
  console.error(`Failed to save progress for ${playerAddress} — retry later`)
}

// 읽기: 이 플레이어의 저장된 진행 상황이 없으면 null
const progress = (await Storage.player.get<Progress>(playerAddress, "progress")) ?? { level: 1, coins: 0 }

// 삭제
await Storage.player.delete(playerAddress, "progress")
```

명령줄에서도 다음을 사용해 플레이어 저장소를 관리할 수 있습니다. `npx sdk-commands storage player`:

```bash
# 특정 플레이어의 값 설정
npx sdk-commands storage player set level --value 10 --address 0x1234...

# 특정 플레이어의 값 가져오기
npx sdk-commands storage player get level --address 0x1234...

# 특정 플레이어의 값 삭제
npx sdk-commands storage player delete level --address 0x1234...

# 특정 플레이어의 데이터 모두 삭제
npx sdk-commands storage player clear --address 0x1234... --confirm

# 모든 플레이어의 데이터 삭제
npx sdk-commands storage player clear --confirm
```

각 씬 값은 최대 512KB이며, 한 World의 모든 씬 값이 공유하는 용량은 10MB입니다. 각 플레이어 값은 최대 100KB이고, 플레이어당 용량은 1MB입니다.

{% hint style="warning" %}
**📔 참고**: 저장된 데이터가 있는 플레이어를 목록으로 확인할 방법은 없습니다. `Storage.player.getValues(address, { prefix, offset })` 를 사용하면 이미 알고 있는 한 플레이어의 키를 나열할 수 있지만, SDK와 `storage player` 명령어 모두 [저장소 UI](#access-stored-data) 에서도 플레이어 주소를 나열할 수는 없습니다. 저장 데이터를 마이그레이션하거나 플레이어 데이터를 바탕으로 순위표를 만드는 등 모든 플레이어를 순회해야 할 수도 있다면, 씬 키에 주소 인덱스도 직접 저장하세요.
{% endhint %}

### 덮어쓰지 않고 저장 데이터 불러오기

플레이어가 참여할 때 기본 데이터를 할당한 뒤 저장하지 마세요. 저장된 데이터가 있지만 아직 불러오지 않은 상태라면 기본 데이터가 이를 덮어씁니다. 먼저 읽고, `get()` 의 결과가 `null`일 때만 기본 데이터를 만드세요. 읽기 중 오류가 발생하면 플레이어를 로드되지 않은 상태로 두고 나중에 다시 시도하세요.

```typescript
import { Storage } from "@dcl/sdk/server"

type Save = { coins: number }
const saves: Record<string, Save> = {}

async function loadOrCreate(address: string): Promise<Save> {
  if (saves[address]) return saves[address] // Already loaded
  // 읽기에 실패하면 예외를 발생시켜 실패가 새 저장 데이터로 처리되지 않도록 합니다
  const stored = await Storage.player.get<Save>(address, "save")
  saves[address] = stored ?? { coins: 0 } // 저장 데이터가 없을 때만 기본값을 사용합니다
  return saves[address]
}
```

join 핸들러의 `try/catch` 안에서 이를 호출하세요. 예외가 발생하면 클라이언트에 알려 재시도할 수 있도록 하고, 해당 플레이어의 저장 데이터가 로드될 때까지 그 플레이어의 동작을 무시하세요.

### 씬에 아무도 없을 때의 진행 상황

작물 성장, 에너지 충전, 상점 재입고처럼 시간이 지나면서 진행되는 작업에 타이머를 계속 실행하지 마세요. Multiplayer Server는 마지막 플레이어가 떠난 후 몇 분이 지나면 중지되므로( [서버가 시작될 때까지 기다리기](#wait-for-the-server-to-start-up)참조), 타이머도 중지됩니다. 대신 진행 상황이 마지막으로 업데이트된 시간을 저장하세요. 플레이어가 돌아오면 경과 시간을 기준으로 진행 상황을 계산하고 저장된 시간을 갱신하세요.

이때는 서버의 `Date.now()` 를 사용하고, 클라이언트가 보낸 시간은 절대 사용하지 마세요. 플레이어가 시계를 앞당겨 대기 시간을 건너뛸 수 있기 때문입니다.

### 동시 쓰기로 인한 데이터 손실 방지

Storage에는 키를 읽은 이후 아무도 변경하지 않았을 때만 업데이트하는 방법("compare-and-set")이 없습니다. 따라서 키를 읽고 값을 변경한 다음 다시 쓰면 데이터가 손실될 수 있습니다.

* 두 서버 인스턴스가 동시에 쓸 수 있습니다. 재배포 중에 씬의 이전 버전과 새 버전이 겹치는 동안 이런 일이 발생합니다.
* 읽기 작업에서 마지막으로 쓴 값보다 오래된 값이 반환될 수 있습니다. Storage는 `Storage.get(key, { fresh: true })`를 사용하고 서버를 재시작한 경우에도 키의 오래된 값을 한 시간 이상 반환한 적이 있습니다. `fresh` 옵션은 SDK 자체 캐시만 건너뜁니다.
* 다음으로 조회한 목록도 `Storage.getValues()` 오래되었을 수 있습니다. 최근에 쓴 키가 빠지거나 삭제한 키가 여전히 표시될 수 있습니다.

결과 로그나 플레이어 피드백처럼 계속 늘어나기만 하는 데이터에는 하나의 키를 덮어쓰는 대신 다음 패턴을 사용하세요.

1. 각 스냅샷을 시간순으로 정렬되고 충돌하지 않는 **새 키** 에 쓰세요. 예를 들면 `results-1-20261027-130512-k3fz`와 같이 접두사, 파트 번호, UTC 시간, 몇 개의 임의 문자로 구성합니다.
2. 읽을 때는 `Storage.getValues({ prefix, offset })`로 해당 파트의 모든 키를 `pagination.total` 개의 항목이 모일 때까지 페이지별로 조회한 다음, 행 ID를 기준으로 병합하세요.
3. 병합한 행을 새 키에 쓰세요. 그 키를 다시 읽고 값이 일치하는 경우에만 병합한 키를 삭제하세요. 읽은 값에 근거해 다른 쓰기 작업이 여전히 변경할 수 있는 키는 절대 삭제하지 마세요.

이렇게 하면 경합이 발생해도 행이 손실되는 대신 추가 키가 남으며, 다음 쓰기 작업에서 이를 병합합니다. 데이터 읽기 작업을 수행하는 모든 사용자(예를 들어 [스토리지 UI](#access-stored-data)에서 데이터를 다운로드하는 경우)는 해당 파트의 모든 키를 읽고 중복 ID를 제거해야 합니다.

```typescript
import { Storage } from "@dcl/sdk/server"

type Row = { id: string; text: string }
const PREFIX = "results-1-"

// 접두사로 시작하는 모든 키를 오래된 순으로 조회합니다
async function listAll(prefix: string) {
  const entries: { key: string; value: unknown }[] = []
  for (;;) {
    const page = await Storage.getValues({ prefix, offset: entries.length })
    entries.push(...page.data)
    if (page.data.length === 0 || entries.length >= page.pagination.total) break
  }
  return entries.sort((a, b) => (a.key < b.key ? -1 : 1))
}

async function appendRows(newRows: Row[]): Promise<boolean> {
  const versions = await listAll(PREFIX)
  // 행 ID를 기준으로 병합하며, 먼저 발견된 항목을 유지합니다
  const rows = new Map<string, Row>()
  for (const { value } of versions) for (const row of value as Row[]) if (!rows.has(row.id)) rows.set(row.id, row)
  for (const row of newRows) if (!rows.has(row.id)) rows.set(row.id, row)
  const merged = [...rows.values()]

  // 매번 새 키를 만듭니다. UTC 시간과 임의의 문자를 조합합니다
  // "2026-10-27T13:05:12.123Z"는 "20261027-130512"가 됩니다
  const stamp = new Date().toISOString().slice(0, 19).replace(/[-:]/g, "").replace("T", "-")
  const key = `${PREFIX}${stamp}-${Math.random().toString(36).slice(2, 6)}`
  if (!(await Storage.set(key, merged))) return false // 저장되지 않았습니다. 나중에 다시 시도하세요

  // 새 키에서 값을 다시 읽을 수 있을 때까지 병합된 키를 삭제하지 않습니다
  const check = await Storage.get<Row[]>(key, { fresh: true })
  if (JSON.stringify(check) !== JSON.stringify(merged)) return true
  for (const version of versions) {
    try {
      await Storage.delete(version.key)
    } catch {
      // 남겨 두면 다음 쓰기 작업에서 다시 병합됩니다
    }
  }
  return true
}
```

값 하나에는 최대 512KB까지 저장할 수 있으므로, 한 부분의 크기가 이 한도에 가까워지기 전에 새 부분을 시작하세요(`results-2-`). [Scene Feedback 예제](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0%2C-1-scene-feedback) 는 CSV 파일에 이 패턴을 사용하며, 크기가 400KB에 도달하면 새 부분으로 전환합니다.

### 저장된 데이터에 액세스하기

다음 링크를 입력하면 스토리지 UI에서 서버에 실시간으로 저장된 데이터를 보고 수정할 수 있습니다.

[decentraland.org/storage](https://decentraland.org/storage)

월드의 경우 Creator Hub를 통해서도 이 페이지에 액세스할 수 있습니다. 다음으로 이동하세요. **관리** 페이지에서 월드 카드의 점 세 개를 클릭한 다음 **스토리지 보기**.

여기에서 씬을 게시할 수 있는 모든 월드와 랜드 목록을 볼 수 있습니다.

씬을 연 다음 **씬** 또는 **플레이어** 탭을 여세요.

의 **씬** 탭에는 저장된 모든 변수의 목록이 표시됩니다. 연필 아이콘이나 휴지통 아이콘을 클릭하면 여기서 변수를 수정하거나 삭제할 수 있습니다.

![Activate stream](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-bbb302fbdb29f57fdcff7bf62fc6608838a06d44%2Fscene-data.webp?alt=media)

의 **플레이어** 탭에는 서버에 저장된 데이터가 있는 모든 플레이어의 목록이 표시됩니다. 주소나 이름으로 검색한 다음 각 플레이어와 관련된 모든 데이터를 확인할 수 있습니다. 연필 아이콘이나 휴지통 아이콘을 클릭해 이 데이터를 수정하거나 삭제할 수도 있습니다.

### 데이터 구조 변경하기

프로덕션 환경에 저장된 데이터는 **씬의 새 버전을 게시해도 삭제되지 않습니다**. 이는 순위표, 플레이어 진행 상황, 그리고 씬의 사소한 업데이트 이후에도 계속 유지되기를 플레이어가 기대하는 환경 변경 사항에 유용합니다.

반면 스토리지에 있는 데이터는 이전 버전의 코드로 작성된 것입니다. 새 코드에서 다른 형식을 기대하면 이전 데이터를 구문 분석하거나 읽는 과정에서 미묘한 오류가 발생할 수 있습니다. 이름을 바꾼 필드는 누락됩니다. 문자열이었던 필드가 객체로 바뀌면 해당 필드의 속성에 액세스할 때 오류가 발생합니다. 몇 달 동안 로그인하지 않은 플레이어가 코드에서 더 이상 처리할 수 없는 구조를 사용하던 시기의 데이터를 불러올 수도 있습니다.

{% hint style="warning" %}
**📔 참고**: 스키마 변경은 배포 직후의 첫 데이터 읽기에만 영향을 주는 것이 아닙니다. 저장된 데이터는 덮어쓰거나 삭제할 때까지 남아 있으므로, 오래된 형식의 값은 언제든 다시 나타날 수 있습니다. 특히 잊고 있던 플레이어가 돌아왔을 때 그런 일이 자주 발생합니다.
{% endhint %}

#### 권장사항

* *항상 방어적으로 읽으세요*. 직접 작성한 데이터라도 저장소에서 가져온 모든 항목을 신뢰할 수 없는 입력으로 취급하세요. get\<T>()에 전달하는 `get<T>()` 의 타입은 검사되지 않으므로, 값을 읽기 전에 필드가 존재하고 올바른 타입인지 확인하고, 그렇지 않을 때 사용할 적절한 기본값을 준비하세요:

  ```typescript
  import { Storage } from "@dcl/sdk/server"

  const saved = await Storage.player.get<any>(playerAddress, "progress")
  const progress = {
    level: typeof saved?.level === "number" ? saved.level : 1,
    coins: typeof saved?.coins === "number" ? saved.coins : 0,
  }
  ```
* *필드는 추가하되 이름을 바꾸거나 제거하지 마세요*. 가장 안전한 스키마 변경은 필드를 추가하는 것입니다. 기본값이 있는 새 필드를 도입하고 기존 필드는 그대로 두세요. 이전 데이터에는 새 필드가 없을 뿐이며, 방어적 파싱으로 이미 처리할 수 있습니다. 필드 이름을 바꾸면 기존 레코드가 모두 깨집니다.
* *저장 객체에 버전을 지정하세요*. 처음부터 `version` 필드를 포함하세요. 데이터를 읽을 때는 버전에 따라 분기하고, 사용하기 전에 이전 형식의 데이터를 현재 형식으로 마이그레이션하세요. 이렇게 하면 나머지 코드는 항상 하나의 최신 형식으로 동작합니다:

  ```typescript
  type ProgressV2 = { version: 2; level: number; coins: number; xp: number }

  function migrate(raw: any): ProgressV2 {
    const version = raw?.version ?? 1
    if (version === 1) {
      // v1에는 xp 필드가 없었으므로 기본값을 설정합니다
      return {
        version: 2,
        level: raw.level ?? 1,
        coins: raw.coins ?? 0,
        xp: 0,
      }
    }
    return raw as ProgressV2
  }
  ```
* *마이그레이션한 값을 다시 저장하세요*. 메모리에서 레코드 형식을 업그레이드한 후에는 다시 저장하여 다음에 읽을 때 이미 새 형식으로 되어 있도록 하세요. 시간이 지나면 일회성 마이그레이션 스크립트 없이도 이전 형식의 레코드가 점차 줄어듭니다.
* *호환성을 깨는 변경에는 새 키를 사용하세요*. 새 구조가 실제로 호환되지 않고 마이그레이션할 가치가 없다면 새 저장소 키(예: `progress_v2`)에 기록하고 이전 키는 무시하세요. 이전 키는 저장소에 그대로 두어도 문제가 없으며, 이를 해석해야 하는 읽기 경로를 피할 수 있습니다. 나중에 [저장소 UI](https://decentraland.org/storage) 또는 `npx sdk-commands storage` 명령을 사용해 이전 키를 정리할 수 있습니다.
* *실제 프로덕션 데이터로 테스트하세요*. 구조를 변경해 배포하기 전에 저장소 UI에서 실제 레코드 몇 개를 가져와 새 파싱 코드로 테스트하세요. 문제를 일으키는 예외 상황은 대개 존재하는 줄 몰랐던 레코드에서 비롯됩니다.
* *복구할 방법을 마련하세요*. 저장소 UI 또는 `npx sdk-commands storage`를 통해 개별 레코드를 수정하거나 삭제할 수 있다는 점을 기억하세요. 스키마 변경 후 특정 플레이어의 상태가 잘못되어 진행이 막히면 다시 배포하지 않고도 해당 레코드를 직접 수정할 수 있습니다.

## 환경 변수

값을 코드에 하드코딩하지 않고 씬을 구성하세요. 환경 변수는 민감한 데이터뿐 아니라 씬을 다시 게시하지 않고도 쉽게 변경할 수 있는 기능 플래그나 매개변수에도 유용합니다.

환경 변수는 **서버 전용입니다**. `isServer()`로 보호하세요. 서버는 환경 변수를 읽을 수 있지만 값을 변경할 수는 없습니다.

`EnvVar.get()` 는 `Promise<string>` 변수가 설정되지 않은 경우 빈 문자열로 확인되므로, 누락된 값에 대비해 항상 기본값을 지정하세요:

```typescript
import { EnvVar } from "@dcl/sdk/server"
import { isServer } from "@dcl/sdk/network"

export async function main() {
  if (!isServer()) return

  const maxPlayers = parseInt((await EnvVar.get("MAX_PLAYERS")) || "4")
  const gameDuration = parseInt((await EnvVar.get("GAME_DURATION")) || "300")
  const debugMode = ((await EnvVar.get("DEBUG")) || "false") === "true"
}
```

### 민감한 데이터

환경 변수는 비공개 키, 보상 수령 코드 및 공개 씬의 컴파일된 코드에 노출될 경우 위험할 수 있는 기타 민감한 데이터를 저장하는 데 특히 유용합니다.

비공개 키를 서버 저장소에 저장하고, 서버에서만 이 키를 읽도록 할 수 있습니다. `isServer()`. 이렇게 하면 민감한 데이터가 플레이어의 컴퓨터를 거치지 않습니다.

### 로컬 개발

프로젝트를 로컬에서 실행하는 동안 환경 변수를 사용하려면 프로젝트 루트에 `.env` 파일을 만드세요:

```
MAX_PLAYERS=8
GAME_DURATION=300
DEBUG=true
```

중요: 잠재적으로 민감한 값이 공개 콘텐츠 서버에 업로드되지 않도록 `.env` 를 `.gitignore`에 추가하세요.

### 환경 변수 변경

환경 변수의 값을 변경하는 가장 쉬운 방법은 저장소 UI를 이용하는 것입니다.

다음 링크를 열어 씬 저장소에 저장된 데이터에 접근할 수 있습니다:

[decentraland.org/storage](https://decentraland.org/storage)

월드의 경우 Creator Hub를 통해서도 이 페이지에 액세스할 수 있습니다. 다음으로 이동하세요. **관리** 페이지에서 월드 카드의 점 세 개를 클릭한 다음 **스토리지 보기**.

여기에서 씬을 게시할 수 있는 모든 월드와 랜드 목록을 볼 수 있습니다.

씬을 연 다음 **환경** 탭을 선택하세요. 프로젝트의 모든 환경 변수가 표시됩니다.

![Activate stream](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-766c8433de10c67980a737242d867ad3c4fb5948%2Fenvironment-variables.webp?alt=media)

민감한 데이터를 보호하기 위해 환경 변수의 값은 읽을 수 없지만, 삭제하거나 덮어쓸 수 있습니다. 연필 또는 휴지통 아이콘을 클릭하세요.

명령줄에서 다음 명령을 사용해 환경 변수를 관리할 수도 있습니다. `npx sdk-commands storage env`:

```bash
# 변수 설정
npx sdk-commands storage env set MAX_PLAYERS --value 8

# 변수 삭제
npx sdk-commands storage env delete OLD_VAR

# 모든 환경 변수 삭제
npx sdk-commands storage env clear --confirm
```

다음 `--target` 플래그를 사용해 특정 환경을 대상으로 지정할 수도 있습니다:

```bash
# 스테이징에 배포
npx sdk-commands storage env set MY_KEY --value my_value --target https://storage.decentraland.zone

# 로컬 개발 서버에 배포
npx sdk-commands storage env set MY_KEY --value my_value --target http://localhost:8000
```

배포된 환경 변수는 `.env` 값보다 우선 적용됩니다.

## 권장 프로젝트 구조

서버, 클라이언트, 공유 코드를 분리하면 코드베이스가 커져도 읽기 쉽게 유지할 수 있습니다:

```
src/
├── index.ts              # 진입점 — isServer() 분기
├── client/
│   ├── setup.ts          # 입력 처리기, 메시지 전송기
│   └── ui.tsx            # React ECS UI (동기화된 상태 읽기)
├── server/
│   ├── server.ts         # 게임 루프, 메시지 처리기, 상태 변경
│   └── gameState.ts      # 서버 상태용 헬퍼 함수
└── shared/
    ├── schemas.ts        # 컴포넌트 정의 + validateBeforeChange
    └── messages.ts       # registerMessages() — 양쪽에서 가져오기
```

{% hint style="info" %}
**💡 팁**:  `registerMessages()` 호출과 사용자 지정 컴포넌트 정의는 모두 `shared/`에 두세요. 서버와 클라이언트 모두 여기서 가져오므로 메시지 스키마가 항상 일치합니다.
{% endhint %}

## 성능 모범 사례

컴포넌트가 변경될 때마다 컴포넌트 데이터 *전체* 가 네트워크를 통해 전송됩니다. 이는 변경분만 전송하는 Colyseus의 방식과 다릅니다. 사용자 지정 컴포넌트를 설계할 때 이 점을 고려하세요. 변경 빈도에 따라 별도의 컴포넌트에 데이터를 저장하는 것이 최적의 방법일 수 있습니다.

### ❌ 거대한 단일 컴포넌트는 피하세요

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"

// 나쁜 예 — 점수를 변경하면 위치 배열도 전송됩니다
const GameState = engine.defineComponent("GameState", {
  playerAScore: Schemas.Int,
  playerBScore: Schemas.Int,
  timer: Schemas.Int,
  playerPositions: Schemas.Array(Schemas.Vector3), // 큰 페이로드
})
```

### ✅ 원자적 컴포넌트를 사용하세요

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"

// 좋은 예 — 각 업데이트가 작고 독립적입니다
const PlayerScore = engine.defineComponent("PlayerScore", {
  playerA: Schemas.Int,
  playerB: Schemas.Int,
})

const GameTimer = engine.defineComponent("GameTimer", {
  secondsLeft: Schemas.Int,
})
```

*경험 법칙*: 함께, 비슷한 빈도로 변경되는 필드를 묶으세요. 자주 변경되는 데이터(타이머, 위치)는 천천히 변경되는 데이터(점수, 구성)와 분리하세요.

### 빈번한 메시지 전송 제한

매 프레임 메시지를 보내지 마세요. 가능한 경우 메시지를 묶거나 전송 빈도를 제한하세요:

```typescript
import { engine } from "@dcl/sdk/ecs"
import { room } from "./shared/messages"

let lastSend = 0
engine.addSystem((dt) => {
  lastSend += dt
  if (lastSend > 0.1) {
    // 100ms마다
    room.send("position", transform.position)
    lastSend = 0
  }
})
```

예를 들어 서버가 카운트다운 타이머를 제어하는 경우, 매초 모든 플레이어에게 업데이트를 보낼 필요는 없습니다. 각 클라이언트가 자체적으로 경과 시간을 계산하고, 일관성을 유지하기 위해 서버가 현재 상태를 약 30초마다 브로드캐스트하는 것이 좋습니다.

## 서버 리소스 제한

멀티플레이어 서버는 엄격한 리소스 한도가 적용되는 샌드박스 격리 환경에서 각 씬을 실행합니다. 한도를 초과하면 데이터가 예고 없이 손실되거나 씬에 있는 모든 사용자에게 서버가 종료될 수 있으므로, 씬이 한도에 충분히 여유를 두도록 설계하세요.

### 메모리

격리 환경에는 다음과 같은 **256 MB** 메모리 상한입니다. 이를 초과하면 격리 실행 환경이 폐기되고 연결된 모든 플레이어의 서버가 종료됩니다. 작업 상태를 가볍게 유지하고 플레이어가 떠날 때 플레이어별 데이터를 정리하세요.

### CPU

각 실행 턴에는 벽시계 기준 제한 시간이 있습니다.

* **동기 실행**: 턴당 10초입니다. 제한 없는 루프가 이를 초과하면 격리 실행 환경이 종료됩니다.
* **비동기 턴 완료 대기**: 60초입니다.  `Promise`  체인 또는  `await` 의 완료까지 이보다 오래 걸리면 격리 실행 환경이 종료됩니다.

다음과 같은  `dt`  누산기를 사용해 무거운 작업을 여러 틱에 나누어 처리하세요:  `engine.addSystem()`. 서버에서 제한 없는 동기 루프를 절대 실행하지 마세요.

### 수신 메시지 속도

연결된 각 피어는 약  **1,000ms당 메시지 300개**까지 보낼 수 있습니다. 초과 데이터 프레임은 대기열에 넣지 않고 삭제됩니다. 클라이언트에서 매 프레임마다 메시지를 보내지 마세요. 전송 빈도를 제한하는 방법은  [성능 모범 사례](#performance-best-practices) 를 참조하세요.

### 메시지 크기

* 수신 패킷의 크기는 패킷당  **128 KB** 로 제한됩니다. 크기가 초과된 패킷은 통째로 삭제됩니다.
* 씬에서 통신 모듈로 보내는 메시지의 크기는 약  **30 KB**로 제한됩니다. 실제 전송 계층에서 동기화 메시지는  **13 KB** 보다 훨씬 작게 유지하세요( [메시지](#messages)  섹션을 참조하세요).

### 외부 가져오기

동시에 실행할 수 있는  `signedFetch`  호출은 최대  **32** 개로 제한됩니다. 추가 요청은 자리가 생길 때까지 대기열에서 기다립니다. 각 가져오기 시도에는  **15초** 의 시간 제한이 있습니다. 가져오기 응답 크기는 최대  **10 MB**입니다. WebSocket 연결은 동시 연결 수가 제한되며 메시지 크기는 최대  **32** 개 소켓까지 허용되고, 메시지 최대 크기는  **1 MB** 입니다.

### 실행 중인 호스트 호출

에서 설명한 호출 수 제한 40개는 Storage를 포함해 격리 실행 환경 전체의 모든 호스트 호출에 적용됩니다. [데이터 저장소](#data-storage) 에 설명된 `signedFetch`및 기타 런타임 API입니다. 초과 호출은 즉시 거부되며 대기열에 추가되지 않습니다.

## 흔히 발생하는 문제

### 서버 전용 상태에 검증을 빠뜨리는 경우

validateBeforeChange `가 없으면`클라이언트가 모든 컴포넌트에 값을 쓸 수 있습니다.

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"
import { isServer } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"

// ❌ 나쁜 예 — 클라이언트가 속일 수 있음
const Score = engine.defineComponent("Score", { value: Schemas.Int })

// ✅ 좋은 예 — 서버 전용
if (isServer()) {
  Score.validateBeforeChange((v) => v.senderAddress === AUTH_SERVER_PEER_ID)
}
```

### 클라이언트가 제공한 값을 신뢰하는 경우

체력, 점수, 위치와 같은 중요한 데이터의 값을 클라이언트가 직접 정하도록 해서는 안 됩니다.

```typescript
import { room } from "./shared/messages"

// ❌ 나쁜 예
room.onMessage("setHealth", (data) => {
  player.health = data.health // 클라이언트가 값을 제어함!
})

// ✅ 좋은 예 — 서버에서 결과 계산
room.onMessage("takeDamage", (data) => {
  const damage = calculateDamage(data.source)
  player.health = Math.max(0, player.health - damage)
})
```

### 메시지에 담긴 금액과 주소를 신뢰하는 경우

클라이언트가 보낸 메시지는 사실이 아니라 요청입니다. 사용하기 전에 모든 필드를 확인하세요.

* **금액**: `Schemas.Int` 는 값을 32비트 정수로 디코딩하지만, 값은 여전히 0이거나 음수일 수 있습니다. 0 이하의 금액은 거부하세요. 그렇지 않으면 플레이어가 코인을 "보내는" 대신 `-500` 받을 수도 있습니다. 또한 송신자에게 충분한 잔액이 있는지도 확인하세요.
* **주소**: 클라이언트가 보내는 지갑 주소는 다음 형식이어야 합니다. `0x` 뒤에 16진수 문자 40개가 와야 합니다. 다른 형식은 맵이나 Storage에 전달되기 전에 거부하세요.

```typescript
import { room } from "./shared/messages"

const ADDRESS = /^0x[0-9a-f]{40}$/
const balances: Record<string, number> = {}

room.onMessage("giveCoins", (data, context) => {
  if (!context) return
  const from = context.from.toLowerCase()
  const to = String(data.to).toLowerCase()
  if (!ADDRESS.test(to) || to === from) return
  if (!Number.isInteger(data.amount) || data.amount <= 0) return // 음수와 0을 거부
  if ((balances[from] ?? 0) < data.amount) return // 코인 잔액 부족
  balances[from] -= data.amount
  balances[to] = (balances[to] ?? 0) + data.amount
})
```

### 상태 동기화 전에 메시지를 보내는 경우

클라이언트는 상호작용하기 전에 상태가 동기화될 때까지 기다려야 합니다.

```typescript
import { engine } from "@dcl/sdk/ecs"
import { isStateSyncronized } from "@dcl/sdk/network"

engine.addSystem(() => {
  if (!isStateSyncronized()) return
  // 이제 메시지를 안전하게 보낼 수 있음
})
```

### 서버가 시작될 때까지 기다리기

씬에 플레이어가 한 명 이상 있을 때만 서버가 활성화됩니다. 마지막 플레이어가 떠난 후에도 서버는 약 2분 동안 실행된 다음 종료됩니다. 다음 방문 시에는 새 인스턴스가 콜드 스타트되며, 이 과정에는 약 **프로덕션 환경에서 15초**가 걸립니다. 로컬 미리보기에서는 서버가 즉시 시작되므로, 콜드 스타트 문제는 거의 항상 게시한 후에야 드러납니다.

씬의 코드는 서버가 온라인 상태가 될 때까지 기다릴 준비가 되어 있어야 합니다. 서버 시작이 완료되기 전에 보낸 메시지는 아무런 표시 없이 유실됩니다. 기다리는 동안 플레이어에게 "서버를 깨우는 중"이라는 메시지를 표시하고, 서버에 보내는 초기 요청에는 재시도 로직을 추가하세요.

{% hint style="info" %}
**팁:** 서버가 준비되었는지 확인하는 신뢰할 수 있는 방법은 하트비트입니다. 서버에서 다음을 기록하도록 하세요. `Date.now()` 동기화된 컴포넌트 필드에 2초마다 기록하고, 클라이언트가 마지막으로 값의 변경을 확인한 시점을 추적하게 합니다. 6초 이내에 변경 사항이 도착하지 않으면 서버가 오프라인 상태라고 간주합니다. 이는 `isStateSyncronized()`보다 더 안정적입니다. 이 함수는 전송 계층이 연결되어 있는지만 확인할 뿐, 서버가 실행 중인지는 확인하지 않기 때문입니다.
{% endhint %}

## 완성된 예제

간단한 멀티플레이어 카운터입니다. 버튼을 클릭하면 서버에서 동기화된 점수가 증가합니다. 서버는 카운터를 `Storage` 에 저장하므로 서버가 재시작되어도 값이 유지됩니다. 씬에 플레이어가 없으면 서버가 종료된다는 점에 유의하세요. 따라서 저장소를 사용하지 않으면 씬에 플레이어가 없는 상태가 될 때마다 카운트가 0으로 초기화됩니다.

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"
import { registerMessages, isServer, syncEntity } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"
import { pointerEventsSystem } from "@dcl/sdk/ecs"
import { Storage } from "@dcl/sdk/server"

// 1. 메시지 정의 (공유)
const Messages = {
  increment: Schemas.Map({}),
  stateUpdate: Schemas.Map({
    count: Schemas.Int,
    lastPlayer: Schemas.String,
  }),
}

// 2. 서버 전용 컴포넌트 정의 (공유)
const Counter = engine.defineComponent("Counter", {
  value: Schemas.Int,
  lastPlayer: Schemas.String,
})

// 3. 룸 생성
const room = registerMessages(Messages)

export async function main() {
  if (isServer()) {
    // === 서버 ===

    // 이 컴포넌트는 서버만 수정할 수 있습니다
    Counter.validateBeforeChange(
      (v) => v.senderAddress === AUTH_SERVER_PEER_ID
    )

    // 서버가 재시작된 경우를 대비해 저장소에서 카운터 복원
    let initialCount = 0
    let initialPlayer = "none"
    let loaded = false
    try {
      initialCount = (await Storage.get<number>("counter")) ?? 0
      initialPlayer = (await Storage.get<string>("lastPlayer")) ?? "none"
      loaded = true
    } catch (error) {
      console.log("[Server] Could not load the counter:", error)
    }

    const counterEntity = engine.addEntity()
    syncEntity(counterEntity, [Counter.componentId], 1)
    Counter.create(counterEntity, {
      value: initialCount,
      lastPlayer: initialPlayer,
    })

    room.onMessage("increment", async (_data, context) => {
      if (!context) return
      if (!loaded) return // 로드되지 않은 카운터를 덮어쓰지 않음
      const from = context.from.toLowerCase()
      const counter = Counter.getMutable(counterEntity)
      counter.value += 1
      counter.lastPlayer = from

      // 서버가 재시작되어도 값이 유지되도록 저장소에 저장
      const saved =
        (await Storage.set("counter", counter.value)) &&
        (await Storage.set("lastPlayer", from))
      if (!saved) console.log("[Server] Counter not saved, the next click saves it again")

      room.send("stateUpdate", {
        count: counter.value,
        lastPlayer: from,
      })
    })
  } else {
    // === 클라이언트 ===
    const button = engine.addEntity()
    // ... Transform, MeshRenderer 등을 추가합니다.

    pointerEventsSystem.onPointerDown(button, () => {
      room.send("increment", {})
    })

    room.onMessage("stateUpdate", (data) => {
      console.log(`Count: ${data.count} (last click by ${data.lastPlayer})`)
    })
  }
}
```

## 로컬에서 테스트하기

표준 미리보기에서 모든 작업이 처리됩니다. SDK의 auth-server 브랜치를 사용하면 클라이언트 미리보기와 함께 로컬 서버가 백그라운드에서 자동으로 시작됩니다.

로컬에서 멀티플레이어 상호작용을 테스트하려면 미리보기를 별도의 창 두 개에서 엽니다. 각 창은 별개의 플레이어로 간주됩니다. 각 창을 서로 다른 주소에 연결하세요. 두 클라이언트 모두 같은 로컬 서버 인스턴스에 연결됩니다.

Creator Hub에서 **다중 인스턴스 미리 보기** 을 **데스크톱 클라이언트** 의 하위 메뉴 **재생 옵션**, 그런 다음 **재생**  버튼을 한 번 더 클릭하면 Decentraland 탐색기 창이 하나 더 열립니다. 두 창 모두 서로 다른 주소로 연결해야 합니다. 장면이 다시 로드되어도 두 세션은 열린 상태로 유지됩니다.

또는 브라우저 주소창에 다음을 입력해 Decentraland 탐색기 창을 하나 더 열 수 있습니다.

> `decentraland://realm=http://127.0.0.1:8000&local-scene=true&debug=true&multi-instance=true`

### 디버깅 팁

* *로그 앞에* 다음을 `[SERVER]` 또는 `[CLIENT]` 붙이면 터미널에서 로그를 구분할 수 있습니다:

  ```typescript
  import { isServer } from "@dcl/sdk/network"

  if (isServer()) {
    console.log("[SERVER] Starting...")
  } else {
    console.log("[CLIENT] Starting...")
  }
  ```
* *구성 요소 동기화 확인* 엔터티 수를 기록해 클라이언트에서 확인합니다:

  ```typescript
  import { engine } from "@dcl/sdk/ecs"

  engine.addSystem(() => {
    const entities = Array.from(engine.getEntitiesWith(MyComponent))
    console.log("[CLIENT] Synced entities:", entities.length)
  })
  ```

## 프로덕션 환경에서 디버깅

사용 [Scene Insights](https://docs.decentraland.org/creator/content-creator-ko/sdk7/debugging/scene-insights.md) 게시된 서버 로그를 검색하고 실시간으로 확인하며 CPU, 메모리 및 기타 메트릭을 조회하려면 사용하세요. 로그와 메트릭은 다음 기간 동안 보관됩니다: **7일**(재시작 및 재배포 후에도 유지됩니다).

최신 버전으로 업데이트 `auth-server` SDK를 사용한 다음, 씬 프로젝트에서 다음 명령을 실행합니다:

```bash
npx sdk-commands scene-insights login
npx sdk-commands scene-insights tail
```

브라우저에서 권한이 있는 지갑으로 로그인합니다. 읽기 전용 세션은 이후 명령에서 최대 12시간 동안 재사용됩니다. 다음 키를 눌러 **Ctrl+C** 로그 추적을 중지합니다.

다음 [Scene Insights 가이드](https://docs.decentraland.org/creator/content-creator-ko/sdk7/debugging/scene-insights.md) 에서는 과거 검색, 씬 선택, 액세스 권한, 지표, AI 지원 디버깅, 컬렉션 한도를 다룹니다.

### 저장 데이터 보기

다음 링크를 열어 씬 저장소에 저장된 데이터에 접근할 수 있습니다:

[decentraland.org/storage](https://decentraland.org/storage)

월드의 경우 Creator Hub를 통해서도 이 페이지에 액세스할 수 있습니다. 다음으로 이동하세요. **관리** 페이지에서 월드 카드의 점 세 개를 클릭한 다음 **스토리지 보기**.

여기에서 씬을 게시할 수 있는 모든 월드와 랜드 목록을 볼 수 있습니다.

월드 데이터나 플레이어 데이터를 열어 각각에 저장된 정보를 확인하세요.

예를 들어, 특정 플레이어가 씬을 플레이할 때 문제가 발생하면 주소로 해당 플레이어를 찾아 어떤 데이터가 저장되어 있는지 확인해 상황을 파악할 수 있습니다. 모서리 사례를 만나 데이터가 서로 모순되는 상태가 되었을 수도 있습니다. 이 페이지에서 해당 플레이어의 데이터를 삭제하거나 수정해 안정적인 상태로 복구할 수도 있습니다.

## 버전 관리

씬을 게시할 때마다 고유한 해시 ID가 부여되며, 각 해시는 전용 서버 인스턴스와 연결됩니다. 따라서 클라이언트 코드와 서버 코드는 항상 함께 버전이 바뀝니다. 이전 로직을 실행하는 클라이언트가 새 로직을 실행하는 서버와 통신하거나(또는 그 반대의 경우) 하는 상황이 발생하지 않습니다.

업데이트를 게시하면 다음과 같이 동작합니다.

* *이미 씬에 있는 플레이어* 는 씬을 나갔다가 다시 들어올 때까지 이전 버전의 씬을 계속 보게 됩니다. 해당 플레이어의 클라이언트는 이전 해시에 해당하는 서버 인스턴스에 계속 연결되어 있습니다.
* *새로 들어오는 플레이어* 는 업데이트 후 새 씬 버전을 불러오고 새 서버 인스턴스에 연결됩니다.

이를 통해 스키마 변경이나 컴포넌트 이름 변경으로 인해 클라이언트와 서버의 상태가 서로 어긋나는 일이 없습니다. 업데이트로 인해 현재 씬에 있는 플레이어의 세션이 중단되는 일도 없습니다.

대신 배포 직후 잠시 동안 플레이어가 서로 다른 두 서버 인스턴스로 나뉠 수 있습니다. 기존에 접속해 있던 플레이어와 새로 접속한 플레이어는 같은 씬에 있더라도 서로를 볼 수 없거나 씬을 통해 상호작용하지 못할 수 있습니다. 기존 플레이어가 나갔다가 다시 접속할 때까지 이런 상태가 지속될 수 있습니다.

{% hint style="info" %}
**💡 팁**:  [Storage](#data-storage) 서비스를 통해 저장된 데이터(예: 리더보드, 플레이어 진행 상황 또는 영구적인 환경 변경 사항)는 버전 간에 *삭제되지* 않습니다. Storage 데이터는 위치 단위로 유지되며 동일한 씬을 가리키는 모든 서버 인스턴스에서 공유되므로, 새 버전은 이전 버전이 멈춘 지점부터 바로 이어서 사용할 수 있습니다.
{% endhint %}

## Colyseus에서 마이그레이션

Colyseus를 기반으로 기존 씬을 구축한 경우, 아래 표에서 일반적인 Colyseus 패턴과 이에 해당하는 SDK7 방식을 확인할 수 있습니다.

| Colyseus                   | SDK7 멀티플레이어 서버                       |
| -------------------------- | ------------------------------------ |
| `room.send(type, data)`    | `room.send(type, data)` — 동일한 API    |
| `room.onMessage(type, cb)` | `room.onMessage(type, cb)` — 동일한 API |
| `room.state.players` (스키마) | `syncEntity` + 사용자 지정 컴포넌트           |
| JSON 직렬화                   | 바이너리 직렬화(다음을 통해 자동 처리: `Schemas`)    |
| 별도의 서버 애플리케이션              | 동일한 코드베이스 — `isServer()` 분기 처리       |
| 사용자 지정 서버 호스팅              | 기본 제공: 미리 보기에서 서버가 자동으로 실행됨          |

유의해야 할 주요 차이점:

* *직렬화*: Colyseus는 JSON 차이점만 전송하지만, SDK는 변경될 때마다 전체 컴포넌트를 전송합니다. 컴포넌트 크기를 작게 유지하세요(참조: [성능 모범 사례](#performance-best-practices)).
* *상태 모델*: Colyseus는 자동 차이점 계산을 지원하는 변경 가능한 상태 트리를 사용합니다. SDK는 다음을 통해 동기화되는 ECS 컴포넌트를 사용합니다. `syncEntity` 그리고 다음을 사용해 변경을 보호합니다. `validateBeforeChange`.
* *호스팅*: 별도의 서버 배포가 필요하지 않습니다. 멀티플레이어 서버는 씬과 함께 자동으로 배포됩니다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/networking/authoritative-servers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
