포담 (Podam)

머더미스터리·TRPG 진행자를 위한 1:1 비공개 채널. 진행자 한 명이 여러 플레이어와 각각 따로 대화하고 핸드아웃을 주고받습니다. 플레이어는 설치도 가입도 없이 링크 하나로 들어옵니다.

자기 컴퓨터에서 돌리고, 기록은 전부 자기 손에 남습니다.

받아서 쓰기 (가장 쉬운 길)

Releases 에서 zip 을 받아 압축을 풀고 「포담 시작.cmd」 를 더블클릭하면 끝입니다. Node 도, PowerShell 설정도, 다른 설치도 필요 없습니다.

포담-1.0.0-win-x64/
  포담 시작.cmd      ← 이것만 누르면 됩니다
  runtime/            동봉한 Node
  app/                프로그램
  읽어주세요.txt

• 창이 뜨고, 브라우저가 열리고, 주소가 클립보드에 들어갑니다. 그 주소를 단톡방에 던지면 플레이어가 설치 없이 들어옵니다.
• 끝낼 때는 그 창을 닫으면 됩니다. 주소도 함께 사라집니다.
• 처음 한 번은 윈도우가 「PC를 보호했습니다」로 막습니다 — 서명을 사지 않아서입니다. [추가 정보] → [실행] 을 누르면 그다음부터는 안 묻습니다.

기록이 어디 쌓이는지는 켤 때 창에 찍힙니다 — 「데이터: …」 줄이 그것입니다. 기본은 프로그램 옆의 data 폴더입니다 — 압축을 푼 자리, 포담 시작.cmd 가 있는 곳입니다. 보이는 데에 있으니 통째로 옮기고, 복사해 두고, 지우기가 쉽습니다.

• 어느 드라이브에 두어도 됩니다 — D:, E:, USB 어디서든 돕니다. 경로가 박혀 있지 않습니다.
• 새 판으로 갈아탈 때는 data 폴더를 새 폴더로 옮겨 주세요. 지난 방이 그대로 이어집니다.
• Program Files 처럼 쓸 수 없는 자리에 두면 윈도우 사용자 폴더(%LOCALAPPDATA%\Podam)로 물러납니다. 그때도 「데이터: …」 줄에 어디인지 찍힙니다.
• 다른 곳을 쓰고 싶으면 DATA_DIR 로 지정할 수 있습니다.

바깥에서 들어오게 하기

플레이어를 초대하려면 cloudflared(Cloudflare 가 만든 작은 프로그램)가 필요합니다. 없으면 처음 켤 때 받을지 물어보고, 받아 두면 다음부터는 그대로 씁니다. 집 안에서만 쓸 거면 설정에 { "TUNNEL": false } 를 적어 두세요.

공유기 포트를 여는 방식은 쓰지 않습니다. 밖으로 나가는 연결 하나만 만듭니다.

소스에서 쓰기

npm install
npm run session      # 서버 + 주소 받기 + 브라우저 열기
npm start            # 서버만 (localhost:3000)
npm test             # 검사

무엇을 할 수 있나

1:1 대화 · 파일	PDF·그림·소리 무엇이든. 받은 자료만 따로 모아 보는 칸이 있습니다
배역	사람에게 배역을 붙여 「집사 역에게 2막 자료 일괄 발송」이 한 번에
예약 발송	「10분 뒤 모두에게」를 미리 걸어 둡니다
NPC 이름으로 말하기	같은 대화에서 이름만 바꿔 말합니다. 뒤에 누가 있는지는 안 보입니다
질문지	최종 지목 같은 것을 받는 비밀 제출함
라운드 타이머	모두의 화면에 같은 시계가 돕니다
입장 잠금 · 내보내기	판이 시작되면 난입을 막습니다
이름 색	각자 고른 색이 말풍선과 공용 대화에 그대로
룸 셋팅	배역·자료·설정을 꾸러미로 저장해 다음 회차에 그대로
기록 내보내기	주고받은 대화를 그때 쓴 그림까지 담아 한 파일로

