Skip to content

Commit 6d8e803

Browse files
chemodunchemodun
committed
refactor: enhance project files with versioning and product information
fix: removed the git commit information from the version info docs: Created an actual README.md
1 parent 54e50ab commit 6d8e803

File tree

5 files changed

+664
-1
lines changed

5 files changed

+664
-1
lines changed

‎Docs/README.egosoft‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
[size=150][b]Modding tools: XML diff and patch for X4: Foundations[/b][/size]
2+
3+
This toolset is a simple XML diff and patch tools for X4: Foundations. It is designed to help modders to compare and patch XML files.
4+
5+
The format of diff XML files is compatible with the appropriate [b]diff.xsd[/b] format definition. It is means - you can you this tool to create diff files for any XML files used in game.
6+
Also, you can use appropriate tool to patch XML files with diff files, this action has reason to check how your diff file will be applied to the vanilla XML file. Or better understand, what other modders did in their mods.
7+
8+
[size=120][b]Important note[/b][/size]
9+
It is highly recommended to use the [b]diff.xsd[/b] file to validate the diff XML files. It is especially important when you creating them by [b]XMLDiff.exe[/b].
10+
11+
12+
[size=120][b]How to use[/b][/size]
13+
[list=1]
14+
[*] Download the latest release from the [url=https://github.com/chemodun/x4_XMLDiffAndPatch/releases/]releases page[/url] - there is an archive file [b]XMLDiffAndPatch.zip[/b].
15+
[*] Extract the archive file to any useful location.
16+
[*] Inside will be a folder, named XMLDiffAndPatch with two executable - [b]XMLDiff.exe[/b] and [b]XMLPatch.exe[/b].
17+
[/list]
18+
[size=100][b]How to create a diff file[/b][/size]
19+
There is a command line help for the [b]XMLDiff[/b] tool:
20+
[code]
21+
XMLDiff 0.2.13
22+
Developed by Chem O`Dun
23+
24+
-o, --original_xml Required. Path to the original XML file or directory.
25+
26+
-m, --modified_xml Required. Path to the modified XML file or directory.
27+
28+
-d, --diff_xml Required. Path for the diff XML file or directory.
29+
30+
-x, --xsd Path to the diff.xsd schema file.
31+
32+
-l, --log-to-file (Default: false) Log to a file.
33+
34+
--only-full-path (Default: false) Generate only full path.
35+
36+
--use-all-attributes (Default: false) Use all attributes in XPath.
37+
38+
--help Display this help screen.
39+
40+
--version Display version information.
41+
[/code]
42+
43+
Example:
44+
[code]
45+
XMLDiff.exe -o vanilla.xml -m modified.xml -d diff.xml
46+
[/code]
47+
48+
[size=100][b]Example of resulting diff files[/b][/size]
49+
There the is example of the diff files created by tool:
50+
[*] with add operation:
51+
[code=xml]
52+
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
53+
<diff>
54+
<add sel="//ware[@id=&quot;scanningarrays&quot;]" pos="before">
55+
<ware id="xenon_psi_emitter_mk1" name="{1972092403, 7002}" description="{1972092403, 7002}" transport="equipment" volume="1" tags="satellite noplayerbuild">
56+
<price min="845800" average="901420" max="1054580" />
57+
<production time="60" amount="0" method="default" name="Xenon Psi Emitter" />
58+
<production time="60" amount="0" method="xenon" name="Xenon Psi Emitter" />
59+
<production time="60" amount="0" method="terran" name="Xenon Psi Emitter" />
60+
<component ref="xenon_psi_emitter_macro" amount="0" />
61+
<use threshold="0" />
62+
</ware>
63+
</add>
64+
</diff>
65+
```
66+
[*] with replace operation:
67+
```xml
68+
<?xml version='1.0' encoding='UTF-8'?>
69+
<diff>
70+
<replace sel="//do_if[@value=&quot;@$speak and not this.assignedcontrolled.nextorder and (@$defaultorder.id != 'Patrol') and (@$defaultorder.id != 'ProtectPosition') and (@$defaultorder.id != 'ProtectShip') and (@$defaultorder.id != 'ProtectStation') and (@$defaultorder.id != 'Plunder') and (@$defaultorder.id != 'Police') and (not this.assignedcontrolled.commander or (this.assignedcontrolled.commander == player.occupiedship)) and notification.npc_await_orders.active&quot;]/@value">@$speak and not this.assignedcontrolled.nextorder and (@$defaultorder.id != 'ProtectSector') and (@$defaultorder.id != 'Patrol') and (@$defaultorder.id != 'ProtectPosition') and (@$defaultorder.id != 'ProtectShip') and (@$defaultorder.id != 'ProtectStation') and (@$defaultorder.id != 'Plunder') and (@$defaultorder.id != 'Police') and (not this.assignedcontrolled.commander or (this.assignedcontrolled.commander == player.occupiedship)) and notification.npc_await_orders.active</replace>
71+
</diff>
72+
```
73+
[size=90][b]Path options[/b][/size]
74+
75+
[size=80][b]Only full path[/b][/size]
76+
The [b]--only-full-path[/b] option will generate only the full path to the element in the XML file. It is mean - there no [b]//[/b] will be in the [b]sel[/b] attribute of the [b]add[/b], [b]replace[/b] or [b]remove[/b] element.
77+
78+
Example:
79+
[/code]xml
80+
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
81+
<diff>
82+
<add sel="/wares/ware[@id=&quot;scanningarrays&quot;]" pos="before">
83+
<ware id="xenon_psi_emitter_mk1" name="{1972092403, 7002}" description="{1972092403, 7002}" transport="equipment" volume="1" tags="satellite noplayerbuild">
84+
<price min="845800" average="901420" max="1054580" />
85+
<production time="60" amount="0" method="default" name="Xenon Psi Emitter" />
86+
<production time="60" amount="0" method="xenon" name="Xenon Psi Emitter" />
87+
<production time="60" amount="0" method="terran" name="Xenon Psi Emitter" />
88+
<component ref="xenon_psi_emitter_macro" amount="0" />
89+
<use threshold="0" />
90+
</ware>
91+
</add>
92+
</diff>
93+
[code]
94+
95+
[size=80][b]Use all attributes in XPath[/b][/size]
96+
The [b]--use-all-attributes[/b] option will generate the [b]sel[/b] attribute with all attributes of the element in the XML file. It is mean - there will be all attributes of the element in the [b]sel[/b] attribute of the [b]add[/b], [b]replace[/b] or [b]remove[/b] element.
97+
98+
Example:
99+
[/code]xml
100+
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
101+
<diff>
102+
<add sel="/wares/ware[@id=&quot;scanningarrays&quot;][@name=&quot;{20201,3301}&quot;][@description=&quot;{20201,3302}&quot;][@factoryname=&quot;{20201,3304}&quot;][@group=&quot;hightech&quot;][@transport=&quot;container&quot;][@volume=&quot;38&quot;][@tags=&quot;container economy&quot;]" pos="before">
103+
<ware id="xenon_psi_emitter_mk1" name="{1972092403, 7002}" description="{1972092403, 7002}" transport="equipment" volume="1" tags="satellite noplayerbuild">
104+
<price min="845800" average="901420" max="1054580" />
105+
<production time="60" amount="0" method="default" name="Xenon Psi Emitter" />
106+
<production time="60" amount="0" method="xenon" name="Xenon Psi Emitter" />
107+
<production time="60" amount="0" method="terran" name="Xenon Psi Emitter" />
108+
<component ref="xenon_psi_emitter_macro" amount="0" />
109+
<use threshold="0" />
110+
</ware>
111+
</add>
112+
</diff>
113+
[code]
114+
115+
[size=100][b]How to apply a diff file[/b][/size]
116+
There is a command line help for the [b]XMLPatch[/b] tool:
117+
[/code]
118+
XMLPatch 0.2.13
119+
Developed by Chem O`Dun
120+
121+
-o, --original_xml Required. Path to the original XML file or directory.
122+
123+
-d, --diff_xml Required. Path to the diff XML file or directory.
124+
125+
-u, --output_xml Required. Path for the output XML file or directory.
126+
127+
-x, --xsd Path to the diff.xsd schema file.
128+
129+
-l, --log-to-file (Default: false) Log to a file.
130+
131+
--help Display this help screen.
132+
133+
--version Display version information.
134+
[code]
135+
136+
Example:
137+
[/code]
138+
xml-patch.exe -o vanilla.xml -d diff.xml -u modified.xml
139+
[code]
140+
141+
[size=100][b]Example of resulting patched XML files[/b][/size]
142+
There the is example of the patched XML files created by tool:
143+
[*] with add operation:
144+
```xml
145+
<ware id="satellite_mk2" name="{20201,20401}" description="{20201,20402}" transport="equipment" volume="1" tags="equipment satellite">
146+
<price min="44380" average="52215" max="60045"/>
147+
<production time="60" amount="1" method="default" name="{20206,101}">
148+
<primary>
149+
<ware ware="advancedelectronics" amount="5"/>
150+
<ware ware="energycells" amount="10"/>
151+
<ware ware="scanningarrays" amount="5"/>
152+
</primary>
153+
</production>
154+
<production time="60" amount="1" method="xenon" name="{20206,601}" tags="noplayerbuild">
155+
<primary>
156+
<ware ware="energycells" amount="10"/>
157+
<ware ware="silicon" amount="1"/>
158+
</primary>
159+
</production>
160+
<component ref="eq_arg_satellite_02_macro"/>
161+
<use threshold="0"/>
162+
</ware>
163+
<ware id="xenon_psi_emitter_mk1" name="{1972092403, 7002}" description="{1972092403, 7002}" transport="equipment" volume="1" tags="satellite noplayerbuild">
164+
<price min="845800" average="901420" max="1054580"/>
165+
<production time="60" amount="0" method="default" name="Xenon Psi Emitter"/>
166+
<production time="60" amount="0" method="xenon" name="Xenon Psi Emitter"/>
167+
<production time="60" amount="0" method="terran" name="Xenon Psi Emitter"/>
168+
<component ref="xenon_psi_emitter_macro" amount="0"/>
169+
<use threshold="0"/>
170+
</ware>
171+
```
172+
[*] with replace operation:
173+
```xml
174+
<set_to_default_flight_control_model object="this.assignedcontrolled"/>
175+
<set_value name="$defaultorder" exact="this.assignedcontrolled.defaultorder"/>
176+
<do_if value="@$speak and not this.assignedcontrolled.nextorder and (@$defaultorder.id != 'Patrol') and (@$defaultorder.id != 'ProtectSector') and (@$defaultorder.id != 'ProtectPosition') and (@$defaultorder.id != 'ProtectShip') and (@$defaultorder.id != 'ProtectStation') and (@$defaultorder.id != 'Plunder') and (@$defaultorder.id != 'Police') and (not this.assignedcontrolled.commander or (this.assignedcontrolled.commander == player.occupiedship)) and notification.npc_await_orders.active">
177+
<set_value name="$speakline" exact="10304" comment="Awaiting orders."/>
178+
```
179+
180+
[size=100][b]If output XML is a directory[/b][/size]
181+
If the output XML is a directory, the tool will create a new XML file with the same name as the original XML file in the output directory.
182+
For example, if the original XML file is [b]vanilla.xml[/b] and the output directory is [b]output[/b], the tool will create a new XML file [b]output/vanilla.xml[/b].
183+
184+
[size=100][b]How to apply a tools to a directories[/b][/size]
185+
You can apply the tools to directories. In this case, the tools will apply the diff or patch to all XML files in the directory.
186+
The logic will be a next:
187+
[*] all input parameters are directories - the tools will apply the diff or patch to all XML files in the directories.
188+
[*] it will recursively gro thru the diff or changed XML files in the directories, respectively to the tool.
189+
[*] for each diff or changed files will be checked a corresponding original XML file in the original directory with the same relative path.
190+
[*] if the original XML file is not found - the diff or changed file will be skipped.
191+
[*] if the original XML file is found - the diff or changed file will be patched with the original XML file and created a new patched XML file in the output directory with the same relative path.
192+
193+
Example:
194+
[/code]
195+
XMLDiff.exe -o vanilla_dir -m modified_dir -d diff_dir
196+
[code]
197+
or
198+
[/code]
199+
XMLPatch.exe -o vanilla_dir -d diff_dir -u modified_dir
200+
```
201+
202+
[size=120][b]Issues reporting[/b][/size]
203+
204+
If you have any issues with the tool, please create an issue in the [url=https://github.com/chemodun/x4_XMLDiffAndPatch/issues]issues page[/url].
205+
Will be highly appreciated if you will provide a version of used tool and XMLDiff.log or XMLPatch.log file respectively to the tool.
206+
To create such debug file please use the [b]--log-to-file[/b] option.
207+
208+
[size=120][b]License[/b][/size]
209+
There is a MIT license for this tool. You can find it in the [url=LICENSE]LICENSE[/url] file.
210+
211+
[size=120][b]Additional links[/b][/size]
212+
213+
There is a topic on the [Egosoft forum]https://forum.egosoft.com/viewtopic.php?t=468623), related to this toolset.

0 commit comments

Comments
 (0)