PhoneHub + Pulse 문서
PhoneHub + Pulse Phone — 설치 가이드
통합 에디션 1.4.6 · ZeroDev
이 에디션은 Pulse Phone, PhoneHub 건물, 전용 PhoneHub OS, 3D 휴대폰 키오스크, 수리 작업대, 직원 재고/배송 시스템을 하나로 묶은 것입니다. 휴대폰 단독 에디션과는 별개의 제품입니다. 휴대폰과 매장 리소스를 함께 설치하세요. phone을 두 개 실행하거나 PhoneHub 맵을 두 버전 실행하지 마세요.
1. 설치 전
- 기존 휴대폰 리소스, 맵 리소스, 설정, 데이터베이스를 백업하세요.
- OneSync와 GTA 게임 빌드 2699 이상을 사용하세요.
- 데이터베이스, framework, 인벤토리, 보이스 리소스, screenshot-basic을 먼저 시작하세요.
- 리소스 이름은 정확히
phone과zerodev_phonehub_mlo로 유지하세요. - 이전 PhoneHub 리소스를 활성 resources 디렉터리에서 제거하고, 중복된
ensure줄도 제거하세요. 백업은 그 디렉터리 밖에 보관하세요. - 같은 Portola Drive 건물을 대체하는 다른 맵은 비활성화된 상태로 두세요.
- 맵 파일을 교체하기 전에 FiveM을 완전히 종료하고 서버를 중지하세요. 서버를 시작한 뒤 FiveM을 다시 실행하세요. 이 스트리밍 MLO를 교체하거나 재시작하기 전에 클라이언트 접속을 끊으세요. 접속 중인 클라이언트는 건물에서 멀리 있어도 맵을 유지할 수 있으며, 핫 리스타트하면 그 클라이언트가 크래시할 수 있습니다.
이 패키지에는 서버 라이선스 키, framework, 인벤토리, 유료 서드파티 스크립트가 포함되어 있지 않습니다. Keymaster 처리 후, 서버 키는 이 새 통합 에셋의 권한을 가진 계정에 속해야 합니다. 예전 휴대폰 단독 에디션의 권한으로는 이 새 에디션을 사용할 수 없습니다.
2. 리소스 복사
이 다운로드의 phone과 zerodev_phonehub_mlo 폴더를 서버 resources 디렉터리에 복사하세요. 어느 카테고리 폴더에 넣어도 되지만, 폴더 이름은 정확히 유지하세요.
screenshot-basic. 카메라를 쓰려면 screenshot-basic이 phone보다 먼저 시작되어야 하며, 기본 리소스로도 작동합니다. 다운로드에는 더 가벼운 사본도 들어 있습니다(사진을 찍는 동안에만 게임 이미지를 그리며, 이름, export, 이벤트는 같습니다). 바꾸는 것은 선택 사항입니다. 기존 폴더는 백업으로 resources 밖에 보관하고, 스크린샷을 찍는 스크립트를 테스트한 뒤, 달라진 것이 있으면 기존 폴더를 되돌리세요. 단계는 Pulse Phone 빠른 시작 6단계에 있으며, 변경된 파일은 screenshot-basic/ZERODEV-CHANGES.md에 나와 있습니다.
server.cfg의 기존 의존성 뒤에 다음 줄을 추가하세요:
ensure phone
ensure zerodev_phonehub_mlo예전 휴대폰 엔진이나 UI를 새 패키지에 복사하지 마세요. 업그레이드할 때는 필요한 설정을 새 설정 파일로 옮기세요. 데이터베이스, 리소스 KVP 저장소, media와 ownermedia 디렉터리는 유지하세요. 새 phone/config/phonehub_business.lua에는 휴대폰 단독 에디션에 없는 배송 설정이 들어 있습니다.
설정된 매장 카운터는 -749.541, -216.952224, 36.256562, 방향 210입니다. 매장 위치는 깨끗한 통합 에디션에 이미 설정되어 있습니다. 이 에디션의 휴대폰 매장은 PhoneHub뿐이며, 휴대폰 단독 패키지의 Legion Square 매장은 포함되지 않습니다. 1.4.4 이하에서 가져온 config.lua에는 여전히 Legion Square가 있지만, 그 항목은 건너뛰고 콘솔에 한 번 알립니다. 매장 키오스크, 수리 작업대, 서비스 카운터, 옥상 제어 지점에서 PhoneHub 키(기본값 E)를 누르거나 /phonehub을 사용하면 PhoneHub 단말기가 열립니다. 키오스크에서는 Shop이, 수리 작업대에서는 Repair가 열립니다. 키는 FiveM 키 바인딩에서 바꿀 수 있습니다. 명령어도 키와 같은 거리 안에서만 작동하며, 직원 작업에는 여전히 서버 권한이 필요합니다.
3. framework, 인벤토리, 기타 스크립트
Config.Framework = 'auto'와 자동 제공자 설정(phone/config/config.lua)으로 시작하세요. 휴대폰의 시작 상태 보고서가 실제로 선택한 제공자를 알려 줍니다. 구매를 진행하기 전에 그 보고서를 확인하세요.
| Framework | 설정 |
|---|---|
| ESX Legacy | es_extended와 인벤토리를 phone보다 먼저 시작하세요. zerodev_phonehub_mlo/setup/phonehub_esx_jobs.sql을 가져오세요. 플레이어에게 배정하지 않고 빠진 직업 직급만 추가합니다. |
| QBCore | 제공된 zerodev_phonehub_mlo/setup/phonehub_qb_job.lua 직업 항목을 core의 shared jobs 테이블에 추가하세요. 휴대폰 아이템은 휴대폰 아이템 가이드를 따라 등록하세요. |
| Qbox | 설치된 Qbox 직업 설정이나 지원되는 직업 등록 API로 같은 직업/직급을 등록하세요. ox_inventory 아이템 정의를 사용하세요. |
| ox_core / vRP | 휴대폰의 기존 framework 어댑터와, PhoneHub 직업 및 숫자 직급을 반환하는 직업 제공자를 설정하세요. 직업 시스템이 이를 제공하지 않으면 ACE로 제어하는 건물 권한을 사용하세요. |
| Standalone / 커스텀 | 공용 쇼핑은 휴대폰의 기존 standalone/커스텀 브리지로 사용할 수 있습니다. 직원 권한에는 설정된 직업 제공자나 신뢰할 수 있는 관리자 ACE가 필요합니다. |
인벤토리 어댑터는 ox_inventory, 지원하는 framework 인벤토리 기능, 그리고 phone/guides/integrations.md(또는 휴대폰 빌드에 포함된 연동 가이드)에 나열된 서드파티 제공자를 지원합니다. 각 제공자에는 실제 아이템 정의와 호환되는 API 버전이 필요합니다. 빠진 아이템은 휴대폰 상태 점검이 보고하며, 그 오류를 숨기지 마세요. 아이템 설정 예시는 phone/config/items/에 들어 있습니다.
휴대폰의 수정 가능한 브리지는 보이스, 소사이어티 계좌, 은행, 차고, 주택, 디스패치 등의 연동을 담당합니다. 기능마다 제공자를 정확히 하나만 선택하세요. 이름을 바꾼 리소스는 Config.ResourceNames로 고정하고, 제공자를 명시적으로 고르려면 Config.Providers를 사용하세요. 임의의 서드파티 export가 자동으로 호환되지는 않습니다. 스크립트가 목록에 없다면 문서화된 커스텀 브리지를 구현하세요. framework 어댑터와 자동 계약 테스트가 있다고 해서 모든 서드파티 버전을 실서버에서 테스트했다는 뜻은 아닙니다.
이번 릴리스의 실서버 테스트 구성: ESX Legacy, ox_inventory, oxmysql, pma-voice. 다른 framework에서는 매장을 열기 전에 7절의 첫 실행 점검을 진행하세요.
4. 공용 상점 또는 플레이어 소유 사업체
서버 콘솔에서 두 명령어 중 하나를 실행하세요:
phonehubmode public
phonehubmode business선택한 모드는 재시작 후에도 유지됩니다. 공용 모드는 일반 쇼핑을 유지합니다. 비즈니스 모드는 PhoneHub 카운터에서 하는 구매에 영구 재고와 예약을 적용합니다. 비즈니스 모드에서는 카운터 보상 판매(trade-in)가 비활성화됩니다. 가격, 결제, 아이템 전달은 같은 휴대폰 결제 과정이 검증합니다.
직업 이름과 직급은 phone/config/phonehub_business.lua에서 설정하세요:
| 직급 | 기본 업무 |
|---|---|
| 0 — 수습 | 비즈니스 단말기 보기, 도착한 배송 수령, 건물 제어 |
| 1 — 판매 | 수습 업무에 더해 공급업체 주문 |
| 2 — 기술자 | 주문/수령과 설정된 수리 역할 |
| 3 — 매니저 | 모든 직원 제어에 더해 대기 중인 공급 주문 취소/환불 |
직업은 framework의 일반 관리 도구로 배정하세요. 회사 관리는 휴대폰에서 Services → My Work → PhoneHub → Staff and account를 여세요. 선택된 framework가 지원하는 직원/소사이어티 기능을 사용합니다. 통합 에디션은 Business 탭의 게임 내 구매나 아래 설명한 관리자 배정 명령어를 통한 영구적인 플레이어 소유도 지원합니다. 모든 소유권 가격은 게임 내 화폐 금액입니다.
esx_addonaccount를 쓰는 ESX에서는 계좌 리소스를 시작하기 전에 zerodev_phonehub_mlo/setup/phonehub_esx_society.sql도 가져온 뒤 서버를 재시작하세요. 기존 잔액을 덮어쓰지 않고 잔액 0의 society_phonehub 회사 계좌를 만듭니다. 직업 이름을 바꿨다면 계좌 접미사도 맞춰 바꾸세요. 다른 은행 제공자는 설정된 직업에 대해 일반적인 회사 계좌 설정이 필요합니다. 사업을 시작하기 전에 Company에서 소액 입금과 출금을 확인하세요.
운영 예산은 별도의 내부 재고 구매 장부입니다. 판매하면 늘어나고, 공급업체 주문 시 차감됩니다. 자동으로 소사이어티 은행 계좌가 되는 것이 아니며, 플레이어가 인출할 수 있는 현금 잔액도 아닙니다.
5. 공급업체 주문과 재고 배송
서비스 카운터에서 E를 눌러 PhoneHub 단말기를 열고 Stock으로 가세요. 제품, 구성, 수량을 고르세요. 서버가 공급업체 견적을 계산하고 직원의 직급, 거리, 운영 예산을 확인합니다.
기본 배송 시간은 120초입니다. 재시작 중에도 배송 상태가 유지됩니다. 도착하면 직원이 단말기에서 Receive delivery를 선택합니다. 기본값 destination='stock'은 구매자의 플레이어 인벤토리 제공자와 관계없이, 결제 시 소모되는 매장 재고 장부에 상품을 추가합니다. 수령 요청을 반복해도 같은 배송이 두 번 추가되지 않습니다. 매니저는 수령하지 않은 배송을 취소하고 예산을 한 번 환불받을 수 있습니다.
설정:
delivery = {
seconds = 120,
autoReceive = false,
destination = 'stock',
resource = '',
export = '',
}커스텀 창고/보관함을 쓰려면 destination='custom'으로 설정하고 서버 export를 지정하세요. 그 export는 (shipment, source)를 받으며, shipment.id를 영구적인 중복 방지 키로 사용해야 합니다. 모든 줄이 성공적으로 저장되었을 때만 true를 반환하세요. 인벤토리의 아이템/SKU 매핑은 그 어댑터에서 설정하세요. 커스텀 배송은 내부 판매 장부에 아이템을 추가하지 않으므로, 재고 중복을 피하려면 창고 판매 흐름을 명시적으로 연결하세요. 범용 보관함 어댑터는 가정하지 않습니다.
외부 인계가 불확실한 경우 검토 대기로 보류하며, 무작정 다시 시도하지 않습니다. 대상 인벤토리를 확인한 뒤 다음을 사용하세요:
phonehubdelivery <shipment-id> delivered
phonehubdelivery <shipment-id> retry고객 결제 예약이 불확실한 경우, phonehubresolve <reservation-id> returned|delivered를 사용하기 전에 결제 기록과 인벤토리 기록을 확인하세요.
6. 매장 제어
서비스 제어 지점이나 옥상 제어 받침대 근처에서 E를 누르세요.
- Space: 정문과 옥상 문 잠금, 매장 조명, 라운지 디스플레이, 테라스 캐노피(비나 눈이 오면 자동, 또는 열림/닫힘), 테라스 히터 또는 송풍, 테라스 전원, 15초 스프링클러 테스트.
- Cameras: Entrance overview, Showroom overview, Service counter. 단말기로 돌아가면 카메라가 닫히고, Escape로 나갑니다.
- Stock과 Business: 공급업체 주문, 배송, 매출, 판매 및 수리 장부, 팀 권한.
건물 제어에는 PhoneHub 직업이나 설정된 직원/관리자 ACE가 필요합니다. 테라스 공용 제어 권한은 systems_config.lua에서 따로 설정합니다. phonehub.admin은 신뢰할 수 있는 관리자 principal에게만 부여하고, 절대 모두에게 주지 마세요. MLO 시스템 설정에서 phoneResource='phone'으로 설정하세요.
자동문은 잠금이 해제되어 있을 때 근접 센서를 사용합니다. 움직이는 문짝은 열려 있을 때도 충돌 판정이 있어야 합니다. 가구, 유리, 조명은 제작된 맵 에셋이며, 모든 장식 오브젝트에 게임플레이 상호작용이 있는 것은 아닙니다.
7. 첫 실행 점검
- 서버를 시작하고
phone:health를 실행하세요. 예상한 framework, 인벤토리, 데이터베이스, 보이스 제공자가 맞는지, 빠진 필수 아이템이 없는지 확인하세요. - 일반적으로 접속해 매장을 방문하세요. noclip을 끈 상태로 인도에서 두 입구를 지나고, 계단을 오르내리고, 옥상 출입구를 지나가 보세요.
- 캐노피를 열고 닫아 보세요. 패널 8개가 모든 위치에서 가이드 레일 안에 정렬되어 있어야 합니다. 비/눈 자동 닫힘은 따로 테스트하세요.
- 각 CCTV 화면을 열고, 서로 전환한 뒤 나가세요. 장면이 보여야 하고, 플레이어의 일반 시점/포커스가 돌아와야 합니다.
- 직원 계정으로 두 출입문 그룹을 잠그세요. 양쪽에서 충돌을 확인하세요. 잠금을 해제하고 근접 열림 애니메이션을 다시 확인하세요.
- 낮/밤 조명, 디스플레이 켜기/끄기, 유리, 간판, 좌석, 모든 모서리를 확인하세요. 건물 쪽으로, 또 반대쪽으로 걷고 운전해 스트리밍 전환을 점검하세요.
- 공용 모드에서 휴대폰/액세서리를 구매하세요. 비즈니스 모드에서는 재고 차감, 직원 주문, 도착/수령, 잔액 부족, 무단 접근을 확인하세요.
- 서버를 재시작하고 매장 모드, 재고, 대기 중인 배송이 유지되는지 확인하세요. 중복 수령/취소를 다시 시도해 보세요. 상품이나 환불이 중복으로 나타나면 안 됩니다. 여러 플레이어가 같은 매장 상태를 보는지 확인하세요.
클라이언트 F8 콘솔의 phonehubcheck는 실제 커버 정렬 상태를 보고합니다. 각 패널의 정렬 값은 1에 가까워야 합니다. 진단용일 뿐, 시각적 품질이나 충돌이 정확하다는 증거는 아닙니다. 자동 점검으로 모든 카메라 각도나 모든 서버 조합을 보증할 수는 없습니다.
8. 문제 해결과 업데이트
30120 포트 사용 중: 다른 서버 인스턴스가 이미 실행 중입니다. 두 번째 FXServer를 시작하지 말고 txAdmin(또는 호스팅 패널)에서 기존 것을 중지하세요.
제어가 없음: 두 리소스가 모두 시작되었는지, 이름이 바뀌지 않았는지, 플레이어가 제어 지점에 있는지 확인하세요. 클라이언트 F8과 서버 오류를 확인하세요.
직원 권한 없음: 설정된 직업, 숫자 직급, 서비스 카운터와의 거리, 선택된 직업 제공자를 확인하세요. 공용 상점 모드는 직원 권한을 부여하지 않습니다.
예전 맵/인터페이스가 계속 보임: 중복된 리소스/ensure 항목을 제거하세요. FiveM을 완전히 종료하고, 서버를 중지하고, 파일을 교체한 뒤 서버를 시작하고 FiveM을 다시 실행하세요. 재접속만으로는 오래된 스트리밍 에셋이 남을 수 있습니다. 클라이언트가 접속해 있는 동안에는 건물에서 멀리 있더라도 MLO를 핫 리로드하지 마세요.
되돌리기: 이 리소스들을 중지하고, 백업한 리소스 폴더와 설정을 복원한 뒤, 기존 txAdmin으로 재시작하세요. 일관된 데이터 백업을 의도적으로 복원하는 경우가 아니라면 데이터베이스/KVP 저장소는 보존하세요.
지원 요청에 대비해 제공된 릴리스 해시(SHA256.json)를 보관하세요.
PhoneHub OS와 소유권
Config.PhoneHubOS(phone/config/phonehub_business.lua)가 이 에디션을 제어합니다. ownership='both'는 게임 내 구매와 관리자 배정을 모두 허용합니다. 한 가지 방식만 허용하려면 'admin' 또는 'purchase'로 설정하세요. purchasePrice는 게임 내 화폐 금액입니다. 관리자는 phonehubowner <online player id>를 서버 콘솔에서 사용하거나, phonehub.admin ACE를 가진 상태로 사용합니다. 구매 결제가 대기 중인 동안에는 배정이 막힙니다. 소유자는 일시적인 플레이어 source 번호가 아니라 framework 캐릭터 식별자 기준으로 저장됩니다. 소유권이 생기면 기존의 영구 재고 및 운영 예산 시스템이 활성화됩니다.
소유자는 Business 탭에서 근처의 직원이나 매니저를 추가합니다. 이 독립 역할은 framework 신원 브리지를 통해 작동하며, 플레이어의 주 직업을 바꾸지 않습니다. 기존 PhoneHub 직업 역할과 설정된 관리자 권한도 계속 작동합니다. 기본적으로 매니저는 물품을 주문할 수 있고, 직원은 도착한 배송을 수령할 수 있습니다. 재고는 구매나 공급업체 배송이 확정될 때까지 예약 상태로 남습니다.
service='hybrid'는 직원 응대와 셀프서비스 결제 및 수리를 모두 허용합니다. 'self'는 직접 서비스만 허용하고, 'staff'는 이 매장에서 고객이 승인한 직원 제안이 있어야 합니다. 단독 제품은 기존 쇼핑 OS를 그대로 유지합니다.
매장 키오스크에 다가가 E를 누르세요. Shop 탭이 실제 보호된 Pulse 모델을 불러오며, 끌어서 회전, 앞/뒷면 확인, 확대, 선택한 마감을 볼 수 있습니다. 가격은 휴대폰 서버에서 받아 옵니다. 결제에는 확인이 필요하며, 설정된 인벤토리, 돈, 박스 휴대폰 전달을 사용합니다. 시간 초과가 결제 실패의 증거는 아니므로, 다시 시도하기 전에 인벤토리와 결제 기록을 확인하세요.
고객은 Help 탭에서 판매나 수리 도움을 요청하고 대기 번호를 받습니다. 직원은 Counter 탭에서 근처 고객을 선택해 제안을 준비하며, 그 고객만 승인하고 결제할 수 있습니다. 두 사람 모두 같은 매장, 같은 routing bucket에 있어야 합니다. 수리 승인은 선택한 고유 기기와 견적 가격에 묶이며, 기기를 바꾸면 무효가 됩니다.
직원 응대 수리에서는 기술자가 빈 수리 작업대에서 단말기를 열고, 고객의 수리 제안을 준비한 뒤, 수락될 때까지 그 자리에 있어야 합니다. 작업대는 결제 전에 예약됩니다. 결제가 완료된 수리는 그 플레이어를 기술자로 하여 조립 과정을 진행하며, 셀프서비스는 매장 기술자를 사용합니다. 기기 수리는 휴대폰 엔진이 담당하며, 서버 세션이 중단되어도 결제된 작업을 복구합니다. 클라이언트 프롭은 인벤토리 휴대폰을 만들거나 교체하지 않습니다.
옥상과 카운터 제어 지점의 Space 탭에서 캐노피, 공조, 잠금, 조명, 디스플레이를 제어합니다. 완성된 MLO의 구조, 날씨 보호, 바닥, 좌석은 그대로 유지됩니다.