Contraption Lights

Bi-directional Coloured Dynamic Lights for Create and Sable.

Put a lantern, glowstone, or any glowing block on a Create contraption or a Sable sub-level, and the light travels with it as it drives, flies, rotates, tilts, or sails. No more pitch-black cabins and tunnels.

Light also passes between your builds and the world in both directions, so a torch on the shore lights a passing ship and the ship's lanterns light the shore. Turn on coloured light and every glowing block lights in its own colour, on your builds and throughout the world. Every dependency is optional: install a backend, something to light, and nothing else.

What can carry light

• Create contraptions - carts, gantries, elevators, bearings: anything assembled and moving, rotating parts included.
• Create kinetics - rotating shafts and cogs, rendered in place by Flywheel.
• Sable sub-levels - physics-driven structures such as ships and dynamic trees.
• Other Flywheel content - blocks and entities drawn by non-Create mods such as Vanillin. Needs Flywheel 1.0.6+, no Create.
• Sable Ragdolls limbs - a ragdolled player keeps carrying their light: a torch in hand still lights the scene while they are limp.

Glowing blocks hidden inside Create copycats and items framed in placards count too, casting the light of whatever they hold.

How light travels

Direction	What you get	Turn it on
Build lights the world	A moving build throws its own light onto the terrain, following every turn of a bearing and roll of a ship. A beacon riding a sub-level casts its beam out along the sub-level's up axis, like a steerable searchlight.	On by default
World lights the build	Held torches, glowing mobs, dropped items, placed torches, glowstone and lava shine back onto a passing build. Directed sources count too, so another mod's flashlight or a beacon beam lights what it sweeps across.	The ...WorldTo... options
Builds light each other	A lit ship lights a nearby contraption or kinetic, and a lit contraption lights nearby kinetics.	Nothing extra. A build already emits, so the option that lets it receive from the world lets it receive from another build.
Builds riding builds	A bearing-driven propeller with a lantern, spinning on a moving ship, lights the deck, the world and other structures, and is lit by all of them in return, tracked to where it is actually drawn.	Automatic once the relevant options above are on

Coloured light

Off by default, and one option turns it on. A torch then glows warm, a soul lantern blue, a redstone torch red, and a froglight the pastel shade of its own texture.

Where two lights overlap their colours blend: a redstone torch beside a soul torch reads purple between them, and a coloured light near a white one still tints it. Colours fade smoothly with distance.

It reaches everything the mod already lights, and the rest of the world with it: blocks, entities, block entities, particles and lava, the lights your builds carry, held items, contraptions and kinetics and anything else Flywheel renders, and anything lighting the world through LambDynamicLights. The one enableColoredLight option covers every mode, VEIL included.

A shaderpack does its own lighting, so coloured light turns itself off while one is loaded and comes back when you unload it. While it is off it costs nothing: no extra memory in Sodium's terrain and none in Flywheel's lighting.

Colours come from data files, so a resource pack or another mod can change any of them or add its own. See Adding light colours.

For colours on other mods' blocks, install Contraption Lights Compat by DadamaldaDad. It covers Supplementaries, Twilight Forest, Immersive Engineering, Farmer's Delight, the Kaleidoscope mods, many Create addons and more. It is maintained separately, so report its colours to its own issue tracker.

Modes

Client lighting has one mode setting. The server option is separate and needs no client mod.

Mode	Light it produces	Shaders	Needs	Covers
LAMB (default)	Smooth per frame and cheap, no shadows. Vanilla-coloured until you turn on coloured light, which this mode supports in full.	Yes	LambDynamicLights	Every direction above.
VEIL (experimental)	Crisp angled shadows cast by a tilted sub-level's own blocks, which no other mode does. Follows the same enableColoredLight option as LAMB.	No. Veil stands down whenever Iris is installed, so this mode disables itself.	Veil	Your build lighting the world, plus a rougher take on the reverse. No cross-build light, no riding builds, no Flywheel kinetics. Not meant for normal play.
Server light blocks	Real invisible light blocks placed as a build moves and cleaned up behind it, so every player sees it with no client mod.	Yes	Nothing on the client	Your build lighting the world. Heavier, so off by default and meant for server admins.

