온라인 세션과 접속 관리

현재 데모는 개인 초대와 캐릭터 배정이 있는 온라인 개발 알파입니다. 참가자는 자신에게 배정된 캐릭터만 조작하며, 배정되지 않으면 관전합니다. GM은 캐릭터 배정·개인 공개 정보·NPC 조작을 관리합니다. 여러 개인 파티와 분리 장면·로비·채팅의 전체 목표는 온라인 파티와 캠페인과 구분하세요.

이 문서의 .exe 이름은 현재 개발 빌드의 실행 예시입니다. 사용하는 빌드의 실행 파일과 지원 환경을 확인하세요.

서버 시작과 재시작

server.exe -project <프로젝트 폴더> -operations로 시작하면 운영체제의 사용자 설정 폴더 아래 Narrafield/server/<프로젝트 ID 해시>/session.dat에서 세션을 불러오거나 새로 만듭니다.

다른 세션 파일을 사용하려면 -state <비공개 파일의 절대 경로>를 지정하세요. 상태 파일은 프로젝트 폴더 밖에 있어야 합니다. 첫 서버가 파일 잠금을 해제할 때까지 두 번째 서버는 같은 세션을 열 수 없습니다. 정상 종료 시 잠금이 풀리며, 프로세스가 종료되어도 운영체제가 잠금을 해제합니다.

세션에는 게임 상태, 명령 기록, 재접속 자격 증명, 개인 자격 증명의 만료·철회, 공지, 접속 제한과 감사 기록이 포함됩니다. 서버는 새 상태 파일의 기록과 동기화를 완료한 뒤에만 명령이나 운영 작업의 성공을 응답합니다. 저장에 실패하면 HTTP 503을 반환하고 메모리 상태와 기존 저장 파일을 유지합니다.

재시작하면 확정된 주사위 기록과 처리한 명령 ID를 포함해 마지막으로 저장된 상태가 복원됩니다. 같은 명령 ID에 다른 내용이나 실행 주체를 보내면 HTTP 409가 발생합니다. 동일한 요청을 재전송하면 동작을 다시 적용하지 않고 현재 서버 상태를 반환합니다.

콘텐츠를 바꾸거나 새 세션을 시작할 때

상태 파일은 프로젝트 ID, 전체 콘텐츠 해시, 엔진 버전과 저장 스키마에 연결됩니다. 콘텐츠가 바뀌었거나 상태 파일이 손상되면 서버는 시작을 거부하고 원래 파일을 보존합니다.

콘텐츠 변경 전 상태 파일을 백업하세요. 새 콘텐츠로 새 세션을 시작하려면 별도의 상태 파일 경로를 사용합니다. 자동 변환이나 실행 중 콘텐츠 다시 불러오기는 제공하지 않습니다.

현재 세션은 데이터베이스 대신 전체 파일을 교체하는 방식으로 저장합니다. 단일 서버 프로세스와 로컬 파일시스템을 대상으로 하며, 데이터베이스 수준의 확장, 네트워크 파일시스템 잠금이나 자동 백업은 제공하지 않습니다. 정전 시 보존 범위는 운영체제의 파일 동기화·교체 동작에 따릅니다.

서버 데이터 보호와 백업

DPAPI를 사용하는 빌드는 전체 상태 파일을 실행 계정에 묶어 암호화하고 인증합니다. 복원할 때 같은 계정 환경이 필요하며, 파일을 다른 계정이나 기기로 복사하는 것만으로는 복원 가능한 백업이 되지 않습니다.

Unix 계열 빌드는 상태 파일에 소유자만 읽고 쓸 수 있는 권한 0600을 적용합니다. 다른 사용자나 그룹에 권한이 있는 기존 파일은 거부합니다. 상태 파일이나 상위 경로가 심볼릭 링크여도 거부합니다. 저장 상태의 암호화가 필요하면 암호화된 볼륨을 사용하세요.

상태 폴더는 비공개로 관리하고 배포 게임 패키지와 별도로 백업합니다. 초기 GM 토큰과 이전 방식의 공용 플레이어 토큰은 재시작 후에도 서버 콘솔에 표시되므로 콘솔과 로그도 보호하세요. 해당 토큰은 플레이어 상태, 공개 패키지, 참가자 목록이나 운영 감사 기록에 포함되지 않습니다.

온라인 영속 세션은 각 주사위를 암호학적 난수로 뽑고 확정 결과를 기록합니다. 미래 난수 상태와 내부 명령·주사위 기록을 참가자의 화면 응답에 공개하지 않습니다. 재전송은 이미 처리한 명령을 다시 실행하지 않으며, 저장 실패 시 해당 상태 변경을 되돌립니다. 오프라인의 재현용 난수 흐름과 구분합니다.

외부 접속 준비

외부 접속은 TLS를 적용한 HTTPS 역방향 프록시를 통해 제공하세요. 기본 서버는 로컬호스트에서 수신합니다. 명령과 상태 조회는 인증된 HTTP를 사용하고, /events의 WebSocket은 현재 참가자에게 허용된 상태의 전체 스냅샷을 전송합니다. 필드별 차이만 보내는 증분 프로토콜은 아닙니다. 연결이 끊기면 클라이언트가 재접속하며 만료·철회된 자격 증명은 거부됩니다.

