Flashlight

module 30137.0 by monkey_05_06.

Download v2.0 BETA 3

Download v1.9

Description

Emulates the "flashlight" effect using a GUI or screen overlay.

Macros (#define-s)

FLASHLIGHT_VERSION

Defines the current version of the module.

FLASHLIGHT_VERSION_200

Defines version 2.0 of the module.

FLASHLIGHT_VERSION_190

Defines version 1.9 of the module.

FLASHLIGHT_VERSION_160

Defines version 1.6 of the module.

FLASHLIGHT_VERSION_150

Defines version 1.5 of the module.

FLASHLIGHT_VERSION_100

Defines version 1.0 of the module.

Functions and Properties

Flashlight.BeamSprite

writeprotected DynamicSprite* Flashlight.BeamSprite

Defines the DynamicSprite used as the 'beam' of the flashlight. This is essentially a black square with a transparent hole in the middle. You can use this property to delete the DynamicSprite before you quit the game and you can set the sprite using the Flashlight.SetBeamSprite method.

Flashlight.Enabled

bool Flashlight.Enabled

Sets whether or not the flashlight effect will be enabled. If no BeamSprite is set then this property will be set to false until the BeamSprite is properly set.

Flashlight.FollowingCharacter

writeprotected Character* Flashlight.FollowingCharacter

Returns the Character the flashlight beam is currently following (if any). If following the mouse or statically positioned this will return NULL. You can set the Character to follow using the Flashlight.SetFollowCharacter method.

Flashlight.IsFollowingCharacter

writeprotected bool Flashlight.IsFollowingCharacter

Returns whether the flashlight beam is following any character (this is the same as checking whether the FollowingCharacter property is NULL). You can lock the flashlight's beam to a Character's position using the Flashlight.SetFollowCharacter method.

Flashlight.IsFollowingMouse

writeprotected bool Flashlight.IsFollowingMouse

Returns whether the flashlight beam is following the mouse. You can lock the flashlight's beam to the mouse position using the Flashlight.SetFollowMouse method.

Flashlight.IsFollowingPlayer

writeprotected bool Flashlight.IsFollowingPlayer

Returns whether the flashlight's beam is following the player Character. This will not actually test if the FollowingCharacter property is set to the current player Character; rather it simply determines whether the FollowingCharacter property will be updated if the player changes. You can lock the flashlight's beam to follow the player Character using the Flashlight.SetFollowCharacter method.

Flashlight.IsGUIMode

writeprotected bool Flashlight.IsGUIMode

Returns whether the flashlight is using a GUI. The benefit of using a GUI is the ability to set transparency using the Flashlight.Transparency property. You can set the flashlight to GUI mode using the Flashlight.SetGUIMode method.

Flashlight.IsOverlayMode

writeprotected bool Flashlight.IsOverlayMode

Returns whether the flashlight is using an Overlay. The draw-back to using an Overlay instead of a GUI is that you cannot set transparency. You can set the flashlight to Overlay mode using the Flashlight.SetOverlayMode method.

Flashlight.IsStatic

writeprotected bool Flashlight.IsStatic

Returns whether the flashlight's beam is statically positioned. This means that in order to move the flashlight you must manually modify the Flashlight.X and Flashlight.Y properties. You can lock the flashlight's beam to a static position using the Flashlight.SetStatic method.

Flashlight.Radius

float Flashlight.Radius

Gets/sets the RADIUS (1/2 the diameter) of the flashlight beam. Cannot be set to less than 0.5 (it will be reset to 0.5 if set to less than this value).

Flashlight.ScaleBeam

bool Flashlight.ScaleBeam

Controls whether the flashlight beam is scaled based on the scaling of the FollowingCharacter property. If not following a Character this does nothing. Note that the Flashlight.Radius property is NOT updated based upon any scaling, only the actual size of the beam will reflect this.

Flashlight.SetBeamSprite

void Flashlight.SetBeamSprite(DynamicSprite* beamSprite)

Sets the sprite to use for the flashlight beam. NULL values will be rejected. It is possible to set an existing sprite as the beam sprite by passing DynamicSprite.CreateFromExistingSprite as the parameter. See Flashlight.BeamSprite for more information.

Flashlight.SetFollowCharacter

void Flashlight.SetFollowCharacter(Character*, optional bool followPlayer)

Locks the flashlight's beam to the Character's position. If (and only if) the Character passed is the current player AND followPlayer is TRUE (the default) the FollowingCharacter property will be locked to the PLAYER Character, updating if the player is changed; otherwise the beam will be locked exclusively to the position of the passed Character. Note that the Character MUST be in the current room or the beam will be locked to the mouse position instead.

Flashlight.SetFollowMouse

void Flashlight.SetFollowMouse()

Locks the flashlight's beam to the mouse's position.

Flashlight.SetGUIMode

void Flashlight.SetGUIMode(GUI*)

Sets the flashlight to use the passed GUI (if valid, otherwise defaults to Overlay mode).

Flashlight.SetOverlayMode

void Flashlight.SetOverlayMode()

Sets the flashlight to use an Overlay.

Flashlight.SetStatic

void Flashlight.SetStatic()

Locks the flashlight's beam to its current (X,Y) position. You can move it manually by modifying the X/Y properties, or lock it back to the mouse (Flashlight.SetFollowMouse) or a Character (Flashlight.SetFollowCharacter) using the appropriate functions.

Flashlight.ScreenSprite

writeprotected DynamicSprite* Flashlight.ScreenSprite

The DynamicSprite used to cover the screen. You can use this property to delete the DynamicSprite before you quit the game.

Flashlight.Transparency

int Flashlight.Transparency

Sets the transparency for the (dark areas of the) flashlight effect. This is only valid if the flashlight is in GUI mode. This property is also passed through a bounding function similar to the way AGS's CHAR type works such that -1 will loop back around to 100, -2 to 99, -3 to 98, and 101 to 0, 102 to 1, 103 to 2, etc.

Flashlight.X

int Flashlight.X

Gets the X co-ordinate of the center of the flashlight beam. If the beam is statically positioned (Flashlight.SetStatic) you can also use this to set the X co-ordinate.

Flashlight.Y

int Flashlight.Y

Gets the Y co-ordinate of the center of the flashlight beam. If the beam is statically positioned (Flashlight.SetStatic) you can also use this to set the Y co-ordinate.

Setup

Modes

GUI mode

GUI mode allows you to use transparency in the darkened areas of the screen when applying the flashlight effect.

To activate GUI mode you can put the following in the Flashlight module header:

 #define FLASHLIGHT_GUI gFlashlight

Where gFlashlight is the script o-name of your GUI. The GUI no longer requires any controls (Flashlight module v2.0 BETA 3). Alternately you can set GUI mode at any time throughout the game by calling Flashlight.SetGUIMode.

Overlay mode

Overlay mode is the default mode for the module. You cannot use transparency in Overlay mode. If you want to use transparency, use GUI mode instead.

Other Setup

In order for the Flashlight module to work, you must:

a) include a "flashlight.bmp" file in your game's Compiled folder and/or

