Localized docs basics/*, getting-started/* and blocks/*

Author: rislaed

docs/basics/building-script.md

@@ -1,9 +1,126 @@
----
-hide_title: true
----
+# Script Building
 
-```mdx-code-block
-import NotLocalized from "@site/src/components/NotLocalized"
+In addition to the ability to directly specify an executable script, there is often a need to split the source code into files. As soon as the project starts to contain the first classes, utility functions, and other things that should be separated, working in one file becomes simply impossible. This is where build files come to our aid, as well as advanced toolchain settings.
 
-<NotLocalized />
+## Compiling Files
+
+The `compile` property is used to run files; adding any script to it will lead to its execution. We have already considered the description of its element:
+
+```json
+{
+    "path": "relative path from the folder where build.config is located",
+    "sourceType": "launcher, main, custom, preloader or library"
+}
+```
+
+If you do not know which `sourceType` to choose, consider [Mod Lifecycle](TODO). As already mentioned, the `compile` property defines scripts that will be compiled and loaded. For example, *build.config* might look like this:
+
+```json title="build.config"
+{
+    ...
+    "compile": [
+        {
+            "path": "main.js",
+            "sourceType": "main"
+        }
+    ]
+}
+```
+
+Which means that the script will be loaded from the current folder from the file *main.js* and will start after calling `Launch();` from the project launcher. But in this case, the file is not built, but simply loaded from an existing one. And what if we want to assemble several files into one?
+
+## There Can Be Any Number of Scripts
+
+And to assemble them all, you need to combine the scripts into one. Inner Core or the Toolchain's TypeScript Compiler will do this for you, depending on which platform you are using.
+
+Let's start with defining the `buildDirs` property of your *build.config* for assembly:
+
+```json title="build.config"
+{
+    ...
+    "buildDirs": [
+        {
+            "targetSource": "main.js",
+            "dir": "dev/"
+        }
+    ]
+}
+```
+
+Now files located in the *dev/* folder will be assembled into the *main.js* file, which we defined earlier. But to determine which scripts will be assembled, in addition to this, we need to define an *.includes* file in the created *dev/* directory.
+
+## .includes
+
+The file describes the list of files that will be included in the final script. Let's consider its implementation with an example:
+
+```gitignore title=".includes"
+# comments can describe why a particular file is included
+header.js
+
+api/tests.js
+api/globals.js
+
+# all files in the folder will be included, in the case of toolchain
+# subfolders are also included additionally
+module/.
+
+// comments can also be used in this form
+```
+
+Empty lines and comments are ignored when building files. In this case, at least three files will be included in the script: *header.js*, as well as *tests.js* and *globals.js* in the *api/* folder. The *module/* folder may not exist at all. Non-existent files are ignored, sending a warning about this to the log.
+
+These same rules apply to the toolchain, however comments in it can contain properties for configuring *tsconfig.json*.
+
+### The Power of Toolchain Comments
+
+Build files in the toolchain, in addition to describing the list of files, can contain a description for compiler options, as well as exceptions for files already included in the build:
+
+```gitignore title=".includes"
+# removeComments
+// checkJs: true
+
+# lib: es6, es2016.array.include
+
+header.js
+
+# very important files
+module/.
+
+!module/tests.ts
+
+# target: es3
 ```
+
+The *header.js* file and all files from the *module/* folder and subfolders will be included in the build, excluding *module/tests.ts*. Files are included as well as excluded only if they exist. Since the toolchain builds *tsconfig.json*, paths can also contain glob selections for files:
+
+```gitignore title=".includes"
+module/tile_*.js
+```
+
+Thus, the files *module/tile_chest.js* and *module/tile_advanced_workbench.js* will be included, but *module/bounce.js* and *module/tile_bedrock.ts* will not be included.
+
+:::info Analysis of compiler option description
+
+Comments will be excluded from the assembled script (and from declarations too), JavaScript will be type-checked just like TypeScript, instead of the latest libraries only ES6 (ES2015) and `Array.include` from ES2016 will be included, and the output script will be presented in ES3 instead of ES5. If you do not need any of these options or any other, just do not use them.
+
+:::
+
+## Building with Toolchain
+
+Apart from the build file description, the structure above does not apply to the toolchain. The toolchain automatically determines the passed values, defining what needs to be assembled, a file or a folder. In addition, it supports building using TypeScript. To assemble or compile the desired file, use:
+
+```json title="make.json"
+{
+    ...
+    "sources": [
+        {
+            "type": "main",
+            "source": "dev",
+            "language": "typescript",
+            "target": "main.js"
+        }
+    ]
+}
+```
+
+This will do the same as the `compile` and `buildDirs` properties described earlier; but also, files that have the *.ts* extension will be assembled. Study the *make.json* properties for more details.

docs/basics/evaluate-context.md

@@ -1,9 +1,102 @@
----
-hide_title: true
----
+# Execution Context
 
-```mdx-code-block
-import NotLocalized from "@site/src/components/NotLocalized"
+Defines the space where all your code resides. Variables and constant values, functions, and converted classes are stored here, and future code interactions with the space are performed here.
 
-<NotLocalized />
+Each function and object can create its own, so-called "local" space. It is not available from the outside, but values from it can be obtained through the hierarchy below. I think if most of what is written remains unclear, it is time to fix this problem.
+
+## API — Global Context
+
+If in browsers, and other browser-like engines, the main object is the page whose content we modify, then in the case of Inner Core, we interact directly with the game. And for this we need spaces, methods, and classes, which are in the global context.
+
+Inner Core defines several global contexts, each with its own specific goals. For many years, the main one has been Core Engine, since the entire functionality of the launcher is located around it. This context extends the capabilities of another, Adapted Script. It provides purely native methods provided by the game itself, or auxiliary ones for the operation of Core Engine itself. There are also Preloader, used exclusively by the preloader, and Preferences Window API, which was used for the functioning of the workbench, and once for in-game mod settings. Their use is quite specific, so we will not consider them in detail.
+
+```md
+- AdaptedScript
+    - CoreEngine
+- PrefsWinAPI
+- Preloader
+```
+
+These contexts are used in every script and are described in the `api` properties of your *build.config*.
+
+In the case of Core Engine, it is possible to change the global context, as done, for example, in Ender IO:
+
+```js title="dev/Base/Items/powder.js"
+// highlight-malformed-start
+Item.createDyeItem = function(id, name, type) {
+    IDRegistry.genItemID(id);
+    Item.createItem(id, name, {
+        name: "item_material_organic_" + type + "_dye"
+    }, { stack: 64 });
+};
+// highlight-malformed-end
+
+Item.createDyeItem("greenDye", "Organic Green Dye", "green");
+Item.createDyeItem("blackDye", "Organic Black Dye", "black");
+Item.createDyeItem("brownDye", "Organic Brown Dye", "brown");
+```
+
+However, think about the consequences, this will change the context in all mods. That is, the `Item.createDyeItem` method can be called from any mod if Ender IO is installed. But in this case, there is also a danger of replacing existing methods or those added with updates. If you need to export something, consider [ModAPI.registerAPI](TODO), it was created specifically for these purposes.
+
+### Global Values
+
+Each context defines its own namespace, access to which can be used to obtain values or perform actions. However, in addition to values in the context, the engine provides built-in values exclusive to each mod individually. These values are the same regardless of which script this space touches. This includes technical values, mod information, and in-game constants.
+
+```js
+const MINECRAFT_VERSION = getMCPEVersion();
+if (MINECRAFT_VERSION.main == 16) {
+    alert("Minecraft " + MINECRAFT_VERSION.str + " is currently relevant!");
+    // outputs: Minecraft 1.16.201 is currently relevant!
+} else if (MINECRAFT_VERSION.main == 11) {
+    alert("Legacy version " + MINECRAFT_VERSION.array.join("-") + " is not relevant for " + __name__);
+    // outputs: Legacy version 1-11-4 is not relevant for <mod name>
+}
+```
+
+The `getMCPEVersion` and `alert` methods here are part of the global API context, while `__name__` is a global value available from any part of the mod. You do not need to think about what properties are available here, they are listed in the API summary and toolchain declarations.
+
+## Script Body
+
+The last and most important step in the formation of your space is the code itself. JavaScript uses Rhino 1.7.7 (partially supporting ES6, however, most of the functionality remained in the ES5 implementation) as the main engine that executes all scripts. The language is interpreted, which means it is processed in real time, or with minimal processing before launch. All code is executed sequentially, and by script body we mean all the code that is contained in the files included in the build.
+
+The script is usually executed once, and any spaces it defines (this can be variables or constants, as well as objects or functions) are activated as a result of events. The content, the logic of your mod is defined in the body, other content is integrated, and everything else that the engine is capable of in principle.
+
+## Restartable Contexts
+
+Considering the life cycle earlier, we superficially introduced __custom__ scripts. Unlike other scripts, this is the only type that can be run any number of times, and in addition, accepts and returns values. Probably, you could have associations with functions if acquaintance with the language once went successfully. But unlike functions, these are still spaces; they work in a new context and store values.
+
+Consider this with an example from Solar Flux Reborn:
+
+```js title="dev/tests.js"
+alert(
+    runCustomSource("custom.js", {
+        THUNDER_MULTIPLIER: 0.4,
+        RAIN_MULTIPLIER: 0.6,
+        WEATHER: World.getWeather()
+    })
+);
 ```
+
+Values passed to the space will be overwritten or created if they do not exist yet. Any constants created in the body of restartable scripts must be set only once. Their repeated modification will cause an error, in which case a simple option would be to place them between `try-catch`.
+
+```js title="custom.js"
+let raining = WEATHER.rain / 10;
+raining = raining > 0.2 ? (raining - 0.2) / 0.8 : 0;
+raining = Math.sin(raining * Math.PI / 2);
+raining = 1 - raining * (1 - RAIN_MULTIPLIER);
+
+let thundering = WEATHER.thunder / 10;
+thundering = thundering > 0.75 ? (thundering - 0.75) / 0.25 : 0;
+thundering = Math.sin(thundering * Math.PI / 2);
+thundering = 1 - thundering * (1 - THUNDER_MULTIPLIER);
+
+// Values must still be returned by a function, since
+// the script body is not capable of returning anything
+(function() {
+    return raining * thundering;
+})();
+```
+
+Depending on weather conditions, the efficiency of solar panels changes, values from the current space are involved. Thus, `runCustomSource("custom.js")` will not change the values and will return the previous result. The context does not change, so the values remain the same.
+
+Modding tools use this type to execute code during the game. Since their space is easily configured and saved between different executions independently of the rest of the mod context, subdividing the main code here was a good idea. A more concrete way to use these scripts simply does not exist. Suggest your ideas where such functionality could be useful.