NoMansSky:Deleted: Difference between revisions

From Step Mods | Change The Game
Line 25: Line 25:
* Each level ends with </Property> except the TOP level which ends with </Data>
* Each level ends with </Property> except the TOP level which ends with </Data>
* Every new level (SECTION) starts with a line ending with ">
* Every new level (SECTION) starts with a line ending with ">
* Every child section ends with />
* Every child property 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 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
* a SECTION can contain any number of sub-sections

Revision as of 16:57, September 6, 2020

Template:TOC right

Introduction[edit | edit source]

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.
It's a powerful tool once mastered.
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.
All the content below is based on Wbertro's Script Rules but rewritten especially for this wiki version.

LUA[edit | edit source]

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}


Notes[edit | edit source]

  • AMUMSS edits .EXML files.So all it functions refer to .EXML content
  • .EXML files are basicaly formatted text files
  • the TOP level is always <Data template="something"> AND this value is NOT used by the tool
  • Each level ends with </Property> except the TOP level which ends with
  • Every new level (SECTION) starts with a line ending with ">
  • Every child property 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


Script Template[edit | edit source]

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.


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.

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"}, 
			    }	
			},
		    }
		},
 	    }
 	},
    }
}


SCRIPT STRUCTURE[edit | edit source]

AMUMSS scripts have to respect some hierarchy.
This is the hierarchy of the possible content of a script:

NMS_MOD_DEFINITION_CONTAINER - REQUIRED
MOD_FILENAME
MOD_AUTHOR
MOD_DESCRIPTION
NMS_VERSION
MOD_BATCHNAME
ADD_FILES
FILE_DESTINATION
EXTERNAL_FILE_SOURCE
FILE_CONTENT
MODIFICATIONS - REQUIRED
PAK_FILE_SOURCE
MBIN_CHANGE_TABLE - REQUIRED
MBIN_FILE_SOURCE - REQUIRED
REGEXBEFORE
REGEXAFTER
EXML_CHANGE_TABLE - 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 realy needs 5 required table declarations and all the other members are optional.

NMS_MOD_DEFINITION_CONTAINER[edit | edit source]

REQUIRED
This is the Master Table. It defines that the following text is a script.

Here are the possible members (order independant):

  • MOD_FILENAME
  • MOD_AUTHOR
  • MOD_DESCRIPTION
  • NMS_VERSION
  • MOD_BATCHNAME
  • ADD_FILES
  • MODIFICATIONS


MOD_FILENAME[edit | edit source]

Member of: NMS_MOD_DEFINITION_CONTAINER.
This variable hosts the name of your final mod .pak file.
Note that the maximum name length can't exceed 106 chars + .pak

if MOD_FILENAME is not found, the created mod will be named 'GENERIC.pak' and a WARNING will be issued.

Example: ["MOD_FILENAME"] = "MyMod.pak",


MOD_AUTHOR[edit | edit source]

Member of: NMS_MOD_DEFINITION_CONTAINER.
This variable hosts the name of the script author. It is currently only a reference.

Example: ["MOD_AUTHOR"] = "I am the author",


MOD_DESCRIPTION[edit | edit source]

Member of: NMS_MOD_DEFINITION_CONTAINER.
This variable hosts the description of the mod. It is currently only a reference.

Example: ["MOD_DESCRIPTION"] = "This mod does so much it can't fit here",


NMS_VERSION[edit | edit source]

Member of: NMS_MOD_DEFINITION_CONTAINER.
This variable hosts the NMS version the script was written for. It is currently only a reference.

Example: ["NMS_VERSION"] = "1.77",


MOD_BATCHNAME[edit | edit source]

Member of: NMS_MOD_DEFINITION_CONTAINER.
This variable supersides MOD_FILENAME when more than one .lua scripts are present.
As for MOD_FILENAME, maximum name length is 106 chars + .pak

Example:  ["MOD_BATCHNAME"] = "MySetofMods.pak",


MODIFICATIONS[edit | edit source]

REQUIRED
Member of: NMS_MOD_DEFINITION_CONTAINER.
This is a table containing one or many tables.
This can be used with or without ADD_FILES and becomes OPTIONAL if ADD_FILES is used.

Here are the possible members (independant order):

  • PAK_FILE_SOURCE
  • MBIN_CHANGE_TABLE


PAK_FILE_SOURCE[edit | edit source]

Member of: MODIFICATIONS.
This variable is optional and not necessary anymore.
It sets the original NMS .pak name as found in the NMS/PCBANKS folder containing the files this mod will edit.
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

Example:  ["PAK_FILE_SOURCE"] = "NMSARC.59B126E2.pak",


