Script Module Guidelines discussion

[Scorpiorus]

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?
--

My opinion would be to leave it up to the develovers, as long as it relates to module internals. The user functions should however be in camel notation, just to be consistent with AGS built-in ones. But even that should not be that important in contrast to prefixing exposed stuff with module name to avoid name collision.

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.

Yeah, I remember there was/is an issue. Any numbers as well as any other names should be ok... provided there is a prefix there. Developer may decide what method to use taking into account the length of module/gui name.

Great, thanks for clearing that up for me!

No problem, thinking of it more however suggests "extends" is not really necessary there since we don't operate with pointers (except for those built-in) to interfaces and such stuff in AGS (at the momentÃ, at least ).

[strazer]

My opinion would be to leave it up to the develovers, as long as it relates to module internals.

Any numbers as well as any other names should be ok... provided there is a prefix there. Developer may decide what method to use taking into account the length of module/gui name.

Of course, the developer is free to do as he chooses. Nobody forces him to follow these guidelines.
Remember, they are only suggestions, but they should be consistent in themselves.

Let's leave it at that. I'll change the suggestion to camel notation.

[Scorpiorus]

Sure. What I just want to point out is that suggestions can be separated in two levels of importance.

First is of a greater importance where it is highly recommended to have a module name prefix to avoid name collisions so that it won't be the reason why one can't have two or more modules working together. It is the reason of having modules after all.

Other is of less one; includes naming conventions, internal organizations etc. May be essential if a group of developers is working on the project, so all would have the same style and it would be easier to read others' codes.

And consistency is a good thing of course

[strazer]

True, important points should probably be emphasized. I'll get on it.

Edit: Done.

[Scorpiorus]

Looks accented now, well done!

By the way, looking at the unique name suggestion what do you think of having a list of modules with their short(script) names included?

A list from AGS Wiki is nice when you're looking for a module to use but it's not clear where it's a script name and where -- a full descriptive one.

I understand, not all modules have a name to prefix but specifying which names are actually "reserved" (already used) would be nice.

It would be of great help to developers, so they wouldn't have to download and open each module to check for its name (if any).

And where should such information be suitably posted?
Possibly as another part of this post?

[strazer]

It think it's a good idea.
But I for one wouldn't want to maintain such a list and I imagine no one else would, so I think adding each module's "script-o-name" to the list of modules in the wiki would probably be the best solution.

In fact, since in the wiki there's hardly any information on the modules anyway, why not just list them all by their script-o-name where available?
Either that, or adding the script-o-name separately without making it look like a mess.

[Scorpiorus]

so I think adding each module's "script-o-name" to the list of modules in the wiki would probably be the best solution.

What I guess may be an obstacle is that some of them reserve additional names for GUIs, etc. I believe it might be too messy to list all such names there.

In fact, since in the wiki there's hardly any information on the modules anyway, why not just list them all by their script-o-name where available?

One problem I see, it's sometimes hard to distinguish between script and full names. The Easy3D module, for instance. That's how it's refered to on Wiki. But the script name is E3d, which is fine for scripting but would look rather ambiguous on the list.

The same goes to "Save/load game GUI with screenshots"; its "sgs" acronym would not look informative at all.


I volunteer myself for looking through the modules to investigate the situation and see if I can come up with a list of used names.
If I manage to compile something I'll post it here for us to consider the rest.

I wouldn't find maintaining the list a big deal but it would be cool if module authors post all the global names (prefixes) they're used in their module thread.

[SSH]

I always meant to expand on the modules list in the wiki, at least for my own modules, and put some documentation in, but haven't got around to it yet....

[Scorpiorus]

Ok, so I took a list of modules from Wiki and browsed through them to see what module "script names" and GUI names are used there, then analysed and built a list.

I didn't check for names of GUI controls at the moment, though.

What I noticed is that some modules have #defined constants (and/or enums) in their headers that could have been prefixed, that would effectively put them within a module "namespace".

Next, there are modules that use an uppercased version of their prefix to define the version macro, ie. MYMODULE_VERSION instead of MyModule_VERSION. It's not a big deal but since the compiler would distinguish between them I listed both.

