Files
roblox-project/bunsik-tycoon/NETWORK.md
2026-10-14 01:34:37 +09:00

90 lines
5.9 KiB
Markdown

# 서버 ↔ 클라이언트 약속 (2026-10-14 개편)
서버는 상태를 **속성(Attribute)** 으로 내보내고, 클라이언트는 `Remotes.Action:FireServer(kind, arg)` 로 요청합니다.
알림은 `Remotes.Notify:FireClient(player, key, args)` 이고, 글자는 클라이언트가 `Locale.t(lang, key, args)` 로 씁니다.
경제·배치 규칙은 공용 모듈(`src/shared/Economy.luau`, `Shop.luau`, `Floor.luau`)이 원본입니다. 클라이언트는 같은 모듈로 값·미리보기를 계산하고, 서버가 다시 검사합니다.
## 플레이어 속성 (Player)
| 속성 | 형 | 뜻 |
|---|---|---|
| Ready | bool | 세이브 로드 끝 |
| Plot | number | 내 부지 번호 |
| Money, Earned | number | 돈, 지금까지 번 돈 |
| Levels | string | 갈래 레벨 `"Stage=1,Menu=2,Price=0,Speed=1,Stove=0,Tray=0,Staff=1"` (Economy.TRACK_ORDER 순서). `Shared.Codec.decodeMap` 로 읽음 |
| Stage | number | 건물 단계 1 포장마차, 2 실내, 3 2층 |
| Seats, Tables | number | 놓은 의자 수(= 손님 자리 수), 테이블 수 |
| Layout | string | 배치 JSON(`Floor.Layout` 모양). `HttpService:JSONDecode` 후 `Floor.clean` |
| Staff | string | 고용한 알바 수 `"Cook=1,Server=0,Promoter=0"` |
| Strike | bool | 시급이 모자라 알바생이 쉬는 중 |
| Wage | number | 1분마다 주는 시급 합계 |
| RushUntil | number | 손님 러시가 끝나는 서버 시각(`workspace:GetServerTimeNow()` 기준, 0이면 없음) |
| PromoteAt | number | 다음 홍보를 할 수 있는 서버 시각(광고 없이) |
| PromoteAdAt | number | 광고를 보고 홍보할 수 있는 서버 시각 |
| KickCredits | number | 남은 "손님 쫓아내기" 횟수(유료로 산 것) |
| ShopName | string | 내가 정한 가게 이름 원문("" = 기본 이름). 다른 사람에게 보이는 이름은 부지 속성 ShopName(필터 거친 글) |
| Rainbow | bool | 무지개 이름 켜기 설정 |
| RainbowOwned | bool | 무지개 이름 게임패스 보유 |
| Design | string | 건물 디자인 id(Economy.DESIGNS) |
| DesignsOwned | string | 유료 디자인 보유 목록 `"Candy,Hanok"` |
| Double | bool | 2배 수익 |
| Boost | number | 돈 부스트 팩 지급액 |
| Tut | number | 튜토리얼 단계(0 끝, 1 조리대로, 2 서빙, 3 사기) |
| Carry, Hand | number, string | 든 접시 수, 든 메뉴 `"Gimbap,Sundae"` |
| Orders | string | 메뉴별 열린 주문 `"Tteokbokki=2,Gimbap=1"` |
| Lang, LangSetting, MouseLook, Sfx, Dev | | 설정(예전과 같음) |
## 부지 모델 속성 (workspace.BunsikWorld.Plots.PlotN, 모두에게 보임)
| 속성 | 뜻 |
|---|---|
| OwnerId, OwnerName | 플레이어 가게 주인 |
| Npc | 이웃 가게(NPC) 번호 |
| Level | 가게 레벨(Economy.shopLevel) |
| Stage | 건물 단계 |
| Menus | 파는 메뉴 `"Tteokbokki,Gimbap"` (메뉴판) |
| PriceMult | 판매 금액 배율(메뉴판 값) |
| ShopName | 필터를 거친 가게 이름("" = 기본 이름 "{name}의 분식집") |
| Rainbow | 무지개 이름(게임패스 + 켜짐) |
| Design | 건물 디자인 |
| ShieldUntil | 손님 쫓아내기 보호가 끝나는 서버 시각 |
| Origin | 부지 기준 CFrame. 배치 좌표 (x, z, 층 f) → 월드: `Origin * CFrame.new(x, Floor.BASE_Y + (f == 2 and Floor.FLOOR2_Y or 0), z)` |
## 배치 물건 모델
부지 안 `Upgrades/Furniture` 폴더에 서버가 짓습니다. 꾸미기 화면이 눌러서 고를 수 있게 모델마다 속성을 붙입니다.
- `ItemKind` = "table" | "chair" | "decor" | "stove", `ItemIndex` = Layout 목록 번호(조리대는 1)
- 조리대(포장마차 수레)는 `Plot.Base.Stall` 모델 그대로 옮깁니다(인스턴스가 바뀌지 않아서 조리대 버튼이 계속 붙어 있음).
## 요청 (Action kind, arg)
| kind | arg | 서버가 하는 일 |
|---|---|---|
| `cookStart`, `cook` | 메뉴 | 요리 창(예전과 같음) |
| `upgrade` | 갈래 id | 다음 단계 구매 |
| `buySeat` | 테이블 번호 또는 nil | 의자 1개(빈 쪽에 자동 배치) |
| `buyTable` | nil | 테이블 + 의자 1개(빈 곳 자동 배치) |
| `buyDecor` | 소품 id | 소품 1개(빈 곳 자동 배치) |
| `buyOffer` | `"Seat"`/`"Table"`/갈래 id | 화면 아래 추천 막대의 [사기] |
| `move` | `{kind="stove"/"table"/"decor", i, x, z, f, r}` | 옮기기(Floor.move로 검사). 의자는 `{kind="chair", i, x=쪽(1~4), z=테이블 번호(0=그대로)}` |
| `hire`, `fire` | 역할 id | 알바 고용·해고 |
| `rename` | 문자열(최대 20자) | 이름 바꾸기(TextService 필터) |
| `rainbow` | bool | 무지개 이름 켜기/끄기. 없으면 게임패스 결제 창 |
| `design` | 디자인 id | 디자인 바꾸기(실내 분식집부터). 유료인데 없으면 결제 창 |
| `promote` | `{ad=bool}` | 홍보. ad=true면 보상형 광고(서버가 AdService로 띄움), 아니면 대기 시간 확인 후 바로 |
| `kick` | 부지 번호 | 손님 쫓아내기. 횟수가 있으면 바로 쓰고, 없으면 결제 창(결제되면 그 부지에 씀) |
| `rush` | nil | 손님 러시 결제 창 |
| `visit`, `lang`, `mouseLook`, `sfx`, `pass`, `boost`, `dev_*` | | 예전과 같음 |
## 알림 키 (Notify)
예전 키(`purchased` 등)에 더해:
- `upgraded {track, level}` 갈래 업그레이드, `newMenu {menu}`, `expanded`(실내), `floor2`(2층)
- `seatAdded`, `tableAdded`, `decorAdded {kind}`, `noSpace`(놓을 곳 없음), `seatMax`, `tableMax`, `needStage`
- `placeFail {why}`: why = bounds | overlap | reserved | floor | blocked | chair
- `hired {role}`, `fired {role}`, `staffLocked`, `staffMax`, `strike`(시급 부족), `strikeOver`
- `renamed`, `nameRejected`(필터 실패·빈 이름), `designSet {design}`, `designLocked`(실내 분식집부터)
- `promoted {n}`, `promoteNone`(데려올 손님 없음), `promoteFull`(빈자리 없음), `promoteWait {sec}`, `adUnavailable`
- `kicked {n, shop}`(내가 쫓아냄), `kickedBy {name}`(내 가게 손님이 쫓겨남), `shielded`(보호 중), `kickOwn`(내 가게는 안 됨)
- `rushOn {min}`, `notEnough {need}`