.eslintignore

-**/Jquery.js
 **/mousetrap.js
+**/pako.js
 **/sugarCubeConfig.js
 **/format.js
 **/displayVariables.js
@@ -7,3 +7,8 @@
 **/optionsMacro.js
 temp.**
 **.temp
+**/001-lib
+/build/**/*
+/devNotes/legacy files/**/*
+bin/*
+/FCHost/**/*

.eslintrc.json

@@ -3,6 +3,7 @@
 	"env": {
 		"browser": true,
 		"es6": true,
+		"es2022": true,
 		"jquery": true
 	},
 	"extends": ["eslint:recommended"],
@@ -25,12 +26,23 @@
 		"postdisplay": true
 	},
 	"parserOptions": {
-		"ecmaVersion": 2019,
+		"ecmaVersion": 2022,
 		"sourceType": "script",
 		"ecmaFeatures": {
 			"impliedStrict": true
 		}
 	},
+	"overrides": [
+		{
+			// overrides for helper scripts that are written
+			// using imports and/or exports
+			"files": ["gulpfile.js", "devTools/scripts/**/*.js"],
+			"parserOptions": {
+				"sourceType": "module",
+				"ecmaVersion": 2022
+			}
+		}
+	],
 	"settings": {
 		"jsdoc": {
 			"mode": "typescript"
@@ -109,6 +121,9 @@
 			}
 		],
 		"one-var": ["warn", "never"],
+		"keyword-spacing": "warn",
+		"no-template-curly-in-string": "error",
+		"operator-linebreak": ["warn", "after", { "overrides": { "?": "before", ":": "before" }}],
 		"jsdoc/check-alignment": 1,
 		"jsdoc/check-examples": 0, // interferes with SugarCube examples
 		"jsdoc/check-indentation": 0,
@@ -122,12 +137,28 @@
 		"jsdoc/newline-after-description": 0,
 		"jsdoc/no-types": 0,
 		"jsdoc/no-undefined-types": 0,
-		"jsdoc/require-jsdoc": 0,
-		"jsdoc/require-param": 0,
+		"jsdoc/require-jsdoc": [
+			"warn",
+			{
+				"enableFixer": false,
+				"require": {
+					"ArrowFunctionExpression": false,
+					"ClassDeclaration": false,
+					"ClassExpression": false,
+					"FunctionDeclaration": true,
+					"FunctionExpression": true,
+					"MethodDefinition": false
+				},
+				"exemptEmptyFunctions": true,
+				"checkGetters": false,
+				"checkSetters": false
+			}
+		],
+		"jsdoc/require-param": ["warn"],
 		"jsdoc/require-param-description": 0,
 		"jsdoc/require-param-name": 1,
 		"jsdoc/require-param-type": 1,
-		"jsdoc/require-returns": 0,
+		"jsdoc/require-returns": ["off"],
 		"jsdoc/require-returns-check": 1,
 		"jsdoc/require-returns-description": 0,
 		"jsdoc/require-returns-type": 1,

.gitignore

@@ -33,16 +33,19 @@ ENV/
 .ropeproject
 
 # Start.tw
-src/config/start.tw
+src/002-config/start.tw
 
 # eslint
 node_modules
 package-lock.json
 yarn.lock
+pnpm-lock.yaml
 
 # Visual Studio Code
 .vscode/settings.json
 .vscode/tasks.json
+# .vscode/bookmarks.json is created by the amazing https://marketplace.visualstudio.com/items?itemName=alefragnani.Bookmarks VSCode extension
+.vscode/bookmarks.json
 *.code-workspace
 
 # WebStorm
