web-city
SimCity 4 Rush Hour를 재현한 도시 시뮬레이션 엔진과 웹 뷰어입니다. RCI 수요와 개발, 예산·세금·대출,
전력·수도·쓰레기, 교육·보건, 범죄·소방, 시장 평점과 조례, 교통, 보상·사업 거래·랜드마크, 재해,
이웃 도시와 지역, 지형·나무를 원작의 공식과 수치대로 구현했습니다. 원작 수치를 알 수 없는 값은 따로 분리해
근거를 적었습니다(아래 "직접 정한 값").
- 엔진 (
packages/engine, 패키지 @web-city/engine): 순수 TypeScript로 작성했고 DOM이나 Node.js 전용 API를 쓰지 않습니다.
그래서 브라우저, Cloudflare Workers, Node에서 똑같이 돌아갑니다.
- 뷰어 (
apps/web, 패키지 @web-city/web): 엔진의 공개 API(@web-city/engine)만 씁니다. Canvas 2D 탑다운 맵과 도구 막대, RCI 수요, 조언자, 여론 조사, 세율·예산·대출·부서 예산, 조례,
이웃·지역, 기록·교통량 그래프, 여러 오버레이(쾌적도, 땅값, 오염, 교통 혼잡과 통근, 지하철, 전력·수도, 송전선·수도관·철로 노후도, 치안·소방, 교육·보건,
시장 평점 등), 경로 조회, 끌고 다니는 재해로 구성됩니다. (엔진의 My Sims·U-Drive-It 운전과 바람은 당분간 웹 화면에 두지 않습니다.)
- Worker 예제 (
examples/worker): 엔진을 Cloudflare Worker에서 실행합니다.
뷰어는 main에 커밋할 때마다 CI 검사를 통과하면 GitHub Pages에 배포됩니다: https://hyunjunian.github.io/web-city/
처음이라면 "시작하기"의 예시 도시 둘러보기(또는 새 도시 → 예시 도시)로 길·구역·공공시설을 갖춘 인구 2만여 명의 도시부터 볼 수 있습니다(엔진의 sampleCity()).
구조
packages/engine @web-city/engine — 시뮬레이션 엔진 (src, test, scripts, docs)
apps/web @web-city/web — 웹 뷰어 (엔진 공개 API만 사용)
examples/worker Cloudflare Worker 예제 (엔진 공개 API만 사용)
뷰어(apps/web/src)는 모듈별로 나뉘어 있습니다: main(프레임 루프·부팅), state(열린 도시·카메라·선택),
render(캔버스 지도), views(지도 보기의 칸별 값·개발 막힘 색·서비스 반경), input(지도 조작·미리 보기), tools(도구 메뉴·도구 카드·찾기)·controls(속도·이달의 테두리·지도 보기·위 버튼 맞추기·세율·도움말)·menu·tabs(카드·시트·패널 열고 닫기)·back(휴대폰의 뒤로 가기),
goals·readings·manage(도시 상태와 분야별 관리 화면), panels·info·reports·graphs·mysims·region·udi·onboarding·journal(인구 화면과 카드 내용·시작하기·소식), minimap·toast·choices(저장 안 한 진행을 셀 선택 횟수)·saves·storage·theme·live, icons(선 아이콘, lucide)·widgets(터치식 슬라이더),
names·messages(한국어 이름·엔진 메시지 번역), util(의존성 없는 도우미). 엔진 상태는 읽기만 하고, 바꾸는 일은 모두 City 메서드로 합니다.
npm 워크스페이스라서 루트에서 npm install 한 번이면 됩니다. 엔진은 TypeScript 소스를 그대로 내보내므로
뷰어·Worker·테스트가 따로 빌드하지 않고 씁니다.
실행
npm install
npm run dev # 뷰어 개발 서버 (http://localhost:5173)
npm test # 단위 테스트
npm run typecheck # 엔진(ES2022 전용), 뷰어, Worker 타입 검사
npm run build # 뷰어 정적 빌드 → apps/web/dist/
npm run build:engine # 엔진 단일 ES 모듈 → packages/engine/dist/engine.js
npm run smoke -- 10 128 # 헤드리스로 10년 시뮬레이션 (맵 128×128)
npm run fuzz -- 20 64 1 # 무작위 도구·재해·거래 20년, 매달 불변식과 저장/불러오기 검사
npm run smoke -- 5 256 -q -spikes # 하루 평균 계산 시간과 가장 느린 날(월말) 측정
npm run benchmark -- 256 9 # 같은 밀도 도시의 조회·시설 조정·월 진행 중간값과 p90(ms)
npm run docs # City 메서드 목록 packages/engine/docs/API.md 다시 만들기
벤치마크의 searchBuffers는 재사용하는 경로 탐색 배열의 실제 할당 수와 바이트를 셉니다.
가중치가 없는 탐색은 비용과 이동 시간이 같은 배열을 공유하고, 교통수단 선호 가중치가 있는
탐색만 시간을 별도 저장합니다. 같은 저장 공간은 한 번만 집계합니다.
slicedMonth는 분할 실행한 한 달의 시간과 처리 조각의 95백분위·최대 시간을 보고하며,
동기 실행과 저장 결과가 같은지도 확인합니다.
Worker 예제:
cd examples/worker
npx wrangler dev
curl "http://localhost:8787/simulate?years=5&size=64&seed=1&difficulty=easy"
# 저장 JSON을 보내서 진행하거나 재해를 일으킬 수도 있습니다.
curl -X POST --data-binary @save.json "http://localhost:8787/step?days=30"
curl -X POST --data-binary @save.json "http://localhost:8787/disaster?kind=meteor&x=20&y=16&intensity=1"
# 도구 호출을 묶어 보내고(허용된 City 메서드만) 며칠 진행한 뒤 결과와 새 저장을 받습니다.
curl -X POST "http://localhost:8787/act" -H 'content-type: application/json' -d '{
"city": { "size": 48, "difficulty": "easy" },
"actions": [
{ "op": "buildNetwork", "args": [0, 20, 47, 20, "road"] },
{ "op": "zone", "args": [1, 12, 46, 19, "R-low"] },
{ "op": "placeStructure", "args": ["gasPlant", 1, 22] }
],
"days": 360 }'
# 이름 붙은 도시를 Durable Object에 두면 알람이 1분마다 한 달씩 진행합니다(TICK_SECONDS로 조절).
curl -X POST "http://localhost:8787/city/demo" -H 'content-type: application/json' -d '{ "size": 64 }'
curl -X POST "http://localhost:8787/city/demo/act" -H 'content-type: application/json' -d '{ "actions": [{ "op": "zone", "args": [1, 1, 10, 10, "R-low"] }] }'
curl "http://localhost:8787/city/demo" # 지금 상태 (pause / resume 으로 시계 멈춤·재개)
시뮬레이션 비용은 하루에 64×64 약 1.6ms, 128×128 약 3ms, 256×256 약 9ms(월말 최대 약 70ms)입니다.
뷰어 사용법
키보드로는 Tab의 첫 자리가 지도로 건너뛰기(지도에 초점이 가고, 화면 읽기 프로그램은 지도의 키 안내를 읽음)이고, 속도 네 버튼은 한 번의 Tab으로 들어가 방향키로 고르며, 시간을 멈춘 알림(불·정전 등)은 화면 읽기 프로그램이 바로 읽습니다. 단축키: Space 멈춤·이어 하기, +/− 확대·축소, Home 전체 보기, [ ] 열린 관리 화면의 이전·다음 탭(지도 보기가 함께 바뀜), G 인구 화면(지도에 개발 막힘), ? 도움말, 0–3 속도, N 낮·밤, Q 조회, X 철거, R 도로, T 골목, V 대로, H 고속도로, Z 주거, C 상업, I 산업, L 송전선, P 수도관, S 커서를 추천 자리로(건설 도구를 든 채 방향키로 커서를 옮기고 Enter로 짓기), 화살표 이동, Esc 그리던 것 취소 → 카드 닫기 → 조회 도구.
게임은 6개월마다와 탭을 떠날 때 브라우저에 자동 저장되고, 다시 열면 이어서 시작합니다(처음부터는 새 도시: 크기·시드·강·높이 지도를 바꾸면 옆의 지형 미리보기가 바로 바뀌고, 다른 지형으로 마음에 드는 지도를 고를 수 있습니다).
메뉴(⋯) → 저장은 도시 이름별로 따로 저장하고(같은 이름은 덮어씀), **불러오기…**는 저장된 도시 목록(인구·게임 날짜·저장 시각)에서 열거나 지웁니다.
파일로 내보내기·가져오기도 됩니다. 화면 테마는 메뉴(⋯) → 테마에서 시스템 설정·밝게·어둡게로 바꿉니다.
以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗
