[AGS HELP WANTED] Wanted a documentation writer for AGS Manual

[Crimson Wizard]

Hello, this is literally a AGS HELP WANTED, in the sense that we need help for the AGS itself.

The AGS manual is lacking many topics, and some existing ones are not complete or not very well done overall. Unfortunately, there have been very little volunteers to help with it over the years.

I cannot remember if I did this before on Recruitment board, but I decided to do now (again?).

We are looking for a person which is:
- Good with writing in English;
- Good with explaining things to people, especially to those who might have less technical knowledge about the topic;
- Good with AGS, of course (you must know the subject well).

Our manual (source) repository is here:
https://github.com/adventuregamestudio/ags-manual
The manual may be edited as a Wiki, using Markdown language:
https://github.com/adventuregamestudio/ags-manual/wiki
There are basic guidelines for working with it:
https://github.com/adventuregamestudio/ags-manual/blob/master/CONTRIBUTING.md
I think the Tutorial pages may be used as an example of a "tone" that we'd like to have, that is not overly encyclopedic, and easy enough to understand for a non-technical person or a kid:
https://github.com/adventuregamestudio/ags-manual/wiki/acintro1
https://github.com/adventuregamestudio/ags-manual/wiki/acintro2
https://github.com/adventuregamestudio/ags-manual/wiki/acintro3


Currently this may be edited by anyone who has a Github account, although the dev team retains a right to edit or even reset your changes if you do something weird there. TBH I was about to discuss setting permissions differently with our dev team, but that's a separate question.

You may look for the list of tasks in the repository's issue tracker:
https://github.com/adventuregamestudio/ags-manual/issues
you may open ones too if you feel the need to


The tasks we are primarily interested in are:
1) Enhancing description of the Editor and editing various items in the project. Issue: https://github.com/adventuregamestudio/ags-manual/issues/218
2) Writing thorough explanation of Game Features, basically, explaining the logic of how things work in game, how they are set up and how they behave. Issue: https://github.com/adventuregamestudio/ags-manual/issues/209
3) Expanding tutorials, explaining solutions to most typical problems (say, run continuous state update in repeatedly_execute, and other).


