Script Module Guidelines discussion

[strazer]

Perhaps this example should be in the form of  a AGS Game Template (*.agt)  that would contain two modules  ExampleModule containg the example you suggest and NewModule containing empty templates.  This way if someone wanted to make a new module they could use this template to create a new game.  The could rename NewModule to whatever they wanted and start coding.

I don't think this will work. AFAIK modules get assigned a unique ID internally when they are created and you can't have two modules with the same ID. That means end users won't be able to mix modules that have been created from this template.

I'm for using a GUI name to prefix its objects(controls) names since just like with module functions and variables GUI controls are contained within a GUI, eg: GUI5_Button3, GUI5_Button3_Click.
But whether GUIs should be prefixed - is still a question.
If it's a specific module GUI I'd use a module name to prefix it:
MyModule_MyGUI
MyModule_MyGUI_Button1
MyModule_MyGUI_Button1_Click

What do you think about the problem?

I agree, prefix everything that is linked to a module.

[Scorpiorus]

I don't think this will work. AFAIK modules get assigned a unique ID internally when they are created and you can't have two modules with the same ID.

Yep, that's the only problem with having a module template in a form of an already created script module. IIRC, we discussed a possibility of having some sort of module template feature built-in AGS; making a module template as two pure text files can serve as a workaround for now I believe.

I agree, prefix everything that is linked to a module.

Funny enough, after have posted that suggestion I just discovered that the underscore character can't be a part of a GUI name.

[strazer]

I agree, prefix everything that is linked to a module.

Funny enough, after have posted that suggestion I just discovered that the underscore character can't be a part of a GUI name.

Also, GUI names can only be 14 characters long...

Going back, I think adding the GUI name to the GUI control script name like
  MyModule_MyGUI_Button1
is not necessary. Isn't
  MyModule_btnDoSomething
better? Naming the control for what it does?

[SSH]

I don't think this will work. AFAIK modules get assigned a unique ID internally when they are created and you can't have two modules with the same ID.

Yep, that's the only problem with having a module template in a form of an already created script module. IIRC, we discussed a possibility of having some sort of module template feature built-in AGS; making a module template as two pure text files can serve as a workaround for now I believe.

so, someone make a tracker entry then...

[strazer]

Honestly, I don't think this feature is needed at all.
Any user that is sophisticated enough to want to publish his own script modules doesn't need a built-in template system. The guidelines and some template text files are enough IMO.

[Scorpiorus]

Also, GUI names can only be 14 characters long...

Indeed... Moreover, the actual GUI script O-Name would be gMyModule_GUI then.

Isn't
Ã,  MyModule_btnDoSomething
better? Naming the control for what it does?

Yeah, provided it's prefixed with module name there shouldn't be any name collisions between modules GUI. The original idea is just to try making things consistent when, for example, module owns several GUIs:

MyModule_GUI1_Button1
MyModule_GUI2_Button1
etc...

It's surely possible to give controls different names but still a generic solution would be to have some sort of a prefix (which a GUI name could serve as just well).

But I found another problem with that -- GUI control name can't be longer 25 chars, nor its OnClick function name be longer than 30; so there is a possibility that even module name itself can eat it allÃ, away

Any user that is sophisticated enough to want to publish his own script modules doesn't need a built-in template system. The guidelines and some template text files are enough IMO.

Not a high priority, but still I guess it can be handy that we just started a new module and all the common license info, maybe also VERSION macro would be there. Just like with rooms the editor could probably read from two external text files (if those exist) instead of presenting blank scripts.

[strazer]

Just like with rooms the editor could probably read from two external text files (if those exist) instead of presenting blank scripts.

Yeah, that sounds simple enough. I like it.
Tracker'd: http://www.adventuregamestudio.co.uk/tracker.php?action=detail&id=535

[SSH]

Module name collisions issue

[edit by scorpiorus]

