☀️ Sunwell

A portable hole in the ceiling. Real sky light underground — on your terms.

Sunwell adds craftable Sunwell Lanterns that project true Minecraft sky light into enclosed spaces. Crops grow. Dynamic Trees survive. Daylight sensors respond. Rain falls through.

Like open sky — except you hang it from a ceiling.

Pack makers get a tag-driven engine: register any block as a simple grow lamp, a full weather-aware sunwell, or anything in between. No Java required.

✨ Why not just a torch?

🏮 The Sunwell Lantern

• 🪝 Vanilla lantern placement — stands on the floor or hangs from a ceiling
• 🔦 Projects virtual sky light below in a downward-widening cone — hang it higher, light a wider pool of floor. Like a small sun.
• 🌗 The orb mirrors the sky it stands in for (see below)
• ⚡ Rare lightning through the column in thunderstorms — far more often near a lightning rod
• 🧪 Recipe: Quartz ×3 · Iron Bars ×4 · Glowstone · Glass

⚠️ Upgrading from 2.0.x — the Soulwell Lantern has been removed

One lamp now presents every sky, so a separate soul variant no longer has a job. Placed Soulwell Lanterns will not survive the update, and any recipe, tag, or script referencing sunwell:soulwell_lantern must be updated.

<details> <summary>💡 Why is the block light only 8?</summary>

Because the lantern lights your room through its sunwell, not by being a torch.

That projected light already scales with day, night and weather — so it genuinely dims in a storm and drops further at night. A constant block light 15 drowned all of that out and pinned every room at full brightness, which also buried the orb it exists to show off.

</details>

🌤️ The orb is a window

Look into the lantern and you see the sky it stands in for.

It changes when the sky changes and as fast as the sky changes.

<details> <summary>⏱️ …because it runs on Minecraft's clocks, not its own</summary>

• 🌅 Dusk & dawn follow the game's real twilight ramp — the exact curve the world darkens on, stretched across the full ~90 seconds it actually takes.
• 🌩️ Weather rides vanilla's own ~5-second ramp. A clear sky slamming into a thunderstorm lands hard, because vanilla drives it that way.
• ☁️ Orb → cloud is a real transformation: the orb flattens and spreads as cloud cover arrives, and the cloud rises out of that same pose. Sun → moon is a straight cross-fade — one round orb dissolving into another.

There is no fade timer anywhere in it. The mix of skies is the sky, sampled every frame — so the lantern can't lag behind the world or run ahead of it.

</details>

<details> <summary>🌧️ Rain, snow & the sprinkler</summary>

Precipitation falls through the lit cone and splashes where it lands, using Sunwell's own rain particle — so it looks the same whether or not a weather mod is installed.

A lantern standing on the ground has nothing to rain "down" into, so it throws its weather outward and up instead, arcing back down across the radius it lights. Like a sprinkler.

</details>

<details> <summary>🎨 How the glow is drawn</summary>

Everything is rendered additively with no depth-write, so nothing z-fights or tears against the cage as the camera moves. The halo is a real radial gradient — a soft round bloom, not a hard-edged square overlay.

