🕹️ 메타그라운드(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 (문자열)

•

규칙:

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

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를 쌍으로 사용합니다.

프리셋

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

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

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

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

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

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

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

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

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

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

이동 경로 보장:

•

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

•

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

•

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

오브젝트 겹침 방지:

•

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

•

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

공간 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.md7.64KB

metagrownd-sample-map.json29.25KB

<프롬프트 예시>

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

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

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

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

Made with Slashpage