Skip to content

Temperature Data System

Jump to bottom
Real Ant Engineer edited this page Jun 16, 2026 · 2 revisions

Temperature Data System

This page explains how temperature-related data is defined, stored, and encoded for blocks, fluids, and biomes in the mod.

📂 Datapack Locations

Each type of data (temperature, conduction, and resilience) is stored in a datapack under the following paths:

Data Type Registry Path
Block Temperature Registries.BLOCK data/crowns/float_map/blocks/temperatures.json
Block Conduction Registries.BLOCK data/crowns/float_map/blocks/conduction.json
Block Resilience Registries.BLOCK data/crowns/float_map/blocks/resilience.json
Fluid Temperature Registries.FLUID data/crowns/float_map/fluids/temperatures.json
Fluid Conduction Registries.FLUID data/crowns/float_map/fluids/conduction.json
Fluid Resilience Registries.FLUID data/crowns/float_map/fluids/resilience.json
Biome Temperature Registries.BIOME data/crowns/float_map/biomes/temperatures.json
  • Precision: 1/255 ≈ 0.39%
  • Storage: 1 byte per voxel, 4 KB per section

🔗 Relationship Between Layers

The three layers work together in the implicit solver each tick:

  • Conduction determines how strongly a voxel is coupled to its neighbours (off-diagonal matrix entries).
  • Resilience determines how strongly a voxel is pulled toward its default temperature (diagonal contribution + RHS source term).
  • Temperature holds the current state (T_current) going in and the computed state (T_next) coming out.

See Temperature Computation for how these are assembled into the linear system.

Last updated: June 2026 — Author: Real Ant Engineer

# Temperature Data System

This page explains how temperature-related data is defined, stored, and encoded for blocks, fluids, and biomes in the mod.

📂 Datapack Locations

Each type of data (temperature, conduction, and resilience) is stored in a datapack under the following paths:

Data Type Registry Path
Block Temperature Registries.BLOCK data/crowns/float_map/blocks/temperatures.json
Block Conduction Registries.BLOCK data/crowns/float_map/blocks/conduction.json
Block Resilience Registries.BLOCK data/crowns/float_map/blocks/resilience.json
Fluid Temperature Registries.FLUID data/crowns/float_map/fluids/temperatures.json
Fluid Conduction Registries.FLUID data/crowns/float_map/fluids/conduction.json
Fluid Resilience Registries.FLUID data/crowns/float_map/fluids/resilience.json
Biome Temperature Registries.BIOME data/crowns/float_map/biomes/temperatures.json

All of these are handled by instances of the FloatMap Data Loader from the Formic API.

🧩 Example JSON (Datapack)

{
  "replace": false,
  "values": {
    "#minecraft:stone_ore_replaceables": 295.15,
    "minecraft:lava": 4000.0,
    "minecraft:water": 293.15
  }
}

Explanation:

  • # before a name means it's a tag reference.
  • Plain names are direct registry entries.
  • The "replace" field determines whether to overwrite or merge with existing datapack values.

Each file follows this same format for temperatures, conduction, and resilience.

🧊 Section-Level Data Storage

Each chunk section (16×16×16 blocks) stores local physical values for temperature, conduction, and resilience. Each value type uses a dedicated data layer class that extends AbstractDataLayer.

All layers share the same 3D indexing scheme:

index = x + z * 16 + y * 256

Valid coordinates are 0–15 on each axis. The total size of each layer is 4096 values (16³).

Layer Stored type Bytes/voxel Precision Value range Purpose
TemperatureDataLayer short 2 0.1 K 0 – ~6553 K Absolute temperature
ConductionDataLayer custom 8-bit mini-float 1 ~10–15% 2⁻¹⁶ – 1.75×2⁴⁷ Thermal conductivity
ResilienceDataLayer byte 1 1/255 ≈ 0.4% 0.0 – 1.0 Temperature stability factor

🌡️ TemperatureDataLayer

Purpose

Stores temperature per voxel in Kelvin. This data is read and written each tick by the temperature computation system.

Default Temperature Priority

When determining the initial temperature of a position, the system checks in the following order:

  1. Fluids — if the block contains or is submerged in one
  2. Blocks — if no fluid temperature is available
  3. Biome — as a fallback background temperature

Encoding

Temperatures are stored as 16-bit signed shorts, using a fixed-point representation with 1 decimal place of precision.

Operation Formula
Encoding stored = (short)(temperature * 10 + Short.MIN_VALUE)
Decoding temperature = (stored - Short.MIN_VALUE) / 10.0
  • Precision: 0.1 K
  • Range: 0 K to (Short.MAX_VALUE - Short.MIN_VALUE) / 10 ≈ 6553 K
  • Storage: 2 bytes per voxel, 8 KB per section

Note: TemperatureDataLayer maintains a float[] values array in memory for fast access. The decode() and encode() methods are bypassed in favour of direct array reads/writes via getDirect() and setDirect().

🔥 ConductionDataLayer

Purpose

Stores the thermal conductivity per voxel, controlling how fast heat diffuses between neighbours. It uses a custom 8-bit mini-float format to cover a very wide range of physically meaningful values in a single byte.

Encoding Format

Bit layout: [E E E E E E M M]
             |           |
             6-bit exp   2-bit mantissa
  • Mantissa (bits 0–1): encodes values 1.0, 1.25, 1.5, 1.75 (i.e. 1 + mantissa/4)
  • Exponent (bits 2–7): stored with a bias of 16, giving an effective range of −16 to +47
Operation Formula
Decoding value = (1 + mantissa / 4.0) * 2^(exponent - 16)
Encoding Compute floor(log2(value)), clamp exponent, round mantissa
  • Range: 2⁻¹⁶ (≈ 1.5×10⁻⁵) to 1.75 × 2⁴⁷ (≈ 2.4×10¹⁴)
  • Precision: ~10–15% relative error (logarithmic spacing)
  • Storage: 1 byte per voxel, 4 KB per section

A decoded float[] cache is maintained in memory so that repeated reads during the solver's inner loop don't re-execute the bit arithmetic every time.

🧱 ResilienceDataLayer

Purpose

Stores a resilience factor in the range [0, 1], representing how strongly a voxel resists diffusion and returns to its default temperature each tick.

  • 0.0 — the voxel diffuses freely with no pull toward a default
  • 0.5 — moderate stabilisation
  • 1.0 — the voxel is fully locked to its default temperature (used for strong heat sources/sinks)

In the solver, resilience appears in both the diagonal of matrix A and the source vector b, acting as a per-voxel spring constant pulling temperature toward T_default.

Encoding

Stored as a signed byte, linearly mapped to [0, 1].

Operation Formula
Encoding stored = (byte)(round(resilience * 255) - 128)
Decoding resilience = (stored + 128) / 255.0
  • Precision: 1/255 ≈ 0.39%
  • Storage: 1 byte per voxel, 4 KB per section

🔗 Relationship Between Layers

The three layers work together in the implicit solver each tick:

  • Conduction determines how strongly a voxel is coupled to its neighbours (off-diagonal matrix entries).
  • Resilience determines how strongly a voxel is pulled toward its default temperature (diagonal contribution + RHS source term).
  • Temperature holds the current state (T_current) going in and the computed state (T_next) coming out.

See Temperature Computation for how these are assembled into the linear system.

Last updated: June 2026 — Author: Real Ant Engineer

Last updated: October 2025 — Author: Real Ant Engineer

Clone this wiki locally