This guide provides technical documentation for extending Better Fire+, adding custom thermal reaction rules, preserving block permutations and container inventories, and integrating external Script Add-ons.

Developer Documentation Index

The documentation is divided into five parts:

1. 01. System Architecture & Module Design
   • File-by-file module layout and responsibilities.
   • Event sequence lifecycle (system.beforeEvents.startup, world.afterEvents.worldLoad).
   • Time-sliced generator simulation loop (system.runJob).
   • Thermal energy falloff equation, raycast occlusion shielding, and in-memory heat map memory management.
2. 02. Thermal Rule Engine & Custom Rules
   • Exact matching (EXACT_RULES) vs. pattern matching (PATTERN_RULES).
   • TransformRule property reference (threshold, chance, minSourceHeat, preserveState, spill, drop).
   • Base and hard-difficulty heat source registries.
   • Soot degradation chains and step-by-step custom rule creation guide.
3. 03. Block Permutations & Container Protection Engine
   • Resolving block state resets using BlockPermutation state key intersection.
   • VOLATILE_STATES blacklist.
   • Anti-duplication container pipeline (snapshotContainer, restoreContainer, scatterSnapshot).
   • Supported containers and copper chest oxidation lifecycle.
4. 04. Commands, Configuration & Scriptevent API
   • Configuration persistence via world dynamic properties (betterfire: namespace).
   • In-game command reference (/bf:fire, /bf:firefeature) and read-only execution model.
   • Feature toggle management (burnContainers, glassShatter, etc.).
   • /scriptevent listener channel (bf:difficulty, bf:intensity, etc.).
   • RawMessage localization and C++ native variant conversion safety.
5. 05. Local Unit Testing & QuickJS Environment Constraints
   • Bedrock QuickJS runtime limitations (avoiding Node/Web globals).
   • Mock server framework (tests/mock-server.js) and ES module loader hooks (tests/resolve-hook.mjs).
   • Running local unit tests (./tests/run.sh) and test suite verification coverage (158 assertions).

Quick Reference: Adding a Custom Rule

Rules are added in behavior_packs/better_fire/scripts/rules.js:

// Adding a static exact-match rule:
"minecraft:dried_kelp_block": {
  feature: "ignitables",
  threshold: 20,
  chance: 0.35,
  minSourceHeat: 8,
  result: "minecraft:fire",
  sound: "random.fizz",
  label: "Dried Kelp Ignition"
}

Quick Reference: Running Unit Tests [NOT PROVIDED TEMPORARILY]

To run the full test suite locally without starting a Bedrock client:

./tests/run.sh

01. System Architecture & Module Design

02. Thermal Rule Engine & Custom Rules

03. Block Permutations & Container Protection Engine