The following quotes were taken from the MODULE: Screenshots SAVELOAD GUI thread:

i imported the modules in the right order and also imported the guis. when i want to test my game i get this error:

'In: savegames with screenshots"

error (line 80): local variable cannot have the same name as an import
how can i fix this?

Do you have your own variable called li?

Change its name to something else

thanks. i really had a variable called "li". but now it works perfectly.

Hmm, interesting. This sort of name collision could happen if you had your own module listed before "Savegames with screenshots" one and which exports a "li" variable which originally is a local variable in "Savegames with screenshots" module itself.

[/edit]

Indeed. I could change the module to have something a bit more obscure, but I'm used to programming languages let local variables MASK any globals, so I think CJ should maybe do something, long term. I guess if ags_freak had stuck all his exports in a struct or with a module prefx, it would be OK.
We should note it in the module writing thread, though.

[Scorpiorus]

Yeah, making a note is a good idea. What I don't like there is no means to catch that one with #ifdefs in implicitly dependent module to display a user-friendly (heh) error message. The ultimate solution would be a possibility to specify what modules (if any) your module depends on. Currently a module depends on each module above (ie. it gets their script headers included).

[SSH]

I noticed while doing the module, btw, that there's was no point in using protected when writing the module: just hide any local function and variables in an struct that inherits the "public" struct. It also effectively allows protected static functions, etc.

[Scorpiorus]

Good point, thanks for sharing! Think it should also be noted in guidelines.

It won't always work for modules that expose structs for further instantiations in user script but for modules that use a single struct as an interface to their functionalities (almost always the case) it looks rather neat.

[SSH]

Hint for module developers:

When I am developing modules, I often use GUI labels to display debug info and trace script stuff. This can be dangerous, as twice I have accidentally left the debug code in which breaks it for everyone else, as they don't have those gui labels.

So, how to solve it? Create a Module at the top of you rmodule list called Debug or something. In the header define DEBUG_MYMODULE and then put #ifdef DEBUG_MYMODULE around all your debug code in your module-under-development. That way, even if you export the module with it all in, no-one else gets the debug stuff and it will work!

Yay!

[strazer]

I think you can even use #ifdef to check for the GUI name the labels are on:

#ifdef GUINAMETHELABELSAREON

But it's not fool-proof as the user could also have a view with this name and then the code would be compiled too. But nice anyway.

[Kweepa]

Before release, I'd recommend importing it into a clean test game to make sure it works.
That way you don't have to remember to put #ifdefs around test code. Speeds up the debugging process.

[Scorpiorus]

Agree with all those bits. I'd do #define-#ifdef approach if I needed the same source code for the debug and release versions of the module. Doing a clean new game test is also a good check to see if it works properly (ie. no undefined tokens etc).

[SSH]

Some further thoughts:

If you want a module to call a user-defined function, how about making a default function in your module but surrounded by:

#ifndef CUSTOM_FUNCTION
#endif

then the user can put their own function in an earlier module and put in a #define to override your module's function.

This could also allow some of a module to be source-protected but some editable...

And finally, I think that the MIT licence is better for AGS modules that LGPL, after some thought:

Code: ags

// 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.

[strazer]

SSH, why do you think the MIT license is better suited? I'm not well versed in legalese...

Also, I'm interested in this:

I noticed while doing the module, btw, that there's was no point in using protected when writing the module: just hide any local function and variables in an struct that inherits the "public" struct. It also effectively allows protected static functions, etc.

I don't quite understand what you mean. Could you elaborate a bit?


Anyway, I've noticed that the length of our discussions and the documents themselves seems to have made people reluctant to release their modules in fear of violating these guidelines.

And I agree the perceived amount of rules seems quite high at first. That's why I've written a short, easy-to-read summary of the guidelines that will hopefully encourage more people to release their modules.

Tell me what you think.

[SSH]

Looks good, great stuff strazer, and I think I agree with your changes.

