Starflight III Wikia
Don't have an account?
Register
Advertisement
Register

Core Module and Database

Edit

This page is a discussion of the Core Module and Database.

The Core Module and Database are actually separate constructs within the game. The Core Module is the basic game runtime routine itself, designed to handle code underlying the functioning of pretty much everything in the game. It's architecture handles basic data types like most of the other modules in the game, but it is different in that it alone actually does the underlying processing of all video and audio output, keyboard and mouse inputs, and data processing via the Panda3D engine. All other in-game modules are dependent upon the Core module to function as intended; its importance to the game, therefore, should be obvious. All code for the Core module is located in the sf3_core.py file.

In contrast, the Database is designed to handle the internal "library" functions, and to act as an in-game informational reference for the player (covering such data as species profiles, planetary information and ship statistics). The basic architecture of the Database is similar to other modules within the game that handle basic data types (such as integers and strings) and hash tables / dictionaries. It is specifically required by the Operations sub-module of the Starport Module; whether a similar function will be included as part of the Captain's menu in the Starship menu is currently being debated. The Database is important to the game because it will help with player immersion in the game, it will act as a quick reference for those players who have not played the original games, and (if the plot is set up that way) it may serve as yet another avenue through which the player may receive clues necessary for the completion of the game. For programming purposes, the Database will be considered part of the Core Module, and so all of its code will also be located in the sf3_core.py file. The Database has now been designed as part of the Operations sub-module of the Starport module. Whether it will be added to the Starship Module as well has still not yet been decided.

Summary Description[]

The game routine is activated by the player from their operating system (and control goes back to their operating system when the player chooses to exit the program). Upon activation, the game routine creates handlers for video, audio, and interface controls and assigns default values to those handlers. Objects and routines that handle ongoing basic in-game tasks, such as the combat handler, are also created. It then creates a toybox object to hold all of the critical single-use objects and in-game data, and loads all of the game's data up from that object (the toybox object itself will be created by a separate generator routine as a means of reducing the amount of game hacking that goes on). Once all the initial items have been created, the core module will pass game control to the Main Menu Interface. The module itself will remain running in the background, providing random numbers as requested to the other modules, specific data as requested by those modules, and overseeing general occurrences of game events (such as starting and stopping music, running animated sequences, etc.).

Data Structure of the StarflightIIICore Object[]

The following list is an indication of the various variables and methods that will be included in a StarflightIIICore object. This list contains suggested methods and variables. StarflightIIICore objects are meant to be used as the root object for all other in-game objects and modules; the base Panda3d architecture will be loaded and the program executed through this object. Every other object in the game is technically a child object of the StarflightIIICore Object. Only one StarflightIIICore object is meant to be used in the game, loaded when the sf3_core.py file is executed; an object of the StarflightIIICore class is created immediately before Panda3d's run() method is activated. The object's data structure is as follows:

Data Structure of the Preloader Object[]

The following list is an indication of the various variables and methods that will be included in the Preloader object. This list contains the final methods and variables that will be included in the object. The Preloader object is meant to be used as a subsidiary of the InterfaceHandler object, coming into existence while the game is loading in all its data and being destroyed upon activation of the Main Menu Interface. The Preloader object has no child objects, and only one is meant to be used in the entire game. Its data structure is as follows:

  • Class: Preloader
    • String: szOpeningMovie
    • Method: _init_(self, fonts)
    • Method: createGraphics(self, fonts)
    • Method: prepLoadGroup(self)
    • Method: playOpeningMovie(self)
    • Method: destroy(self)

Data Structure of the InterfaceHandler Object[]

