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

[monkey0506]

v2.0 [FINAL] Update

Now presenting: The version change nearly 2 years in the making...Flashlight v2.0!

This should be the most stable and functional version of the module ever! It does now require AGS 3.1.2*, but there's a good cause. Alpha channeled beam sprites with transparency are incredible!

Due to this change in AGS, I highly recommend using GUI mode. Overlay mode does not support alpha channels or transparency. And of course to use alpha channels you would also have to be in 32-bit. But the effect is completely worth it! For information on setting up the GUI, RTFM

Alpha sprites+transparency was the major difference between this module and the previous plugin. Now thanks to CJ's dedication, you don't have to compromise!

Download Flashlight v2.0 [FINAL]
Mirror
Read the Flashlight manual online (NOTE: Last updated with v2.0 BETA 3)

Hopefully I'll find time soon(-ish) to update the demo.

- monkey

*I have received confirmation that the module will work with AGS versions as early as 3.0.2 without problem (provided the #ifver is updated). The reason for this requirement was to allow the awesomeness to abound, but if you're using a prior version and don't want to upgrade, give it a shot...

NEW! Alpha channeled sprite with partial transparency!

[Gilbert]

Good work!
I'll move this to archive section.

[Lt. Smash]

Thanks!
That's exactly what I need.

But I have some questions:

Is there a way to make that black overlay a bit transparent?
Is it possible to draw some shades into that bmp, like they were in the other plugin?
Is it possible to use a normal sprite instad of that file?
And how did you name that dynamic sprite(flashlight) because I want to delete it, when quitting game? (sprite.delete())

EDIT:
I also found a bug:
When I'm using Flashlight.CharacterToFollow and I'm in a room (640x200) which is larger than the screen resolution, then the flashlight goes away from the character.(If I'm scrolling)

[Da_Elf]

i too use scrolling rooms alot. how this gets addressed. if it does work out then i will definately be downloading this.

EDIT

i cant download. both left click and right click "save as" give me an html file to save.

EDIT EDIT

never mind. was aproblem with my browser i guess

EDIT EDIT EDIT hehe

can you by anychance post a quick demo scene on how its used?

[monkey0506]

I take a DynamicSprite of the top-left pixel of the flashlight sprite to create the surrounding black Overlays. Also the flashlight sprite is loaded dynamically (at the moment). And there's currently no way to make a DynamicSprite partially transparent. Nor is there a way to make an Overlay partially transparent. So, in short, no.

You can replace the "flashlight.bmp" file with your own custom "flashlight.bmp" if you'd like. So if you want shades drawn into the image you can simply replace the file with your custom image. The default image was just something I made simply for testing and showing the module at work.

I will look into the bug with scrolling rooms, however I use the Character.x and Character.y variables directly so I see no reason why there should be a problem. According to the manual these are room co-ordinates, so I'm not sure what's gone amiss, though I will look into it.

I will also take a look at allowing the user some access to the sprite so you can use a copy of a static sprite instead of requiring the use of the external file. Additionally this will allow you to delete the sprite to suppress error messages with AGS versions prior to 2.72.

[EDIT:]

I think I've thought this through backwards. I think Overlays use screen co-ordinates which would explain the error with scrolling rooms (since the Character.x/y variables are room co-ordinates). I'll fix this.

@Da_Elf's EDIT Mark III: I think that would be a reasonable request. But for some reason my brain isn't working and I can't seem to figure out how to convert ROOM co-ordinates into SCREEN co-ordinates.

Wait...never mind. It's just the room co-ordinates minus the Viewport X/Y. D'oh! I'm going to try and find a scrollable background here just to test that it is working, and then I should be able to upload v1.5. And a demo as well.

[Lt. Smash]

I take a DynamicSprite of the top-left pixel of the flashlight sprite to create the surrounding black Overlays. Also the flashlight sprite is loaded dynamically (at the moment). And there's currently no way to make a DynamicSprite partially transparent. Nor is there a way to make an Overlay partially transparent. So, in short, no.

wouldn't it be possible with RawDrawImageTransparent if the picture is in the sprite manager?

[monkey0506]

RawDrawImageTransparent (as with all the RawDraw functions) draws onto the room background. So any characters and objects in the room would appear to be on top of the darkened areas. So that wouldn't really work out too well.

But I did get the bug with scrolling rooms worked out in the new version which I'll be uploading shortly. I also corrected my error with using the "Radius" parameter as a diameter (the property is still Flashlight.Radius, but it is now a float and the radius instead of the int diameter used by v1.0). I've made the DynamicSprite (Flashlight.Sprite) writeprotected, so you now have read access (this allows you the ability to use Flashlight.Sprite.Delete()), and I've included a Flashlight.SetSprite function so you can use existing sprites.

[Da_Elf]

here are the bugs i found.
For some reason i couldnt use the flashlight without the keypresses. i tried to type my code as such due to the fact that i dont want to give control to the light by keypresses. this is for my character when he is in a dark area with or without a flaming torch

Code: ags

#sectionstart room_fÃ,  // DO NOT EDIT OR REMOVE THIS LINE
function room_f() {
Ã,  // script for Room: Player enters room (before fadein)
Flashlight.Enabled = !Flashlight.Enabled; // toggle Flashlight on/off
Flashlight.CharacterToFollow = player; // Flashlight follows player
if (GetGraphicalVariable("torch") == 0) {
	Flashlight.Radius == 0;
	}
else {
Ã,  Ã,  Ã,  Ã, Flashlight.Radius == 70:
Ã,  Ã,  Ã,  Ã, }
}
#sectionend room_fÃ,  // DO NOT EDIT OR REMOVE THIS LINE

also i my character is in a room where he scales as well and the circle is centered way over his head when he is small.

the last part is that when he changed rooms the overlay would start strobing, then when i quit there was a message saying that some errors were generated while i was testing the game....

(in rom1):Dynamic Sprite 68 was never deleted

Code: ags

[Rui 'Trovatore' Pires]

Whee, problem when playing the demo.

---------------------------
Adventure Game Studio
---------------------------
A fatal error has been generated by the script using the AbortGame function. Please contact the game author for support.

in Flashlight (line 33)
from Flashlight (line 85)

Error: Error enabling Flashlight module: Flashlight.Sprite null. Game aborted.

---------------------------
OKÃ,  Ã, 
---------------------------

I just got on the game and pressed tab.

[Da_Elf]

that ones simple. just add the bmp file to the compile folder of the demo.

[monkey0506]

Ah...I forgot to put the BMP in the demo package. Sorry about that. My mistake and sincerest apologies.

Regarding your code Da_Elf:

Code: ags

#sectionstart room_f  // DO NOT EDIT OR REMOVE THIS LINE
function room_f() {
  // script for Room: Player enters room (before fadein)
  Flashlight.Enabled = true; // turn flashlight on, toggling would turn it off if it was already on
  Flashlight.CharacterToFollow = player; // Flashlight follows player
  if (GetGraphicalVariable("torch") == 0) {
    Flashlight.Radius = 0.0; // changed int 0 to float 0.0
  }
  else {
    Flashlight.Radius = 70.0; // changed int 70 to float 70.0 and colon ( : ) to semicolon ( ; ).
  }
}
#sectionend room_f  // DO NOT EDIT OR REMOVE THIS LINE

That should work (except for the Scaling issue which I hadn't previously considered).

[EDIT:]

I've re-uploaded the demo. It now includes a QuitFlashlightDemo function. Use this instead of the QuitDemo function. I've also included a Compiled folder which actually only contains the "flashlight.bmp" file.

You can now open the game in AGS and simply press Ctrl+T to try out the demo. And I don't want any complaining about me not releasing the demo as a compiled EXE. I did it this way on purpose so that you could read through the code and figure out how I worked these things through.

[GarageGothic]

Using five overlays plus not being able to use transparency? This doesn't seem very efficient. I take your original post about not being able to use overlays as they can't be bigger than 320 to mean that you moved the entire GUI around?

What if, on the other hand, you instead had a GUI with five buttons - a middle one using the flashlight mask sprite, and the four surrounding buttons entirely black? Their positions and sizes could then be adjusted accordingly so the edge sprites always aligned to the center one. This would allow you to do any degree of transparency.

[Da_Elf]

and what about the problem when the gui starts strobbing when i change rooms with the flashlight still on.

plus is the room scaling going to be an issue? i use it alot in my game.

[monkey0506]

Using five overlays plus not being able to use transparency? This doesn't seem very efficient. I take your original post about not being able to use overlays as they can't be bigger than 320 to mean that you moved the entire GUI around?

What if, on the other hand, you instead had a GUI with five buttons - a middle one using the flashlight mask sprite, and the four surrounding buttons entirely black? Their positions and sizes could then be adjusted accordingly so the edge sprites always aligned to the center one. This would allow you to do any degree of transparency.

Hmmm...yes...for some reason I hadn't thought it through like this. I've gotten it mostly worked out, except when nearing the edges of the screen I'm crashing with an error saying that GUIControls must have a size of at least 2x2. So I suppose that implementing a simple check that I'm not trying to set them any smaller than that should get rid of this error.

And I'll probably try to keep some of the old code in-tact so that if the GUI isn't present, it can use Overlays instead.

Anyway, more testing is in order for now. But thank you for pointing my mind in the right direction. I swear, sometimes I think if my skull wasn't so hard my mind would have broken out and wandered off to play in traffic somewhere...

[EDIT:]

@Da_Elf - The scaling issue has already been fixed:

v1.6 Update

I fixed the issue with Character scaling levels.

However I haven't had the chance (and/or haven't taken the time... ) to look at this strobing issue yet. I'll have to take a look at exactly what's happening, but if it's what I'm imagining, it should be relatively easy to fix.

First however, I'm in desperate need of some sleep that I haven't been getting (notice the timestamps on the changelog... 8)). So I haven't forgotten it, and I'll see what I can do to get it fixed.

[Lt. Smash]

when using the new 2.0 beta i get an error message:

ERROR (line 12): 'Follow Character' is already defined  //in Flashlight header

I hope you can fix it.

question:
is it possible to use an png as the flashlight, which is already transparent(alpha blended sprite) and has a black transparent  gradient?

like this?

[monkey0506]

How about: Enforce object-based scripting!

Hehehe...I didn't think about the fact that Character.FollowCharacter used to be just FollowCharacter, and the compiler can't handle both a global FollowCharacter function and a Flashlight.FollowCharacter function (unless the latter was declared first apparently (which isn't possible as the first is internal)).

I'm uploading v2.0 BETA 2 now which is identical except that if you haven't checked "Enforce object-based scripting" then Flashlight.FollowCharacter will be known as Flashlight.SetCharacterToFollow. The script-autocomplete will detect the correct version of the function (thanks to its cunning ability to detect the STRICT macro!).

As for the PNG, as long as you can import it into AGS then you can use it. Import the sprite into the Sprite Manager, then do something like this:

Code: ags

// game_start
Flashlight.SetSprite(DynamicSprite.CreateFromExistingSprite(42)); // 42 would be the slot number for your sprite

[Da_Elf]

I'm confused. how do i set my character to follow manually if the functions been locked. everytime i try to compile my scene when using Flashlight.CharacterToFollow = cEgo; i get an error about the variable 'FlashlightType::CharacterToFollow' is write protected.


the other problem i have since currently my flashlight is stuck on the pointer and not on the character is when I'm using a radius of 0 (to simulate the torch being burnt out.) i get some of the darkness missing


plus I'm also still getting strobbing when changing rooms

[Lt. Smash]

As for the PNG, as long as you can import it into AGS then you can use it. Import the sprite into the Sprite Manager, then do something like this:

Code:
// game_start
Flashlight.SetSprite(DynamicSprite.CreateFromExistingSprite(42)); // 42 would be the slot number for your sprite

that don't work.

I think the problem is, that currently only bmp and pcx can be loaded as a dynamic sprite.
So it would be better if the sprite will be used as the buttons normal graphic and not as a dynamic sprite.

Then it would be possible to use every format(if its supported from the editor) and it would be possible to use an already transparent picture.

EDIT:

using Flashlight.Sprite.Delete(); only the flashlightsprite will be deleted but there are also 5 other dynamic sprites, which won't be deleted.

[GarageGothic]

Da_Elf, have you tried using Flashlight.FollowCharacter(cEgo) instead?

Lt. Smash, what do you mean that DynamicSprites only can be created from bmp and pcx? Perhaps there's some mistake in the module code, so it doesn't work for that reason, but DynamicSprites can certainly be created from existing sprites.
There would be some trouble combining a 32-bit png with alpha channels and a GUI using transparency though, since alpha channels an the transparency setting are incompatible.

[Da_Elf]

that worked. the autocomplete kept giving me charactertofollow as an option.

im still getting the other two problems though. the one with the image i posted above im assuming has something to do with the fact that my game is 640x480 and maybe this code was designed for 320x240 or something like that.
as for the strobing it doesnt happen all the time. when i load the game in the 1st room everythings fine. however when i go into the next room all of the black pieces start to strobe on and off. sometimes i can walk through 3 rooms with no strobing then poof starts to strobe again