Architecture Overview¶

This document describes the high-level architecture of Ansible Crafting, its package structure, key classes, and data flows.

See also: Development Guide for building and testing, Guidelines for coding conventions.

High-Level Architecture¶

Ansible Crafting is a client-server Minecraft mod for Fabric, Forge, and NeoForge that scans nearby inventories on the server, syncs the data to the client for display, and handles crafting requests that pull items from remote containers. The codebase uses Stonecutter + Modstitch for multi-version, multi-loader support from a single source tree.

flowchart TB
    subgraph Server Side
        SCANNER["InventoryScanner<br/>Scans nearby blocks"]
        AGG["AggregatedInventory<br/>Merges all inventories"]
        STATE["InventoryStateManager<br/>Persistent enable/disable"]
        CRAFT["RemoteCraftingHandler<br/>Extracts items from containers"]
        SESSION["CraftingSessionManager<br/>Tracks active crafting sessions"]
    end

    subgraph Network
        SYNC_PKT["InventorySyncPacket<br/>Item data → client"]
        STATE_PKT["InventoryStateSyncPacket<br/>Enable/disable states → client"]
        TOGGLE_PKT["InventoryToggleRequestPacket<br/>Toggle request → server"]
        RESYNC_PKT["StateResyncRequestPacket<br/>Resync request → server"]
    end

    subgraph Client Side
        CACHE["ClientInventoryCache<br/>Stores synced item data"]
        PANEL["InventoryPanelWidget<br/>Side panel UI"]
        HIGHLIGHT["HighlightRenderer<br/>Block outline highlights"]
        OVERLAY["InventoryOverlayRenderer<br/>Wifi status icons"]
        SHADER["ShaderCompat<br/>Shader mod detection"]
        TRACKER["InventoryPanelTracker<br/>Panel lifecycle"]
        TEXTURES["AnsibleCraftingTextures<br/>Texture identifiers"]
    end

    subgraph Integrations
        EMI["EMI Plugin<br/>Recipe transfer + exclusion zones"]
        REI["REI Plugin<br/>Recipe transfer + exclusion zones"]
    end

    SCANNER --> AGG
    AGG --> SYNC_PKT
    STATE --> STATE_PKT
    SYNC_PKT --> CACHE
    STATE_PKT --> CACHE
    CACHE --> PANEL
    PANEL --> HIGHLIGHT
    TOGGLE_PKT --> STATE
    RESYNC_PKT --> STATE
    EMI --> CRAFT
    REI --> CRAFT
    CRAFT --> SESSION

Package Structure¶

com.ansiblecrafting/
├── AnsibleCraftingMod          — Server-side mod entrypoint, lifecycle
├── ModResourceLocation         — Version-safe ResourceLocation factory
├── RegistryHelper              — Version-safe registry lookup utility
├── ServerTickHandler           — Per-tick inventory scanning orchestration
├── client/
│   ├── AnsibleCraftingClient   — Client-side mod entrypoint
│   ├── AnsibleCraftingTextures — Texture ResourceLocation constants
│   ├── ClientInventoryCache    — Client-side inventory data cache
│   ├── HighlightRenderer       — 3D block highlight rendering
│   ├── InventoryOverlayRenderer — 3D inventory icon overlay rendering
│   ├── ShaderCompat            — Shader mod detection (Iris/Optifine)
│   └── ui/
│       ├── InventoryPanelTracker — Panel visibility state tracking
│       └── InventoryPanelWidget  — Side panel UI widget
├── config/
│   ├── ConfigScreenBuilder     — Cloth Config screen builder
│   ├── ModConfig               — Configuration data class
│   └── ModMenuIntegration      — Mod Menu config screen provider
├── crafting/
│   ├── ClientCacheRecipePopulator — Client-side recipe ingredient populator
│   ├── CombinedPlayerInventory — Player + nearby inventory wrapper
│   ├── CraftingSessionManager  — Per-player crafting session state (CraftingSession is a Java record)
│   ├── GridSlotSourceHolder    — Tracks which container each grid slot's item came from
│   ├── RemoteCraftingHandler   — Item extraction/insertion from nearby containers
│   ├── VirtualInventory        — Read-only Container for recipe filling
│   └── VirtualSlot             — Single slot in a VirtualInventory
├── integration/
│   ├── NearbyInventoryHelper   — Shared recipe viewer helper methods
│   ├── emi/
│   │   ├── AnsibleCraftingEmiExclusionArea
│   │   ├── AnsibleCraftingEmiPlugin
│   │   └── AnsibleCraftingRecipeHandler
│   ├── jei/
│   │   ├── AnsibleCraftingJeiPlugin
│   │   ├── JeiExclusionAreaHandler
│   │   └── JeiTransferHandler
│   └── rei/
│       ├── ReiExclusionZoneProvider
│       ├── ReiPlugin
│       └── ReiTransferHandler
├── inventory/
│   ├── AggregatedInventory     — Merged view of all nearby container contents
│   ├── CapabilityBackedInventory — Forge/NeoForge capability wrapper
│   ├── InventoryLookup         — Block entity → Container resolution
│   ├── InventoryScanner        — Nearby container discovery and caching
│   ├── InventoryStateManager   — Per-inventory enable/disable persistence
│   ├── InventoryToggleHandler  — Toggle request processing
│   └── StorageBackedInventory  — Fabric Transfer API wrapper
├── mixin/
│   ├── AbstractRecipeScreenHandlerMixin — Recipe placement injection
│   ├── CraftingScreenHandlerMixin      — Crafting menu lifecycle hooks
│   └── client/
│       ├── ContainerScreenMixin — Generic container screen hooks
│       └── CraftingScreenMixin  — Crafting screen panel integration
└── network/
    ├── InventoryStateSyncPacket    — Server→Client state sync
    ├── InventorySyncPacket         — Server→Client inventory data sync
    ├── InventoryToggleRequestPacket — Client→Server toggle request
    ├── NetworkHandler              — Forge/NeoForge network channel setup
    ├── RemoteCraftFillRequestPacket — Client→Server craft request
    ├── StateResyncRequestPacket    — Client→Server state resync request
    └── StateSyncHelper             — State sync utility methods

