Jump to content

XmlTools/Full documentation: Difference between revisions

XmlTools/Full documentation (view source)

Revision as of 16:41, 14 March 2016

2,024 bytes added ,  14 March 2016
overall copy-edit; lowered all headers one level so that level 1 isn't being used (that is reserved for the article title); grammar edit to first half of article
m (Iritscen moved page XmlTools/Full Documentation to XmlTools/Full documentation without leaving a redirect: Unneeded capitalization.)
(overall copy-edit; lowered all headers one level so that level 1 isn't being used (that is reserved for the article title); grammar edit to first half of article)
Line 1: Line 1:
=Overview=
This page lists all XmlTools commands with examples. It is the full version of the summary of XmlTools options found on the [[XmlTools|main page]]. The main page also offers a beginner's guide to this program's syntax and links to pages that explain the concepts behind XML modding.


This page describes all XmlTools options with examples. It is needed to avoid too much content in the XmlTools [[XmlTools|main page]].
{{TOClimit|3}}


=Command-line operations=
==Command-line operations==
These are the commands that you can pass to XmlTools when directly calling it from the command line.


==Overview==
===--add-values===
====Description====
This operation allows you to add new XML values to an existing XML element that contains a list of values. The values should be space-separated and contained within quotes.


==--add-values==
Oni's game data contains various bitsets that are used to indicate the on/off status of attributes that can pertain to that object. For instance, characters in the game can have various flags such as Unkillable turned on for them. In OniSplit's XML output of this data, the flags are given names and listed within quotes as a single string. --add-values and --remove-values were designed to edit these XML representations of bitsets.
 
===Description===
 
This operation allows you to add new XML values to existing XML elements. The values should be space separated and contained within quotes.


Usage:
Usage:
<tt>XmlTools --add-values --new-val "new values"</tt>
<tt>XmlTools --add-values --new-val "new values"</tt>


===Example===
====Example====
Let's say you want to add the Unkillable and the NonCombatant flag to A_L18 character.
Let's say you want to add the Unkillable and the NonCombatant flag to the character A_L18.




Line 24: Line 23:


{| style="margin: 1em auto 1em auto;" <!-- Centers table -->
{| style="margin: 1em auto 1em auto;" <!-- Centers table -->
! style="width: 50%;" | XML Original
! style="width: 50%;" | XML Before
! style="width: 50%;" | XML After Command
! style="width: 50%;" | XML After
|-
|-
|
|
Line 69: Line 68:
|}
|}


==--remove-values==
===--remove-values===
====Description====
This operation allows you to remove XML values from an existing XML element that contains a list of values. The values should be space-separated and contained within quotes.


===Description===
Oni's game data contains various bitsets that are used to indicate the on/off status of attributes that can pertain to that object. For instance, characters in the game can have various flags such as Unkillable turned on for them. In OniSplit's XML output of this data, the flags are given names and listed within quotes as a single string. --add-values and --remove-values were designed to edit these XML representations of bitsets.
 
This operation allows you to remove XML values from existing XML elements. The values to remove should be space separated and contained within quotes.


<tt>Usage: XmlTools --remove-values --current-val "current values to remove"</tt>
<tt>Usage: XmlTools --remove-values --current-val "current values to remove"</tt>


===Example===
====Example====
 
Let's say you want to remove the UpgradeDifficulty and InfiniteAmmo flags from character D_S82.
Let's say you want to remove the UpgradeDifficulty and InfiniteAmmo flags from D_S82 character.




Line 86: Line 84:


{| style="margin: 1em auto 1em auto;" <!-- Centers table -->
{| style="margin: 1em auto 1em auto;" <!-- Centers table -->
! style="width: 50%;" | XML Original
! style="width: 50%;" | XML Before
! style="width: 50%;" | XML After Command
! style="width: 50%;" | XML After
|-
|-
|
|
Line 131: Line 129:
|}
|}


==--replace-value==
===--replace-value===
 
====Description====
===Description===
This operation allows you to execute a find/replace on existing XML elements, changing one specific value to another.
 
This operation allows you to replace 1 XML value from existing XML elements.


<tt>Usage: XmlTools --replace-value --current-val "currentValue" --new-val "newValue"</tt>
<tt>Usage: XmlTools --replace-value --current-val "currentValue" --new-val "newValue"</tt>


===Example===
====Example====
Let's say you want to swap all the w1_tap weapons from characters to w8_mbo.
Let's say you want to find all the w1_tap weapons currently assigned to characters and change them to w8_mbo.




Line 147: Line 143:


{| style="margin: 1em auto 1em auto;" <!-- Centers table -->
{| style="margin: 1em auto 1em auto;" <!-- Centers table -->
! style="width: 50%;" | XML Original
! style="width: 50%;" | XML Before
! style="width: 50%;" | XML After Command
! style="width: 50%;" | XML After
|-
|-
|
|
Line 192: Line 188:
|}
|}


==--replace-all-values==
===--replace-all-values===
 
====Description====
===Description===
This operation allows you to replace the values on all matching XML elements regardless of their current value (unlike --replace-value). The new values should be space-separated and contained within quotes.
 
This operation allows you to replace all the XML values from existing XML elements. The new values should be space separated and contained within quotes.


<tt>Usage: XmlTools --replace-all-values --new-val "new values"</tt>
<tt>Usage: XmlTools --replace-all-values --new-val "new values"</tt>


===Example===
====Example====
Let's say you want to replace all the flags in all characters by InfiniteAmmo and NotInitiallyPresent flags.
Let's say you want to replace all existing character flags with the InfiniteAmmo and NotInitiallyPresent flags.




Line 208: Line 202:


{| style="margin: 1em auto 1em auto;" <!-- Centers table -->
{| style="margin: 1em auto 1em auto;" <!-- Centers table -->
! style="width: 50%;" | XML Original
! style="width: 50%;" | XML Before
! style="width: 50%;" | XML After Command
! style="width: 50%;" | XML After
|-
|-
|
|
Line 253: Line 247:
|}
|}


==--update-elements==
===--update-elements===
 
====Description====
===Description===
This operation allows you to offset the values in a set of existing XML elements by specified amounts. The value differences must be space-separated and contained within quotes.
 
This operation allows you to update all values in a set of existing XML elements. The values differences must be space separated and contained within quotes.


<tt>Usage: XmlTools --update-elements --diff-old-new-val "differences old-new values"</tt>
<tt>Usage: XmlTools --update-elements --diff-old-new-val "differences old-new values"</tt>


===Examples===
====Examples====
=====Example 1=====
Let's say you have a level built in a 3D modeling program and you have already set the positions in the BINACBJOCharacter file for all the characters that are to be spawned during the gameplay. However, for some reason you need to change the position of the level in the modeling program, which means that the character spawn locations are now incorrect. --update-elements provides the way to correct them.


====Example 1====
Let's say that you know that the difference between the old level's position and the new level's position is, in Oni's world units, {130, 80, 0} (in x, y, z order).
 
Let's say you have a Level built on Google Sketchup. Inside the level you have positioned all the characters that are spawn during the gameplay. However for some reason you need to change the position of the level and the character accordingly. You can move the level inside the level editor, while the positions of the character can be updated using XmlTools.
 
You know the difference between the old level position and the new level position is 130 in X, 80 in Y and 0 in Z.


'''XmlTools command:'''
'''XmlTools command:'''
Line 273: Line 263:


{| style="margin: 1em auto 1em auto;" <!-- Centers table -->
{| style="margin: 1em auto 1em auto;" <!-- Centers table -->
! style="width: 50%;" | XML Original
! style="width: 50%;" | XML Before
! style="width: 50%;" | XML After Command
! style="width: 50%;" | XML After
|-
|-
|
|
Line 341: Line 331:




====Example 2====
=====Example 2=====
Let's say you want to use the Tanker's forward throw attack with a new character. You know that your new character has a higher pelvis than the Tanker, which means that you need to alter the height values in every frame of the Tanker's TRAM data to match those of your new character.


Let's say you want to use tanker forward throw to a new character. You know that your new character has higher pelvis than the tanker, so you need to update all the heights of tanker animation to match those of your new character.
Let's say that we know the difference between the pelvis height of the Tanker and your character is -0.7970685 (that is, the values that we are about to alter are this much less than what they should be). This number will be added to each value in the named XML elements.
 
We also know that difference between tanker animation (old value) and your character's (new value) is -0.7970685.




Line 352: Line 341:


{| style="margin: 1em auto 1em auto;" <!-- Centers table -->
{| style="margin: 1em auto 1em auto;" <!-- Centers table -->
! style="width: 50%;" | XML Original
! style="width: 50%;" | XML Before
! style="width: 50%;" | XML After Command
! style="width: 50%;" | XML After
|-
|-
|
|
Line 393: Line 382:
|}
|}


==--invert-elements==
===--invert-elements===
 
====Description====
===Description===
This operation allows you to invert a set of values in XML elements, for example, reversing the motion of an animation by flipping its frame values from 1, 2, 3 to 3, 2, 1.
 
This operation allows you to invert a set of XML elements.


<tt>Usage: XmlTools --invert-elements</tt>
<tt>Usage: XmlTools --invert-elements</tt>


===Example===
====Example====
Let's say you want to invert the helicopter animation from Oni's final level. If you notice in that level the helicopter comes from down to above to reach the compound higher spot then it goes down again. If we invert the helicopter animation it will come from above to down and then to above again (which what was did in Old China mod).
Let's say you want to invert the helicopter animation from Oni's final level. If you notice, in that level the helicopter comes up from below to land on the satellite dish platform, and then it goes down again. If we invert the helicopter animation, it will come down from above, and then go back up again (which is exactly what was done in the Old China mod).


For simplicity we will only edit one part of the helicopter animation: 'heli_interior09' and its Translation (position) element. Please note that to invert correctly the animation you will need to invert Rotation element too.
For simplicity we will only edit one part of the helicopter animation: 'heli_interior09' and its Translation (position) element. Please note that to correctly invert the animation, you will need to invert the Rotation element too.


'''XmlTools command:'''
'''XmlTools command:'''
Line 410: Line 397:


{| style="margin: 1em auto 1em auto;" <!-- Centers table -->
{| style="margin: 1em auto 1em auto;" <!-- Centers table -->
! style="width: 50%;" | XML Original
! style="width: 50%;" | XML Before
! style="width: 50%;" | XML After Command
! style="width: 50%;" | XML After
|-
|-
|
|
Line 471: Line 458:
|}
|}


=Patch file operations=
==Patch file operations==
 
XmlTools has a special set of commands that can be listed within a plain-text file to be executed all at once. One of these commands allows you to use any of the above command-line operations, and another command allows you to use JavaScript to modify the XML (for especially complex situations).
==Overview==
 
==@XML_TOOLS==
 
===Description===


===@XML_TOOLS===
====Description====
This operation allows to specify options related with the XmlTools program. Currently only allows to specify the minimum XmlTools version necessary to apply the patch file.
This operation allows to specify options related with the XmlTools program. Currently only allows to specify the minimum XmlTools version necessary to apply the patch file.


Line 484: Line 468:
<tt>@XML_TOOLS Version "XmlToolsVersion"</tt>
<tt>@XML_TOOLS Version "XmlToolsVersion"</tt>


===Example===
====Example====
 
Let's say your patch is only compatible with XmlTools 2.0.
Let's say your patch is only compatible with XmlTools 2.0.


Line 493: Line 476:
Note that by "2.0" it means that it is also compatible with XmlTools 2.0a, 2.0b etc.
Note that by "2.0" it means that it is also compatible with XmlTools 2.0a, 2.0b etc.


==@ADD_INSIDE_NODES==
===@ADD_INSIDE_NODES===
 
====Description====
===Description===
 
This operation allows to insert new XML inside existing XML nodes. The XML to insert must be contained between <tt><xml></tt> and <tt></xml></tt> tags as seen bellow.
This operation allows to insert new XML inside existing XML nodes. The XML to insert must be contained between <tt><xml></tt> and <tt></xml></tt> tags as seen bellow.


Line 509: Line 490:
<tt></xml></tt>
<tt></xml></tt>


===Example===
====Example====
 
Let's say your want do add a new glass particle to the SWAT Griffin ONCC.
Let's say your want do add a new glass particle to the SWAT Griffin ONCC.


Line 564: Line 544:
|}
|}


==@REMOVE_NODES==
===@REMOVE_NODES===
 
====Description====
===Description===
 
This operation allows to remove existing XML nodes.
This operation allows to remove existing XML nodes.


Line 573: Line 551:
<tt>@REMOVE_NODES</tt>
<tt>@REMOVE_NODES</tt>


===Example===
====Example====
 
Let's say your want do remove the glass particle from the SWAT Griffin ONCC.
Let's say your want do remove the glass particle from the SWAT Griffin ONCC.


Line 621: Line 598:
|}
|}


