SCRIPT CONVENTIONS ------------------ The .txt files in the content/comm directories are unlikely to stay in their current form forever, as it's a rather fragile format. However, in the the meantime, and for those who seek to edit the script files (to conform to 3DO, PC, and/or director's cut versions). This file will describe the format, and how it relates to the source code in the src/sc2code/comm directory. The .txt files -------------- The text files should all have a set of records, optionally separated by newlines. Each record has a header, then one or more lines of text. The header is a hash (#), an identifier in parentheses, and (if it's an alien voice) a tab, then the name of the file corresponding to that voice. Alien voices have identifiers in ALL_CAPITAL_LETTERS, while Zelnick's lines are in_lower_case. Often one line is broken into several parts - in these cases the full line is knitted together by the communications code (usually inserting the name of the Captain, or the flagship, or whatever). A modest example: #(HAVING_FUN_WITH_ILWRATH_2) thrad103.wav The exploding starships! The screaming crew! The direct hits, the cunning escapes! These are the moments we live for! Now we must return to the great battles! Farewell, Great Teacher. Zelnick's lines must be ON ONE LINE ONLY; line breaking is handled by the communication code and anything after the first newline is IGNORED. So don't do it while repairing his lines, and if you find one (a lowercase id with multiple lines following it) delete the newlines and make it all one line. It appears that newlines may appear in the middle of speeches; however, most of the lines by aliens have pauses represented by a single space or tab. It seems reasonable to duplicate this. When multiple records are used to define a single speech line (as often happens when they say your name, for instance), only the first line has an audio file associated with it. Lines that do not end in a punctuation mark or a space have a "..." added to the end of them by the communications code. If the previous line had "..." appended to it and this line does not START with a space, this line will have "..." prepended to it. The "scriptcheck" tool looks for all cases where "..." does not occur in midsentence. When editing the script files, check your intended results against this. The .h files (src/sc2code/comm) ------------------------------- Each race has its own directory in src/sc2code/comm, and there is a file marked strings.h in each directory. This file defines a single enum which should list every record identifier in the appropriate race's .txt file over in content/comm/{race}, IN THE PRECISE ORDER THOSE RECORDS ARE GIVEN. Due to the non-symbolic nature of C, there is no relation whatsoever between the identifiers in the record and in the enum (though it would be reasonably straightforward to generate the strings.h files from the .txt files) The values of the enum are used in the {racec}.c files in the same directory. The scriptcheck utility also checks for proper correlation between the .h file and the associated .txt file. It assumes that one enum value is listed per line, and that the general format of the file matches the current one. Types of script bugs -------------------- Script bugs can fall into three broad categories. - Voice/Speech mismatch. These are easy. The wrong audio file is associated with this clip. Merely change the clip to make it fit. If a clip is expected but is not specified, this appears to crash the game. Example: The Zoq-Fot-Pik's "Goodbye Captain." "See ya." lines had no clips associated with them, which both caused the game to loop forever on those lines and misaligned all clips after that so that the voices did not match the subtitles. - Subtitling error. These are also easy. The voice and text more or less match, but the phrasing is slightly different. This is also easy. Change the text to match. If the speech is *wildly* different, make sure that it's not a misfiled audio file. NOTE: The PC and 3DO versions had slightly different texts, and the texts we are working with here match neither one. The voices are to be taken as the ultimate authority on the 3DO text. - Communications Logic errors. Basically, this means the enum in the appropriate strings.h was defined wrong, or, worse, was misused by the {race}c.c file. One fixed example was the Spathi Ruling Council (Race name: spahome), where strings.h defined *two* enums, one for the Captain's lines, one for the Spathi. This would have horribly garbled everything were it not for the fact that it made their initial challenge and your responses invalid, thus causing the game to lock up on your first visit. An example of one of these that made it into the final game (PC version, anyway) is when the Umgah are trying to reward you as Great Hero - the responses for the "I act purely from largesse" and "Yep! You guys owe me BIG time" are clearly reversed. No decision has yet been made on how to handle these (whether to reproduce them precisely, or fix them, or only fix them in a "director's cut" which would presumably require input from the director) so leave them alone for now unless they crash the game. (To my knowledge, the only truly serious error of this type was the Spathi Homeworld, which has since been repaired.) (Initial version: Michael Martin, 10/10/02)