User-submitted tutorials / How-To's

[Omni]

I hate recommending things I know I could do myself but the holidays are always busy for me so I will give a general thought process on the whole thing since I am lacking the time to create pages currently.

We need a comprehensive index with a listing of the main categories and a subsection in the index that leads to editing guidelines or best practices for when people update/change/add their own pages.

Links should be kept as a reference where applicable with a link link to the site on the way back machine for the broken/dead links if it has them.

Fangame listings should be summaries with all the games in a single page unless a game has enough information to warrant its own page. Walkthroughs would be their own page in a subsection in the game listings.

I believe Brians tutorials should be duplicated in the wiki if they have any room for improvement. My knowledge of the tutorial game and his tutorial is rather limited compared to others here so if it is hard to transfer or never ever changes or can not be improved upon then I would just link to it.

If I am not clear I will probably reread this in the morning and make adjustments as needed.

[gumby]

I have the Kernel functions section entered. It was a formatting headache. Could look it over to check it out? Just need that "SCI in action" section done, now.

Will do.  I'll grab some time today & see what I can contribute.  EDIT:  Okay, kernel functions page is completed, except for the broken links

The one thing that I would love is some 'master index' of topics, with links to where the actual content can be found.  Something that ties all the different tutorials together.  For example, 'Said() string syntax' might be a topic & under that would have a link (or maybe show all pages combined on a single page?) to Brian's contribution, Troflips, the FreeSCI page, etc.  That's what kills me now, I end up having to go into multiple pages strewn hither-and-yon to find what I need.

[Collector]

It would be good to have it arranged and linked in some kind of logical, cohesive way. That is part of the point of doing it in a Wiki. I do think we need to concentrate first on gathering all of the information before anything more disappears. I expect the Free SCI site to not be around much longer. Is there anything else on their site that we should get?

Omni mentioned the Web Archive, but this is of limited use. The main thing that would be what we would want to get is the SCI forum of the MT board and forums are never archived at any usable level. Most of the threads are inaccessible and the rest are incomplete. It would probably be more productive to contact an admin of the AGI Games site if they have a backup of the board's data base. I could setup a temporary SMF board to import it into so we could grab the info in the threads. Of course it would be missing any images or files, but the info would be there.

Does anyone know how to contact an admin from the MT board?

[gumby]

It would be good to have it arranged and linked in some kind of logical, cohesive way. That is part of the point of doing it in a Wiki. I do think we need to concentrate first on gathering all of the information before anything more disappears. I expect the Free SCI site to not be around much longer. Is there anything else on their site that we should get?

The source code for the FreeSCI project is there too - maybe get that?
http://freesci.linuxgames.com/?page=download

Omni mentioned the Web Archive, but this is of limited use. The main thing that would be what we would want to get is the SCI forum of the MT board and forums are never archived at any usable level. Most of the threads are inaccessible and the rest are incomplete. It would probably be more productive to contact an admin of the AGI Games site if they have a backup of the board's data base. I could setup a temporary SMF board to import it into so we could grab the info in the threads. Of course it would be missing any images or files, but the info would be there.

Does anyone know how to contact an admin from the MT board?

