# oliverhesse/formationarrays architecture

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

- Interactive diagram: https://gitdiagram.com/oliverhesse/formationarrays
- Repository: https://github.com/oliverhesse/formationarrays

## Overview

Formation Arrays is a Minecraft mod that discovers typed nodes in a dimension, activates formations when their node requirements are met, tracks those formations, and synchronizes updates to clients. Its main runtime flow runs from world/node changes through the dimension node manager and formation manager into formation instances; persisted dimension state and client patches support that lifecycle. The excerpts show key manager and serialization behavior, but not every registration or event-dispatch detail, so uncertain wiring is omitted.

Main entry points: [`src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManager.java`](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManager.java) (Dimension formations), [`src/main/java/net/lucent/formation_arrays/core/nodes/DimensionNodeManager.java`](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/nodes/DimensionNodeManager.java) (Dimension nodes), [`src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManagerPatch.java`](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManagerPatch.java) (Formation patch), [`src/main/java/net/lucent/formation_arrays/api/CoreRegistries.java`](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/api/CoreRegistries.java) (Core registries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_node_api["Node API"]
  node_node_type["Node types"]
  node_node_manager_api["Node manager API<br/>[NodeManager.java]"]
  node_node_providers["Node providers"]
  node_capabilities["Node capabilities"]
  node_block_util["Block lookup<br/>[BlockUtil.java]"]
end

subgraph group_formation_api["Formation API"]
  node_registries["Core registries"]
  node_formation["Formation definition<br/>[Formation.java]"]
  node_instance["Formation instance"]
  node_state_handler["State contract<br/>[StateHandler.java]"]
  node_simple_state["Simple state"]
end

subgraph group_server_runtime["Server Runtime"]
  node_dimension_nodes[("Dimension nodes")]
  node_activation["Activation recipes"]
  node_dimension_formations[("Dimension formations")]
  node_placed["Placed formation"]
  node_formation_events["Formation events"]
end

subgraph group_client_sync["Client Sync"]
  node_patch_packet["Formation patch packet"]
  node_patch["Formation patch"]
  node_client_manager[("Client formations")]
end

node_world(("Minecraft world"))

node_registries -->|"registers type"| node_formation
node_registries -->|"registers factories"| node_node_providers
node_simple_state -->|"implements"| node_state_handler
node_simple_state -->|"checks nodes"| node_node_manager_api
node_dimension_nodes -->|"resolves types"| node_node_type
node_dimension_nodes -->|"checks providers"| node_block_util
node_dimension_nodes -->|"reads entity capability"| node_capabilities
node_block_util -->|"queries capability"| node_capabilities
node_world -.->|"provides node state"| node_dimension_nodes
node_dimension_formations -->|"gets node manager"| node_dimension_nodes
node_dimension_formations -->|"finds formations"| node_activation
node_dimension_formations -->|"tries activation"| node_formation
node_dimension_formations -->|"creates instances"| node_instance
node_dimension_formations -->|"tracks placements"| node_placed
node_formation_events -->|"dispatches changes"| node_dimension_formations
node_dimension_nodes -->|"posts node events"| node_formation_events
node_dimension_formations -->|"builds updates"| node_patch
node_patch -->|"transmitted by"| node_patch_packet
node_patch -->|"applies changes"| node_client_manager
node_client_manager -->|"ticks instances"| node_instance

click node_registries "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/api/CoreRegistries.java"
click node_formation "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/api/formations/Formation.java"
click node_instance "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/api/formations/FormationInstance.java"
click node_state_handler "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/api/formations/StateHandler.java"
click node_simple_state "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/SimpleStateHandler.java"
click node_node_type "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/api/nodes/FormationNodeType.java"
click node_node_manager_api "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/api/nodes/NodeManager.java"
click node_node_providers "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/api/nodes/type_provider/block/BlockNodeTypeProvider.java"
click node_capabilities "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/capabilities/CoreCapabilities.java"
click node_block_util "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/util/BlockUtil.java"
click node_dimension_nodes "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/nodes/DimensionNodeManager.java"
click node_activation "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/FormationActivationHelper.java"
click node_dimension_formations "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManager.java"
click node_placed "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/PlacedFormation.java"
click node_formation_events "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/FormationEventHandler.java"
click node_patch_packet "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/network/DimensionFormationManagerPatchPacket.java"
click node_patch "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManagerPatch.java"
click node_client_manager "https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/client/ClientDimensionFormationManager.java"

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_node_type,node_node_manager_api,node_node_providers,node_capabilities,node_block_util toneBlue
class node_registries,node_formation,node_instance,node_state_handler,node_simple_state toneAmber
class node_dimension_nodes,node_activation,node_dimension_formations,node_placed,node_formation_events toneMint
class node_patch_packet,node_patch,node_client_manager toneRose
class node_world toneIndigo
```

## Components

### Node API

- [Node types](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/api/nodes/FormationNodeType.java): `src/main/java/net/lucent/formation_arrays/api/nodes/FormationNodeType.java`
- [Node manager API](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/api/nodes/NodeManager.java): `src/main/java/net/lucent/formation_arrays/api/nodes/NodeManager.java`
- [Node providers](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/api/nodes/type_provider/block/BlockNodeTypeProvider.java): `src/main/java/net/lucent/formation_arrays/api/nodes/type_provider/block/BlockNodeTypeProvider.java`
- [Node capabilities](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/capabilities/CoreCapabilities.java): `src/main/java/net/lucent/formation_arrays/capabilities/CoreCapabilities.java`
- [Block lookup](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/util/BlockUtil.java): `src/main/java/net/lucent/formation_arrays/util/BlockUtil.java`

### Formation API

- [Core registries](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/api/CoreRegistries.java): `src/main/java/net/lucent/formation_arrays/api/CoreRegistries.java`
- [Formation definition](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/api/formations/Formation.java): `src/main/java/net/lucent/formation_arrays/api/formations/Formation.java`
- [Formation instance](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/api/formations/FormationInstance.java): `src/main/java/net/lucent/formation_arrays/api/formations/FormationInstance.java`
- [State contract](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/api/formations/StateHandler.java): `src/main/java/net/lucent/formation_arrays/api/formations/StateHandler.java`
- [Simple state](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/SimpleStateHandler.java): `src/main/java/net/lucent/formation_arrays/core/formations/SimpleStateHandler.java`

### Server Runtime

- [Dimension nodes](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/nodes/DimensionNodeManager.java): `src/main/java/net/lucent/formation_arrays/core/nodes/DimensionNodeManager.java`
- [Activation recipes](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/FormationActivationHelper.java): `src/main/java/net/lucent/formation_arrays/core/formations/FormationActivationHelper.java`
- [Dimension formations](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManager.java): `src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManager.java`
- [Placed formation](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/PlacedFormation.java): `src/main/java/net/lucent/formation_arrays/core/formations/PlacedFormation.java`
- [Formation events](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/FormationEventHandler.java): `src/main/java/net/lucent/formation_arrays/core/formations/FormationEventHandler.java`

### Client Sync

- [Formation patch packet](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/network/DimensionFormationManagerPatchPacket.java): `src/main/java/net/lucent/formation_arrays/network/DimensionFormationManagerPatchPacket.java`
- [Formation patch](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManagerPatch.java): `src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManagerPatch.java`
- [Client formations](https://github.com/oliverhesse/formationarrays/blob/main/src/main/java/net/lucent/formation_arrays/core/formations/client/ClientDimensionFormationManager.java): `src/main/java/net/lucent/formation_arrays/core/formations/client/ClientDimensionFormationManager.java`

### Other components

- **Minecraft world**

## Connections

- Core registries → Formation definition: registers type (evidence: `src/main/java/net/lucent/formation_arrays/api/CoreRegistries.java`)
- Core registries → Node providers: registers factories (evidence: `src/main/java/net/lucent/formation_arrays/api/CoreRegistries.java`)
- Simple state → State contract: implements (evidence: `src/main/java/net/lucent/formation_arrays/core/formations/SimpleStateHandler.java`)
- Simple state → Node manager API: checks nodes (evidence: `src/main/java/net/lucent/formation_arrays/core/formations/SimpleStateHandler.java`)
- Dimension nodes → Node types: resolves types (evidence: `src/main/java/net/lucent/formation_arrays/core/nodes/DimensionNodeManager.java`)
- Dimension nodes → Block lookup: checks providers (evidence: `src/main/java/net/lucent/formation_arrays/core/nodes/DimensionNodeManager.java`)
- Dimension nodes → Node capabilities: reads entity capability (evidence: `src/main/java/net/lucent/formation_arrays/core/nodes/DimensionNodeManager.java`)
- Block lookup → Node capabilities: queries capability (evidence: `src/main/java/net/lucent/formation_arrays/util/BlockUtil.java`)
- Minecraft world → Dimension nodes: provides node state
- Dimension formations → Dimension nodes: gets node manager (evidence: `src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManager.java`)
- Dimension formations → Activation recipes: finds formations (evidence: `src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManager.java`)
- Dimension formations → Formation definition: tries activation (evidence: `src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManager.java`)
- Dimension formations → Formation instance: creates instances (evidence: `src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManager.java`)
- Dimension formations → Placed formation: tracks placements (evidence: `src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManager.java`)
- Formation events → Dimension formations: dispatches changes (evidence: `src/main/java/net/lucent/formation_arrays/core/formations/FormationEventHandler.java`)
- Dimension nodes → Formation events: posts node events (evidence: `src/main/java/net/lucent/formation_arrays/core/nodes/DimensionNodeManager.java`)
- Dimension formations → Formation patch: builds updates (evidence: `src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManager.java`)
- Formation patch → Formation patch packet: transmitted by (evidence: `src/main/java/net/lucent/formation_arrays/network/DimensionFormationManagerPatchPacket.java`)
- Formation patch → Client formations: applies changes (evidence: `src/main/java/net/lucent/formation_arrays/core/formations/DimensionFormationManagerPatch.java`)
- Client formations → Formation instance: ticks instances (evidence: `src/main/java/net/lucent/formation_arrays/core/formations/client/ClientDimensionFormationManager.java`)