Light Dust

Light Dust is a lightweight client side mod that adds floating dust to your world. Built with interactive physics, dust reacts to light, weather, and the exact biome you are exploring.

if you want a more in depth guide as to how to configure this mod check out the new wiki!.

Features

• Biome specific dust: Dust tints and changes behavior based on the specific biome you are exploring.
• Light dust tinting: Dust gets tinted based off the light sources that are near it, dust near fire are tinted slightly orange and dust near glow stone are tinted a bright pale yellow (works with modded as long as you add it to the list and add a color).
• Advanced Wind: A fluid dynamics simulation that causes dust to swarm, sweep, and flow. It utilizes a sky light gradient to allow drafts to work under trees, overhangs, and in tunnels.
• Thermal Updrafts: Particles above heat sources like fire, campfires, and lava, cause them to swirl upward.
• Directional Block Breaking: Debris shoots out from the specific face of a block you hit. This debris can bounce or slide off nearby walls. Breaking a block also creates a vacuum that pulls nearby ambient dust toward the empty space.
• Cave Tremors: Explosions and other loud sounds trigger a shockwave that drops debris from the ceiling. The effect is most intense at the epicenter and fades as it travels outward.
• Combat & Movement: Dust reacts to sprinting, sword swings, and shield raising by being pushed away within a configurable interaction radius.
• Heavy Landings: Falling three or more blocks kicks up a scaling ring of dust upon impact, displacing any existing ambient particles in the landing zone.
• Dynamic Block Colors: Debris, landing dust, and tremor particles use the map color of the block you are interacting wit so dirt will have dirt tinted debris dust and stone will have grey tinted debris dust.
• Dynamic Lights Compatibility: handheld lights (torches, lanterns, etc.) spawn a local area of dust around the player. This is compatible with Curios and Accessories slots.
• Dust Glinting: Particles subtly glint when approached. In dark areas, dust near light sources softly illuminates before fading as it drifts away.
• Configurable: configs are split across 3 files (main.toml, colors.toml, experimental.toml).

Configuration

All values are adjustable in the config/lightdust/ folder (split into main.toml, colors.toml, and experimental.toml).

Spawning & Performance

• enableMaxYLevel (Default: false): Toggle for the height limit.
• maxYLevel (Default: 60): The height coordinate where dust stops spawning.
• ambientRadius (Default: 10): How far away from the player dust will attempt to spawn.
• ambientHardCapRadius (Default: 12): The absolute maximum distance dust can exist. Particles further than this are deleted instantly.
• ambientBlockCap (Default: 14): The maximum density of dust allowed in a single block.
• minBlockLight (Default: 6): The minimum block light level required for ambient dust to spawn.
• daytimeLightDiff (Default: 5): The minimum difference between Block Light and Sky Light required for dust to spawn during the day.
• falloffDistance (Default: 6): Distance from the player where dust density starts to decrease.
• falloffMultiplier (Default: 0.3): Multiplier applied to the max particle cap beyond the falloff distance.
• enableOcclusionCulling (Default: true): Uses LOS raytracing to prevent dust from spawning behind solid walls.

Visuals & Environment

• useHdParticles (Default: true): Toggle for the HD dust particles or use the legacy version. Note that if you use this you should lower the values for particle size and opacity slightly. (I suggest 0.016 and 0.18 respectively)
• enableDynamicBlockColors (Default: true): Toggle for the block color inheritance system.
• ambientDustOpacity (Default: 0.18): Base opacity for ambient dust.
• particleSize (Default: 0.016): Adjust the visual size of the ambient dust particles.
• particleLifetime (Default: 200): Control how long (in ticks) dust particles stick around.
• windSpeedClear (Default: 0.25): Adjusts global wind drift during clear weather.
• windSpeedRain (Default: 0.35): Adjusts global wind drift during rain.
• windSpeedThunder (Default: 0.5): Adjusts global wind drift during thunder.
• disableDuringRain (Default: false): Toggles to prevent outdoor dust from spawning or existing during rain.
• disableDuringThunder (Default: false): Toggles to prevent outdoor dust from spawning or existing during thunder.

Interactions & Actions

