# ges233/variationsofyesterday architecture

> Architecture diagram of the GitHub repository ges233/variationsofyesterday, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ges233/variationsofyesterday
- Repository: https://github.com/ges233/variationsofyesterday

## Overview

Variations of Yesterday is an experimental Minecraft mod centered on a tick-driven ecological Mandate Engine. Server lifecycle hooks start the engine; active-player ticks enter an actor as events, which update a spatial stress lattice and publish snapshots. A development-only client HUD reads those snapshots. The action channel and inbound event types establish extension points, but no gameplay event producers or action producers are shown. README feature detail is minimal, so this map reflects the implemented prototype; several edges are grounded in the sampled implementation excerpts.

Main entry points: [`src/main/scala/moe/chestnut/awa/voy/MandateRuntime.scala`](https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/MandateRuntime.scala) (Engine Runtime), [`src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateAgent.scala`](https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateAgent.scala) (Mandate Actor), [`src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateState.scala`](https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateState.scala) (Cell Dynamics), [`src/client/scala/moe/chestnut/awa/voy/hud/MandateHud.scala`](https://github.com/ges233/variationsofyesterday/blob/master/src/client/scala/moe/chestnut/awa/voy/hud/MandateHud.scala) (Mandate HUD)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Game Integration"]
  node_mod_init["Mod Initializer"]
  node_runtime["Engine Runtime"]
end

subgraph group_engine["Mandate Engine"]
  node_event_protocol["Event Protocol<br/>[EventMsg.scala]"]
  node_action_protocol["Action Protocol<br/>[ActionMsg.scala]"]
  node_agent["Mandate Actor<br/>[MandateAgent.scala]"]
end

subgraph group_model["Simulation Model"]
  node_grid["Stress Lattice<br/>[MandateGrid.scala]"]
  node_state["Cell Dynamics<br/>[MandateState.scala]"]
  node_solver["ODE Solver<br/>[ODESolver.scala]"]
  node_plant_dto["Plant Data<br/>[PlantDTO.scala]"]
end

subgraph group_client["Client View"]
  node_client_init["Client Initializer"]
  node_hud["Mandate HUD<br/>[MandateHud.scala]"]
end

node_player(("Player"))
node_minecraft["Minecraft Server"]

node_minecraft -->|"fires lifecycle"| node_mod_init
node_mod_init -->|"starts and ticks"| node_runtime
node_runtime -->|"reads tick state"| node_minecraft
node_runtime -->|"sends tick"| node_event_protocol
node_runtime -->|"creates actor"| node_agent
node_agent -->|"handles messages"| node_event_protocol
node_agent -->|"steps lattice"| node_grid
node_grid -->|"advances cells"| node_state
node_state -->|"integrates equations"| node_solver
node_agent -->|"publishes snapshot"| node_runtime
node_agent -.->|"emits actions"| node_action_protocol
node_runtime -->|"drains queue"| node_action_protocol
node_client_init -->|"registers in development"| node_hud
node_hud -->|"reads chunk state"| node_runtime
node_player -.->|"views overlay"| node_hud
node_plant_dto -.->|"models plant"| node_state

click node_mod_init "https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/VariationsOfYesterday.scala"
click node_runtime "https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/MandateRuntime.scala"
click node_event_protocol "https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/inner/event/EventMsg.scala"
click node_action_protocol "https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/inner/action/ActionMsg.scala"
click node_agent "https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateAgent.scala"
click node_grid "https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateGrid.scala"
click node_state "https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateState.scala"
click node_solver "https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/helpers/ODESolver.scala"
click node_plant_dto "https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/inner/plant/PlantDTO.scala"
click node_client_init "https://github.com/ges233/variationsofyesterday/blob/master/src/client/scala/moe/chestnut/awa/voy/VariationsOfYesterdayClient.scala"
click node_hud "https://github.com/ges233/variationsofyesterday/blob/master/src/client/scala/moe/chestnut/awa/voy/hud/MandateHud.scala"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mod_init,node_runtime toneBlue
class node_event_protocol,node_action_protocol,node_agent toneAmber
class node_grid,node_state,node_solver,node_plant_dto,node_minecraft toneMint
class node_client_init,node_hud toneRose
class node_player toneIndigo
```

## Components

### Game Integration

- [Mod Initializer](https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/VariationsOfYesterday.scala): `src/main/scala/moe/chestnut/awa/voy/VariationsOfYesterday.scala`
- [Engine Runtime](https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/MandateRuntime.scala): `src/main/scala/moe/chestnut/awa/voy/MandateRuntime.scala`

### Mandate Engine

- [Event Protocol](https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/inner/event/EventMsg.scala): `src/main/scala/moe/chestnut/awa/voy/inner/event/EventMsg.scala`
- [Action Protocol](https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/inner/action/ActionMsg.scala): `src/main/scala/moe/chestnut/awa/voy/inner/action/ActionMsg.scala`
- [Mandate Actor](https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateAgent.scala): `src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateAgent.scala`

### Simulation Model

- [Stress Lattice](https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateGrid.scala): `src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateGrid.scala`
- [Cell Dynamics](https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateState.scala): `src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateState.scala`
- [ODE Solver](https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/helpers/ODESolver.scala): `src/main/scala/moe/chestnut/awa/voy/helpers/ODESolver.scala`
- [Plant Data](https://github.com/ges233/variationsofyesterday/blob/master/src/main/scala/moe/chestnut/awa/voy/inner/plant/PlantDTO.scala): `src/main/scala/moe/chestnut/awa/voy/inner/plant/PlantDTO.scala`

### Client View

- [Client Initializer](https://github.com/ges233/variationsofyesterday/blob/master/src/client/scala/moe/chestnut/awa/voy/VariationsOfYesterdayClient.scala): `src/client/scala/moe/chestnut/awa/voy/VariationsOfYesterdayClient.scala`
- [Mandate HUD](https://github.com/ges233/variationsofyesterday/blob/master/src/client/scala/moe/chestnut/awa/voy/hud/MandateHud.scala): `src/client/scala/moe/chestnut/awa/voy/hud/MandateHud.scala`

### Other components

- **Player**
- **Minecraft Server**

## Connections

- Minecraft Server → Mod Initializer: fires lifecycle (evidence: `src/main/scala/moe/chestnut/awa/voy/VariationsOfYesterday.scala`)
- Mod Initializer → Engine Runtime: starts and ticks (evidence: `src/main/scala/moe/chestnut/awa/voy/VariationsOfYesterday.scala`)
- Engine Runtime → Minecraft Server: reads tick state (evidence: `src/main/scala/moe/chestnut/awa/voy/MandateRuntime.scala`)
- Engine Runtime → Event Protocol: sends tick (evidence: `src/main/scala/moe/chestnut/awa/voy/MandateRuntime.scala`)
- Engine Runtime → Mandate Actor: creates actor (evidence: `src/main/scala/moe/chestnut/awa/voy/MandateRuntime.scala`)
- Mandate Actor → Event Protocol: handles messages (evidence: `src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateAgent.scala`)
- Mandate Actor → Stress Lattice: steps lattice (evidence: `src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateAgent.scala`)
- Stress Lattice → Cell Dynamics: advances cells (evidence: `src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateGrid.scala`)
- Cell Dynamics → ODE Solver: integrates equations (evidence: `src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateState.scala`)
- Mandate Actor → Engine Runtime: publishes snapshot (evidence: `src/main/scala/moe/chestnut/awa/voy/MandateRuntime.scala`)
- Mandate Actor → Action Protocol: emits actions (evidence: `src/main/scala/moe/chestnut/awa/voy/inner/mandate/MandateAgent.scala`)
- Engine Runtime → Action Protocol: drains queue (evidence: `src/main/scala/moe/chestnut/awa/voy/MandateRuntime.scala`)
- Client Initializer → Mandate HUD: registers in development (evidence: `src/client/scala/moe/chestnut/awa/voy/VariationsOfYesterdayClient.scala`)
- Mandate HUD → Engine Runtime: reads chunk state (evidence: `src/client/scala/moe/chestnut/awa/voy/hud/MandateHud.scala`)
- Player → Mandate HUD: views overlay
- Plant Data → Cell Dynamics: models plant
