MODULE: Flashlight v2.0 [FINAL] - Updated 16 January 2009!

[placyd]

It's me again
I have a problem using the module.
My script is:
...
DynamicSprite* sprite = DynamicSprite.CreateFromExistingSprite(168, true);
Flashlight.SetGUIMode(gFlashlight, sprite);
Flashlight.Enabled = true;
Flashlight.Radius=0.0;
Flashlight.Transparency=2;
player.Say("I've turned the light off.");

But what is happening: the player talks then the flashlight turns off.
How can I make it in reverse order, like in the script?

[monkey0506]

Just so you know the Flashlight module does assume that you're always going to have some sort of "beam" area while the effect is turned on so setting Flashlight.Radius = 0.0 may not work as you might think.

It will actually in that case be defaulted to 0.5 which of course gives a 1 pixel diameter for the beam.

That's not the problem however. The real problem is with the fact that the module doesn't get a chance to update before you call the Say function. Try doing this:

Code: ags

// ...
import void Update(this FlashlightType*); // copy this line EXACTLY
DynamicSprite* sprite = DynamicSprite.CreateFromExistingSprite(168, true);
Flashlight.SetGUIMode(gFlashlight, sprite);
Flashlight.Enabled = true;
Flashlight.Radius=0.0;
Flashlight.Transparency=2;
Flashlight.Update(); // copy this line EXACTLY
player.Say("I've turned the light off.");

That will force the screen to update the flashlight effect prior to the player.Say command.

If it still doesn't work you can instead just add a Wait(1); right before calling player.Say. I'm not certain whether the GUI would actually get the chance to update on-screen even with directly calling the internal update function.

I'll do more testing on this myself to see. If it does get to update in time it might be prudent to import the updating function as part of the primary structure anyway.

[Nahuel]

Hello there! Look I just wondering if you have any tutorial to undertand how start with this excelent Module!

Thanks for your time!

Nahuel.

[Joseph DiPerla]

You should only post in one spot. Here is a manual for the module: http://americangirlscouts.org/agswiki/Flashlight

[monkey0506]

Thanks for linking that for me Joseph. However although the information included should still be valid, there's admittedly not really any example code to work with.

In order to use this module you should have a basic grasp on scripting in AGS. If not, check out the scripting tutorial in the AGS manual first.

Next you need to decide a few things about how you want to use the module. You can change your mind later, but you'll need someplace to start at. If you want a basic effect, don't care too much about "jaggy" edges in your sprites, and/or are running at 8-bit then using Overlay mode is the simplest route for you. If however you want smoothed edges around the "beam" area, or perhaps want the darkened areas to be partially transparent, or any sort of alpha channeled sprites whatsoever you will want to use GUI mode instead. The difference is the way that the module actually displays the effect, both of which have significant pros and cons.

Depending which mode you choose, you will need to call either Flashlight.SetGUIMode or Flashlight.SetOverlayMode. Both of these can optionally accept a parameter to specify a new "beam" sprite, but we'll come back to that in a moment. If you have chosen GUI mode you will need to have a GUI set up, dedicated to being used by this module. The actual size/location of the GUI doesn't matter, but it should not have any controls whatsoever. You will need to pass this GUI's script name as the first parameter when you call SetGUIMode.

As far as the "beam" sprite I referenced before, basically the module handles filling in the entire screen with the darkened area. You however, must supply a DynamicSprite* to a valid sprite for the area that will not be darkened. This area will be the "beam" of your flashlight.

There are two example sprites included which you can feel free to use, or you can create your own. The sprites are "flashlight.bmp" and "import_only.png". "flashlight.bmp" is designed with Overlay mode in mind (though it works fine with GUI mode as well) and gives a sort of simple, low-res sort of beam effect. "import_only.png" is designed for GUI mode only and has an alpha channel which gives it nice, smoothed edges around the beam.

If you want to use "flashlight.bmp" you can either A) just include it with the EXE file in your distribution (put it in your "Compiled" folder) or B) actually import the sprite. If the module detects the file in the same folder as the EXE when the game is run then it will automatically be loaded for the beam sprite. If you import it into AGS you will have to manually set the sprite (see next paragraph).

If you want to use "import_only.png" you must import it into AGS's sprite manager. Unless you intentionally want to destroy the alpha channel, you should also choose to preserve that on import. Once the sprite is imported then you will have to manually load the beam sprite for the module using the Flashlight.SetBeamSprite function, or just by passing a DynamicSprite* to the sprite when you set the mode.

The final important setup point is setting the Flashlight.Radius property. This will set the radius (half the diameter) (in pixels) you want the beam of your flashlight to be drawn at. This is a float property, however note that if it rounds to 0 or less then it will default to a radius of 0.5. So for example a radius of 5.0 would make the beam appear 10 pixels across.

Finally, you use Flashlight.Enabled to turn the effect on/off.

Okay, so that's the most important steps to getting the module's effects up and running. The last thing of course is "where do I put these?" so let me cover that as well. You can change any of these settings at any time, however you're going to need to set them all before you can utilize the effect. Therefore, putting them in the game_start function (in GlobalScript.asc) is a good place to initialize your settings:

Code: ags

// game_start - using GUI mode with import_only.png imported as sprite 42
DynamicSprite *sprite = DynamicSprite.CreateFromExistingSprite(42);
Flashlight.SetGUIMode(gFlashlight, sprite);
Flashlight.Radius = 5.0;