MBIN_CHANGE_TABLE[edit | edit source]

REQUIRED
Member of: MODIFICATIONS.
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


MBIN_FILE_SOURCE[edit | edit source]

REQUIRED
Member of: MBIN_CHANGE_TABLE
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.
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.
If Optional_Flag is set to "REMOVE" then the original .MBIN file will NOT be included in the mod pak.

REGEXBEFORE[edit | edit source]

Member of: MBIN_CHANGE_TABLE
If use, will invoque a regex utility to process the EXML file BEFORE any script processing
This is a table of (two STRINGs)table(s) like {{"ToFindRegex","ToReplaceRegex"},...},

Eample: ["REGEXBEFORE"] = {
			{((.*Unknown.*)(True)),\2False},
			...
			},

Sed regex rules apply (see https://www.gnu.org/software/sed/)

REGEXAFTER[edit | edit source]

Member of: MBIN_CHANGE_TABLE
If use, will invoque a regex utility to process the EXML file AFTER the script processing
This is a table of (two STRINGs)table(s) like {{"ToFindRegex","ToReplaceRegex"},...},

Example:: ["REGEXAFTER"] = {
				{((.*Unknown.*)(True)),\2False},
				...
				},

Sed regex rules apply (see https://www.gnu.org/software/sed/)

EXML_CHANGE_TABLE[edit | edit source]

REQUIRED
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


SPECIAL_KEY_WORDS[edit | edit source]

Member of: EXML_CHANGE_TABLE
This is a TABLE of any pair of STRINGS.
This functions uses special key words to narrow the search in the .EXML file to a specific section of the file.
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.
  • If the line pointed to by the special_key_word pair(s) is found, it will be used by LINE_OFFSET (if any).
  • Works alone or with PRECEDING_KEY_WORDS to narrow the editing section (see MiningLaserSpeed.lua for example).
  • If SPECIAL_KEY_WORDS are used, they are processed BEFORE the PRECEDING_KEY_WORDS unless the flag [PRECEDING_FIRST] = "TRUE" is used.


PRECEDING_FIRST[edit | edit source]

Member of: EXML_CHANGE_TABLE.
This boolean variable determines the order in which PRECEDING_KEY_WORDS and SPECIAL_KEY_WORDS are processed by AMUMSS.
If set to "", nil or "FALSE" (default value), PRECEDING_KEY_WORDS will be processed after SPECIAL_KEY_WORDS.
Set it to "TRUE" to make it process PRECEDING_KEY_WORDS before SPECIAL_KEY_WORDS.

Example: [PRECEDING_FIRST] = "TRUE"


PRECEDING_KEY_WORDS[edit | edit source]

Member of EXML_CHANGE_TABLE.
This functions uses keywords to narrow the search in the .EXML file to a specific section of the file.
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.
  • You can recognize keys as their lines ends with "> and not /> like for special key words.
  • Skipping one or more LEVEL can work, specially if you want to specify many sections (see REPLACE_TYPE)
  • 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.


USING PRECEDING_KEY_WORDS AND SPECIAL_KEY_WORDS TOGETHER
When using SPECIAL_KEY_WORDS, you can use PRECEDING_KEY_WORDS with multiple keys to further refine the desired section.
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.
This single key can be any name or value inside that SPECIAL_KEY_WORDS's SECTION (much better if UNIQUE in that SECTION)
See MiningLaserSpeed.lua or Multi_PAK_Multi_MBIN_Example_Mod.lua for example.
If the single "preceding_key_word" word is not found in that SECTION, the whole SPECIAL_KEY_WORDS's SECTION will be used

'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, can only be used as SPECIAL_KEY_WORDS pair
  <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, can only be used as SPECIAL_KEY_WORDS pair
    <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, can only be used as SPECIAL_KEY_WORDS pair
      <Property name="y" value="1" />			    --This is a child, can only be used as SPECIAL_KEY_WORDS pair
    </Property>					    --end of third section
    <Property name="List" />                        	    --This is a child, can only be used as SPECIAL_KEY_WORDS pair       
  </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 />).
  • "keys" should always be declared from the most global to the most specific section
  • Even if you set several keys, they all add up to point a single section.
  • ONLY section start can be used as keys.
  • Childs can be used in SPECIAL_KEY_WORDS to narrow a section even more.
  • 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
  • You can check MiningLaserSpeed.lua or Multi_PAK_Multi_MBIN_Example_Mod.lua for more examples on this function


SECTION_UP[edit | edit source]

Member of: EXML_CHANGE_TABLE.
This variable tells AMUMSS to search in a parent section relative to the current one.
The value indicates the parent level relative to the current section.

Example: ["SECTION_UP"] = 0,     means: stay in the selection section (default value)
         ["SECTION_UP"] = 1,     means: select the level one up from the current level


WHERE_IN_SECTION[edit | edit source]

Member of: EXML_CHANGE_TABLE
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.
  • The value of the found property, either by its name or value, will then be compared to the ComparisonValue.
  • If the values are matching, AMUMSS will then narrow down its search to the section containing this property.
  • "IGNORE" can be used in place of one or both strings
  • An example use can be found in the script RewardTable_Test.lua


SAVE_SECTION_TO[edit | edit source]

IN DEVELOPMENT
Member of: EXML_CHANGE_TABLE.
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


SAVE_SECTION_ACROSS[edit | edit source]

IN DEVELOPMENT
Member of: EXML_CHANGE_TABLE.
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.
If set to "TRUE", the section will only be saved for use in the current script.
If set to "", nil or "FALSE", the save section will be available for the other scripts too.

Example: ["SAVE_SECTION_ACROSS"] = "FALSE",


USE_SECTION[edit | edit source]

IN DEVELOPMENT
Member of: EXML_CHANGE_TABLE.
This function instructs AMUMSS to paste that previously saved section into the current EXML at the current position.

Example: ["USE_SECTION"] = "CustomSectionName",

Note : If set to "", no section will be copied.

MATH_OPERATION[edit | edit source]

Member of: EXML_CHANGE_TABLE.
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" />)
F: == Fetch Forward from the LINE for endString and get the value on that new line
FB: == Fetch Backward from the LINE for endString and get the value on that new line

SUFFIX L: or LB: AND NUMBER_OF_LINES
L: == Lookup Forward from the LINE PLUS NUMBER_OF_LINES and get the value on that new line
LB: == Lookup Backward from the LINE MINUS NUMBER_OF_LINES and get the value on that new line

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      


INTEGER_TO_FLOAT[edit | edit source]

Member of: EXML_CHANGE_TABLE.
Force AMUMSS to consider a value as a float even if it has no decimal part.
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.
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.
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",


REPLACE_TYPE[edit | edit source]

Member of: EXML_CHANGE_TABLE
This variable controls the way AMUMSS deal with search results occurences 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 key_words (default AMUMSS behaviour)
  • "ALL" : AMUMSS will replace all lines that match the VALUE_CHANGE_TABLE pairs inside the current section
  • "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

WARNING: RAW IS POWERFULL AND DANGEROUS, EVEN DESTRUCTIVE IF NOT USED CORRECTLY. USE WITH GREAT CARE

VALUE_MATCH[edit | edit source]

Member of: EXML_CHANGE_TABLE.
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

VALUE_MATCH_OPTIONS[edit | edit source]

Member of: EXML_CHANGE_TABLE.
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


VALUE_MATCH_TYPE[edit | edit source]

Member of: EXML_CHANGE_TABLE.
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


LINE_OFFSET[edit | edit source]

Member of: EXML_CHANGE_TABLE.
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
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

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


VALUE_CHANGE_TABLE[edit | edit source]

Member of: EXML_CHANGE_TABLE.
This function will replace the .EXML original value of a property by a new one.
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".
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].

