View source for Sonic Adventure/Lantern Engine

Lantern (stylized LANTERN) Engine is the internal name of the lighting system used in [[Sonic Adventure]] (Dreamcast). It is also the name of a mod that restores said lighting system in the PC version of Sonic Adventure DX.

= Overview of the SA1 Lighting System =
The Dreamcast version of Sonic Adventure has a lighting system (referred to internally as “LANTERN”) that consists of two modes:

# Palette lighting using a series of 256-color palettes.
# Lights set up by the Dreamcast’s Ninja library ([[Ninja Lights|Ninja]] [[Ninja Lights|Lights]]).

Lighting information for each level is stored in a pair of files: the PL file (PL_....BIN) contains the palettes, and the SL file (SL_....bin) contains light direction and data for setting up the Ninja Lights.

The [https://github.com/michael-fadely/sadx-dc-lighting Lantern Engine mod] for Sonic Adventure DX PC is a reimplementation of palette lighting for the PC port of SADX. At the moment it does not implement the Ninja Lights.

== Palette Lighting ==

=== Brightness Index Calculation ===
The palette-based system gives each vertex in the scene a “brightness index”, which is a value in the range of 0 to 255 used to select a color in a palette to set as vertex color. The brightness index is calculated using the following formula:

<code>1 - ((dot(normal, light direction) + 1) / 2)</code>, where <code>dot</code> is dot product and <code>normal</code> is vertex normal.

The result is multiplied by 255 to get the color index in the palette. If we visualized brightness indices (from white being maximum brightness to black being completely unlit), it would look something like this:
[[File:Brightness.png|none|thumb|Brightness indices visualized: from white (fullbright) to black (fully dark).]]

=== Diffuse and Specular Lighting ===
LANTERN palettes are applied in pairs to create diffuse and specular lighting.

* Diffuse color is the color that is calculated by multiplying the original color with the color in the diffuse palette. It works like the “Multiply” blending mode in Photoshop.
* Specular color is additive, so it works like the “Add” blending mode in Photoshop.

Making the diffuse color brighter makes the result closer to the original texture’s color. Making the specular color brighter adds to the brightness of the resulting color directly, so white diffuse + black specular is effectively the same as not applying any lighting at all, and white specular would make the vertex completely white regardless of the texture and diffuse color. Normally diffuse lighting is used to give the entire model or area a “base” color, while specular lighting is used to add gloss.
[[File:Palettesample.png|none|thumb|Diffuse palette samples (image by Speeps)]]

=== Palette Selection ===
The PL file can store up to eight pairs of diffuse/specular palettes, although only up to six pairs are used normally. There are several variables the game relies on to select which palettes to apply to a specific model:

'''1. Light type'''

This is a variable set in code before rendering the model. The light type value determines which diffuse palette is used by the model:
{| class="wikitable"
!Value
!Description
!Diffuse Palette
!Specular Palette
|-
|0
|Used by the majority of models in the game except characters and bosses.
|0
|0 or 1
|-
|2
|Used by characters and cutscene models.
|2
|2 or 3
|-
|4
|Used by some bosses and for blending effects.
|4
|4 or 5
|}
The majority of models in the game outside cutscenes use the level/object light type 0. These are the palettes you see on level pieces and most objects.

Character/NPC models and models used in cutscenes generally use the character/event light type 2, although there are some exceptions. For example, Amy’s Warrior Feather and some parts of Gamma’s body that are rendered as separate models (such as the Laser Scope) use the level/object light type 0 outside cutscenes. The gameplay models in Sky Chase use the level/object light type 0 despite being character-related; however, models involving the Tornado in Sky Chase cutscenes use the character light type 2. It happens the other way around as well: some non-character objects that would normally be using level/object palettes (such as floating meteors near the end of Twinkle Park Act 1) set the character light type so they also get character lighting, but this is uncommon.

The boss light type 4 is only used by a few models in the game. Diffuse 4 and Specular 5 are used by Chaos 2, Chaos 6 and Perfect Chaos. Diffuse 4/Specular 4 and Diffuse 5/Specular 5 are also used by the transition effect in Mystic Ruins Past when the Emerald Altar is on fire. The palettes blend between each other to create a burning fire effect.

'''2. Material flags'''

Material flags influence palette selection in the following ways:

* If a mesh’s material has the “ignore lighting” flag (<code>NJD_FLAG_IGNORE_LIGHT</code>), the mesh is not palettized and the fullbright texture is used as-is. Neither the diffuse nor the specular palette is applied to the mesh, but the rest of the meshset may be palettized depending on whether or not the remaining materials have the “ignore lighting” flag.
* If the model’s first material has the “ignore specular” flag (<code>NJD_FLAG_IGNORE_SPECULAR</code>), the entire model’s specular palette index is the same as the diffuse palette index (e.g. Diffuse 0, Specular 0).
* If the model’s first material doesn’t have “ignore specular”, the specular palette index is the diffuse index + 1 (e.g. Diffuse 0, Specular 1).

Note that only the first mesh’s material in the model affects specular palette selection, and all other meshes follow it regardless of whether they have “ignore specular” or not. Specular palette selection is consistent within a single model, but if the model has child or sibling models those are processed separately unlike the light type. So it is possible to have a model (e.g. Tails) that has child models with a different specular palette (Tails’ shoes). They would still use the same diffuse palette, however, as they would have the same light type as the parent model.

Sometimes the game forcibly adds or removes the “ignore specular” flag or sets a specific light type when rendering certain models. If you want to change palette selection in these cases, you would need to change/disable the code doing that, or use Lantern API to register those models’ materials for arbitrary palette selection.

'''3. White diffuse'''

In the Dreamcast version of SA1, if a mesh in a model has a material with the “ignore lighting” flag, the remaining meshes after it may get the fullbright diffuse palette (as if they were ignoring lighting), but keep the specular palette. The Lantern Engine mod does not do this by default. Dreamcast Conversion has an option to enable white diffuse.

'''4. Palette blending'''

There are cases when the game swaps or mixes different palettes for some special effects:

* The Past fire effect creates the level/object palettes (Diffuse 0/Specular 0) by mixing Diffuse 4/Specular 4 and Diffuse 5/Specular 5 using a blending coefficient. The Lantern Engine mod blends between Diffuse 0/Specular 0 and Diffuse 5/Specular 5 instead, which are identical to Diffuse 0/Specular 0 in the PL file anyway.
* Sky Deck Acts 1 and 2 swap palettes when the Egg Carrier changes altitude. Palettes in <code>PL_60B</code> are used normally, and palettes from <code>PL_61B</code> are used when the Egg Carrier descends into the clouds. While the original game only swaps the palettes, the Lantern Engine mod actually blends between them.
* The Egg Viper boss fight blends palettes in <code>PL_M0B.BIN</code> with specific colors (white, red and cyan).
* In Casinopolis Act 1, when Sonic goes to pinball areas the character specular palette blends with white, making character lighting brighter as Sonic is floating before getting teleported to the pinball field.

'''5. Palette selection example'''

Here is a simple example of palette selection based on Emerald Coast. Color-coded specular palettes are used to tell which light type is being used by the model:
{| class="wikitable"
|+Palette masks ingame
![[File:Mask_test.png]]
![[File:Mask_edit.png|none|thumb]]
|}

=== List of PL files ===
The game loads PL/SL files using a naming scheme that roughly matches the game’s internal level list. The first number/letter after “PL_” is the level ID, the number after that is usually act number, but there are some exceptions. Here is a list of PL files and stages that load them:

==== Action Stages ====
{| class="wikitable"
!Filename
!Description
|-
|PL_10B.BIN
|Emerald Coast (all acts), Egg Carrier Outside when the Egg Carrier has sunk
|-
|PL_20B.BIN
|Windy Valley Act 1
|-
|PL_21B.BIN
|Windy Valley Act 2
|-
|PL_22B.BIN
|Windy Valley Act 3
|-
|PL_30B.BIN
|Twinkle Park Act 1
|-
|PL_31B.BIN
|Twinkle Park Act 2
|-
|PL_32B.BIN
|Twinkle Park Act 3
|-
|PL_40B.BIN
|Speed Highway Act 1
|-
|PL_41B.BIN
|Speed Highway Act 2
|-
|PL_42B.BIN
|Speed Highway Act 3
|-
|PL_50B.BIN
|Red Mountain Act 1
|-
|PL_51B.BIN
|Red Mountain Act 2
|-
|PL_52B.BIN
|Red Mountain Act 3 (Knuckles)
|-
|PL_60B.BIN
|Character select screen, Sky Deck normal (Acts 1 and 2), Sky Deck Act 3
|-
|PL_61B.BIN
|Sky Deck dark (Acts 1 and 2)
|-
|PL_70B.BIN
|Lost World Act 1
|-
|PL_71B.BIN
|Lost World Acts 2 and 3
|-
|PL_80B.BIN
|Ice Cap Act 1
|-
|PL_81B.BIN
|Ice Cap Act 2
|-
|PL_82B.BIN
|Ice Cap Act 3
|-
|PL_83B.BIN
|Ice Cap Act 4 (Big)
|-
|PL_90B.BIN
|Casinopolis Act 1
|-
|PL_91B.BIN
|Casinopolis Act 2 (Sewers)
|-
|PL_92B.BIN
|Casinopolis Act 3 (Sonic pinball)
|-
|PL_93B.BIN
|Casinopolis Act 4 (NiGHTS pinball)
|-
|PL_A0B.BIN
|Final Egg Act 1
|-
|PL_A1B.BIN
|Final Egg Act 2
|-
|PL_A2B.BIN
|Final Egg Act 3 (Sonic/Gamma)
|-
|PL_C0B.BIN
|Hot Shelter Act 1
|-
|PL_C1B.BIN
|Hot Shelter Act 2
|-
|PL_C2B.BIN
|Hot Shelter Act 3 (Gamma)
|}

==== Bosses ====
{| class="wikitable"
!Filename
!Description
|-
|PL_F0B.BIN
|Chaos 0
|-
|PL_G0B.BIN
|Chaos 2
|-
|PL_H0B.BIN
|Chaos 4
|-
|PL_I0B.BIN
|Chaos 6
|-
|PL_J0B.BIN
|Perfect Chaos (first 3 hits)
|-
|PL_J1B.BIN
|Perfect Chaos 2nd phase
|-
|PL_K0B.BIN
|Egg Hornet
|-
|PL_M0B.BIN
|Egg Viper
|-
|PL_N0B.BIN
|Zero
|-
|PL_O0B.BIN
|E-101 Beta
|-
|PL_P0B.BIN
|E-101R
|}

==== Adventure Fields ====
{| class="wikitable"
!Filename
!Description
|-
|PL_Q1B.BIN
|Station Square Evening (All acts)
|-
|PL_Q3B.BIN
|Egg Walker, Station Square Night (All acts)
|-
|PL_Q4B.BIN
|Station Square Day (All acts)
|-
|PL_T0B.BIN
|Egg Carrier Outside (before the Egg Carrier sinks)
|-
|PL_T2B.BIN
|Egg Carrier Private Room
|-
|PL_T3B.BIN
|Egg Carrier Captain’s Room
|-
|PL_T5B.BIN
|Egg Carrier Pool
|-
|PL_W0B.BIN
|Egg Carrier Ammunition Room
|-
|PL_W1B.BIN
|Egg Carrier Bridge
|-
|PL_W2B.BIN
|Egg Carrier Hedgehog Hammer Room
|-
|PL_W3B.BIN
|Egg Carrier Prison
|-
|PL_W4B.BIN
|Egg Carrier Reservoir Room
|-
|PL_W5B.BIN
|Egg Carrier Chao Garden transporter
|-
|PL_X0B.BIN
|Mystic Ruins Day (Station, Angel Island and Jungle)
|-
|PL_X1B.BIN
|Mystic Ruins Evening (Station, Angel Island and Jungle)
|-
|PL_X2B.BIN
|Mystic Ruins Night (Station, Angel Island and Jungle)
|-
|PL_X3B.BIN
|Mystic Ruins Eggman’s Base
|-
|PL_Y0B.BIN
|Past Act 1 (Echidna City)
|-
|PL_Y1B.BIN
|Past Act 2 (Emerald Altar)
|-
|PL_Y2B.BIN
|Past Act 3 (Emerald Altar on fire)
|}

==== Subgames ====
{| class="wikitable"
!Filename
!Description
|-
|PL_Z0B.BIN
|Twinkle Circuit
|-
|PL1A0B.BIN
|Sky Chase Act 1
|-
|PL1B0B.BIN
|Sky Chase Act 2
|-
|PL1C0B.BIN
|Sand Hill
|}

==== Chao ====
{| class="wikitable"
!Filename
!Description
|-
|PL1D0B.BIN
|Station Square Chao Garden
|-
|PL1E0B.BIN
|Egg Carrier Chao Garden
|-
|PL1F0B.BIN
|Mystic Ruins Chao Garden Day
|-
|PL1F1B.BIN
|Mystic Ruins Chao Garden Evening (unused in the original game, used in SADX Lantern Engine)
|-
|PL1F2B.BIN
|Mystic Ruins Chao Garden Night (unused in the original game, used in SADX Lantern Engine)
|-
|PL1G0B.BIN
|Chao Stadium
|-
|PL1G1B.BIN
|Chao Race
|}

==== Unused ====
The following files are present on the disk, but not used by the game:
{| class="wikitable"
!Filename
!Description
|-
|PL_9MB.BIN
|An alternative version of the Casinopolis sewers palette that is never applied.
It was originally supposed to be used by an object called MUD. The object would gradually change character palettes to make them darker.
|-
|PL_MRD.BIN
|Possibly alternative Mystic Ruins Day palette
|-
|PL_MRE.BIN
|Possibly alternative Mystic Ruins Evening palette
|-
|PL_MRN.BIN
|Possibly alternative Mystic Ruins Night palette
|-
|PL_T1B.BIN
|Egg Carrier related, might have been used in the early transformation cutscene
|-
|PL_T4B.BIN
|Egg Carrier related, possibly the lighting used for some endgame credits images
|-
|PL1D1B.BIN
|Possibly Station Square Chao Garden Night
|-
|PL1E1B.BIN
|Egg Carrier Chao Garden Evening
|-
|PL1E2B.BIN
|Egg Carrier Chao Garden Night
|}

== SL Files ==
SL files use the same naming scheme as the PL files. They store the following data:

* Light rotation: Y and Z rotation values that are applied to the default light direction, which is a downward facing vector (0, -1, 0).
* Lighting configuration for models that use [[Ninja Lights|Ninja]] [[Ninja Lights|Lights]] instead of palette lighting.