From 2aefc48e99ae39a5427858ce44bfb625c51ac8db Mon Sep 17 00:00:00 2001 From: chaoskagami Date: Tue, 23 Sep 2014 00:02:32 -0400 Subject: [PATCH] Converting Format.vndc.txt to Markdown --- SCRIPTINGDOC.md | 311 ++++++++++++++++++++++++++++++++++++++++++++++++ TODO.md | 11 ++ 2 files changed, 322 insertions(+) create mode 100644 SCRIPTINGDOC.md create mode 100644 TODO.md diff --git a/SCRIPTINGDOC.md b/SCRIPTINGDOC.md new file mode 100644 index 0000000..3c9e9f4 --- /dev/null +++ b/SCRIPTINGDOC.md @@ -0,0 +1,311 @@ +VNDC Script format documentation +===== + +Functions: + 1. bgload + 2. choice + 3. cleartext + 4. delay + 5. if and fi + 6. goto and label + 7. jump + 8. music + 9. random + 10. setimg + 11. setvar and gsetvar + 12. sound + 13. text + 14. save + 15. debug commands + 1. help + 2. resume + 3. quit + 4. debugsave + 16. Save format + +BGLOAD +----- + +bgload sets a background image. + +bgload takes two arguments, one of which is optional. + + bgload bg [fadeout] + +The parameter 'bg' should be a file in backgrounds. + +The second parameter, 'fadeout', should be a length in frames to fade into the new background. + +The game always operates at 60fps. + +CHOICE +----- + +choice presents choices to the user on screen. + +` + choice ch1|ch2|ch3... +` + +Each choice is separated by a '|' (pipe) character. The result of the choice is stored into a variable named 'selected', which can be queried with if. + +Optionally, I implement an extension of this form: +` + choice ch1|ch2|... >var +` +Instead of storing to selected, 'var' will be used instead. + +CLEARTEXT +----- + +cleartext clears all of the text on-screen. + + cleartext [mod] + +A modifier can be specified with mod. This is supposed to be fadeout or something. + +Strangely, this command does not actually appear in the conversion of fate-stay night. + +Also, I ignore mod. It seems to be useless...maybe. + +DELAY +----- + +delay will sit around and wait a certain number of frames. + + delay frames + +'frames' is the number of frames to delay. Again, we operate at 60fps. + +IF AND FI (Control Flow) +----- + +Technically, two commands. if and fi are used for execution control. if the result of if is true, all statements are executed until a matching fi. + + if var op val + +'var' is a variable name. This can be a setvar, choice etc. + +op should be one of the following: + + < - less than + <= - less than or equal + == - equal + != - not equal + >= - more than or equal + > - more than + +I have no clue how many of these VNDS implements, but I do them all. + +----- + +fi simply ends an if statement. + +`fi` + +Note that I am a bit smarter than vnds here. `if` and `fi` CAN be embedded. So this is valid: + +` + if selected == 2 + if previous >= 5 + text 'You win!' + fi + if previous <= 5 + text 'You lose!' + fi + fi +` + +The behavior of VNDS would be to `'if previous <= 5'` on failure of `selected == 2`. This is really not proper: vnds just conditional jumps. Frankly, a jumpeq would be far more effective. I keep an if-count instead of an in-if bool value, so there's proper control flow. + +GOTO +----- + +goto finds a label and continues execution from there. + + goto label + +In my implementations, label is actually completely non-existent as a script command. Instead, goto finds labels by re-seeking through the file. + +Goto cannot jump to another file. That's not how it works. Use jump instead. + +JUMP +----- + +jump transfers control to another script file: + + jump script + +My implementation provides an extra form of jump: + + jump script [line] + +Which goes directly to line in the file. This is utilized for saving. As such, you can't turn off that extension. Period. + +MUSIC +----- + +music loads a audio file from sound, and plays it in a loop as music. + + music file + +You can pass '~' as file to stop playing all music like so: + + music ~ + +RANDOM +----- + +random saves a random number to a variable. + + random var low high + +low and high are the range the random number is in, inclusive. + +SETIMG +----- + +setimg displays an image from foreground at a position specified. + + setimage file x y + +G/SETVAR (variables) +----- + +setvar and gsetvar are used to set variables. gsetvar specifically sets the 'global' state, that is, common to all saves. In my implementation - that is moot. Thus, gsetvar just calls setvar. + +` + [g]setvar var mod value +` + +mod can be one of the following: + + `=` Set var to value + `+` Add value to var + `-` Subtract value from var + +Also, if value is not specified, you can also do this as the mod: + + `~` Reset to 0. + +One more thing that was not all over the place in vnds, but typically at the beginning. + +` + setvar ~ ~ +` + +Which means reset all vars. This ignores globals - e.g. prefixed with a lowercase `g`. + +As well, my extension provides the ability to set a variable to another variable. + +` + [g]setvar var op var2 +` + +Again, this only works in extensions mode. + +SOUND +----- + +sound plays a sound, and optionally a number of times. + +` + sound file [times] +` + +`times` is implicitly 1 if not specified. Pass -1 for infinity. + +You can do + +` + sound ~ +` + +To stop all playing sounds. + +TEXT +----- + +text is the meaty huge function. It outputs text, as you probably expect. + +` + text This is text dee doo... +` + +There are a bunch of variants with special meaning. I don't know why, but there are: + + `text` - (no params) Clear screen + `text !` - Wait for input and clear all. + `text ~` - Clears all text (like cleartext) + `text @...` - Don't wait for click after text is output. + +I've implemented a few extensions that help generally +with NVL games. + + `---` - At the beginning of a line, + clears before text output. + `"` - In the sound function + if lookahead finds a text + with quotes, it's assumed + that sound is a voice and + linked to the text. AKA + smart voice stopping. + +DEBUG +----- + +I've implemented a few debug commands to help out and just generally be useful (cheats? :P) + +Make sure you start up with the -b parameter, and start it from a console. Send it a SIGINT (^C). + +The console should now prompt you with this; + +` + [scr command] $ +` + +You can enter any command above; Some won't work right. choice probably won't work properly, because mouse is disabled. + +No commands run in this state will advance the program, but flags set will affect it. + +HELP +----- + +help will print everything available. + +RESUME +----- + +resume (renamed from stop) will disable debugging and kill the console. You can SIGINT again at any point to come back to the debug state. + +QUIT +----- + +quit sets the quit state - it's equivalent to ESC in the form of a console command. + +DEBUGSAVE +----- + +debugsave will save to a mandatory file specified; + + save file + +See section 15 for info on what the a save actually is. + +This function bypasses all checks. It just dumps it. You can write a save anywhere if you have write perms. + +SAVE FORMAT +----- + +Saves are actually a script generated by the save function. So, for example, this is a save: + +` + setvar selected = 2 + music bgm03.ogg + bgload qmrtb.jpg + jump fate01-00.scr 261 +` + +It restores any variables needed, loads the current music and bg, and jumps to the location we were previously at in the script. + +Saves should be loaded with the -s parameter until I get better gui stuff in place. diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..2babe54 --- /dev/null +++ b/TODO.md @@ -0,0 +1,11 @@ +What needs to be done +===== + + - Stop using dirty rendering completely. + - Make a better debug-console/menu system. + - Implement a proper save menu with highlighting. + - Also, op_choice. It's terrible and hackish. + - Change all direct SDL uses to call Zero instead - since that will be backend-independent. + - Rework op_text to use newlined buffers instead of dirty text renders + - After reworking op_text, make current text on-screen restored with saves + - Also, find an inventive way to save screenshots and current sfx. -- 2.39.5