Realistic Smoke

A server-side smoke and ventilation mod inspired by Valheim-style building constraints. It runs entirely on the server, so players do not need a client-side mod installed.

Gameplay

• Lit furnaces, smokers, blast furnaces, campfires, and soul campfires produce smoke.
• Smoke rises, gathers beneath ceilings, and fills unventilated rooms.
• Chimneys and open roofs vent smoke outside. Glass roofs seal smoke even though they let skylight through.
• Open doors, trapdoors, and fence gates act as ventilation openings. Fluids block smoke, tho.
• Inhaling dense smoke builds exposure based on concentration at the player's eye level. High exposure brings nausea, blindness, and potentially lethal damage.
• Creative mode, spectator mode, and dead players do not build exposure.
• Exposure tracks across dimensions and dissipates in clean air. Respawning, dying, disconnecting, or stopping the server resets tracked exposure.
• Optional vanilla particles visualize plumes, exhaust, and ceiling smoke. The underlying physics and exposure checks run whether particles are enabled or disabled.

Approximation limits

The simulation focuses on survival building mechanics, using discrete approximations:

• Air within a single connected pocket inside a two-block cell mixes instantly. Buoyancy and inter-cell diffusion update at discrete tick intervals.
• Block passability uses bounding box collision states. Non-empty shapes block smoke unless they expose an active OPEN property (such as opened doors or trapdoors). Partial shapes like stairs, slabs, fence gaps, and open door leaves are evaluated at whole-block granularity.
• The simulation omits ambient wind vectors, dynamic temperature layers, oxygen depletion, and fire choking.
• Natural dissipation, outdoor venting, density caps, pocket pruning, and chunk unloads intentionally discard smoke. Mass conservation governs cell-to-cell transport, while sinks like venting and natural dissipation discard smoke intentionally.
• Active smoke fields do not persist through chunk unloads or server restarts.

Performance and safety

Smoke runs on a numeric grid without spawning entities or custom blocks. The simulation step runs every 10 ticks by default (twice per second at standard 20 TPS).

• Smoke sources register through Fabric block-entity lifecycle callbacks. On chunk load, fallback scans check stored block-entity coordinates instead of scanning the full chunk volume.
• A chunk-to-source index avoids iterating the full dimensional registry when chunks unload.
• Chunk unloads and cache trimmings batch once per world tick. Intermediate calculation buffers clear after every step.
• Simulation routines, exposure lookups, roof checks, and particle dispatch use non-loading chunk queries to avoid triggering unwanted chunk loads.
• Block geometry caches in a bounded primitive LRU table (defaulting to 24,000 cells per dimension). Exhaust column results use a separate cache sized at four times that limit.
• A server-side WorldChunk mixin invalidates cached geometry and roof profiles when blocks change. Time-based expiration and periodic clearing clean up lingering cache entries.
• Hot loops use fastutil primitive iterators to avoid per-entry heap allocations.
• Active smoke fields hold up to 12,000 pockets per dimension by default (configured via maxActiveCellsPerWorld).
• Temporary working buffers limit scratch pockets to 5x the active cap and candidate transfers to 25x the active cap during a step.
• Exposure checks sample eye-level concentration once per second (every 20 ticks). Smoke damage accrues independently and executes at most once every 20 ticks to align with vanilla damage immunity cooldowns.

Particles

The particle engine reads precomputed ceiling and exhaust profiles generated during the simulation pass, checking chunk status and block passability prior to spawning. It verifies block types and active burn states so extinguished or broken sources stop emitting immediately.

• The default budget allows 64 spawn events per visual update, running every 10 ticks (up to 128 events per second at 20 TPS).
• Up to 16 events per update are reserved for sources and up to 12 for vents, with remaining slots allocated to ceiling smoke.
• Plume and vent selections cycle on an epoch counter to avoid favoring specific hash table entries. Category priority shifts when source or exhaust allocations fill the frame.
• Ceiling smoke selection prioritizes dense pockets close to players, adding slight temporal jitter to prevent repetitive patterns. Spatial player indexing avoids evaluating every candidate against every online player.
• Particle limits apply to server spawn events rather than individual network packets; one event reaches all qualified players in range. Individual player checks observe both the configured view distance and the vanilla 32-block client particle threshold.
• Exhaust smoke calculations operate normally down through negative Y levels.

Ceiling effects spawn vanilla LARGE_SMOKE particles just below obstructed roof blocks, using wide horizontal dispersion and tight vertical drift to give the appearance of trapped smoke on unmodified clients.

Configuration

The configuration file is created at config/realistic-smoke.json on first run. Any missing keys are populated with defaults.

The mod validates numeric inputs on startup, replacing non-finite values with defaults. If the file is unreadable or malformed, the game logs a warning and uses default values in memory without overwriting the broken file on disk. Config writes serialize to a temporary file before replacing the target via an atomic filesystem move.

Status effect durations cover the sampling period with an added buffer to prevent visual flicker between ticks. Unapplied damage calls retry across a short grace window, resetting if exposure drops below the lethal threshold. Smoke damage uses vanilla magic damage, respecting standard potion effects and protective enchantments.