1. 시작하기
로그인 후 프로젝트를 열고, 왼쪽 패널에서 타일 또는 에셋을 선택해 작업합니다.
온라인 N명, 편집 모드, 로그인 사용자 상태를 확인합니다. 온라인 인원에 마우스를 올리면 접속 중인 사용자 목록을 볼 수 있습니다.
세션이 유효하면 GitHub 프로젝트 목록의 첫 번째 프로젝트를 자동으로 불러옵니다. 프로젝트 데이터와 동기화 기준 적용이 끝날 때까지 화면 전체가 잠기며 완료 후 조작할 수 있습니다.
2. 프로젝트
빈 프로젝트를 생성합니다.
GitHub의 다른 프로젝트 또는 컴퓨터의 JSON 프로젝트를 불러올 수 있습니다. GitHub 프로젝트는 meta → 타일 → 에셋 → 맵 → 맵 에셋 배치 순으로 리소스를 하나씩 받아 순간 요청 병목을 줄입니다. 모든 데이터 적용이 끝날 때까지 저장·편집·단축키·캔버스 조작을 잠급니다.
덮어쓰기 또는 다른 이름으로 저장을 선택할 수 있습니다.
PNG, Unity용 데이터 등 외부 사용을 위한 결과물을 생성합니다.
3. 타일과 레이어
타일은 목적에 따라 그룹으로 나뉘며, 좌측 패널에서 관리합니다.
| 구분 | 용도 |
|---|---|
| 오브젝트 타일 | 기본 타일 위에 올라가는 오버레이 계층. 기본 타일이 없는 칸에는 배치하지 않습니다. |
| 기본 타일 | 맵의 주된 바닥/벽 타일 계층입니다. |
| 심층 타일 | 기본 타일 아래쪽의 깊이 표현용 계층입니다. |
| 최하단 바닥 | 맵 최하층 배경/바닥 계층입니다. |
텍스처 유형
주변 타일과 연결 규칙 없이 독립적으로 표시됩니다.
같은 타일이 인접한 방향에 맞춰 연결 상태를 표시합니다.
다른 타일이 존재하는 방향만 연결 텍스처를 적용합니다. 같은 타일이 있는 방향에는 생성하지 않습니다.
연결 텍스처 적용 범위는 우측 설정에서 접기/펼치기로 조절합니다.
4. 픽셀 편집
타일 또는 에셋의 텍스처를 직접 수정합니다.
펜, 지우개, 채우기, 직사각형 채우기, 올가미, 디더링 등.
펜 크기, 불투명도, 정사각/원형 브러시 형태를 조절합니다.
색상환, HSV, HEX 등으로 색상을 지정합니다.
타일 레이어의 색조/채도/명도 등을 조절할 수 있습니다.
5. 맵 에디터
선택한 타일을 맵에 배치하고, 선택/채우기/삭제/이동 등의 작업을 수행합니다.
타일을 선택한 뒤 맵을 클릭하거나 드래그하여 배치합니다.
사각 선택, 올가미, 영역 채우기 등으로 범위를 편집합니다.
휠로 커서 기준 확대/축소, 휠클릭 드래그로 화면 이동.
높이/등고선과 타일의 입체 배치를 확인합니다.
맵 타일 배치는 맵 단위 Lock을 사용합니다. 누군가 같은 맵의 타일 배치를 작업 중이면 다른 사용자는 그 맵에서 타일을 배치하거나 제거할 수 없습니다.
6. 에셋
에셋은 타일 크기와 독립적인 자유 크기 이미지 리소스입니다.
에셋 생성/편집
원하는 폭×높이로 새 에셋을 만듭니다.
PNG/JPEG/WebP 이미지를 여러 개 동시에 선택해 원본 캔버스 크기로 에셋을 생성합니다. 같은 이름이 이미 있으면 기존/새 썸네일을 비교해 전체 또는 선택 덮어쓰기를 할 수 있습니다. 캔버스 크기가 같으면 텍스처를 교체하고, 크기가 다르면 해당 항목을 선택할 수 있으며 픽셀 크기가 다르기에 삭제 후 재생성됩니다 경고를 표시합니다. 재생성 시 기존 배치 좌표와 앵커는 그대로 유지됩니다.
래스터 레이어, 폴더, 표시/숨김, 이름 변경, 복제/삭제, 순서 이동을 지원합니다.
불투명도, Multiply/Screen/Overlay/발광 계열, 클리핑, 투명 픽셀 잠금 등을 사용할 수 있습니다.
에셋 배치
- 새 에셋 배치는 클릭한 위치를 에셋 하단 중앙(bottom-center) 기준점으로 사용합니다.
- 이미 배치된 에셋의 조작 판정은 캔버스 전체가 아니라 실제 불투명 픽셀(alpha > 0)에서만 발생합니다. 투명 여백은 선택되지 않습니다.
- 배치된 에셋 위에서 휠클릭 + 드래그하면 위치를 이동할 수 있습니다.
- 에셋 관리 영역에 현재 맵의 배치 개수를 표시합니다.
- 배치한 에셋 삭제는 해당 에셋의 현재 맵 배치 인스턴스를 즉시 제거하며 확인창 없이 실행됩니다.
- 원본 에셋 삭제는 확인창을 표시합니다.
- 에셋 캔버스 크기는 에셋 레이어 패널에서 폭×높이를 수치로 변경합니다. 기존 픽셀 크기는 유지하고 캔버스 영역만 중앙 기준으로 늘리거나 줄입니다.
7. 온라인 협업
텍스처 편집과 맵 배치는 서로 다른 잠금 규칙을 사용합니다.
| 작업 | 동시 작업 규칙 |
|---|---|
| 타일 텍스처 | 타일별 독립 Lock. A가 타일 1을 수정 중이어도 B는 타일 2를 수정할 수 있습니다. |
| 에셋 텍스처 | 에셋별 독립 Lock. 서로 다른 에셋은 동시에 편집 가능합니다. |
| 맵 타일 배치 | 맵 전체 Lock. 한 사용자가 맵 배치를 시작하면 다른 사용자는 같은 맵의 타일 배치를 할 수 없습니다. |
| 에셋 배치 | 독점 Lock 없음. 배치/제거/이동 시 최신 서버 상태를 읽고 operation 단위로 병합합니다. |
다른 사용자의 저장 때문에 내가 작업 중인 다른 타일/에셋 텍스처가 초기화되지 않도록 변경된 리소스만 부분 갱신합니다.
8. 내보내기
내보내기 창의 미리보기와 출력 규격을 기준으로 PNG, PSD, Aseprite, Unity, JSON을 생성합니다. 픽셀 배율을 바꾸면 최종 출력 해상도가 즉시 표시됩니다.
등고선 높이 기준 레이어 분리를 켜면 Ground_Deep + Terrain_* + Side 구조로 출력합니다. Terrain_*에는 각 높이의 TOP·그림자만 들어가고, Side에는 에디터의 최종 가림 판정을 통과해 실제로 보이는 모든 옆면만 통합됩니다. 가려진 옆면은 출력하지 않습니다.
미리보기에서 보이는 결과 그대로 PNG 한 장을 출력합니다. 레이어별로는 제외 여부만 지정하며, 배치한 에셋 포함과 등고선 텍스처 적용도 미리보기와 실제 PNG에 동일하게 반영됩니다.
내보내기에서 지정한 출력 그룹을 기준으로 맵 레이어를 분리합니다. 에셋 원본은 맵 레이어와 별도 리소스로 취급합니다.
선택한 출력 그룹을 레이어로 구성한 .aseprite 파일을 생성합니다. v_beta1.51부터 Layer/Cel Chunk 길이와 바이너리 구조를 수정한 Writer를 사용합니다.
Pixel Map Maker 프로젝트 데이터를 JSON으로 내보냅니다.
Unity · Prefab 패키지
- 각 출력 그룹은 동일한 전체 맵 Canvas를 사용하며 Static과 필요한 경우 Animated 자식으로 구성됩니다.
- Order in Layer는
Ground_Deep=-1,Terrain_0=1000,Terrain_1=2000... 순으로 올라가며,Side는 모든 Terrain 위,Assets는 Side보다 한 단계 위에 생성됩니다. 같은 지형 그룹의 Static/Animated는 동일한 Order를 사용합니다. - 애니메이션 타일은 프레임별 PNG 여러 장이 아니라 한 장의 Sprite Sheet로 출력되고, Unity Importer가
Sprite Mode: Multiple로 자동 분할합니다. - Pixel Map Maker의 60 logical FPS와 각 타일의 frame hold를 기준으로 AnimationClip 키 시간을 생성하고 Loop/자동 재생을 설정합니다.
- 같은 맵 그룹의 서로 다른 애니메이션 속도는 하나의 공통 타임라인으로 베이크되어 Map Prefab을 씬에 놓으면 즉시 같은 속도로 재생됩니다.
- 에셋은 원본 Texture와 Prefab을 공유하고 맵 내부에는 Prefab Instance로 배치합니다. 같은 에셋이 여러 개면 이름별 그룹으로 묶습니다.
- 에셋은 맵에디터에서 등고선 상승까지 적용되어 실제로 보이는 최종 Y 위치로 배치됩니다.
contourHeight는 메타데이터로 유지하고 Transform Z에는 다시 더하지 않습니다. - 에셋 인스턴스의 등고선 색보정은 Unity 6 URP 호환
PixelMapMaker/PixelHSVSprite와 MaterialPropertyBlock으로 적용합니다. 에디터의 Hue / Saturation / Value 보정값을 인스턴스별로 전달하므로 Texture를 복제하지 않습니다. - 기존 프로젝트에서 핑크색 때문에 Material Shader를 기본 Sprite 셰이더로 바꿨더라도 새 패키지를 덮어쓴 뒤
Tools → Pixel Map Maker → Create Prefabs를 실행하면 PixelMapMaker 전용 셰이더로 다시 연결합니다. - Point Filter, No Mipmap, Uncompressed 설정을 사용해 픽셀 경계를 유지합니다.
Unity · PNG 폴더
Prefab을 만들지 않고, 사용자가 지정한 출력 그룹별 합성 PNG + 등록된 모든 에셋 PNG를 폴더 구조로 출력합니다.
- 같은 출력 그룹 이름을 가진 맵 레이어는 한 PNG로 합성합니다.
Tiles_A,Foreground처럼 직접 입력한 그룹명도 그대로 파일명으로 사용합니다.- 각 맵 그룹 PNG는 동일한 전체 맵 Canvas 크기를 유지합니다.
Assets/에는 현재 맵에 배치했는지와 관계없이 등록된 모든 에셋을 출력합니다.- 에셋의 배치 스케일은 출력 이미지 크기에 영향을 주지 않습니다. 내보내기 픽셀 배율은 맵과 에셋 모두에 적용됩니다.
PNG 단일 출력과 Unity의 PNG 폴더 출력은 서로 다른 기능입니다. PNG 단일 출력은 미리보기 결과 한 장, Unity PNG 폴더는 출력 그룹별 맵 PNG와 Assets 리소스 세트입니다.
9. 단축키 / 마우스 조작
| 조작 | 기능 |
|---|---|
| Ctrl + Z | 직전에 프로젝트 데이터를 변경한 작업을 되돌립니다. 그림, 배치, 삭제, 이동, 레이어/설정/수치 변경 등에 적용됩니다. |
| Ctrl + Y | Ctrl+Z로 되돌린 프로젝트 변경을 다시 실행합니다. |
| Ctrl + S | 현재 GitHub 프로젝트를 덮어쓰기 저장합니다. 저장 직전 상태는 자동 백업됩니다. |
| Q / W / E / R / A / S | 픽셀 편집 도구를 각각 펜 / 디더링 / 지우개 / 채우기 / 올가미 / 직사각형 채우기로 전환합니다. 입력칸에 타이핑 중일 때는 실행되지 않습니다. |
| Esc | 열려 있는 사용 설명서 패널을 닫습니다. |
| 마우스 휠 | 맵/프리뷰 확대·축소 |
| 휠클릭 + 드래그 | 일반 영역: 화면 이동 / 배치 에셋 위: 해당 에셋 이동 |
| 좌클릭 | 현재 선택 도구 실행 또는 타일/에셋 배치 |
| 우클릭 | 도구별 제거/반대 동작 |
10. 저장 백업 정책
GitHub 덮어쓰기 저장 전에 이전 프로젝트 상태를 자동 백업하는 안전장치입니다.
각 백업은 최대 48시간 유지합니다. 시간이 지났다고 즉시 삭제하는 것이 아니라 다음 저장 시 정리합니다.
프로젝트당 최대 20개. 초과하면 생성 시각이 가장 오래된 백업부터 제거합니다.
각 프로젝트의 백업은 서로 영향을 주지 않도록 별도 관리합니다.
백업 생성에 실패하면 원본 프로젝트를 먼저 덮어쓰지 않도록 합니다.
프로젝트 선택 → 백업/복구에서 저장 전 Snapshot 목록을 확인하고 원하는 시점을 작업 화면으로 불러올 수 있습니다. 불러온 직후에는 GitHub 원본을 바꾸지 않으며, 확인 후 저장하기 → 덮어쓰기를 실행해야 실제 복원이 완료됩니다.
에셋 삭제·동일 이름 덮어쓰기·크기 불일치 재생성은 먼저 작업 화면에만 임시 반영됩니다. GitHub의 기존 에셋 파일은 저장하기 전까지 변경되지 않습니다. 저장 시 기존 원격 상태를 백업한 뒤에 새 에셋 저장·배치 갱신·기존 에셋 삭제를 순서대로 커밋합니다.
GitHub의 tiles, maps, assets 실제 파일과 meta.json 목록을 비교합니다. 파일은 남아 있지만 목록에서 빠진 항목만 뒤에 다시 등록하며, 참조만 남은 누락 항목이나 파일은 자동 삭제하지 않습니다.
현재 Snapshot 백업은 meta.json에 등록된 타일·맵·에셋만 포함합니다. 이미 삭제했거나 meta에서 제외된 고아 파일은 자동으로 백업에 다시 넣지 않습니다. 고아 파일을 되살리고 싶을 때만 미등록 데이터 복구를 사용합니다.
공통 텍스처 레이어 · 선택 변형 · 저장 상태
에셋뿐 아니라 타일과 최하단 바닥의 각 텍스처도 레이어/폴더/불투명도/블렌딩/클리핑/알파 잠금을 사용할 수 있습니다. 영역선택(직사각형/올가미) 후 선택 내부를 드래그하면 이동합니다. Shift를 누르면 직사각형 변형 박스와 8개 핸들이 나타나며, 핸들을 좌클릭 드래그하면 확대·축소하고 영역 밖을 좌클릭 드래그하면 중심 기준으로 회전합니다. 선택 가장자리 우클릭 회전도 그대로 사용할 수 있습니다. 모든 변형은 픽셀아트가 흐려지지 않도록 Nearest Neighbor 방식으로 처리되며 한 번의 드래그가 한 번의 실행 취소 기록이 됩니다.
패널 구조 1·3·4는 맵 에디터와 2D/3D 맵 렌더링을 완전히 끄고 타일 편집 패널만 넓게 표시합니다. 1·2·3·4로 돌아오면 현재 타일 상태로 맵을 한 번 다시 렌더링합니다.
저장 중에는 상단 상태가 저장 중…으로 표시되며 진행 표시가 나타납니다. 실제 서버 저장이 끝난 뒤에만 저장됨과 저장되었습니다. 알림이 표시됩니다. 저장 도중 추가 수정이 발생하면 해당 수정은 저장되지 않은 상태로 유지됩니다.
11. 모바일·태블릿
Android 스마트폰과 Galaxy Tab 계열을 포함한 터치 기기에서는 화면 폭뿐 아니라 터치 포인터와 화면 방향을 함께 고려해 UI를 재배치합니다.
- 휴대폰 세로/가로, 태블릿 세로/가로에 대응합니다.
- 좁은 화면에서 컨트롤을 잘라내지 않고 패널을 재배치하며, 내용이 많으면 해당 패널 내부에서 세로 스크롤합니다.
- 터치 버튼과 슬라이더의 조작 영역을 확보하고 캔버스의 탭/드래그/롱프레스 판정을 터치 환경에 맞춥니다.
- 모달과 내보내기 창은 동적 화면 높이와 Safe Area를 고려합니다.
- PC의 마우스 조작과 데스크톱 레이아웃은 별도 경로를 유지합니다.
12. 현재 버전 핵심 상태 v5.26
현재 GitHub 프로젝트는 Ctrl+S/덮어쓰기로 저장하며, 다른 이름으로 저장은 사용자가 해당 메뉴를 직접 선택했을 때만 실행합니다. 덮어쓰기 전 JSON Snapshot 백업을 생성합니다.
GitHub 프로젝트는 meta와 개별 리소스를 순서대로 하나씩 요청합니다. 전체 로딩과 데이터 적용이 끝날 때까지 입력을 잠가 대량 병렬 요청으로 인한 실패와 중간 조작을 방지합니다.
자기 기기의 배치 조작은 로컬에서 즉시 반영하고 서버 동기화는 짧게 묶어 전송하여 원격 기기 지연이 로컬 조작감을 막지 않도록 합니다.
지형 높이별 Terrain_* 레이어는 TOP·그림자만 포함하고, 실제 화면에서 보이는 옆면은 높이에 관계없이 하나의 Side 레이어로 통합합니다. 지형 TOP에 가려진 옆면은 Side에서 제외됩니다.
좌·우·상·하의 다른 타일 접촉을 같은 규칙으로 합성합니다. 그림자 표시를 끄면 관련 렌더 계산도 함께 중지되며, 타일을 드래그 배치하는 동안 그림자는 손을 놓을 때 한 번만 최종 계산합니다.
직사각형/올가미 선택이 있으면 펜·지우개·채우기·디더링·도형 채우기 등 픽셀 수정은 선택 영역 안에서만 적용됩니다. 선택 도구로 드래그하지 않고 단순 클릭하면 선택이 해제됩니다. 선택 영역 이동·회전·크기 변형은 Undo/Redo 시 선택 마스크도 함께 복원됩니다. Ctrl+C / Ctrl+V는 현재 픽셀 레이어를 복사해 활성 레이어 바로 위에 새 레이어로 붙여넣습니다.