User-submitted tutorials / How-To's

[Collector]

The Creating and Editing stub is here http://sierrahelp.com/SCI/SCIStudio3Help/vocabresources.creatingandediting.html
which is a modified version of http://sierrahelp.com/SCI/SCIStudio3Help/viewresources.creatingandediting.html
This one is as complete as the one for the other resources and probably doesn't need anything more.

The stub is here http://sierrahelp.com/SCI/SCIStudio3Help/vocabresources.overview.html
which is a modified version of http://sierrahelp.com/SCI/SCIStudio3Help/viewresources.overview.html
Feel free to change it as needed, but it is just a brief overview. I only need text. You can post it here and I'll work it in the help file.

[gumby]

Let's start with this: (anyone else please feel free to jump in).   Modify as you see fit...

- All words that can be inputted by the user must reside in the vocabulary in order for the parser to accept the user input, with the exception of word suffixes (see below).

- It is critical that the correct parts of speech are associated to each vocab word for the parser to interpret what the user is attempting to communicate.  It is not recommended to change parts-of-speech of a word just to get the desired result in your code.  There is an occasional need for it, but before doing it explore all other avenues.

- Note that the template game has most (if not all) of the vocabulary words from all SCI0 games.  This means that the need for adding new words will probably be limited to nouns and qualifying adjectives (and perhaps some imperative verbs & adverbs).  When adding new words, it is recommended to find other similar words & model the parts-of-speech from them.