// on_key_press
if (keycode == eKeyTab) Flashlight.Enabled = !Flashlight.Enabled;
// the above is shorthand for "Flashlight.Enabled = (Flashlight.Enabled == false);"
// which of course would toggle the status of Flashlight.Enabled

Anything else should be covered by reading the documentation. I hope I've been thorough enough. If you have any other questions feel free to ask.

[placyd]

Code: ags

// ...
import void Update(this FlashlightType*); // copy this line EXACTLY
DynamicSprite* sprite = DynamicSprite.CreateFromExistingSprite(168, true);
Flashlight.SetGUIMode(gFlashlight, sprite);
Flashlight.Enabled = true;
Flashlight.Radius=0.0;
Flashlight.Transparency=2;
Flashlight.Update(); // copy this line EXACTLY
player.Say("I've turned the light off.");

Thanks, monkey! This update thing is working well! 

[Nahuel]

Monkey Thank you very much for the explaination. This is realy realy good. i appreciate your time.

If I have any question when I try I'll ask in this post.

Thankyou again.

Nahuel. From Argentina.

[monkey0506]

You're both very welcome.

Given that Flashlight.Update worked for you placyd I shall make a point (at some point) to import the function as part of the module. Normally you shouldn't need to call it, but as your case demonstrates for example, if you need the effect to be drawn after making some changes but prior to the next game loop being run (for example calling a blocking function, like Character.Say) then it's vital to getting it to update in time. If you need to use Flashlight.Update in other scripts, just move the import line into the Flashlight.ash file.

Nahuel definitely this is the place to ask if you have any further questions. I'll try to be prompt if able. I tried to be thorough enough to get you started though, so hopefully you'll be good to go from here!

[Nahuel]

You're both very welcome.

Given that Flashlight.Update worked for you placyd I shall make a point (at some point) to import the function as part of the module. Normally you shouldn't need to call it, but as your case demonstrates for example, if you need the effect to be drawn after making some changes but prior to the next game loop being run (for example calling a blocking function, like Character.Say) then it's vital to getting it to update in time. If you need to use Flashlight.Update in other scripts, just move the import line into the Flashlight.ash file.

Nahuel definitely this is the place to ask if you have any further questions. I'll try to be prompt if able. I tried to be thorough enough to get you started though, so hopefully you'll be good to go from here!

Monkey, I have a question. How can I start in a darkroom?

Thank you.

Nahuel.

[monkey0506]

If you want the first room to have the effect enabled you can set "Flashlight.Enabled = true;" in that room's "Player enters room (before fade-in)" event.

However the module does expect to have some area shown so if you wanted, for example, the entire room to be dark until the player turns the flashlight on (by using an inventory item for example) then you would need to darken the screen a different way. You could use FadeOut. If you call "FadeOut(64);" that would make sure the screen stays black and then when the player activates the flashlight you could call "FadeIn(64);" (after turning the flashlight on).

[Nahuel]

Excelent, tanks for help me!! 

Thank you very much Monkey.

Nahuel.

[Nahuel]

Monkey, I have a problem. My room doesn't stay dark with FadeOut(64), FadeOut(100),  FadeOut(1).
Another way to dark the background??

Thank you.

Nahuel.

[monkey0506]

The maximum value for FadeOut is 64 which should be instantaneous. I probably should have said to put the FadeOut call in "(after fade-in)" obviously otherwise the editor is going to try and fade it back in. I just wasn't thinking. Sorry about that.

I haven't actually tested FadeOut in the after fade-in function, but it should work fine with FadeOut(64). That should also answer your other question.

[Nahuel]

Thank you very much monkey!!

Nahuel.

[Dave Gilbert]

Hi all.  Bit of an old thread, but I've been tinkering around with this module and I am having some issues.  I am using AGS 3.2v5, so I *think* it is probably related to the alpha channel/GUI problem that was brought up in this thread, but I wanted to confirm it before I took it further.

In a nutshell, here's my room with the flashlight off:



And with it on:



Displaying it in overlay mode works perfectly.

[Adrian]

Have you tried setting the GUI's background colour to 0 in the panel?

[Dave Gilbert]

Adrian: Yes, it is definitely set to 0.

[Aarduil]

I am just getting started with AGS, but this script provides a very evocative feature that I want to have in my project from the start!

I, uh, implemented it somewhat. But I'm definitely getting something wrong, because it looks like this:
http://i.imgur.com/l9Noo.png

I would appreciate any tips!

[monkey0506]

Hi Aarduil,

Could you upload the image you're using as the beam sprite? I think I might know what your issue is there, but I'm not entirely sure just from that image.

Also, dunno why I never got around to answering Dave's question. If anyone else experiences the same problem, if I don't respond please feel free to PM me a reminder.

Edit: Just to be sure that this is still functional with the latest version(s) of AGS, I've tested it in a beta version of 3.2.2, and it seemed to be working fine for me. If you imported the file "import_only.png", make sure you don't select to use the "Top-left pixel" (or any of the other corners) as the transparent area of the image. Change that drop-box to "No transparency" or "Leave as-is". Also make sure your game is 32-bit and you select "Yes" to use the alpha channel if you want to use that image.

[Aarduil]

If you imported the file "import_only.png", make sure you don't select to use the "Top-left pixel" (or any of the other corners) as the transparent area of the image. Change that drop-box to "No transparency" or "Leave as-is".

Was exactly that. It works perfectly now, thanks!
http://i.imgur.com/g4FUZ.png