fscript guide

Using-FScript.md

@@ -0,0 +1,74 @@
+FScript is Firestar's processing script that handles dynamic file changes and updates without replacing files or breaking compatibility.
+
+**A couple notes:**
+- Commands are case-insensitive
+- After defining a target/context, further operations can be wrapped into a single context block.
+- You can escape new-lines and tabulators with `\n` and `\t` respectively.
+
+### Syntax
+The basic single-line syntax.
+```
+command context operation1 arguments
+command context operation2 arguments
+```
+
+Multiple lines under the same 'context' can be combined in a context block.
+```
+command context {
+	operation1 arguments
+	operation2 arguments
+}
+```
+
+### Commands
+
+`FSCRIPT [version]`
+Defines the version of FScript. This is for future backwards compatibility.
+
+`FILE [context:relative-path]`
+Opens a file under the relative-path. In the case of Firestar, this is under the temporary deployment path.
+
+ `DELETE`
+ Deletes the file.
+
+&emsp;`[XSTR|STR] [append|delete|replace] [find] <replace> <offset> <limit>`
+&emsp;Finds, appends to, or replaces text in a file. `offset` determines the found index to start with, and `limit` determines the maximum to find. STR is case-sensitive while XSTR is not.
+
+&emsp;`BINEDIT [offset] [byte]`
+&emsp;Edits the file binary. `offset` is the integer offset to start editing at. `byte` is the hexadecimal representation of your data.
+
+&emsp;`XML [create|delete] [context:selector]`
+&emsp;Creates or deletes an XML element in the file. See [XML Selector](#user-content-xml-selector) for selector help.
+
+&emsp;`XML [modify] [context:selector] SET [value|attribute] [text1] <text2>`
+&emsp;Modifies an attribute or inner text of an element. See [XML Selector](#user-content-xml-selector) for selector help.
+
+&emsp;`XML [merge] [file]`
+&emsp;Merges the data from another XML into the file.
+
+&emsp;`PATCH [file]`
+&emsp;Runs a unified patch on the file.
+
+### XML Selector
+The XML selector is a simple string separated by periods. The following document will be used as an example.
+```xml
+<root>
+    <parent>
+        <child id="A" name="Downtown"/>
+        <child id="B" name="Sol"/>
+        <child id="C" name="Ubermall"/>
+    </parent>
+</root>
+```
+The second `<child>` element can be obtained with the following selectors:
+```
+root.parent.child[1]
+```
+```
+root.parent.child#B
+```
+```
+root.parent.child$Sol
+```
+
+The `#` character is used to refer to an elements `id` attribute. The `$` character is used to refer to an elements `name` attribute. These characters can not be used at the same time, and FScript will fail if the elements cannot be found.