Documentation for progrutils.py

Warning: This documentation was generated from the comments in the source code (using progrutils.documentPyFile()), with a few tweaks, under the principle that poor documentation is better than no documentation. In case of ambiguity, please refer to the code itself.

FFX Programming Utilities, v.1.3

By Épiméthée

A collection of helper functions related to debugging FFX Python scripts.

Events

startTimer(countdown = 10, increment = 1, verbose = 1, funct = '')

A very simple timer, displaying the countdown in the console and, optionally,
call immediately a function. A sound will play when the time expires.
Requires a from progrutils import *
Works only with integer values for the seconds.

OnEventTest(event)

For testing results of an event function call. This will print out the value of various event parameters.

Object attributes

FFQ_GetAttrForAll(whichAttribute)

attribute tests
get the value of a selected object attribute for everyone on the level
use with care, since if the attribute is not set for a character, FF will pop an error message box!

FFQ_SetAttrForAll(whichAttribute,newValue)

set the value of a selected attribute for everyone on the level

FFQ_SetAttrForAllRandom(whichAttribute,rangeStart,rangeEnd)

set the value of a selected attribute to a random value for everyone on the level

FFQ_RestoreAttrForAll(whichAttribute)

restore the value of a selected attribute for everyone on the level

Information

whoIsThat(onoffvalue=1)

Based on the WHO AM I idea used in FFX 1.3
Attach a "WHO IS" custom command to every hero. When using the custom command on an object, info is printed out to the console/script.log.

startFX(char, sparks = "effect_ffxabsorbstrength", pos = "Bip01 Spine")

a simple method to quickly test effects in-game

stopFX(char)

Character attributes

printRemovableAttributes()

(Can be run outside the game)
Prints to script.log (or to the console if used outside the game) a list of which FFX attributes are removable and which are not.
added FFX 3.2.0 alpha

getRemovableAttributes(remove = 1, basePath = "C:\\Program Files\\Irrational Games\\Freedom Force vs The 3rd Reich\\ffx3")

(Can be run outside the game)
Returns a list of removable (or non-removable if 'remove' parameter set to 0) FFX attributes.
Note that it is quite slow, as it need to parse thousands of items; too bad we can't use inspect, introduced in Python 2.1...
Notes/bugs:
- A function whose name starts with 'init' and which is all in lowercase will falsely register as an FFX attribute.
added FFX 3.2.0 alpha build 0, updated progrutils 1.0 to be run from outside the game.

Documentation

documentPyFile(file, output = 'htm', css = '../manual.css', txtSeparator = '\n\n\n')

(Can be run outside the game)
Create a rough plain text or HTML file listing top-level functions, variables and classes, plus the top-level #-style comments above them.

Arguments:

- file: full path name of the source file
- output: extension name-format, either 'txt' or 'htm'
- css: if output is set to 'htm', source of the external cascading style sheet file to be linked to; if set to any value except '', the line

<link rel="stylesheet" href="css filename" type="text/css" />

will be added to the HTML file header. It defaults to FFX 3.2 documentation's manual.css caled fro a subfolder.
- txtSeparator: if output is set to 'txt', the text to be used to visually separate the various functions, classes and variables. Default is three consecutive line-breaks.

How it works:

The function reads your source .py file and looks for the following items:
- Section Headers: Any block starting a number sign ("#") followed by at least four identical characters (which can be "#" too).
- Object Class Definition: a line beginning with the word "class ". Comments above this line are considered to be related to the current class.
- Function Definition: a line beginning with the word "def ". Comments above this line are considered to be related to the current function.
- Variable Definition: a line beginning with a non-reserved word. Comments above this line are considered to be related to the current variable.

Example:

Launch an external console or the FF built-in one.

You might need to start by telling Python to look for files in your folder:

>>> import sys

>>> sys.path.append("C:\\Program Files\\Irrational Games\\Freedom Force vs The 3rd Reich\\ffx3\\Missions\\Scripts")


Starting FFX Programming Utilities 1.3

FFX Programming Utilities running outside the game.

<module 'progrutils' from 'C:\Program Files\Irrational Games\Freedom Force vs The 3rd Reich\ffx3\Missions\Scripts\progrutils.py'>

If you're running outside the game, the above errors are normal. No worry.

>>> progrutils.documentPyFile("C:\\Program Files\\Irrational Games\\Freedom Force vs The 3rd Reich\\ffx3\\Missions\\Scripts\\myfile.py")

documentPyFile(): C:\Program Files\Irrational Games\Freedom Force vs The 3rd Reich\ffx3\Missions\Scripts\myfile_doc.htm created.

Moving the file to C:\Program Files\Irrational Games\Freedom Force vs The 3rd Reich\ffx3\Manual\ would have it use the manual.css formatting style used in the FFX manual.

Notes/bugs/limitations/etc.:

- This function attempts to keep things very basic, especially since each FFX coder has a very different coding style. If you need something fancier, look into the PyDoc module, which is part of the Python distro. Another option might be the third-party Doxygen.
- The output file WILL need to be edited manually afterward, as, for example, any comment before recognized code is supposed to belong to it.
- Second-level functions (i.e., inside classes), variables and comments aren't supported.
Exception: Comments nested inside functions or classes will still be considered first-level if the # is put at the begining of the line
(as when using an editor's automatic commenting out feature) instead of following the current nesting level. Ex.:

def helloWorld():

    print "hello, world!'

    #print "indented comment"

##    print "non-indented comment"

will output

helloWorld()

print "non-indented comment"

- Triple quote-style comments aren't supported either, since they're not much used in FF/FFX scripts and detecting them correctly would have required a wee bit more work. (Yes, I know that they are the correct way to document functions automatically...)
- Only the first line of variables is recognized. Again, it would require more work; beside the value of documenting the content of
long lists, tupples or dictionnary outside the source code file itself is rather limited. In fact, variables are documented mostly
so the comments belonging to them can be recognized as such when editing the output file.
- A sequence of four identical characters (except spaces or tabs) after the initial number-sign character(s) is considered as being the start of a new section.
- Only the most basic special characters are converted to HTML entities ("<", ">", "&" and some "\" variants), so don't expect to get valid XHTML 1.1 syntax out of the box. :P - If there are special Python characters in your comments, they might be erroneously converted.
- Multiple consecutive spaces are rendered as a single space. Indenting in commented-out code isn't preserved either.
- This function won't win any prize for coding elegance...

convertLineEntities(line)

convert problematic characters within a line to HTML entities and escaped characters

isLineEmpty(line)

return 1 if the line is empty (the string contains only a return and possibly spaces or tabs)