# 🕹️ 메타그라운드(MetaGrownd) 맵 생성 가이드

🏡 홈으로 

이 문서는 메타그라운드 플랫폼에서 사용 가능한 맵 데이터(JSON)를 생성할 수 있도록 작성된 기술 명세서입니다. 이 가이드를 준수하면 문법적 오류가 없고 즉시 플레이 가능한 맵 파일을 생성할 수 있습니다. 다만 아래 내용을 선생님들께서 모두 숙지하실 필요는 없으며, 맵 생성은 기본 에디터로 생성하시면 됩니다. 아래 내용은 인공지능이 참고할 맵 제작 가이드 내용을 담고 있습니다. 

실제 인공지능을 활용한 맵 제작 방법은 가장 하단 섹션을 참고하세요. 

## 🕹️ 메타그라운드(MetaGrownd) 맵 구조 가이드

## 1. 파일 개요

- **포맷**: JSON

- **인코딩**: UTF-8

- **확장자**: `.json`

- **검증**: 생성된 JSON은 메타그라운드 로더에서 파싱 가능해야 하며, 스키마 위반 시 맵이 로드되지 않거나 깨질 수 있습니다.

---

## 2. JSON 데이터 구조

맵 파일의 최상위 구조는 다음과 같습니다. 모든 필드는 필수입니다.

```
{
  "version": "1.0",
  "exportedAt": "ISO-8601-Timestamp (예: 2024-02-11T09:00:00.000Z)",
  "mapData": {
    "id": "UUID-String",
    "name": "맵 이름",
    "description": "맵 설명",
    "gridSize": {
      "rows": 28,
      "cols": 50
    },
    "spaces": [ ... ],
    "cells": { ... },
    "objects": { ... },
    "objectConfigs": { ... },
    "isPublished": false,
    "defaultSpaceId": "시작-공간-UUID-또는-null",
    "backgroundColor": "CSS-Background-String",
    "backgroundId": "Background-ID",
    "createdBy": "User-ID",
    "createdAt": { "seconds": 0, "nanoseconds": 0 },
    "updatedAt": { "seconds": 0, "nanoseconds": 0 }
  }
}
```

---

## 3. 핵심 구성 요소 상세 명세

### 3.1. 그리드 시스템 (Grid System)

- **크기**: 기본 `rows: 28`, `cols: 50` (FHD 해상도 최적화).

- **죄표 키(Key)**: `"행-열"` 문자열 포맷 (예: `"0-0"`, `"10-25"`).

    - 행(Row): 0 ~ 27

    - 열(Col): 0 ~ 49

### 3.2. 공간 (Spaces)

공간은 맵의 바닥(Tile) 역할을 하며, 유저가 이동할 수 있는 영역을 정의합니다.

### `spaces` 배열 요소 구조

```
{
  "id": string,          // 고유 UUID (v4 권장)
  "name": string,        // 공간 이름 (예: "교실", "운동장")
  "description": string, // (선택) 설명
  "color": string,       // HEX 색상 코드
  "colorId": string,     // 컬러 팔레트 ID (아래 참조)
  "textureId": string,   // 텍스처 ID (아래 참조)
  "cellCount": number,   // 이 공간에 속한 셀의 개수
  "center": {            // 라벨이 표시될 중심 좌표
    "row": number,
    "col": number
  },
  "isPasswordProtected": boolean, // (선택) 비밀번호 잠금 여부 (기본 false)
  "password": string,             // (선택) 잠금 암호
  "isCapacityLimited": boolean,   // (선택) 정원 제한 여부 (기본 false)
  "capacity": number              // (선택) 최대 인원 (예: 30)
}
```

### `cells` 객체 구조

- **Key**: `"row-col"` 형식의 좌표 문자열

- **Value**: 해당 좌표가 속한 `spaceId` (문자열)

- **규칙**:

1. 공간은 반드시 연속된(인접한) 셀들로 구성되어야 합니다. (떨어진 셀은 별도 공간으로 분리)