If you have questions or suggestions, please contact us in this forum thread, at the issue tracker or AGS Discord (there's a channel dedicated to documentation). You may also send me a PM, although I'd prefer to keep the discussion public.

[RootBound]

It seems like no one is volunteering here, so even though I have only been using AGS seriously for a year or so, I have completed one game and about 90% of another, so I know the editor well enough to at least explain many of the "Built-in Game Features." This is essentially the list of components in the "explore project" window, correct?

I can definitely write a description of the basic ones like characters, rooms, inventory, guis, views, cursors, colours, and audio.

There are a few features I've not used there, though, like lip-sync, plugins, translations, and the text parser.

I'd be willing to put in some time on the basic things, though. Would I need to have a github account?

[Crimson Wizard]

@RootBound, hello, thank you for your interest!

I know the editor well enough to at least explain many of the "Built-in Game Features." This is essentially the list of components in the "explore project" window, correct?

Not only, there are objects that may only be created at runtime (like overlays, dynamic sprites, drawing surfaces), and also concepts that do not have a direct representation in the project tree, such as speech, animation, walking (pathfinding).

I'd like to emphasize again that there's a distinction between describing a game feature (behavior) and editing an item in the editor. In my opinion these should be distinct articles.

When I speak about features, I mean an overview of how something works in AGS.

To give couple of very crude examples:

Rooms

A game made in AGS consists of rooms. Rooms are like scenes, and may be used for various purposes: game locations, menus, cutscenes, and so forth. Rooms may have this and that. Characters travel between rooms. Only one room may be loaded and running at a time, - that is decided by where the player character is. Etc etc...

Characters

Character is meant to represent a person in the game (but may have other utilitary uses). Characters can: Speak, Walk, Animate. Character walking involves both moving and animating using current NormalView. Pathfinding is normally done over walkable areas in the room (link to what walkable areas are). Etc etc.

Would I need to have a github account?

Ideally yes, but if you don't want for some reasons, you could post the text elsewhere, except in that case we'd have to manually copy it over to the manual repository (and possibly reformat).

[RootBound]

Hi @Crimson Wizard ,

Thanks for the explanations.

Is there a complete list anywhere of which items need these pages written?

I certainly don't have the "in-engine behavior" knowledge to write many of these, but I can try for a couple of them.

Also, I've noticed that people here and on discord have commented that there are pages that need screenshots, which seems like an easy thing to create. Is there a list of "needed screenshots" anywhere?

Here is my attempt at writing a "behavioral" description of inventory items. Some of it may be incorrect or in need of clarification, but this is the extent of my knowledge of how they work:

Built-in Game Features

Inventory Item (attributes and behaviors):

Inventory items are a built-in class of script object, which have user-assigned images and cursors, as well as unique automatic ID numbers and user-assigned script names. Each unique inventory ID is included in a built-in array which may be accessed from the script.

An inventory item's five main capabilities are being "added" to a set of items that "belongs" to a character, "displayed" in those sets via GUI windows, "lost" from those sets, becoming "active" in the game interface, and being "used" on other game components such as hotspots, room objects, characters, and other inventory items.

Being "lost," made "inactive," or "used" does not affect the existence of the inventory item's definition and accessibility from the script. Each inventory item may also have multiple instances, such that a character may "possess" x number of any particular inventory item. Each character in the game has a distinct set of items that "belong" to them. Inventory items may be assigned to any or all of these distinct character inventory sets.

[newwaveburritos]

One thing that confused me about inventory items--and this may just be the BASS template--but in the custom properties you can set the item "InstantUse" as well which changes the behavior somewhat.  I didn't realize why it affected some inventory items and not others.  There's also the setting "display multiple icons for multiple items" that may also be worth mentioning.

I think what you're writing sounds great, though.  It fits the tone of the manual and helps explain things a bit further.

[Crimson Wizard]

Is there a complete list anywhere of which items need these pages written?

No, i did not prepare this yet. I think anything relevant will do for now, as things may be restructured later.

Also, I've noticed that people here and on discord have commented that there are pages that need screenshots, which seems like an easy thing to create. Is there a list of "needed screenshots" anywhere?

Not in my knowledge.

Here is my attempt at writing a "behavioral" description of inventory items. Some of it may be incorrect or in need of clarification, but this is the extent of my knowledge of how they work:

I've read it, and am afraid that it's written in an overly "encyclopedic" style. I'd propose a more light and regular-human-friendly style for these articles, so to speak.
There are also few incorrect terms used, and incorrect information.
For instance, Inventory items are not a "script object" but a game object, which has a corresponding InventoryItem script class.
Another example, it's not inventory IDs are in array, but pointers to InventoryItem objects are.

One thing that confused me about inventory items--and this may just be the BASS template--but in the custom properties you can set the item "InstantUse" as well which changes the behavior somewhat.  I didn't realize why it affected some inventory items and not others.

All custom properties come from templates, there are no custom properties provided by AGS itself.

[RootBound]

I've read it, and am afraid that it's written in an overly "encyclopedic" style. I'd propose a more light and regular-human-friendly style for these articles, so to speak.
There are also few incorrect terms used, and incorrect information.
For instance, Inventory items are not a "script object" but a game object, which has a corresponding InventoryItem script class.
Another example, it's not inventory IDs are in array, but pointers to InventoryItem objects are.

Thanks for the input. With regards to tone, I could certainly write in a more friendly style. That's not a problem at all.

I can try revising this draft to reflect your comments, but as regards the errors, I don't think my knowledge of the technical side of things is advanced enough to prevent similar errors on any other page I might write, so my text would have to serve as a very rough draft in need of revision by people with more expertise. If that's OK, I can continue writing drafts. If that's not a preferable situation, I may not be the best person for this, unfortunately.

[Crimson Wizard]

I can try revising this draft to reflect your comments, but as regards the errors, I don't think my knowledge of the technical side of things is advanced enough to prevent similar errors on any other page I might write, so my text would have to serve as a very rough draft in need of revision by people with more expertise. If that's OK, I can continue writing drafts. If that's not a preferable situation, I may not be the best person for this, unfortunately.

Frankly, it's not a problem if a text might require revision (that's a normal process), the problem is to get someone to make these revisions . I'd really wished to delegate the work on the manual to some other people, as I have to constantly switch between various tasks and that becomes tedious.

