PL Tool - X-Hax/sa_tools GitHub Wiki
PL Tool is an editor for Sonic Adventure lighting files (PL and SL files).
Table of Contents
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.
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 Ninja lights.
The 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:
1 - ((dot(normal, light direction) + 1) / 2), where dot is dot product and normal 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:
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.
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:
| 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 (
NJD_FLAG_IGNORE_LIGHT), 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 (
NJD_FLAG_IGNORE_SPECULAR), 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
PL_60Bare used normally, and palettes fromPL_61Bare 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
PL_M0B.BINwith 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:
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
| 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
| 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
| 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
| Filename | Description |
|---|---|
| PL_Z0B.BIN | Twinkle Circuit |
| PL1A0B.BIN | Sky Chase Act 1 |
| PL1B0B.BIN | Sky Chase Act 2 |
| PL1C0B.BIN | Sand Hill |
Chao
| 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:
| Filename | Description |
|---|---|
| PL_9MB.BIN | An alternative version of the Casinopolis sewers palette that is never applied, but 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, posibly 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 instead of palette lighting.
Ninja Lights
Note: Ninja Lights are not implemented in the Lantern Engine mod, so the information below is irrelevant to the PC version.
The SL file contains data for setting up Ninja lights. This information consists of: light color (three floats for R/G/B), diffuse multiplier, specular power and ambient multiplier. Both diffuse and specular components are the same color. The "ignore specular" material flag disables the specular component per mesh.
There are three types of lights used for non-palettized models in the game:
| Lighting Setup | Description | Used by |
|---|---|---|
| Two Ninja Lights | Non-palettized lighting that uses two Ninja Lights. These lights use NJS_LIGHT structures described in the Katana SDK. One is set up using the parameters in the SL file (let's call it the ENV Light), and the other is set up in code, usually in level binaries (let's call it the DIR light). The ENV light has one configurable color that is shared for diffuse and specular, the DIR light can have different diffuse and specular color (though the game doesn't seem to use that). It can also have a different light direction. |
Common switch, Hint monitor, OEggKanban (glowing Eggman logo in Final Egg, tube parts only), Chaos puddle in some cutscenes, Aoki Switch (top) |
| Simple Ninja Light | Non-palettized lighting that uses one Ninja Light using the parameters from the SL file except the color, which is always white. | Rock bits in Red Mountain, non-Jewel Chao, Master Emerald pieces, Froggy in Gamma's Emerald Coast |
| Easy Light | Non-palettized lighting that sets up the Easy Light (not NJS_LIGHT) using the parameters from the SL file. The Easy light is described in the Katana SDK. It doesn't support specular lighting. |
Snowboard, OSandSwitch (Sand Hill switch), shadow blob, Chambr (chambers with opening doors in Sky Deck), debug objects, Aoki Switch (bottom), E101's missiles, Hedgehog Hammer targets |
Using the Editor
Palette List
PLTool's main window lists diffuse and specular palettes in the PL file. Click the palette to select it. Right click a palette for a list of options to edit it. You can create palettes with sliders like gradients in Photoshop, generate them like in the Preview prototype of SADX, fill them with a specific color (or a combination of colors), import and export palettes as PNG files, as well as copy and paste them. The B palette pair is not stored in the PL file and can be used for backing up palettes before editing them.
- Note: Color Alpha is ignored in the game.
Create Gradient
This window lets you create gradients from four colors and an ambient color. Click each color box to set the color and drag the sliders to adjust the position of the two colors in the middle.
Generate Gradient (SADX Preview)
The SADX Preview prototype has a debug menu that creates gradients. This feature is recreated in PL Tool. The gradients are generated using the following formula:
Result = Ambient + CO1 * Pow((1 - Index / 256), CO1Pow / 100.0) + CO2 * Pow((Index / 256), CO2Pow / 100)
- Ambient is the Ambient color R/G/B.
- CO1 is Color 1 R/G/B.
- CO2 is Color 2 R/G/B.
- CO1Pow and CO2Pow are Color 1 and Color 2 power values respectively.
- Index is the color index in the gradient (0 to 255).
Color Selector
The trackbar is used to select a specific color in the palette. Its index and R/G/B values are shown on the right side of the status bar. Click the small colored box in the status bar to edit the color.
- Note: Color Alpha is ignored in the game.
Menu bar
- The File menu lets you import or export the entire palette list as a single PNG file.
- The Options menu lets you set a background color for the editor to make it easier to work with light or dark palettes.
- The Level Select menu allows you to locate the PL file by selecting a stage. If you have opened a PL file previously, the tool will look for PL files in the same folder without an open file dialog.
- The Format menu allows you to toggle the Endianness of PL and SL files. Leave it on Dreamcast for the Lantern Engine mod.
- The Tools menu opens the editor for SL files (see below).
SL Editor
The SL Editor lets you edit light direction and Ninja Lights configuration.
- The Environment Data box has the parameters for the Ninja lights. You can click the color box to select the color.
- The Light Direction box has light rotation Y and Z values. These are used to rotate the default light direction vector. This light direction is used by palette lights and Ninja lights except the DIR light which has a hardcoded light direction.
- The Free/Slave Data box has additional lighting data. This data doesn't seem to be used by the game. It may be left over from the Saturn because a menu with similar data was found in a Burning Rangers prototype.