모듈 만들기: 조사부터 발행까지
믿을 수 있는 게임 모듈을 만드는 전체 절차. 조사, 실제 서버 실측, 포터블 런타임, 격리 실행, 콘솔 방식, 실제 PC 확인을 다룹니다.
모듈 만들기: 조사부터 발행까지
모듈 개발 가이드는 모듈에 무엇이 들어가는지 설명합니다. 이 문서는 실제 PC에서 동작하는 모듈을 만드는 순서를 설명합니다.
단위 테스트를 모두 통과한 모듈도 실제 서버에서는 실패할 수 있습니다. 테라리아 모듈이 그런 예입니다. 단위 테스트와 적합성 검사를 모두 통과했지만, 실제 서버에서는 결함이 9가지 나왔습니다. 이 문서는 그런 결함을 발행 전에 찾는 절차를 보여 줍니다.
1. 설계 원칙
모든 모듈에 적용하는 원칙입니다.
- 데몬이 일을 합니다. 모듈은 게임을 설명할 뿐입니다. 데몬 계약을 우회하지 않습니다. 필요한 기능이 계약에 없으면 데몬에 범용 확장 지점을 먼저 만듭니다.
- 게임 이름으로 분기하지 않습니다. 데몬과 공용 도우미에는 게임 이름이 없습니다.
module.toml키, 훅, 슬롯을 씁니다. - 어디서나 같은 실행 환경을 씁니다. PC에 설치된 런타임을 쓰지 않습니다. 모듈이 고정 판 런타임을 받아 서버 폴더에 둡니다(5절).
- 값은 한 곳에 둡니다. 설정의 기본값은 파일 하나에서 옵니다. 게임이 만든 파일, 또는 배포물에 동봉된 예시 파일입니다.
- 사용자 문구는 모두
locales/에 둡니다.en.json이 기준 파일입니다.
2. 게임 조사
코드를 쓰기 전에 <game>/RESEARCH.md에 조사 표를 만듭니다. 항목마다 출처를 적고, 그 출처가 문서인지 실측인지도 적습니다. 출처를 찾지 못한 항목은 비워 두고 "확인 못 함"으로 적습니다. 값을 짐작하지 않습니다.
| 항목 | 찾을 곳 |
|---|---|
| 서버 실행 파일, 실행 인자, 기본 포트 | 공식 문서, 서버 도움말, 배포물의 실행 스크립트 |
| 명령 전체와 인자 | 공식 명령 문서와 서버 help 출력. 둘을 한 줄씩 대조합니다 |
| 설정 전체(키, 형식, 범위, 기본값) | 서버가 만든 기본 설정 파일. 서버가 만들지 않으면 배포물의 예시 파일 |
| 설정 파일의 문법과 인코딩 | 그 파일의 원래 바이트 |
| 월드 세이브와 게임이 만드는 백업 | 서버를 켜고 저장한 뒤의 파일 목록 |
| 준비 완료·정지·접속·퇴장 문구 | 서버 콘솔 원문. 서버 언어 설정이 문구를 번역하는지도 봅니다 |
| 설치 방법과 파일 검증 | 공식 내려받기 주소와 공식 체크섬. 체크섬이 없으면 "없음"과 출처 |
| 실행 전제(런타임) | 서버 실행 파일의 참조 목록과 공식 문서. 배포물에 없는 것을 찾습니다 |
| 인스턴스 폴더 밖의 파일 | 서버 실행 뒤 홈 폴더와 문서 폴더의 변화 |
위키는 옛 버전을 설명할 수 있습니다. 테라리아 위키에는 death 명령이 있지만, 테라리아 1.4.5.8 서버는 이 명령에 "Invalid command."로 답합니다.
3. 실제 파일 확인
서버를 내려받을 수 있으면 파일을 직접 확인합니다.
- 압축 파일의 항목 전체를 출력합니다. OS마다 폴더가 있는지, 같은 실행 파일 이름이 여러 폴더에 있는지 봅니다. 테라리아 압축 파일은
Linux/폴더와Windows/폴더에 모두TerrariaServer.exe가 있습니다. - 기본 파일을 바이트 단위로 읽습니다. 인코딩(UTF-8, BOM, cp1252), 줄바꿈(LF, CRLF), 주석 처리된 예시 키, 주석이 아닌 줄을 찾습니다.
- 주석 처리된 예시 키도 설정 목록에 넣습니다. 주석이 아닌 줄의 값이 기본값입니다.
4. 실제 서버 실행
데몬과 같은 방식으로 서버를 띄웁니다. stdin과 stdout을 파이프로 잇고 원문을 기록합니다. 제작 환경에서 다른 OS용 서버밖에 실행할 수 없어도 실행합니다. 게임 코드가 같으면 명령, 문구, 저장 동작은 같습니다.
다음을 기록합니다.
- 준비 완료 줄, 정지 명령 뒤의 줄, 저장에 걸린 시간
help출력. 문서에만 있는 명령은 하나씩 보내 답을 기록합니다- 콘솔 프롬프트. 어떤 서버는 줄바꿈 없이 프롬프트를 찍어 다음 줄이 프롬프트로 시작합니다. 테라리아는
: Server started로 찍습니다 - 파이프로 보낸 명령의 답. 서버가 답하지 않으면 의사 콘솔로 다시 시험합니다(7절)
- 서버 언어마다 준비·정지 문구
- 서버가 시작하고 저장할 때 만드는 파일. 테라리아는
world.wld.bak과world.wld.bak2를 만듭니다
접속 문구, 추방 대상처럼 게임 클라이언트가 있어야 재는 항목은 비워 두고 "실측 못 함"으로 적습니다.
5. 실행 전제: 고정 판 포터블
어떤 서버는 배포물에 없는 런타임을 요구합니다. Java, XNA Framework, Visual C++ 런타임 같은 것입니다. PC에 설치된 런타임은 쓰지 않습니다. PC마다 판이 다를 수 있기 때문입니다.
다음 순서를 따릅니다.
- 공식 런타임 파일의 주소, 크기, 서명, SHA-256을 조사 표에 적습니다.
- 서버에 꼭 필요한 파일의 최소 집합을 찾습니다. 그 파일만 두고 서버를 띄워 확인합니다. 테라리아는 XNA 어셈블리 4개(
Microsoft.Xna.Framework,.Game,.Graphics,.Xact),XnaNative.dll,msvcr100.dll,msvcp100.dll입니다. install_server에서 고정 판을 받습니다. 공식 체크섬과 비교합니다. 공식 체크섬이 없으면, 게시자 서명이 유효한 파일에서 기록한 SHA-256과 비교합니다.- 필요한 파일만 서버 폴더나 인스턴스 폴더에 두고, 그 경로로 서버를 띄웁니다.
validate에서 이 파일들을 찾습니다. 하나라도 없으면severity: "critical"과 전용code로 문제를 돌려주고, 서버를 다시 설치하라고 안내합니다.
관리자 권한, 시스템 설치, Windows 서비스를 쓰지 않습니다.
한계: .NET Framework는 같은 이름·판의 어셈블리가 전역 어셈블리 캐시(GAC)에 있으면 GAC 쪽을 먼저 읽습니다. 네이티브 DLL은 서버 폴더의 것을 먼저 읽습니다.
6. 격리 실행
Windows에서 서명된 사바쨩 카탈로그에 없는 모듈은 Windows AppContainer 안에서 돕니다. 새로 만든 모듈은 모두 이 격리 안에서 돕니다. PR을 열기 전에 격리 실행에서 모듈을 시험합니다.
격리 실행에서는 다음을 쓸 수 없습니다.
| 막힌 것 | 대신 쓰는 것 |
|---|---|
| 루프백 연결(데몬 API, 게임 서버 REST API) | daemon_stdin_command, daemon_rest, loopback_http, loopback_exchange. 데몬이 요청을 중계합니다 |
Windows Installer(msiexec가 오류 1601로 실패)와 다른 서비스 | 설치 파일(MSI, CAB)을 Python으로 직접 읽습니다 |
tempfile.mkdtemp이 인스턴스 폴더에 만든 폴더 | tempfile.mkstemp, 또는 os.mkdir로 직접 만든 폴더. Python 3.13부터 mkdtemp은 현재 사용자에게만 권한을 줘서, 격리 계정이 그 폴더에 쓰지 못합니다 |
| 허용된 폴더 밖의 쓰기 | 인스턴스 폴더, 작업 폴더, 설치 폴더, data_roots에 선언한 폴더 |
격리 실행에서 공용 도우미가 실패하면 모듈에서 우회하지 않습니다. 데몬 문제로 보고합니다.
7. 콘솔 방식
데몬은 기본으로 서버의 stdin과 stdout을 파이프로 잇습니다([launch] console = "pipe"). 어떤 서버는 stdin이 파이프일 때 다르게 동작합니다.
- 팰월드는 끝날 때까지 출력을 모아 둡니다.
- 테라리아 Windows 서버는 파이프 입력을 읽지 않습니다. 명령과
exit에 답하지 않았고, 데몬이 60초 뒤 저장 없이 강제 종료했습니다.
이런 서버는 [launch] console = "pty"로 설정합니다. 그러면 데몬이 서버를 의사 콘솔(Windows ConPTY, Unix pty)에서 띄웁니다.
의사 콘솔은 보낸 명령을 다시 찍습니다. 줄 나눔도 달라질 수 있습니다. 의사 콘솔에서 테라리아는 프롬프트 :와 Server started를 다른 줄에 찍습니다. 패턴은 두 경우를 모두 받게 씁니다.
8. 콘솔 패턴
준비 완료, 접속, 퇴장, 정지 패턴은 실측한 원문으로만 씁니다.
- 준비 완료·접속·퇴장 패턴은
[extensions.saba-core](ready_patterns,player_join_patterns,player_leave_patterns)에, 정지 패턴은[detection] graceful_exit_patterns에 둡니다. - 패턴을 줄의 처음과 끝에 묶습니다. 같은 낱말이 든 채팅 줄(
<Server> Server started)이 맞으면 안 됩니다. - 문구 앞에 프롬프트가 올 수 있으면
^(?:<프롬프트>)?로 받습니다. - 서버 언어 설정이 문구를 번역하면, 언어마다 실측한 문구를 모두 넣습니다. 영어만 넣으면 다른 언어로 설정한 서버의 준비 상태를 데몬이 알 수 없습니다.
- 테스트를 넣습니다. 실측 원문 줄은 프롬프트가 있든 없든 맞아야 하고, 채팅 줄은 맞지 않아야 합니다.
9. 설치와 설정 파일
설치:
- 압축 파일에 OS마다 폴더가 있으면, OS 이름으로 폴더를 고릅니다. 실행 파일 이름, 경로 길이, 첫 항목으로 고르지 않습니다. 폴더가 없거나 둘 이상이면 실패로 답합니다.
- 기존 설정과 월드를 덮지 않습니다. 예시 설정 파일은 설정 파일이 없을 때만 풉니다.
- 받은 파일을 모두 검증합니다. 바이너리마다 공식 체크섬을 씁니다. 공식 체크섬이 없으면 고정된 공식 호스트로의 HTTPS, 압축 CRC, 기대 실행 파일의 존재로 확인합니다. 조사 표에 "공식 체크섬 없음"과 출처를 적습니다. 체크섬을 지어내거나 커뮤니티 해시를 쓰지 않습니다.
설정 파일:
- 그 형식의 공식 문법으로 읽고 씁니다. 예를 들어 Java
.properties파일에는\:,\=이스케이프가 있고, 줄 끝의\는 줄을 잇습니다. - 인코딩을 가정하지 않습니다. 실제 인코딩으로 읽고, 같은 인코딩과 같은 줄바꿈으로 다시 씁니다. 테라리아 Windows
serverconfig.txt는 cp1252이고 주석에 0x92 바이트가 있습니다. UTF-8로만 읽는 모듈은 이 서버를 켜지도, 설정을 저장하지도, 가져오지도 못합니다. - 바뀐 키만 고칩니다. 다른 키, 주석, 순서는 그대로 둡니다.
- 파일을 읽지 못했으면 쓰지 않습니다. 파일 없음, 읽기 실패, 해석 실패는 서로 다른 경우입니다.
10. 테스트
단위 테스트와 적합성 키트는 격리 없이 견본 파일로 돕니다. 그래서 실제 배포물, 격리 실행, 콘솔 방식, Windows에서만 생기는 문제는 찾지 못합니다. 세 단계의 테스트를 모두 합니다.
10.1 단위 테스트
- 함수를 쓰기 전에
test_lifecycle.py에 그 함수의 테스트를 씁니다. - 테스트를 돌려 실패하는 것을 확인합니다.
- 함수를 씁니다.
- 다음 검사를 돌립니다.
saba-core module validate mygame
saba-core module audit mygame
pytest conformance --module path/to/mygame --shared-libs path/to/saba-chan/modules
10.2 실제 서버 테스트 (PR 전)
4절을 마친 뒤, 실제 서버 폴더에서 모듈 함수를 부릅니다.
- 실제 배포물로
install_server를 돌립니다. 이 OS의 파일만 폴더에 있는지 확인합니다. get_launch_command가 준 명령으로 서버를 띄웁니다. 준비 패턴이 맞는지 확인합니다.- 명령 템플릿을 하나씩 보냅니다. 서버가 받아들이는지 확인합니다.
- 정지 명령을 보냅니다. 서버가 저장하고 끝나는지 확인합니다.
backup_paths와reset_server의 경로를 서버가 만든 파일과 비교합니다.
10.3 실제 PC 테스트
Windows PC의 정규 사바쨩 설치를 씁니다. 새 모듈은 격리 실행으로 돌기 때문에, 이 테스트에서 격리 실행 문제도 드러납니다.
- 모듈 폴더를 사바쨩 데이터 폴더의
modules\<이름>\에 복사합니다. saba-chan-cli module refresh를 실행합니다.saba-chan-cli server add <서버> -m <모듈>을 실행합니다.- 서버를 켭니다. 사바쨩이 준비 상태를 보여 주는지 확인합니다.
saba-chan-cli run <서버> <명령>으로 명령을 보내고,saba-chan-cli server console <서버> --print로 답을 읽습니다.- 설정을 바꾸고 서버를 다시 시작합니다. 서버가 새 값을 쓰는지 확인합니다.
saba-chan-cli backup create <서버>로 백업을 만들고, 백업에 든 파일을 봅니다.- 서버를 끕니다. 사바쨩이 정상 종료로 기록했는지, 월드 세이브가 남았는지 확인합니다.
- 월드를 초기화합니다. 지운 파일과 남은 파일을 봅니다.
[module.dependencies] saba-core가 아직 발행되지 않은 판을 요구하면, 정규 설치는 그 모듈을 읽지 않습니다. 그 판이 발행된 뒤에 PC 테스트를 합니다. 의존 판을 낮추지 않습니다.
11. PR 전 체크리스트
-
RESEARCH.md의 항목마다 출처가 있고, 출처마다 "문서"나 "실측"이 적혀 있습니다. - 압축 파일 항목과 기본 파일의 원래 바이트를 확인했습니다.
- 실제 서버를 띄워 원문,
help출력, 저장 뒤 파일을 기록했습니다. - 선언한 명령이 모두
help출력에 있습니다. - 서버가 명령에 답합니다. 답하지 않으면
[launch] console = "pty"를 설정했습니다. - 콘솔 패턴이 모두 실측 원문에서 왔고, 프롬프트와 언어별 번역을 받습니다.
- 런타임이 모두 고정 판 포터블이고, 모듈이 받은 파일을 검증합니다.
- 설치가 이 OS의 폴더만 풉니다.
- 설정 파일이 인코딩과 줄바꿈을 지킵니다.
- 월드 초기화가 서버가 만든 파일(게임이 만든 백업 포함)만 지웁니다.
- 모듈이
msiexec, Windows 서비스,mkdtemp폴더, 루프백 직접 연결을 쓰지 않습니다. - 실제 서버 테스트와 실제 PC 테스트를 했거나, 못 한 테스트를 적었습니다.