쓰는 법은 프로그램 안에 있습니다 — 화면 오른쪽 아래 ❔ 사용 가이드. GM 용과 플레이어 용이 따로 있고, 플레이어에게는 그 방에서 켜진 기능만 보입니다.

🧩 모듈 — 폴더 하나가 기능 하나

시나리오에 따라 쓰기도 하고 안 쓰기도 하는 기능은 코어에 넣지 않았습니다. 모듈은 폴더 하나이고, 넣으면 붙고 빼면 없어집니다. 받자마자는 비어 있습니다 — 기본만 쓰고 싶으면 그대로 두세요.

포담-0.1.0-win-x64/
  modules/        ← 여기 들어 있는 것만 붙는다 (처음엔 비어 있음)
  모듈 모음/       ← 공식 모듈 보관. 쓸 것만 modules 로 옮긴다

찾는 곳은 두 군데입니다 — 프로그램 옆의 modules 와 데이터 폴더의 modules. 앞의 것은 프로그램과 함께 다니고, 뒤의 것은 새 판으로 갈아도 남습니다. 둘 다 실립니다.

켤 때 창에 무엇을 어디서 실었는지 찍힙니다.

모듈 2개: trpg, verdict
   D:\포담-0.1.0-win-x64\modules  (trpg, verdict)

잠깐 끄려면 폴더 이름 앞에 _ 를 붙이세요. 기록은 그대로 남습니다.

공식 모듈

따로 나눠 줍니다 → Podam-modules

모듈	무엇
🔑 정답 판정	배역마다 「정답:답변」 표를 두고, 플레이어가 정답을 내면 그 답변이 자동으로 나갑니다
🎲 간이 TRPG	모두가 함께 보는 무대(배경·BGM) · 공용 대화 · 3D 주사위
👥 캐릭터 카드	무대에 얹히는 확장. 그림·수치·상태이상·토큰
🤖 AI 시나리오 보조	자료(PDF·그림·글)를 읽혀 두고 물어봅니다. 답에는 원문 인용이 붙고, 자료에 없으면 없다고 합니다. API 키는 각자의 브라우저에만 두고 모델도 브라우저가 직접 부릅니다

받아서 modules/ 폴더에 풀고 다시 켜면 됩니다.

쓰기

• 방 만들 때 — 첫 화면의 「쓸 기능 고르기」에서 체크
• 나중에 — GM 대시보드 왼쪽 아래 🧩 모듈 버튼으로 켜고 끄기
• 모듈 설정은 룸 셋팅(zip)에 함께 담겨 다음 회차에서 그대로 살아납니다

모듈은 자기 사용법을 들고 다닙니다. guide.js 의 gm/player 두 토막이 가이드 화면에 자동으로 붙습니다 — 모듈을 넣어도 guide.html 은 고치지 않습니다.

