Web sandbox 프로젝트

브라우저에서 돌아가는 **파우더 토이류 파티클 샌드박스** 게임. 그리드 위에 물질 파티클을 그려 낙하·확산·연소·반응·밀도 상호작용을 실험한다. 백엔드 없이 정적 파일만 Cloudflare Workers(Static Assets)로 배포한다.

> 이 문서는 프로젝트를 처음 보는 사람을 위한 **소개문서**다. 세부 구현·기능·물질 레퍼런스 등 상세 개발 기록은 저장소의 [`docs/` 폴더](https://github.com/eoeoe22/sandbox/tree/main/docs)에 분야별로 나눠 관리한다.

- 저장소: [eoeoe22/sandbox](https://github.com/eoeoe22/sandbox)
- 배포: Cloudflare Workers Builds (`main` 푸시 시 `npm run build` → `dist/` 자동 배포)
- PR 프리뷰: 열린 PR마다 `<branch>-sandbox.eoe253326.workers.dev` 프리뷰 URL이 자동 생성되어 PR 코멘트로 게시됨

## 무엇을 하는 게임인가

셀룰러 오토마타 기반 모래·물 시뮬레이터다. 팔레트에서 물질을 골라 캔버스에 그리면, 각 파티클이 중력을 따라 떨어지고 흐르고 서로 반응한다. 우선순위는 **① 재미 ② 편의성 ③ 과학적 고증** — 실험실이 아니라 장난감이다.

- 모래를 쌓고 물을 부어 젖은 모래를 만들고,
- 원유를 밀폐 용기에 넣고 아래에서 가열해 **분별증류**로 휘발유·등유·경유를 뽑고,
- 철광석을 녹여 석탄으로 환원해 **철을 제련**하고,
- 그 반대로 알루미늄 가루는 **아무 불 위에 올려놓기만 하면 녹아** 부어 굳히는 것으로 금속이 된다 — 광석도 환원도 필요 없는 값싼 주조. 대신 그렇게 뽑은 알루미늄은 **자기를 만든 불에 도로 녹는다**. 열이 닿지 않는 곳이라면 게임에서 가장 싼 **레이저 거울**이자 전선이 된다. 그리고 그렇게 지은 알루미늄 구조물은 **액체 갈륨 한 방울에 무너진다** — 갈륨이 스며든 금속이 가루로 바스러지는 실제 현상이고, 갈륨은 소모되지 않아 방울 하나가 벽을 계속 갉아먹는다(막으려면 **얼려서** 굳히면 된다),
- 가루 둘을 맞대 **폭약을 직접 제조**한다 — 알루미늄 가루에 녹가루를 섞으면 지형을 뚫고 내려가는 **테르밋**, 초석을 섞으면 아무것도 부수지 않고 눈만 멀게 하는 **섬광화약**이 된다(황·초석·석탄가루 셋을 모으면 흑색화약),
- 배터리 → 금속 배선 → 니크롬 코일로 **불 없는 전기 히터**를 만들고,
- 레이저를 **태양광 패널**에 조준해 빛으로 전기를 만들고, 옆으로 새지 않는 **전선**으로 수조·철골을 가로질러 그 전기를 먼 기계까지 보내고,
- **펌프**로 물·기름은 물론 모래까지 파이프 위로 끌어올리고(전기를 끊으면 그냥 통과시키는 구멍 뚫린 고체가 된다),
- **전자석**으로 모래 더미에서 철가루만 골라 뽑아내고, 굴러다니는 **드럼통과 연막탄까지 공중으로 끌어올려 매달아** 두고(고무공·나무 상자는 그대로 지나간다),
- 용암에 물을 부어 **흑요석**으로 급랭시켜 방폭 벽을 짓고,
- 우라늄을 뭉쳐 **원자로를 돌리다 냉각을 끊어 멜트다운**시키고,
- 화약·니트로·TNT·다이너마이트로 지형을 폭파하고,
- **성형작약**을 드래그한 방향으로 붙여 방폭 다이아몬드 벽조차 한 줄로 꿰뚫는 관통구멍을 내고,
- 그 반대편에서는 **불꽃놀이 화약**으로 지형을 한 톨도 건드리지 않은 채 색색의 자탄만 쏘아 올리고, **연막탄**을 던져 4초 뒤 터지는 연막으로 화면을 뒤덮는다 — **물속에 가라앉혀도 꺼지지 않고**, 물을 밀어내며 부글부글 끓다가 수면에서 구름으로 피어난다.
- 밭에 물을 주고 **씨앗을 뿌려** 줄기와 가지를 뻗는 식물을 키우고(다 자란 꽃봉오리가 씨앗을 떨궈 밭이 스스로 번지고, 베어내면 그루터기에서 다시 난다), 소금물 수조 바닥에는 **산호**를 심어 느린 프랙탈 가지로 퍼지는 암초를 만든다 — 물을 빼거나 민물로 바꾸거나 데우면 **백화**로 하얗게 죽는다.

100종이 넘는 물질과 온도·전기·연소·반응 시스템이 맞물려, 조합에 따라 예상치 못한 연쇄가 일어난다.

## 주요 기능 하이라이트

- **동적 화면비 샌드박스** — 캔버스가 컨트롤 UI를 뺀 화면 전체를 채우고, 고정 셀 크기로 격자 해상도를 유도한다. 창 크기가 바뀌어도 내용을 보존하며 재구성.
- **반응형 컨트롤 UI** — 데스크톱은 왼쪽 고정 사이드바, 모바일은 하단 두 줄 바. 아이콘은 Bootstrap Icons.
- **다양한 브러시** — 지우개/재료/혼합/가열/냉각/섞기/보기/전기/충격파 도구, 원·사각 모양, 휠로 크기 조절, 혼합 브러시(최대 3물질 비율 배합), 돋보기 오버레이(구성·평균 온도 관찰). **전기 브러시**는 배터리 없이 손으로 회로에 전원을 넣고, **충격파 브러시**는 브러시 영역 자체를 스피커 삼아 아무것도 부수지 않는 충격파를 터뜨린다. 사각 영역을 잡아 한 번에 적용하는 **영역 선택 모드**도 모든 도구와 함께 쓸 수 있다.
- **물질 팔레트** — 13개 카테고리 탭 + 검색 + 즐겨찾기·최근 사용 빠른접근.
- **온도·전기·중력 시스템** — 셀별 열전도, 도체별 전기 세기 감쇠, 방향·세기 조절 가능한 중력. 전기 세기는 **전류가 어디까지 가는가**만 정한다 — 선풍기·레이저·펌프·전자석·우퍼 같은 전기 장치는 어느 한 면에만 전선을 대도 **세기와 무관하게 연결된 몸체 전체가 즉시** 돈다.
- **관찰 도구** — 온도 열지도 오버레이, 격자 표시, 실시간 성능 HUD(입자 수·FPS·틱레이트).
- **씬 저장과 공유** — 진행상황은 로컬스토리지에 자동 저장·복원되고, 그와 별개로 이름·설명을 붙인 **스냅샷 슬롯**에 장면을 담아둘 수 있다. 슬롯은 `.psbx.json` 파일로 **내보내고 가져올 수 있어** 다른 기기나 다른 사람에게 씬을 통째로 넘길 수 있다. 화면비·해상도가 달라도 괜찮다 — 불러오기를 누르면 **미리보기 창**이 열려, 결과를 보면서 **자동 맞춤 / 수동(배율·위치 직접 조절) / 원본 크기** 중에서 고를 수 있다.
- **편의** — 시뮬레이션 속도 ×0.25~×4, 연기 세기 3단계, 설정 기본값 복원.

## 물질 카테고리

팔레트는 주제별 13개 카테고리로 묶인다:

🪨 고체 · 🏖️ 가루 · 💧 액체 · 💨 기체 · 🔥 불·열 · ⚒️ 제련 · 🛢️ 석유 · 💥 폭발 · ❄️ 냉각 · ⚡ 전기 · 🌱 생명 · ☢️ 방사성 · ✨ 특수

각 물질의 상세 거동과 상호작용 사슬은 [물질 도감(docs/MATERIALS.md)](https://github.com/eoeoe22/sandbox/blob/main/docs/MATERIALS.md)에 정리돼 있다.

## 플레이 가이드

- [[Web sandbox 프로젝트/가이드/원유 분별증류]] — 원유를 끓여 유분을 분리하는 정유 놀이
- [[Web sandbox 프로젝트/가이드/철광석 제련]] — 철광석을 녹이고 석탄으로 환원해 철을 뽑는 제련 공정
- [[Web sandbox 프로젝트/가이드]] — 가이드 모음

## 기술 스택 (요약)

**Astro**(정적 산출) + **TypeScript**(프레임워크 독립 엔진) + **Svelte**(컨트롤 UI 아일랜드) + **nanostores**(UI↔엔진 브리지) + **Canvas 2D**(Uint32 픽셀 버퍼) + **Cloudflare Workers Static Assets**. 엔진(Grid·Simulation)은 자족적이라 추후 Web Worker/WASM 코어로 옮겨도 물질·UI 코드는 그대로다. 상세 구조는 [docs/ARCHITECTURE.md](https://github.com/eoeoe22/sandbox/blob/main/docs/ARCHITECTURE.md) 참고.

## 상세 개발 기록

세부 기능·물리·물질·오브젝트 구현 문서는 저장소 `docs/` 폴더에 분야별로 나눠 둔다:

- [ARCHITECTURE.md](https://github.com/eoeoe22/sandbox/blob/main/docs/ARCHITECTURE.md) — 아키텍처·스택·배포
- [FEATURES.md](https://github.com/eoeoe22/sandbox/blob/main/docs/FEATURES.md) — UI·UX·편의 기능
- [PHYSICS.md](https://github.com/eoeoe22/sandbox/blob/main/docs/PHYSICS.md) — 물리·엔진 시스템
- [ELECTRICITY.md](https://github.com/eoeoe22/sandbox/blob/main/docs/ELECTRICITY.md) — 전기 계통(장치 쪽 활성화 규약)
- [MATERIALS.md](https://github.com/eoeoe22/sandbox/blob/main/docs/MATERIALS.md) — 물질 도감
- [MATERIAL-SYSTEMS.md](https://github.com/eoeoe22/sandbox/blob/main/docs/MATERIAL-SYSTEMS.md) — 물질군·시스템 노트
- [OBJECTS.md](https://github.com/eoeoe22/sandbox/blob/main/docs/OBJECTS.md) — 독립 오브젝트 시스템
- [SNAPSHOTS.md](https://github.com/eoeoe22/sandbox/blob/main/docs/SNAPSHOTS.md) — 스냅샷 슬롯·파일 포맷·화면 맞춤

아직 구현하지 않은 확장 아이디어(신규 물질·오브젝트·산업 공정 후보)는 하위 문서 [[Web sandbox 프로젝트/구상]] 참고.