v 1.5 2017 12 25 update with html-bootstrap format, missing format for section 8
v 1.4 2015 09 23 update with netplay, variable framerate
v 1.3 2015 02 19 update with game flow, newer state controllers and functions
v 1.2 2014 12 30 update with additions, updated with index
v 1.1 2014 11 07 update with changes
v 1.0 2014 09 12 creation of the documentation file
this is the programmer's documentation for the "pantsu of rage" engine.the engine runs at 60gfps, is coded using the monogame framework.the engine makes a lot of use of json to optimize load/development times so if you re not familiar with json make sure to read on it, the document assumes you already know json so json specific explanations will be ommited, you can refer to the following webpages for more information about json
http://json.org/the engine refers to the elements as objects, the object hierarchy is the following:
there are also object containers which follow the following hierarchy:
the folder structure of the engine is:
the animation file contains an array of animation objects, each animation object has an id and an array of animation frames:
an animation frame contains several parameters that specify how to cut the frame from the sheet, how to draw it and an array of collision boxes:
a collision box contains it's size, location and how it will handle it's collison logic.
the objects are loaded based on an id (the id is a string with the name of the object) the engine loads the configuration file that is named the same as the object's id, so if the object is "foo.player", the file foo.player which contains the player's configuration is loaded. the configuration file contains the following sections.
example:
foo.png is used in the animation file , the line:
"_palettes": [[["foo.png","foo.png"]],[["foo.png","foored.png"]],[["foo.png","foogreen.png"]]]
means that for palette index 0 the animation frames that use foo.ong should reference foo.png, if the palette index is 1 the animation frames that reference foo.png should reference foored.png, same for index 2 and foogreen.That means that we can change the whole sprite look and not just it's colours.
the code runs on a state machine, you can load multiple script files per object, each script file contains a list of states. there are three types of states : current, before and after, current states are states whose code is executed only when the character is in that specific state, the before type states are all executed before the current state, the after states are executed after the current state.
A state is made of two sections, the state's variables and the state controllers, the state variables are used when the object changes to that state normally to set object internal variables.
Normally current type states are used to depict a character's movelist, while the previous type states are used to change from one state to other by putting all state logic in a single place, after type states are used to perform aditional checks.
example of a state: "_id": "stand", "_type": "current", "_moveType": "idle", "_physicsType": "stand", "_animation": "stand", "_controlLevel": 1, "_velX": 0, "_velY": 0, "_velZ": 0, "_landAutomatically": false, "_faceEnemy": true, "_stateControllers": [ { "_type": "changeState", _parameters : [ {"_name": "state", "_value": "'walk'","_valueType": "string"}, {"_name": "or", "_value": "_commandEquals('holdForward') || _commandEquals('holdDown') || _commandEquals('holdUp') ", "_valueType": "boolean" } ] } ]
there are several different types of state controllers, those are used to script the logic of the object, they normally consist of a type and a list of parameters, the type specifies what does teh satte controller actually does and the parameter can be divided in two types, condition parameters (and, or) and value parameters, the condition parameters tell the engine when to execute the state controller while the value parameters are values used by the state controller.
state controllers have a parent child hierarchy, used to inherit certain parameters and make the code more manteainable.
state parameter
the state parameter has the following fields
* certain parameters of certain state controllers do not support yet expressions in the value of their parameters.
an important type of parameters are the and and or parameters; both are of boolean type. they are used to know when is a state controller executed, all the and type parameters must evaluate to true for the state controller to be executed. the or type parameters only need one of them to be evaluated as true for the state controller to be executed. if there are no and type parameters in the sctrl the and condition is evaluated to true, if there are no or type controllers the state parameter is evaluated to false.
This is a list of state controllers, their effect on the game engine and the parameters they utilize.
these two must be used as a pair; all the state controllers after an executeConditionStart state controller and before an executeConditionEnd state controller are considered a block; if the executeConditionStart is evaluated to false the block is not executed, if executeConditionStart evaluates to true the block is executed, the executecondition pairs can be nested.
parameters:
it is always executed, does not support expressions
it ends the current state sending the character to the stand or crouch state depending on the physics type.
parameters:
supports expressions, it's executed when it evaluates to true
changes the current state of the object.
parameters:
supports expressions, it's executed when it evaluates to true
changes the type of physics of the object, it also performs friction and acceleration setting depending on the physics type.
parameters:
supports expressions, it's executed when it evaluates to true
changes the position of the object.
parameters:
supports expressions, it's executed when it evaluates to true
changes the velocity of the object.
parameters:
supports expressions, it's executed when it evaluates to true
sets the value of a variable; this state controller is a special case as there are no fixed parameter names and and and or, the parameter name indicates the name to give the variable to be set, you can use this to set more than one variable per state controller.as of version 1.0 of this document only single variables are supported, no list types.
parameters:
supports expressions, it's executed when it evaluates to true
changes the facing of the object; only the X coordinate is affected by the facing, the controls and graphics facing can be changed separately.
parameters:
supports expressions, it's executed when it evaluates to true
changes the side the object, normally you need to be on a different side to another object for you to be able to hit it.
parameters:
supports expressions, it's executed when it evaluates to true
destroys a projectile with the specified id, 'self' is a special value which destroys the current object assuming it's a projectile.
parameters:
supports expressions, it's executed when it evaluates to true
creates a projectile, a projectile can use the engine's hardcode bynot specifying state parametersbut it's recommended to create it's own states to have better control over it's behaviour. there is a hardcoded behaviour for reflected projectiles but a customized one can be created as well.
parameters:
it is always executed, does not support expressions
it creates a hit definition and adds it to the hitDefinitions list, the hit definition is used by the collision boxes with a hit parameter of true to attack players of the opposing side.
parameters:
the next sub-section is the hitspark subsection
supports expressions, it's executed when it evaluates to true
signals the engine/scene to end the intro state of the character
parameters:
supports expressions, it's executed when it evaluates to true
signals the engine/scene to end the win state of the character
parameters:
supports expressions, it's executed when it evaluates to true
signals the engine/scene to end the lose state of the character
parameters:
supports expressions, it's executed when it evaluates to true
changes the animation to the specified animation
parameters:
supports expressions, it's executed when it evaluates to true
creates an effect onscreen
parameters:
supports expressions, it's executed when it evaluates to true
adds a value to the current position, takes facing into account as well as stage limits.
parameters:
supports expressions, it's executed when it evaluates to true
changes the frame that is currently being shown without chaning the animation
parameters:
supports expressions, it's executed when it evaluates to true
changes the power of the character, can be used to add to the power
parameters:
supports expressions, it's executed when it evaluates to true
changes the life of the character, can be used to add to the life
parameters:
supports expressions, it's executed when it evaluates to true
changes the scene of the current game mode
parameters:
supports expressions, it's executed when it evaluates to true
for menu type scenes, it fires the event of the menu items that is currently selected.
parameters:
supports expressions, it's executed when it evaluates to true
it selects a character for a specific player, can be used in the script of complicated selection screens/menus
parameters:
supports expressions, it's executed when it evaluates to true
It changes the current game mode to a different one
parameters:
supports expressions, it's executed when it evaluates to true
changes the parameter of an effect, the id is mandatory so the parameters of the efect with that id are changed
parameters:
supports expressions, it's executed when it evaluates to true
destroys an effect so it stops being drawn, the id is mandatory
parameters:
supports expressions, it's executed when it evaluates to true
It changes the current game mode's scene to the first one in the list,
parameters:
supports expressions, it's executed when it evaluates to true
creates a simple text message
parameters:
supports expressions, it's executed when it evaluates to true
creates a dialog box, the dialog box has a set width and height so word and linewrap can be used for it,
parameters:
supports expressions, it's executed when it evaluates to true
creates a popup menu, the way to do it is calling a .scn menu type scene on it's parameters
parameters:
named parameters are a special case, similar to the setVariable state controller, named parameters are pased to the pop up menu so it can receive the data from the script. example:
{"_name": "source", "_value": "'yesnomenu.scn'", "_inherit": null, "_valueType": "string"}, {"_name": "question", "_value": "'do you want to stop on this cutscene?'", "_valueType": "string"},
this code is part of a create menu sctrl, in the yesnomenu.scn scene we have the following menuItem
{"_id":"question", "_type": "text", "_label": "_defaultText('question')", "_posX":0, "_posY":0, "_event":"null", "_eventData":"null", "_restrictInput":10000, "_selectedColor":"255,0,0,255", "_unselectedColor":"255,255,255,255"}
in the default label the use the _defaultText function of scenes, that one searches for the question parameter and shows it's value; that way we can recycle the yesnomenu.scn in multiple instances (as a side note, a value of 10 on _restrictInput , means that only player11 can select this menu, thus making the text effectively work as a label as it becomes unselectable )
supports expressions, it's executed when it evaluates to true
changes the descriptor of the current move, it's used for the ai to learn which move is being used as an optimization against using the animation adn animation frame
parameters:
supports expressions, it's executed when it evaluates to true
Plays a sound , the sounds can be buffered by the scene
parameters:
supports expressions, it's executed when it evaluates to true
changes the parameters of a sound, uses the id to modify it
parameters:
supports expressions, it's executed when it evaluates to true
Stops a sound from playing
parameters:
supports expressions, it's executed when it evaluates to true
normally inputs (button presses, sequences) are buffered for a specific amount of game ticks, this state controller makes it so the buffer does not decrease while this sctrl is active, as an example it's used in jump start so the comands are buffered and executed once you have left the ground.
parameters:
supports expressions, it's executed when it evaluates to true
creates a layer based on the object's layer buffer/config, the layer is overimposed on the character
parameters:
supports expressions, it's executed when it evaluates to true
destroys a layer with the existing id
parameters:
supports expressions, it's executed when it evaluates to true
Sets the value of a game variable; this state controller is a special case as there are no fixed parameter names sand and and or, the parameter name indicates the name to give the variable to be set, you can use this to set more than one variable per state cdontroller.as of version 1.0 of this document only single variables are supported, no list types.
parameters:
supports expressions, it's executed when it evaluates to true
saves all the game variables to a file, the variables to save and the file they get saved to are configured in the scene's code.
parameters:
supports expressions, it's executed when it evaluates to true
changes the value of a property of a menu item
parameters:
the expressions are used in the engine to determine the value of certain parameters, based on internal varibales from the engine/object.examples of expressions are:
_commandEquals('2qcfX') && controlLevel == 1 && physicsType != 'air' && power >= 1000
posY > 0 && velY > 0
the expressions consist of operators, static values, variables and functions, the parenthesis are a special operator that is used to adjust precedence, the variables can be custom variable screated with the setVariable state controller or internal variables of the object. a logical value of true equal an int value of 1 , a logical value of false equals an in value of 0, in reverse only 0 is read as logical false while any value different to 0 is treated as true by the logical operators. the value type returned by an operator depends on the value type of the operands and the operator itself.
The operators are ordered by precedence from lowest to highest, most operators are the same as they are in standar programming languages.
variables start with any letter or a . character and the rest of the variable's name can be any letter , any number or the . and _ characters, certain variable names are reserved as internal variables:
functions start with the _ character, then comes the function name, then the parameters between parentheses, functions return a single value to be used in expressions
to debug you need a debug build , the debug keys are:
the debug console is there so you can edit the animation timings or the state controller parameters:
first it asks you to edit whether to edit animation or code
second it asks you the id of the animatino/state to edit
if you are editing an animation you ahve to choose the frame to edit, then you edit the timing of said frame
if you are editing the state code you have to choose the state controller and then the parameter, once you do that you type v to edit the parameter's value
once you are done editing, typing "s" in the prompt saves the anim_ or code_ file with the adjustments
GameMode this is a general cointainer for the game flow, there are different game types. Game mode configurations are saved in the modes subfolder inside the content folder a game mode has variables, named game mode variables _id [string ] this is the id for the game mode, used to identify it _mode [string] this is the game mode type, the possible values are: arcade versus aivsai training any other value a generic game mode is loaded, it behaves mostly as a menu most of the differences between game modes are in how sides are handled while selecting the characters _sceneList [string list] this is the list of scenes that the game mode will load, it starts at the first scene then goes to the next scene when a sceneOver event is fired _controlsNo [int] this is the number of human controls that the game mode will read, it's used mostly to tell apart 1p and 2p modes, also to restrict the menues to a certain amount of players _playersNo [int] the amount of players to create, usually 1 for arcade/hisotry game modes 0 for ai vs ai modes and 2 for versus or cooperative modes _aisNo [int] the amount of ais to select/carry as partners or to use in training mode _saveFile [string] the file in which to save the gamemode variables, common examples of game variables are the key input and the screen resolution _loadFile [string] the file from which to read the game mode variables Game Variable _name [string] the name of the variable _value [string] the value fo the variable, it is the default value when a file is read and the varaible does not exist in it _type [string] the variable type: int, float, string, boolean Scene this is a scene, multiple scenes make a gamemode , most of the scenes will be stages or menus, their configuration fiels are saved in the scenes folder: _id [string] this is the id for the scene, used to identify it _type [string] this is the scene type, the possible values are: stage this is an interactive/fighting scene menu the scene is a configurable menu, it creates menu items based on the _menuItems data cutscene this is a cutscene _background [string] this is the configuration file for teh background object, located in the objects subfolder _orientation [string] this is the orientation of the menu, it's possible values are: vertical the menu items are selected up to down horizontal the menu items are selected left to right rectangular the menu items are a square, pressing left or right right changes items 1 by 1, pressing up or down changes the row, so the selected menu item changes depending on the amount of columns, _disableAfterSelectingCharacter [boolean] if set to true disables the menu control once a character has been selected, mostly used for versus mode so a player can only select one character _rows [int] used for rectangular type menus, it's used to indicate how many rows of menuItems will the menu have _columns [int] used for rectangular type menus, it's used to indicate how many columns of menuItems will the menu have _scriptObject [string] if set to null/not set, it is ignored; otherwise it's value is the configuration file in the objects folder of a script object for this scene: this is a way to make scenes that interact with the player, an example is a cutscene that shows text based on the player's input. _roundLimit [int] a number indicating the aomunt of round to play for stages, once one side has won over half of the rounds the scene is now over. _numberOfSides [int] the amount of sides this scene will handle, side 0 is reserved for scene object, side 1 and side 2 are adversarial sides. _effectsFile [string] used ostly for stages; it's value is the configuration file in the objects folder of a script object for this scene, this object containts the animation data for lifebars, turnbuckles and hit sparks that will be used in this scene, it also containts their configuration data. _fonts [stringList] list of xnb font files in the fonts folder, this is the list of fonts the scene will use, it's mostly useful for menues and cutscenes, the first font is the default one. _autoJumpToNextScene [boolean] if true, once this scene is over (usually because one side has won in a stage) the gamemode will jump to the next scene, it can also be set to false so the scene's script object is the one telling the game mode to which scene to jump to next. _saveVariables [game variable list] this is a list of the game variables that will be loaded/saved on this scene, in the case of menu type scenes those variables can be assigned to menu items _saveFile [string] the file in which to save the scene's variables _loadFile [string] the file from which to read the scene variables _menuItems [menu item list] this is a list of menu items, used in menu type scenes, it containts the general menu item configuration such as it's type, position, event that it fires and data that depends on it's type Menu Item _id [string] this is the id for the menu item, used to identify it; it can eb refered to by the script _posX [int] the starting position for the menu item X component _posY [int] the starting position for the menu item Y component _event [string] the event this menu item will fire, most menu item fire the event when A is pressed and they are selected the event types are: changeScene changes to the scene specified in the event data, event data has the configuration filename. changeGameMode changes to the gamemode specified in the event data, event data has the configuration filename. saveData saves the _saveVariables in the _saveFile exitGame exist the game completely selectCharacter selects a character, event data has the configuration filename for the character to select continueAnswer answer to a continue menu, event data indicates whetehr tog o to the previous scene or to a different scene menuAnswer answer to a menu, it's normally used when the menu is used as a pop up menu, the evenData is put in the menu answer buffer _eventData [string] the data to use when firing the event, it is event dependant _type [string] this is the type of the menu item, the behaviour depends heavily on the type, the types are: text list number key scriptable any no existing type defaults to scriptable _variable [string] name of the variable that will be bind to this menu item, it's used on configuration menus so this menu items gets and modified said game variable's value _restrictInput [int] if this parameter is set to a value > -1 only the control N (0 is the first control or p1 .1 is the second cotrnol or p2, etc.. ) only that control can select this menu item, by setting it to a control value taht does not exist, like 9999, the menu item is unselectable. the other use is so only p1 or p2 can access certain configuration options ( like the key/input configuration ) _minimumValue [int] used for number type menu items, is the lower range for this item; if you want to select values form 0 to 9 this value would be 0 _maximumValue [int] used for number type menu items, is the upper range for this item; if you want to select values form 0 to 9 this value would be 9 _steps [int] used for number type menu items, is the amount of values that will be shown _values [stringList] used for list type menu items, it's a list of the list's elements values _labels [stringList] used for list type menu items, it's a list of the list's elements labels, this is the text that will be drawn on screen _label [string] it's the label/text that will be shown for this menu item _selectedColor [string] this is the colour of the text that will be shown when this menu item is selected, the colour format is "R,G,B,A" _unselectedColor [string] this is the colour of the text that will be shown when this menu item is not selected, the colour format is "R,G,B,A" _chooseKeyColor [string] this is the colour of the text that will be shown when this menu item has it's key being selected, this refers to key type menu items, the colour format is "R,G,B,A" _state [string] it's the unselected state of this menu item, it's used for scriptable menu items _configId [string] it's the script object that contains the script code of this menu item, it's used for scriptable menu items _visible [boolean] if true, teh emnu item is visible, if false , it's invisible
this refers to configuring a game in general, to configure a full game the first step is to configure a "menu" type game mode to load it first, in it's scene list you configure scenes for the intro then a menu type scene to show all the game play modes so the user can select them, running the game via a .bat file we can tell it which is the first game mode to load: as an example, turnbuckler.cfg is like this: "_id": "turnbuckler", "_mode": "menu", "_sceneList": ["mainmenu.scn"], "_controlsNo": 1, "_saveFile" : "config.txt", "_loadFile" : "config.txt", the mode is menu because we don't need any real gamemode rules to be complied with, we enable control for one user, the scene we load is named mainmenu.scn, which contains the game modes we configured for this game as well as a configuration menu. now, on to configurating the first menu "_id": "mainmenu", "_type": "menu", "_background": "titlebg.bg", "_orientation": "vertical", "_menuItems":[ {"_id":"arcade", "_state": "arcade.unselected", "_configId": "mainmenu.menu","_posX":200, "_posY":200, "_event":"changeGameMode", "_eventData":"arcade.cfg"}, {"_id":"versus", "_state": "versus.unselected", "_configId": "mainmenu.menu","_posX":200, "_posY":220, "_event":"changeGameMode", "_eventData":"versus.cfg"}, {"_id":"aivsai", "_state": "aivsai.unselected", "_configId": "mainmenu.menu","_posX":200, "_posY":240, "_event":"changeGameMode", "_eventData":"aivsai.cfg"}, {"_id":"training", "_state": "training.unselected", "_configId": "mainmenu.menu","_posX":200, "_posY":260, "_event":"changeGameMode", "_eventData":"training.cfg"}, {"_id":"options", "_state": "options.unselected", "_configId": "mainmenu.menu","_posX":200, "_posY":280, "_event":"changeGameMode", "_eventData":"options.cfg"}, {"_id":"exit", "_state": "exit.unselected", "_configId": "mainmenu.menu","_posX":200, "_posY":300, "_event":"exitGame", "_eventData":"exit.cfg"}] we make a scene of type menu, so that creates the menu objects we configure to it. then we point to the background object we will use for it. next comes the menu orientation which in our case is vertical, then we have alist of menu objects, each one with a changeGameMode event, which points to the game mode configuration file that corresponds to the game mode we want to change into, the last menu item exits the game. in this case all the menu items use images/animations/scripts from the "mainmenu.menu" script file. in the menu item's selected states we point to the menu it's selected animations and do similarly for the unselcted states. then we change game modes, for arcade.cfg we have the following configuration: "_id": "arcade", "_mode": "arcade", "_comment": "only up to colloseum is really used, the rest of the stages are choosen by stage script", "_sceneList": ["select.scn", "intro_arc.scn","colloseum_arc.scn", "cave_arc.scn", "mansion_arc.scn", "iceland_arc.scn", "carpet_arc.scn"], "_controlsNo": 1, "_playersNo": 1, "_saveFile" : "config.txt", "_loadFile" : "config.txt", the mode is arcade, so it ahs the apropiate behaviour, we enable control for one, then enable one player for the mode, the files used for saving/loading are the ones that have the general game configuration data. for each different mdoe we make a set of scenes, since the scenes are very similar (liek teh carpet set of scenes ) the only notable change is their script file. now, on to select.scn "_id": "mainmenu", "_type": "menu", "_background": "selectbg.bg", "_orientation": "rectangular", "_fonts":["smallFont","comic"], "_rows": 2, "_columns": 4, "_scriptObject":"select.menu", "_menuItems":[ {"_id":"bannou", "_state": "bannou.unselected", "_configId": "select.menu","_posX":250, "_posY":120, "_event":"selectCharacter", "_eventData":"bannou.player"}, {"_id":"bannou_b", "_state": "bannou_b.unselected", "_configId": "select.menu","_posX":284, "_posY":120, "_event":"selectCharacter", "_eventData":"bannou_b.player"}, {"_id":"bannou_g", "_state": "bannou_g.unselected", "_configId": "select.menu","_posX":318, "_posY":120, "_event":"selectCharacter", "_eventData":"bannou_g.player"}, {"_id":"bannou_r", "_state": "bannou_r.unselected", "_configId": "select.menu","_posX":352, "_posY":120, "_event":"selectCharacter", "_eventData":"bannou_r.player"}, {"_id":"bannou", "_state": "bannou.unselected", "_configId": "select.menu","_posX":250, "_posY":158, "_event":"selectCharacter", "_eventData":"bannou.player"}, {"_id":"bannou_b", "_state": "bannou_b.unselected", "_configId": "select.menu","_posX":284, "_posY":158, "_event":"selectCharacter", "_eventData":"bannou_b.player"}, {"_id":"bannou_g", "_state": "bannou_g.unselected", "_configId": "select.menu","_posX":318, "_posY":158, "_event":"selectCharacter", "_eventData":"bannou_g.player"}, {"_id":"bannou_r", "_state": "bannou_r.unselected", "_configId": "select.menu","_posX":352, "_posY":158, "_event":"selectCharacter", "_eventData":"bannou_r.player"} ] the scene is of type menu, the orientation is rectangular we use code from select.menu, in this case to show a portrait related to the selected menu item as well as to have a secret character. the menu items are scriptable type to show a different border around the small portraits of the character's menu, the menu items have a select character event along the config file of the apropiate character matching to the protrait. regarding the script we navigate ot the scene's script object which is select.menu, then to select.script which containts the code. once a character is selected, the game changes to the next scene which is intro_arc.scn "_id": "intro_arc", "_type": "cutscene", "_background": "intro.bg", "_roundLimit" : 1, "_numberOfSides" :3, "_effectsFile": "lifebar.bar", "_fonts":["smallFont","comic"], "_scriptObject":"intro_arc.menu", "_autoJumpToNextScene": false, "_players": [ { "_characterType" : "player", "_side" : 1, "_facing" : 1, "_posX" : 200, "_posY" : 0, "_posZ" : 500, "_life" : 1000, "_power" : 3000, } ], first we define this as a cutscene next we use our specific intro.bg object, then we specify the fonts and our script object. "_objectId": "intro", "_animation": ["intro.anim"], "_code": ["intro.script"], "_palettes": [ [["intro.png","intro.png"]] ], "_intConstants": { "_leftBoundary": 80, "_rightBoundary": 40, "_topBoundary": 40, "_bottomBoundary": 40, "_width": 1280, "_height": 0, "_depth": 60, "_startPositionX": 0, "_startPositionY": 0, "_startPositionZ": 0, "_cameraWidth": 1280, "_cameraHeight": 720, }, "_shape" : [ {"X": 100, "Y":480}, {"X": 680, "Y":480}, {"X": 800, "Y":530}, {"X": 680, "Y":580}, {"X": 100, "Y":580} ] in the background object, the most important part is that we modify the cameraWidth and Height so we get a higher resolution for the cutscene, everything else is normal background configuration. in the intro_arc.menu, we call intro_arc.script as well as configure the animation/sprite files we will use for the speaking portaits / tachie: now in the script file the init state _sequential atribute is true so it executes the state controllers one by one and does not reset to state controller 0 between ticks. first we create a base body layer for the tachie, then we put a neutral face to it, after that we create a small dialog to give the player some information, we set stopSequence to true so no more state controllers are executed until the dialgo is over, next we create a menu using the yesnomenu.scn scene configuration file we also set stop sequence to true so the code waits for the menu answer. now depending on the menu answer we either change the overlay on top of the tachie to change it's facial expression or enable a block fo code using the executeConditionStart sctrl, in teh code block we create a new dialog then we create a pop menu using the start_arc.scn configuration file. at last we chagne the scene based on the menu answer. now we move to the next scene, sicne the route depends on several factors we will use iceland_arc as an example: "_id": "iceland_arc", "_type": "stage", "_background": "iceland.bg", "_roundLimit" : 1, "_numberOfSides" :3, "_effectsFile": "lifebar.bar", "_scriptObject":"iceland_arc.menu", "_autoJumpToNextScene": false, "_players": [ { "_characterType" : "player", "_side" : 1, "_facing" : 1, "_posX" : 200, "_posY" : 0, "_posZ" : 500, "_life" : 1000, "_power" : 3000, }, { "_characterType" : "ai", "_configId" : "bannou.player", "_palette" : 0, "_side" : 2, "_facing" : -1, "_posX" : 400, "_posY" : 0, "_posZ" : 500, "_life" : 1000, "_power" : 3000, } ], this will be of type stage, so the fighting engine is used, then we point to our effects file and our script object, we disable outjump so the script can select the next stage instead, in the list of players configuration for the scene we enable one player type character so we get it from the game mode and one ai type character, we also specify the ai character's configuration file so ti loads a specific character , we specify both characters sides as well as their initial positions on the scene. iceland_arc.menu points to iceland_arc.script, in this file we have the following code: { "_type": "changeScene", _parameters : [ {"_name": "or", "_value": "matchIsOver == true && sideWon == 1", "_inherit": null, "_valueType": "boolean"}, {"_name": "scene", "_value": "'carpet_arc.scn'", "_inherit": null, "_valueType": "string"} ] }, { "_type": "changeScene", _parameters : [ {"_name": "or", "_value": "matchIsOver == true && sideWon == 2", "_inherit": null, "_valueType": "boolean"}, {"_name": "scene", "_value": "'continue_arc.scn'", "_inherit": null, "_valueType": "string"} ] } so, depending on which side won the match, we change to either the continue screen ( side 2 won) or the next scene (in this case carpet_arc) in the case of carpet_arc { "_type": "changeGameMode", _parameters : [ {"_name": "or", "_value": "matchIsOver == true && sideWon == 1", "_inherit": null, "_valueType": "boolean"}, {"_name": "gameMode", "_value": "'turnbuckler.cfg'", "_inherit": null, "_valueType": "string"} ] } in the case side 1 wins , we change back to teh title screen to finish the game, we could also change to a cutscene to show the character ending. now, the continue scene is: "_id": "continue_arc", "_type": "menu", "_background": "continue_arc.bg", "_orientation": "vertical", "_effectsFile": "continue_arc.bg", "_scriptObject":"continue_arc.menu", "_menuItems":[ {"_id":"yes", "_state": "yes.unselected", "_configId": "continue_arc.menu","_posX":250, "_posY":200, "_event":"continueAnswer", "_eventData":"previous"}, {"_id":"no", "_state": "no.unselected", "_configId": "continue_arc.menu","_posX":250, "_posY":220, "_event":"continueAnswer", "_eventData":"select.scn"} ] it is a menu type scene, we configure our script object and a menu with scriptable menu items for the yes no options. the yes option has an event of type continueAnswer, which jumps to the previous scene, which in this case would be the scene in which we just lost. the no option goes back to the select.scn scene so we can select characters again. continue_arc.menu points to continue_arc.script, in this file we create an animation for the countdown, another for the "continue ?" question, then, once 10 seconds / 600 ticks have passed we change to another state in which we use the "useSelectedItem" sctrl, so even if A has not been pressed in the menu items we forcefully fire the selected items's event. now, onto vs mode: "_id": "versus", "_mode": "versus", "_sceneList": ["select_versus.scn", "stageSelect_versus.scn"], "_controlsNo": 2, "_playersNo": 2, "_aisNo": 0, "_saveFile" : "config.txt", "_loadFile" : "config.txt", the mode is versus , in our scene list we put our character select scene then a satge select scene, we enable two controls, one per player, 2 players and no ais . select_versus.scn is pretty much the same as the arcade one, the important difference is that we point to a different script object, select_versus.menu, in there we go to select_versus.script, in there we also adjust the camera and change the scene's script object animation based on the selected menu item as we did in select_arcade, but we also create and change an effect based on the second selected menu item using the _selectedMenuItemId(1) function. stageSelect_versus.scn is a simple menu taht shows one scriptable object per stage "_id": "stageSelect_versus", "_type": "menu", "_background": "stageSelect_versus.bg", "_orientation": "rectangular", "_rows": 2, "_columns": 3, "_menuItems":[ {"_id":"carpet", "_state": "carpet.unselected", "_configId": "stageSelect_versus.menu","_posX":100, "_posY":100, "_event":"changeScene", "_eventData":"carpet_versus.scn"}, {"_id":"cave", "_state": "cave.unselected", "_configId": "stageSelect_versus.menu","_posX":260, "_posY":100, "_event":"changeScene", "_eventData":"cave_versus.scn"}, {"_id":"colloseum", "_state": "colloseum.unselected", "_configId": "stageSelect_versus.menu","_posX":420, "_posY":100, "_event":"changeScene", "_eventData":"colloseum_versus.scn"}, {"_id":"mansion", "_state": "mansion.unselected", "_configId": "stageSelect_versus.menu","_posX":180, "_posY":220, "_event":"changeScene", "_eventData":"mansion_versus.scn"}, {"_id":"iceland", "_state": "iceland.unselected", "_configId": "stageSelect_versus.menu","_posX":340, "_posY":220, "_event":"changeScene", "_eventData":"iceland_versus.scn"}, ] in the event data we put the scene we want to play vs mode at all the selectable scenes have a simialr configuration: the mansion_versus.scn is the following "_id": "mansion_versus", "_type": "stage", "_background": "mansion.bg", "_roundLimit" : 1, "_numberOfSides" :3, "_effectsFile": "lifebar.bar", "_scriptObject":"mansion_versus.menu", "_autoJumpToNextScene": false, "_players": [ { "_characterType" : "player", "_side" : 1, "_facing" : 1, "_posX" : 200, "_posY" : 0, "_posZ" : 500, "_life" : 1000, "_power" : 3000, }, { "_characterType" : "player", "_side" : 2, "_facing" : -1, "_posX" : 400, "_posY" : 0, "_posZ" : 500, "_life" : 1000, "_power" : 3000, } ], we disable autojump to next scene, and specify mansion_versus.menu for oru script object, in the character list both characters are of _characterType "player" so tehya re laoded from the game mode's selected players. then onto the mansion_versus.script we ahev the following code "_type": "changeToRootScene", _parameters : [ {"_name": "or", "_value": "matchIsOver == true ", "_inherit": null, "_valueType": "boolean"}, {"_name": "flags", "_value": "'resetCharacterSelection'", "_inherit": null, "_valueType": "string"} ] this changes to the first scene of the game mode once the match is over, in this case the "select_versus.scn" scene. next is the aivsai mode "_id": "aivsai", "_mode": "aivsai", "_sceneList": ["select_aivsai.scn", "stageSelect_aivsai.scn"], "_controlsNo": 1, "_playersNo": 0, "_aisNo": 2, "_saveFile" : "config.txt", "_loadFile" : "config.txt", in the configuration mode we set the type to aivsai, like the versus mode we configure a select scene and a stage selection scene. teh mode is configured with 1 control so one player can select teh ais that will fight, 0 player as tehre won't be player controlled characters and 2 ais. the select_aivsai scene is the same as the versus one, the only difference is the script file, select_aivsai.script , here the script is the same as the one in the arcade mode one as we only select characters one by one. stageSelect_aivsai scene folow the exact same logic as the versus one, except that it points to the _aivsai stages instead of the versus one. then for a fighting scene/stage "_id": "mansion_aivsai", "_type": "stage", "_background": "mansion.bg", "_roundLimit" : 1, "_numberOfSides" :3, "_effectsFile": "lifebar.bar", "_scriptObject":"mansion_aivsai.menu", "_autoJumpToNextScene": false, "_players": [ { "_characterType" : "ai", "_side" : 1, "_facing" : 1, "_posX" : 200, "_posY" : 0, "_posZ" : 500, "_life" : 1000, "_power" : 3000, }, { "_characterType" : "ai", "_side" : 2, "_facing" : -1, "_posX" : 400, "_posY" : 0, "_posZ" : 500, "_life" : 1000, "_power" : 3000, } ], both characters are of ai type, the rest of the file is the same as the regular stage configuration. in the script file we just reset to the select screen as we did in versus. next is the training mode "_id": "training", "_mode": "training", "_sceneList": ["select_training.scn", "stageSelect_training.scn"], "_controlsNo": 1, "_playersNo": 1, "_aisNo": 1, "_saveFile" : "config.txt", "_loadFile" : "config.txt", the medo is training, we enable one control, one player type character and one ai type character. the select_training scene is the same as the versus one, the only difference is the script file, select_training.script here the script is the same as the one in the arcade mode one as we only select characters one by one. stageSelect_training scene folow the exact same logic as the versus one, except that it points to the _training stages instead of the versus one. then for a fighting scene/stage "_id": "mansion_training", "_type": "stage", "_background": "mansion.bg", "_roundLimit" : 1, "_numberOfSides" :3, "_effectsFile": "lifebar.bar", "_scriptObject":"mansion_training.menu", "_autoJumpToNextScene": false, "_players": [ { "_characterType" : "player", "_side" : 1, "_facing" : 1, "_posX" : 200, "_posY" : 0, "_posZ" : 500, "_life" : 1000, "_power" : 3000, }, { "_characterType" : "ai", "_side" : 2, "_facing" : -1, "_posX" : 400, "_posY" : 0, "_posZ" : 500, "_life" : 1000, "_power" : 3000, } ], we have one player character and one ai type character, in the case of the ai type we don't specify the character file to load so teh engine will load the ai we just selected previously, the rest of the file is the same as the regular stage configuration. in the script file we just reset to the select screen as we did in versus. next is the options mode "_id": "options", "_mode": "menu", "_sceneList": ["options.scn"], "_controlsNo": 2, "_playersNo": 0, "_saveFile" : "config.txt", "_loadFile" : "config.txt", the mode for it will be menu as we don't need any specific gameplay behaviour, we enable control for 2 players (so palyer 2 can configure his own keys ) , 0 player type characters as thre won't be real gameplay thre anyway. we only have one scene, the main options.scn one. "_id": "options", "_type": "menu", "_background": "titlebg.bg", "_orientation": "vertical", "_fonts":["smallFont","comic"], the scene is of type menu, it is a vertical one and we declare the fotns we will use, that is important as we will create text type menu items and they require the font. "_saveFile" : "config.txt", "_loadFile" : "config.txt", "_shareSelectedItem" : true, we configure the save and the load files as the config file we use for the rest of the game modes, so all of the have access to the same data. we set share selected item to true. "_saveVariables": [ {"_name": "difficulty", "_value": "5", "_type": "int" }, {"_name": "sfxVolume", "_value": "50", "_type": "int" }, {"_name": "soundVolume", "_value": "40", "_type": "int" }, {"_name": "resolution", "_value": "1280,720", "_type": "string" } ], those are the variables that will be saved to the file, we also give them default values. "_menuItems":[ {"_id":"difficulty", "_type": "list", "_label": "difficulty", "_variable": "difficulty", "_posX":200, "_posY":200, "_event":"null", "_eventData":"null", "_selectedColor":"255,0,0,255", "_unselectedColor":"255,0,255,255", "_labels":["easy","normal","hard"], "_values":["0","5","9"] }, {"_id":"inputConfig", "_type": "text", "_label": "input", "_posX":200, "_posY":220, "_event":"changeScene", "_eventData":"inputConfig.scn", "_selectedColor":"255,0,0,255", "_unselectedColor":"255,0,255,255"}, {"_id":"sfxVolume", "_type": "number", "_label": "sfx volume", "_variable": "sfxVolume", "_posX":200, "_posY":240, "_event":"null", "_eventData":"null", "_selectedColor":"255,0,0,255", "_unselectedColor":"255,0,255,255", "_minimumValue":"0", "_maximumValue":"100","_steps":"10" }, {"_id":"soundVolume", "_type": "number", "_label": "sound volume", "_variable": "soundVolume", "_posX":200, "_posY":260, "_event":"null", "_eventData":"null", "_selectedColor":"255,0,0,255", "_unselectedColor":"255,0,255,255", "_minimumValue":"0", "_maximumValue":"100","_steps":"10" }, {"_id":"resolution", "_type": "list", "_label": "resolution", "_variable": "resolution", "_posX":200, "_posY":280, "_event":"null", "_eventData":"null", "_selectedColor":"255,0,0,255", "_unselectedColor":"255,0,255,255", "_labels":["640 x 360","1280 x 720","1920 x 1080"], "_values":["640,360","1280,720","1920,1080"] }, {"_id":"save", "_type": "text", "_label": "save", "_posX":200, "_posY":300, "_event":"saveData", "_eventData": "config.save", "_selectedColor":"255,0,0,255", "_unselectedColor":"255,0,255,255"}, {"_id":"exit", "_type": "text", "_label": "exit", "_posX":200, "_posY":320, "_event":"changeGameMode", "_eventData":"turnbuckler.cfg", "_selectedColor":"255,0,0,255", "_unselectedColor":"255,0,255,255"}, ] as for the menu items: the first is the difficulty , we use a list type item for it, we name and label it as "difficulty" and asociate the difficulty variable to it, set the apropiate colors for being selected and unselected, it won't fire an event so we null it.then we ocnfigure the label we will have for the difficulty, in this case just 3 levels and we ocnfigure their apropiate numericla values as difficulty can only range from 0 to 9. the second one is the input configuration, it's of type text, instead of configuring something itself what it does is call the inputConfig.scn Scene by using a change scene event. the sfx volume is of type number, we associate it to the sfxVolume variableset the minimum and maximum values and the amount of steps it will show. now the resolution is associated to the resolution variable, it's a list type menuItem, in teh list we have the resolutions we will allow to be used and their apropiate labels. for the save menu item we have a text type menu item, for the event we fire a save data, so the variables are saved to the config.txt file. for exit we have a text type menu item, in it's event we change the game mode to turnbuckler.cfg so we effectively go back to the initial game mode. finally comes the inputConfig.scn file "_id": "inputConfig", "_type": "menu", "_background": "titlebg.bg", "_orientation": "vertical", "_fonts":["smallFont","comic"], "_saveFile" : "inputConfig.txt", "_loadFile" : "inputConfig.txt", it's a vertical menu, with properly configured fonts, we save the variables to the inputConfig.txt file because the inputs can read the configuration from there. "_saveVariables": [ {"_name": "player1A", "_value": "65", "_type": "int" }, {"_name": "player1B", "_value": "83", "_type": "int" }, {"_name": "player1C", "_value": "68", "_type": "int" }, {"_name": "player1X", "_value": "81", "_type": "int" }, {"_name": "player1Y", "_value": "87", "_type": "int" }, {"_name": "player1Z", "_value": "69", "_type": "int" }, {"_name": "player1S", "_value": "82", "_type": "int" }, {"_name": "player1up", "_value": "38", "_type": "int" }, {"_name": "player1down", "_value": "40", "_type": "int" }, {"_name": "player1left", "_value": "37", "_type": "int" }, {"_name": "player1right", "_value": "39", "_type": "int" }, {"_name": "player2A", "_value": "46", "_type": "int" }, {"_name": "player2B", "_value": "35", "_type": "int" }, {"_name": "player2C", "_value": "34", "_type": "int" }, {"_name": "player2X", "_value": "45", "_type": "int" }, {"_name": "player2Y", "_value": "36", "_type": "int" }, {"_name": "player2Z", "_value": "33", "_type": "int" }, {"_name": "player2S", "_value": "189", "_type": "int" }, {"_name": "player2up", "_value": "104", "_type": "int" }, {"_name": "player2down", "_value": "101", "_type": "int" }, {"_name": "player2left", "_value": "100", "_type": "int" }, {"_name": "player2right", "_value": "102", "_type": "int" }, ], for the variables we configure the variables that will contain the player's input configuration, since we want two player support we have one set for player1 and one set for player2, for the varaibles name we use the player id for the input (player1, player2, etc...) then we concatenate the button name,it can be a single letter or a full word. "_menuItems":[ {"_id":"p1A", "_type": "key", "_label": "A", "_variable": "player1A", "_posX":200, "_posY":100, "_restrictInput":0, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p1B", "_type": "key", "_label": "B", "_variable": "player1B", "_posX":200, "_posY":110, "_restrictInput":0, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p1C", "_type": "key", "_label": "C", "_variable": "player1C", "_posX":200, "_posY":120, "_restrictInput":0, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p1X", "_type": "key", "_label": "X", "_variable": "player1X", "_posX":200, "_posY":130, "_restrictInput":0, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p1Y", "_type": "key", "_label": "Y", "_variable": "player1Y", "_posX":200, "_posY":140, "_restrictInput":0, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p1Z", "_type": "key", "_label": "Z", "_variable": "player1Z", "_posX":200, "_posY":150, "_restrictInput":0, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p1S", "_type": "key", "_label": "S", "_variable": "player1S", "_posX":200, "_posY":160, "_restrictInput":0, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p1up", "_type": "key", "_label": "up", "_variable": "player1up", "_posX":200, "_posY":170, "_restrictInput":0, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p1down", "_type": "key", "_label": "down", "_variable": "player1down", "_posX":200, "_posY":180, "_restrictInput":0, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p1left", "_type": "key", "_label": "left", "_variable": "player1left", "_posX":200, "_posY":190, "_restrictInput":0, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p1right", "_type": "key", "_label": "right", "_variable": "player1right", "_posX":200, "_posY":200, "_restrictInput":0, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p2A", "_type": "key", "_label": "A", "_variable": "player2A", "_posX":300, "_posY":100, "_restrictInput":1, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p2B", "_type": "key", "_label": "B", "_variable": "player2B", "_posX":300, "_posY":110, "_restrictInput":1, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p2C", "_type": "key", "_label": "C", "_variable": "player2C", "_posX":300, "_posY":120, "_restrictInput":1, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p2X", "_type": "key", "_label": "X", "_variable": "player2X", "_posX":300, "_posY":130, "_restrictInput":1, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p2Y", "_type": "key", "_label": "Y", "_variable": "player2Y", "_posX":300, "_posY":140, "_restrictInput":1, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p2Z", "_type": "key", "_label": "Z", "_variable": "player2Z", "_posX":300, "_posY":150, "_restrictInput":1, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p2S", "_type": "key", "_label": "S", "_variable": "player2S", "_posX":300, "_posY":160, "_restrictInput":1, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p2up", "_type": "key", "_label": "up", "_variable": "player2up", "_posX":300, "_posY":170, "_restrictInput":1, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p2down", "_type": "key", "_label": "down", "_variable": "player2down", "_posX":300, "_posY":180, "_restrictInput":1, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p2left", "_type": "key", "_label": "left", "_variable": "player2left", "_posX":300, "_posY":190, "_restrictInput":1, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"p2right", "_type": "key", "_label": "right", "_variable": "player2right", "_posX":300, "_posY":200, "_restrictInput":1, "_selectedColor":"255,0,0,255", "_unselectedColor":"0,0,0,255", "_chooseKeyColor":"255,255,0,255" }, {"_id":"save", "_type": "text", "_label": "save", "_posX":200, "_posY":300, "_event":"saveData", "_eventData": "config.save", "_selectedColor":"255,0,0,255", "_unselectedColor":"255,255,255,255"}, {"_id":"exit", "_type": "text", "_label": "exit", "_posX":200, "_posY":320, "_event":"changeScene", "_eventData":"options.scn", "_selectedColor":"255,0,0,255", "_unselectedColor":"255,255,255,255"}, ] in the menu item list we have three main sets, the first and second sets are the input configuration for the players, the items are of key type, the label corresponds to the ingame key so the player can easily know which key he is configuring, then we bind the key to the apropiate variable; since we want only p1 to be able to configure player1 input we configure the restrict input index to 0 for player1's inputs, same for player2 using index 1, then we set the selected and unselected colours as apropiate, we also configure the _chooseKeyColour, this colour is used when the player presses A on top of a key type menu item, once the player does that the key changes colour to the choose key one and the next key that is pressed will be the value that will be assigned to the variable. the third set are the exit and save menu items, save is just a text item and which we have a savedata event; exit is a test type menu item, for it's event we change the scene to the options.scn which is the previous menu file.