|
|
| Line 1: |
Line 1: |
| {{#set:
| |
| NMSIndex=AMUMSS
| |
| }}{{PageTitle|logo=nomanssky|title=AMUMSS Script Rules|subtitle=For version 3.6.0W or higher|author=Wbertro & Lo2k}}
| |
| {{NMSPage}}
| |
| {{TOC}}
| |
| == Introduction ==
| |
| AMUMSS offers a new way to create mods for No Man's Sky. Using scripts and the game files currently installed on your computer, it can indeed generate mods on the fly whenever needed.<br>
| |
| It's a powerful tool once mastered.<br>
| |
| This page is dedicated to script rules. It explains each and every AMUMSS function and how to use each of them to create a script that will do exactly what you want.<br>
| |
| All the content below is based on Wbertro's Script Rules but rewritten especially for this wiki version.
| |
| <br>
| |
|
| |
|
| === LUA ===
| |
| AMUMSS uses LUA 5.3 coding language so scripts can use:
| |
| * All the standard lua syntax (section 3 of https://www.lua.org/manual/5.3/)
| |
| * All available standard functions in {string, math, table}
| |
| * io.open, io.input, io.type, io.read, io.lines and io.close
| |
| * os.clock, os.date, os.difftime, os.getenv, os.time, os.tmpname
| |
| * Plus {assert, pairs, ipairs, print, tonumber, tostring, type}
| |
| <br>
| |
|
| |
| ==== Notes ====
| |
| * AMUMSS edits .EXML files.So all it functions refer to .EXML content
| |
| * .EXML files are basicaly [https://stepmodifications.org/wiki/NoMansSky:Tutorials/EXMLFiles formatted text files]
| |
| * the TOP level is always <nowiki><Data template="something"></nowiki> AND this value is NOT used by the tool
| |
| * Each level ends with </Property> except the TOP level which ends with </Data>
| |
| * Every new level (SECTION) starts with a line ending with ">
| |
| * Every child statement ends with />
| |
| * a SECTION is defined as "all the lines" from the beginning [">] to the ending </Property> line (so a SECTION is at least 3 lines long)
| |
| * a SECTION can contain any number of sub-sections
| |
| <br>
| |
|
| |
| === Script Template ===
| |
| To be able to edit precise values, AMUMSS needs to be guided toward:
| |
| * The original .MBIN file you want to edit (that AMUMSS will internaly convert into .EXML). This is the role of MBIN_FILE_SOURCE
| |
| * The section containing the values you want to edit. SPECIAL_KEY_WORDS and PRECEDING_KEY_WORDS will do this task if necessary.
| |
| * The new value to apply. VALUE_CHANGE_TABLE is usualy the way to do it.
| |
| <br>
| |
| You can see below the syntax for a very basic script replacing a single fictive value but you will find lots of scripts in AMUMSS ModScriptCollection folder and particulary in LearningExamples one.<br>
| |
| <br>
| |
| NMS_MOD_DEFINITION_CONTAINER =
| |
| {
| |
| ["MOD_FILENAME"] = "MyScript.pak",
| |
| ["MOD_DESCRIPTION"] = "this mod replaces a value",
| |
| ["MOD_AUTHOR"] = "My name",
| |
| ["NMS_VERSION"] = "2.62",
| |
| ["MODIFICATIONS"] =
| |
| {
| |
| {
| |
| ["MBIN_CHANGE_TABLE"] =
| |
| {
| |
| {
| |
| ["MBIN_FILE_SOURCE"] = "ORIGINAL.MBIN",
| |
| ["EXML_CHANGE_TABLE"] =
| |
| {
| |
| {
| |
| ["VALUE_CHANGE_TABLE"] =
| |
| {
| |
| {"OriginalValue", "NewValue"},
| |
| }
| |
| },
| |
| }
| |
| },
| |
| }
| |
| },
| |
| }
| |
| }
| |
| <br>
| |
|
| |
| == SCRIPT STRUCTURE ==
| |
| AMUMSS scripts have to respect some hierarchy.<br>
| |
| This is the hierarchy of the possible content of a script:<br>
| |
|
| |
| : {{fc|#FFF|NMS_MOD_DEFINITION_CONTAINER}} {{fc|#AAF|- REQUIRED}}
| |
| :: MOD_FILENAME
| |
| :: MOD_AUTHOR
| |
| :: MOD_DESCRIPTION
| |
| :: NMS_VERSION
| |
| :: MOD_BATCHNAME
| |
| :: ADD_FILES
| |
| ::: FILE_DESTINATION
| |
| ::: EXTERNAL_FILE_SOURCE
| |
| ::: FILE_CONTENT
| |
| :: {{fc|#FFF|MODIFICATIONS}} {{fc|#AAF|- REQUIRED}}
| |
| ::: PAK_FILE_SOURCE
| |
| ::: {{fc|#FFF|MBIN_CHANGE_TABLE}} {{fc|#AAF|- REQUIRED}}
| |
| :::: {{fc|#FFF|MBIN_FILE_SOURCE}} {{fc|#AAF|- REQUIRED}}
| |
| :::: REGEXBEFORE
| |
| :::: REGEXAFTER
| |
| :::: {{fc|#FFF|EXML_CHANGE_TABLE}} {{fc|#AAF|- REQUIRED}}
| |
| ::::: SPECIAL_KEY_WORDS
| |
| ::::: PRECEDING_FIRST
| |
| ::::: PRECEDING_KEY_WORDS
| |
| ::::: SECTION_UP
| |
| ::::: WHERE_IN_SECTION
| |
| ::::: SAVE_SECTION_TO
| |
| ::::: SAVE_SECTION_ACROSS
| |
| ::::: USE_SECTION
| |
| ::::: MATH_OPERATION
| |
| ::::: INTEGER_TO_FLOAT
| |
| ::::: REPLACE_TYPE
| |
| ::::: VALUE_MATCH
| |
| ::::: VALUE_MATCH_TYPE
| |
| ::::: LINE_OFFSET
| |
| ::::: VALUE_CHANGE_TABLE
| |
| ::::: ADD
| |
| ::::: REMOVE
| |
|
| |
| You might notice that every script only really needs 5 required table declarations and all the other members are optional.<br>
| |
| <br>
| |
|
| |
| == NMS_MOD_DEFINITION_CONTAINER ==
| |
| {{fc|#AAF|REQUIRED}}<br>
| |
| This is the Master Table. It defines that the following text is a script.<br>
| |
| <br>
| |
| Here are the possible members (order independant):
| |
| :* MOD_FILENAME
| |
| :* MOD_AUTHOR
| |
| :* MOD_DESCRIPTION
| |
| :* NMS_VERSION
| |
| :* MOD_BATCHNAME
| |
| :* ADD_FILES
| |
| :* MODIFICATIONS
| |
| <br>
| |
|
| |
| === MOD_FILENAME ===
| |
| Member of: NMS_MOD_DEFINITION_CONTAINER.<br>
| |
| This variable hosts the name of your final mod .pak file.<br>
| |
| Note that the maximum name length can't exceed 106 chars + .pak<br>
| |
|
| |
| if MOD_FILENAME is not found, the created mod will be named 'GENERIC.pak' and a WARNING will be issued.<br>
| |
| <br>
| |
| Example: ["MOD_FILENAME"] = "MyMod.pak",
| |
| <br>
| |
|
| |
| === MOD_AUTHOR===
| |
| Member of: NMS_MOD_DEFINITION_CONTAINER.<br>
| |
| This variable hosts the name of the script author. It is currently only a reference.<br>
| |
|
| |
| Example: ["MOD_AUTHOR"] = "I am the author",
| |
|
| |
| <br>
| |
|
| |
| === MOD_DESCRIPTION ===
| |
| Member of: NMS_MOD_DEFINITION_CONTAINER.<br>
| |
| This variable hosts the description of the mod. It is currently only a reference.<br>
| |
| <br>
| |
| Example: ["MOD_DESCRIPTION"] = "This mod does so much it can't fit here",
| |
| <br>
| |
|
| |
| === NMS_VERSION ===
| |
| Member of: NMS_MOD_DEFINITION_CONTAINER.<br>
| |
| This variable hosts the NMS version the script was written for. It is currently only a reference.<br>
| |
| <br>
| |
| Example: ["NMS_VERSION"] = "1.77",
| |
| <br>
| |
|
| |
| === MOD_BATCHNAME ===
| |
| Member of: NMS_MOD_DEFINITION_CONTAINER.<br>
| |
| This variable supersides MOD_FILENAME when more than one .lua scripts are present.<br>
| |
| As for MOD_FILENAME, maximum name length is 106 chars + .pak
| |
| <br>
| |
| Example: ["MOD_BATCHNAME"] = "MySetofMods.pak",
| |
| <br>
| |
|
| |
| == MODIFICATIONS ==
| |
| {{fc|#AAF|REQUIRED}}<br>
| |
| Member of: NMS_MOD_DEFINITION_CONTAINER.<br>
| |
| This is a table containing one or many tables.<br>
| |
| This can be used with or without ADD_FILES and becomes OPTIONAL if ADD_FILES is used.<br>
| |
| <br>
| |
| Here are the possible members (independant order):
| |
| * PAK_FILE_SOURCE
| |
| * MBIN_CHANGE_TABLE
| |
| <br>
| |
|
| |
| === PAK_FILE_SOURCE ===
| |
| Member of: MODIFICATIONS.<br>
| |
| This variable is optional and not necessary anymore.<br>
| |
| It sets the original NMS .pak name as found in the NMS/PCBANKS folder containing the files this mod will edit.<br>
| |
| Note that if you have the name of the .MBIN file you need to edit, the original .pak file containing it can be easily found thanks to NMS_PCBANKS_Explorer-Unpacker provided with AMUMSS<br>
| |
| <br>
| |
| Example: ["PAK_FILE_SOURCE"] = "NMSARC.59B126E2.pak",
| |
| <br>
| |
|
| |
| == MBIN_CHANGE_TABLE ==
| |
| {{fc|#AAF|REQUIRED}}<br>
| |
| Member of: MODIFICATIONS.<br>
| |
| It hosts a table of MBIN_FILE_SOURCE(s) and EXML_CHANGE_TABLE(s).
| |
|
| |
| The possible members of MBIN_CHANGE_TABLE are (order independant):
| |
| * MBIN_FILE_SOURCE
| |
| * REGEXBEFORE
| |
| * EXML_CHANGE_TABLE
| |
| * REGEXAFTER
| |
| <br>
| |
|
| |
| === MBIN_FILE_SOURCE ===
| |
| {{fc|#AAF|REQUIRED}}<br>
| |
| Member of: MBIN_CHANGE_TABLE<br>
| |
| This variable hosts the name of the .MBIN file(s) that will be converted to .EXML files to receive changes via this script.
| |
|
| |
| * For a single file:
| |
| Example: ["MBIN_FILE_SOURCE"] = "METADATA\SIMULATION\SCENE\EXPERIENCESPAWNTABLE.MBIN",
| |
|
| |
| * For 2 (or more) files (read from top to bottom):
| |
| Example:
| |
| ["MBIN_FILE_SOURCE"] = {"METADATA\SIMULATION\SOLARSYSTEM\BIOMES\BARREN\BARRENHQOBJECTSFULL.MBIN",
| |
| "METADATA\SIMULATION\SOLARSYSTEM\BIOMES\BARREN\BARRENOBJECTSDEAD.MBIN",},
| |
|
| |
| * Create a backup of 2 (or more) files before editing them:
| |
| Example: ["MBIN_FILE_SOURCE"] = {
| |
| {"METADATA\SIMULATION\SOLARSYSTEM\BIOMES\BARREN\BARRENHQOBJECTSFULL.MBIN", "NEWPATH\MYSUBFOLDER\MYBACKUPFILE.MBIN", Optional_Flag},
| |
| {"METADATA\SIMULATION\SOLARSYSTEM\BIOMES\BARREN\BARRENOBJECTSDEAD.MBIN", "NEWPATH\MYSUBFOLDER\MYBACKUPFILE2.MBIN", Optional_Flag},
| |
| },
| |
| Note that only the source (original) .MBIN file will be edited by the script.<br>
| |
| If you want to edit the backup copy, you will need to add a new section in MBIN_CHANGE_TABLE with the MBIN_FILE_SOURCE now referencing the backup file (see NEW_PathFilename.lua for an example of use)
| |
|
| |
| If Optional_Flag is omitted or set to "", the original .MBIN file will be present in the mod .pak file.<br>
| |
| If Optional_Flag is set to "REMOVE" then the original .MBIN file will NOT be included in the mod pak.<br>
| |
| <br>
| |
|
| |
| ==== REGEXBEFORE ====
| |
| Member of: MBIN_CHANGE_TABLE<br>
| |
| If use, will invoque a regex utility to process the EXML file BEFORE any script processing<br>
| |
| This is a table of (two STRINGs)table(s) like {{"ToFindRegex","ToReplaceRegex"},...},
| |
| : Example:
| |
| <pre>["REGEXBEFORE"] = {
| |
| {[[((.*Unknown.*)(True))]],[[\2False]]},
| |
| ...
| |
| },</pre>
| |
| Sed regex rules apply (see https://www.gnu.org/software/sed/)<br>
| |
| <br>
| |
|
| |
| ==== REGEXAFTER ====
| |
| Member of: MBIN_CHANGE_TABLE<br>
| |
| If use, will invoque a regex utility to process the EXML file AFTER the script processing<br>
| |
| This is a table of (two STRINGs)table(s) like {{"ToFindRegex","ToReplaceRegex"},...},<br>
| |
| : Example:
| |
| <pre>["REGEXAFTER"] = {
| |
| {[[((.*Unknown.*)(True))]],[[\2False]]},
| |
| ...
| |
| },</pre>
| |
| Sed regex rules apply (see https://www.gnu.org/software/sed/)<br>
| |
| <br>
| |
|
| |
| == EXML_CHANGE_TABLE ==
| |
| {{fc|#AAF|REQUIRED}} (except in very rare occasions, see MapFileTree_UPDATER.lua)<br>
| |
| Member of MBIN_CHANGE_TABLE.
| |
|
| |
| The possible members of EXML_CHANGE_TABLE are (order is independant):
| |
| * SPECIAL_KEY_WORDS
| |
| * PRECEDING_FIRST
| |
| * PRECEDING_KEY_WORDS
| |
| * SECTION_UP
| |
| * WHERE_IN_SECTION
| |
| * SAVE_SECTION_TO
| |
| * SAVE_SECTION_ACROSS
| |
| * USE_SECTION
| |
| * MATH_OPERATION
| |
| * INTEGER_TO_FLOAT
| |
| * REPLACE_TYPE
| |
| * VALUE_MATCH
| |
| * VALUE_MATCH_TYPE
| |
| * LINE_OFFSET
| |
| * VALUE_CHANGE_TABLE
| |
| * ADD
| |
| * REMOVE
| |
| <br>
| |
|
| |
| === SPECIAL_KEY_WORDS ===
| |
| Member of: EXML_CHANGE_TABLE<br>
| |
| This is a TABLE of any pair of STRINGS.<br>
| |
| This functions uses special key words to narrow the search in the .EXML file to a specific section of the file.<br>
| |
| Indeed, instead of searching a property inside the whole .EXML file, using this function, AMUMSS will only search inside the section containing the last special key words of the list.
| |
|
| |
| Example: ["SPECIAL_KEY_WORDS"] = {"Keyword1","value1","Keyword2","value2",},
| |
|
| |
| WHAT ARE CONSIDERED SPECIAL_KEY_WORDS?
| |
| * any line with a Property AND a value
| |
| * The value MUST NOT be: "", "True", "False" or a number
| |
| * lines with a value like a filename (???.MBIN or ???.XML for example) are now accepted as SPECIAL_KEY_WORDS
| |
| * You can recognize possible Special keywords by the /> at the end of the line
| |
|
| |
| Example of an .EXML file:
| |
| <Property value="GcGenericReward.xml"> start of a SECTION, can only be used in PRECEDING_KEY_WORDS
| |
| <Property name="Id" value="VEHICLE_SCAN" /> can be used in SPECIAL_KEY_WORDS pair
| |
|
| |
| Notes :
| |
| * You can use "", or {}, or {"",} to tell AMUMSS you want it to search the whole original .EXML file (for certain values in a loop for example)
| |
| * The last "value" of all declared pairs can be set to "IGNORE" for more compatibility. See the script LearnMoreWords.lua as an example.<br>
| |
| * If the line pointed to by the special_key_word pair(s) is found, it will be used by LINE_OFFSET (if any).<br>
| |
| * Works alone or with PRECEDING_KEY_WORDS to narrow the editing section (see MiningLaserSpeed.lua for example).<br>
| |
| * If SPECIAL_KEY_WORDS are used, they are processed BEFORE the PRECEDING_KEY_WORDS unless the flag [PRECEDING_FIRST] = "TRUE" is used.<br>
| |
| <br>
| |
|
| |
| === PRECEDING_FIRST ===
| |
| Member of: EXML_CHANGE_TABLE.<br>
| |
| This boolean variable determines the order in which PRECEDING_KEY_WORDS and SPECIAL_KEY_WORDS are processed by AMUMSS.<br>
| |
| If set to "", nil or "FALSE" (default value), PRECEDING_KEY_WORDS will be processed after SPECIAL_KEY_WORDS.<br>
| |
| Set it to "TRUE" to make it process PRECEDING_KEY_WORDS before SPECIAL_KEY_WORDS.<br>
| |
|
| |
| Example: ["PRECEDING_FIRST"] = "TRUE"
| |
| <br>
| |
|
| |
| === PRECEDING_KEY_WORDS ===
| |
| Member of EXML_CHANGE_TABLE.<br>
| |
| This functions uses keywords to narrow the search in the .EXML file to a specific section of the file.<br>
| |
| Indeed, instead of searching a property inside the whole file, using this function, AMUMSS will only search inside each section containing each key of the list.
| |
|
| |
| Example: ["PRECEDING_KEY_WORDS"] = {"key1","key2","key3",},
| |
|
| |
| Notes :
| |
| * key1, key2, ... defined sub-SECTION heads (SECTIONs) in the EXML file hierarchy.<br>
| |
| * You can recognize keys as their lines ends with "> and not /> like for special key words.<br>
| |
| * Skipping one or more LEVEL can work, specially if you want to specify many sections (see REPLACE_TYPE)<br>
| |
| * You can use "", or {}, or {"",} to tell AMUMSS you want it to search the whole original .EXML file (for certain values in a loop for example)
| |
| * You can use PRECEDING_KEY_WORDS and SPECIAL_KEY_WORDS to narrow the desired section even more.<br>
| |
| <br>
| |
|
| |
| USING PRECEDING_KEY_WORDS AND SPECIAL_KEY_WORDS TOGETHER<br>
| |
| When using SPECIAL_KEY_WORDS, you can use PRECEDING_KEY_WORDS with multiple keys to further refine the desired section.<br>
| |
| If the keys of PRECEDING_KEY_WORDS are not found inside the SPECIAL_KEY_WORDS's SECTION then the last key will be used to try to locate a line inside that SPECIAL_KEY_WORDS's SECTION.<br>
| |
| This single key can be any name or value inside that SPECIAL_KEY_WORDS's SECTION (much better if UNIQUE in that SECTION)<br>
| |
| See MiningLaserSpeed.lua or Multi_PAK_Multi_MBIN_Example_Mod.lua for example.<br>
| |
| If the single "preceding_key_word" word is not found in that SECTION, the whole SPECIAL_KEY_WORDS's SECTION will be used<br>
| |
| <br>
| |
|
| |
| 'Simplified' example EXML with possible keys:
| |
|
| |
| <Property value="GcGenericReward.xml"> --first section start, can be used in PRECEDING_KEY_WORDS
| |
| <Property name="Id" value="VEHICLE_SCAN" /> --This is a child
| |
| <Property name="Common" value="Gc...List.xml"> --second section start, can be used in PRECEDING_KEY_WORDS
| |
| <Property name="Reward" value="GiveAll" /> --This is a child
| |
| <Property name="Count" value="Vector2f.xml"> --third section start, can be used in PRECEDING_KEY_WORDS
| |
| <Property name="x" value="1" /> --This is a child
| |
| <Property name="y" value="1" /> --This is a child
| |
| </Property> --end of third section
| |
| <Property name="List" /> --This is a child
| |
| </Property> --end of second section
| |
| </Property> --end of first section
| |
|
| |
| A few notes :
| |
| * "keys" can be recognized by the end of their line ending with "> (and not />).<br>
| |
| * "keys" should always be declared from the most global to the most specific section<br>
| |
| * Even if you set several keys, they all add up to point a single section.<br>
| |
| * ONLY section start can be used as keys.<br>
| |
| * Childs can be used in SPECIAL_KEY_WORDS to narrow a section even more.<br>
| |
| * PRECEDING_KEY_WORDS rarely define a single line in the EXML file but the start line of the SECTION found can be used as the base for LINE_OFFSET<br>
| |
| * You can check MiningLaserSpeed.lua or Multi_PAK_Multi_MBIN_Example_Mod.lua for more examples on this function<br>
| |
| <br>
| |
|
| |
| === SECTION_UP ===
| |
| Member of: EXML_CHANGE_TABLE.<br>
| |
| This variable tells AMUMSS to search in a parent section relative to the current one.<br>
| |
| The value indicates the parent level relative to the current section.
| |
| Example: ["SECTION_UP"] = 0, means: stay in the current section (default value)
| |
| ["SECTION_UP"] = 1, means: select the section one level upper the current level
| |
| <br>
| |
|
| |
| ===WHERE_IN_SECTION ===
| |
| Member of: EXML_CHANGE_TABLE<br>
| |
| This function will search for a pair of properties and values to narrow the search to this particular section, BUT ONLY if the value has a specific value
| |
|
| |
| Example: ["WHERE_IN_SECTION"] =
| |
| {
| |
| {"NameOrValue1","ComparisonValue1",},
| |
| {"NameOrValue2","ComparisonValue2",},
| |
| },
| |
|
| |
| Notes :
| |
| * NameOrValue can be either the name of a property, either the value itself if it is meaningfull.<br>
| |
| * The value of the found property, either by its name or value, will then be compared to the ComparisonValue.<br>
| |
| * If the values are matching, AMUMSS will then narrow down its search to the section containing this property.<br>
| |
| * "IGNORE" can be used in place of one or both strings<br>
| |
| * An example use can be found in the script RewardTable_Test.lua<br>
| |
| <br>
| |
|
| |
| === SAVE_SECTION_TO ===
| |
| {{fc|#8F8|IN DEVELOPMENT}}<br>
| |
| Member of: EXML_CHANGE_TABLE.<br>
| |
| This function instructs AMUMSS to copy the current section under a specific name for a future use in the script.
| |
|
| |
| Example: ["SAVE_SECTION_TO"] = "CustomSectionName",
| |
|
| |
| Note:
| |
| * only the first section of multiple sections returned by the keywords is saved.
| |
| * If set to "", no section will be copied<br>
| |
| <br>
| |
|
| |
| === SAVE_SECTION_ACROSS ===
| |
| {{fc|#8F8|IN DEVELOPMENT}}<br>
| |
| Member of: EXML_CHANGE_TABLE.<br>
| |
| This boolean variable specify if the saved section will be reachable for this script only or for this script and any other from the Modscript folder.<br>
| |
| If set to "TRUE", the section will only be saved for use in the current script.<br>
| |
| If set to "", nil or "FALSE", the save section will be available for the other scripts too.
| |
|
| |
| Example: ["SAVE_SECTION_ACROSS"] = "FALSE",
| |
| <br>
| |
|
| |
| === USE_SECTION ===
| |
| {{fc|#8F8|IN DEVELOPMENT}}<br>
| |
| Member of: EXML_CHANGE_TABLE.<br>
| |
| This function instructs AMUMSS to paste that previously saved section into the current EXML at the current position.
| |
|
| |
| Example: ["USE_SECTION"] = "CustomSectionName",<br>
| |
| Note : If set to "", no section will be copied.<br>
| |
| <br>
| |
|
| |
| === MATH_OPERATION ===
| |
| Member of: EXML_CHANGE_TABLE.<br>
| |
| This function apply a mathematical operation to an existing numerical value present in the .EXML file.
| |
|
| |
| To work properly, this function needs to respect a few rules :
| |
| * The operation applies at the LINE pointed to by the keywords AND possibly redirected by LINE_OFFSET
| |
| * Operation can only apply to numerical values, not to strings.
| |
| * You can set an operation to "" and no change will be done to the value
| |
|
| |
| The operation is described as a string and can be composed of 3 terms
| |
| * $ wich is the commutation symbol. When used, it commutes the order of the operands so that, for example, (3 - 5 = -2) becomes (5 - 3 = 2)
| |
| * one of the four common operation signs : +, -, / or *. This will apply this operation between the original value and the script value. In this case, the script value doesn't replace the original value but is used as a operand for the original value.
| |
| * a SUFFIX to locate the exact value to apply the operation
| |
|
| |
| SUFFIX F: or FB: AND endString = "IGNORE" or a Property Name STRING (like [MaxAmount] here: <Property name="MaxAmount" value="300" />)<br>
| |
| F: == Fetch Forward from the LINE for endString and get the value on that new line<br>
| |
| FB: == Fetch Backward from the LINE for endString and get the value on that new line
| |
|
| |
| SUFFIX L: or LB: AND NUMBER_OF_LINES<br>
| |
| L: == Lookup Forward from the LINE PLUS NUMBER_OF_LINES and get the value on that new line<br>
| |
| LB: == Lookup Backward from the LINE MINUS NUMBER_OF_LINES and get the value on that new line<br>
| |
|
| |
| {{fc|red|WARNING : avoid using {L:, LB:} as if a single line is added or removed during any NMS update, the script won't work anymore}}
| |
|
| |
| Examples, supposing the .EXML original value is 10 and the script VALUE_CHANGE_TABLE new value is 2 :
| |
|
| |
| ["MATH_OPERATION"] = "*", Final value : 10*2 = 20
| |
| ["MATH_OPERATION"] = "*F:MaxAmount", Final Value : MaxAmount value * 2
| |
| ["MATH_OPERATION"] = "$/", Final value : 2/10 = 0.5
| |
| ["MATH_OPERATION"] = "-$L:5", Final value : 2 minus the value 5 lines below
| |
| <br>
| |
|
| |
| === INTEGER_TO_FLOAT ===
| |
| Member of: EXML_CHANGE_TABLE.<br>
| |
| Force AMUMSS to consider a value as a float even if it has no decimal part.<br>
| |
| This could solve the false positive warnings raised in the mod final report but you have to be sure the edited value is really a float, else MBINCompiler will fail to convert the value anyway.<br>
| |
| Indeed, you may seen this warning in the REPORT.txt file :
| |
| [WARNING]: ORIGINAL and NEW number value have mismatched types (INTEGER vs FLOAT or STRING vs NUMBER)
| |
| This WARNING only tells you that the script is trying to replace an INTEGER like "0" to a new FLOAT value like "0.75", or a STRING to a NUMBER or a NUMBER to a STRING.<br>
| |
| This warning is there to raise potential issue but it can't control the type. Ultimately, if the EXML compiles fines with MBINCompiler then it is alright.
| |
|
| |
| This function can have one of these values:
| |
| * nil, "" or "PRESERVE" : Default setting. Keeps the type of the original value. Float will still be a float, integer will still be an integer (rounding up the value if necessary)
| |
| * "FORCE" : changes the INTEGER value to a FLOAT if necessary
| |
| Example: ["INTEGER_TO_FLOAT"] = "FORCE",
| |
| <br>
| |
|
| |
| === REPLACE_TYPE ===
| |
| Member of: EXML_CHANGE_TABLE<br>
| |
| This variable controls the way AMUMSS deal with search results occurrences of the PRECEDING_KEY_WORDS and SPECIAL_KEY_WORDS.
| |
| Example: ["REPLACE_TYPE"] = "ALL",
| |
|
| |
| Supported values are :
| |
| * nil or "" : AMUMSS will only replace the first line that matches the VALUE_CHANGE_TABLE pairs inside found section(s) (default AMUMSS behaviour)
| |
| * "ALL" : AMUMSS will use all lines that match the VALUE_CHANGE_TABLE pairs inside found section(s) as starting point to replacing content
| |
| * "ALLFOLLOWING" : NOT YET IMPLEMENT == will replace ALL lines that match the VALUE_CHANGE_TABLE pairs FOLLOWING the most recent replaced line (after the first replacement obviously)
| |
| * "ADDAFTERSECTION": When used with ADD, REPLACE_TYPE can only be "ADDAFTERSECTION" to specify to add the TEXT_TO_ADD AFTER the SECTION specified by the SPECIAL_KEY_WORDS and the VALUE_CHANGE_TABLE property
| |
| * RAW replaces property's value on ALL lines where property is found. SPECIAL_KEY_WORDS / PRECEDING_KEY_WORDS and other options can be use to limit the SECTION. NOTE: each RAW only targets one line of the EXML
| |
| * See the "RAW_REPLACEMENT.lua" script in the ModScriptCollection\LearningExamples\Commented folder for some more details<br>
| |
| {{fc|#F88|WARNING: RAW IS POWERFULL AND DANGEROUS, EVEN DESTRUCTIVE IF NOT USED CORRECTLY. USE WITH GREAT CARE}}<br>
| |
| <br>
| |
|
| |
| === VALUE_MATCH ===
| |
| Member of: EXML_CHANGE_TABLE.<br>
| |
| This function will search for any specified value inside the current section.
| |
|
| |
| Example: ["VALUE_MATCH"] = "Snow",
| |
| or ["VALUE_MATCH"] = "5",
| |
|
| |
| You can check CreatureSizeAndSpawnRateIncrease.lua and MoreScreenFilters.lua as examples<br>
| |
| <br>
| |
|
| |
| ===VALUE_MATCH_OPTIONS ===
| |
| Member of: EXML_CHANGE_TABLE.<br>
| |
| This variable defines the comparison used to search the VALUE_CHANGE_TABLE value in the .EXML file.
| |
|
| |
| Example: ["VALUE_MATCH_OPTIONS"] = "~=", search a value different than the one specified
| |
|
| |
| Here are the possible operators:
| |
| * = or "" : Default value. AMUMSS search for a value or string equal to the script value
| |
| * ~= : search for a value or string different to the script value
| |
| * < : search for any value inferior to the script value
| |
| * <= : search for any value inferior or equal to the script value
| |
| * > : search for any value superior to the script value
| |
| * >= : search for any value superior or equal to the script value
| |
| <br>
| |
|
| |
| === VALUE_MATCH_TYPE ===
| |
| Member of: EXML_CHANGE_TABLE.<br>
| |
| Adds a type comparison when searching for the "Property name/value" set in VALUE_CHANGE_TABLE.
| |
|
| |
| Example: ["VALUE_MATCH_TYPE"] = "NUMBER",
| |
| Possible values :
| |
| * "" : AMUMSS won't check the value type
| |
| * "NUMBER" : AMUMSS will only stop on lines if the value found is a number
| |
| * "STRING" : AMUMSS will only stop on lines if the value found is a string
| |
| <br>
| |
|
| |
| === LINE_OFFSET ===
| |
| Member of: EXML_CHANGE_TABLE.<br>
| |
| This function will focus on a value one or several lines before or after the one found with SPECIAL_KEY_WORDS and PRECEDING_KEY_WORDS<br>
| |
| {{fc|red|WARNING : if possible, avoid using LINE_OFFSET because if a single line is added or removed during any NMS update, the script won't work anymore}}<br>
| |
|
| |
| Example: ["LINE_OFFSET"] = "-15",
| |
|
| |
| Notes :
| |
| * The offset value can be positive (go up in the file) or negative (go down in the file)
| |
| * If a line is found using the SPECIAL_KEY_WORDS, it is used as the starting point otherwise, the start line of the SECTION found using the PRECEDING_KEY_WORDS will be used
| |
| * when ADD function is used, the line the new section is inserted is the NEXT line
| |
| * when REMOVE function is used, the line used (to define the SECTION or the LINE to REMOVE) is the line found
| |
| * For a script example see LodDistanceScale.lua or TerrainEditorMod.lua
| |
| <br>
| |
|
| |
| === VALUE_CHANGE_TABLE ===
| |
| Member of: EXML_CHANGE_TABLE.<br>
| |
| This function will replace the .EXML original value of a property by a new one.<br>
| |
| It takes one or several pairs of strings:
| |
| * The first string is either the property name or the original value.
| |
| * The second string is for the new value.
| |
|
| |
| Example:
| |
| ["VALUE_CHANGE_TABLE"] =
| |
| {
| |
| {"Property name/value1","newvalue1",},
| |
| {"Property name/value1","newvalue1",},
| |
| },
| |
|
| |
| Either string can be set to "IGNORE".<br>
| |
| In that case, AMUMSS will do NO exchange for this line and continue processing the next Property name/value
| |
| This can be useful to update a group of numerical 'Property value='.
| |
|
| |
| Example :
| |
| [MATH_OPERATION] = "*",
| |
| ["VALUE_CHANGE_TABLE"] = {{"IGNORE","1.5"},},
| |
| This will multiply each value by 1.5 without the need for [LINE_OFFSET].<br>
| |
| <br>
| |
|
| |
| === ADD ===
| |
| Member of: EXML_CHANGE_TABLE.<br>
| |
| This function adds lines or whole SECTION inside a the .EXML file.
| |
| :- Can be of type "string" or <nowiki>[[long string]]</nowiki> or a user named variable of those types (like TEXT_TO_ADD)
| |
|
| |
| Example: ["ADD"] = "a short string", Adds a string
| |
| or ["ADD"] = [[a
| |
| multi-line
| |
| string]], Adds 3 lines in the file
| |
| or ["ADD"] = MY_VARIABLE, Adds the content of MY_VARIABLE defined before the opening MODIFICATIONS SECTION
| |
|
| |
| Notes :
| |
| * Can be used with SPECIAL_KEY_WORDS, PRECEDING_KEY_WORDS, LINE_OFFSET, VALUE_MATCH, VALUE_MATCH_TYPE and REPLACE_TYPE
| |
| " "Property name/value1" of VALUE_CHANGE_TABLE can be used to specify a sub-SECTION of the SPECIAL_KEY_WORDS + PRECEDING_KEY_WORDS SECTION
| |
| * Used with REPLACE_TYPE = "ADDAFTERSECTION", AMUMSS will find the end of the SECTION and then ADD the text
| |
| * Used with LINE_OFFSET, the TEXT_TO_ADD is added EXACTLY AFTER the line found.
| |
| * See the ADD_REMOVE_TEXT_EXAMPLE.lua example in "ModScriptCollection\LearningExamples\Commented\" folder
| |
| * See also the LearnMoreWords.lua script in "ModScriptCollection" folder
| |
| NOTE: If you use both ADD and REMOVE inside the same EXML_CHANGE_TABLE, the respective TEXT will be "added" first AND the "removed" second.<br>
| |
| <br>
| |
|
| |
| === REMOVE ===
| |
| Member of: EXML_CHANGE_TABLE.<br>
| |
| This function removes the currently pointed section or line.
| |
|
| |
| Example: ["REMOVE"] = "SECTION",
| |
|
| |
| Possible values :
| |
| * "" or {} or {"",} : all these mean: no REMOVE to use
| |
| * "SECTION" : the whole section currently pointed will be removed
| |
| * "LINE" : the currently pointed line will be removed
| |
|
| |
| As for every function, you can narrow the scope of the search to a line/section with SPECIAL_KEY_WORDS, PRECEDING_KEY_WORDS, LINE_OFFSET, VALUE_MATCH, VALUE_MATCH_TYPE and REPLACE_TYPE.<br>
| |
| With LINE_OFFSET, the REMOVE action happens AT the line found for LINE or the SECTION.<br>
| |
| NOTE: If you use both ADD and REMOVE inside the same EXML_CHANGE_TABLE, the respective TEXT will be "added" first AND the "removed" second.<br>
| |
| <br>
| |
|
| |
| === ADD_FILES ===
| |
| Member of: NMS_MOD_DEFINITION_CONTAINER.<br>
| |
| This function can add files to the final mod.
| |
|
| |
| see StandardSchemeExtended.lua and ADD_NEW_FILES_EXAMPLE.lua scripts for more details
| |
|
| |
| Possible members of ADD_FILES (order independant):
| |
| * FILE_DESTINATION
| |
| * EXTERNAL_FILE_SOURCE
| |
| * FILE_CONTENT
| |
| <br>
| |
|
| |
| === FILE_DESTINATION ===
| |
| Member of: ADD_FILES<br>
| |
| This variable hosts the path and name of the new file to create.
| |
|
| |
| Example : ["FILE_DESTINATION"] = "METADATA\NEWFILE.EXML",
| |
| <br>
| |
|
| |
| === EXTERNAL_FILE_SOURCE ===
| |
| Member of: ADD_FILES<br>
| |
| This variable hosts the path and name of a distinct file
| |
|
| |
| Example : ["EXTERNAL_FILE_SOURCE"] = "MYFOLDER\MYFILE.EXML",
| |
| <br>
| |
|
| |
| === FILE_CONTENT ===
| |
| Member of: ADD_FILES<br>
| |
| This variable can contain the text of your new file.
| |
|
| |
| Example :
| |
| ["FILE_CONTENT"] =
| |
| [[
| |
| NEW TEXT TO ADD HERE (EXML CODE and everything else)
| |
| ]]
| |
| <br>
| |
|
| |
| == ADVANCED SCRIPT RULES / TIPS ==
| |
|
| |
| === Tip #1 - Loops ===
| |
| In a loop, it is much faster to use a table to store strings and do a table.concat() than to concatenate strings.<br>
| |
| <br>
| |
| As an example, this function will take 50 seconds to complete
| |
| function UsingConcatenation()
| |
| local NbIteration = 200000
| |
| print("NbIteration = "..NbIteration)
| |
| local a = "MyString"
| |
| local b = a
| |
| for i=1,NbIteration do
| |
| b = b..a
| |
| end
| |
| print(#b)
| |
| end
| |
|
| |
| But this one will only take 1 second
| |
| function UsingTable()
| |
| local NbIteration = 200000
| |
| print("NbIteration = "..NbIteration)
| |
| local a = "MyString"
| |
| local T = {}
| |
| T[1] = a
| |
| for i=1,NbIteration do
| |
| T[#T+1] = a
| |
| end
| |
| b = table.concat(T)
| |
| print(#b)
| |
| end
| |
| <br>
| |
|
| |
| === Tip #2 : False positive conflicts ===
| |
| AMUMSS report any conflict it will detect, but it can sometimes detect false positive.
| |
| The following cases could cause such false positive :
| |
| * You previously created the same .pak file and placed it in the game MODS folder. As AMUMSS compare this mod to these in the MODS folder, a conflict could be raised.
| |
| * You are merging 2 mods editing the same .MBIN file. AMUMSS doesn't check if the same value is edited, only if the same file is edited, and will raise a conflict.
| |
|
| |
| In such cases, you can safely disregard these conflicts.
| |