@@ -63,10 +66,26 @@ fc-pregmod
 bin/*
 *.outline
 *.todo
+/TODO.*
 TODO.txt
 temp.*
 *.temp
 src/002-config/fc-version.js.commitHash.js
+devTools/scripts/.package.json.diff
+/settings.json
+.eslintcache
+/sanityCheck.log
+/.tsbuildinfo
 
 # macOS devices
 *.icloud
+
+# legacy
+devNotes/legacy files/*
+/.vs
+
+# mod development
+/mods/dev/
+
+# cSpell
+.cspellcache

.gitlab-ci.yml

@@ -18,27 +18,32 @@ variables:
   # precompiled / assets
   # the URLs are the same as inside the game, change both if updating
   WEBGL_NAME: "WebGL art assets"
-  WEBGL_URL: "https://mega.nz/folder/rtAzEYTS#5a5KO_rqq_BB8eqtOuhEow"
+  WEBGL_URL: "https://mega.nz/folder/CgRiQaxS#Cjok57jXZwQt-jP7zkRh2Q"
   RENDER_NAME: "Rendered imagepack (outdated)"
   RENDER_URL: "https://mega.nz/file/upoAlBaZ#EbZ5wCixxZxBhMN_ireJTXt0SIPOywO2JW9XzTIPhe0"
 
 build:
   stage: build
-  image: debian:latest
+  image: ggcr.io/pregmodfan/fc-pregmod/build
+  cache:
+    paths:
+      - node_modules/
   rules:
     # official release
     - if: $CI_COMMIT_TAG =~ /\A\d+\.\d+\.\d+/
     # latest
     - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+  before_script:
+    - npm update --no-audit --no-fund --omit=dev
   script:
-    - ./compile.sh --ci --minify
+    - npx gulp html --minify --release --ci
   artifacts:
     paths:
       - bin/FC_pregmod.html
 
 upload:
   stage: upload
-  image: gitgud.io:5050/pregmodfan/fc-pregmod:megacmd
+  image: ggcr.io/pregmodfan/fc-pregmod:megacmd
   extends: .official-releases
   script:
     - mega-login $MEGA_MAIL $MEGA_PWD

.gitlab/issue_templates/bug_report.md

@@ -4,7 +4,7 @@
 <!--- If you're describing a bug, tell us what should happen -->
 
 ## Current Behavior
-<!-- If describing a bug, tell us what happens instead of the expected behavior. Provide a Screenshots if possible. -->
+<!-- If describing a bug, tell us what happened instead of the expected behavior. Provide screenshots of the problem if possible. -->
 
 ## Steps to Reproduce
 <!-- Provide an unambiguous sequence of steps to reproduce the bug. -->

.gitlab/merge_request_templates/default.md

+<!-- If you have any questions about anything don't hesitate to ask in this merge request or by creating a new issue -->
+#### Description and notes
+<!-- Describe what you have done and why. -->
+
+<details><summary>Merge Checklist</summary>
+
+<!---
+Check all that apply by replacing the space inside the square brackets with an x ([x] for example)
+This is to help us streamline the merging process
+It is not a list of requirements
+-->
+- [ ] I have read [CONTRIBUTING.md](https://gitgud.io/pregmodfan/fc-pregmod/-/blob/pregmod-master/CONTRIBUTING.md)
+  - and
+    - my code editor has
+      - [ ] ESLint support enabled
+      - [ ] TypeScript support enabled
+      - [ ] some form of spell checker
+        - We suggest using a spell checker compatible with cSpell if possible
+    - [ ] my changes compile successfully and seem to work properly
+    - [ ] I am using the simple compiler (`simple-compiler.[bat or sh]`)
+    - [ ] I am using the normal compiler (`compile.[bat or sh]`)
+    - [ ] this is my first merge request
+    - [ ] the changes in this merge request comply with the [coding style defined in CONTRIBUTING.md](https://gitgud.io/pregmodfan/fc-pregmod/-/blob/pregmod-master/CONTRIBUTING.md#code-style)
+
+</details>
+
+<details><summary>Changes made</summary>
+
+- Some change
+- Another change
+
+</details>
+
+#### Things left to do
+<!-- A todo list of things that you think still need done before merging -->
+- [ ] code review (this is done by one or more people other than you)
+- [ ] final tests
+- [ ] let Pregmodder know that this is ready for merging

.vscode/extensions.json

+{
+    "recommendations": [
+        "streetsidesoftware.code-spell-checker",
+        "naumovs.color-highlight",
+        "usernamehw.errorlens",
+        "dbaeumer.vscode-eslint",
+        "waderyan.gitblame",
+        "donjayamanne.git-extension-pack",
+        "eamodio.gitlens",
+        "visualstudioexptteam.vscodeintellicode",
+        "davidanson.vscode-markdownlint",
+        "christian-kohler.path-intellisense",
+        "esbenp.prettier-vscode",
+        "gruntfuggly.todo-tree",
+        "wayou.vscode-todo-highlight",
+        "cyrusfirheir.twee3-language-tools"
+    ]
+}
\ No newline at end of file

.vscode/settings.template.jsonc

+{
+    // This is our suggested VSCode settings. To use them as is just copy this file and name the copy settings.json
+    "[javascript]": {
+        "editor.defaultFormatter": "dbaeumer.vscode-eslint",
+        "editor.formatOnPaste": true,
+        "editor.formatOnSave": true,
+        "editor.formatOnType": true
+    },
+    "[json]": {
+        "editor.defaultFormatter": "vscode.json-language-features",
+        "editor.formatOnPaste": true,
+        "editor.formatOnSave": true,
+        "editor.formatOnType": true
+    },
+    "cSpell.enabledFileTypes": {
+        "*": true
+    },
+    "editor.inlineSuggest.enabled": true,
+    "editor.rulers": [
+        {
+            "column": 80,
+            "color": "#1f8300"
+        },
+        {
+            "column": 120,
+            "color": "#ff7700"
+        }
+    ],
+    "editor.semanticHighlighting.enabled": true,
+    "eslint.format.enable": true,
+    "eslint.probe": [
+        "javascript",
+        "javascriptreact",
+        "typescript",
+        "typescriptreact",
+        "html",
+        "vue",
+        "markdown",
+        "twee3-sugarcube-2"
+    ],
+    "files.associations": {
+        "*.tw": "twee3-sugarcube-2"
+    },
+    "todo-tree.regex.regex": "(//|#|--|<!--|;|/\\*|^|^[ \\t]*(-|\\d+.))\\s*($TAGS)",
+    "twee3LanguageTools.storyformat.current": "sugarcube-2"
+}
\ No newline at end of file

CONTRIBUTING.md

@@ -2,186 +2,256 @@
 
 First off, thanks for taking the time to contribute!
 
-If there is anything you don't understand feel free to ask. Many of the more advanced tools are also not required for
-fixing small typos or simple bugs.
+If there is anything you don't understand please ask us about it. The advanced tooling is not required for
+fixing small typos or simple bugs, but it is suggested.
 
 ## Environment
 
 ### Requirements
 
-To effectively work on the project the following tools are required:
+To effectively work on the project the following tools are needed:
 
-* `Git`
-* `Node.js` or another npm client
-* an IDE capable of working with JavaScript, TypeScript and CSS. `VS Code` is one option.
-* Java Runtime Environment, minimum JRE8
+* [Git](https://git-scm.com)
+* [Node.js](https://nodejs.org/en/) or another npm client
+* a code editor/IDE
+  * [VSCode](https://code.visualstudio.com/) is a popular option and is what we recommend if you don't already have a preference
+
+These tools are not required, but are suggested and will make working on FC easier.
 
 ### Setting everything up
 
-0. Clone the project from GitGud.io ([Detailed Git setup and work cycle](devNotes/gitSetup.md))
-1. Open a terminal (Linux) / cmd window (Windows) and navigate to the `fc-pregmod` root directory.
-2. Run `npm install`
-3. Open the directory in your preferred IDE
-4. Configure your IDE to use ESLint and the type checking capabilities of the TypeScript compiler.
+1. Clone the project from GitGud.io ([Detailed Git setup and work cycle](devNotes/gitSetup.md))
+2. Navigate to the `fc-pregmod` root directory.
+   * Windows: Run `Windows Powershell` or `Command Prompt` and execute `cd C:\path\to\project\fc-pregmod`
+   * Mac/Linux: Open a terminal and execute `cd /path/to/project/fc-pregmod/`
+3. Run `setup.bat` (Windows) or `setup.sh` (Mac/Linux) in your terminal
+4. Follow the install steps until you get to the `Welcome to FC development!...` menu and then select `Exit`
+5. Open the directory in your preferred editor/IDE
 
-## Compiling
+**Make sure you have ESLint, TypeScript, and spell checking (preferably with cSpell compatiblity) support installed and enabled (if avaliable) in your preferred editor/IDE to catch formatting, type def, and spelling errors**
 
-While you can compile it like usual (`compile.bat`/`compile.sh`/`make`), there is also a `Gulp script` that creates
-source files for easier debugging. Other than that there are no differences between compiling for development or
-compiling for playing the game.
+<details><summary>Recommended editor/IDE plugins/extensions</summary>
 
-# Code
+The list below is for VSCode. If you are not using VSCode but want some of these extensions functionality, then do some research. Many of these extensions exist or have alternatives in most common editors/IDEs.
 
-## Code style
+* [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
+  * Catches formatting problems and lets you know when your code doesn't conform to our standards
+* TypeScript/TSC
+  * Built into VSCode. Catches discrepancies between your code and the existing TypeScript type defs
+* [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)
+  * Catches most spelling issues
+* [Error Lens](https://marketplace.visualstudio.com/items?itemName=usernamehw.errorlens)
+  * Highlights lines that ESLint, TSC, or Code Spell Checker have marked as having problems
+* [Git Extension Pack](https://marketplace.visualstudio.com/items?itemName=donjayamanne.git-extension-pack)
+  * Adds a few tools that make working with git easier
+* [IntelliCode](https://marketplace.visualstudio.com/items?itemName=VisualStudioExptTeam.vscodeintellicode)
+  * Will make your day easier by suggesting functions and properties for autocompletion
+  * Will also show you documentation for those suggested functions and properties
+* [TODO Highlight](https://marketplace.visualstudio.com/items?itemName=wayou.vscode-todo-highlight)
+  * Makes TODO comments stand out better
+* [Todo Tree](https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree)
+  * Adds a tab to the left sidebar that lists all TODO comments in the current project
+
+</details>
 
-Generally the code style is based on our `.eslintrc.json`. If your IDE has an auto format feature it can often read the
-rules from `.eslintrc.json`.
+If you are using VSCode we also suggest copying `.vscode/settings.template.jsonc` to `.vscode/settings.json` to use our recommended VSCode settings.
 
-### Important Rules
+### Compiling
+
+Use either the simple or advanced compiler. See the `Compile the game yourself` section in the [readme](README.md) for more information. We suggest using the advanced compiler when possible.
+
+## Code style
 
-* use spaces after commas
-* do not omit semicolons
-* no empty blocks
-* don't pad blocks with blank lines
-* prefer strict equality/inequality
-* etc.
+The coding style is based on our [`.eslintrc.json`](/.eslintrc.json) file. If your editor/IDE has ESLint support it will let you know when your coding style doesn't conform to our standards.
+  * Most editors/IDEs don't have native ESLint support and will need you to install an ESLint plugin/extension.
 
 ### Documentation
 
-It's a good idea to provide meaningful documentation for new functions and classes where possible. We follow
-Typescript's [JSDoc](https://jsdoc.app) type dialect for the most part (and we provide a Typescript configuration and
-auxiliary type definition files if you'd like to use it yourself – it's pretty nifty). Don't worry too much about
-specific type syntax if you can't make TS work or don't understand it, someone else will probably fix it for you as long
-as you've made the intent clear in some form of JSDoc.
+It's a good idea to provide meaningful documentation for new functions and classes where possible.
+We follow [JSDoc's](https://jsdoc.app) type dialect for the most part with some TypeScript definitions thrown in.
+We provide a [TypeScript configuration](/tsconfig.json) (for TSC support).
+More complex type definitions are usually stored in our [TypeScript type definition files](https://gitgud.io/pregmodfan/fc-pregmod/-/tree/pregmod-master/devTools/types?ref_type=heads).
+Don't worry too much about specific type syntax if you can't make TS work or don't understand it,
+someone else will probably fix it for you as long as you've made the intent clear in some combination of Comments, JSDoc, and/or TypeScript type def.
+
+Here are some links that are may be helpful in regards to TypeScript, jsdoc, and documentation.
+  * Getting started with JSDoc: https://jsdoc.app/about-getting-started.html
+  * JSDoc's website: https://jsdoc.app/
+  * The `human.d.ts` file where the bulk of our commonly used type defs are stored: https://gitgud.io/pregmodfan/fc-pregmod/-/blob/pregmod-master/devTools/types/FC/human.d.ts
 
 ### Naming conventions
 
 * JavaScript variable and function names should be `camelCase`.
 
 ```js
+// good
+let fooBar;
+
 // bad
 let foobar;
 let Foobar;
 let FooBar;
+```
 
+* JavaScript classes and namespaces should be `PascalCase`.
+
+```js
 // good
-let fooBar;
+class Foo {}
+App.Foo.bar();
+
+// bad
+class foo {}
+class FOO {}
+App.foo.bar();
 ```
 
-* Enum members should be `ALLCAPS`.
+* TypeScript type defs should be `PascalCase`.
 
 ```ts
+// good
+export type Foo = "bar" | "car";
+export interface Foo {
+  bar: boolean,
+}
+
 // bad
-enum Foo {
-  bar = 'bar',
-  Baz = 'baz',
+export type foo = "bar" | "car";
+export interface FOO {
+  bar: boolean,
 }
+```
 
+* Enum members should be `ALLCAPS`.
+
+```js
 // good
 enum Foo {
   BAR = 'bar',
   BAZ = 'baz',
 }
+
+// bad
+enum Foo {
+  bar = 'bar',
+  Baz = 'baz',
+}
 ```
 
 This also applies to JavaScript objects that are used as enums.
 
 ```js
-// bad
-/** @enum {string} */
-const foo = {
-  bar: 'bar',
-  Baz: 'baz',
-}
-
 // good
 /** @enum {string} */