Setup

Mod	Enables
LambDynamicLights	LAMB mode.
Veil	VEIL mode.
Create 0.6+	Contraptions, kinetics, copycat and placard light.
Sable	Sub-levels, on any mode.
Sable Ragdolls 0.7+	A ragdolled player's held light.
Sodium 0.8.12+	The options below in Video Settings. Coloured light works with Sodium installed or without it.

Common setups: Create + LambDynamicLights for smooth contraption lighting; Sable + a backend for ships with no Create; Create + the server option for a whole server at once. Running Iris shaders, use LAMB. Coloured light is a separate option on top of whichever mode you pick.

Options

Everything has sensible defaults. Client options live in the in-game config screen, the config file, and Sodium's Video Settings.

Client

Option	Default	What it does
mode	LAMB	Rendering backend: LAMB, VEIL or OFF. A mode whose mod is absent lights nothing and says so on screen; your choice is kept, so installing the mod later just works.
luminanceMultiplier	1.0	Overall brightness, up to 2.0.
updateInterval	0	Milliseconds between updates of the light a build casts outward. 0 is every tick, smoothest; higher costs less.
worldUpdateInterval	0	The same, for light cast back onto a build.
showStatusOverlay	on	Show a short message in the bottom-right when something needs attention (no backend installed, a backend missing, a feature that disabled itself). Click its x to dismiss. Everything shown also goes to the log.
enableContraptionDynamicLight	on	A Create contraption casts the light it carries.
enableSubLevelDynamicLight	on	A Sable sub-level casts the light it carries, including a carried beacon's beam.
enableWorldToContraptionLambLight	on	World light shines onto Create contraptions. Needs Create's Flywheel backend.
enableWorldToSubLevelLambLight	on	World light shines onto Sable sub-levels, dynamic sources and static blocks alike.
enableWorldToFlywheelLight	on	World light shines onto Flywheel-rendered blocks and entities. Needs Flywheel 1.0.6+, works without Create.
enableWorldToStructureVeilLight	on	VEIL mode only: world light shines onto contraptions and sub-levels.
enableSubLevelOcclusion	on	A sealed room inside a Sable sub-level holds its light in and keeps outside light out, in both directions. Needs Sable.

Client, coloured light

Option	Default	What it does
enableColoredLight	off	Every glowing block lights the world in its own colour, and overlapping lights blend. Turns itself off while a shaderpack is loaded.
colorIntensity	1.0	How far a colour departs from white. Below 1 washes towards white, above 1 deepens, 0 leaves every light white.
colorfulCandles	on	Dyed candles glow the colour of their wax. Off gives every candle a warm flame.
deriveColorFromTexture	on	Blocks with no colour of their own take one from their texture. Off gives them a warm torch glow instead.
animatedLightColors	on	Let a resource pack give a block a colour that cycles. Off holds every such light at the average of its colours.

Client, Iris fixes

Sable sub-levels are lit incorrectly whenever Iris is installed. These restore them, and are applied by a bundled "Contraption Lights Fixes" mod that ships inside Contraption Lights and appears as its own entry in the mod list. All three need Sable, Iris and Veil installed.

Option	Default	What it does
fixSubLevelShading	on	Restore directional face shading, which otherwise looks flat and too bright. Follows the build as it tilts, with or without a shaderpack.
fixSubLevelSkyLight	on	Go dark in caves and underground instead of staying lit as if under open sky.
fixSubLevelAmbientOcclusion	on	Shade corners and recesses the way the shaderpack shades the world's, instead of washing them out and dimming glowing blocks. Only with a shaderpack loaded, and only for packs that handle ambient occlusion themselves.

Server