개인 초대와 만료·철회

제작기의 서버 운영 창을 열거나 operator.exe -server <HTTPS 주소>로 운영 콘솔을 실행합니다. 보호된 서버 콘솔에서 확인한 GM 토큰을 입력하세요.

운영 콘솔에서는 참가자 새로고침, 초대 생성, 철회, 공지, 파티 접속 제한과 감사 기록을 사용할 수 있습니다. GM 토큰은 메모리에만 보관합니다. 초대 토큰은 생성 결과 창에서만 표시되므로 초대할 사람에게 전달할 때 복사하세요. 결과 창을 닫으면 토큰 입력란도 비워집니다.

운영 콘솔은 외부의 암호화되지 않은 HTTP 연결과 리다이렉트를 거부하고, 요청 제한 시간과 응답 크기 제한을 적용합니다.

모든 API 요청에는 Authorization: Bearer <자격 증명> 헤더가 필요합니다. 운영 모듈 사용 여부와 관계없이 참가자 관리는 GM만 할 수 있습니다.

활성 개인 자격 증명은 최대 6개입니다. ID는 재사용할 수 없으므로 재초대할 때 새 ID를 사용하세요. 발급한 토큰을 플레이어의 토큰 입력란에 넣으면 접속할 수 있습니다. 만료된 토큰은 모든 요청에서 거부됩니다.

이전 방식의 공용 플레이어 토큰은 호환성을 위해 남아 있으며 개인별로 철회할 수 없습니다. 개인별 철회가 필요한 세션에서는 공용 토큰을 배포하지 마세요. 파티 접속 제한은 모든 플레이어 토큰에 적용됩니다. 개인 접속 관리 기록은 선택적 운영 기능을 꺼도 보존됩니다.

캐릭터 배정과 개인 화면

1. 운영 콘솔의 참가자에서 참가자 ID와 초대 만료를 지정합니다.
2. 배우 ID로 기존 캐릭터 인스턴스를 배정하거나 생성할 캐릭터 정의로 새 캐릭터를 만듭니다. 새 캐릭터 생성은 전투 사이에 진행합니다.
3. 초대 토큰 생성 후 해당 플레이어에게 개인 토큰을 전달합니다. 비워 둔 배정은 관전입니다.
4. 기존 참가자의 조작 대상을 바꾸려면 캐릭터 소유권 배정을 사용합니다. 이전 대상은 GM 조작으로 전환됩니다.
5. 플레이어는 나의 비공개 메모, GM은 참가자 비공개 화면 편집에서 메모와 개인 공개 도감을 다룹니다. 개인 메모는 해당 참가자와 GM에게 보입니다.

기존 공용 플레이어 토큰은 기존 주 캐릭터의 배정이 유지될 때만 조작합니다. 개인에게 재배정하면 공용 토큰의 조작권도 사라집니다. 초대 토큰과 캐릭터 ID를 바꾸는 것만으로 타인의 조작권을 얻을 수 없습니다.

GM의 NPC 조작

GM 캐릭터·AI → 배우·정의 새로고침에서 대상을 고릅니다. GM 수동 조종, AI에 조종 반환, AI 일시정지 / AI 계속 진행, 선택 배우의 GM 플레이 화면을 사용할 수 있습니다. 서버가 현재 차례와 조작권을 확인합니다. 부재한 플레이어의 행동을 자동으로 대신 실행하는 일반 위임·부재 정책은 아직 전체 구현이 아닙니다.

플레이 중 이미지 접근

GET /media?path=<URL로 인코딩한 관리 이미지 경로>는 인증과 접속 제한을 확인한 뒤 검증된 프로젝트 이미지를 제공합니다.

플레이어는 현재 장면의 배경·초상만 요청할 수 있으며, 이후 장면의 이미지를 요청하면 HTTP 404를 반환합니다. GM도 불러온 프로젝트에서 참조하는 이미지에만 접근할 수 있습니다. 응답에서는 캐시와 MIME 유형 추측을 비활성화합니다. 장면 상태에는 현재 배경과 초상 참조가 포함됩니다.

검증 범위

로컬 자동 검사에서는 개인 조작권·비공개 정보 분리, 상태 저장·재시작, 명령 중복 방지, WebSocket 재접속과 자격 증명 철회를 확인했습니다. 이 결과는 외부 네트워크에서의 실제 여러 플레이어 시험이나 정식 서비스 품질을 보증하지 않습니다.

외부 접속·지연·부하·접근성 검증과 통합 로비, 여러 개인 파티, 분리 탐험, 지속 신원 복구·서버 이전은 후속 작업입니다. 온라인 파티와 캠페인에 목표 흐름이 있습니다.

관련 문서

• 플레이와 게임 배포: 클라이언트·서버 패키지를 구분합니다.
• 문제 해결과 호환성: 이전 세션과 콘텐츠 변경 문제를 확인합니다.