LLM Wiki

night-street — Golden Hour 도시 거리를 외부 에셋 없이 프로시저럴 렌더링하는 Three.js 웹앱

Properties3
descriptionStarKnightt/night-street의 zero-external-asset 접근법, 5개 AI 프롬프트로 구축된 절차, 8-system sequential build, blind critic loop, GitHub 고정 커밋 기준 분석.
tagsthreejs, react-three-fiber, procedural-generation, webgl, graphics, 3d-rendering, nextjs, typescript, agent-skills, ai-coding
aliasesnight-street, 나이트 스트리트, procedural city street

10 min read

StarKnightt/night-street는 브라우저에서 골든아워(Golden Hour)의 도시 거리를 첫인칭으로 걸을 수 있는 Three.js + React Three Fiber 웹앱이다. 외부 에셋이 전혀 없다 — 모든 텍스처, 메시, 조명, 사운드가 코드로 생성된다. AI coding agent에게 5개의 프롬프트를 주고 sequential build + blind visual critic loop로 구축되었다.

저장소 구성

고정 커밋의 recursive tree는 총 265 entries, truncated: false. 전용 tests/ 경로는 확인되지 않았다.

night-street/
├── README.md              # 프로젝트 개요, 한계점, Stack, Debug API
├── PROMPTS.md             # 빌드에 사용된 5개 프롬프트 원문 (verbatim)
├── AGENTS.md              # Next.js 16 agent 규칙 파일
├── CLAUDE.md              # @AGENTS.md (symlink)
├── NOTES.md               # Deferred work, post-mortems, technique brief
├── LICENSE                # MIT License
├── package.json           # Next.js 16, React 19, Three.js 0.185, R3F 9
├── next.config.ts         # Next.js 설정
├── tsconfig.json          # TypeScript 설정
├── postcss.config.mjs     # PostCSS 설정
├── src/                   # 소스 코드
│   ├── city/              # 도시 구조 (road, buildings, cars, signs, lamps)
│   ├── scene/             # 씬 (camera, collisions, clouds, dust, tone, grade)
│   ├── world/             # 월드 데이터 (street layout, car positions, sign data)
│   ├── audio/             # Web Audio 합성 DSP (oscillators, IR, engine, design)
│   └── NightStreet.tsx    # Canvas, renderer, tone mapping setup
├── tools/                 # Harness & instruments (capture, audio, route, signcount)
├── public/                # 정적 에셋
├── media/                 # 스크린샷 이미지
└── docs/
    ├── TECHNIQUE.md       # Lighting, atmosphere, post-processing brief
    └── COLDSTART.md       # 로드 과정과 해결되지 않은 모순

전체 소스는 위키에 중복 저장하지 않고, fixed commit URL과 선별 파일 해시를 raw source: github-starknightt-night-street에 기록했다.

핵심 설계 철학: Zero-Asset Rule

README가 강조하는 핵심 제약은 “외부 에셋 금지”다. 이 규칙의 진짜 가치는 파일 크기 절약이 아니라 모든 결정이 코드에 의해 정당화되어야 한다는 점에 있다. 다운로드한 텍스처는 “이유 없이 그냥 그렇게 보이는” 사실(fact)이지만, 프로시저럴 텍스처의 모든 파라미터는 실제 측정값, 광도 측정 목표, 톤 커브를 통해 역산된 수치에 대해 정당화되어야 한다.

저장소는 “아트 덩어리”라기보다 “논증의 집합” 이며, 대부분의 논증은 코드 자체에 주석으로 기록되어 있다. 주석은 코드가 무엇을 하는지 설명하는 문서가 아니라, 무엇을 시도했고, 어떻게 측정했으며, 왜 롤백했는지에 대한 기록이다.

AI Agent 빌드 방법론

이 프로젝트는 5개의 프롬프트로 구축되었으며 PROMPTS.md에 원문 그대로 보존되어 있다:

  1. 최초 브리프 (8/10 1:09PM): 8개 시스템을 순차적으로 구축하고 각 단계마다 blind visual critic sub-agent가 렌더링 결과를 실사 사진과 비교. 야간 도시 거리 요청.
  2. 시간대 변경 (8/11 12:50PM): “make it golden hour” — 프로젝트 전체 방향을 골든아워로 변경. “80% of the code in this repository is now dead.”
  3. 첫 번째 아트 패스 (8/12 1:05AM): “saturation is too even… shadows go a little cooler” — 톤·대기·채도 상세 지시.
  4. 두 번째 아트 패스 (8/12 1:38PM): 거리 간판, 램프 광도, 간판 중복 검사 도구 요청.
  5. 자동차 패스 (8/12 6:20PM): “car is the weakest part” — 자동차 재질·윈도우·휠·바디 라인·지면 접촉 집중 디테일 패스.

빌드 방법의 핵심:

  • Sequential build: 8개 시스템을 순서대로 구축. 병렬 sub-agent는 후반에 부분적으로 허용.
  • Blind critic loop: 각 시스템 완료 후, 소스 코드를 보지 않고 렌더링 결과만 보는 sub-agent가 실사 사진과 비교. 렌더로 읽히면 다시 보냄.
  • 이전 프로젝트(jungle-trail)와 달리 점수 원장(score ledger)은 기록되지 않음.