2. `cells`에 정의되지 않은 좌표는 "빈 공간(Void)" 처리되어 이동할 수 없습니다 (단, `path` 오브젝트가 있으면 이동 가능).

### 유효한 컬러 팔레트 (`colorId`)

| ID | Name | Hex |
| --- | --- | --- |
| `red` | 로즈 | `#FFA6B6` |
| `orange` | 살구 | `#FFD4A9` |
| `yellow` | 크림 | `#FFE99E` |
| `lime` | 라임 | `#D7F5B1` |
| `green` | 민트 | `#A5E6BA` |
| `teal` | 아쿠아 | `#88E1D9` |
| `cyan` | 하늘 | `#A8DDF5` |
| `blue` | 소라 | `#A3C4F3` |
| `purple` | 라벤더 | `#D6BCFA` |
| `pink` | 블라썸 | `#FBCFE8` |

### 유효한 텍스처 (`textureId`)

- `none` (민무늬), `dots` (도트), `stripes-diag` (사선), `grid` (격자), `wave` (물결), `stars` (반짝)

### 3.3. 오브젝트 (Objects)

맵 위에 배치되는 사물입니다.

### `objects` 객체 구조

- **Key**: `"row-col"` 형식의 좌표 문자열 (오브젝트의 좌상단 앵커 포인트)

- **Value**: 오브젝트 타입 문자열 (`MetaGrowndObjectType`)

### `objectConfigs` 객체 구조

- **Key**: `"row-col"` (objects의 키와 동일)

- **Value**: 설정 객체

```
{
  "size": number,               // 크기 (1: 1x1, 2: 2x2, 3: 3x3)
  "message": string,            // (선택) 상호작용 시 표시 메시지
  "linkUrl": string,            // (선택) 웹 링크 (https://...)
  "youtubeUrl": string,         // (선택) 유튜브 영상 링크
  "isPasswordProtected": boolean, // (선택) 상호작용 암호화
  "password": string,           // (선택) 암호
  "backgroundColor": string     // (선택) 배경색 HEX
}
```

### 오브젝트 타입 (`MetaGrowndObjectType`) 목록

| 타입 | 설명 | 이동 가능 | 주요 용도 |
| --- | --- | --- | --- |
| `**path**` | 길/보도블럭 | ✅ **가능** | 공간과 공간을 잇는 통로. **유일하게 밟고 지나갈 수 있음.** |
| `brick` | 벽돌 | ❌ 불가 | 벽, 테두리, 장애물 |
| `flower` | 화분 | ❌ 불가 | 장식 |
| `computer` | 컴퓨터 | ❌ 불가 | 정보 검색, 링크 연결 |
| `book` | 책들 | ❌ 불가 | 학습 자료 |
| `tree` | 나무 | ❌ 불가 | 조경 (주로 2x2 이상 권장) |
| `lamp` | 가로등 | ❌ 불가 | 장식 |
| `box` | 선물상자 | ❌ 불가 | 이벤트, 보상 |
| `desk` | 책상 | ❌ 불가 | 교실 구성 |
| `chair` | 의자 | ❌ 불가 | 교실 구성 |
| `trophy` | 트로피 | ❌ 불가 | 성취 전시 |
| `rock` | 바위 | ❌ 불가 | 장애물 |

### 3.4. 배경 테마 (`backgroundColor`, `backgroundId`)

맵 전체의 배경 스타일입니다. CSS `background` 속성 값과 메타그라운드 내부 ID를 쌍으로 사용합니다.

### 프리셋

1. **기본(default)**: `#e0f7fa` 계열 그라데이션 + 구름 패턴

2. **캔디(candy)**: `#FFF5FA` 핑크 계열 + 캔디/별 패턴

3. **복숭아(peach)**: `#FFF9F5` 주황 계열 + 복숭아/잎 패턴

4. **민트(mint)**: `#F5FFFA` 민트 계열 + 잎/꽃 패턴