If you feel not confident enough on technical side, I might propose to skip certain "advanced" details in these texts, and only explain how things work in general.

[RootBound]

Here's a revision of the inventory items explanation:
-----------------------------------------------------

Inventory items, which are typically items the player carries around, are a built-in game object with a built-in corresponding script class. The user assigns each item an image and, optionally, a cursor, as well as a unique script name which allows each item to be easily called or pointed to from within the script.

An inventory item's main capabilities include the following:
- being added to the set of items that belongs to a character
- being displayed in those sets via a built-in class of GUI windows
- becoming active in the game interface (so as to be used by the player)
- being used on game components such as hotspots, room objects, characters, and other inventory items.
- being lost from the set of items available to the current character

 All inventory items may be given to a character multiple times, such that a character may possess any number of copies of any particular item, and each character in the game has a distinct inventory set to which items may be added. "Lost," "inactive," or "used" items always remain present and accessible in the script, and can be re-added to a character's inventory, re-activated, and re-used whenever the game requires.

[Crimson Wizard]

I might say that "Inventory items represent something that a character may acquire and use: a physical object, an idea, a useable skill, and so forth, depending on game mechanics that you want to have".

Another thing, in my opinion it may be better to say that characters own copies (or "instances") of items, this is why character may have multiple instances of same item, and multiple characters may have same item too.

"called or pointed to from within the script" - may be said as "referred to".

"set of items that belongs to a character" - may be called simpler as "inventory". Perhaps you could put the definition in front: "Inventory - is a set of items that belong to a character", and then use this term in the following text.

[RootBound]

Second revision.
------------------

Inventory items represent something that a character may acquire and use: a physical object, an idea, a useable skill, and so forth, depending on game mechanics that you want to have. They are a built-in game object with a built-in corresponding script class. The user assigns each item an image and, optionally, a cursor, as well as a unique script name which allows each item to be easily referred to and used from within the script. Each character in the game has their own overall "inventory" which is the set of items or skills they are carrying.

An inventory item's main capabilities include the following:
- being added to a character's inventory
- being displayed in a character's inventory via a built-in class of GUI windows
- becoming active in the game interface (so as to be used by the player)
- being used on game components such as hotspots, room objects, characters, and other inventory items
- being lost from a character's inventory

Character own copies or instances of inventory items, so any character may possess any number or amount of any particular item. These copies use the particular item's information as given in the AGS editor, which always remains present. This means that any time an item is "lost," "inactive," or "used," this affects only the specific copy of the item referred to. Other copies of the item remain, and new copies can be created, re-added to a character's inventory, re-activated, or re-used whenever the game requires.

[Crimson Wizard]

This is fine overall. Personally I have a concern about the general "scientific tone", but I don't know if it's just me. I would not want to seem like nagging over this.

Perhaps if some other AGS users could comment on this too?...

On the other hand, you could begin adding the texts to the manual source, and somebody might adjust the style later.


To elaborate, by "scientific tone" I mean the expressions like: "An inventory item's main capabilities include the following: " and then "being added", "being removed", "becoming active". This may be just me, but it feels like reading an algebra textbook.

I might give a link to the Tutorial we already have in our manual, which maybe could serve an example of a "tone":
https://github.com/adventuregamestudio/ags-manual/wiki/acintro1
https://github.com/adventuregamestudio/ags-manual/wiki/acintro2
https://github.com/adventuregamestudio/ags-manual/wiki/acintro3


For an alternate variant, I might imagine a more vivid text style (roughly):

Inventory item has:
* unique script name, used to refer to this item in scripts;
* textual name, for describing it to player;
* graphic, for displaying it on screen;
* cursor graphic, for setting a cursor when the item is selected.

What can you do with inventory item?
* Add to character's inventory and remove from one;
* Make item "active", which means it is "selected" for use;
* Use active item on other game entities, such as hotspots, room objects, ..... ......
* Whole inventory may be displayed on a GUI using InventoryWindow control. This is a standard way of displaying items on screen, but there are others (see below).

Each of the above points may be expanded below, with references to both editor and script commands: how do you do this and that with an item, how do you change their properties, etc.

Then this may be continued further, explaining the alternate ways of displaying and using items in game.

(very roughly)

