title: Conversion Tool System
author: cdunde

The <a href="adv.conversion.html#conversiontool">Conversion Tool</a> is the most detailed and
flexible of the <a href="adv.conversion.html#__top__">three tools above</a>
because it not only can use the other two, it also is completely modular to allow individual
module component updates and new modules to be added. Here we will cover the structure of this
system to encourage further development of it.
<img border=1 align=right>conversiontoolsys1.png</img>

<b><u>System Hierarchy :</u></b> As shown in the image to the right, all of this systems files are located
in the <b>QuArK\plugins</b> folder at its current development stage.

The only two exceptions to this is the <b>QuArK\quarkpy\qmacro.py</b> file which is used to place the
<a href="adv.conversion.html#conversiontool">Conversion Tool</a> on QuArK's Explorer Main Files menu.
Comparing version 1.27 and 1.28 of this file will disclose the first part of the changes needed to do so.
The second part is in the plugins\ent1conversiontools.py file at the very bottom

The other file is the <b>QuArK\quarkpy\qentbase.py</b> file that did not require any changes and is only used
at the same location in the plugins\ent1conversiontools.py file to pass the menu item to the qmacro.py file.
<ul>
<g><b><u>1st Level Hierarchy :</u></b></g><br>
<li><b>ent1conversiontools.py :</b> This is the main control file. It has <b>4</b> major functions:

