Emulates the "flashlight" effect using a GUI or screen overlay.
- 1 Macros (#define-s)
- 2 Functions and Properties
- 2.1 Flashlight.BeamSprite
- 2.2 Flashlight.Enabled
- 2.3 Flashlight.FollowingCharacter
- 2.4 Flashlight.IsFollowingCharacter
- 2.5 Flashlight.IsFollowingMouse
- 2.6 Flashlight.IsFollowingPlayer
- 2.7 Flashlight.IsGUIMode
- 2.8 Flashlight.IsOverlayMode
- 2.9 Flashlight.IsStatic
- 2.10 Flashlight.Radius
- 2.11 Flashlight.ScaleBeam
- 2.12 Flashlight.SetBeamSprite
- 2.13 Flashlight.SetFollowCharacter
- 2.14 Flashlight.SetFollowMouse
- 2.15 Flashlight.SetGUIMode
- 2.16 Flashlight.SetOverlayMode
- 2.17 Flashlight.SetStatic
- 2.18 Flashlight.ScreenSprite
- 2.19 Flashlight.Transparency
- 2.20 Flashlight.X
- 2.21 Flashlight.Y
- 3 Setup
- 4 Licensing
- 5 Changelog
Defines the current version of the module.
Defines version 2.0 of the module.
Defines version 1.9 of the module.
Defines version 1.6 of the module.
Defines version 1.5 of the module.
Defines version 1.0 of the module.
Functions and Properties
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.
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.
See Also: Flashlight.SetBeamSprite
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.
See Also: Flashlight.SetFollowCharacter
writeprotected bool Flashlight.IsFollowingCharacter
Returns whether the flashlight beam is following any character (this is the same as checking whether the FollowingCharacter property is not NULL). You can lock the flashlight's beam to a Character's position using the Flashlight.SetFollowCharacter method.
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.
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.
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.
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.
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.
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).
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.
See Also: Flashlight.FollowingCharacter
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.
See Also: Flashlight.BeamSprite
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.
Locks the flashlight's beam to the mouse's position.
Sets the flashlight to use the passed GUI (if valid, otherwise defaults to Overlay mode).
Sets the flashlight to use an Overlay.
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.
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.
See Also: Flashlight.BeamSprite
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.
See Also: Flashlight.IsGUIMode
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.
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.
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.
In order for the Flashlight module to work, you must:
a) include a "flashlight.bmp" file in your game's Compiled folder and/or
// 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.
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.
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).
Date: 14 February 2007, 10:05 P.M. GMT -6:00 Author: monkey_05_06 Description: Fixed bug with flashlight following scaled characters.
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".
Date: 12 February 2007, 1:56 A.M. GMT -6:00 Author: monkey_05_06 Description: First public version of module.