Items do not have to be visible, they may be used even as a logical list of things.
.....
You may display items as a textual list, by using ListBox and filling it with Inventory Item's names.
.....
You may script your own custom inventory window using item graphics. For instance, you may place buttons on GUI and assign Inventory item's Graphic property as a button's NormalGraphic to make it look like an item is placed there.

[RootBound]

I think this is probably the last revision that I have the time and energy to write. I made a GitHub account, but I don't know how to post the text or where in the AGS manual it should go. If someone can tell me the proper place and how to add it, I will put the text there so that others can edit or expand upon it.

Third revision
--------------

Inventory items represent things that a character may acquire and use: a physical object, an idea, a useable skill, and so forth, depending on game mechanics that you want to have. Each character in the game has their own overall "inventory" which is the set of items or skills they are carrying. They can be made visible in the game, or simply work behind the scenes.

In technical terms, inventory items are a built-in game object with a built-in corresponding script class.

Each inventory item has:

* a unique script name, used to refer to this item in scripts; (required)
* a textual name, for describing it to player;
* a graphic, for displaying it on screen;
* a cursor graphic, for setting a cursor when the item is selected.

What can you do with an inventory item?
* add it to a character's inventory
* display it in a character's inventory using a GUI (this can be done with the built-in Inventory Window, a list box, or a custom GUI).
* make the item "active" (selected for use by the player)
* use the item  on game components such as hotspots, room objects, characters, and other inventory items
* remove the item from a character's inventory

In the game script, character own "copies" or instances of inventory items, so any character may possess any number or amount of any particular item. Using or removing an item affects only the specific copy of the item referred to. Other copies of the item remain, and new copies can be created, re-added to a character's inventory, re-activated, or re-used whenever the game requires.

[Crimson Wizard]

I don't know how to post the text or where in the AGS manual it should go. If someone can tell me the proper place and how to add it, I will put the text there so that others can edit or expand upon it.

I created a placeholder page here:
https://github.com/adventuregamestudio/ags-manual/wiki/InventoryItems

Added a section of "Game Features" on the main page:
https://github.com/adventuregamestudio/ags-manual/wiki#game-features

More pages may be added likewise.

I was not certain whether place "Game Features" before or after the "Editor" section, but that may be adjusted later.

[RootBound]

Thanks, that looks good. I feel like I'm missing something basic, though, because I can't see a way to edit it or paste anything here.

EDIT: I think I got it working. The text should be up now.

[Crimson Wizard]

I might have made a mistake though. There's only 1 item under "game features" now, and because we use this version of the manual to make a AGS distributable, it may look confusing to readers.

I need to find a way to "hide" these pages temporarily, until there's more related content.

There's a way to create separate "branches" in the manual, and put pages there, but these branches wont be accessible and editable from the Wiki frontpage, one would have to use git for that probably, and that's more complicated.

Alternatively, of course, we might quickly make several pages with at least some minimal information.

EDIT: Another alternative is if I make a private clone of the manual, and gather these new pages there. Then later, when there's enough material, I'd copy these texts to the official place.

[Crimson Wizard]

I might have made a mistake though. There's only 1 item under "game features" now, and because we use this version of the manual to make a AGS distributable, it may look confusing to readers.

I need to find a way to "hide" these pages temporarily, until there's more related content.

There's a way to create separate "branches" in the manual, and put pages there, but these branches wont be accessible and editable from the Wiki frontpage, one would have to use git for that probably, and that's more complicated.

Alternatively, of course, we might quickly make several pages with at least some minimal information.

EDIT: Another alternative is if I make a private clone of the manual, and gather these new pages there. Then later, when there's enough material, I'd copy these texts to the official place.

Does anybody have a good idea on how to solve this? Perhaps if there were a temporary place to gather these pages before there's enough content to look good in the manual?

Myself I don't have much spare time now to write these pages.

[eri0o]

 The wiki here in the forums is back at being in working state, it could be made there? It's also same login as the forums. Some pages currently in the manual were stolen carefully selected from there. 

[Crimson Wizard]

So, Morgan told me that the building process excludes all pages starting with underscore "_", therefore one may create pages like "_InventoryItems" and they won't get included.

Moved Game Features list and Inventory Items to the hidden names for now:
https://github.com/adventuregamestudio/ags-manual/wiki/_GameFeatures
https://github.com/adventuregamestudio/ags-manual/wiki/_InventoryItems