==@COMMAND==
===@COMMAND===
 
====Description====
===Description===
 
This operation allows you to use any of the [[XmlTools#Command-line_operations|command line operations]] in a patch file.
This operation allows you to use any of the [[XmlTools#Command-line_operations|command line operations]] in a patch file.


Line 632: Line 607:
Note: For command line input operations which use quotes ("") replace the double quotes with single quotes (<nowiki>''</nowiki>). If any XPath expression also includes single quotes you can double them to allow XmlTools to process the command.
Note: For command line input operations which use quotes ("") replace the double quotes with single quotes (<nowiki>''</nowiki>). If any XPath expression also includes single quotes you can double them to allow XmlTools to process the command.


===Example===
====Example====
 
Let's say your want to perform the same operation in [[#Example|--add-values example]]. This operation adds the Unkillable and the NonCombatant flag to A_L18 character.
Let's say your want to perform the same operation in [[#Example|--add-values example]]. This operation adds the Unkillable and the NonCombatant flag to A_L18 character.


Line 643: Line 617:
The resulting XML file is exactly the same of [[#Example|--add-values example]].
The resulting XML file is exactly the same of [[#Example|--add-values example]].


==@CUSTOM_CODE==
===@CUSTOM_CODE===
 
====Description====
===Description===
 
This operation allows you to use [[wikipedia:JavaScript|JavaScript]] to edit XML.  
This operation allows you to use [[wikipedia:JavaScript|JavaScript]] to edit XML.  


Line 669: Line 641:
XmlTools uses the [http://www.petetracey.com/jsxml/index.html JSXML XML Tools] JavaScript libraries to allow you to edit the XML. You can read it documentation in its [http://www.petetracey.com/jsxml/documentation.html website] or [http://script10k.oni2.net/documentation/xmltools/jsxml-documentation.htm here].
XmlTools uses the [http://www.petetracey.com/jsxml/index.html JSXML XML Tools] JavaScript libraries to allow you to edit the XML. You can read it documentation in its [http://www.petetracey.com/jsxml/documentation.html website] or [http://script10k.oni2.net/documentation/xmltools/jsxml-documentation.htm here].


===Example===
====Example====
 
Let's say your want to add one additional ammo and cell to all characters that are from TCTF team.
Let's say your want to add one additional ammo and cell to all characters that are from TCTF team.


Retrieved from "https://wiki.oni2.net/Special:MobileDiff/25387"