Add information on template functions not in template script

[babloyi]

Multiple templates listed here use:
open_gui()
close_gui()
show_restore_game_dialog()
show_save_game_dialog()

These are not documented anywhere

[ericoporto]

These are functions in the templates themselves, that can/should be edited by the user, it's not something in the engine API, isn't it better to document those in the script itself?

https://github.com/adventuregamestudio/ags-template-source/blob/c9f8c8ebde194ad026d095a7e6a30ef6fdd10fe5/Sierra-style/GlobalScript.asc#L47

The code is actually pretty small and obvious

[babloyi]

https://adventuregamestudio.github.io/ags-manual/Templates.html
Meant to link this in my original comment. This page exists for templates in the manual, and it links to pages for each template with documentation of specific functions in those scripts, so it wouldn't be weird to have them documented. The functions I mentioned above are common to many of the templates, but not documented anywhere.

As a person who was using those templates, I was confused as to why the regular AGS functions I was using for functionality that I always do in AGS didn't work.

[ericoporto]

The functions aren't exported, so you aren't calling them from elsewhere, from what I remember only public functions you may want to use elsewhere are documented.

There would have to be something about modifying the scripts but not about those functions in particular.

[babloyi]

That's also something that should probably be fixed. Since the functions behave in a specific way that should probably be consistent (e,g. mouse mode manipulation and using GUIs) that could be needed in Room scripts as well

[morganwillcock]

Multiple templates listed here use:
open_gui()
close_gui()
show_restore_game_dialog()
show_save_game_dialog()

I think it was me that introduced these functions (or at least the first two), but the reason for doing so was to try and provide a common interface which could be used to throughout the rest of this template. If AGS had some kind of GUI state stack (or something similar) I would have used that, but since each game has to implement this type of thing itself, I just took the most direct result possible to try and ensure that the final result was readable code.

But, in making them as simple and direct as possible, the final functions did end up being very specific to other decisions made in the game. As an example:

// hide the icon bar and show a GUI
function open_gui(GUI* gui_to_open)
{
  if (gui_to_open != gInventory)
  {
    lblOverHotspot.Visible = false;
  }

  gIconbar.Visible = false;
  mouse.UseModeGraphic(eModePointer);
  gui_to_open.Visible = true;
}

The above assumes that:

• There is a GUI used for inventory named gInventory
• There is some kind of label named lblOverHotspot which may need to be invisible and is somehow relayed to the inventory GUI
• There is a GUI named gIconbar.Visible which definitely should be hidden
• The mouse cursor should definitely be changed to eModePointer

All of these choices are game specific, and I would imagine that anyone doing something slightly different is probably going to partially or fully replace the functions.

Ideally all of these things should be handled by script modules and those modules should be documented somewhere, but I don't think the functions that are there are equivalent to the missing modules. I just tried to make things as obvious as I could so that someone reading the code would know which parts to replace. I'm not sure it would make sense to document the functions as part of the template, but the comments in the code could be improved, or the tutorial could go through what each part of each function does.

Or to put it another way, what AGS calls a template has already gone way past the point where anything can be templated. Unless the behaviour can be modular, the final template will always have game specific code in it which will need to be changed.

P.S. I hope you are well, @babloyi