agigames.com has a page on Facebook.  Looks like Chris Cromer is the admin.  Anyone want to try to contact him (I'm not on Facebook...)?

[Collector]

Why not, but I'm not sure what good the Free SCI source would do us. Perhaps for the SCI Studio development? Better to get it and not need it than not and find out later that it would have been of use.

[MusicallyInspired]

There's some SCI sound documentation by Ravi I believe that would be a swell addition:

SCI Sound Resource Format (incomplete)                             Revision 2
Ravi I.                                                          Jan 16, 1999


Preface

   The sound resource is basically just a MIDI file. Much of what I write
   here comes from outside documents, and I would direct anyone seeking
   further information to various MIDI specifications. There are quite a few
   floating around - I leave it to the reader to find individual documents.

   Some people prefer the one-based numbering system for channel and program
   numbers. I personally prefer the zero-based system, and use it here. If
   you're familiar with channels 1-16, be aware that I will call them 0-15.
   My intention is not to be deviant from other programs but to be more
   accurate in representing the way information gets stored. The same is true
   for programs 0-127 as opposed to 1-128.

   Sierra may have changed its sound file format in the switch to SCI1.
   Resources extracted from "Quest for Glory II" (which uses the odd
   in-between engine) will not strictly follow this specification. I haven't
   had a chance to look at true SCI1 files yet, but will when I can. For now,
   I refer only to SCI0 sound files. Games which are known to follow this
   specification include:
      Conquests of Camelot
      Hero's Quest I (Retitled Quest for Glory, but I only have the original)
      King's Quest IV

   Please post comments or questions to the SCI webboard:
      http://www.InsideTheWeb.com/mbs.cgi/mb173941


About the output medium

   The output medium (Adlib, MT-32, PC Speaker, etc.) greatly affects the way
   music will sound. They may even affect the way sound resources get used.
   Not having anything else, I can only play sounds with the Adlib and PC
   Speaker drivers. I'd like to get my hands on an MT-32 firstly because it
   would make the music sound quite a bit better and secondly because I think
   Sierra's composers might have used them.

   I have not yet tried to create sounds which play out the PC speaker. My
   suspicion is that either the header specifies which channel should be used
   for speaker output or the speaker always plays a certain channel. I have
   been able to create sounds which play with an Adlib or compatible. If
   other devices do not play sounds correctly, I'd appreciate it if people
   with them could do some byte twiddling to help me figure out why.

   Another issue to deal with in the output medium is the fact that the same
   song may exist in two different files. In Conquest for Camelot, the
   version of the title music which gets played by an Adlib is in sound.001.
   The speaker version is in sound.201. The speaker version will play on the
   Adlib (with more than one channel, I might add) but the Adlib version will
   not play on the Speaker. While I haven't looked at patch files yet, I
   think that different mediums have their own instrument format as well.


First two bytes

   The first two bytes in an extracted sound file (they aren't actually part
   of the resource) will be 84h 00h. This is the resource type OR-ed with 80h
   and stored as a word.


Header

   The header is 33 bytes long. The format appears to be:
      byte - always 0
      2 bytes - initialization for channel 0
      2 bytes - initialization for channel 1
      .
      .
      .
      2 bytes - initialization for channel 15

   The first byte is zero for every extracted file I've seen. Changing it
   makes the sound resources I tested not play. Perhaps this is a format
   version number: if Sierra wanted to expand the sound resource, they would
   increment this byte to signal the player that it won't recognize the file
   and should not try to play it.

   After the first byte, each channel gets two bytes of initialization. The
   first byte seems to initialize controls 4Bh and 4Eh (see command Bx).

   The second byte's function is unknown.


Events

   The actual music is stored in a series of events. The generic form for an
   event is:
      <byte - delta time> [byte - status] [byte - p1 [p2]]

   Delta time is the number of ticks to wait after executing the previous
   event before executing this event. Standard MIDI stores this as a variable
   length value. In sound resources, it will be exactly one byte and the most
   significant bit is in fact used as part of the value.

   The status byte is basically a command. The most significant bit is always
   set. This feature is important because the status byte will not always be
   present. If you read a byte expecting it to be a command but the most
   significant bit is not set, that byte is actually a paramater and you
   should repeat the last status byte used. This is know as running status
   mode and appears to get used relatively often.

   There generic form for a status byte is (in bits) 1xxxcccc - The lower
   nibble designates which channel the command affects. The upper nibble is
   the command, but as stated earlier, the most significant bit must be 1.
   That leaves space for 8 commands, most of which require at least one
   paramater. Paramaters will never have their most significant bit set as a
   way of distinguishing them from status bytes.


Status reference

   8x n v - Note off: Stop playing note n on channel x, releasing the key
            with velocity v. If a hold pedal is pressed, the note will
            continue to play after this status is received and end when the
            pedal is released. Note 60 corresponds to middle-c on a keyboard,
            but the patch selection can change the actual pitch. Often, a
            zero-velocity note on gets used instead of a note off.

   9x n v - Note on: Play note n on with velocity v on channel x. Note 60
            corresponds to middle-c on a keyboard, but the patch selection
            can change the actual pitch. The velocity is the speed with
            which the key gets pressed, which basically means how loud the
            note should be played. Playing a note with velocity 0 is a way
            of turning the note off.

   Ax n p - Key pressure (after-touch): Set key pressure to p for note n on
            channel x. This is to modify key pressure for a note that is
            already playing.

   Bx c s - Control: Set control c to s on channel x. This can be confusing
            because there isn't just one meaning. Changing the settings on
            different controls will, of course, have different outcomes.

            Controls which handle any value are continuous controllers. They
            have a continuous range. Controls which are only on/off are
            switches. Their defined range is only 01h (OFF) and 7Fh (ON).
            However, in order to respond to all values, 01h-3Fh is treated as
            OFF and 40h-7Fh is treated as ON. While in practice they may only
            use bit 6 as a flag, my personal opinion is that values between
            01h and 7Fh should be avoided for the sake of clarity.

            Common controls seem to be 07h, 0Ah, 40h, 4Bh, and 4Eh.

            Control Refrence (tentative)

               07h - Volume: Set the volume. This is a continuous controller
                        where a value of 00h is muted and a value of 7Fh is
                        loudest. There is a wide range of recorded values.

               0Ah - Panning: Set the pan. This is a continuous controller
                        where 00h is hard left, 40h is center, and 7Fh is
                        hard right. There is a wide range of recorded values.

               40H - Hold 1 Pedal: This is a switch that defines the state of
                        the hold pedal. When ON, the pedal is pressed. When
                        OFF, the pedal is not pressed. When the pedal is
                        pressed, notes continue to play after a key is
                        released. The notes will then stop once the pedal is
                        released. Recorded values are 1 and 127.

               4Bh - Polyphonic / monophonic: The value determines the number
                        of voices which may be played at once on the channel.
                        Recorded values are 0, 1, 2, 4, 6, and 8. This seems
                        to be a non-standard control.

               4Eh - Unknown: I had originally thought this control was some
                        sort of volume enable. A non-zero will allow volume
                        to be determined on a per-note basis with the
                        velocity paramater to command 9x while a zero value
                        means the channel will play at channel volume
                        regardless of the velocity paramater. This doesn't,
                        however, seem to be the case. Its odd interactions
                        with control 4Bh make me suspicious that it might be
                        some parallel to omni mode. Recorded values are 0 and
                        1. This seems to be a non-standard control.

   Cx p - Program change: Set program (patch / instrument / ect.) to p for
          channel x. This is a simple instrument change.

   Dx p - Pressure (after-touch): Set key pressure to p on channel x. This is
          similar to Ax but differs in its scope. Command Ax is applied on a
          per-note basis while command Dx is applied to an entire channel.

   Ex t b - Pitch wheel: Set the pitch wheel to tb. The setting is actually
            a 14 bit number with the least significant 7 bits stored in b
            and the most significant 7 bits stored in t. (Remember the top
            bit can't be used for either byte.) The range of settings is
            0000h to 3FFFh. A setting of 2000h means the pitch wheel is
            centered. Larger values raise pitch and smaller values lower it.

   FC - The only command I've seen which starts with F is FC and that denotes
        the end of a file. Note that the lower nibble does not signify a
        channel.


Revision history

   Revision 2 - Jan. 16, 1999
      - Got rid of the HTML. I originally intented to post this as a message
        on the webboard, but ended up distributing the file. If I'm going to
        distribute it as a file, there's no need to bother with the HTML
        since I can do all my formatting as plain text.
      - I found refrences to command 8x in the 1988 Christmas Card, so my
        comment about not seeing one got removed. To date, I haven't seen any
        examples of commands Ax or Dx.
      - Expanded the header section.
      - Added information about controls.
      - Added information about the output mediums.
      - Tried to be more consistent with terminology

   Revision 1 - Dec. 29, 1998
      - First release of the specification

Here's some fanmade SCI drivers documentation which might have some good information: http://sierra.voyd.net/

[Collector]

Feel free to add Ravi's stuff. I am aware of the sierra.voyd.net site, but it seems to be mostly about his drivers and not much about SCI specifically.

[MusicallyInspired]

Looks like it's already there and much newer than mine. Excellent. Though, it is incorrect. Ravi says that KQ1 SCI is the only game he knows of that has digital sound effects and that's not true. SQ3, KQ1, QFG2, and a handful of other SCI0 games also have digital sound effects.

EDIT: Would Wiki-ifying the entire SCI Studio Help file be feasible?

[Collector]

Go ahead and make any corrections you see that need to be made. Just comment out the original and notate it.

[MusicallyInspired]

I'm brand new to Wiki. Can you explain that a little more? How do I notate it?

EDIT: I did something, let me know if I did it correctly.

[Collector]

The Wiki will accept some HTML code, so commenting is the same

Code: [Select]

<!-- text inside these tags will not be seen -->
This can be used to hide, but keep the original text with the page. The Wiki software tracks changes, however, commenting out the original text will keep it where it was. I think that the Free SCI document and Brian's tutorial are the only things that we should do this with. The Wiki tracking is fine for everything else.

By the way, it will accept the HTML tag for line break. Probably should use the XHTML version:

Code: [Select]

<br /> since it generates XHTML code. I put  links to WikiMedia formatting, linking and tables how tos on the main page.

I have still to work out citations and footnotes, but if I don't have much success, I'll just set named anchors to link to.

[Omni]

Hoping someone from Freesci sees this.

Which is most up to date 

http://www-plan.cs.colorado.edu/creichen/freesci/freesci.pdf (July 5, 2007)

or

http://freesci.linuxgames.com/scihtml/book1.html

[Omni]

Err, Upon further examination it appears the website is just as up to date as the pdf minus the table of contents. The table of contents does not appear to link to all the pages.

[gumby]

Hoping someone from Freesci sees this.

Which is most up to date  

http://www-plan.cs.colorado.edu/creichen/freesci/freesci.pdf (July 5, 2007)

or

http://freesci.linuxgames.com/scihtml/book1.html

Good question.  I did find a few inconsistencies, but nothing conclusive.

[gumby]

EDIT: Would Wiki-ifying the entire SCI Studio Help file be feasible?

Yes.  Collector - could you please add a link under the left-navigation pane to include the heading 'SCI Studio Help Files'?  I can't seem to to figure out how to edit that...  content from here (at least that's where I found it, ): http://sierrahelp.com/Files/Utilities/SCITools/SCI%20Studio%203/SCI_Studio_3_Help_Files.zip