typed-factorio 1.17.0 → 2.0.0

package/README.md

@@ -2,23 +2,20 @@
 
 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 lua API that are as complete as possible. This means no `any`s or `unknown`s, correct nullability, and lots of smart type features. The generator integrates both the Factorio JSON api docs and manually defined additions and overrides.
+This project aims to provide type definitions for the Factorio lua API that are as complete as possible.
+The generator uses both the Factorio api docs JSON and manually defined additions.
 
 ## Installation
 
-To use in your TypescriptToLua project:
+To use in your [TypescriptToLua](https://typescripttolua.github.io/) project:
 
-1. Install this package
+1. Install this package: `npm install typed-factorio`
+    - Note: When types are updated for a new factorio version, you will need to the npm package to get the latest types.
 
-```
-npm install typed-factorio
-
-or
-
-yarn add typed-factorio
-```
+2. Add the types for the [stages](https://lua-api.factorio.com/1.1.89/index.html) used to `tsconfig.json > compilerOptions > types`.
+   The available stages are `"typed-factorio/settings"`, `"typed-factorio/prototype"`, and `"typed-factorio/runtime"`.
 
-2. Add to your `tsconfig.json`:
+Example:
 
 ```diff
 {
@@ -28,84 +25,137 @@ yarn add typed-factorio
 }
 ```
 
-This will add the types for the runtime stage to your entire project.
+The stages selected will control the global variables defined.
+It is possible to include multiple stages, but there are some caveats. See [Using multiple stages in the same project](#using-multiple-stages-in-the-same-project) for more info.
 
-Note: When types are updated, or released for a new factorio version, you will need update your package version to get the types.
+## Usage
 
-### Settings and data stage
+Global variables will be defined for the stage(s) selected.
 
-There are also definitions for the settings/data stage.
+### Types
 
-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`.
+No matter which stage(s) are selected, _type_ definitions for all stages are available in the modules `"factorio:settings"`, `"factorio:prototype"`, and `"factorio:runtime"`: 
+```ts
+import { BoolSettingDefinition } from "factorio:settings"
+import { ItemPrototype } from "factorio:prototype"
+import { LuaEntity } from "factorio:runtime"
+```
 
-Example:
+### Data.extend
+In the settings and prototype stages, the `data` global variable is available. 
 
+For [performance reasons](https://github.com/microsoft/TypeScript/wiki/Performance#preferring-base-types-over-unions), `data.extend()` is only loosely typed.
+To get full type checking, use specific types when adding prototypes:
 ```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
+// example: adding an ammo category and item prototype
+import { AmmoCategory, ItemPrototype } from "factorio:prototype"
+
+data.extend([
+   {
+     type: "ammo-category",
+     name: "foo",
+   } satisfies AmmoCategory,
+   { 
+     type: "item",
+     name: "bar",
+     // other fields...
+   } satisfies ItemPrototype,
+])
 
-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:
+There are types for the following [Factorio lualib modules](https://github.com/wube/factorio-data/tree/master/core/lualib):
 
 - `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.
+These can be imported as modules:
+
+```ts
+import * as util from "util"
+
+const foo = util.copy(bar)
+```
+
+If you wish to see types for more lualib modules, feel free to open an issue or pull request.
 
 ### The `global` table
 
-The `global` table is a lua table which can have any shape, so it is not defined in typed-factorio. Instead, you can either:
+The `global` table (in the runtime stage) can have any shape, so it is not defined here. Instead, you can:
 
 - add `declare const global: <Your type>` in a `.d.ts` file included in your project, to apply it project-wide, or
-- add `declare const global: {...}` to each module/file where needed. This way, you can define only attributes that each module/file specifically uses.
+- add `declare const global: {...}` to each file where needed. This way, you can define only properties that each file specifically uses.
+
+## Using multiple stages in the same project
+
+Every Factorio loading stage declares different global variables.
+To add types for multiple Factorio stages, you have a few options, with different pros and cons:
+
+1. Add multiple stages to the "types" field, e.g. `"types": ["typed-factorio/prototype", "typed-factorio/runtime"]`. This will define global variables for _all_ stages selected. With this option, take care that you only use global variables available in the stages the code is run.
+2. Add _only_ the runtime stage to your types, then manually declare other global variables in other stages, only in files that use them. There are types in `"factorio:common"` to allow this:
+   ```ts
+   // -- For the prototype stage --
+   import { PrototypeData, ActiveMods } from "factorio:common"
+   declare const data: PrtotopyeData
+   declare const mods: ActiveMods
+   // The `settings` global variable is already declared in the runtime stage.
+   // However, in the prototype stage _only_ startup settings are available.
+   ```
+   ```ts
+   // -- For the settings stage --
+   import { SettingsData, ActiveMods } from "factorio:common"
+   declare const settings: SettingsData
+   declare const mods: ActiveMods
+   ```
+3. Use a separate `tsconfig.json` for each stage. In each `tsconfig.json`, include only files in that stage in the `"include"` field, e.g. `include: ["src/control.ts"]` for the runtime stage. However, this means you need to run `tstl` separately for each stage, and files shared by multiple stages will be compiled multiple times.
+
+### Additional notes
+
+You can also include just `"typed-factorio"` in your `types` field. This will include only global variables available to _all_ stages.
 
 ## Type features
 
-### `nil`
+Here is some info on type features that you may find useful:
 
-`nil` is equivalent to `undefined`.
+### `nil`
 
-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 possible on _write_, you can write `nil` by using `undefined!` or `myNullableValue!`, e.g. `controlBehavior.parameters = undefined!`.
+The `nil` type is equivalent to `undefined`.
+A class attribute is marked as possibly nil if the _read_ type is possibly `nil`. For properties where `nil` is possible on _write_, but not _read_, you can use `undefined!` or `myNullableValue!`, e.g. `controlBehavior.parameters = undefined!`.
 
 ### Parameter Variants
 
-Parameter tables with variants (having "additional attributes can be specified depending on type ...") are defined as a union of all variants. The type for a specific variant is prefixed with the variant name, or "Other" types variants without extra properties (e.g. `AmmoDamageTechnologyModifier`, `OtherTechnologyModifier`).
+Parameter tables with variants (having "additional attributes can be specified depending on type ...") are defined as a union of all variants. The type for a specific variant is prefixed with the variant name (e.g. `AmmoDamageTechnologyModifier`), or prefixed with "Other" for variants without extra properties (e.g. `OtherTechnologyModifier`).
 
 ### Events
 
-Event IDs (`defines.events`) carry information about their event type and filters, which is used by the various methods on `script`.
-You can pass an event data type parameter to `script.generate_event_name<T>()`, and it will return a `CustomEventId` that holds type info of the event data.
+Event IDs (`defines.events`) hold type info for their corresponding event type and filters, which is used by various methods in `script`.
+
+You can pass an event data type parameter to `script.generate_event_name<T>()`, and it will return a `CustomEventId` that includes type info.
 
 ### Array-like classes
 
-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**.
+Classes that have an index operator, a length operator, and have an array-like structure subclass from `(Readonly)Array`. These are `LuaInventory`, `LuaFluidBox`, `LuaTransportLine`.
+This allows you to use these classes like arrays, e.g. having array methods and `.length` translating to the lua length operator. However, this means like typescript arrays, they are **0-indexed, not 1-indexed**.
 
 ### Read and write variants
 
 For concepts that can take a table or array form, the main type (e.g. `MapPosition`) defines the table form, and an `Array` suffix (e.g. `MapPositionArray`) defines the array form.
-Concepts in a "read" position will always be in the table form, and concepts in a "write" position may be either in table or array form (e.g. `MapPosition | MapPositionArray`). This is including within other concepts (e.g. in `ScriptArea`, via the `ScriptAreaWrite` type).
+Concepts in a "read" position are in table form, and concepts in a "write" position may be either in table or array form (e.g. `MapPosition | MapPositionArray`).
+Concepts that include table-or-array concepts may have an additional `Write` variant (e.g. `ScriptArea`, `ScriptAreaWrite`).
 
 ### Classes with subclasses
 
-Some classes have attributes that are documented to only work for particular subclasses. For these classes, e.g. `LuaEntity`, there are specific types that you can _optionally_ use:
+Some classes have attributes that only work for particular subclasses. For these classes (e.g. `LuaEntity`) there are specific types that you can _optionally_ use:
 
-- a "Base" type, e.g. `BaseEntity`, which only contains members usable by all subclasses
-- individual subclass types, e.g. `CraftingMachineEntity`, which extends the base type with members specific to that subclass.
+- A "Base" type (e.g. `BaseEntity`) which contains only members usable by all subclasses
+- Multiple subclass types, e.g. `CraftingMachineEntity`, which extends the base type with members specific to that subclass.
 
-The simple class name, e.g. `LuaEntity`, contains attributes for _all_ subclasses.
+The original class name (e.g. `LuaEntity`) contains attributes for _all_ subclasses.
 
 For stricter types, use the `Base` type generally, and the specific subclass type when needed.
-You can also create your own type-narrowing functions, like so:
+You can also create your own type-narrowing functions:
 
 ```ts
 function isCraftingMachineEntity(entity: BaseEntity): entity is CraftingMachineEntity {
@@ -115,16 +165,8 @@ function isCraftingMachineEntity(entity: BaseEntity): entity is CraftingMachineE
 
 ### LuaGuiElement
 
-`LuaGuiElement` is broken up into a [discriminated union](https://basarat.gitbook.io/typescript/type-system/discriminated-unions), with a separate type for each gui element type. Individual gui element types can be referred to by `<Type>GuiElement`, e.g. `ButtonGuiElement`.
+`LuaGuiElement` is broken up into a [discriminated union](https://basarat.gitbook.io/typescript/type-system/discriminated-unions), for each gui element type. Individual gui element types can be referred to by `<Type>GuiElement`, e.g. `ButtonGuiElement`.
 
-Similarly, the table passed to `LuaGuiElement.add`, referred to as `GuiSpec`, is also broken up into a discriminated union. The type for a specific GuiSpec is `<Type>GuiSpec`, e.g. `ListBoxGuiSpec`. `LuaGuiElement.add` will return the appropriate gui element type corresponding to the GuiSpec type received.
+Similarly, `GuiSpec` (the table passed to `LuaGuiElement.add`), is also a discriminated union. The type for a specific GuiSpec is `<Type>GuiSpec`, e.g. `ListBoxGuiSpec`. `LuaGuiElement.add` will return the appropriate gui element type corresponding to the GuiSpec type passed in.
 
 This is done both to provide more accurate types, and for possible integration with [JSX](https://typescripttolua.github.io/docs/jsx/).
-
-### Strict index types
-
-This is a recommended **opt-in** feature. To opt in, add `"typed-factorio/strict-index-types"` to `compilerOptions > types` in your tsconfig.json (in addition to `"typed-factorio/runtime"`).
-
-Some `uint` types which represent unique indices, e.g. player_index, entity_number, can be "branded" numbers, e.g. `PlayerIndex` and `EntityNumber`. If opted-in, these index-types will be still assignable to `number`, but a plain `number` is not directly assignable to them. This helps ensure their correct use.
-You can use these types as keys in an index signature, e.g. `{ [index: PlayerIndex]: "foo" }`.
-You can cast "plain" numbers to these types, e.g. `1 as PlayerIndex`, do this with caution.

package/common/data-global.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Provides access to read/edit prototypes.
+ *
+ * This is only available in the settings or prototype stage.
+ * Only prototypes for the current stage can be accessed.
+ */
+declare const data: import("factorio:common").DataGlobal
+
+/**
+ * A table of (mod name -> mod version) for all currently active mods.
+ *
+ * This global is only available in the settings or prototype stage.
+ * In the runtime stage, use `script.active_mods`.
+ */
+declare const mods: import("factorio:common").ActiveMods

package/common/serpent.d.ts

@@ -0,0 +1,93 @@
+// from https://lua-api.factorio.com/latest/Libraries.html
+// last updated for 1.1.35, 1.1.36, 1.1.37
+
+/** @noSelfInFile */
+
+/**
+ * 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 {
+  /** @noSelf */
+  interface Options {
+    /** 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
+  }
+
+  /** Full serialization; sets name, compact and sparse options; */
+  function dump(tbl: unknown, options?: Partial<Options>): string
+
+  /** Single line pretty printing, no self-ref section; sets sortkeys and comment options; */
+  function line(tbl: unknown, options?: Partial<Options>): string
+
+  /** Multi-line indented pretty printing, no self-ref section; sets indent, sortkeys, and comment options. */
+  function block(tbl: unknown, options?: Partial<Options>): 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]>
+}

package/common/settings-global.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Provides access to the current mod settings.
+ * This is available in the prototype and runtime stages.
+ *
+ * In the prototype stage, _only_ the `startup` settings are available.
+ * In the runtime stage, this is extended with the full {@link LuaSettings} interface.
+ */
+declare const settings: import("factorio:common").SettingsGlobal

package/common/types.d.ts

@@ -0,0 +1,74 @@
+/** @noResolution */
+declare module "factorio:common" {
+  import { ModSetting } from "factorio:runtime"
+  import { PrototypeMap as PrototypePrototypeMap } from "factorio:prototype"
+  import { PrototypeMap as SettingsPrototypeMap } from "factorio:settings"
+  /**
+   * A type map of type name -> prototype type.
+   *
+   * Including the settings/prototype stage in your tsconfig extends this interface.
+   */
+  export interface GlobalPrototypeMap {}
+
+  /** Represents any valid prototype. */
+  export interface AnyPrototype<M = GlobalPrototypeMap> {
+    readonly type: keyof M
+    readonly name: string
+  }
+
+  export interface DataGlobal<M = GlobalPrototypeMap> {
+    /**
+     * A table of the already added prototypes.
+     * Indexed by prototype type, then by prototype name.
+     */
+    readonly raw: {
+      readonly [T in keyof M]: {
+        readonly [name in string]?: M[T]
+      }
+    }
+
+    /**
+     * Add additional prototypes.
+     */
+    extend<P extends AnyPrototype<M>>(prototypes: readonly P[]): void
+  }
+
+  export interface SettingsGlobal {
+    readonly startup: {
+      readonly [name: string]: ModSetting
+    }
+  }
+
+  /** A version string, in the form "major.minor.patch". */
+  export type VersionString = `${bigint}.${bigint}.${bigint}`
+
+  export interface ActiveMods {
+    readonly [modName: string]: VersionString | undefined
+  }
+
+  /**
+   * Represents a `data` global variable for the prototype stage.
+   *
+   * If you did _not_ add `"typed-factorio/prototype"` to your tsconfig, you can manually declare this global like so:
+   * ```ts
+   * import { PrototypeData } from "factorio:prototype"
+   * declare const data: PrototypeData
+   *
+   * data.extend(...)
+   * ```
+   */
+  export type PrototypeData = DataGlobal<PrototypePrototypeMap>
+
+  /**
+   * Represents a `data` global variable for the settings stage.
+   *
+   * If you did _not_ add `"typed-factorio/settings"` to your tsconfig, you can manually declare this global like so:
+   * ```ts
+   * import { SettingsData } from "factorio:settings"
+   * declare const data: SettingsData
+   *
+   * data.extend(...)
+   * ```
+   */
+  export type SettingsData = DataGlobal<SettingsPrototypeMap>
+}

package/index.d.ts

@@ -0,0 +1,26 @@
+/*
+This file includes _only_ types for all factorio stages; it declares the factorio:common, factorio:prototype,
+and factorio:runtime modules.
+*/
+/// <reference types="lua-types/5.2" />
+
+/// <reference path="common/types.d.ts" />
+
+/// <reference path="settings/types.d.ts" />
+
+/// <reference path="prototype/generated/prototypes.d.ts" />
+/// <reference path="prototype/generated/types.d.ts" />
+
+/// <reference path="runtime/generated/builtin-types.d.ts" />
+/// <reference path="runtime/generated/events.d.ts" />
+/// <reference path="runtime/generated/classes.d.ts" />
+/// <reference path="runtime/generated/concepts.d.ts" />
+/// <reference path="runtime/generated/index-types.d.ts" />
+/// <reference path="runtime/pairs.d.ts" />
+
+/// <reference path="lualib/index.d.ts" />
+
+// common globals
+/// <reference path="common/serpent.d.ts" />
+/// <reference path="runtime/generated/defines.d.ts" />
+/// <reference path="runtime/generated/global-functions.d.ts" />

package/lualib/index.d.ts

@@ -0,0 +1,2 @@
+/// <reference path="util.d.ts" />
+/// <reference path="mod-gui.d.ts" />

package/{runtime → lualib}/mod-gui.d.ts

@@ -2,6 +2,7 @@
 
 /** @noResolution */
 declare module "mod-gui" {
+  import { FlowGuiElement, FrameGuiElement, LuaPlayer } from "factorio:runtime"
   const button_style: string
   const frame_style: string
 

package/{runtime → lualib}/util.d.ts

@@ -1,10 +1,27 @@
-// "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" {
+  import {
+    ColorArray as RColorArray,
+    float,
+    LuaEntity,
+    MapPosition,
+    MapPositionArray,
+    nil,
+    table,
+  } from "factorio:runtime"
+  import { Color as PrototypeColor, SpriteParameters } from "factorio:prototype"
+  import { PrototypeData } from "factorio:common"
+
+  type ColorArray = PrototypeColor & float[]
+  interface ColorTable {
+    r: float
+    g: float
+    b: float
+    a?: float
+  }
+  type AnyColor = PrototypeColor | RColorArray
   namespace table {
     function deepcopy<T>(table: T): T
 
@@ -20,24 +37,23 @@ declare module "util" {
   function formattime(ticks: number): string
 
   /** Supports 'rrggbb', 'rgb', 'rrggbbaa', 'rgba', 'ww', 'w' */
-  function color(hex: string): Color
+  function color(hex: string): ColorTable
+
+  function premul_color(color: AnyColor): ColorTable
+
+  function mix_color(c1: AnyColor, c2: AnyColor): ColorArray
 
-  function premul_color(color: Color): Color
+  function multiply_color(c1: AnyColor, n: number): ColorArray
 
-  function mix_color(c1: Color, c2: Color): ColorArray
+  function get_color_with_alpha(color: AnyColor, alpha: number, normalized_alpha?: boolean): ColorTable
 
-  function multiply_color(c1: Color, n: number): ColorArray
+  const direction_vectors: Record<defines.direction, MapPositionArray>
 
   function moveposition(
     position: MapPositionArray,
-    direction: defines.direction.north | defines.direction.east | defines.direction.south | defines.direction.west,
+    direction: defines.direction.north,
     distance: number
   ): MapPositionArray
-  function moveposition(
-    position: MapPositionArray,
-    direction: defines.direction,
-    distance: number
-  ): MapPositionArray | nil
 
   function oppositedirection(direction: defines.direction): defines.direction
 
@@ -50,22 +66,30 @@ declare module "util" {
   /** Gets tile position by pixel, hr */
   function by_pixel_hr(x: number, y: number): MapPositionArray
 
-  // omitted: foreach_sprite_definition
+  type SpriteWithHrVersion<T = unknown> = T & SpriteParameters & { hr_version?: SpriteParameters & T }
+
+  function foreach_sprite_definition<T extends SpriteWithHrVersion>(
+    sprite: T,
+    fun: (sprite: T & T["hr_version"]) => void
+  ): void
 
   function add_shift(a: MapPositionArray | nil, b: MapPositionArray): MapPositionArray
   function add_shift(a: MapPositionArray, b: MapPositionArray | nil): MapPositionArray
   function add_shift(a: MapPositionArray | nil, b: MapPositionArray | nil): MapPositionArray | nil
 
-  // omitted: add_shift_offset
+  function add_shift_offset<T extends SpriteWithHrVersion<{ shift?: MapPositionArray }>>(
+    offset: MapPositionArray | nil,
+    sprite: T
+  ): T
 
   function mul_shift(shift: MapPositionArray, scale: number | nil): MapPositionArray
   function mul_shift(shift: MapPositionArray | nil, scale: number | nil): MapPositionArray | nil
 
   function format_number(amount: number, append_suffix?: boolean): string
 
-  function increment(t: number[], index: number, v?: number): void
+  function increment(t: number[], luaIndex: number, v?: number): void
 
-  // omitted: conditional_return
+  // Omitted: conditional_return; it's literally just `a and b`
 
   /**
    * Recursively merges and/or deep-copies tables. Entries in later tables override entries in earlier ones, unless both
@@ -80,37 +104,44 @@ declare module "util" {
 
   function split_whitespace(string: string): string[]
 
-  // omitted: split, string_starts_with. already TS functions for that
+  // Omitted: split, string_starts_with. Use the builtin tstl functions for that.
 
-  // omitted: online_players. use game.connected_players
+  // Omitted: online_players. Use game.connected_players
+  // The lua code actually logs "But why?" if you do this...
 
   function clamp(x: number, lower: number, upper: number): number
 
   function get_walkable_tile(): string
 
-  // omitted: combine_icons
+  /**
+   * This function takes 2 icons tables, and adds the second to the first, but applies scale, shift and tint to the entire second set.
+   * This allows you to manipulate the entire second icons table in the same way as you would manipulate a single icon when adding to the icons table.
+   */
+  function combine_icons<T extends SpriteParameters>(
+    icons1: readonly T[],
+    icons2: readonly T[],
+    inputs: {
+      scale?: number
+      shift?: MapPositionArray
+      tint?: AnyColor
+    }
+  ): T[]
+
   // 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 product_amount(product: {
+    probability: number
+    amount?: number
+    amount_min?: number
+    amount_max?: number
+  }): number
+
+  function empty_sprite(): SpriteParameters
+
+  function draw_as_glow<T extends SpriteWithHrVersion>(sprite: T): T
+  function remove_tile_references(data: PrototypeData, array_of_tiles_to_remove: readonly string[]): void
 
   function remove_from_list<T>(list: T[], value: T): boolean