OpenXcom Extended - Realistic Lighting test build
==================================================

Build:    Extended 8.6.1 + Realistic Lighting
Commit:   c477bb375
Engine:   OXCE-RL 1.0 (mod pin: requiredExtendedEngine: OXCE-RL)


Links
-----
Forum thread: https://openxcom.org/forum/index.php?topic=13068.0
Source code:  https://github.com/lewster32/OpenXcom/tree/coloured-lighting-oxce
Website:      https://www.rotates.org/oxce-rl/


This is a test build of OXCE with an experimental Realistic Lighting
pipeline on top: 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 -> OXCE -> 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 modded lights             - default ON. When on, mods that ship
                                    light: { color: ..., source: ..., ... }
                                    blocks override the auto-derived colour
                                    and radius. When off, the engine derives
                                    colours from the sprite alone.

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

  Dithered lighting               - 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 (Mods on the main menu):

  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. The primary place
to report problems is the forum thread:

  https://openxcom.org/forum/index.php?topic=13068.0

For code-level bugs you can also raise an issue on 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 -> OXCE -> Battlescape. 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.
