set up tstl factorio mod, and auto deploy stuff. A bit of mucking around with kotlin/js & dukat but it didn't go anywhere. Add a license.

modules/mod2/build.gradle.kts

@@ -157,3 +157,9 @@ tasks {
     }
   }
 }
+
+
+configure<NodeJsRootExtension> {
+  versions.dukat.version = "0.5.8-rc.4-dev.20211001"
+//  versions.dukat.version = "0.5.8-rc.4"
+}

modules/mod2/dukat-custom/builtin-types.module_typed-factorio.kt

@@ -2,18 +2,6 @@
 
 import kotlin.js.*
 import kotlinext.js.PropertyDescriptor
-import org.khronos.webgl.*
-import org.w3c.dom.*
-import org.w3c.dom.events.*
-import org.w3c.dom.parsing.*
-import org.w3c.dom.svg.*
-import org.w3c.dom.url.*
-import org.w3c.fetch.*
-import org.w3c.files.*
-import org.w3c.notifications.*
-import org.w3c.performance.*
-import org.w3c.workers.*
-import org.w3c.xhr.*
 
 typealias float = Number
 

modules/mod2/dukat-custom/classes.module_typed-factorio.kt

@@ -183,9 +183,9 @@ external interface LuaBootstrap {
     fun on_init(f: (() -> Unit)?)
     fun on_load(f: (() -> Unit)?)
     fun on_configuration_changed(f: ((param1: ConfigurationChangedData) -> Unit)?)
-    fun <E : uint> on_event(event: E, f: ((data: Any) -> Unit)?, filters: Array<Any> = definedExternally)
-    fun <E : uint> on_event(event: E, f: ((data: Any) -> Unit)?)
-    fun <E : uint> on_event(event: Array<E>, f: ((data: Any) -> Unit)?)
+    fun <E : OnTickEvent> on_event(event: E, f: ((data: E) -> Unit)?, filters: Array<Any> = definedExternally)
+    fun <E : OnTickEvent> on_event(event: E, f: ((data: E) -> Unit)?)
+    fun <E : OnTickEvent> on_event(event: Array<E>, f: ((data: Any) -> Unit)?)
     fun on_event(event: String, f: ((data: CustomInputEvent) -> Unit)?)
     fun on_nth_tick(tick: uint?, f: ((param1: NthTickEventData) -> Unit)?)
     fun on_nth_tick(tick: Array<uint>?, f: ((param1: NthTickEventData) -> Unit)?)

modules/mod2/dukat-custom/defines/events/defines.defines.events.module_typed-factorio.kt

@@ -2,6 +2,8 @@
 @file:Suppress("INTERFACE_WITH_SUPERCLASS", "OVERRIDING_FINAL_MEMBER", "RETURN_TYPE_MISMATCH_ON_OVERRIDE", "CONFLICTING_OVERLOADS")
 package defines.events
 
+import EventId
+import OnTickEvent
 import kotlin.js.*
 import org.khronos.webgl.*
 import org.w3c.dom.*
@@ -17,7 +19,7 @@ import org.w3c.workers.*
 import org.w3c.xhr.*
 import uint
 
-external var on_tick: uint /* uint & `T$93`<OnTickEvent, Unit> */
+external var on_tick: EventId<OnTickEvent> /* uint & `T$93`<OnTickEvent, Unit> */
 
 external var on_gui_click: uint /* uint & `T$93`<OnGuiClickEvent, Unit> */
 

modules/mod2/dukat-custom/eventId.kt

@@ -0,0 +1,11 @@
+
+external class TsUInt : tsstdlib.Number
+
+external class EventId<DataT: table, FilterT: table?> {
+  @JsName("_eventData")
+  val eventData: DataT
+
+  @JsName("_filter")
+  val filter: FilterT
+
+}

modules/mod2/dukat-custom/global.module_lua-types.kt

@@ -1,4 +1,5 @@
-@file:Suppress("INTERFACE_WITH_SUPERCLASS", "OVERRIDING_FINAL_MEMBER", "RETURN_TYPE_MISMATCH_ON_OVERRIDE", "CONFLICTING_OVERLOADS")
+@file:Suppress("INTERFACE_WITH_SUPERCLASS", "OVERRIDING_FINAL_MEMBER",
+    "RETURN_TYPE_MISMATCH_ON_OVERRIDE", "CONFLICTING_OVERLOADS")
 
 import kotlin.js.*
 import org.khronos.webgl.*
@@ -17,11 +18,11 @@ import tsstdlib.Record
 import tsstdlib.Iterable
 
 external interface LuaThread {
-    var __internal__: Any
+  var __internal__: Any
 }
 
 external interface LuaUserdata {
-    var __internal__: Any
+  var __internal__: Any
 }
 
 external var _VERSION: String /* "Lua 5.1" | "Lua 5.2" | "Lua 5.3" | "Lua 5.4" */
@@ -30,13 +31,15 @@ external var _G: Any
 
 external fun <V> assert(v: V): Any
 
-external fun <V, A : Array<Any>> assert(v: V, vararg args: A): dynamic /* JsTuple<Exclude<V, Boolean?>, Any> */
+external fun <V, A : Array<Any>> assert(v: V,
+    vararg args: A): dynamic /* JsTuple<Exclude<V, Boolean?>, Any> */
 
 external fun collectgarbage(opt: String /* "collect" | "stop" | "restart" */ = definedExternally)
 
 external fun collectgarbage()
 
-external fun collectgarbage(opt: String /* "setpause" | "setstepmul" | "step" */, arg: Number): dynamic /* Number | Boolean */
+external fun collectgarbage(opt: String /* "setpause" | "setstepmul" | "step" */,
+    arg: Number): dynamic /* Number | Boolean */
 
 external fun dofile(filename: String = definedExternally): Any
 
@@ -44,17 +47,25 @@ external fun error(message: String, level: Number = definedExternally): Any
 
 external fun <T> getmetatable(obj: T): LuaMetatable__1<T>?
 
-external fun <T> ipairs(t: Record<Number, T>): Iterable<dynamic /* JsTuple<Number, NonNullable<T>> */> /* Iterable<dynamic /* JsTuple<Number, NonNullable<T>> */> & LuaIterator<dynamic /* JsTuple<Number, NonNullable<T>> */, undefined> & LuaExtension<String /* "__luaIterableBrand" */> */
+external fun <T : Any> ipairs(
+    t: kotlinext.js.Record<Number, T>):
+    Iterable<dynamic /* JsTuple<Number, NonNullable<T>> */>
+/* Iterable<dynamic /* JsTuple<Number, NonNullable<T>> */> & LuaIterator<dynamic /* JsTuple<Number, NonNullable<T>> */, undefined> & LuaExtension<String /* "__luaIterableBrand" */> */
 
-external fun next(table: Any?, index: Any = definedExternally): dynamic /* JsTuple<Any, Any> | JsTuple<> */
+external fun next(table: Any?,
+    index: Any = definedExternally): dynamic /* JsTuple<Any, Any> | JsTuple<> */
 
-external fun <TKey : AnyNotNil, TValue> pairs(t: LuaTable<TKey, TValue>): Iterable<dynamic /* JsTuple<TKey, NonNullable<TValue>> */> /* Iterable<dynamic /* JsTuple<TKey, NonNullable<TValue>> */> & LuaIterator<dynamic /* JsTuple<TKey, NonNullable<TValue>> */, undefined> & LuaExtension<String /* "__luaIterableBrand" */> */
+external fun <TKey : AnyNotNil, TValue> pairs(
+    t: LuaTable<TKey, TValue>): Iterable<dynamic /* JsTuple<TKey, NonNullable<TValue>> */> /* Iterable<dynamic /* JsTuple<TKey, NonNullable<TValue>> */> & LuaIterator<dynamic /* JsTuple<TKey, NonNullable<TValue>> */, undefined> & LuaExtension<String /* "__luaIterableBrand" */> */
 
-external fun <T> pairs(t: T): Iterable<dynamic /* JsTuple<Any, NonNullable<Any>> */> /* Iterable<dynamic /* JsTuple<Any, NonNullable<Any>> */> & LuaIterator<dynamic /* JsTuple<Any, NonNullable<Any>> */, undefined> & LuaExtension<String /* "__luaIterableBrand" */> */
+external fun <T> pairs(
+    t: T): Iterable<dynamic /* JsTuple<Any, NonNullable<Any>> */> /* Iterable<dynamic /* JsTuple<Any, NonNullable<Any>> */> & LuaIterator<dynamic /* JsTuple<Any, NonNullable<Any>> */, undefined> & LuaExtension<String /* "__luaIterableBrand" */> */
 
-external fun <This, Args : Array<Any>, R> pcall(f: (self: This, args: Args) -> R, context: This, vararg args: Args): dynamic /* JsTuple<Boolean, R> | JsTuple<Boolean, String> */
+external fun <This, Args : Array<Any>, R> pcall(f: (self: This, args: Args) -> R, context: This,
+    vararg args: Args): dynamic /* JsTuple<Boolean, R> | JsTuple<Boolean, String> */
 
-external fun <A : Array<Any>, R> pcall(f: (self: Unit, args: A) -> R, vararg args: A): dynamic /* JsTuple<Boolean, R> | JsTuple<Boolean, String> */
+external fun <A : Array<Any>, R> pcall(f: (self: Unit, args: A) -> R,
+    vararg args: A): dynamic /* JsTuple<Boolean, R> | JsTuple<Boolean, String> */
 
 external fun print(vararg args: Any)
 
@@ -68,14 +79,17 @@ external fun rawlen(v: String?): Number
 
 external fun <T : Any?, K : Any> rawset(table: T, index: K, value: Any): T
 
-external fun <T> select(index: Number, vararg args: T): Array<T> /* Array<T> & LuaExtension<String /* "__luaMultiReturnBrand" */> */
+external fun <T> select(index: Number,
+    vararg args: T): Array<T> /* Array<T> & LuaExtension<String /* "__luaMultiReturnBrand" */> */
 
 external fun <T> select(index: String /* "#" */, vararg args: T): Number
 
-external fun <T : Any?, TIndex> setmetatable(table: T, metatable: LuaMetatable<T, TIndex>? = definedExternally): Any
+external fun <T : Any?, TIndex> setmetatable(table: T,
+    metatable: LuaMetatable<T, TIndex>? = definedExternally): Any
 
 external fun tonumber(e: Any, base: Number = definedExternally): Number?
 
 external fun tostring(v: Any): String
 
-external fun type(v: Any): String /* "nil" | "number" | "string" | "boolean" | "table" | "function" | "thread" | "userdata" */
+external fun type(
+    v: Any): String /* "nil" | "number" | "string" | "boolean" | "table" | "function" | "thread" | "userdata" */

modules/mod2/dukat-custom/tsstdlib/lib.es5.kt

@@ -63,7 +63,9 @@ typealias Partial<T> = Any
 
 typealias Pick<T, K> = Any
 
-typealias Record<K, T> = Any
+@Deprecated("use Kotlin Wrapper", ReplaceWith("kotlinext.js.Record<K, T>"))
+typealias Record<K, T> = kotlinext.js.Record<K, T>
+
 
 typealias Exclude<T, U> = Any
 

modules/mod2/src/main/kotlin/events.kt

@@ -0,0 +1,11 @@
+fun main() {
+
+
+script.on_event(
+  defines.events.on_tick
+) { event ->
+
+}
+
+
+}

modules/mod2/typed-factorio/README.md

@@ -0,0 +1,113 @@
+# Typed Factorio
+
+Complete and featureful typescript definitions for the Factorio modding lua api. This is intended to be used with [TypescriptToLua](https://typescripttolua.github.io/).
+
+This project aims to provide type definitions for the Factorio API that are as complete as possible. This means minimal `any`s and `unknown`s, correct nullability, and smart types where possible. The generator integrates both the Factorio JSON api docs and manually defined additions and overrides.
+
+## Installation
+
+To use in your TypescriptToLua project:
+
+1. Install this package
+
+```
+npm install typed-factorio
+
+or
+
+yarn add typed-factorio
+```
+
+2. Add to your `tsconfig.json`:
+
+```diff
+{
+  "compilerOptions": {
++    "types": [ "typed-factorio/runtime" ]
+  }
+}
+```
+
+This will add the types for the runtime stage to your entire project.
+
+Note: When types are updated, or released for a new factorio version, you will need update your package version to get the types.
+
+### Settings and data stage
+
+There are also definitions for the settings/data stage.
+
+To avoid type conflicts, the global tables for the settings/data stages have to be declared manually where you need them. These types can be imported from `typed-factorio/data/types` or `typed-factorio/settings/types`.
+
+Example:
+
+```ts
+import { Data, Mods } from "typed-factorio/data/types"
+// or 
+import { Data, Mods } from "typed-factorio/settings/types"
+
+declare const data: Data
+declare const mods: Mods
+
+data.extend([{ ... }])
+```
+
+There are currently full types for settings stage, but only basic types for the data stage.
+
+### Factorio lualib modules
+
+Currently, there are types for the following modules:
+
+- `util`
+- `mod-gui`
+
+If you have a need for types to more lualib modules, feel free to open an issue or pull request on GitHub.
+
+## Type features
+
+Typed-factorio has 100% complete types for the runtime stage. Description-only concepts and some not documented types are filled in manually.
+
+### Lua features
+
+The types include [TypescriptToLua language extensions](https://typescripttolua.github.io/docs/advanced/language-extensions/)
+and [lua-types](https://github.com/TypeScriptToLua/lua-types) (for v5.2) as dependencies.
+
+This is to use tstl features such as `LuaLengthMethod` and `LuaMultiReturn`.
+
+### `nil`
+
+The types consistently use `undefined` to represent `nil`.
+`null` is not used, because `undefined` in typescript is much more similar to `nil` in lua, and optional parameters/properties already use `undefined`.
+
+A class attribute is marked as possibly undefined only if the _read_ type is possibly `nil`. For properties where `nil` is not possible on _read_, but is possible on _write_, you can write `nil` by using `undefined!` or `myNullableValue!`, e.g. `controlBehavior.parameters = undefined!`.
+
+### Variant parameter types
+
+Variant parameter types (types with "additional fields can be specified depending on ...") are handled as discriminated unions. This gives proper type checking for individual variants.
+
+The type for a specific variant is prefixed with the either variant name or "Other" for variants without additional fields, e.g. `AmmoDamageTechnologyModifier`, `OtherTechnologyModifier`
+
+### Events
+
+`script.on_event()`, `script.get/set_filters()`, and `script.raise_event()` all have type checking on the event data/filter type, inferred from what is passed as the event name/id.
+
+You can pass a type parameter to `script.generate_event_name()`, and it will return an `EventId` that holds type info of the event data. Event functions on `script` can then use the type data when the `EventId` is passed.
+
+### Array-like types
+
+Classes that have an index operator, a length operator, and have an array-like structure, inherit from `(Readonly)Array`. These are `LuaInventory`, `LuaFluidBox`, `LuaTransportLine`. This allows you to use these classes like arrays, meaning having array methods, and `.length` translating to the lua length operator. However, this also means, like typescript arrays, they are **0-indexed, not 1-indexed**.
+
+### Table or array types
+
+For table or array types (e.g. Position), there also are types such as `PositionTable` and `PositionArray` that refer to the table or array form specifically.
+
+### LuaGuiElement
+
+`LuaGuiElement` is broken up into a discriminated union for each gui element type (See [here](https://basarat.gitbook.io/typescript/type-system/discriminated-unions) for information on discriminated unions). The type for a specific GuiElement type is `<Type>GuiElement`, e.g. `ButtonGuiElement`.
+
+Similarly, the table passed to `LuaGuiElement.add`, referred to as `GuiSpec`, is also broken up into a discriminated union for each gui element type. The type for a specific GuiSpec type is `<Type>GuiSpec`, e.g. `ListBoxGuiSpec`.
+
+This is done both to provide more accurate types, and for possible integration with [JSX](https://typescripttolua.github.io/docs/jsx/).
+
+### Examples
+
+Check out the `test` directory on GitHub for more examples on particular type features.

modules/mod2/typed-factorio/data/types.d.ts

@@ -0,0 +1,13 @@
+export interface Data {
+  readonly raw: Record<string, Record<string, any>>
+
+  /**
+   * The `data` table expects a specific format for each item in the table. Missing properties will either fall back to
+   * default values or give an error indicating what's missing. Extra properties that the game isn't looking for are
+   * simply ignored.
+   */
+  extend(prototypes: Record<string, any>[]): void
+}
+
+/** A mapping of mod names to mod version for all enabled mods. */
+export type Mods = Record<string, string>

modules/mod2/typed-factorio/generated/builtin-types.d.ts

@@ -0,0 +1,66 @@
+/** @noSelfInFile */
+
+/**
+ * A floating-point number. This is a single-precision floating point number. Whilst Lua only uses double-precision
+ * numbers, when a function takes a float, the game engine will immediately convert the double-precision number to
+ * single-precision.
+ *
+ * {@link https://lua-api.factorio.com/next/Builtin-Types.html#float View documentation}
+ */
+type float = number
+
+/**
+ * A double-precision floating-point number. This is the same data type as all Lua numbers use.
+ *
+ * {@link https://lua-api.factorio.com/next/Builtin-Types.html#double View documentation}
+ */
+type double = number
+
+/**
+ * 32-bit signed integer. Possible values are -2,147,483,648 to 2,147,483,647.
+ *
+ * {@link https://lua-api.factorio.com/next/Builtin-Types.html#int View documentation}
+ */
+type int = number
+
+/**
+ * 8-bit signed integer. Possible values are -128 to 127.
+ *
+ * {@link https://lua-api.factorio.com/next/Builtin-Types.html#int8 View documentation}
+ */
+type int8 = number
+
+/**
+ * 32-bit unsigned integer. Possible values are 0 to 4,294,967,295.
+ *
+ * {@link https://lua-api.factorio.com/next/Builtin-Types.html#uint View documentation}
+ */
+type uint = number
+
+/**
+ * 8-bit unsigned integer. Possible values are 0 to 255.
+ *
+ * {@link https://lua-api.factorio.com/next/Builtin-Types.html#uint8 View documentation}
+ */
+type uint8 = number
+
+/**
+ * 16-bit unsigned integer. Possible values are 0 to 65535.
+ *
+ * {@link https://lua-api.factorio.com/next/Builtin-Types.html#uint16 View documentation}
+ */
+type uint16 = number
+
+/**
+ * 64-bit unsigned integer. Possible values are 0 to 18,446,744,073,709,551,615.
+ *
+ * {@link https://lua-api.factorio.com/next/Builtin-Types.html#uint64 View documentation}
+ */
+type uint64 = number
+
+/**
+ * Tables are enclosed in curly brackets, like this `{}`
+ *
+ * {@link https://lua-api.factorio.com/next/Builtin-Types.html#table View documentation}
+ */
+type table = object

modules/mod2/typed-factorio/generated/global-objects.d.ts

@@ -0,0 +1,51 @@
+/** @noSelfInFile */
+
+/**
+ * This is the main object, through which most of the API is accessed. It is, however, not available inside handlers
+ * registered with {@link LuaBootstrap.on_load LuaBootstrap::on_load}.
+ *
+ * {@link https://lua-api.factorio.com/next/ View documentation}
+ */
+declare const game: LuaGameScript
+
+/**
+ * Provides an interface for registering event handlers.
+ *
+ * {@link https://lua-api.factorio.com/next/ View documentation}
+ */
+declare const script: LuaBootstrap
+
+/**
+ * Allows inter-mod communication by way of providing a repository of interfaces that is shared by all mods.
+ *
+ * {@link https://lua-api.factorio.com/next/ View documentation}
+ */
+declare const remote: LuaRemote
+
+/**
+ * Allows registering custom commands for the in-game console accessible via the grave key.
+ *
+ * {@link https://lua-api.factorio.com/next/ View documentation}
+ */
+declare const commands: LuaCommandProcessor
+
+/**
+ * Allows reading the current mod settings.
+ *
+ * {@link https://lua-api.factorio.com/next/ View documentation}
+ */
+declare const settings: LuaSettings
+
+/**
+ * Allows printing messages to the calling RCON instance if any.
+ *
+ * {@link https://lua-api.factorio.com/next/ View documentation}
+ */
+declare const rcon: LuaRCON
+
+/**
+ * Allows rendering of geometric shapes, text and sprites in the game world.
+ *
+ * {@link https://lua-api.factorio.com/next/ View documentation}
+ */
+declare const rendering: LuaRendering

modules/mod2/typed-factorio/generated/index.d.ts

@@ -0,0 +1,7 @@
+///<reference types="lua-types/5.2" />
+///<reference path="builtin-types.d.ts" />
+///<reference path="defines.d.ts" />
+///<reference path="events.d.ts" />
+///<reference path="classes.d.ts" />
+///<reference path="concepts.d.ts" />
+///<reference path="global-objects.d.ts" />

modules/mod2/typed-factorio/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "typed-factorio",
+  "version": "0.7.1",
+  "description": "Featureful typescript definitions for the the Factorio modding lua api.",
+  "keywords": [
+    "factorio",
+    "types",
+    "typescript-to-lua",
+    "tstl"
+  ],
+  "repository": "https://github.com/GlassBricks/typed-factorio",
+  "license": "MIT",
+  "files": [
+    "**/*.d.ts"
+  ],
+  "homepage": "https://github.com/GlassBricks/typed-factorio#readme",
+  "scripts": {
+    "generate": "cd ../generator && yarn run check && yarn run gen --in ../definitions/generatorSrc --out ../definitions/generated --warn-as-error",
+    "generate:dev": "cd ../generator && yarn run gen --in ../definitions/generatorSrc --out ../definitions/generated --no-format",
+    "clean": "rimraf ./generated",
+    "pretest": "yarn run generate",
+    "test": "jest",
+    "prepublishOnly": "yarn run test",
+    "download-latest-runtime-api": "ts-node ./scripts/downloadLatest.ts"
+  },
+  "dependencies": {
+    "lua-types": "^2.10.1",
+    "typescript": "~4.3.5",
+    "typescript-to-lua": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^26.0.24",
+    "@types/node": "^16.4.13",
+    "jest": "^27.0.6",
+    "prettier": "^2.3.2",
+    "ts-jest": "^27.0.4",
+    "ts-node": "^10.1.0"
+  }
+}

modules/mod2/typed-factorio/runtime/index.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="lua-types/5.2" />
+
+/// <reference path="../generated/index.d.ts" />
+
+/// <reference path="librariesAndFunctions.d.ts" />
+/// <reference path="pairs.d.ts" />
+
+// lualib
+/// <reference path="util.d.ts" />
+/// <reference path="mod-gui.d.ts" />

modules/mod2/typed-factorio/runtime/librariesAndFunctions.d.ts

@@ -0,0 +1,123 @@
+// from https://lua-api.factorio.com/latest/Libraries.html
+// last updated for 1.1.35, 1.1.36, 1.1.37
+
+/** @noSelfInFile */
+
+/** @noSelf */
+interface SerpentOptions {
+  /** Indentation; triggers long multi-line output. */
+  indent: string
+  /** Provide stringified value in a comment (up to maxlevel of depth). */
+  comment: boolean | number
+  /** Sort keys. */
+  sortkeys: boolean | ((this: void, keys: any[], table: any) => void)
+  /** Force sparse encoding (no nil filling based on #t). */
+  sparse: boolean
+  /** Remove spaces. */
+  compact: boolean
+  /** Raise fatal error on non-serializable values. */
+  fatal: boolean
+  /** Disable bytecode serialization for easy comparison. */
+  nocode: boolean
+  /** Disable checking numbers against undefined and huge values. */
+  nohuge: boolean
+  /** Specify max level up to which to expand nested tables. */
+  maxlevel: number
+  /** Specify max number of elements in a table. */
+  maxnum: number
+  /** Specify max length for all table elements. */
+  maxlength: number
+  /**
+   * Use __tostring metamethod when serializing tables (v0.29); set to false to disable and serialize the table as is,
+   * even when __tostring is present.
+   */
+  metatostring: boolean
+  /**
+   * Specify format for numeric values as shortest possible round-trippable double (v0.30). Use "%.16g" for better
+   * readability and "%.17g" (the default value) to preserve floating point precision.
+   */
+  numformat: string
+  /** Allows to specify a list of values to ignore (as keys). */
+  valignore: string[]
+  /** Allows to specify the list of keys to be serialized. Any keys not in this list are not included in final output (as keys). */
+  keyallow: string[]
+  /** Allows to specity the list of keys to ignore in serialization. */
+  keyignore: string[]
+  /** Allows to specify a list of value types to ignore (as keys). */
+  valtypeignore: string[]
+  /** Provide custom output for tables. */
+  custom(opts: {
+    /** The name of the current element with '=' or an empty string in case of array index, */
+    tag: string
+    /** An opening table bracket { and associated indentation and newline (if any), */
+    head: string
+    /** Table elements concatenated into a string using commas and indentation/newlines (if any), */
+    body: string
+    /** A closing table bracket } and associated indentation and newline (if any), and */
+    tail: string
+    /** The current level. */
+    level: number
+  }): string
+  /** Name; triggers full serialization with self-ref section. */
+  name: string
+
+  refcomment: boolean | number
+  tablecomment: boolean | number
+}
+
+/**
+ * Factorio provides the {@link https://github.com/pkulchenko/serpent serpent library} as a global variable `serpent` for
+ * all mods to use. It allows for easy debugging of tables, because serpent makes it trivial to print them, for example
+ * by using `serpent.block()`. However, serpent cannot pretty-print LuaObjects such as LuaEntity. The serpent library
+ * was modified to improve determinism, e.g. comments are turned off by default to avoid returning table addresses.
+ * Furthermore, two options were added: `refcomment` (true/false/maxlevel) and `tablecomment` (true/false/maxlevel),
+ * which allow to separately control the self-reference and table value output of the `comment` option.
+ */
+declare namespace serpent {
+  /** Full serialization; sets name, compact and sparse options; */
+  function dump(tbl: unknown, options?: Partial<SerpentOptions>): string
+
+  /** Single line pretty printing, no self-ref section; sets sortkeys and comment options; */
+  function line(tbl: unknown, options?: Partial<SerpentOptions>): string
+
+  /** Multi-line indented pretty printing, no self-ref section; sets indent, sortkeys, and comment options. */
+  function block(tbl: unknown, options?: Partial<SerpentOptions>): string
+
+  /**
+   * For loading serialized fragments, serpent also provides `load` function that adds safety checks and reports an
+   * error if there is any executable code in the fragment.
+   */
+  function load<T>(str: string, options?: { safe?: boolean }): LuaMultiReturn<[true, T] | [false, string]>
+}
+
+/**
+ * This function allows to log {@link LocalisedString} to the Factorio
+ * {@link https://wiki.factorio.com/Log_file log file}. This, in combination with serpent, makes debugging in the data
+ * stage easier, because it allows to simply inspect entire prototype tables. For example, this allows to see all
+ * properties of the sulfur item prototype: `log(serpent.block(data.raw["item"]["sulfur"]))`
+ */
+declare function log(ls: LocalisedString): void
+
+/**
+ * This function allows printing {@link LocalisedString}s to stdout without polluting the logfile. This is primarily
+ * useful for communicating with external tools that launch Factorio as a child process.
+ */
+declare function localised_print(ls: LocalisedString): void
+
+/**
+ * Factorio provides the function `table_size()` as a simple way to find the size of tables with non-continuous keys,
+ * because the standard `#` does not work correctly for these. The function is a C++-side implementation of the
+ * following Lua code, thus it is faster than using this code in Lua:
+ *
+ *     local function size(t)
+ *       local count = 0
+ *        for k,v in pairs(t) do
+ *         count = count + 1
+ *       end
+ *       return count
+ *     end
+ *
+ * Note that `table_size()` does not work correctly for {@link LuaCustomTable}s, their size has to be determined with
+ * {@link LuaCustomTable.length LuaCustomTable::operator #} instead.
+ */
+declare function table_size(tbl: table): number

modules/mod2/typed-factorio/runtime/mod-gui.d.ts

@@ -0,0 +1,11 @@
+/** @noSelfInFile */
+
+/** @noResolution */
+declare module "mod-gui" {
+  const button_style: string
+  const frame_style: string
+
+  function get_button_flow(player: LuaPlayer): FrameGuiElement
+
+  function get_frame_flow(player: LuaPlayer): FlowGuiElement
+}

modules/mod2/typed-factorio/runtime/pairs.d.ts

@@ -0,0 +1,13 @@
+/** @noSelfInFile */
+
+/** Iterating with `pairs` will only iterate the array part of a {@link LuaCustomTable}. */
+declare function pairs<V>(table: LuaCustomTable<number | string, V>): LuaIterable<LuaMultiReturn<[number, V]>>
+
+declare function pairs<K extends keyof any, V>(table: LuaCustomTable<K, V>): LuaIterable<LuaMultiReturn<[K, V]>>
+
+/**
+ * {@link LuaCustomTable} cannot be iterated with `ipairs`. Use `pairs` instead.
+ *
+ * @deprecated
+ */
+declare function ipairs(table: LuaCustomTable<any, any>): never

modules/mod2/typed-factorio/runtime/util.d.ts

@@ -0,0 +1,120 @@
+// "util" is declared only as a module, even though it also modifies global variables
+// This is both because of limitations in `declare module`, and that modules are much friendlier to tooling.
+
+/** @noSelfInFile */
+
+/** @noResolution */
+declare module "util" {
+  namespace table {
+    function deepcopy<T>(table: T): T
+
+    function compare<T>(tb1: T, tb2: T): boolean
+  }
+
+  function copy<T>(table: T): T
+
+  function distance(position1: Position, position2: Position): number
+
+  function positiontostr(position: Position): string
+
+  function formattime(ticks: number): string
+
+  /** Supports 'rrggbb', 'rgb', 'rrggbbaa', 'rgba', 'ww', 'w' */
+  function color(hex: string): ColorTable
+
+  function premul_color(color: Color): ColorTable
+
+  function mix_color(c1: Color, c2: Color): ColorArray
+
+  function multiply_color(c1: Color, n: number): ColorArray
+
+  function moveposition(
+    position: Position,
+    direction: defines.direction.north | defines.direction.east | defines.direction.south | defines.direction.west,
+    distance: number
+  ): Position
+  function moveposition(
+    position: Position,
+    direction: defines.direction, //todo: cardinal only
+    distance: number
+  ): Position | undefined
+
+  function oppositedirection(direction: defines.direction): defines.direction
+
+  /** Creates a new array where each element in `stripes` is duplicated `count` times */
+  function multiplystripes<T>(count: number, stripes: T[]): T[]
+
+  /** Gets tile position by pixel */
+  function by_pixel(x: number, y: number): Position
+
+  /** Gets tile position by pixel, hr */
+  function by_pixel_hr(x: number, y: number): Position
+
+  // omitted: foreach_sprite_definition
+
+  function add_shift(a: PositionArray | undefined, b: PositionArray): PositionArray
+  function add_shift(a: PositionArray, b: PositionArray | undefined): PositionArray
+  function add_shift(a: PositionArray | undefined, b: PositionArray | undefined): PositionArray | undefined
+
+  // omitted: add_shift_offset
+
+  function mul_shift(shift: PositionArray, scale: number | undefined): PositionArray
+  function mul_shift(shift: PositionArray | undefined, scale: number | undefined): PositionArray | undefined
+
+  function format_number(amount: number, append_suffix?: boolean): string
+
+  function increment(t: number[], index: number, v?: number): void
+
+  // omitted: conditional_return
+
+  /**
+   * Recursively merges and/or deep-copies tables. Entries in later tables override entries in earlier ones, unless both
+   * entries are themselves tables, in which case they are recursively merged. Non-merged tables are deep-copied, so
+   * that the result is brand new.
+   */
+  function merge<T extends object>(tables: T[]): T
+
+  function insert_safe(entity: LuaEntity | undefined, item_dict: Record<string, number> | undefined): void
+
+  function remove_safe(entity: LuaEntity | undefined, item_dict: Record<string, number> | undefined): void
+
+  function split_whitespace(string: string): string[]
+
+  // omitted: split, string_starts_with. already TS functions for that
+
+  // omitted: online_players. use game.connected_players
+
+  function clamp(x: number, lower: number, upper: number): number
+
+  // omitted: get_walkable_tile
+
+  // omitted: combine_icons
+  // omitted: technology_icons. Create an issue if you really want to see these
+
+  function parse_energy(energy: string): number
+
+  function product_amount(
+    product: {
+      probability: number
+    } & (
+      | {
+          amount: number
+        }
+      | {
+          amount_min: number
+          amount_max: number
+        }
+    )
+  ): number
+
+  function empty_sprite(): object
+
+  // omitted: draw_as_glow
+  // omitted: remove_tile_references
+
+  function remove_from_list<T>(list: T[], value: T): boolean
+
+  function list_to_map<T extends keyof any>(list: T[]): Record<T, true>
+  function list_to_map<T>(list: T[]): LuaTable<T, true>
+  function list_to_map<T>(list: T): LuaTable<T[keyof T], true>
+}

modules/mod2/typed-factorio/settings/types.d.ts

@@ -0,0 +1,120 @@
+// Based off of https://wiki.factorio.com/Tutorial:Mod_settings
+
+export type SettingType = "bool-setting" | "int-setting" | "double-setting" | "string-setting"
+
+export interface BaseSettingDefinition {
+  type: SettingType
+  /**
+   * The name of the settings prototype should be unique to avoid mod conflicts since the mod settings are global across
+   * all mods. Because of that it is recommended to prefix mod settings with your mod name,
+   */
+  name: string
+  localized_name?: LocalisedString
+  localized_description?: LocalisedString
+
+  /**
+   * The order property can be used to change how the mod settings are ordered in the settings gui. Mod settings are sorted
+   *
+   * - First by mod
+   * - Then by the setting "order" string
+   * - Then finally by the setting name.
+   */
+  order?: string
+  /**
+   * The hidden property can be used to hide mod settings from GUIs, so that they cannot be seen or changed by players.
+   * However, other mods can still access hidden settings. {@link https://forums.factorio.com/83316}
+   */
+  hidden?: boolean
+  /**
+   * There are the overall kinds of settings:
+   *
+   * - **startup**: This kind of setting is available in the prototype stage, and can not be changed runtime. They have to
+   *   be set to the same values for all players on a server.
+   * - **runtime-global**: This kind of setting is global to an entire save game and can be changed runtime. On servers,
+   *   only admins can change these settings.
+   * - **runtime-per-user**: This kind of setting is only available runtime in the control.lua stage and each player has
+   *   their own instance of this setting. When a player joins a server their local setting of "keep mod settings per
+   *   save" determines if the local settings they have set are synced to the loaded save or if the save's settings are used.
+   *
+   * This "setting_type" also determines in which tab the setting is showed in the mod settings menu.
+   */
+
+  setting_type: "startup" | "runtime-global" | "runtime-per-user"
+}
+/** A true/false checkbox */
+export interface BoolSettingDefinition extends BaseSettingDefinition {
+  type: "bool-setting"
+  /** Defines the default value of the setting, in this case whether the checkbox is checked or not. */
+  default_value: boolean
+  /**
+   * Only loaded if `hidden = true`. This forces the setting to be of this value. This can be useful for mod
+   * compatibility. {@link https://forums.factorio.com/viewtopic.php?p=531322#p531322}
+   */
+  forced_value?: boolean
+}
+/** A signed 64 bit integer textfield (or selection dropdown) */
+export interface IntSettingDefinition extends BaseSettingDefinition {
+  type: "int-setting"
+  /** Defines the default value of the setting. */
+  default_value: number
+  /** Defines the lowest possible number. */
+  minimum_value?: number
+  /** Defines the highest possible number. */
+  maximum_value?: number
+  /**
+   * Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a
+   * textfield. If only one allowed value is given, the settings is forced to be of that value.
+   */
+  allowed_values?: number[]
+}
+/** A double precision floating point textfield (or selection dropdown) */
+export interface DoubleSettingDefinition extends BaseSettingDefinition {
+  type: "double-setting"
+  /** Defines the default value of the setting. */
+  default_value: number
+  /** Defines the lowest possible number. */
+  minimum_value?: number
+  /** Defines the highest possible number. */
+  maximum_value?: number
+  /**
+   * Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a
+   * textfield. If only one allowed value is given, the settings is forced to be of that value.
+   */
+  allowed_values?: number[]
+}
+/** A string textfield (or selection dropdown) */
+export interface StringSettingDefinition extends BaseSettingDefinition {
+  type: "string-setting"
+  /** Defines the default value of the setting. */
+  default_value: string
+  /** Defines whether it's possible for the user to set the textfield to empty and apply the setting. */
+  allow_blank?: boolean
+  /** Whether values that are input by the user should have whitespace removed from both ends of the string. */
+  auto_trim?: boolean
+  /**
+   * Makes it possible to force the player to choose between the defined strings, creates a dropdown instead of a
+   * textfield. The strings in the dropdown can be localized (translated) and can have a tooltip, see below. If only one
+   * allowed value is given, the settings is forced to be of that value.
+   */
+  allowed_values?: string[]
+}
+/** Setting definitions. See {@link https://wiki.factorio.com/Tutorial:Mod_settings} for more info. */
+export type SettingDefinition =
+  | BoolSettingDefinition
+  | IntSettingDefinition
+  | DoubleSettingDefinition
+  | StringSettingDefinition
+
+export interface Data {
+  readonly raw: {
+    [T in SettingDefinition["type"]]: Record<string, Extract<SettingDefinition, { type: T }>>
+  }
+  /**
+   * The `data` table expects a specific format for each item in the table. Missing properties will either fall back to
+   * default values or give an error indicating what's missing. Extra properties that the game isn't looking for are
+   * simply ignored.
+   */
+  extend(prototypes: SettingDefinition[]): void
+}
+/** A mapping of mod names to mod version for all enabled mods. */
+export type Mods = Record<string, string>