• breakParticleCount (Default: 12): Controls the volume of the block-breaking debris.
• breakParticleSpeed (Default: 0.1): Controls the speed of the block-breaking debris.
• actionDustGravity (Default: 0.002): Controls the fall speed of debris hitting surfaces.
• actionDustBounce (Default: 0.2): Controls the bounciness of debris hitting surfaces.
• breakVacuumRadius (Default: 1.2): The radius in blocks that ambient dust is pulled toward a broken block.
• breakVacuumForce (Default: 0.01): How strong the dust is pulled toward the broken block.
• caveTremorParticleCount (Default: 90): The base density of falling debris during explosions.
• tremorEpicenterMultiplier (Default: 5.0): Controls intensity at the blast center.
• tremorFalloffExponent (Default: 6.0): Controls how quickly intensity fades from the blast center.
• tremorCeilingBias (Default: 0.75): Adjusts the ratio of ceiling-to-floor spawns.
• tremorFloorKickForce (Default: 2.1): Adjusts the upward force for floor dust.
• tremorWavefrontThickness (Default: 6.0): Controls the depth of the expanding shockwave zone.
• tremorMaxGravity (Default: 0.04): Adjusts the weight of debris at the center.
• tremorMinGravity (Default: 0.001): Adjusts the weight of debris at the outer edge.
• tremorRoofMultiplier (Default: 0.4): Multiplier for the gravity applied to dust falling from the ceiling.
• tremorFloorMultiplier (Default: 0.2): Multiplier for the gravity applied to dust kicked up from the floor.
• playerInteractRadius (Default: 4.0): The radius at which player movements physically push dust particles.
• heavyLandingMaxParticles (Default: 96): Controls how many particles spawn when taking fall damage.
• heavyLandingParticleMultiplier (Default: 12): Controls the multiplier for particles spawned when taking fall damage.
• heavyLandingUpwardSpeed (Default: 0.2): Controls the speed of the heavy landing dust ring upward.
• heavyLandingOutwardSpeed (Default: 0.12): Controls the shape of the heavy landing dust ring outward.
• heavyLandingAmbientPush (Default: 0.001): Controls the shockwave force that pushes ambient dust away when you land.
• heavyLandingAmbientRadius (Default: 4.0): Controls the shockwave radius that pushes ambient dust away when you land.
• heatBlocks (Default: DEFAULT_HEAT_BLOCKS): List of blocks that emit heat for thermal updrafts.

Dynamic Lights Compat

• enableHandheldLights (Default: false): If true, items held in your hand will act as fake light sources, allowing dust to spawn and coloring the dust.
• handheldLightItems (Default: DEFAULT_HANDHELD_LIGHTS): List of items/tags and their light properties. Format: 'modid:item_name=radius,#HEXCOLOR' or '#modid:tag=radius,#HEXCOLOR'.

Experimental Features (experimental.toml)

• enableEntityDisturbance (Default: true): Allows non-player entities (mobs/projectiles) to kick up and disturb dust. This is hard capped to only track the 6 closest moving entities.
• entityScanRate (Default: 4): How often in ticks the mod scans for nearby entities.
• entityPushStrength (Default: 0.05): How strongly entities push dust when moving through it.
• enableAdvancedWindMath (Default: true): Enable complex spatial turbulence and sweeping wind physics.
• enableWindDeflection (Default: true): Allows wind to realistically blow dust down tunnels.
• enableDustSettling (Default: true): Allows dust particles to visually settle when hitting the ground.

Color & Tinting Settings (colors.toml)

• tintStrength (Default: 0.75): Adjusts how strongly colored lights tint the dust. (suggest higher values if using Hd dust ex: 0.75).
• customTints: A list of light-emitting blocks and their hex colors for dust tinting.
• customBiomeTints: Define base ambient colors for biomes using hex codes.
• caveBiomeTriggers: Map specific blocks to a hex color for underground environment changes.

Q&A

Q: Does this work with true dark mods?

A: Yes. It should work with them. However, you may need to change the opacity of the dust.

Q: Does this work with Shaders?

A: Yes. However, shaders often change how transparency renders. If the dust looks too invisible, increase ambientDustOpacity in the config (try 0.45 or higher).

Q: Will this cause lag in big modpacks?

A: It is designed specifically to be lightweight. The mod has a ton of optimization options such as the newly added LOS and Hemisphere system aswell as Occlusion Culling to skip particle rendering behind solid walls. If you still drop frames, you can disable enableAdvancedWindMath or lower the particle caps in the configs.

Q: Can I change the color of the dust?

A: Yes! You can change the tint of light sources (customTints), the base color of any biome (customBiomeTints), and trigger colors underground using specific blocks (caveBiomeTriggers) in the colors.toml config.

Q: Does this work with modded biomes and caves?

A: Yep. Just add the modded biome ID or the modded blocks to the respective lists in the config, assign a hex color, and it should work just fine.

Q: How do I disable the Block Break particles?

A: Set breakParticleCount to 0 in the config.