OpenXcom Extended - Coloured Lighting test build
==================================================

Build:    Extended 8.6.1 + coloured-lighting branch
Commit:   1d7300d51
Branch:   https://github.com/lewster32/OpenXcom (coloured-lighting-oxce)
Upstream: OpenXcom Extended (Meridian) - https://openxcom.mod.io/openxcom-extended

This is a test build of OXCE with an experimental coloured-lighting pipeline
on top: realistic LOS-traced light propagation, additive RGB tint per tile,
per-corner light mixing for floors and walls, modder-tunable per-source
colour / radius / intensity / litChance / offset, dithering, perceptual
palette snap, and a small ambient sky-tint pass. The master switch is on by
default in this build - turning it off restores byte-equivalent vanilla
OXCE behaviour.


Installing
----------

1. Unzip this archive somewhere writable (NOT inside Program Files unless
   you are happy running as administrator - OpenXcom writes a log file
   alongside the executable).

2. Copy your X-COM: UFO Defense data files into the UFO/ subdirectory.
   At minimum the UFO/ folder needs:
     GEODATA, GEOGRAPH, MAPS, ROUTES, SOUND, TERRAIN, UFOGRAPH, UNITS
   (plus optional UFOINTRO).
   See UFO/README.txt for full details.

3. (Optional) If you also have X-COM: Terror From The Deep, copy its
   data files into the TFTD/ subdirectory the same way. See TFTD/README.txt.

4. Run openxcom.exe. The user / config / save folder is auto-created at
   %USERPROFILE%\Documents\OpenXcom\.


Lighting options
----------------

In-game: Options -> Advanced -> Battlescape category. Master switch:

  Realistic Lighting              - default ON. The master gate. Off =
                                    vanilla OXCE. On = LOS-traced light
                                    propagation, additive RGB mixing, and
                                    inverse-square clamped falloff.

Sub-options (only honoured when Realistic Lighting is on):

  Allow modder colour overrides   - default ON. When on, mods that ship
                                    light: { color: ..., source: ..., ... }
                                    blocks (see below) override the auto-
                                    derived colour and radius. When off,
                                    the engine derives colours from the
                                    sprite alone.

  Per-corner colour interpolation - default ON. When on, floor and wall
                                    tiles linearly interpolate between
                                    per-corner light values for smoother
                                    lighting gradients across the map.

  Coloured light dither           - default 2 (Floyd-Steinberg).
                                    0 = none, 1 = ordered Bayer,
                                    2 = Floyd-Steinberg error diffusion.
                                    Reduces banding in the per-corner
                                    interpolation at low palette depth.


Bundled mods
------------

The standard/ folder ships two new mods you can enable from the in-game
Mod Manager (Options -> Mods):

  Realistic Lighting              - For UFO. Adds per-MCD light colours,
                                    radii, intensities, litChance and
                                    ambient-by-time-of-day for craft
                                    interiors, alien bases, urban tiles,
                                    Cydonia, and more.

  Realistic Lighting              - For TFTD. Equivalent set covering
                                    Triton, Hammerhead, Leviathan, alien
                                    colonies, ports, liners, and more.

Both mods only have a visible effect when the Realistic Lighting master
switch is on. With it off they parse but do nothing.


Reporting issues
----------------

This is a development branch, not an upstream release. Please report bugs
against the lewster32/OpenXcom fork on GitHub, NOT to the OpenXcom Extended
or OpenXcom upstream issue trackers.


Restoring vanilla behaviour
---------------------------

If anything looks visually wrong, try toggling Realistic Lighting to Off
in Options -> Advanced. With the master switch off this build is a clean
OXCE 8.6.1 binary that ignores all of the new code paths. If a problem
still reproduces with the master switch off, that's an unrelated regression
- please report it with that detail included.