- Word suffixes:  It is not necessary to add word suffixes to the vocabulary words unless the game developer would like to make a distinction in their code (specifically in the Said() string syntax) between two words with the same root word (example: tree vs. trees, jump vs. jumping, etc).  Suffixes are predefined in another vocab resource not directly accessible for modification within SCI Studio.  This means that if 'tree' is defined in the vocab (and it's plural is not), the user is free to enter the word 'trees' & the parser will accept the input, ultimately converting the word down to it's base word 'tree'.

- Synonyms:  The use of synonyms is encouraged.  Any number of synonyms can be used for a word; they reside with the word in vocabulary, separated with the vertical bar (|) character.  Using synonyms limit the amount of code a developer needs to write to handle various inputs & makes it easier to the game player for find a word that matches the intended meaning.  Take for example the word 'door'.  It could by matched in the input phrase 'open door'.  However, if we added a few synonyms to door (like this: 'door | portal | gateway | opening'), then the user could enter 'open portal' or 'open gateway', and the developer's code would work as if the user inputted 'open door'.

[Collector]

This is more detail than what I was thinking, but it is more clear than most of Brian's documentation. I have been thinking that the information in the help file should be incorporated in the Wiki in more of a reference form than the current help file form. Something where the aim was to understand and how to work with SCI rather than Studio specifically. It could easily be crossed referenced better than what the help file is.

[gumby]

This is more detail than what I was thinking, but it is more clear than most of Brian's documentation. I have been thinking that the information in the help file should be incorporated in the Wiki in more of a reference form than the current help file form. Something where the aim was to understand and how to work with SCI rather than Studio specifically. It could easily be crossed referenced better than what the help file is.

Do you need me to boil what I put together down to a more appropriate overview?  Seems like what you've got already on that page does a pretty good job (without going into too much detail).

[Collector]

I just combined the two and added it to the TOC. References to it elsewhere in the help file should be OK as I used the same name for the files that the links were looking for.

[MusicallyInspired]

The guys at ScummVM don't seem to agree with the fact that we copied the same FreeSCI documentation that's on their wiki and would rather host the SCI Development Wiki over there. Here's the thread. What's everybody think? Their argument is that having two sites with the same information is redundant and one is more prone to going out of date. I just really think it's a great second resource for SCI game development as opposed to engine development. And there's a lot of valuable information in the FreeSCI docs for game developers.

I really like the idea of it all being under a Sierra roof, owned and operated by active SCI game developers rather than another thing for ScummVM to swallow up into itself and have control of. I have no say in the matter at all seeing as I didn't make any of this, but I thought it should be brought to your attention since we all own it in a way, being the developers and contributors.

[Collector]

I have been following it, but have not responded because I don't like their attitude. They proudly display the GNU Free Documentation License logo on their copy of the SCI documentation as they tell us that we should not have the FreeSCI documentation on our Wiki. I got the documentation from the FreeSCI site, not their Wiki. I also included the original copyright info. We have the legal right to publish it to our Wiki

Permission is hereby granted, free of charge, to any person obtaining a copy of this documentation to deal in the Documentation without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Documentation, and to permit persons to whom the Documentation is furnished to do so

I would hate to have to rely on their Wiki. Besides the fact that their Wiki is closed, I have found the ScummVM server to not be nearly as reliable as SHP's and since it is ScummVM generic, not only would we would have to dig through it to find the SCI related stuff, we would also have to dig through that to find the game development info.

There is a certain amount of arrogance in assuming that a community that has been around longer than the CABAL joke should fold and be assimilated into theirs just because they are the self proclaimed experts of all things Sierra, when they don't even seem to respect the opinions and desires of the traditional Sierra fans. This community has roots going back to the original MT forums, which may predate the ScummVM project. Even though I am currently hosting our Wiki on SHP, I very much consider it to be an extension of this community. I would like to keep it there until this has better hosting.

I understand that the impetus for the Sierra game creation forums on ScummVM came from the fact that AGI Games went down. They might have had the database from the original MT forum, but this for the most part has been the home of the SCI community. Before their forum change, some had posted about new SCI game development only to have some of the devs deride SCI as too primitive for anyone to waste their time with for a new game.

Sorry for the rant, but they are starting to tick me off.

[MusicallyInspired]

No I get you. I don't like their attitude either. I'm tired of the ScummVM team's need to have everything under their own roof. Their arrogance insisting that they know more about Sierra-related material than anybody else just because they did "the impossible" and added SCI into ScummVM is appalling. I'd rather keep this stuff "in the family" so to speak.

[Collector]

Agreed. Their attempts to bring it all together come off more as trying to control everything. It makes me want to have all of the AGI stuff here, too. I wish that someone here could get in touch with someone from AGI games. Even if a backup of the database was old, it should have most of the important stuff that we would want.

BTW, I Have finished adding the tutorial to the Wiki. I altered the style to math the Help file with the Studio syntax highlighting. If others could start looking it over to check for any mistakes. What do you guys think of adding a tools section to the Wiki so that everything can be cross referenced throughout the Wiki?

[gumby]

Agreed. Their attempts to bring it all together come off more as trying to control everything. It makes me want to have all of the AGI stuff here, too. I wish that someone here could get in touch with someone from AGI games. Even if a backup of the database was old, it should have most of the important stuff that we would want.

BTW, I Have finished adding the tutorial to the Wiki. I altered the style to math the Help file with the Studio syntax highlighting. If others could start looking it over to check for any mistakes. What do you guys think of adding a tools section to the Wiki so that everything can be cross referenced throughout the Wiki?

Again, agigames.com has a page on Facebook.  Does anyone here have a relationship with Chris Cromer who could contact him?

I like the idea of the tools section in the Wiki for cross-reference...  I find myself bumbling through multiple sites to find what I'm looking for.

As for ScummVM... (haven't read the thread there yet).  Do they think that we ripped it from them?  My view is that 2 copies is better than one (even if there might be *slight* discrepancies).  If the documentation had disappeared from the FreeSCI prior to ScummVM or us grabbing it and making it presentable (big thanks to Collector for the hard work), everyone would be screwed (similar to MT going down).  Let them get all worked up about it, I guess.  We haven't done anything wrong.

[MusicallyInspired]

Fingolfin came in and calmed everybody down, saying he's not against it. But he did point out that there are some things in the parser documentation that are out of date in our version.

[Collector]

I found a Wiki extension that doe automatic syntax highlighting. Of course there was no SCI support, so I hacked it in, using Studio's highlighting as a template. You can see it here:

http://sierrahelp.com/SCI/Wiki/index.php?title=Manipulating_the_Parser_-_Part_1_-_%27Complex%27_Nouns

You use it in lieu of 'pre' tags. For consistency in the Wiki, format any code like this:

Code: [Select]

<div class="CodeBlockHeader">Code:</div>
<div class="CodeBlockStyle"><syntaxhighlight lang="sci">code goes here
because it acts like <pre> tags it will preserve the code's formatting without adding nonbreaking spaces or line breaks.</syntaxhighlight></div>
This will make the code readable while editing it.

[MusicallyInspired]

I actually prefer Companion's syntax colors to Studio's. Can there be like a toggle?

[Collector]

I actually prefer Companion's syntax colors to Studio's. Can there be like a toggle?

The way the extension works it couldn't be easily done by choice of skin/CSS. All of the language info is contained in a language specific PHP file that I made for Brian's highlighting. I chose Brian's for constancy because of the inclusion of the Studio tutorial and help files. If Omni were to change Studio's highlighting to match Companions for his builds, We could distribute that instead and I would change the tutorial and help files accordingly. Of course if we are going to set a default SCI syntax highlighting, we could come to a consensus of what we want. For example, I prefer gray for comments so they don't visually dominate the code. Brian's comments almost overwhelm the rest of what is in the editor.

Edit: This should not prevent anyone from using the tag now. When we do come to a consensus the tags will reflect the changes in the modified sci.php file.

[MusicallyInspired]

Yeah, his comments are pretty brutal. Troflip's comments in companion are italicized and green. Much easier on the eyes.