현재에는 역사가 있다
WorldState를 한 시점의 모습이 아니라 과거부터 이어지는 변화의 결과로 다룹니다.
DESIGN / OVERVIEW
여기는 API 레퍼런스가 아닙니다.
‘MachiVerse를 MachiVerse답게 유지하는 계약’을 보는 곳입니다.
南雲 澪 / Mio Nagumo
SYSTEM DEVELOPMENT
SYSTEM DEVELOPMENT
01 / DESIGN PRINCIPLES
세계의 ‘지금’뿐 아니라,
‘왜 지금 이렇게 되었는가’를 다룹니다.
MachiVerse의 중심은 표면적인 기능 수를 늘리는 것이 아니라 세계 요소를 인과로 연결하는 데 있습니다. 도시, 주민, 자연환경, 사회관계를 고정된 완성품으로 두지 않고 과거 상태와 선택의 누적에서 현재가 형성되고 현재의 변화가 미래에 남는 세계를 지향합니다.
재현 가능성을 계약으로 둔다
같은 World Seed, simulation-affecting Config, 유효 Operation 집합・순서・적용 Step에서는 같은 논리적 세계 결과를 얻는 것을 기본 계약으로 합니다.
책임을 분리한다
Core, Gateway, General View, Admin View를 독립된 실행・build・배포 단위로 취급합니다.
경계는 Protocol로 만든다
내부 타입이나 공용 DTO DLL을 통신 계약으로 공유하지 않고 versioned Protocol / schema를 컴포넌트 경계로 사용합니다.
02 / TOP-LEVEL COMPONENTS
네 개로 나누지만,
세계는 하나입니다.
코드, build, 배포, 실행 단위까지 독립시키고 다른 컴포넌트 내부 메서드를 직접 호출하지 않으며 Protocol을 통해서만 연계합니다.
Simulation Core권위 있는 WorldState / Simulation Step / Operation / Persistence
GatewayAuth / Cache / Mediation / Publication / Resync
General ViewDiver / Spectator / Browser UI / Prediction
Admin ViewHealth / Log / Metrics / Config / Operations
정본은 Core. Gateway cache와 View 표시 상태는 파생 상태입니다.
General View와 Admin View는 Core에 직접 연결하지 않습니다. Gateway가 외부 연결, 인증・인가, cache, Operation 집약, publication, 재동기화를 담당합니다.
03 / HIGH-LEVEL SPECIFICATION
먼저 알아둘
전체 사양.
다음은 현재 전체 아키텍처가 정의하는 표준 구성의 핵심입니다. 개별 Protocol과 시뮬레이션 영역의 상세 내용은 본체 저장소 설계 문서를 기준으로 합니다.
| 항목 | 표준 설계 | 의미 |
|---|---|---|
| 세계 상태 정본 | Simulation Core만 | Gateway cache, View 표시 상태, prediction은 권위가 없는 파생 상태입니다. |
| 표준 토폴로지 | Simulation Core 1 / Gateway 1:N | General View / Admin View는 Gateway를 통해 연결되며 표준 Protocol에는 Core↔Core 통신이 없습니다. |
| 권위 있는 시간 | 정수 기반 Simulation Step | 사회적 달력・시계와 별개이며 표준 계산 빈도는 30Hz, 외부 Config로 변경 가능합니다. |
| 결정론 | 같은 재현 조건에서 같은 논리 결과 | 처리 속도, OS scheduling, thread 완료 순서, Gateway 수, network 도착 경쟁을 world outcome에 반영하지 않습니다. |
| 통신 경계 | Versioned Protocol / schema | Major 불일치는 연결 거부, 같은 Major의 새 Minor는 후방 호환을 유지하는 설계입니다. |
| Config | 각 component가 자신의 외부 Config 소유 | simulation-affecting Config와 display / ops-only Config를 구분해 명시적 안전 경계에서 적용합니다. |
| View prediction | 비권위・presentation-only | Diver 조작에 local prediction / correction을 사용해도 최종적으로 Core 확정 상태와 reconcile합니다. |
04 / AUTHORITATIVE OPERATION FLOW
조작은 예측할 수 있지만,
확정하는 것은 Core입니다.
General View는 실시간 조작감을 위해 local prediction / correction을 사용할 수 있습니다. 하지만 예측 상태는 정본이 아니며 Gateway와 Simulation Core를 거쳐 확정된 상태로 reconcile합니다.
General View
↓
Gateway
↓ auth / authorization / mediation
Simulation Core
↓ authoritative apply
confirmed WorldState
↓
Gateway → View reconciliation05 / DESIGN VS CURRENT ALPHA
전체 설계와
현재 실행 가능한 범위는 같지 않습니다.
이 페이지에는 장기 표준 설계도 포함됩니다. 현재 develop에서 실제 연결된 범위는 Alpha 1.0 vertical slice이며 multi-Gateway failover, production OIDC / TLS deployment acceptance, 대규모 Resident / economy / governance scenario 등은 향후 work package입니다.
지금 실제로 연결된 것
Core–Gateway 실제 gRPC, General / Administration View 실제 browser session, FULL / DELTA publication, 최소 Operation, Config read / change, persistence / recovery 등.
설계 및 향후 구현
Core 1 : Gateway 1:N 표준 토폴로지 전체, multi-Gateway failover, production deployment acceptance, 성능 / soak, 대규모 세계 시나리오 등.
DEEP DIVE
상위 구조에서,
개별 설계 문서로.
공식 웹사이트는 이해를 위한 진입점으로 두고 변경되는 기술 사양의 정본은 본체 저장소에 모읍니다. 구현 판단이나 Protocol 변경 시 최신 설계 문서를 확인해 주세요.
