# Machi – Multiverse World Design - GitHub Analogy

This document captures the current working mental model for Machi’s world, story, and character system.

The core goal:  
**Machi should exist even if every server is turned off.**  
Everything online is optional, sleeping, or player-hosted.

---

## 1\. Machi is a multiverse, not a single world

There is no single “true” Machi world.

Instead there are:

* **Personal worlds** (offline, local saves)
    
* **Co-op worlds** (player-hosted)
    
* **Online towns** (public shards that sleep when empty)
    
* **Forked continuities** (branches)
    

All of them use the same:

* world seed
    
* event log
    
* snapshot format
    

A world can be:

* created offline
    
* later uploaded
    
* forked
    
* merged back
    
* or turned into a public town
    

Nothing requires a permanent server.

---

## 2\. Worlds sleep

When nobody is in a world:

* its simulation stops
    
* its spirits stop
    
* its SOUP ecology freezes
    
* only its snapshot + event log remain
    

When someone enters:

* the world wakes
    
* it fast-forwards using deterministic catch-up
    
* spirits generate “while you were away” context
    

This creates the illusion of persistence without operational cost.

---

## 3\. AI characters live on the player’s machine

Characters (Pixel, etc.) do **not** require servers to think.

The model:

* AI runs locally on the player (or host) machine
    
* Only the **results** (movement, dialogue lines, world edits) are written to the world log
    

In online towns:

* one client is elected **authority**
    
* that client runs the spirits
    
* commits NPC actions
    
* others observe
    

This avoids:

* server AI costs
    
* duplicated “brains”
    
* merge chaos
    

---

## 4\. World state is event-sourced and mergeable

World =  
`seed + event log + snapshots`

Everything that changes the world is an **event**:

* tile placed
    
* object moved
    
* NPC spoke
    
* SOUP grew
    

Worlds can:

* branch
    
* diverge
    
* be merged like Git
    

---

## 5\. Tile & world merges

Each event has a **write set**:

* e.g. `(room_id, layer, x, y)` or `object_id`
    

Two events auto-merge if:

* their write sets don’t overlap
    

Conflicts occur when:

* same tile
    
* same structure
    
* same NPC state
    

UI is **map-based**, not diff-based:

* show BASE / YOURS / THEIRS / MERGED
    
* resolve conflicts by clicking tiles or structures
    
* preview merged world
    
* even walk around before finalizing
    

Some things merge automatically:

* tiles in different locations
    
* decorations
    
* SOUP growth
    
* bulletin posts
    

Some things don’t:

* inventories
    
* unique items
    
* exclusive story choices  
    → these cause forks or require manual choice.
    

---

## 6\. Mainline + forks is intentional

There is a **mainline world** that is curated and stable.

There are **forks** that:

* experiment
    
* move faster
    
* become popular
    
* form their own canons
    

Popularity affects **discovery**, not **authority**.

Mainline can:

* merge rooms or story from forks
    
* but forks never have to converge
    

Machi is a platform for **worldlines**, not a single canon.

---

## 7\. Characters are not linear — they have story graphs

Characters don’t have one timeline.  
They have a **story DAG**:

Nodes:

* trauma
    
* bonds
    
* losses
    
* discoveries
    
* growth
    

Edges:

* “caused”
    
* “happened before”
    
* “recontextualizes”
    

This allows:

* retroactive backstories (A-1 before A)
    
* reinterpretation without deleting old stories
    
* unreliable narrators
    
* multiple truths
    

Canon is the best-supported story graph, not a single log.

---

## 8\. Side stories feed canon

Side worlds and forks produce **story atoms** like:

* “Pixel lost her village”
    
* “Pixel bonded with Jin”
    
* “Pixel learned to trust fire”
    

These are:

* clustered by AI
    
* reviewed by humans + AI
    
* proposed to canon
    
* accepted / rejected / edited
    

Canon Pixel evolves via merges.

---

## 9\. Story changes real behavior

Story nodes don’t just sit in lore files.

They map into:

* emotional weights
    
* fears
    
* trust
    
* curiosity
    
* topic bias
    
* quest generation
    
* NPC movement preferences
    

So when a story merges:

* dialogue changes
    
* reactions change
    
* behavior changes
    

Players feel it even if they never read the lore.

---

## 10\. Shared “information sheet”

Across the multiverse there is a **public ledger**:

* discoveries
    
* rumors
    
* lore fragments
    
* world seeds
    
* postcards from spirits
    

This is:

* append-only
    
* mergeable
    
* not authoritative
    

It connects parallel worlds without breaking offline play.

---

## 11\. GitHub is the right mental model

Machi is:

* branches
    
* PRs
    
* commits
    
* forks
    
* maintainers
    
* merges
    

But instead of code:

* rooms
    
* tiles
    
* NPCs
    
* story nodes
    

Open canon is a feature, not a spoiler.

---

## 12\. The core design law

Everything that makes Machi *Machi* must run locally.  
Anything online must be optional, sleeping, or player-hosted.

If all servers disappear, Machi still exists.

---

If future me ever forgets what Machi is supposed to be:  
it’s not an MMO.  
it’s not a game with lore.

It’s a **multiverse of living worlds and evolving spirits**.

— @[Pixel](@pix-el), @[Sprited Dev](@sprited)