======
Syntax
======

// tint screen
void SetFlashlightTint (int RedTint, int GreenTint, int BlueTint);
int GetFlashlightTintRed ();
int GetFlashlightTintGreen ();
int GetFlashlightTintBlue ();

// darkest LightLevel
int GetFlashlightMinLightLevel ();
// brightest LightLevel
int GetFlashlightMaxLightLevel ();

// set surrounding darkness
void SetFlashlightDarkness (int LightLevel);
int GetFlashlightDarkness ();
void SetFlashlightDarknessSize (int Size);
int GetFlashlightDarknessSize ();

// set light spot
void SetFlashlightBrightness (int LightLevel);
int GetFlashlightBrightness ();
void SetFlashlightBrightnessSize (int Size);
int GetFlashlightBrightnessSize ();

// set light spot position
void SetFlashlightPosition (int X, int Y);
int GetFlashlightPositionX ();
int GetFlashlightPositionY ();

// set light spot movement
void SetFlashlightFollowMouse (int OnOff);
int GetFlashlightFollowMouse ();

void SetFlashlightFollowCharacter (int CharacterId, int dx, int dy, int horz, int vert);
int GetFlashlightFollowCharacter ();
int GetFlashlightCharacterDX ();
int GetFlashlightCharacterDY ();
int GetFlashlightCharacterHorz ();
int GetFlashlightCharacterVert ();

// experimental
void SetFlashlightMask (int SpriteSlot);
int GetFlashlightMask ();

============
Basic / Tint
============

Note:
This plugin only supports Hi-Color (15/16 bit), though it won't have a negative effect on other color mode games.

For better understanding think of the flashlight as 2 circles which have the same center. Inside the inner circle there is Brightness, outside the outer circle there is Darkness. Between the 2 circles lighting is linear shaded.

The lowest LightLevel (GetFlashlightMinLightLevel) will color the area black; the highest (GetFlashlightMaxLightLevel) will leave your image unchanged.

You can set the LightLevels for Brightness and Darkness: SetFlashlightDarkness and SetFlashlightBrightness

Note:
The LightLevel of Darkness will always be lower or equal to that of Brightness. If you set Darkness to a higher value than Brightness, then Brightness will set to the same value. On the other hand if you set Brightness to a lower value than Darkness, then Darkness will be set to this value.

-------------------------------------
Example how to switch off the effect:
-------------------------------------

SetFlashlightDarkness (GetFlashlightMaxLightLevel ());


With SetFlashlightTint you can tint your scenery with a color. Values for tints an be from -31 to +31; 0 means no change to the color component.

Note:
At first a pixel is tinted then it is shaded.

----------------------------------
Example how to switch tinting off:
----------------------------------

SetFlashlightTint (0, 0, 0);

--------------------------
Example how to add yellow:
--------------------------

SetFlashlightTint (10, 10, 0);

=================
Dim / Fade-in-out
=================

Please read first "Basic" for better understanding.

If you use equal LightLevels for Darkness and Brightness, then you can create effects like dim the whole scenery, fade-in and -out or tv flicker.

--------------------
Example for fade-in:
--------------------

function room_a() {
  // script for room: Player enters screen (before fadein)
  SetFlashlightBrightness (GetFlashlightMinLightLevel());
}

function room_b() {
  // script for room: Player enters screen (after fadein)
  int ll, lm;
  ll = GetFlashlightMinLightLevel();
  lm = GetFlashlightMaxLightLevel();
  while (ll < lm)
  {
    SetFlashlightDarkness (ll);
    Wait (1);
    ll += 5;
  }
}

---------------------
Example for fade-out:
---------------------

function room_c() {
  // script for room: Player leaves screen
  int ll, lm;
  ll = GetFlashlightMinLightLevel();
  lm = GetFlashlightMaxLightLevel();
  while (lm > ll)
  {
    SetFlashlightBrightness (lm);
    Wait (1);
    lm -= 5;
  }
}

---------------------------------------
flicker like a switched on tv produces:
---------------------------------------

// room script file

int minll, deltall;
int w = 0;

function room_a() {
  // script for room: Player enters screen (before fadein)
  minll = GetFlashlightMinLightLevel() + 10;
  deltall = (GetFlashlightMaxLightLevel() - minll) / 3;
}

function room_b() {
  // script for room: Repeatedly execute
  int ll;
  if (w <= 0)
  {
    w = Random (10);
    ll = minll + Random (deltall);
    if (ll < GetFlashlightBrightness ()) SetFlashlightBrightness (ll);
    else SetFlashlightDarkness (ll);
  }
  else w--;
}

==========
Light spot
==========

In the previous examples the whole scenery was dimmed with the same LightLevel. If you use different values for Brightness and Darkness, then you will get the flashlight effect.
Use SetFlashlightDarknessSize to set the radius of the outer circle and SetFlashlightBrightnessSize to set the radius of the inner circle.

