From 7f6002caba3f0a6749820c2772161caf55b8d267 Mon Sep 17 00:00:00 2001 From: neonloop Date: Fri, 7 May 2021 20:00:12 +0000 Subject: Initial commit (uqm-0.8.0) --- doc/devel/script | 117 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 doc/devel/script (limited to 'doc/devel/script') diff --git a/doc/devel/script b/doc/devel/script new file mode 100644 index 0000000..07dbf0f --- /dev/null +++ b/doc/devel/script @@ -0,0 +1,117 @@ +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) -- cgit v1.2.3