ADD[edit | edit source]

Member of: EXML_CHANGE_TABLE.
This function adds lines or whole SECTION inside a the .EXML file.

- Can be of type "string" or long string 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.

REMOVE[edit | edit source]

Member of: EXML_CHANGE_TABLE.
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.
With LINE_OFFSET, the REMOVE action happens AT the line found for LINE or the SECTION.
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.

ADD_FILES[edit | edit source]

Member of: NMS_MOD_DEFINITION_CONTAINER.
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


FILE_DESTINATION[edit | edit source]

Member of: ADD_FILES
This variable hosts the path and name of the new file to create.

Example : ["FILE_DESTINATION"] = "METADATA\NEWFILE.EXML",


EXTERNAL_FILE_SOURCE[edit | edit source]

Member of: ADD_FILES
This variable hosts the path and name of a distinct file

Example : ["EXTERNAL_FILE_SOURCE"] = "MYFOLDER\MYFILE.EXML",


FILE_CONTENT[edit | edit source]

Member of: ADD_FILES
This variable can contain the text of your new file.

Example :
  ["FILE_CONTENT"] =	
    [[
      NEW TEXT TO ADD HERE (EXML CODE and everything else)
    ]]


ADVANCED SCRIPT RULES / TIPS[edit | edit source]

Tip #1 - Loops[edit | edit source]

In a loop, it is much faster to use a table to store strings and do a table.concat() than to concatenate strings.

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


Tip #2 : False positive conflicts[edit | edit source]

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.
Template:NMSPageClose