 |
freedroidRPG
1.0+git
The best game in town
|
|
freedroidRPG
1.0+git
The best game in town
|
With repeated editing or refactoring of FDRPG dialog files, circumstances arise where sections of the dialog are no longer reachable during game play. Editing of dialog files to correct misconnected or unconnected dialog code can be a difficult proposition.
By parsing a dialog file and transforming the data into graphic output, dialog developers and maintainers now have a tool to "visually" ensure circumstances above do not occur. Freedroid RPG Dialog Node Mapper( FDDNM ) tool parses dialog files and can producing graphic output in several formats, all to indicate inter-connectivity and viability of dialog file nodes.
Freedroid Dialog Node Mapper is a standalone program that is not compiled along with Freedroid RPG. Users/Developers must compile this tool separately.
Note to Freedroid RPG developers/maintainers
Changes to dialog structure or variables will require that source for this tool be reviewed and if necessary updated.
For BSD and MacOS X users, you must use gmake to build the FDDNM tool. Any reference below to make should be replaced with gmake command. The gmake tool is available for your platform from ports|packages repository. All other platforms can use make.
Execute the sequence below to configure and build the FDDNM tool.
cd [FDRPG root]/tools/fddnm ./autogen_fddnm.sh ./configure make
The tool is not meant to be installed on the users system, but remain resident in the FDRPG root directory.
A gitignore file has been established that will exclude the tool, object files and any program output (dot, png, svg, et al)
from being accidentally included into the FDRPG git tree.
After successful compile and link, the executable fddnm can be used to process FDRPG dialog files.
Usage:
fddnm [-h|--help]
Show help message for fddnm
fddnm [-q] [-P | --verboseprint]
[-D | --verbosedot] [-G | --group]
[-H | --extrainfo] [-I | --individual]
[[-s | --dirsearch=]arg] [[-o | --diroutput=]arg]
[[-F | --fileprefix=]arg] [[-L | --layout=]arg]
[[-T | --format=]arg] [[-d | --dialog=]arg]
[-q]
Quiet - no output to stdout
[-P | --verboseprint]
Print parsed dialog data to text file. Text file placed in output directory.
Note - output file will be named "[PREFIX][Dialog Name]_VPARSE.txt"
[-D | --verbosedot]
Print analyzed dialog data used to create graphic to text file. Text file placed in output directory.
Note - output file will be named "[PREFIX][Dialog Name]_VDOT.txt"
[-G | –group]
Grouping is used as a layout hint to graphviz.
Enables nodes connected to "end_dialog" to be grouped closer to "end_dialog" node.
(E.g. Dixon or Tania graphs produce better output with this setting enabled).
[-H | –extrainfo]
enable HTML-like dot output - includes presentation of extra node information.
(See below for an example of the output produced.)
[-I | --individual]
Program is to parse and process all dialog files individually.
Any references to "include" another dialog file will not be processed. (e.g. 614-cryo.lua)
[-s | --dirsearch=]arg
Directory arg will be searched for dialog files (DEFAULT: [FDRPG root]/dialogs)
[-o | --diroutput=]arg
Directory arg will be used to store program output (graphic or text) (DEFAULT: current directory)
[-F | --fileprefix=]arg
arg will be the validated text used as a prefix for output file names.
Note - see the second entry "portable_name" in the Boost Filesystem Portability Guide for limitations
[-L | --layout=]arg
arg is the direction of graph layout. One of [ TB (DEFAULT) | LR | RL | BT ]
Note: see Graphviz rankdir attribute for details
[-T | --format=]arg
arg is the graphic format of output. One of [ none | dot | jpg | png | svg (DEFAULT) ]
[ | -d | --dialog=]arg
arg is the file name of dialog to be parsed without its lua file extension.
No supplied dialog names implies all dialogs in search directory are to be parsed.
More than one dialog name can be used without the switch as the use of the switch is optional.
Usage Examples:
All examples assume current directory is [FDRPG root]/tools/fddnm
./fddnm -Tpng
./fddnm -Tdot Tania
./fddnm -Tsvg -FTESTING_ -o/home/user -LLR DocMoore
Current implementation uses the following colour scheme:
blue parent node calls "show" child node green parent node calls "next" on child node orange parent node calls "show_if" child node red(dashed) parent node calls "hide" child node purple parent node is calling end_dialog
Dialog nodes that are apart of a dialog topic are grouped inside a black line box.
Black lines are drawn from the dialog start to any "FirstTime" and "EveryTime" dialog nodes.
During parsing printout to console or review of verbose output, the user may notice the following text:
Tania Detected 48 nodes Parsed 49 nodes
This output indicates that the dialog contains within code a call to end_dialog. To allow lines (or edges) to be drawn from the calling node, an "artificial" end node is appended to the dialog node data. As a result of the addition of an end_dialog node, the Parsed node count will be set to (Detected Node Count + 1).
Using the command line switch [-H | –extrainfo] will result in diagrams similar to above. The only change is the inclusion of text ( text="..." for each node in the dialog file). Currently, the line wrap value is set for 30 characters.
Diagram above shows node99 as having no show, next or show_if connections leading to this node. The node is not a child of any other nodes. Although the node has a hide command (red arrow), this is in fact a dangling node.
There are two possible interpretations: a) FDDNM has a bug (not unlikely considering the tool is parsing fluid lua language without interpretation) or b) the node in question is unreferenced in code. Which situation is occurring can be verified by doing a search of the file similar to...
grep -n "nodeXX" dialogfile.lua
or similar code tools. If after the search no references can be found to show, next or show_if of "nodeXX" then the node is unreferenced (or not called) in the dialog. A developer or dialog writer should view this kind of output as an error in the dialog file. This is a type of error FDDNM tool is trying to highlight.
Current implementation has issues with some node parsing that involve programmatically determining the node value to be used. The dialogs involved include Tamara, Engel (bot parts topic) and Ewald (gamble topic). This problem will be corrected in a future release.
There are known issues when running address sanitizer or valgrind against the fddnm sources. These issues stem from code within graphviz and do not appear to be related to fddnm. This is an ongoing issue that is being monitored.
If you receive an error during config that the boost libraries could not be found, do the following:
./configure CPPFLAGS="-I/folder/path_boost_folder" LDFLAGS="-L/folder/path_libboost_system"
If you receive an error during configure that the graphviz libraries could not be found, attempt the following:
./configure CPPFLAGS="`pkg-config libgvc --cflags`" LDFLAGS="`pkg-config libgvc --libs-only-L`"
./configure CPPFLAGS="-I/folder/path_gvc_h" LDFLAGS="-L/folder/path_gvc_so/"
fddnm.cpp: In member function ‘void fddnm::graphivOutput(const string&, const string&)’:
fddnm.cpp:653:38: error: invalid conversion from ‘const char*’ to ‘char*’ [-fpermissive]
Agraph_t* G = agmemread(userDotData);
^
In file included from /usr/include/graphviz/types.h:717:0,
from /usr/include/graphviz/gvc.h:20,
from fddnm.cpp:39:
/usr/include/graphviz/graph.h:165:22: note: initializing argument 1 of ‘Agraph_t* agmemread(char*)’
extern Agraph_t *agmemread(char *);
^
This indicates that the graphviz library requirement has not been met. See requirements above and follow the instructions for your distribution to update graphviz.Undefined symbols for architecture x86_64: boost::...there is a difference in compiler used to build boost library and FDDNM. ( http://stackoverflow.com/a/20015083 )
otool -L /opt/local/lib/libboost_system-mt.dylibThe command should report back libboost_system library linkage to either libc++ (clang) or libstdc++ (gcc).
./configure ... CXX="[ g++ | clang++ ]"
1.9.5