Also, there are extra prefixes in a couple of modules to mark identifiers (ie. whether it's a struct/function/define). Again, shouldn't be a big chance of name collisions this way but unlike with enums I'm not really sure whether it's necessary.

By the way, another advantage of using the same module name prefix for all identifiers is that once it's typed-in the autocompleter will bring the list of identifiers related to this module. If there is a name one don't want to pop up, then just hide it with #define, $AUTOCOMPLETEIGNORE$, etc...

In either way, those are suggestions aimed to assist users, so that it would be easy to install a module and use, no matter how much code they've written or how many (which) modules are already on the list.

You can find the list here (the list is removed).

[Wretched]

 Thought I might suggest adding a Object/Character Properties naming convention, guess MyModule_Property would do.

[strazer]

Ah, you mean the built-in custom properties accessible from the editor? Sounds like a good idea to me. What do the others think?

[SSH]

Well, in practice I've found those things to be more trobule than they are worth, strazer. But why MyModule? Or is this for properties that are to be used by a module?

[strazer]

Yes, that's my understanding. Apparently his Easy3D module uses custom character properties.

[RickJ]

I just saw Strazer's summary of the Script Module Guidelines.  He has done a nice job of simplifying everything and making it less intimidating.   I have a few comments I'll share below. 

GUI Naming Convention
I have mixed feelings about this proposal.  I understand the motivation behind using the module name as a GUI prefix but wonder if this is the best approach.   

When a Gui event occurs an event handler function is called and passed a pointer to the gui contol that generated the event.   The event handler calls one or more functions to service the event.   In our case here these functions are presumably defined in a module.  The passed pointer is the linkage between the GUI and the module and it can be used to access the GUI and all of it's controls.  It doesn't seem right to uneccessarily create other linkages.

The problem is that the pointers to all controls on all GUIs are global instead of being children of the GUI in which they occur.   So for example if a GUI has two or more labels you can walk through all the controls and pick out all the labels but you don't have a way of knowing which one is which.  If they were children of the GUI then you would be able to get to the one you wanted just by using the child's name (i.e. GuiPointer.Title.Text="Hello").   In this way external references to controls are relative to a GUI which is passed in as a pointer.  The module could then check for the existance of the Title label, in this example, write the title text if the label exists, and do nothing otherwise.   

Hopefully the above description is clear enough to generate some discussion about this.  I have only recently started doing some Module/GUI work so I'm a bit naieve about some of the practicalities but it seems to me that the passed pointer should be the linkage to the GUI and that a method needs to be devised to allow specifc controls relative to the GUI to be identified.   Most of the time the only thing you need to know is the control that generated the event.  In cases where this is inadequate, perhaps, there could be an initialization method where each control on each GUI could be indentified to the module by calling MyModule.GuiInit(GUI *GuiPtr, GUIControl *CtrPtr, int Id).   Something like this:

Code: ags

function game_start() {
   // Initialize Save Game GUI
   MyModule.GuiInit(gSave, gSaveOk, eMyModule_OK);
   MyModule.GuiInit(gSave, gSaveCancel, eMyModule_CANCEL);
   MyModule.GuiInit(gSave, gSaveList, eMyModule_SAVEDGAMES);
}

One other thing relating to GUI naming conventions.  I don't really see any useful purpose in using M$'s infamous hungarian notation (is  that what it's called? i.e.  lblTitle) in forming control names.   In the context of AGS and autocomplete it's redundant to include the data type in the name and it burns up a limited number of characters available to the name.    I suppose everyone has their own preference; mine would be to not encourage the use of this style of notation.   IMHO, it's more important to prepend the GUI name so as to make the most of the auto-complete feature.   Given this, and our use of camel notation everywhere else, this kind of prefix is just out of place and should not really be incouraged.   

What do the rest of you think about this?   

[strazer]

I just saw Strazer's summary of the Script Module Guidelines.  He has done a nice job of simplifying everything and making it less intimidating.

Thanks, I'm glad you approve.

The problem is that the pointers to all controls on all GUIs are global instead of being children of the GUI in which they occur.   So for example if a GUI has two or more labels you can walk through all the controls and pick out all the labels but you don't have a way of knowing which one is which.

I'm not sure I understand what you're suggesting.
I proposed to also enumerate the GUI name when prefixing the module name, i.e. naming the GUI for example MYMODULE1, so you would be able to distinguish labels on different GUIs by prepended the GUI name they're on: MYMODULE1_LabelA vs MYMODULE2_LabelA

If they were children of the GUI then you would be able to get to the one you wanted just by using the child's name (i.e. GuiPointer.Title.Text="Hello").

Is this a feature request or what are you saying?

I don't really see any useful purpose in using M$'s infamous hungarian notation (is  that what it's called? i.e.  lblTitle) in forming control names.

As you say, it's personal preference, my preference in this case. I like all button control names to pop up when I start typing "btn".
But if you read it again, you'll see the control name itself is not part of the suggestion, just a name I chose without thinking. I've changed it now.

[SSH]

I've posted in the Tech Forum about this, but I've moved my preference for licences from the MIT one to the Creative Commons Attribution-Sharealike. One good thing about it is that there are many localised versions of it for your own countries' legal systems.

[strazer]

Yes, I like CC, the licenses are worded so even I can understand.

Is everybody okay with changing our suggested license to this?

This work is licensed under the Creative Commons Attribution-Share Alike 3.0 License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative Commons, 543 Howard Street, 5th Floor, San Francisco, California, 94105, USA.

You are free:
    * to Share â€" to copy, distribute and transmit the work
    * to Remix â€" to adapt the work

Under the following conditions:
    * Attribution. You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work).
    * Share Alike. If you alter, transform, or build upon this work, you may distribute the resulting work only under the same, similar or a compatible license.
    * For any reuse or distribution, you must make clear to others the license terms of this work. The best way to do this is with a link to this web page.
    * Any of the above conditions can be waived if you get permission from the copyright holder.
    * Nothing in this license impairs or restricts the author's moral rights.

And another thing:

I volunteer myself for looking through the modules to investigate the situation and see if I can come up with a list of used names.
If I manage to compile something I'll post it here for us to consider the rest.

I see you haven't updated the list in a while.
As I have feared from the beginning, with the amount of modules being released nowadays, collating these names has probably become more work for one person to handle.
How about we add a "List of reserved module keywords" or something to the Wiki so everybody can help? Would you mind setting that up?

I wouldn't find maintaining the list a big deal but it would be cool if module authors post all the global names (prefixes) they're used in their module thread.

Yeah, another suggestion for authors to update the list probably wouldn't hurt.

[Scorpiorus]

Is everybody okay with changing our suggested license to this?

Yeah, they of course can choose whatever license they like, but that suggested license seems like a good alternative in case they are not sure.

I see you haven't updated the list in a while. As I have feared from the beginning, with the amount of modules being released nowadays, collating these names has probably become more work for one person to handle.

Ah yes sorry that the list hasn't been updated; their quantity is not a real problem though. The real issue is that quite a few modules just doesn't follow the guidelines which makes it questionable whether it's worth listing all the names from a module header.

And listing only those that follow? Seems a bit discriminative to me...

How about we add a "List of reserved module keywords" or something to the Wiki so everybody can help? Would you mind setting that up?

Sure, that's probably the best way to deal with it. I wouldn't use the word keywords, as it more implies some basic language tokens, such as if, while, int etc.

And maybe indeed only put those there that at least use a struct (or prefix) to group their user functions, because that list is more for developers to check if their module's identifiers chance to collide with others'.

[GarageGothic]

But what would the "share alike" clause mean for games using the modules? Does it mean they need to be open source? Does it mean they can't be sold? Simplicity isn't always the same as clarity

[Scorpiorus]

Hmm... I think the main question is what's meant by "build upon this work"?

If a game using a module is considered to be built upon this module then yes the game must also use a similar license.

The problem with script modules is that they are plain source script codes. Were they external compiled units there wouldn't be any problem I believe. A game then would just use the module but it would not be an internal part of the game.