<b>1</b>) It produces the main dialog where all of the core selections are made at the very beginning
(<a href="adv.conversion.html#conversiontool">shown above</a>).<br>
<b>2</b>) It processes these selections to <g>trim</g> and provide only that part of the input as needed.<br>
<b>3</b>) First it will create a new <g>game folder</g> in <g>QuArK's main directory folder</g>
to handle temporary work files (that are removed later, if all goes well)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;and place the new
<a href="adv.intro.html#qrk">.qrk</a> files into.<br>
&nbsp;&nbsp;&nbsp;&nbsp;
If something should go wrong, the temporary work files remain in the new game folder as a means to help
track down the problem and rectify it.<br>
&nbsp;&nbsp;&nbsp;&nbsp;
It then <g>steps through</g> each <b>files to make</b> selection of code creating the more <g>simple</g>
type of <a href="adv.intro.html#qrk">.qrk</a> files, the <g>Data(gamename).qrk</g> and<br>
&nbsp;&nbsp;&nbsp;&nbsp;
<g>UserData (gamename).qrk</g> files, which are copies of the selected <a href="adv.conversion.html#conversiontool">Game Engine type:</a>
files that was chosen in its <a href="adv.conversion.html#conversiontool">main dialog</a>.<br>
&nbsp;&nbsp;&nbsp;&nbsp;
It also produces its own <g>Secondary Dialog</g> for the selection of the <g>Default Room Textures</g>
to be used in the <g>Data(gamename).qrk</g> file.<br>
&nbsp;&nbsp;&nbsp;&nbsp;
As these files are copied things such as the <g>game name</g> and <g>type of Pak file</g>
it uses are exchanged in the file's copy.<br>
<b>4</b>) It calls on the <b>2nd & 3rd Level</b>
files and passes the input data to those modular sections for creation of the particular
<a href="adv.intro.html#qrk">.qrk</a> file that they deal with.<br>
&nbsp;&nbsp;&nbsp;&nbsp;
Each time a <b>2nd or 3rd Level</b> file has complete crating its <a href="adv.intro.html#qrk">.qrk</a> file
the processing returns to the <g>ent1conversiontools.py</g> control file to continue<br>
&nbsp;&nbsp;&nbsp;&nbsp;
on to the next step until it reaches the end where it displays a message that
all of the selected files have been created successfully.<br>
&nbsp;&nbsp;&nbsp;&nbsp;
If a problem does exist with one or more of the files due to a selection in the
<a href="adv.conversion.html#conversiontool">main dialog</a>, those selections can be changed<br>
&nbsp;&nbsp;&nbsp;&nbsp;
and the individual files re-created as long as the <a href="adv.conversion.html#conversiontool">main dialog</a>
has not been closed. Other wise it will reset the entire system and clear all selections.
</ul>
<ul>
<g><b><u>2nd Level Hierarchy :</u></b></g><br>
<li><b>ConvertToolQ3typeEnts.py :</b> This creates the <g>(gamename)Entities.qrk</g> file for a
<a href="adv.conversion.html#conversiontool">Quake 3 type game engine</a>.<br>
It can use <g>.def, .cpp</g> or any other entity definition file that uses the <b>keyword</b> <g>/*Quaked</g>
to designate a new entity.<br>
It also produces its own dialog input for selection of aditional items to include in that
<a href="adv.intro.html#qrk">.qrk</a> file.<br>
It then calls on the <g>AddSpecificsList.py</g> and <g>entdef2qrk.py</g> 3rd level files below to add the
entity Specifics detail data<br>
as well as create its own <g>Color Setting</g> and <g>Selection Lists</g> code for such things as
<g>Game Models</g>, <g>Game Sounds</g> and<br>
<g>Game Music</g> if those items are seleced from its dialog to be included in the <a href="adv.intro.html#qrk">.qrk</a> file.


<li><b>ConvertToolD3typeEnts.py :</b> This creates the <g>(gamename)Entities.qrk</g> file for a
<a href="adv.conversion.html#conversiontool">Doom 3 type game engine</a>.<br>
It can use <g>.def, .cpp</g> or any other entity definition file that uses the <b>keyword</b> <g>entityDef</g>
to designate a new entity.<br>
It also produces its own dialog input for selection of aditional items to include in that
<a href="adv.intro.html#qrk">.qrk</a> file.<br>
It then calls on the <g>ConvertToolGet_tokens.py</g> 3rd level file below to assist in creating the
entity Specifics detail data<br>
as well as create its own <g>Color Setting</g> and <g>Selection Lists</g> code for such things as
<g>Game Models</g>, <g>Game Sounds</g> and<br>
<g>Game Music</g> if those items are seleced from its dialog to be included in the <a href="adv.intro.html#qrk">.qrk</a> file.
</ul>
<ul>
<g><b><u>3rd Level Hierarchy :</u></b></g><br>
<li><b>AddModelEnts.py :</b> This file is called on directly by the <g>ent1conversiontools.py</g> file to make the
<g>(gamename)ModelEntities.qrk</g> file.
<li><b>AddShaderList.py :</b> This file is called on directly by the <g>ent1conversiontools.py</g> file to make the
<g>(gamename)Shaders.qrk</g> file.
<li><b>AddSpecificsList.py :</b> This file is used by the <g>ConvertToolQ3typeEnts.py</g> file
and works in conjunction with the <g>entdef2qrk.py</g> file below<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
to create the final<g>(gamename)Entities.qrk</g>
file for a <a href="adv.conversion.html#conversiontool">Quake 3 type game engine</a>.
<li><b>AddTextureList.py :</b> This file is called on directly by the <g>ent1conversiontools.py</g> to make the
<g>(gamename)Textures.qrk</g> file.
<li><b>ConvertToolGet_tokens.py :</b> This file is <b><g>Tool</g></b> file used by both the
<g>ConvertToolD3typeEnts.py</g> and <g>AddShaderList.py</g> files above for data processing.
<li><b>entdef2qrk.py :</b> This file is used by the <g>ConvertToolQ3typeEnts.py</g> file before the
<g>AddSpecificsList.py</g> file above to create a temporary <a href="adv.intro.html#qrk">.qrk</a> file<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
that it uses to merge all of the collected entity Specific items detail data with
to create the final <g>(gamename)Entities.qrk</g> file.
</ul>

As you can see, all of these modular files, including the control file, can be updated, improved upon
or added to for any future QuArK game file support needs.

In addition, the code has been written to process multiple levels of folders and their sub-folders
as well as allowing the input for multiple texture and sound type files in the dialogs. All of this
is displayed to the user as they move along, in the way of individual <g>Hints</g> for each input
to act as a guide and assist them.