The following list is an indication of the various variables and methods that will be included in the InterfaceHandler object. This list contains suggested variables only; methods may be added as they are deemed necessary. The InterfaceHandler object is meant to be used as a means by which the game coordinates visual and auditory output (what's on screen and what's playing out the speakers) as well as control inputs. It is a child object of the StarflightIIICore object and is a parent object of all Modules that utilize an Interface. Additionally, the object has three child objects, "InputManager" (which handles the currently active set of hotkeys and mouse clicks), "Jukebox" (which handles audio), and "Interface" (which handles the visual elements and actual functioning of each given interface). Only one InterfaceHandler is meant to be used in the game, created by the StarflightIIICore object as part of its initialing routine and remaining active until the game routine terminates. Its data structure is as follows:

  • Class: InterfaceHandler
    • Enum: ACTIVE_INTERFACE (MAIN-MENU, STARPORT, OPERATIONS, PERSONNEL, BANK, FLEET_CONFIG, TRADE, CASINO, LOUNGE, STARSHIP, TERRAIN_VEHICLE, CAPTAINS_LOG, STARMAP, TACTICAL)
    • Enum: LAST_ACTIVE_INTERFACE (same options as ACTIVE_INTERFACE)
    • Tuple: Game_Settings
      • Float: Music Volume (range 0-1; default 0.8)
      • Float: Sound Volume (range 0-1; default 0.8)
      • Tuple: Resolution Settings (default 1024x768, 32-bit)
        • Integer: X-axis Resolution
        • Integer: Y-Axis Resolution
      • Flag: Full-Screen or Windowed
      • Flag: Sound Muted?
      • Flag: Reverse Speakers?
    • Class: InputManager
      • Dictionary: Hotkeys
        • Keys: Standard Keys on a Keyboard
        • Values: Hotkey Assignments
    • Class: Jukebox (audio handler)
      • Dictionary: MusicAndSounds
        • Key: Music/Sound File Name
        • Value (Tuple): Playback Data
          • Flag: Playing?
          • Float: Current Playback Position
          • Float: Loop Back Position
          • Float: Loop Back To Position
    • Method: _init_(XML)
    • Method: setInterface(ACTIVE_INTERFACE, LAST_ACTIVE_INTERFACE)
    • Method: runLastInterface()
    • Method: activateInterface()
    • Method: destructInterface()


Data Structure of the Interface Object[]

The following list is an indication of the various variables and methods that will be included in an Interface objects. This list contains the final methods and variables included in the object. Interface objects are meant to be used in order to handle the actual functioning of a given interface; as such, they are direct child objects of the InterfaceHandler. Interface objects have no child objects of their own. One Interface object is in the game for every possible game interface; for SF3, this means that there will be approximately two dozen Interface objects in existence. They are meant to loaded into existence when the game initially loads, though they won't actually be displayed unless selected for display by the InterfaceHandler. Their data structure is as follows:

  • Class: Interface
    • Hash/Dictionary: hObjects
    • Method: _init_(fonts, inputManager)
    • Method: initMenu(self, args)
    • Method: highlightItem(self, item)
    • Method: activateItem(self, item)
    • Method: menuControl(self, task)
    • Method: destroy(self)

Data Structure of the Toybox Object[]

The following list is an indication of the various variables and methods that will be included in a Toybox object. This list contains suggested methods and variables. The Toybox object is designed primarily as an overall holder for one-time use objects in the game as well as pieces of data the game uses on a temporary basis. It is unique in the game in that it is originally created by an external generator program, which generates the included objects and data and then saves the object as a c-pickled binary file. The purpose in doing this is to prevent broad dissemination of the game's data; the XML files used to hold the game's data will not be released to the general public. This file allows the necessary data to accompany the game while stymieing any attempts at cheating in-game (which would otherwise be simple to do simply by altering the content of the XML). A single Toybox object is meant to be used in the game, loaded by the StarflightIIICore object when the game routine initializes. Its data structure is as follows:

  • Class: Toybox
    • Class: Onomastikon
    • Class: Encounter_Handler
    • Class: Trader
    • Class: gameClock
    • Class: Player
    • Method: _init_(XML)
    • Method: loadData()

Data Structure of the SF3Actor Object[]

