Voxel Reactions

intermediate feature

Voxel Play 4 · Features

Voxel Reactions define what happens when two voxel types touch: lava meeting water hardens into rock, acid eats through metal, snow melts beside fire. Reactions are pure data - the rules live in a Voxel Reaction Set asset assigned to your World Definition - so no scripting is required. The engine checks the rules automatically whenever a voxel is placed and while liquids spread.

Setting It Up

  1. Create the rules asset: right-click in the Project window and choose Create > Voxel Play > Voxel Reaction Set.
  2. Add one or more rules to the asset (see the anatomy below).
  3. Assign one or more assets to the Reaction Sets list of your World Definition (the rules from every assigned set are combined).

That's all. Any voxel definitions referenced only by the rules (for example a "solid rock" result voxel that never appears during generation) are registered automatically at startup, so you don't need to add them to the world's More Voxels list.

When Reactions Fire

  • On placement - after any voxel is placed (by the player, a script or pouring), its six neighbours are checked against the rules.
  • During liquid spread - when a spreading liquid tries to enter a cell occupied by a liquid of a different family, the rules are checked before the move.

Liquids of the same family (two water-type liquids, or the same definition) simply merge levels and never react. Liquids of different families - such as water (Water render type) and lava (Fluid render type) - either react if a rule matches, or act as barriers to each other if none does. A reaction may place a voxel that immediately triggers another rule; such chains are capped at 4 steps to stay bounded.

Liquid spread requires the water flood simulation, which is enabled by default (Enable Water Flood exists both on the Voxel Play Environment and on the World Definition).

Anatomy of a Rule

Each rule describes two sides (A and B), the required contact, and the outcome for each side:

FieldPurpose
Match By (per side)How the side is matched: a specific Voxel Definition, Any Water (Water render type), Any Fluid (lava-like Fluid render type) or Tag (matched against the voxel definition's Reaction Tags list).
State (per side)Required liquid state: Source = full level (as placed), Flowing = partially spread, Any = ignore. Non-liquid voxels always count as Source.
ContactRequired relative position: Any, A Above B, A Below B or Lateral (same height).
ChanceProbability (0-1) that the rule fires each time the contact is checked. Values below 1 make the transformation creep gradually instead of converting everything at once.
Voxel A / Voxel B (outcome)What happens to each side: Keep (unchanged), Air (removed) or Transform into the voxel set in Becomes.
VaporEmits a burst of vapor puffs at the contact point, with configurable puff count, size, life and color. Client-side dressing: skipped in server mode.
SoundOptional audio clip played at the contact point.

Sides are matched in both directions - a rule with lava as side A and water as side B also fires when the water is the voxel being placed or spreading.

Walkthrough: Classic Lava + Water

This recreates the behavior of the included example: water touching still lava hardens into cold lava, and water touching flowing lava turns into plain rock.

  1. Create the asset. In the Project window: Create > Voxel Play > Voxel Reaction Set. Name it after your world, e.g. MyWorld Reactions.
  2. Add rule 1 - still lava. Click + on the Rules list and expand the new entry:
    • Side A: Match By = Voxel Definition, Voxel = your lava definition, State = Source (lava at full level).
    • Side B: Match By = Any Water, State = Any.
    • Conditions: Contact = Any, Chance = 1.
    • Outcome: Voxel A = Keep, Voxel B = Transform, Becomes = a hardened voxel such as Cold Lava (an obsidian-like block works well).
    • Effects: leave Vapor on (8 puffs by default) so contact produces a satisfying steam burst.
  3. Add rule 2 - flowing lava. Duplicate the first rule and change: Side A State = Flowing, Becomes = a cheaper result such as Solid Rock. Now only lava source blocks yield the valuable material, like the classic obsidian/cobblestone split.
  4. Assign the set. Select your World Definition and add the asset to its Reaction Sets list.
  5. Test it. Enter play mode, place a lava voxel, then pour water next to it (or vice versa) - the contact voxel transforms and vapor rises. Let water flow downhill into a lava pool to watch the reaction front creep as the liquids spread.

Included example: the Earth Reactions asset (in Resources/Worlds/Earth) ships with exactly these two rules and is already assigned to the Earth, Earth 3D and HQ Forest worlds - open demo scene 1 and try it, or use the asset as a starting template for your own set.

Scripting (Optional)

The system is fully asset-driven, but two events let you hook into it:

MemberPurpose
OnVoxelReactionBeforeRaised before a reaction applies. Return false to cancel it (the liquids then behave as barriers), or set suppressEffects to apply the outcomes without the built-in vapor/sound so you can play your own effects.
OnVoxelReactionRaised after a reaction has been applied, with both chunks/voxel indices and the rule that fired.
TryVoxelReaction(chunk1, voxelIndex1, chunk2, voxelIndex2)Manually attempts a reaction between two touching voxels. Returns true if a rule fired.
CreateSteamEffect(position, amount, scale, duration, color)Spawns the same vapor puff burst used by reactions, anywhere you like.

Tips

  • Use tags for mods and custom voxels. Give voxel definitions entries in their Reaction Tags list (e.g. flammable) and match rules by Tag - new voxel types then join existing rules without editing the reaction set.
  • Chance below 1 creates a creeping front. A large water/lava contact surface converts gradually instead of in a single frame, which reads much more naturally.
  • Reactions run in server mode - only the vapor and sound dressing is skipped, so multiplayer worlds stay consistent.
  • Static liquids don't react until disturbed. Rules fire on placement and spread; two liquids generated side by side with a wall between them only react once the wall is broken and one starts flowing into the other.

See Also

Was this page helpful?