Critique가 찾아낸 버그들

  • 자동차 지면 접촉 decal이 보이지 않았음 — 쿼드가 역방향으로 감겨 back-face cull됨
  • 오디오 시스템 전체가 무음 — ConvolverNode sample-rate mismatch (IR 24kHz vs context 48kHz), 1주일간 발견되지 않음
  • 2,200개의 먼지 입자가 카메라 뒤 32m에 위치 — capture 환경에서 interactive walk와 달랐음
  • 태양 shadow box가 stale capture에서 stale 상태 — still capture에 그림자가 전혀 없었음

Stack

계층기술
FrameworkNext.js 16
UIReact 19
3DThree.js 0.185.1 + React Three Fiber 9.7.0 + Drei 10.7.8
스타일Tailwind CSS 4
언어TypeScript
캡처 하네스Playwright 1.62.1
인코딩ffmpeg
에셋없음 (모든 텍스처·메시·조명·사운드 코드 생성)
배포Vercel

What Is Not Good Enough Yet

README에 기록된 현재 한계점:

  • Shadow filter artifact: shadow map filter가 특정 각도에서 밴딩 패턴 생성
  • Window illumination uniformity: 모든 창문 조명이 너무 균일함
  • Car material realism: 페인트 재질의 clearcoat 반사가 부족함
  • Vegetation 없음: 나무·화분·잡초 없음
  • Pedestrian 없음: 사람이 없어 거리가 정적임
  • Atmospheric perspective: 원거리 대기 원근법 불완전
  • Bloom stability: 특정 조명 조건에서 bloom 불안정

Debug API

개발 모드에서 window.__scene을 통해 렌더러 원격 제어 가능 (production 비활성화):

호출기능
goTo(t)거리 따라 순간이동, t in 0..1
setYaw(rad) / setPitch(rad)절대 heading/pitch
warp(seconds)스프링·정착 시간 단축
setDriven(bool)프레임 루프를 wall clock에서 분리
step(dt)useFrame을 dt만큼 진행 후 렌더
renderOnce()animation frame 없이 상태 적용 후 렌더
info(){ calls, triangles, programs, textures }
probe()luminance histogram + percentiles
fps현재 측정 프레임 레이트
walker보행자 gait phase와 속도

window.__sunFollow는 shadow box의 stale 여부와 drift 분포를 보고한다.

공식 확인·해석·미검증 범위

고정 커밋에서 직접 확인한 것

  • README, PROMPTS.md, package.json, AGENTS.md, CLAUDE.md, LICENSE, NOTES.md SHA-256
  • 프로젝트 구조와 디렉터리 레이아웃
  • 5개 프롬프트 원문 및 빌드 방법론
  • Zero-asset rule 설계 철학과 구현 방식
  • Debug API 명세
  • AI agent skill 사용 기록 (AGENTS.md / CLAUDE.md)

저장소가 주장하지만 재현하지 않은 것

  • 실제 렌더링 품질과 실사 수준 근접성
  • RTX 4060 첫 프레임 34.9–39.4초 부팅 시간
  • Playwright 캡처 하네스와 npm run shoot 결과
  • 오디오 시스템 Web Audio DSP 구현
  • Vercel 배포 및 실제 웹 페이지 동작
  • window.__scene Debug API 기능

이번 ingest에서 하지 않은 것

  • npm install 및 로컬 개발 서버 실행
  • npm run dev로 브라우저에서 거리 체험
  • npm run shoot / npm run reel 캡처 실행
  • Playwright headless QA
  • Vercel 배포 링크 방문 및 벤치마크 측정
  • 빌드(npm run build) 실행

관련 메모

  • 정식 raw provenance: raw source: github-starknightt-night-street
  • AI coding / agent skill 관점: moc-ai-coding
  • 3D 그래픽스 / 멀티미디어 관점: moc-multimedia
  • 이전 유사 프로젝트: jungle-trail

한눈에 보기

  • 프로젝트 성격: Procedural 3D cityscape renderer, zero external assets, browser-based first-person walkthrough.
  • 주 결과물: 골든아워 도시 거리 실시간 렌더링. Vercel 배포 — https://night-street.vercel.app
  • 고정 기준: master의 333f064778105640588a95d2c2d150780044e7bf (notes: the frame-rate-calibrated term, and X3595 on the shadow filter, 2026-08-13).
  • 메타데이터 스냅샷: TypeScript 저장소, 69 stars, 13 forks, 0 open issues, 라이선스 MIT. 수치는 2026-08-15 KST 스냅샷이다.
  • 라이선스: MIT License (Copyright (c) 2026 Prasenjit / StarKnightt).
  • 구현 핵심: 모든 에셋을 코드로 생성. GLSL로 아스팔트 텍스처 생성, massing solver로 빌딩 생성, analytic dome + 3개 procedural cloud deck, Web Audio graph로 오프라인 렌더링.
  • 검증 상태: source inspection과 정적 해시 검증 완료. 로컬 설치·실행·캡처·벤치마크·사이트 방문은 하지 않았다.

백링크