Key Data Flows¶

Inventory Scanning and Sync¶

sequenceDiagram
    participant Server as Server (tick loop)
    participant Scanner as InventoryScanner
    participant Agg as AggregatedInventory
    participant Net as Network
    participant Cache as ClientInventoryCache
    participant Panel as InventoryPanelWidget

    Server->>Scanner: scanInventories(player) every N ticks
    Scanner->>Scanner: Find blocks with inventories within range
    Scanner->>Agg: Aggregate all inventory contents
    Agg->>Net: InventorySyncPacket (item stacks + positions)
    Net->>Cache: Update cached item data
    Cache->>Panel: Panel reads cache on render

Remote Crafting (via Recipe Viewer)¶

sequenceDiagram
    participant Player as Player
    participant EMI as EMI / REI
    participant Handler as RecipeHandler
    participant Mixin as CraftingScreenHandlerMixin
    participant Remote as RemoteCraftingHandler
    participant Container as Nearby Container

    Player->>EMI: Click recipe to craft
    EMI->>Handler: Transfer recipe to crafting grid
    Handler->>Mixin: fillInputSlots() with remote sources
    Mixin->>Remote: Extract items from remote inventories
    Remote->>Container: Remove items from container slots
    Remote->>Mixin: Place items in crafting grid
    Player->>Mixin: Take crafted result
    Mixin->>Remote: Return unused items to source containers

Inventory Toggle¶

sequenceDiagram
    participant Player as Player (Client)
    participant Net as Network
    participant State as InventoryStateManager
    participant PState as PersistentState (World Save)

    Player->>Net: InventoryToggleRequestPacket (blockPos, enabled)
    Net->>State: Toggle inventory at position
    State->>PState: Persist to world save data
    State->>Net: InventoryStateSyncPacket (updated states)
    Net->>Player: Client updates overlay icons

Mixin Strategy¶

The mod uses four mixins to hook into Minecraft's crafting system and screen rendering:

Mixin policy: No empty stub mixins. Every mixin must contain at least one functional injection. See Guidelines — Mixin Best Practices.

Recipe Viewer Integration¶

Both EMI and REI integrations follow the same pattern:

flowchart LR
    PLUGIN["Plugin Registration<br/>EmiPlugin / REIClientPlugin"] --> HANDLER["Recipe Transfer Handler<br/>Fills crafting grid from remote items"]
    PLUGIN --> EXCLUSION["Exclusion Zone Provider<br/>Prevents recipe viewer overlapping panel"]

JEI is supported on Forge (1.20.1) and NeoForge (1.21.1+) via the integration/jei/ package.

Client-Server Boundary¶

All code is strictly separated by side:

Client-only classes use @Environment(EnvType.CLIENT) to prevent loading on dedicated servers. Entry points are declared in fabric.mod.json:

{
  "entrypoints": {
    "main": ["com.ansiblecrafting.AnsibleCraftingMod"],
    "client": ["com.ansiblecrafting.client.AnsibleCraftingClient"]
  }
}

Persistent State¶

InventoryStateManager extends Minecraft's PersistentState to save per-inventory enable/disable toggles to the world save. This means:

• Toggle states survive server restarts
• Each world/dimension has its own state
• States are synced to clients via InventoryStateSyncPacket