AGS v2.7 Final: Yet Another Edition

[Pumaman]

S3M works fine as far as I know ... can you upload an s3m file that doesn't play, if you're having problems.

[Gregjazz]

Looks like the latest beta puts a few plugins out of business.

Won't be needing to use Maya again.

[jetxl]

http://www.2dadventure.com/ags/s3mmusic.zip

I tried it on two computers. both didn't work (in ags, that is).
mod and xm works fine.
s3m stopped working around 2.60? I don't know...

[Pumaman]

jetxl: ok thanks, I'll look into it.


Anyway, here's a first draft of the Upgrading to Object Based Scripting guide:
http://www.adventuregamestudio.co.uk/manual/UpgradingTo27.htm

Basically, this will be aimed at people who are currently using 2.62 but haven't been looking at this beta thread. Let me know if there are any errors or omissions, or any further detail you think should be added.

[strazer]

I think a passage about enums and optional parameters would be nice.

[strazer]

Ok, I didn't realize the function would have to be renamed. In that case it can probably wait.

Yeah, it's backwards compatibility -- if it wasn't renamed, and the engine was used to run an old (2.62) game, it would only push one argument to the function, and mess the stack up.

I just think PlaySoundEx isn't a terribly intuitive name. Seeing as we have a tracker entry about PlaySoundChannel anyway, how about renaming PlaySoundEx to PlaySoundChannel and, since optional parameters are possible, be able to add the vol, x, y and loop parameters at a later time?
Or would that pose the same backwards compatibility problem?

[HeirOfNorton]

An intro to pointers and how they work would also be nice.

HoN