b) call Flashlight.SetBeamSprite on a valid DynamicSprite before turning the Flashlight effect on.

Failure to do this will prevent the module from working properly and prevent the Flashlight.Enabled property from being set (it will reset to false every loop until the BeamSprite is properly set.

Licensing

 // Permission is hereby granted, free of charge, to any person obtaining a copy
 // of this software and associated documentation  files  (the  "Software"),  to
 // deal in the Software without restriction, including without  limitation  the
 // rights to use, copy, modify, merge, publish, distribute, sublicense,  and/or
 // sell copies of the Software, and to permit persons to whom the  Software  is
 // furnished to do so, subject to the following conditions:
 //
 // The above copyright notice and this permission notice shall be  included  in
 // all copies or substantial portions of the Software.
 //
 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,  EXPRESS  OR
 // IMPLIED, INCLUDING BUT NOT LIMITED TO  THE  WARRANTIES  OF  MERCHANTABILITY,
 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL  THE
 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE  FOR  ANY  CLAIM,  DAMAGES  OR  OTHER
 // LIABILITY, WHETHER IN AN ACTION OF  CONTRACT,  TORT  OR  OTHERWISE,  ARISING
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 // IN THE SOFTWARE.

Changelog

Version 2.0 BETA 3

Date:        21 November 2007, 2:57 P.M. GMT -6:00
Author:      monkey_05_06
Description: Uses RawDraw methods to only require two sprites instead of six,
             and only one Overlay instead of five. Also GUI no longer
             requires ANY controls as opposed to previous requisite of five.
             Designed to be forward-compatible with AGS 3.0 while remaining
             compatible with AGS 2.72.
             Renamed:
             Flashlight.CharacterToFollow to Flashlight.FollowingCharacter,
             Flashlight.FollowCharacter to Flashlight.SetFollowCharacter,
             Flashlight.FollowMouse to Flashlight.SetFollowMouse,
             Flashlight.SetSprite to Flashlight.SetBeamSprite, and
             Flashlight.Sprite to Flashlight.BeamSprite.
             Added:
             Flashlight.IsFollowingPlayer, Flashlight.IsGUIMode,
             Flashlight.IsOverlayMode, Flashlight.IsStatic,
             Flashlight.ScaleBeam, Flashlight.SetGUIMode,
             Flashlight.SetOverlayMode, Flashlight.SetStatic, and
             Flashlight.ScreenSprite.

Version 2.0 BETA 2

 Date:        16 February 2007, 2:32 P.M. GMT -6:00
 Author:      monkey_05_06
 Description: Fixed bug if "Enforce object-based  scripting"  was  turned  off.

Version 2.0 BETA 1

 Date:        16 February 2007, 11:53 A.M. GMT -6:00
 Author:      monkey_05_06
 Description: Made Flashlight.CharacterToFollow writeprotected and added method
              Flashlight.FollowCharacter to fix bug when changing  rooms  while
              the   flashlight   was   following    the    player    character.

Version 1.9

 Date:        16 February 2007, 2:28 A.M. GMT -6:00
 Author:      monkey_05_06
 Description: Implemented methods for using a GUI  instead  of  Overlays  which
              should be faster, as well as allowing transparency (set  via  the
              Flashlight.Transparency property).

Version 1.6

 Date:        14 February 2007, 10:05 P.M. GMT -6:00
 Author:      monkey_05_06
 Description: Fixed  bug   with   flashlight   following   scaled   characters.

Version 1.5

 Date:        12 February 2007, 1:52 P.M. GMT -6:00
 Author:      monkey_05_06
 Description: Fixed bug  with  flashlight  following  Characters  in  scrolling
              rooms, corrected usage of Flashlight.Radius as a  diameter,  made
              Flashlight.Radius  a   float   instead   of    an    int,    made
              Flashlight.Sprite writeprotected to  allow  read  access  so  the
              sprite can be deleted, and  implemented  Flashlight.SetSprite  to
              remove dependency on file "flashlight.bmp".

Version 1.0

 Date:        12 February 2007, 1:56 A.M. GMT -6:00
 Author:      monkey_05_06
 Description: First public version of module.