Flashlight
module 30137.0 by monkey_05_06.
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.
NOTE: This property does not support sprites with an alpha channel as the sprite is flattened while creating the sprite for the GUI/Overlay.
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.