PS (Hey, here's a neat side-benefit to using AGS. I've just started learning how to program in C++, and I'm already familiar with a lot of the conventions/syntax. Thanks, CJ!)

[RickJ]

If there's anything else that anyone is keen to have in terms of float support, now's the time to speak.

Just did  overflow and undeflow test.  Both conditions handled perfectly, as far as I could tell.   Nice work 

Yeah, it would be nice to have them all working like that. I propose to add hotspot and region objectisation for the next beta and then call it a day, again unless anyone has good reasoning to do anything else.

Great!  I suppose you are leaving out Walkable and Walk Behind Areas because they have no interactions and so very few functions that do anyting with them?  Future possibilites come to mind though, particularily with regard to Set/Get property type stuff (not the custom property thingy of course).   Leaving this to the future, I think, works for most of us. 

Oh, will regions be geting script-o names or how will they  be handled?   

Basically, this will be aimed at people who are currently using 2.62 but haven't been looking at this beta thread. Let me know if there are any errors or omissions, or any further detail you think should be added.

How about adding a section called GOTCHAS

New Keywords/Reserved Words
A number of new keywords have been added in this version of AGS.  If any of these are used as variable, function, or parameter names in a game you are upgrading it is very likely you will get compile errors.  Change your names to something else and recompile.  Here is a list of keywords/reserved words

• object
  
• attribute
  
• etc
  
  Using '==' with Floating Point Numbers
  The likely hood of any two floating point numbers being exactly equal is extremely low.  Comparing two floats using the '==' operator  may not produce the results you expect.  Try checking for a range instead.
  
  
  
  

[Pumaman]

I think a passage about enums and optional parameters would be nice.

Done.

I just think PlaySoundEx isn't a terribly intuitive name. Seeing as we have a tracker entry about PlaySoundChannel anyway, how about renaming PlaySoundEx to PlaySoundChannel and, since optional parameters are possible, be able to add the vol, x, y and loop parameters at a later time?
Or would that pose the same backwards compatibility problem?

I agree about PlaySoundEx being nasty ... in fact, I hate "Ex" naming. But, adding extra parameters later would pose the same compataibility problem.
However, in this case I'm really not convinced of the need for the (x,y) parameters, so how about:
PlaySoundChannel(sound, optional channel, optional loop, optional volume);

An intro to pointers and how they work would also be nice.

Ok, well I've added a very brief paragraph explaining that pointers exist, but I don't want to confuse matters too much by talking about them at this stage. Perhaps a "Part 2: Advanced topics" page later on could cover them properly.

Great!  I suppose you are leaving out Walkable and Walk Behind Areas because they have no interactions and so very few functions that do anyting with them?

Yeah, they have so few functions I can't really justify the time and effort. It was a close call with Regions in that respect, but I've decided to do them anyway.

Oh, will regions be geting script-o names or how will they  be handled?   

No, I don't really think it's worth it. Hotspots will get an "hHotspot" name, but regions will not. You'll have to access them through:

region[3].LightLevel = 40;

or whatever.

New Keywords/Reserved Words
A number of new keywords have been added in this version of AGS.  If any of these are used as variable, function, or parameter names in a game you are upgrading it is very likely you will get compile errors.

Good point, added.

Using '==' with Floating Point Numbers
The likely hood of any two floating point numbers being exactly equal is extremely low.  Comparing two floats using the '==' operator  may not produce the results you expect.

This is an interesting one. I was actually thinking about dealing with it by making the == operator return true for floats if the values were within 0.0001 of each other. Do you think this would be useful, or would this be annoying big brother interference when you did actually want to compare at a very fine accuracy?

[Radiant]

This is an interesting one. I was actually thinking about dealing with it by making the == operator return true for floats if the values were within 0.0001 of each other. Do you think this would be useful, or would this be annoying big brother interference when you did actually want to compare at a very fine accuracy?

From a purist mathematical point of view, I would disagree with that. If two things aren't equal, then == isn't true for them. Plus there's the matter of exponents (according to your defintion, 1 ex -8 == 1 ex -10, since the difference is 99 ex -10, which is less than 1 ex -4).
Maybe you could create a shorthand function for (abs (float_a - float_b) < epsilon), though.

[strazer]

I agree about PlaySoundEx being nasty ... in fact, I hate "Ex" naming. But, adding extra parameters later would pose the same compataibility problem.
However, in this case I'm really not convinced of the need for the (x,y) parameters, so how about:
PlaySoundChannel(sound, optional channel, optional loop, optional volume);

Works for me.
However, I would prefer for "volume" to be the second parameter, so we need not specify a channel if we want to play a sound at a specified volume.
Because PlaySoundChannel(sound,,, 80); doesn't work, right?

Btw, would that volume affect the whole channel or only that sound?
I was thinking about how to implement "adjust volume with scaling" for frame sounds, so being able to play only the sound at the specified volume would make that possible.
Almost sounds like a suggestion...sorry.

[Pumaman]

From a purist mathematical point of view, I would disagree with that. If two things aren't equal, then == isn't true for them.

But on the other hand, they might well have been supposed to be equal, but the precision has been lost.

However, I do see what you're saying. Floats only have an accuracy of 6 digits; but because these 6 digits can "float" anywhere due to the exponent, just hardcoding something like "0.001" in wouldn't be fair on people trying to work with small numbers. Perhaps I'll just leave it and add a warning as Rick suggests.

However, I would prefer for "volume" to be the second parameter, so we need not specify a channel if we want to play a sound at a specified volume.

On the other hand, having to specify the volume would be annoying if you just wanted to loop the sound. Actually, thinking about it I can't see any ideal order for these parameters. Hmmm

[Pumaman]

http://www.2dadventure.com/ags/s3mmusic.zip

I tried it on two computers. both didn't work (in ags, that is).

I've just tried this out ... seems that the S3M player that AGS uses doesn't like these tracks. I've found an alternate player, but the problem is it doesn't support SeekMODPattern. How many people are using SeekMODPattern; what would opinions be like if it stopped working?

[Gilbert]

In my opinion SeekMODPattern can be quite useful for tracker musics, it's just common that a tracker music piece plays in on player and doesn't in another (that means if the player is changed it's also possible that it won't play some of the files the engine used to play anymore), so I vote for not changing it.
If there's a file which won't work, I'd recommend using another (in different format or some other composition, etc.).

[RickJ]

This is an interesting one. I was actually thinking about dealing with it by making the == operator return true for floats if the values were within 0.0001 of each other. Do you think this would be useful, or would this be annoying big brother interference when you did actually want to compare at a very fine accuracy?

Instead of playing with the == operator, how about  adding a floating point function to test if a value is in a specified range.   It could return 1 if the value was within the range and 0 otherwise.  If the "min" parameter is not specified then the range is +/- max.  For example:

   FloatInRange(float value, float max, optional float min);  // For lack of a better name

   float var;

   if (FloatInRange(var, 10.1, -0.042)) { // Do something when 10.1 <= var <= -0.042
   }

   if (FloatInRange(var, 9.234)) { // Do something when 9.234 <= var <= -9.234
   }

[Gilbert]

Interesting, but FloatInRange() can be just defined like:

function FloatInRange(float var,float min,float max) {
Ã,  if ((var<=max)&&(var>=min)) return 1;
Ã,  else return 0;
}

Well the max parameter is not optional here, but users can just custumize it according to their needs, like changing >= to >, etc. So I think it's not quite necessary to add this internally.

For the '== true for within certain range' part I'll say 'no', unless you can set the accuracy via some function/property/game variable/whatever, eg:
FloatSetCompareAccuracy(0.01); //so x==y will return true if |x-y|<0.01
as different people may need different accuracies.

[strazer]

However, I would prefer for "volume" to be the second parameter, so we need not specify a channel if we want to play a sound at a specified volume.

On the other hand, having to specify the volume would be annoying if you just wanted to loop the sound. Actually, thinking about it I can't see any ideal order for these parameters. Hmmm

Seeing as it would be called PlaySoundChannel, maybe the "channel" parameter shouldn't be optional, but passing -1 for example would choose a free channel like PlaySound.
Would it be too much trouble to implement the x and y parameters? I think it would be nice being able to pan the sound.

[jetxl]

I've just tried this out ... seems that the S3M player that AGS uses doesn't like these tracks. I've found an alternate player, but the problem is it doesn't support SeekMODPattern. How many people are using SeekMODPattern; what would opinions be like if it stopped working?

In such case, instead of one music file, you could make two. Instead of jump to another pattern, you can just simply play the second music file.

In my opinion SeekMODPattern can be quite useful for tracker musics, it's just common that a tracker music piece plays in on player and doesn't in another (that means if the player is changed it's also possible that it won't play some of the files the engine used to play anymore), so I vote for not changing it.
If there's a file which won't work, I'd recommend using another (in different format or some other composition, etc.).

The weird thing is that a s3m file I used worked fine, then I stopped working on the game for a while (and downloaded other ags versions), but when I tested the game again, the music didn't work. Somewhere along, the s3m tracker in ags must has been changed?

s3m converters are rare, work in dos (not in xp. I hate xp), and will bring the quality down. I changed them to mp3, but then the game is more than 3 times bigger (making it hard to host it on my wbsite).
This the first time I made music, and it fits the atmosphere of the game perfect. I don't want to change a thing about it.

[SSH]

Another nice thing would be if the recompile all rooms dialog on loading an old game had 3 options instead of 2: OK, Load but dont recompile rooms and Cancel... that way you can use the latest editor to load an old game just to look at, without it forcing the old game into 2.7 ...


EDIT:

and are enums strictly type-checked? Can I use an enum value of one enumeration as a parameter to a function that has a different enumeration type? Can you set more that one identifier to the same value in the same enumeration, i.e.

enum verb { Take = 1, Pickup = 1, PickUp = 1, ...}


EDIT 2: MORE TECHIE QUESTIONS

Is it possible for a global function to take a pointer to a function as an argument, and then call the dereferenced pointer. Would this work if the function was a room specific function?

I am thinking to avoid using the interaction editor by having global functions  called something like SetObjectCallback which run in the before_fadein of the room and set up a global array which the global script can use to find otu which function pointer to use for a given verb/object or verb/hotspot combination. Is this possible?

And can you have static protected functions?

And can you have static member variables, protected or otherwise?

Oh, and the manual doesn't mention that you can have a room-specific rep_ex_always function

[Pumaman]

In my opinion SeekMODPattern can be quite useful for tracker musics, it's just common that a tracker music piece plays in on player and doesn't in another (that means if the player is changed it's also possible that it won't play some of the files the engine used to play anymore), so I vote for not changing it.

Thanks for your input on the MOD music issue, guys. However, we're in luck, as I've found an alternate mod player that supports MOD/XM/S3M/IT and also does support SeekMODPattern, so things are looking good. I'm currently giving it some testing, with a view to implementation in beta 10.

Instead of playing with the == operator, how about  adding a floating point function to test if a value is in a specified range.   It could return 1 if the value was within the range and 0 otherwise.  If the "min" parameter is not specified then the range is +/- max.  For example:

Good idea -- but then, as Gilbert says, it's so easy to implement yourself that I'm not sure a built-in function is necessary.

Seeing as it would be called PlaySoundChannel, maybe the "channel" parameter shouldn't be optional, but passing -1 for example would choose a free channel like PlaySound.
Would it be too much trouble to implement the x and y parameters? I think it would be nice being able to pan the sound.

Well, I was also thinking of renaming it to PlaySoundEffect; but I digress, let's leave this one for now

Another nice thing would be if the recompile all rooms dialog on loading an old game had 3 options instead of 2: OK, Load but dont recompile rooms and Cancel... that way you can use the latest editor to load an old game just to look at, without it forcing the old game into 2.7 ...

Sounds reasonable -- it is a bit drastic at the moment forcing you to recompile or quit, so I'll make the change.

and are enums strictly type-checked? Can I use an enum value of one enumeration as a parameter to a function that has a different enumeration type? Can you set more that one identifier to the same value in the same enumeration, i.e.

No. Yes. Yes.

Is it possible for a global function to take a pointer to a function as an argument, and then call the dereferenced pointer. Would this work if the function was a room specific function?

No; allowing function pointers throws up various problems and isn't something I'll be implementing for 2.7.

And can you have static protected functions?

Yes.

And can you have static member variables, protected or otherwise?

No.

Oh, and the manual doesn't mention that you can have a room-specific rep_ex_always function

Actually it does, under "repeatedly_execute_always" in the Scripting event reference.