-const foo = {
+const Foo = {
   BAR: 'bar',
   BAZ: 'baz',
 }
 
-
-// better
+// bad
 /** @enum {string} */
-const Foo = {
+const foo = {
   BAR: 'bar',
   BAZ: 'baz',
 }
-```
-
-* JavaScript classes and namespaces should be `PascalCase`.
 
-```js
-// bad
-class foo {}
-class FOO {}
-App.foo.bar();
-
-// good
-class Foo {}
-App.Foo.bar();
+// worse
+/** @enum {string} */
+const foo = {
+  bar: 'bar',
+  Baz: 'baz',
+}
 ```
 
 * CSS classes are `kebob-case`.
 
 ```css
+/* good */
+.foo-bar {}
+
 /* bad */
 .fooBar {}
 .FOO-BAR {}
-
-/* good */
-.foo-bar {}
 ```
 
-New code should generally get organized into the `App` namespace. See `js/002-config/fc-init-js.js` for a rough outline.
+### JavaScript Features
+
+Use modern JavaScript features when possible. We are currently targeting ECMAScript 2022, and aren't trying to support Internet Explorer or anything stupid like that (it isn't 2010 anymore). For example, use [`let`/`const` rather than `var`](https://www.freecodecamp.org/news/var-let-and-const-whats-the-difference/), prefer [`Arrow function expressions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions) to inline long-form functions, use [`nullish coalescing`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing) and [`optional chaining`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining), etc.
+
+### Code quality
 
-## JavaScript Features
+Contributions should generally not add any new ESLint, TSC, or spelling errors. You can check for errors by running `sanityCheck.bat` (Windows)/`sanityCheck.sh` (Mac/Linux) and/or by using a code editor that supports ESLint, TSC, and cSpell.
+  * With the default settings running `sanityCheck.bat` (Windows) or `sanityCheck.sh` (Mac/Linux) will (mostly) show you just the errors that were caused by your changes.
+  * If you are not using the advanced tooling then use `legacySanityCheck.bat` or `legacySanityCheck.sh` instead.
 
-* Avoid using very new JavaScript features
-  * Generally, we're currently targeting ECMAScript 2018, though we use a few widely-implemented ECMAScript 2019
-    features, like `globalThis`.
-* Conversely, do use modern features, it's not 2010 anymore and we don't try to support Internet Explorer or anything
-  stupid like that.
-  * use `let`/`const` rather than `var`
-  * prefer fat arrow functions to inline long-form functions
-  * etc.
+## Project Structure
 
-## Code quality
+### Source files
 
-There are three main tools used to ensure good code quality, `ESLint`, `TypeScript Compiler (tsc)` and a custom sanity
-check.
+* `src/` is the main directory for source code. It also contains the embedded art files. Since it is inside an `eval()` statement debugging and minification is more complicated than for `js/`.
+* `js/` is loaded before SugarCube and therefore outside SugarCube's eval which `src/` is contained in. This means accessing SugarCube features (like `SugarCube.Engine`) is more complicated however it other than `src/` it can be minified and is easier to debug. Currently, contains mainly static data, however new code not relying on SC2 should be sorted in here too.
+* `css/` contains all CSS files. The internal structure is explained [here](css/css.md).
+* `themes/` contains [custom themes](themes/themes.md) which are built separately.
 
-`ESLint` and `tsc` can be setup in most IDEs aimed at web development to show errors while editing the file.
+### Developer Files
 
-Contributions should generally not add any new sanity check errors, and it's especially important to check this if
-you're making changes to .tw files.
-Use `./compile.sh --dry --sanity` or the short hand `./compile.sh -d -s` on linux or mac.
-On Windows run `compile_debug+sanityCheck.bat`.
-It searches for common spelling errors and syntax errors in the twine files. Don't worry about preexisting
-errors, it's not totally clean as is and there are a few false positives.
+* `devNotes/` contains various wiki files and other potentially interesting files.
+  * Note that many of these files have outdated info. Your best bet is to double check the actual code before utilizing the info found in these files
+* `devTools/` contains various scripts and executables needed for working with the project or compiling.
+  * TypeScript typing files are stored here as well in the `devTools/types/` directory.
+* `submodules/` contains Git submodules
+  * currently only a custom version of SugarCube 2
 
-# Further Reading
+### Art files
 
-## Wiki Files
+* `artTools/`contains files for creating and updating [vector art](artTools/README.md)
+* `resources/` contains various [art related files](resources/ReadmeBeforeAddingArt.md)
 
-* Writing Guides
-  * [Twine (Twine is being phased out of the project however the concepts are still relevant)](devNotes/scene-guide.txt)
+### External Programs
+
+* `docker/` contains Docker files from which the docker containers for GitLabs CI are created
+* `FCHost/` contains the sources for [FCHost](FCHost/README.md)
+* `saveTools/` contains tools for [editing save files](saveTools/README.md)
+
+## Further Reading
+
+### Notes and things that it is useful to know
+
+* I highly recommend reading https://javascript.info/comments
+* Whenever you add, remove or change the type of a property that is stored when saving the game you need to create a patch for your changes. Instructions for this can be found at the top of https://gitgud.io/pregmodfan/fc-pregmod/-/blob/pregmod-master/src/data/patches/patch.js
+* If you have any suggestions, changes, or additions to this document that would have been helpful to you you please create a new issue or create a merge request with your changes.
+
+### New to JavaScript and/or web development?
+
+Here are some links to tutorials and reference material that should help you on your journey.
+  * https://www.w3schools.com/Js/
+  * https://www.geeksforgeeks.org/javascript/
+  * https://www.freecodecamp.org/news/learn-javascript-for-beginners/
+  * https://developer.mozilla.org/en-US/docs/Web#web_technology_references
+
+### Wiki Files
+
+* Event Writing Guides
+  * [Twine<sup>1</sup>](devNotes/sceneGuide.md)
   * [JavaScript](devNotes/jsEventCreationGuide.md)
 * [Exception handling](devNotes/exceptions.md)
-* [Sanity check](devNotes/sanityCheck.md)
+* [Sanity check<sup>2</sup>](devNotes/sanityCheck.md)
 * [Slave List](devNotes/slaveListing.md)
 * [Pronouns](devNotes/Pronouns.md)
 * External function documentation
-  * [Eyes](devNotes/eye functions.md)
-  * [Limbs](devNotes/limb functions.md)
-  * [Standalone functions](devNotes/standaloneFunctions.md)
-  * [Some potentially useful JS functions](devNotes/usefulJSFunctionDocumentation.txt)
-  * [Content embedding chart](devNotes/contentEmbeddingChart.png) (for more details refer to https://gitgud.io/pregmodfan/fc-pregmod/-/merge_requests/7453#note_118616)
+  * [Eyes](devNotes/eyeFunctions.md)
+  * [Limbs](devNotes/limbFunctions.md)
+  * [Some potentially useful JS functions](devNotes/usefulJSFunctionDocumentation.md)
+  * [Content embedding chart](devNotes/contentEmbeddingChart.png) (for more details refer to [this issue](https://gitgud.io/pregmodfan/fc-pregmod/-/merge_requests/7453#note_118616))
+
+<sup>1. Twine is being phased out of the project and should not be used in new code, but the basic concepts found here still apply.</sup>
+
+<sup>2. Only applies to the legacy sanity checks.</sup>
 
-## Useful issues
+### Useful issues
 
 * [Setting up VS Code](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/2448)
 * [Classes in Game State](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/696)
 * [Self executing functions](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/2325)
 * [Sort a map](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/2642)
+* [How to create a Merge Request (MR)](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/3903)

FCHost.bat

+@ECHO off
+:: Free Cities FCHost Launcher - Windows
+
+:: run dependencyCheck.bat
+CALL .\devTools\scripts\dependencyCheck.bat
+SET CODE=%ERRORLEVEL%
+
+IF %CODE% EQU 69 (
+	:: if exit code is 69, then we don't have all the dependencies we need
+	ECHO.
+	ECHO Dependencies not met.
+    ECHO.
+	EXIT /b 0
+) ELSE IF %CODE% EQU 0 (
+	:: if exit code is 0, run FCHostInstallAndRun.js
+	CALL node devTools\scripts\FCHostInstallAndRun.js
+	EXIT /b 0
+) ELSE (
+	:: if exit code is not 0, print error message
+	ECHO.
+	ECHO dependencyCheck.bat exited with code: %CODE%
+	ECHO Dependency check failed unexpectedly.
+    ECHO.
+    EXIT /b 0
+)

FCHost.sh

+#!/bin/bash
+
+# Free Cities FCHost Launcher - Unix
+
+# run dependencyCheck.sh
+./devTools/scripts/dependencyCheck.sh
+exitCode=$?
+# exit code is now stored in $exitCode
+
+# if exit code is 69, then we don't have all the dependencies we need
+if [[ $exitCode -eq 69 ]]; then
+    echo "Dependencies not met."
+    echo ""
+   exit 0
+# if exit code is not 0, print error message
+elif [[ $exitCode -ne 0 ]]; then
+	echo "dependencyCheck.sh exited with code: $exitCode"
+    echo "Dependency check failed unexpectedly."
+    echo ""
+    exit 0
+# if exit code is 0, run FCHostInstallAndRun.js
+else
+    node devTools/scripts/FCHostInstallAndRun.js
+fi

FCHost/.gitignore

 CMakeCache.txt
-CMakeFiles
-Debug
-Release
+CMakeFiles/
+Debug/
+Release/
+fchost/Release_*
+Release.file
 x64
 *.sln
 *.vcxproj
 *.vcxproj.filters
 *.vcxproj.user
-libcef_dll_wrapper
+libcef_dll_wrapper/
+libs/
 .vs
 cmake_install.cmake
 *.VC.db
-GPUCache
+GPUCache
\ No newline at end of file
+PreCompiledFCHost.zip
+Makefile
+.ninja_deps
+.ninja_log
+build.ninja

FCHost/Building_FCHost.txt

-BUILD REQUIREMENTS
-
-The below requirements must be met to build this project.
-
- - Chromium Embedded Framework (CEF) 76.1.5 or newer.  The windows build is
-   currently configured to operate with the X64 binary distribution of CEF.
-
- - CMake version 2.8.12.1 or newer.
-
- - Linux/MacOS requirements:
-   I haven't tested these platforms, and there is platform-specific code missing.
-   Shouldn't be too hard to add, check the CEF distribution and treat FCHost
-   as a derivative of tests/cefsimple.
-   
- - Have the environment variable CEF_ROOT set to the root of your CEF distribution.
- - Have the CMake binary folder added to your path e.g. for Windows C:\Program Files\CMake\bin.
-
- - Windows requirements:
-   Visual Studio 2019 (the community edition will work fine) or newer with the "Desktop development with C++" workload installed.
-
-BUILD STEPS
-
-If you are running Windows and meet the above requirements then within the root of FCHost/, 
-execute cmake_vs2019.bat which will generate FCHost.sln in the same location.
-Now open FCHost.sln in Visual Studio 2019 
-and build from there via tool bar -> Build -> Build Solution or Ctrl + Shift + B.
-
-The resulting binary and supporting files will be in
-FCHost/fchost/Debug, or FCHost/fchost/Release depending on the configuration
-selected in Visual Studio via the drop down found under the Build and Debug tool bar headers.  
-
-You should be able to zip up the contents of the 
-Release folder and distribute them to another machine or user if desired.
-Due to space and privacy concerns it is suggested that you remove *.html and fchost.ilk prior to distribution. 
-
-If you are not running Windows or you need something else special, please
-familiarize yourself with CMake and see the detailed information in CMakeLists.txt.
\ No newline at end of file

FCHost/CMakeLists.txt

@@ -105,45 +105,73 @@ set_property(GLOBAL PROPERTY OS_FOLDERS ON)
 
 
 #
-# CEF_ROOT setup.
-# This variable must be set to locate the binary distribution.
-#
+# CEF configuration.
+#
+
+# Specify the CEF distribution version.
+# Visit https://cef-builds.spotifycdn.com/index.html for the list of
+# supported platforms and versions.
+set(CEF_VERSION "126.2.11+gb281f7a+chromium-126.0.6478.127")
+
+# Determine the platform.
+if("${CMAKE_SYSTEM_NAME}" STREQUAL "Darwin")
+  if("${PROJECT_ARCH}" STREQUAL "arm64")
+    set(CEF_PLATFORM "macosarm64")
+  elseif("${PROJECT_ARCH}" STREQUAL "x86_64")
+    set(CEF_PLATFORM "macosx64")
+  elseif("${CMAKE_HOST_SYSTEM_PROCESSOR}" STREQUAL "arm64")
+    set(PROJECT_ARCH "arm64")
+    set(CEF_PLATFORM "macosarm64")
+  else()
+    set(PROJECT_ARCH "x86_64")
+    set(CEF_PLATFORM "macosx64")
+  endif()
+elseif("${CMAKE_SYSTEM_NAME}" STREQUAL "Linux")
+  if("${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "arm")
+    set(CEF_PLATFORM "linuxarm")
+  elseif("${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "arm64")
+    set(CEF_PLATFORM "linuxarm64")
+  elseif(CMAKE_SIZEOF_VOID_P MATCHES 8)
+    set(CEF_PLATFORM "linux64")
+  else()
+    message(FATAL_ERROR "Linux x86 32-bit builds are discontinued.")
+  endif()
+elseif("${CMAKE_SYSTEM_NAME}" STREQUAL "Windows")
+  if("${CMAKE_CXX_COMPILER_ARCHITECTURE_ID}" STREQUAL "ARM64")
+    set(CEF_PLATFORM "windowsarm64")
+  elseif(CMAKE_SIZEOF_VOID_P MATCHES 8)
+    set(CEF_PLATFORM "windows64")
+  else()
+    set(CEF_PLATFORM "windows32")
+  endif()
+endif()
 
-# The binary distribution is in a separate directory from your
-# project. Locate the binary distribution using the CEF_ROOT
-# environment variable.
-#
-# Set the CEF_ROOT environment variable before executing CMake. For example:
-#    > set CEF_ROOT=c:\path\to\cef_binary_3.2704.xxxx.gyyyyyyy_windows32
-#
-# set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
+# Add this project's cmake/ directory to the module path.
+set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 
+# Download and extract the CEF binary distribution (executes DownloadCEF.cmake).
+include(DownloadCEF)
+DownloadCEF("${CEF_PLATFORM}" "${CEF_VERSION}" "${CMAKE_SOURCE_DIR}/libs")
 
-#
-# Load the CEF configuration.
-#
+# Add the CEF binary distribution's cmake/ directory to the module path.
+set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CEF_ROOT}/cmake")
 
-# try to find system installation
-find_package(CEF QUIET)
+# Load the CEF configuration (executes FindCEF.cmake).
+find_package(CEF REQUIRED)
 
-if(NOT DEFINED _CEF_ROOT_EXPLICIT) # if that fails, try the standard way
-  include("${CMAKE_CURRENT_LIST_DIR}/cmake/FindCEF.cmake")
-endif()
 
 #
 # Define CEF-based targets.
 #
 
 # Include the libcef_dll_wrapper target.
-# Comes from the libcef_dll/CMakeLists.txt file in the binary distribution
-# directory.
 add_subdirectory(${CEF_LIBCEF_DLL_WRAPPER_PATH} libcef_dll_wrapper)
 
+# Allow includes relative to the current source directory.
+include_directories(${CMAKE_CURRENT_SOURCE_DIR})
+
 # Include application targets.
-# Comes from the <target>/CMakeLists.txt file in the current directory.
-if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/fchost")
-  add_subdirectory(fchost)
-endif()
+add_subdirectory(fchost)
 
 # Display configuration settings.
 PRINT_CEF_CONFIG()

FCHost/HowToBuild.md

+# How to Build
+
+## BUILD REQUIREMENTS
+
+The below requirements must be met to build this project.
+
+- CMake version 2.8.12.1 or newer
+  - Ensure the CMake binary folder is added to your path (e.g. for Windows `C:\Program Files\CMake\bin`)
+- Chromium Embedded Framework (CEF) 126.1 or newer
+  - Running CMake will automatically download this so there is no need to configure it yourself
+
+### Windows
+
+Visual Studio 2019 (the community edition will work fine) or newer with the "Desktop development with C++" workload installed.
+
+### Linux
+
+Ensure you have a C++ compiler installed. On Debian/Ubuntu this can be installed with:
+
+```bash
+sudo apt install build-essential
+```
+
+## BUILD STEPS
+
+### Windows
+
+Assuming that Visual Studio 2019/2022 is being used, run the following command:
+
+```bash
+# For Visual Studio 2019
+# Alternatively run `cmake_vs2019.bat`
+cmake -G "Visual Studio 16" .
+
+# For Visual Studio 2022
+# Alternatively run `cmake_vs2022.bat`
+cmake -G "Visual Studio 17" .
+```
+
+Open the generated `fchost.sln` file in Visual Studio. Then build the project by either:
+
+- Selecting **Build > Build Solution** on the menu bar
+- Pressing **Ctrl + Shift + B**
+
+### Linux
+
+Run the following commands:
+
+```bash
+cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release .
+make -j4
+```
+
+### Output
+
+The resulting binary and supporting files will be in `FCHost/fchost/Debug` or `FCHost/fchost/Release` depending on the configuration selected in Visual Studio via the drop down found under the Build and Debug tool bar headers.
+
+You should be able to zip up the contents of the Release folder and distribute them to another machine or user if desired. Due to space and privacy concerns it is suggested that you remove `*.html` and `fchost.ilk` files (if present) prior to distribution.

FCHost/documentation_FCHost.md → FCHost/README.md

+<!-- cSpell:ignore fchost, Shokusku's -->
+
 # FCHost
 
 FCHost is an alternative HTML renderer for playing Pregmod based on Chromium. It has multiple advantages compared to normal browsers:
 
-* No browser cache limits, allowing arbitrarily large save files.
-* Saves are stored in an easily accessible way on disk, allowing for easy manual editing.
-* No lost saves due to accidentally cleared cookies.
-* Can be noticeable faster.
+- No browser cache limits, allowing arbitrarily large save files.
+- Saves are stored in an easily accessible way on disk, allowing for easy manual editing.
+- No lost saves due to accidentally cleared cookies.
+- Can be noticeable faster.
+
+A Windows build is available for [download](https://mega.nz/file/kY5GmLRa#jwwgshNuKz0yAQDDeSs-jbPOOGX4Ap1ha_EKlWp-9-M).
 
-A precompiled version for Windows is available [here](https://mega.nz/folder/vzxgwKwL#L4V4JEk1YfWcvC7EG76TMg) 
+If you are developing FC using the advanced tooling then you can run `FCHost.bat` (Windows) or `FCHost.sh` (Mac/Linux) to download and setup FCHost automatically.
 
 ## Initial setup
 
 ### HTML files
 
-Place FC_pregmod.html next to the FCHost executable. On Windows, this is `fchost.exe`
+Place `FC_pregmod.html` next to the FCHost executable. This is usually `fchost.exe`, but it may be a file named `fchost` on Mac/Linux.
 
 ### Art resources
 
@@ -23,9 +27,9 @@ the art resources have to be placed in a `resources` directory next to the HTML
 Elohiem's interactive WebGL:
 
 - fchost.exe
-- resources/ 
-  - webgl 
-    
+- resources/
+  - webgl
+
 Shokusku's rendered image pack
 
 - fchost.exe
@@ -37,17 +41,19 @@ If making changes while the game is open make sure to refresh or restart FCHost
 
 ## Keybinds
 
-| Action    | Key Kombination  |
+| Action    | Key Combination  |
 | --------- | ---------------- |
 | Zoom In   | Ctrl + Plus      |
 | Zoom Out  | Ctrl + Minus     |
 | Dev Tools | Ctrl + Shift + J |
 
-
 ## Save file locations
 
-On Windows saves are stored in `%User%\Documents\FreeCities_Pregmod\FCHostPersistentStorage\`
+| Platform | Location                                                       |
+| -------- | -------------------------------------------------------------- |
+| Windows  | `%User%\Documents\FreeCities_Pregmod\FCHostPersistentStorage\` |
+| Linux    | `~/.local/share/FreeCities_Pregmod/FCHostPersistentStorage/`   |
 
 ## Building FCHost
 
-If you want to build FCHost yourself please refer to [FCHost/Building_FCHost.txt](FCHost/Building_FCHost.txt).
+If you want to build FCHost yourself please refer to [FCHost/HowToBuild.md](FCHost/HowToBuild.md).

FCHost/cmake/DownloadCEF.cmake

+# Copyright (c) 2016 The Chromium Embedded Framework Authors. All rights
+# reserved. Use of this source code is governed by a BSD-style license that
+# can be found in the LICENSE file.
+
+# Download the CEF binary distribution for |platform| and |version| to
+# |download_dir|. The |CEF_ROOT| variable will be set in global scope pointing
+# to the extracted location.
+# Visit https://cef-builds.spotifycdn.com/index.html for the list of
+# supported platforms and versions.
+
+function(DownloadCEF platform version download_dir)
+  # Specify the binary distribution type and download directory.
+  set(CEF_DISTRIBUTION "cef_binary_${version}_${platform}")
+  set(CEF_DOWNLOAD_DIR "${download_dir}")
+
+  # The location where we expect the extracted binary distribution.
+  set(CEF_ROOT "${CEF_DOWNLOAD_DIR}/${CEF_DISTRIBUTION}" CACHE INTERNAL "CEF_ROOT")
+
+  # Download and/or extract the binary distribution if necessary.
+  if(NOT IS_DIRECTORY "${CEF_ROOT}")
+    set(CEF_DOWNLOAD_FILENAME "${CEF_DISTRIBUTION}.tar.bz2")
+    set(CEF_DOWNLOAD_PATH "${CEF_DOWNLOAD_DIR}/${CEF_DOWNLOAD_FILENAME}")
+    if(NOT EXISTS "${CEF_DOWNLOAD_PATH}")
+      set(CEF_DOWNLOAD_URL "https://cef-builds.spotifycdn.com/${CEF_DOWNLOAD_FILENAME}")
+      string(REPLACE "+" "%2B" CEF_DOWNLOAD_URL_ESCAPED ${CEF_DOWNLOAD_URL})
+
+      # Download the SHA1 hash for the binary distribution.
+      message(STATUS "Downloading ${CEF_DOWNLOAD_PATH}.sha1 from ${CEF_DOWNLOAD_URL_ESCAPED}...")
+      file(DOWNLOAD "${CEF_DOWNLOAD_URL_ESCAPED}.sha1" "${CEF_DOWNLOAD_PATH}.sha1")
+      file(READ "${CEF_DOWNLOAD_PATH}.sha1" CEF_SHA1)
+
+      # Download the binary distribution and verify the hash.
+      message(STATUS "Downloading ${CEF_DOWNLOAD_PATH}...")
+      file(
+        DOWNLOAD "${CEF_DOWNLOAD_URL_ESCAPED}" "${CEF_DOWNLOAD_PATH}"
+        EXPECTED_HASH SHA1=${CEF_SHA1}
+        SHOW_PROGRESS
+        )
+    endif()
+
+    # Extract the binary distribution.
+    message(STATUS "Extracting ${CEF_DOWNLOAD_PATH}...")
+    execute_process(
+      COMMAND ${CMAKE_COMMAND} -E tar xzf "${CEF_DOWNLOAD_DIR}/${CEF_DOWNLOAD_FILENAME}"
+      WORKING_DIRECTORY ${CEF_DOWNLOAD_DIR}
+      )
+  endif()
+endfunction()
\ No newline at end of file

FCHost/cmake/FindCEF.cmake

-# Copyright (c) 2016 The Chromium Embedded Framework Authors. All rights
-# reserved. Use of this source code is governed by a BSD-style license that
-# can be found in the LICENSE file.
-
-#
-# This file is the CEF CMake configuration entry point and should be loaded
-# using `find_package(CEF REQUIRED)`. See the top-level CMakeLists.txt file
-# included with the CEF binary distribution for usage information.
-#
-
-# Find the CEF binary distribution root directory.
-set(_CEF_ROOT "")
-if(CEF_ROOT AND IS_DIRECTORY "${CEF_ROOT}")
-  set(_CEF_ROOT "${CEF_ROOT}")
-  set(_CEF_ROOT_EXPLICIT 1)
-else()
-  set(_ENV_CEF_ROOT "")
-  if(DEFINED ENV{CEF_ROOT})
-    file(TO_CMAKE_PATH "$ENV{CEF_ROOT}" _ENV_CEF_ROOT)
-  endif()
-  if(_ENV_CEF_ROOT AND IS_DIRECTORY "${_ENV_CEF_ROOT}")
-    set(_CEF_ROOT "${_ENV_CEF_ROOT}")
-    set(_CEF_ROOT_EXPLICIT 1)
-  endif()
-  unset(_ENV_CEF_ROOT)
-endif()
-
-if(NOT DEFINED _CEF_ROOT_EXPLICIT)
-  message(FATAL_ERROR "Must specify a CEF_ROOT value via CMake or environment variable.")
-endif()
-
-if(NOT IS_DIRECTORY "${_CEF_ROOT}/cmake")
-  message(FATAL_ERROR "No CMake bootstrap found for CEF binary distribution at: ${CEF_ROOT}.")
-endif()
-
-# Execute additional cmake files from the CEF binary distribution.
-set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${_CEF_ROOT}/cmake")
-include("cef_variables")
-include("cef_macros")

FCHost/cmake_vs2022.bat

+@ECHO OFF
+REM Quickly rebuild 64-bit VS2022 solution/project files from the CMake files.
+
+cmake -G "Visual Studio 17" -A x64
+pause
\ No newline at end of file