• GM 가이드(/guide.html#gm) 맨 아래 「🧩 모듈」에 이 서버의 모든 모듈 사용법이 나옵니다.
• 플레이어 가이드는 자기가 들어와 있는 방에서 켜진 모듈의 사용법만 보여 줍니다. 방 밖(코드만 아는 사람)에게는 아무것도 보이지 않습니다.

꺼진 모듈은 서버에서 막습니다 — 화면만 숨기는 것이 아니라 API 자체가 없는 것처럼 404를 돌려줍니다. 모듈이 오류를 내도 대화는 그대로 배달됩니다.

직접 만들기

폴더 하나에 index.js 만 있으면 모듈입니다. → docs/모듈-만들기.md

모듈은 서버에서 도는 코드라 방·대화·파일에 모두 닿습니다. 읽을 수 있거나 믿는 모듈만 넣으세요.

비공개성이 지켜지는 방식

클라이언트 필터링이 아니라 서버에서 막습니다.

• 소켓 룸은 r:<방>:p:<참가자>(플레이어)와 r:<방>:gm(GM) 둘뿐입니다. 방 전체에 emit하는 코드는 존재하지 않으며, 전체 공지도 수신자별 개별 발송입니다.

• 모든 발송은 src/messages.js의 deliver() 하나만 지납니다 — 채팅·파일·공지 전부. 삭제도 같은 파일의 remove() 하나만 지납니다.

• 플레이어가 보내는 participantId는 무시하고 핸드셰이크에서 확정한 서버 측 값만 씁니다.

• 파일 다운로드 /f/:id는 요청자가 그 파일을 받은 본인이거나 GM일 때만 200, 아니면 404 (존재 여부도 알리지 않음).

• 참가자 목록 API는 GM 토큰 없이는 403.

• GM끼리의 대화는 별도 테이블·별도 소켓 룸입니다. 플레이어 소켓으로는 흘러갈 경로가 없습니다.

• 질문지 답은 GM만 집계를 봅니다. 플레이어는 자기 답만 보고, 공개는 GM이 누를 때만 일어납니다.

npm test가 이 항목들을 실제로 뚫어보며 검증합니다 (146개 확인 — 격리, 대상 위조, 파일 권한, 이력 복구, 배역 자료함, 메시지 삭제, 다중 GM, GM 대화 격리, 닉네임 변경, 순서 저장, 내보내기, 타이머, NPC 이름, 일괄 발송, 질문지).

더 읽을 것

docs/모듈-만들기.md	내 기능을 모듈로 만들어 붙이기
docs/운영.md	서버를 계속 띄워 두고 쓰기 — 암호·백업·설정값
docs/서버에-올리기.md	늘 켜 두는 서버(NAS·미니PC·VPS)에 도커로 올리기
소개.md	이 프로그램이 왜 이렇게 생겼는지

구조

src/
  db.js         SQLite 스키마
  auth.js       토큰 발급·해시·검증
  messages.js   ★ 모든 발송과 삭제의 단일 진입점 (격리 규칙)
  socket.js     소켓 인증과 이벤트
  rooms.js      방 개설·입장·참가자·순서
  gms.js        GM 로그인·GM끼리의 대화
  roles.js      배역과 배정
  send.js       GM 발송·배역별 일괄 발송
  timer.js      라운드 타이머
  ask.js        질문지와 답 모으기
  targets.js    발송 대상 선별
  upload.js     업로드와 권한 검사된 다운로드
  export.js     기록 HTML 생성
  paths.js      데이터·설정·모듈 폴더가 어디인지
  modules/
    index.js    모듈 폴더를 훑어 싣는 곳 (코어에는 모듈이 없다)
    hooks.js    모듈이 대화 흐름에 끼어드는 지점
    state.js    방마다 어떤 모듈을 켰는지
public/
  index.html    랜딩
  gm.html/js    GM 대시보드
  room.html/js  플레이어 화면 (대화/받은 자료/메모)
  shared.js     알림음·볼륨·드래그 정렬·이미지 확대·알림
docs/모듈-만들기.md  모듈 만드는 법
test/e2e.js     종단 검증 (시험용 모듈을 그 자리에서 만들어 넣고 로더까지 확인한다)
start-session.bat  ← 더블클릭해서 세션 시작
start-session.ps1  서버 + 터널을 한 번에 (bat이 호출)

npm test        # 종단 검증 (검사 292개)

배포판 만들기

powershell -ExecutionPolicy Bypass -File tools\build-release.ps1 -Version 0.1.0 -ModulesFrom ..\podam-modules\modules

dist\포담-<판>-win-x64.zip 이 나옵니다. Node 런타임과 공식 모듈까지 담아 한 덩어리로 묶습니다. -ModulesFrom 을 빼면 모듈 없이 코어만 담깁니다.

만든 사람

포하 (Poha) — 머더미스터리를 온라인으로 굴리다가 창을 서른 번 오가는 게 싫어서 만들었습니다.

쓸 만하셨다면 커피 한 잔 사 주세요 ☕ → buymeacoffee.com/poha

라이선스

MIT. 마음대로 쓰고 고치고 나눠 주세요.