I prefer MIT, because LGPL insists that any changed versions of the module need to be republishes as open-source, and if someone needs to modify one of my modules to add something game-specific, I don't think that is necessary. MIT simply asks for Credit and denies warranty liability.

I agree about people being scared too. I suggest your summary is made the only post ina locked sticky, with another thread (the rest of this one) linked to for discussion and fuller detail. It should also be presented as "Suggestion" and clearly stated that we'd rather people published modules "as is" than not at all.

[Scorpiorus]

Good work, strazer! Thanks for summing it up

*1 Is it really necessary to restrict the maximum length to 16 characters?

No, I believe... Still, developers should probably be encouraged to use relatively short but yet informative enough names. The problem with really long names is that it may bloat the source code making it a bit difficult to read.

*2 If both utility and application functions have local scope, do we really need to make the distinction?

I think it's up to the author and how they prefer to organize the internal structure of their modules. In this case it's a layered fashion where all functions divided into two or more groups forming layers so that if a higher layer is changed it won't affect a lower one. Again, in my opinion it's up to their decision. Generally depends on how complex the module is.

concerning naming convention for GUIs:

*3 This is my idea, I don't think we reached a consensus yet? What do you think?

I don't really know what's the best approach here. In my opinion, just make sure a GUI name is unique with prefixing it with a module name. But "g" will also be added infront, just to mention.

A shortcup name might be handy though, to compensate for the limit on max length of names.

*4 e moved to front to avoid value names popping up when typing the module name

Personally, I don't mind their popping up and prefer to see all module related stuff on the list but since one may find it annoying and we also have the exact behaviour with GUI names ("g" infront), it may be the option too.

I noticed while doing the module, btw, that there's was no point in using protected when writing the module: just hide any local function and variables in an struct that inherits the "public" struct. It also effectively allows protected static functions, etc.

I don't quite understand what you mean. Could you elaborate a bit?

What I believe he means is:

module header:

struct MyModule {

   // user functions
   import static void DoWork();
};


module script:

struct Internal extends MyModule {

   // additional internal functions
   import static void do_this();
   import static void do_that();
};

Maybe handy sometimes. See his module as an example of usage.

[strazer]

Thanks guys!

I prefer MIT, because LGPL insists that any changed versions of the module need to be republishes as open-source, and if someone needs to modify one of my modules to add something game-specific, I don't think that is necessary. MIT simply asks for Credit and denies warranty liability.

That makes sense. I like that better, too.

I suggest your summary is made the only post ina locked sticky, with another thread (the rest of this one) linked to for discussion and fuller detail.

Good idea, will do once we agree on all points.

It should also be presented as "Suggestion" and clearly stated that we'd rather people published modules "as is" than not at all.

Yeah, I'll emphasize this more.

Still, developers should probably be encouraged to use relatively short but yet informative enough names. The problem with really long names is that it may bloat the source code making it a bit difficult to read.

Sure, I meant to ask if there's a technical reason for the 16 character limit.
I'll change "as short as possible" to "as short but as descriptive as possible".

I think it's up to the author and how they prefer to organize the internal structure of their modules.

I understand the reasoning for the distinction but I agree with you that this should be up to the module author. For consistency, let's suggest lowercase for module-script-only functions?
--Edit:
Hm, come to think of it, since functions can be accessed from anywhere in the script after their definition, maybe camel notation would be the consistent thing?
--

In my opinion, just make sure a GUI name is unique with prefixing it with a module name. But "g" will also be added infront, just to mention.

The reason I proposed the numbering is that (last I checked) GUI names can only be 14 characters long, so with the module name prefix there wouldn't be much left anyway for a descriptive name.

Personally, I don't mind their popping up and prefer to see all module related stuff on the list but since one may find it annoying and we also have the exact behaviour with GUI names ("g" infront), it may be the option too.

Glad you approve.

What I believe he means is:

Great, thanks for clearing that up for me!