ludic/ns-light.html

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Light — Ludic</title>
<meta name="description" content="A software 2D light-accumulation pass over the framebuffer, run in a render phase after drawing the scene and before Screen.show.">
<link rel="stylesheet" href="base.css">
<link rel="stylesheet" href="docs.css">
</head>
<body>
<header class="nav"><div class="wrap nav-in"><a class="brand" href="index.html"><span class="logo">L</span> Ludic</a><button class="nav-toggle" aria-label="Toggle menu" aria-expanded="false">☰</button><nav class="nav-links"><a href="index.html">Home</a><a href="api.html">API Reference</a><a class="nav-cta" href="https://git.workshopsoft.io/workshopsoft/ludic">Source ↗</a></nav></div></header>
<main class="wrap item">
  <div class="crumbs"><a href="api.html">API Reference</a> <span>›</span> <span class="here">Light</span></div>
  <div class="item-head"><span class="kind-badge kind-namespace">namespace</span><h1 id="top">Light</h1></div>
  <p class="ns-blurb">A software 2D light-accumulation pass over the framebuffer, run in a render phase after drawing the scene and before <a href="screen-show"><code>Screen.show</code></a>. <a href="light-ambient"><code>Light.ambient</code></a> multiplies the whole scene toward a tint — the night/cave modulate that darkens everything so lights add mood back on top. <a href="light-point"><code>Light.point</code></a> accumulates a radial glow that falls off with distance and clamps per channel, and <a href="light-occlude"><code>Light.occlude</code></a> registers rectangles that block a light's rays to cast hard shadows (cleared each frame with <a href="light-clear_occluders"><code>Light.clear_occluders</code></a>). Lighting is a rendering concern only — it never touches game state or replays — and it is fully deterministic (integer and Q16.16 fixed), so the same scene lights identically every run and in a headless render, keeping screenshots diffable. Colours are <code>0x00RRGGBB</code>. Beyond the radial core, the pass carries the render-quality tiers: <a href="light-spot"><code>Light.spot</code></a> cones, a <a href="light-falloff"><code>Light.falloff</code></a> exponent, <a href="light-soft"><code>Light.soft</code></a> shadows (penumbra), <a href="light-gel"><code>Light.gel</code></a> colour cookies, normal-mapped surfaces (<a href="light-normal"><code>Light.normal</code></a> + <a href="light-height"><code>Light.height</code></a>) that shade by facing, and a <a href="light-time_of_day"><code>Light.time_of_day</code></a> day/night ramp — every one deterministic. This is the imperative surface; the engine also consumes <code>Light2D</code>/<code>Occluder</code> components automatically (a Light2D may carry optional <code>direction</code>/<code>spread</code>/<code>falloff</code>/<code>softness</code>/<code>gel</code> fields). Related: <a href="screen"><code>Screen</code></a>, <a href="color"><code>Color</code></a>, <a href="camera"><code>Camera</code></a>.</p>
  <div class="ns-methods"><a class="ns-method" href="light-ambient.html"><code class="nm-sig">Light.ambient(color)</code><span class="nm-tip">Multiply the whole scene by a tint — the night/cave modulate.</span></a><a class="ns-method" href="light-point.html"><code class="nm-sig">Light.point(x, y, radius, color, energy)</code><span class="nm-tip">Add a radial glow that falls off with distance.</span></a><a class="ns-method" href="light-occlude.html"><code class="nm-sig">Light.occlude(x, y, width, height)</code><span class="nm-tip">Register a rectangle that blocks light — a hard shadow caster.</span></a><a class="ns-method" href="light-clear_occluders.html"><code class="nm-sig">Light.clear_occluders()</code><span class="nm-tip">Forget every occluder — call once per frame before re-registering.</span></a><a class="ns-method" href="light-spot.html"><code class="nm-sig">Light.spot(x, y, radius, color, energy, direction, spread)</code><span class="nm-tip">A cone / flashlight light aimed at a direction with a half-angle spread.</span></a><a class="ns-method" href="light-falloff.html"><code class="nm-sig">Light.falloff(exponent)</code><span class="nm-tip">Set the brightness-ramp exponent for later lights (1 linear, 2 quadratic…).</span></a><a class="ns-method" href="light-soft.html"><code class="nm-sig">Light.soft(radius)</code><span class="nm-tip">Soft shadows — an occluder edge fades through a penumbra of this radius.</span></a><a class="ns-method" href="light-gel.html"><code class="nm-sig">Light.gel(color)</code><span class="nm-tip">A colour cookie — later lights gel from their centre colour to this rim colour.</span></a><a class="ns-method" href="light-clear_gel.html"><code class="nm-sig">Light.clear_gel()</code><span class="nm-tip">Clear the gel — later lights are a flat single colour again.</span></a><a class="ns-method" href="light-normal.html"><code class="nm-sig">Light.normal(x, y, width, height, nx, ny)</code><span class="nm-tip">Stamp a surface normal over a rectangle so lights shade it by facing (N·L).</span></a><a class="ns-method" href="light-clear_normals.html"><code class="nm-sig">Light.clear_normals()</code><span class="nm-tip">Forget every stamped normal — call once per frame before re-stamping.</span></a><a class="ns-method" href="light-height.html"><code class="nm-sig">Light.height(height)</code><span class="nm-tip">Set the virtual height of lights above the surface, for normal-map shading.</span></a><a class="ns-method" href="light-time_of_day.html"><code class="nm-sig">Light.time_of_day(t)</code><span class="nm-tip">Set the ambient tint from a 0..1 time-of-day — a day/night cycle in one value.</span></a></div>
  <a class="back" href="api.html">← All symbols</a>
</main>
<script src="ludic-highlight.js"></script>
<script>Ludic.installCards(); Ludic.flashTarget();</script>
</body></html>