M3EC Docs

Welcome to the M3EC Advanced Documentation.
M3EC is built to be very extensible, and has its own scripting language in addition to dictionary and template file formats.

This documentation is currently incomplete!

Individual loader/version builds are largely configurable.
See m3ec_build.json files within loader/version folders in the data folder for examples.
Example: M3EC/data/forge1.20.1/m3ec_build.json

M3EC Template Syntax

Specific patterns within template strings are replaced using values from the global dictionary.

${key}: Resolves to the value of the key if it exists.
---ifN key\n ... ---fiN: Only writes the data if the value of the key is true.
---iterN key\n ... ---endN: Writes the data for each entry in the value of the key.
Sets $%v to the value of each entry, $%i to the value of each index.
---listN key\n ... ---endN: Writes the data for each entry in the value of the key, joined with commas.
Sets $%v to the value of each entry, $%i to the value of each index.

Template System Notes

...: Corresponds to any text data.
\n: Corresponds to a newline character
N: Can be empty, or 0 through 9.
Used in places where you need if inside an if or iter/list in an iter/list.

Template System Special Keys

$%v: Replaced with the current value of iter/list
$%i: Replaced with the current index of iter/list
%v: Replaced with the current iteration value (for iterating actions)
%i: Replaced with the current iteration index (for iterating actions)
$%a: Replaced with the last computed value if the destination for that value was not specified. (actions)

Template System Examples

---iter some_key\n $%v---end: iterate through the value of some_key, writing each value.
If the value is the list ["a", "b", "c", "d", 1, 2, 3, 4]
then this will write the string "abcd1234"
---list some_key\n---if ?$%i < 3\n$%i---fi---end: iterate through the value of some_key, writing only indices prior to 3, joined with commas.
If the value is the list [1, 2, 3, 4, 5, 6, 7, 8]
then this will write the string "1,2,3"

M3EC Actions Scripting Syntax

Actions are written as json files containing an array of action steps, any of which can be conditional, many can be iterated.

Keys Valid for all Actions

iterate: Repeat this step for each entry of the specified key, setting the keys "%i" and "%v" to the current index and value respectively.
if: Execute this step if the condition is true. See below for condition syntax.
action: Set the action that this step performs.

List of Actions

appendkey: Appends the value "value" to the key "key", making it a list if it isn't one already or isn't defined yet.
copy: Copy file/directory "source" to file/directory "dest".
copyf: Copy file "source" to file "dest", running the data through the template system first.
doactions: Executes the actions "actions" while the condition "while" is true, or until condition "until" is true.
If the condition "while" evaluates to false, this will not execute the actions.
If the condition "until" is set, this will execute the actions at least once.
Sets the key "%i" to the current run count.
error: Print string "string", key "var", and string "value" to the console, then exit. (Exits M3EC, effectively cancelling all builds)
execactions: Execute actions list "actions" or from json file "file"
exit: Exit with error code "code", (1 if unspecified) printing string "string" to the console if specified.
getkey: Gets the value of the key "key" and stores it to another key "var"
If dictionary "dict" is specified, use it instead of the global dictionary.
makedir: Creates directory "value" if it doesn't exist yet. ("value" can be a list of directory strings)
movef: Moves file "source" to file "dest", running the data through the template system first.
print: Print string "string", key "var", and string "value" to the console.
readf: Run file "file" or string "data" through the template system, storing to the key "key".
If dictionary "dict" is specified, use it instead of the global dictionary.
repeatactions: Execute actions list "actions", "repeat" times. Sets the key "%i" with the current run count.
return: Return from executing this list of actions, returning value "value" if specified.
setkey: Stores the value "value" to the key "key".
write: Writes the data "data" to the file "file".

Conditions Syntax

A condition can be a string or a list of conditions. (recursive)
Each string can be a single key to check, or a special condition.
Condition strings are run through the template system before being evaluated.

!: Prefix to invert the condition.
keyexists key: Evaluates to true if the key exists.
?key: Evaluates to true if the key's value evaluates to true. (bool or number>0 or str==true/yes)
?key [#...]: Checks the value of the key using other methods. See Below.

Condition String Methods

Only one method will be executed if more than one is present.
These methods are applied on the value of the key.

#contains str: Evaluates to true if the string is contained in the value. (false if not a string)
#containskey key: Evaluates to true if the key is defined in the value. (false if not a dictionary)
#equals value: Evaluates to true if the values are equal.
#length zero: Evaluates to true if the length of the string is 0.
#length nonzero: Evaluates to true if the length of the data is greater than 0. (false if not a string, list, tuple, or iterable)
#startswith str: Evaluates to true if the value starts with the string. (false if not a string)
#typeis type: Evaluates to true if the value is of type type. Types: int float str list tuple dict number iterable none

Condition List Special Operators

These operators are used to determine the result of the list of conditions.

Operators are applied sequentially. For AND and OR operators this doesn't matter, but XOR and XNOR might give unexpected results for more than two items.

^OR: Logical OR conditions together
^AND: Logical AND conditions together
^XOR: Logical XOR (one but not the other) conditions together
^XNOR: Logical XNOR (both or neither) conditions together