The following list is an indication of the various variables and methods that will be included in an SF3Actor object (this object, while not directly required by the StarflightIIICore object, is required by pretty much all of the game's objects, and thus is included here with the remainder of the Core Module discussion). This list contains suggested variables only; methods will be added at a later time. SF3Actor objects are basic objects used by the Core Module for any object that must appear on screen, regardless of any other function that object has in the game. They are generally included as a part of all other objects and modules in the game, unless specified otherwise. Their data structure is as follows:

  • Class: SF3Actor
    • Class: Actor (Panda3D) = None
    • Class: Model (Panda3D) = None; see the Panda3D Manual for details on the distinction between Actors and Models
    • String: szMesh (name of the file that contains the object's image)
    • String: szIcon (name of a sprite file that can be used as an icon representing the object)
    • List: vSFXHit (list of sound effects to select from for playback when the object is hit)
    • List: vSFXAttack (list of sound effects to select from for playback when the object is attacking)
    • List: vSFXIdle (list of sound effects to select from for playback when the object is on screen and neither hit nor attacking)

An SF3Actor object should either contain data on an Actor or a Model; under no circumstances should it contain both.

Methods[]

StarflightIIICore Class[]

_init_()[]

The object's initializer will begin by diabling the default mouse-camera controls in Panda3d and setting the background color to black. Filters will then be set to integrate glow maps in order to create halos around glowing objects, and automatic shader generation will be activated. The game's font set will then be loaded into memory. A series of objects will then be created, including an InputManager, InterfaceHandler, Jukebox and a Toybox object (this last object will be created with the appropriate flag value for the level of development; see the discussion under the Toybox _init_() method below). A call will then be made to the create a Preloader object before going out of scope.

I need to review when any Preloader class will be called...

regRoll(diceType, diceAmount)[]

The regRoll method is the game's underlying random integer generator; any time any module in the game needs a random number for any reason, it is this method that is called. The regRoll method is based on the native Python random number generator, which itself is based on the Mersenne Twister algorithm. When called, the method creates a local holder (called "diceTally") for the final overall total. The method then enters into a for loop, with the number of iterations set equal to the value passed to the method from the diceAmount argument (an integer). For each interation, a call to the random module's randit() method is made, with the range set between 1 and the value passed to the regRoll method's diceType argument (also an integer). The returned value is added to diceTally for each iteration of the loop. Once the loop is completed, the final value of diceTally is returned to the caller and the method goes out of scope.

Preloader Class[]

_init_(self, fonts)[]

This method's purpose is to activate the Preloader, call into existence its graphics, and activate the opening animation. It merely consists of a call to its own createGraphics(), prepLoadGroup() and destroy() methods, which it performs in that order. While the prepLoadGroup() methods are functioning, the method will display a "loading progress bar" on the screen, which will be updated as the files are loaded into memory (which this method also does). Once all files are loaded, the destroy method will be called.

createGraphics(self, fonts)[]

This method's function is simply to load the visual elements necessary for the preloader into memory, as well as any text associated with the preloader (such as the words "Loading Starflight III..."). As the visual elements are loaded, they are placed on the appropriate Panda nodes for rendering, though they are not actually rendered until after the prepLoadGroup() method has had a chance to run; they are finally rendered through the initializer routine.

prepLoadGroup(self, args)[]

This method's purpose is to define the pre-determined set of objects that will be loaded into memory. The method receives as an argument the list of items from the initial loading of the InterfaceHandler and stores that list into a local list container. It then counts the total number of items to be loaded before going out of scope. (References to items created by this method will still exist and be valid due to references to those items in various Panda nodes).

playOpeningMovie(self)[]

This method's purpose is to play the game's opening movie. When called, the opening animation indicated in the master_interface.xml file is read into a Panda MovieTexture (since it implements synchronizeTo, necessary for the animation's sound). A card is then generated to set the video texture on; this card will utilize the current resolution settings of the game (defaulting to fullscreen). Once set the animation will be set to render in a 2D aspect. Sound is then loaded and synchronized with the video, and then the video is allowed to play. The animation will play through once and can be interrupted by the player by pressing any key on the keyboard, calling the Preloader's destroy() method. Before going out of scope, a call is made to the InterfaceHandler class to set the CURRENT_INTERFACE to the Main Menu Interface, and to pass game control to that interface.

This method is based on the Panda3d Media Player sample program, which should be all the more complex our animation player needs to be. A similar method may be utilized for other in-game animations.

destroy(self)[]

This method's purpose is to remove all visual elements of the Preloader class. It simply removes the Panda node to which the visual elements are anchored, destroys all text and removes the frame. It will then call the playOpeningMovie() method and wait for that method to return before finally going out of scope, which should simultaneously destroy the Preloader object.

InterfaceHandler Class[]

_init_(XML)[]

The argument flag is designed to be a way of indicating whether the game will be set to load data from XML files or from the saved toybox file. While the game is being tested, the flag should be set to True to load from XML. When the game is ready for public dissemination (including any public alpha tests), this flag should be set to False.

When the InterfaceHandler object is initialized, the object's initializer creates an InputManager and Jukebox object, as well as the ACTIVE_INTERFACE and LAST_ACTIVE_INTERFACE enums (enum is NOT a native Python object type; the same effect can be achieved, however, by creating a dictionary and using the desired values as keys, setting the values to False.). A Game_Settings tuple is also created with a set of default settings.

The object's initializer creates, in order, an Onomastikon object, an Encounter_Handler object, a Trader object, a gameClock object, and a Player object. For each object (except the Player object), the value of the initializer's flag is passed on to the initializer of the created object; this is intended to instruct the object whether or not to go ahead and load its data through XML or not. If the initializer's flag is set to True, the method is allowed to go out of scope after creating all objects. Otherwise, a call is made to the loadData() method prior to the method going out of scope. Next, the initializer will check the argument passed to it. If an XML load is indicated, the routine will gather the information necessary to fill in the various dictionaries and enums from the XML file. Otherwise, it will overwrite those values with what's been stored in the toybox object. Finally, before going out of scope, it will set both the ACTIVE_INTERFACE and LAST_ACTIVE_INTERFACE to the first value stored (which should be MAIN-MENU).

setInterface(ACTIVE_INTERFACE)[]

This method simply sends an instruction to switch out the current interface. When this routine runs, the InterfaceHandler goes through the LAST_ACTIVE_INTERFACE enumerator (a dictionary, with the names of the interfaces as the keys and a simple flag for the values). The key which is currently set to True is set to False. Then, the enumerator is checked again, compared to the current True key in ACTIVE_INTERFACE. This value is set to True in LAST_ACTIVE_INTERFACE. Now ACTIVE_INTERFACE is checked; the value currently set as True is set to False, and whichever key matches the argument sent to the method is switched to True. The hotkeys will be reassigned at that point to match the Interface, and any music changes will also be done at that time. Any additional changes required for the new Interface (such as stopping the game clock), will also be done at this time.

runLastInterface()[]

This method performs the same sort of instructional change set as the setInterface method, but is intended strictly to move the current LAST_ACTIVE_INTERFACE back to ACTIVE_INTERFACE, with the intent of allowing the player to temporarily switch over to a different interface and come back to what they had been doing up to that point. It may be that we'll need to save a little more information than just the last interface state to get the kind of functionality we want here. Particularly if, for example, someone is in the middle of exploring a planet, has to quit and come back. We'd not only have to store which interface was active, but the state of that interface at the time of the switch. Might be something to add to all that is stored in the player's save files.

activateInterface()[]

This method's purpose is to display the visual elements of a given interface on screen and to activate any sounds and controls associated with that interface. When called, the method will make sure there are no items currently displayed on screen and go ahead and remove anything still present. If the interface has an animation associated with its activation, the method goes ahead and makes a call to play the animation. It then sorts through the interface's elements, setting the control hotkeys in the Input Manager and any sounds in the Jukebox. Finally, it gathers the information on the interface's visual elements, calls up the necessary models/sprites, places, orients and scales them as indicated by the interface's data, and renders the interface before going out of scope.

destructInterface()[]

This method's purpose is to deactivate a given interface. When called, the item will clear the hotkeys in the Input manager, remove all sounds associated with the interface from the Jukebox, and remove the interface's visual elements (this might be done by simply moving the interface's node from the Panda rendering node; if it can be done this way, interfaces could be pre-rendered while the game is loading up and simply moved and removed from the render node when required). If there is an animation associated with the interface's deactivation, the method goes ahead and makes a call to play the animation.

Interface Class[]

_init_(fonts, inputManager)[]

This method loads in the elements of the associated interface. When an Interface is created, the method begins by loading in the list of visual elements it needs into its holder dictionary. After loading in any font information the interface requires, it passes its list of keyboard commands to the InterfaceHandler's InputManager object. Before going out of scope, the Interface will create a reference to itself in order to keep itself from being prematurely garbage collected.

initMenu(self, args)[]

This method's purpose is to load in and organize any menu options associated with the interface an ultimately to display the interface. When called, the method will sift the arguments passed to it into several sets of holder objects. It will then create a framework for displaying all visual elements along with those menu options based on the menu type argument passed to it. This includes preparation of any text associated with the menu and/or graphical elements such as buttons and dialogues. Finally, it sets the first item on the menu list to highlight before going out of scope.

The arguments passed to the method will determine the degree of complexity of its functioning. Because the structure of the item, function, and argument lists can be confusing, here is an outline-style example of what it should like:

Argument list passed to initMenu:

  • 0: Type of menu
  • 1: Title of menu
  • 2: List of Menu Item Strings (the thing displayed)
  • 3: List of functions for each item to execute if selected.
    • 0: List of functions for item 0
    • 1: List of functions for item 1
    • N: List of functions for item N
  • 4: List of arguments for functions
    • 0: List of Argument Lists for item 0
      • 0: List of Arguments for function 0 of item 0
      • 1: List of Arguments for function 1 of item 0
      • N: List of Arguments for function N of item 0
    • 1: List of Argument Lists for item 1
      • 0: List of Arguments for function 0 of item 1
      • 1: List of Arguments for function 1 of item 1
      • N: List of Arguments for function N of item 1
    • N: List of Argument Lists for item N
      • 0: List of Arguments for function 0 of item N
      • 1: List of Arguments for function 1 of item N
      • N: List of Arguments for function N of item N

highlightItem(self, item)[]

This method's purpose is to indicate on the interface which selection is currently "active" to the player. Called by the menuControl method, the method goes through the list of options available to the player to see if anything is currently selected. If so, the method will go ahead and "de-highlight" the active item. Regardless of whether or not an item is deactivated, the method will then go through to the item indicated in its argument and "highlight" it; this can involve a change in the color of text or the replacement of a graphical element with another graphical element. Prior to going out of scope, the method ensures the indicated "highlighted" portion is properly rendered on screen and that any sounds associated with the interface for the highlighting of a new item are played.

activateItem(self, item)[]

This method's purpose is to activate the currently selected interface item. Called by the menuControl method, the method goes to the item indicated in its argument and activates it(usually causing the executiion of a piece of code that will cause a Check, pull up another menu, or bring up a new interface; this can also be used to activate an interface's commands while the interface remains active). If there are any sounds associated with the action indicated, the method ensures they are played before going out of scope.

menuControl(self, task)[]

This method's purpose is to provide Panda with a task that monitors the keyboard and mouse for inputs, and sends calls to either highlight or activate items as necessary. When the method detects an input, it checks through the list of valid hotkey commands for the current interface. If a matching input command is found, it checks the instructions associated with that hotkey, and either sends a call to highlight a new area on the present interface (if the command instructs the interface to select a new "active command", or to activate that command.

destroy(self)[]

This method's purpose is to cause its associated interface to destruct, generally used before a new interface is activated. The method wipes out the contents of its hObjects dictionary (removing all visual elements) and sends a call to the InterfaceHandler to reset the hotkeys to none. It then destroys the frame in which the interface is set and deactivates the interface's self-reference, allowing the Interface object to be garbage collected immediately after the method goes out of scope.


Toybox Class[]

__init__(XML)[]

The argument flag is designed to be a way of indicating whether the game will be set to load data from XML files or from the saved toybox file. While the game is being tested, the flag should be set to True to load from XML. When the game is ready for public dissemination (including any public alpha tests), this flag should be set to False.

The object's initializer creates, in order, an Onomastikon object, an Encounter_Handler object, a Trader object, a gameClock object, and a Player object. For each object (except the Player object), the value of the initializer's flag is passed on to the initializer of the created object; this is intended to instruct the object whether or not to go ahead and load its data through XML or not. If the initializer's flag is set to True, the method is allowed to go out of scope after creating all objects. Otherwise, a call is made to the loadData() method prior to the method going out of scope.

loadData()[]

This method's purpose is to load up data from the saved Toybox object, bypassing the need for the created objects to load their data directly from XML files. It functions simply by opening the saved pre-generated Toybox object file into a local object, and then overwriting the default objects created during the initializer routine with those from the saved file (this would be the onomastikon object, Encounter_handler object, Trader object, gameClock object, and default Player object). Once all the objects have been overwritten, the saved pre-generated Toybox object file is closed out and the method goes out of scope.


XML[]

Of the objects in the Core Module, the only one that requires any XML data for its functioning is the InterfaceHandler object. The InterfaceHandler object, like most of the other objects in the game, is largely XML driven; this will help keep it flexible up until SF3's design is finalized (i.e. in-game interfaces and functionality can be added and removed from the game freely, based upon what data is available in the XML files). The InterfaceHandler object itself requires direct access to two types of XML files. One type is a specific file that contains data on the interfaces that will be in the game (the file "master_interface_data.xml"), while the other type is the raw data on the interfaces themselves (the file type "(interface_name.xml)"). The following briefly goes over what data is located in these XML files.

master_interface_data.xml[]

The file "master_interface_data.xml" is designed as a listing of the available interfaces that will be present in the game, used by the IntefaceHandler object as a means of controlling which interface is currently active in the game; it is thus a key bit of data necessary for the game's functioning. Under the root element, entries in the XML file are empty elements with the name "interface". These elements have exactly two mandatory attributes, "id" (which is used to seed the _INTERFACE enums in the InterfaceHandler object and identifies the specific interface involved), and "object" (which identifies the specific Interface object that needs to be activated when it is indicated to be active by the InterfaceHandler object.

Two additional, single-use mandatory elements are included with this file, meant for use by the Preloader object. The first of these is identified with the name "openinganim", which has a single, mandatory attribute called "name" (used to hold the file name of the game's opening animation sequence, which plays once the game is ready to begin). The second of these is identified with the name "preload", which has two attributes, "gamename" (used to hold the Preloader's loading message) and "load" (used to hold the list of files that will need to be preloaded, separated by commas).

Sample structure of the master_interface_data.xml file: 


<?xml version="1.0" encoding="UTF-8"?>
 <root table-name="master_interface_data" version="0.1">
  <openinganim name="SF3OpeningAnimation.avi" />
  <preload gamename="Loading Starflight III..." load="../toybox.dat, ../Models/intrepid.egg, ../Music/SF3Theme.mp3" /> 
  <interface id="MAIN-MENU" object="MainMenu_InterfaceHandler" />
  <interface id="STARPORT" object="Starport_InterfaceHandler" />
  <interface id="OPERATIONS" object="Operations_InterfaceHandler" />
  <interface id="PERSONNEL" object="Personnel_InterfaceHandler" />
  <interface id="BANK" object="Bank_InterfaceHandler" />
  <interface id="FLEET_CONFIG" object="FleetConfig_InterfaceHandler" />
  <interface id="TRADE" object="Trade_InterfaceHandler" />
  <interface id="CASINO" object="Casino_InterfaceHandler" />
  <interface id="LOUNGE" object="Lounge_InterfaceHandler" />
  <interface id="STARSHIP" object="Starship_InterfaceHandler" />
  <interface id="TERRAIN_VEHICLE" object="Vehicle_InterfaceHandler" />
  <interface id="CAPTAINS_LOG" object="Log_InterfaceHandler" />
  <interface id="STARMAP" object="Starmap_InterfaceHandler" />
  <interface id="TACTICAL" object="Tactical_InterfaceHandler" />
 </root>

(interface_name).xml[]

The file type "(interface_name).xml" is designed as a blueprint for the functioning of an in-game interface. This includes positioning of visual elements of the interface as well as information on sound effects associated with the interface and control inputs. This is being handled via XML rather than being hard-coded for the sake of any future games where a different set of menu options might be required by an interface (SF2 is a good example, where there's an option on the Starship Interface's Captain's Menu for the Uhl Weapon and no option for the Ship's Log). Under the root element, entries in the XML file may be under of one of the following categorical elements:

  • visual_elem: Used to identify a "visual element" used by the interface. These are meant to indicate the visual pieces of ther interface itself, not any other items that may happen to appear on screen at the same time as the interface (like alien ships when the Encounter Interface is active, etc.). All interfaces must contain at least one visual_elem element.
  • main: Used to identify a "main level" menu option. All main elements have a single attribute, called name, which indicates how the option will appear in the interface; for the main menu of the Starship Interface, these must have a value equal to the name of one of the Senior Officer positions. Menu elements are optional depending on the interface and may have one or more option sub-elements.
    • option: These are used to contain a set of specific sub-menu functions under a main level entry. They are optional depending on the interface and may have one or more suboption elements.
      • suboption: These are empty elements used to denote additional sub-menu options under a specific option menu.
  • keystroke: These are used to identify commands to carry out when a given key is pressed on the keyboard (this can also be used for mouse clicks and movement). Keystroke elements are optional depending on the function of the interface. All keystroke options are fed to the InputManager when the interface becomes active.
  • sound: These are used to identify specific sounds associated with the interface itself, and are always optional.
  • animOn: This is an optional element that sets a command to play a given animation sequence when the interface is first activated.
  • animOff: This is an optional element that sets a command to play a given animation sequence when the interface is being deactivated.

Actual entries are empty elements under each of these categories (except where indicated otherwise). Relevant data on each is stored in their individual attribute sets.

The following describes the attributes used by visual_elem elements:

  • filename: This indicates the file name of the visual element to load.
  • pos: This indicates the position at which the element will be located on screen.
  • hpr: This indicates the heading, pitch and roll of the visual element when it is loaded on screen.
  • scale: This indicates the x, y, and z-axis scaling to be applied to the visual element when it is loaded on screen.
  • offset: This indicates the x, y, and z-axis offset that needs to be applied to the model when it is loaded on screen.
  • parent: This indicates another visual element in the interface to which the visual element needs to be parented. If there is no such element, this needs to have a value of None.

The following describes the attributes used by the option and suboption sub-elements:

  • name: Mandatory. As with the main element, this indicates how the option will appear in the interface. If an option may be displayed as more than one option, those options are separated by commas.
  • display: Mandatory if and only if the "name" attribute has more than one option. This indicates the name of the method that will be used to determine which name option will appear on the interface.
  • exec: Mandatory. This indicates the name of the method that will be executed in the event this particular menu option is selected by the player.
  • include: Optional. This indicates the file name of a file which contains a custom method that will be called upon activation of the menu option by the player.
  • hotkey: Mandatory. This indicates what key may be pressed on the keyboard to instantly activate the method or include file.
  • click: Optional. This indicates which areas of the screen may be clicked upon to instantly activate the method or include file.
  • pos: Optional. This specifies the position at which the option will appear on the interface.
  • color: Optional. This overrides the default value and specifies the color of the text of the menu option, listed in hexidecimal. All menu options default to #ffffff, or white.
  • sound_h: Optional. This indicates a sound file to load into the Jukebox, which will be played when the menu option is highlighted.
  • sound_a: Optional. This indicates a sound file to load into the Jukebox, which will be played when the menu option is activated.

There may be only instance of each attribute in the entry; if subsequent attributes are encountered, the last one will be used. Both "hotkey" and "click" are mandatory methods; any entry lacking them will be completely ignored by the XML handler. An entry must include either "method" or "include", but cannot contain both; entries lacking them or having both methods will be completely ignored by the XML handler. If "include" is used, the XML handler will check for the existence of the indicated file and will ignore the entry if the file is not found. A similar method may be used to determine whether a proper method name has been indicated for entries using the "method" attribute.

The following describes the attributes used by the keystroke elements:

  • key: Mandatory. This indicates the specific key or mouse button to assign a specific command.
  • command: Mandatory. This indicates the command to execute when the indicated key is activated.

The following describes the attributes used by the sound elements:

  • file: Mandatory. This indicates the name of the sound file to be passed to the Jukebox
  • loop: Mandatory. A flag, this indicates whether the sound is supposed to loop after being played.
  • repeat: Optional. This indicates a length of time after the sound has stopped playing for the sound to play again.

The following describes the attributes used by the animOn and animOff elements:

  • sequence: Mandatory. A tuple, this indicates an animated sequence to play. The first item in the tuple is always the filename; if no additional items are present in the tuple, it is assumed the animation plays in all instances of the interface's activation/deactivation as the case may be. Additional elements beside the first are to indicate other interfaces; the animation will only play if the indicated LAST_INTERFACE is in the list when the interface is being activated (or the CURRENT_INTERFACE when the interface is being deactivated).

Sample structure of the (interface_name).xml file: 

<?xml version="1.0" encoding="UTF-8">
 <root table-name="ship_interface" version="0.1">
  <visual_elem filename="avs1_bg.bam" pos="543,0,0" hpr="0,0,90" scale="0.25,1,0.25" offset="400,0,300" parent="None" />
  <main name="Captain">
   <option name="Launch, Land" display="checkLaunchLand" exec="launchLand" hotkey="f1" click="549, 441, 560, 463" sound_h="selectscroll.wav"<br/>   sound_a="activate.wav">
    <suboption name="Select Site" hotkey="f1" click="549, 441, 560, 463" exec="selectSite" sound_h="selectscroll.wav" sound_a="activate.wav" />
    <suboption name="Descend" hotkey="f2" click="549, 471, 560, 493" exec="descendToPlanet" sound_h="selectscroll.wav" sound_a="activate.wav" />
    <suboption name="Abort" hotkey="f3" click="549, 501, 560, 523" exec="abortLanding" sound_h="selectscroll.wav" sound_a="activate.wav" />
   </option>
   <option name="Cargo" hotkey="f2" click="549, 471, 560, 493" exec="lookAtCargo" sound_h="selectscroll.wav" sound_a="activate.wav"/>
   <option name="Bridge" pos="552,0,584" color="#8080ff" hotkey="f7" exec="exitMenu" sound_h="selectscroll.wav" sound_a="activate.wav"/>
  </main>
  <keystroke key="arrow_up" command="scrollMenuUp"
  <sound file="engineHum.wav" loop="True"
  <sound file="bridgeChirp1.wav" loop="False" repeat="5"
  <animOn sequence="teleportAboard.avi, STARPORT"
  <animOff sequence="shipLaunch.avi, PLAN_EX"
 </root>

Module Status[]

This is current as of August 14, 2011.

This module is currently in the final design phases; while specific descriptions of the intended functions of modules have yet to be written, the remainder of the module's basic description is complete at this point. Further design work on this module has been frozen for the time being, and will remain so until I'm ready to begin method descriptions for all remaining extant modules. We'll need a few more methods here to be sure, but I'm satisfied enough in the level of completion of the module at this point to move on.

NEXT: Basic Combat Module
PREVIOUS: Modules, Interfaces and Engines
TOP

Community content is available under CC-BY-SA unless otherwise noted.
Advertisement

Fan Feed

More Starflight III Wikia