Note:
DarknessSize will always be greater or equal to BrightnessSize. If you set DarknessSize lower than BrightnessSize then BrightnessSize will be set to the same value, and vice versa.

If DarknessSize is equal to BrightnessSize then you scenery is shaded with 2 LightLevels: Inside the circle it will be Brightness, outside Darkness.
If DarknessSize is greater than BrightnessSize then you will get a ring between Brightness and Darkness which is linear shaded.

----------------------------------------------------------
Example for enter a dark room with flashlight switched on:
----------------------------------------------------------

function room_b() {
  // script for room: Player enters screen (before fadein)

  // set darkness so dark than you can still see a little bit of the background (+3)
  SetFlashlightDarkness (GetFlashlightMinLightLevel() + 3);
  // set brightness to the brightest value
  SetFlashlightBrightness (GetFlashlightMaxLightLevel());
  // define the outer circle (outside it will be dark)
  SetFlashlightDarknessSize (50);
  // define the inner circle (inside it will be bright)
  SetFlashlightBrightnessSize (20);
  // set this to have the light spot follow mouse movement
  SetFlashlightFollowMouse (1);
}

---------------------------------------------------
Example for switch light off (flashlight also off):
---------------------------------------------------

function hotspot1_a() {
  // script for hotspot1: Interact hotspot
  SetFlashlightBrightness (GetFlashlightMinLightLevel());
}

---------------------------------
Example for switch flashlight on:
---------------------------------

function hotspot1_a() {
  // script for hotspot1: Interact hotspot
  SetFlashlightDarknessSize (50);
  SetFlashlightBrightnessSize (20);
  SetFlashlightBrightness (GetFlashlightMaxLightLevel ());
  SetFlashlightFollowMouse (1);
}

----------------------------------
Example for switch flashlight off:
----------------------------------

function hotspot1_a() {
  // script for hotspot1: Interact hotspot
  SetFlashlightBrightness (GetFlashlightDarkness ());
}

--------------------------------------------------
Example for switch light on (flashlight also off):
--------------------------------------------------

function hotspot1_a() {
  // script for hotspot1: Interact hotspot
  SetFlashlightDarkness (GetFlashlightMaxLightLevel ());
}

===================
Position / Movement
===================

Use SetFlashlightPosition to fix the light spot on a position in your room.

Flashlight effect:
You can have the user move around the light spot with the mouse as if he had a flashlight in his hand (SetFlashlightFollowMouse).

Candle light effect:
Use SetFlashlightFollowCharacter to have the light spot follow a character as if the character was carrying a candle light. With dx and dy you can position the light spot relative to the character.
If you want the light spot adjust to the direction (view-loop 0 to 7) then use Horz and Vert.

Note:
Flashlight coordinates are room coordinates.

-------------------
Example for a lamp:
-------------------

function room_a() {
  // script for room: Player enters screen (before fadein)
  SetFlashlightPosition (120, 100);
  SetFlashlightDarknessSize (200);
  SetFlashlightBrightnessSize (10);
  SetFlashlightDarknessSize (GetFlashlightMaxLightLevel () + 3);
  SetFlashlightBrightness (GetFlashlightMaxLightLevel ());
}

-------------------------------------
Example for light spot follows mouse:
-------------------------------------

function room_a() {
  // script for room: Player enters screen (before fadein)
  SetFlashlightFollowMouse (1);
  SetFlashlightDarknessSize (200);
  SetFlashlightBrightnessSize (10);
  SetFlashlightDarknessSize (GetFlashlightMaxLightLevel () + 3);
  SetFlashlightBrightness (GetFlashlightMaxLightLevel ());
}

---------------------------------------------------
candle light effect (light spot follows character):
---------------------------------------------------

function room_a() {
  // script for room: Player enters screen (before fadein)
  SetFlashlightDarkness (20);
  SetFlashlightBrightness (GetFlashlightMaxLightLevel ());
  SetFlashlightDarknessSize (50);
  SetFlashlightBrightnessSize (10);
  SetFlashlightFollowCharacter (GetPlayerCharacter (), 0, -20, 20, 10);
}

=====
Masks
=====

If your scenery includes e.g. walkbehind-areas and a character "carries" the light spot, then light on this area would depend on wether the character is in front of or behind the area.

How to do:
- paint a room mask with your favorite paint programm in Hi-color (white = light; black = no light)
- import it into the sprite manager from the file with transparent color set to palette index 0.
- Use SetFlashlightMask with the sprite slot number to which you imported the mask
- Use SetFlashlightMask (-1) to show the normal effect without mask

Note:
The mask must have the same size as the room.

Caution:
If you notice that white or black are changed into transparent (red) then the import wasn't successful. Please try again with correct settings (see above).

Usage:
You can use hotspots (e.g. player stands on hotspot) to run a script in which you switch on/off the mask; or you can check coordinates of the character or of the light spot.

-----------------------
Any questions?
eMail me: a-v-o@web.de
-----------------------