5. **라벤더(lavender)**: `#F5F3FF` 보라 계열 + 나비 패턴

6. **하늘(sky)**: `#F5FBFF` 파랑 계열 + 새/구름 패턴

7. **석양(sunset)**: `#FFFDF5` 노랑 계열 + 해/꽃 패턴

8. **다크(dark)**: `#1a1a2e` 남색 계열 + 달/별/건물 패턴 (야간 모드)

---

## 4. 맵 생성 시 주의사항 (AI 필독)

1. **좌표 유효성**: 모든 `"row-col"` 좌표는 `0 <= row < 28`, `0 <= col < 50` 범위를 벗어나면 안 됩니다.

2. **이동 경로 보장**:

- `brick`(벽)으로 둘러싸인 공간은 반드시 출입구(문)가 있어야 합니다.

- 출입구는 `objects`를 비워두거나, `path` 오브젝트를 배치해야 합니다.

- 서로 다른 `spaces` 사이는 `path` 오브젝트로 연결되어야 자연스럽습니다.

3. **오브젝트 겹침 방지**:

- `objects`의 키는 중복될 수 없습니다.

- `size: 2` 이상의 큰 오브젝트를 배치할 때, 그 오브젝트가 차지하는 영역(Footprint) 내의 다른 좌표에는 다른 오브젝트를 배치하면 안 됩니다.

4. **공간 ID 일치**: `cells`에 사용된 모든 `spaceId`는 `spaces` 배열에 정의되어 있어야 합니다.

---

## 5. 생성 예시 (간단한 교실)

```
{
  "version": "1.0",
  "mapData": {
    "gridSize": { "rows": 5, "cols": 5 },
    "spaces": [
      {
        "id": "room-1",
        "name": "작은 방",
        "color": "#FFD4A9",
        "colorId": "orange",
        "cellCount": 9,
        "center": { "row": 1, "col": 1 }
      }
    ],
    "cells": {
      "0-0": "room-1", "0-1": "room-1", "0-2": "room-1",
      "1-0": "room-1", "1-1": "room-1", "1-2": "room-1",
      "2-0": "room-1", "2-1": "room-1", "2-2": "room-1"
    },
    "objects": {
      "0-0": "flower",
      "1-1": "desk"
    },
    "objectConfigs": {
      "1-1": { "size": 1, "message": "공부합시다!" }
    }
    // ... 기타 필드 생략
  }
}
```

## 6. 샘플 맵 다운로드 

아래 두 파일을 다운로드 받은 다음, ChatGPT, Gemini 등에 두 파일을 업로드 하고 다음의 프롬프트를 참고하여 맵 생성을 요청하시면 됩니다. 

metagrownd_map_generation_guide.md

metagrownd-sample-map.json

**<프롬프트 예시>**

첨부한 메타그라운드 맵 생성 가이드 문서와 실제 맵 json 파일을 참고하여, 대한민국 독도 퀴즈를 8단계 공간을 활용한 퀴즈로 생성해줘. 1단계부터, 8단계까지 하나의 경로로 이어지는 공간맵을 구성하고, 각 공간 입장시에 퀴즈를 풀어야만 입장이 가능하도록 생성해줘. 가이드 문서에 표시된 오브젝트와 맵 사용법을 준수하여 맵을 생성해줘.  

생성된 맵은 json 파일로 직접 다운로드 받을 수 있도록 파일로 생성해야해.

이렇게 인공지능이 생성해준 내용을 [map.json](https://map.json) 파일 등의 이름으로 저장한 뒤 맵 에디터에서 불러오면 끝 -

**<생성된 독도 퀴즈 맵 모습>**

![Image](https://upload.cafenono.com/image/slashpageHome/20260211/192411_aqeFvRxPhmbsFKjgC5?q=80&s=1280x180&t=outside&f=webp)

For the site tree, see the [root Markdown](https://slashpage.com/grownd.md).