The present has a history
World state is treated as the result of change over time rather than only as a snapshot.
DESIGN / OVERVIEW
This is not an API reference.
It is about the contracts that keep MachiVerse structurally consistent.
Mio Nagumo / 南雲 澪
SYSTEM DEVELOPMENT
SYSTEM DEVELOPMENT
01 / DESIGN PRINCIPLES
Not just what the world is now,
but why it became this way.
The central idea is not to maximize the number of surface features, but to connect world elements through causality. Cities, residents, natural environments, and social relationships are intended to emerge from accumulated state and choices, with present changes remaining part of the future.
Reproducibility is a contract
The same World Seed, simulation-affecting Config, valid Operation set and order, and application Steps should produce the same logical world result.
Responsibilities stay separated
Core, Gateway, General View, and Admin View are independent execution, build, and distribution units.
Protocol defines the boundary
Internal types and shared DTO DLLs do not become the cross-component contract; versioned Protocol / schema does.
02 / TOP-LEVEL COMPONENTS
Four units.
One connected world.
Code, build, distribution, and execution remain independent. Components do not directly call each other's internal methods; they communicate through Protocol.
Simulation CoreAuthoritative WorldState / Simulation Step / Operation / Persistence
GatewayAuth / Cache / Mediation / Publication / Resync
General ViewDiver / Spectator / Browser UI / Prediction
Admin ViewHealth / Log / Metrics / Config / Operations
Core is authoritative. Gateway cache and View state are derived.
General View and Admin View do not connect directly to Core. Gateway handles external connectivity, authentication and authorization, cache, Operation aggregation, publication, and resynchronization so those responsibilities stay outside the world-state authority.
03 / HIGH-LEVEL SPECIFICATION
The system-level facts
to know first.
The following points summarize the current top-level architecture. Individual Protocols and simulation domains remain defined by the source documents in the main repository.
| Area | Standard design | Meaning |
|---|---|---|
| World authority | Simulation Core only | Gateway cache, View display state, and prediction are non-authoritative derived state. |
| Standard topology | Simulation Core 1 / Gateway 1:N | General View and Admin View connect through Gateway. Standard Protocol has no Core↔Core communication. |
| Authoritative time | Integer Simulation Step | Separate from social clocks and calendars. The standard compute frequency is 30Hz and configurable externally. |
| Determinism | Same replay conditions, same logical result | Processing speed, OS scheduling, thread completion order, Gateway count, and network arrival races must not determine world outcome. |
| Communication boundary | Versioned Protocol / schema | Major mismatch is rejected; new Minor versions within the same Major maintain backward compatibility by design. |
| Config | Each component owns its external Config | Simulation-affecting Config is distinguished from display / operations-only Config and applied at explicit safe boundaries. |
| View prediction | Non-authoritative, presentation-only | Local prediction / correction may improve responsiveness, but state reconciles to Core-confirmed results. |
04 / AUTHORITATIVE OPERATION FLOW
Prediction can be local.
Authority stays in Core.
General View may use local prediction and correction so Diver actions feel responsive. That predicted state is never authoritative and must reconcile with the state confirmed through Gateway and Simulation Core.
General View
↓
Gateway
↓ auth / authorization / mediation
Simulation Core
↓ authoritative apply
confirmed WorldState
↓
Gateway → View reconciliation05 / DESIGN VS CURRENT ALPHA
The architecture target
is larger than today's Alpha.
This page includes parts of the intended standard design. The current develop implementation is the Alpha 1.0 vertical slice. Multi-Gateway failover, production OIDC / TLS deployment acceptance, large Resident / economy / governance scenarios, and other work remain future packages.
Connected today
Real Core–Gateway gRPC, real General / Administration View browser sessions, FULL / DELTA publication, a minimal Operation path, Config read / change, persistence, and recovery.
Design target and later work
The broader Core 1 : Gateway 1:N standard topology, multi-Gateway failover, production deployment acceptance, performance / soak work, and large-scale world scenarios.
DEEP DIVE
From the overview
to detailed design.
The official site stays at the explanatory layer while the main repository remains the source of truth for changing technical specifications. Implementation and Protocol changes should always consult the current source documents.
