From b23bc921706a467116992fc24c13fba7eb8e867a Mon Sep 17 00:00:00 2001 From: Jon Feldman Date: Tue, 23 Sep 2014 00:27:06 -0400 Subject: [PATCH] Update SCRIPTINGDOC.md --- SCRIPTINGDOC.md | 190 ++++++++++++++++++++++++------------------------ 1 file changed, 93 insertions(+), 97 deletions(-) diff --git a/SCRIPTINGDOC.md b/SCRIPTINGDOC.md index 906094c..78df82f 100644 --- a/SCRIPTINGDOC.md +++ b/SCRIPTINGDOC.md @@ -2,91 +2,87 @@ 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 + 1. `bgload` + 2. `choice` + 3. `cleartext` + 4. `delay` + 5. `if , fi` + 6. `goto , label` + 7. `jump` + 8. `music` + 9. `random` + 10. `setimg` + 11. `setvar , gsetvar` + 12. `sound` + 13. `text` + 14. `save` 15. debug commands - 1. help - 2. resume - 3. quit - 4. debugsave + 1. `help` + 2. `resume` + 3. `quit` + 4. `debugsave` 16. Save format BGLOAD ----- -bgload sets a background image. +`bgload` sets a background image. -bgload takes two arguments, one of which is optional. +`bgload` takes two arguments, one of which is optional. bgload bg [fadeout] -The parameter 'bg' should be a file in backgrounds. +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 second parameter, `fadeout`, should be a length in frames to fade into the new background. Currently, this just calls delay. -The game always operates at 60fps. +The game always operates at 60fps. Or, the logic is limited to 60fps. CHOICE ----- -choice presents choices to the user on screen. - +`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. +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. +Instead of storing to a default variable named `selected`, the name specified at `var` will be used instead. CLEARTEXT ----- -cleartext clears all of the text on-screen. +`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. +Strangely, this command does not actually appear in the conversion of fate-stay night and other games. -Also, I ignore mod. It seems to be useless...maybe. +Also, I ignore `mod`. It's the delay in drawing text, and until I am capable of fading the letters in individually, it won't be implemented. DELAY ----- -delay will sit around and wait a certain number of frames. +`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. +`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. +Technically, two commands. `if` and `fi` are used for execution control. If the result of an `if` statement 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. +`var` is a variable name. This can be a value set through `setvar`, `choice`, etc. previously. -op should be one of the following: +`op` should be one of the following: < - less than <= - less than or equal @@ -95,15 +91,15 @@ op should be one of the following: >= - more than or equal > - more than -I have no clue how many of these VNDS implements, but I do them all. +I have no clue how many of these VNDS implements, but I do them all because they are useful. Additionally, you can use two variables or two values. My implementation doesn't care about order with rvals and lvals. ----- -fi simply ends an if statement. +`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: +Note that I am a quite a bit smarter than vnds here. `if` and `fi` CAN be embedded. So this is valid: if selected == 2 @@ -116,178 +112,178 @@ Note that I am a bit smarter than vnds here. `if` and `fi` CAN be embedded. So t 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. +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` sort of command would be far more effective and descriptive. 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` 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. +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. +`goto` cannot jump to another file. That's not how it works. Use `jump` instead. JUMP ----- -jump transfers control to another script file: +`jump` transfers control to another script file: jump script -My implementation provides an extra form of jump: +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. +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` 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: +You can pass `~` as file to stop playing all music like so: music ~ RANDOM ----- -random saves a random number to a variable. +`random` saves a random number to a variable. random var low high -low and high are the range the random number is in, inclusive. +`low` and `high` are the range the random number is in, inclusive. SETIMG ----- -setimg displays an image from foreground at a position specified. +`setimg` displays an image from foreground at a position specified. setimage file x y +Note that vnds uses a rather odd concept of coordinates. They're nintendo DS based. I will add a number format specifier at some point for the simple reason of more precision. + 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. +`setvar` and `gsetvar` are used to set variables. `gsetvar` specifically sets the 'global' state, that is, common to all saves. In my implementation - global is moot. Thus, `gsetvar` just calls `setvar`. setvar var mod value gsetvar var mod value -mod can be one of the following: +`mod` can be one of the following: - `=` Set var to value - `+` Add value to var - `-` Subtract value from var + = 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: +Also, if `value` is not specified, you can also do this as the `mod` value: `~` 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. - +As well, my implementation 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` 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 - +You also can do sound ~ - To stop all playing sounds. TEXT ----- -text is the meaty huge function. It outputs text, as you probably expect. - +`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. + 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. + +SAVE +----- + +`save` saves the game to a mandatory file. + + save file -I've implemented a few extensions that help generally -with NVL games. +For save format, see `debugsave` and save format information at the end. - `---` - 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. +Unlike `debugsave`, this file is saved in a directory. 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). +Make sure you start up with the `-b` parameter, and start it from a console. Send it a SIGINT (`Ctrl+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. +You can enter any command above; Some won't work right. `choice` definitely 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. +`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. +`resume` (renamed from `stop` in super-early builds) 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. +`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; +`debugsave` will save to a mandatory file specified; - save file + debugsave file See section 15 for info on what the a save actually is. @@ -307,4 +303,4 @@ Saves are actually a script generated by the save function. So, for example, thi 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. +Saves should be loaded with the `-s` parameter until I get better gui stuff in place. -- 2.39.5