Option	Default	What it does
enableContraptionLightBlock	off	Place real light blocks as a Create contraption moves.
enableSubLevelLightBlock	off	Place real light blocks as a Sable sub-level moves.
enableSubLevelLightBlockOcclusion	on	A light inside a sealed room on a Sable sub-level places no light block in the world outside.
minLightBlockEmission	1	Only place a light block for sources at least this bright, to place fewer of them.
lightBlockMergeTolerance	1	Lights next to each other share one light block when no spot ends up more than this many light levels darker. 0 shares only where nothing gets darker.
maxLightBlockChangesPerTick	0	Most light blocks placed, changed or removed per tick in each dimension, the rest following on later ticks. 0 is no limit.

Light blocks go into air and water, and are only ever removed by the mod that placed them. Players who also run the mod with coloured light on see them in their source's colour.

Adding light colours

Any block can be given its own light colour, including blocks this mod has never heard of, and the colours it ships for vanilla blocks can be overridden the same way. There are three routes:

• A JSON file in a resource pack or inside a mod jar, matching on block id, block tag or blockstate. This needs no dependency on this mod and no coordination, so a mod can ship colours for its own blocks and they are picked up if a player installs both. A file can name the mods it needs, so one pack can carry colours for many of them.
• The same file can colour a glowing entity or a lit item, such as a blaze or a lava bucket in hand, give a block a colour that cycles over time, or colour a light that comes from no block at all, such as a flashlight another mod adds through LambDynamicLights.
• A small Java API, for a colour that cannot be written down as a function of the blockstate: a lamp holding a dyed bulb, a colour stored in a block entity, one read from an attached machine.

All of it is documented in the wiki, along with how the mod decides a colour when nothing has claimed a block, and the settings that change it.

Page	Covers
How colours work	What a colour means to the mod, the order every source is consulted in, how a colour is guessed from a texture, and every setting that affects it
Resource pack colours	The full JSON reference: fields, matching rules, cycling colours, entities and items, behaviour lights, error handling
Java API	Supplying a colour from code

FAQ

Which mode should I use? LAMB. It covers every direction light travels, works with shaders, and supports coloured light in full. VEIL exists for crisp angled shadows on tilted sub-levels, is experimental, and does nothing while Iris is installed.

Do other players need the mod? For LAMB and VEIL, yes, each player installs it. For the server light-block option, only the server does and everyone sees the light.

The server places light blocks and I run the mod too. Is the light doubled? No. Where the two overlap the brighter one wins, so a build looks the same as with either alone, and with coloured light on the server's light blocks take their source's colour. They move a whole block at a time, so on a fast build they can sit slightly off your own smoothly moving light. Each step also makes your game rebuild the chunk sections around it, which costs a little frame rate with many moving lights.

My Sable sub-levels look flat, too bright, washed out at the corners, or stay lit underground. That is the Iris break the bundled fixes above are for. Check Sable, Iris and Veil are all installed and the three fixSubLevel... options are on. Shading and sky light take effect immediately; ambient occlusion applies to sections as they rebuild.

Coloured light does nothing. Check it is on, since it is off by default, and that no shaderpack is loaded, since it stands down while one is. If one block looks wrong rather than all of them, the mod may have no colour on file for it and be guessing from its texture; Contraption Lights Compat may already cover it, or give it a colour with a data file as the wiki describes, or turn deriveColorFromTexture off to make everything unknown glow warm instead.

Light still gets into my sealed cabin. The room has to be closed on every side by blocks that stop light on their own. Glass, slabs, stairs, fences and open trapdoors all let light past, and one gap anywhere leaves the room open. Set enableSubLevelOcclusion off if you would rather light passed through hulls.

Nothing lights up. Watch the bottom-right corner from the main menu onward: if the setup is at fault, the mod says so there. Otherwise check the backend's mod is installed, the build actually carries a glowing block, and the matching option is on. Both server options are off by default.

Credits

• Logo by arthursimon900.

License

All Rights Reserved. You may include this mod in modpacks.