# panzerdevorg/tessera architecture

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

- Interactive diagram: https://gitdiagram.com/panzerdevorg/tessera
- Repository: https://github.com/panzerdevorg/tessera

## Overview

Tessera is a client-side NeoForge mod that reduces texture-atlas VRAM by recompressing vanilla atlases into GPU-compressed BC formats. The principal flow starts after vanilla uploads an atlas: a mixin hands off to the atlas driver, which prepares mip levels, checks budget and cache, and delegates encoding before the compressed data is uploaded. Animated sprites are updated separately. Configuration, compatibility helpers, and F3 reporting support that flow. README statements document several runtime behaviors; source excerpts are incomplete, so uncertain internal links are omitted.

Main entry points: [`src/main/java/com/panzer/mods/tessera/atlas/AtlasCompressionDriver.java`](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/atlas/AtlasCompressionDriver.java) (Atlas compression), [`src/main/java/com/panzer/mods/tessera/Tessera.java`](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/Tessera.java) (Mod bootstrap), [`src/main/java/com/panzer/mods/tessera/compress/CompressionPipeline.java`](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/CompressionPipeline.java) (Compression pipeline), [`src/main/java/com/panzer/mods/tessera/compress/backend/TesseraRuntime.java`](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/backend/TesseraRuntime.java) (Backend selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Game integration"]
  node_upload_hook["Atlas upload hook"]
  node_sprite_hook["Sprite upload hook"]
  node_bootstrap["Mod bootstrap<br/>[Tessera.java]"]
  node_compat["Game compatibility<br/>[TesseraCompat.java]"]
  node_events["Compression events"]
end

subgraph group_atlas["Atlas processing"]
  node_atlas_driver["Atlas compression"]
  node_family_analysis["Sprite family analysis"]
  node_mip_builder["Mip-chain builder"]
  node_animation["Animation updates"]
  node_animation_reader["Animation frame reader"]
  node_cache[("Atlas disk cache<br/>[AtlasCache.java]")]
end

subgraph group_encoding["Compression"]
  node_pipeline["Compression pipeline"]
  node_backend_runtime["Backend selection"]
  node_backend_api["Compression backend"]
  node_jni_backend["Native encoder"]
  node_software_backend["Software backend"]
  node_bc7_encoder["Software BC7 encoder"]
  node_bc1_encoder["Software BC1 encoder"]
  node_texel_bleed["Transparent texel cleanup"]
end

subgraph group_runtime["Settings and reporting"]
  node_config["Client configuration<br/>[Config.java]"]
  node_rules["Reload rules<br/>[RulesManager.java]"]
  node_vram["VRAM budget"]
  node_overlay["F3 VRAM overlay<br/>[DebugOverlay.java]"]
  node_features["Feature API"]
end

node_minecraft(("Minecraft client"))

node_minecraft -->|"uploads atlas"| node_upload_hook
node_upload_hook -->|"dispatches compression"| node_atlas_driver
node_atlas_driver -->|"builds mip chain"| node_mip_builder
node_atlas_driver -->|"checks and stores"| node_cache
node_atlas_driver -->|"requests encoding"| node_pipeline
node_atlas_driver -->|"checks budget"| node_vram
node_atlas_driver -->|"uses game helpers"| node_compat
node_atlas_driver -.->|"analyzes sprites"| node_family_analysis
node_pipeline -->|"selects backend"| node_backend_runtime
node_pipeline -->|"cleans texels"| node_texel_bleed
node_backend_runtime -->|"probes native"| node_jni_backend
node_backend_runtime -->|"falls back to"| node_software_backend
node_software_backend -.->|"encodes BC7"| node_bc7_encoder
node_software_backend -.->|"encodes BC1"| node_bc1_encoder
node_sprite_hook -.->|"updates compressed sprites"| node_animation
node_animation -->|"reads frames"| node_animation_reader
node_animation -->|"encodes frames"| node_pipeline
node_bootstrap -->|"registers settings"| node_config
node_bootstrap -->|"initializes backend"| node_backend_runtime
node_bootstrap -->|"registers reload listener"| node_rules
node_bootstrap -->|"warms VRAM query"| node_vram
node_bootstrap -->|"registers debug display"| node_overlay
node_vram -->|"uses fallback target"| node_config
node_overlay -->|"shows VRAM savings"| node_vram
node_atlas_driver -.->|"fires lifecycle events"| node_events
node_atlas_driver -->|"uploads compressed atlas"| node_minecraft

click node_upload_hook "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/mixin/TextureAtlasUploadMixin.java"
click node_sprite_hook "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/mixin/SpriteContentsUploadMixin.java"
click node_bootstrap "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/Tessera.java"
click node_compat "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compat/TesseraCompat.java"
click node_events "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/api/AtlasCompressEvent.java"
click node_atlas_driver "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/atlas/AtlasCompressionDriver.java"
click node_family_analysis "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/atlas/SpriteFamilyAnalyzer.java"
click node_mip_builder "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/atlas/MipChainBuilder.java"
click node_animation "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/CompressedAnimationUploader.java"
click node_animation_reader "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/AnimationReader.java"
click node_cache "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/cache/AtlasCache.java"
click node_pipeline "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/CompressionPipeline.java"
click node_backend_runtime "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/backend/TesseraRuntime.java"
click node_backend_api "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/backend/CompressionBackend.java"
click node_jni_backend "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/backend/JniCompressionBackend.java"
click node_software_backend "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/backend/SoftwareCompressionBackend.java"
click node_bc7_encoder "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/software/SoftwareBc7Encoder.java"
click node_bc1_encoder "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/software/SoftwareBc1Encoder.java"
click node_texel_bleed "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/software/TransparentTexelBleed.java"
click node_config "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/config/Config.java"
click node_rules "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/config/RulesManager.java"
click node_vram "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/vram/VramBudgetEngine.java"
click node_overlay "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/gui/DebugOverlay.java"
click node_features "https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/api/TesseraFeatures.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_upload_hook,node_sprite_hook,node_bootstrap,node_compat,node_events,node_minecraft toneBlue
class node_atlas_driver,node_family_analysis,node_mip_builder,node_animation,node_animation_reader,node_cache toneAmber
class node_pipeline,node_backend_runtime,node_backend_api,node_jni_backend,node_software_backend,node_bc7_encoder,node_bc1_encoder,node_texel_bleed toneMint
class node_config,node_rules,node_vram,node_overlay,node_features toneRose
```

## Components

### Game integration

- [Atlas upload hook](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/mixin/TextureAtlasUploadMixin.java): `src/main/java/com/panzer/mods/tessera/mixin/TextureAtlasUploadMixin.java`
- [Sprite upload hook](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/mixin/SpriteContentsUploadMixin.java): `src/main/java/com/panzer/mods/tessera/mixin/SpriteContentsUploadMixin.java`
- [Mod bootstrap](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/Tessera.java): `src/main/java/com/panzer/mods/tessera/Tessera.java`
- [Game compatibility](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compat/TesseraCompat.java): `src/main/java/com/panzer/mods/tessera/compat/TesseraCompat.java`
- [Compression events](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/api/AtlasCompressEvent.java): `src/main/java/com/panzer/mods/tessera/api/AtlasCompressEvent.java`

### Atlas processing

- [Atlas compression](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/atlas/AtlasCompressionDriver.java): `src/main/java/com/panzer/mods/tessera/atlas/AtlasCompressionDriver.java`
- [Sprite family analysis](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/atlas/SpriteFamilyAnalyzer.java): `src/main/java/com/panzer/mods/tessera/atlas/SpriteFamilyAnalyzer.java`
- [Mip-chain builder](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/atlas/MipChainBuilder.java): `src/main/java/com/panzer/mods/tessera/atlas/MipChainBuilder.java`
- [Animation updates](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/CompressedAnimationUploader.java): `src/main/java/com/panzer/mods/tessera/compress/CompressedAnimationUploader.java`
- [Animation frame reader](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/AnimationReader.java): `src/main/java/com/panzer/mods/tessera/compress/AnimationReader.java`
- [Atlas disk cache](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/cache/AtlasCache.java): `src/main/java/com/panzer/mods/tessera/cache/AtlasCache.java`

### Compression

- [Compression pipeline](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/CompressionPipeline.java): `src/main/java/com/panzer/mods/tessera/compress/CompressionPipeline.java`
- [Backend selection](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/backend/TesseraRuntime.java): `src/main/java/com/panzer/mods/tessera/compress/backend/TesseraRuntime.java`
- [Compression backend](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/backend/CompressionBackend.java): `src/main/java/com/panzer/mods/tessera/compress/backend/CompressionBackend.java`
- [Native encoder](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/backend/JniCompressionBackend.java): `src/main/java/com/panzer/mods/tessera/compress/backend/JniCompressionBackend.java`
- [Software backend](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/backend/SoftwareCompressionBackend.java): `src/main/java/com/panzer/mods/tessera/compress/backend/SoftwareCompressionBackend.java`
- [Software BC7 encoder](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/software/SoftwareBc7Encoder.java): `src/main/java/com/panzer/mods/tessera/compress/software/SoftwareBc7Encoder.java`
- [Software BC1 encoder](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/software/SoftwareBc1Encoder.java): `src/main/java/com/panzer/mods/tessera/compress/software/SoftwareBc1Encoder.java`
- [Transparent texel cleanup](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/compress/software/TransparentTexelBleed.java): `src/main/java/com/panzer/mods/tessera/compress/software/TransparentTexelBleed.java`

### Settings and reporting

- [Client configuration](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/config/Config.java): `src/main/java/com/panzer/mods/tessera/config/Config.java`
- [Reload rules](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/config/RulesManager.java): `src/main/java/com/panzer/mods/tessera/config/RulesManager.java`
- [VRAM budget](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/vram/VramBudgetEngine.java): `src/main/java/com/panzer/mods/tessera/vram/VramBudgetEngine.java`
- [F3 VRAM overlay](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/gui/DebugOverlay.java): `src/main/java/com/panzer/mods/tessera/gui/DebugOverlay.java`
- [Feature API](https://github.com/panzerdevorg/tessera/blob/master/src/main/java/com/panzer/mods/tessera/api/TesseraFeatures.java): `src/main/java/com/panzer/mods/tessera/api/TesseraFeatures.java`

### Other components

- **Minecraft client**

## Connections

- Minecraft client → Atlas upload hook: uploads atlas
- Atlas upload hook → Atlas compression: dispatches compression (evidence: `src/main/java/com/panzer/mods/tessera/mixin/TextureAtlasUploadMixin.java`)
- Atlas compression → Mip-chain builder: builds mip chain (evidence: `src/main/java/com/panzer/mods/tessera/atlas/AtlasCompressionDriver.java`)
- Atlas compression → Atlas disk cache: checks and stores (evidence: `src/main/java/com/panzer/mods/tessera/atlas/AtlasCompressionDriver.java`)
- Atlas compression → Compression pipeline: requests encoding (evidence: `src/main/java/com/panzer/mods/tessera/atlas/AtlasCompressionDriver.java`)
- Atlas compression → VRAM budget: checks budget (evidence: `src/main/java/com/panzer/mods/tessera/atlas/AtlasCompressionDriver.java`)
- Atlas compression → Game compatibility: uses game helpers (evidence: `src/main/java/com/panzer/mods/tessera/atlas/AtlasCompressionDriver.java`)
- Atlas compression → Sprite family analysis: analyzes sprites
- Compression pipeline → Backend selection: selects backend (evidence: `src/main/java/com/panzer/mods/tessera/compress/CompressionPipeline.java`)
- Compression pipeline → Transparent texel cleanup: cleans texels (evidence: `src/main/java/com/panzer/mods/tessera/compress/CompressionPipeline.java`)
- Backend selection → Native encoder: probes native (evidence: `src/main/java/com/panzer/mods/tessera/compress/backend/TesseraRuntime.java`)
- Backend selection → Software backend: falls back to (evidence: `src/main/java/com/panzer/mods/tessera/compress/backend/TesseraRuntime.java`)
- Software backend → Software BC7 encoder: encodes BC7 (evidence: `src/main/java/com/panzer/mods/tessera/compress/backend/SoftwareCompressionBackend.java`)
- Software backend → Software BC1 encoder: encodes BC1 (evidence: `src/main/java/com/panzer/mods/tessera/compress/backend/SoftwareCompressionBackend.java`)
- Sprite upload hook → Animation updates: updates compressed sprites (evidence: `src/main/java/com/panzer/mods/tessera/mixin/SpriteContentsUploadMixin.java`)
- Animation updates → Animation frame reader: reads frames (evidence: `src/main/java/com/panzer/mods/tessera/compress/CompressedAnimationUploader.java`)
- Animation updates → Compression pipeline: encodes frames (evidence: `src/main/java/com/panzer/mods/tessera/compress/CompressedAnimationUploader.java`)
- Mod bootstrap → Client configuration: registers settings (evidence: `src/main/java/com/panzer/mods/tessera/Tessera.java`)
- Mod bootstrap → Backend selection: initializes backend (evidence: `src/main/java/com/panzer/mods/tessera/Tessera.java`)
- Mod bootstrap → Reload rules: registers reload listener (evidence: `src/main/java/com/panzer/mods/tessera/Tessera.java`)
- Mod bootstrap → VRAM budget: warms VRAM query (evidence: `src/main/java/com/panzer/mods/tessera/Tessera.java`)
- Mod bootstrap → F3 VRAM overlay: registers debug display (evidence: `src/main/java/com/panzer/mods/tessera/Tessera.java`)
- VRAM budget → Client configuration: uses fallback target (evidence: `src/main/java/com/panzer/mods/tessera/vram/VramBudgetEngine.java`)
- F3 VRAM overlay → VRAM budget: shows VRAM savings (evidence: `src/main/java/com/panzer/mods/tessera/gui/DebugOverlay.java`)
- Atlas compression → Compression events: fires lifecycle events
- Atlas compression → Minecraft client: uploads compressed atlas