The orb sits on cutout while settled (alpha-tested, no sorting, so the overlapping orb boxes can't shimmer) and only switches to translucent mid-dissolve, where the fade hides any sorting wobble.

</details>

💡 Tip — Every effect is gated by config (lanternFlux, respondToWeather, weatherShaftParticles, lightningThroughOdds, lightningRodBoost), so packs can dial it back or off entirely.

🏷️ Tag-driven behavior

Every sunwell block needs #sunwell:sunwell_source. That alone gives a static grow light — always-on virtual sky at skyLevel, no undead burn, no weather dimming, no rain.

Opt into more with additional tags:

The Sunwell Lantern ships with all four.

📝 Note — Full weather presentation (the sky-mirroring orb, rain & snow shafts, sun shafts, and lightning through the column) requires both dynamic_exposure and rain_through. Pack blocks must opt in explicitly.

<details> <summary>📦 Datapack — static grow lamp</summary>

data/sunwell/tags/blocks/sunwell_source.json

{
  "replace": false,
  "values": [
    "yourmod:ceiling_lamp"
  ]
}

</details>

⚠️ On Minecraft 1.21+ this folder is singular: data/sunwell/tags/block/sunwell_source.json (likewise recipe/, loot_table/).

<details> <summary>🔧 KubeJS — static grow lamp</summary>

ServerEvents.tags('block', event => {
  event.add('sunwell:sunwell_source', 'kubejs:ceiling_lamp')
  event.add('sunwell:sunwell_source', 'blockofsky:sky_block')
})

</details>

<details> <summary>🔧 KubeJS — the full treatment</summary>

ServerEvents.tags('block', event => {
  const block = 'yourmod:solar_panel'
  event.add('sunwell:sunwell_source',   block)
  event.add('sunwell:dynamic_exposure', block)
  event.add('sunwell:undead_burning',   block)
  event.add('sunwell:rain_through',     block)
})

</details>

💡 Tip — Tags grant capability; config can revoke it. Global toggles like enableUndeadBurning and respondToWeather act as pack-wide master switches over everything the tags allow.

⚙️ How it works

1. Place a Sunwell Lantern (or any tagged block).
2. The mod flood-fills the open air below it, stopping at solid blocks.
3. That flood spreads in a cone — every block of descent buys extra horizontal reach (coneSpread), so a high ceiling lamp lights a wide pool of floor.
4. Inside the region, sky light is raised to skyLevel (default 14).
5. Blocks with dynamic_exposure dim and brighten with the outside world; static sources stay at full grow strength around the clock.

<details> <summary>🚀 Performance & correctness</summary>

Bounded flood-fill with per-tick chunk and node budgets, chunk caching and adaptive batch sizing — built for dense lamp layouts in large underground builds.

Light is published to other threads as immutable snapshots, so chunk meshing never reads a map the flood is still writing.

Removing a source re-floods and clears its region, and the client re-renders the affected area immediately — no stale "still exposed to sky" lighting left hanging around.

</details>

🎛️ Configuration

All options live in config/sunwell-server.toml.

<details> <summary>📐 Region — how far the light reaches</summary>

</details>

<details> <summary>💡 Light — how bright, and how it falls off</summary>

</details>

<details> <summary>🌍 Behavior — weather, burning, spawns, lightning</summary>

</details>

<details> <summary>🚀 Performance — tick budgets</summary>

</details>

<details> <summary>🐛 Diagnostics — when something looks wrong</summary>

</details>

<details> <summary>💭 Recipes for common setups</summary>

• Always-on grow rooms → tag blocks with sunwell_source only, or set followDayNightCycle = false on dynamic sources.
• Sealed backrooms bases → ceiling grow lamps use sunwell_source only. For portable lanterns underground, set followDayNightCycle = false so crops keep growing at night. Pair with respondToWeather = false if you don't want rain shafts indoors.
• Safe undead farms → omit undead_burning, or set enableUndeadBurning = false.
• Wider pools from high ceilings → raise coneSpread. It costs flood budget, so raise nodeBudgetPerTick to match.
• Leave skyLevel at 14 unless you explicitly need vanilla canSeeSky() (15).

</details>

📦 Supported versions

<details> <summary>Differences between the two builds</summary>

The 1.21.1 build carries the full lantern, VFX and tag-driven light system. It does not bundle the optional Amendments wall/hand-lantern integration that ships on 1.20.1, and its data-pack folders are singular (tags/block, recipe, loot_table) rather than plural.

Other Minecraft or loader versions are not supported.

</details>

📜 Credits & license

Sunwell is an original mod by SdataG — all code, block models, textures and client VFX were written and authored for this project. No assets or textures were ported from any prior mod.

<details> <summary>On prior art</summary>

The general idea of a ceiling-mounted virtual skylight lantern is familiar in the modding community, including older projects such as Ferreus Veritas's Skylight Lanterns.

Sunwell is an independent reimplementation with its own architecture: tag-driven profiles, an exposure system, rain-through weather hooks, performance budgets, models, textures and client presentation.

</details>

License: MIT

Source on GitHub · Project page · Changelog