typed-factorio 0.20.0-beta.1 → 1.0.0

package/Changelog.md

@@ -1,8 +1,13 @@
+# v1.0.0
+
+- This project now has all the features that was originally planned, and can now guarantee reasonable backwards compatibility for future releases. As such, it now deserves the v1.0.0. Goodbye to [Zer0Ver](http://0ver.org)!
+- Updated to factorio version 1.1.57
+
 # v0.20.0
 
 - Updated to factorio version 1.1.56
-- Added custom-index-template.d.ts. You can use this if you would like to make a "custom" modification of the type definitions.
-- **This is an opt-in**: Some numeric types which represent indices/number,e.g. player_index, entity_number, are now branded numbers with their own type, e.g. `PlayerIndex` and `EntityNumber`. See the README for more info.
+- This is an **opt-in** feature: Some numeric types which represent indices/number,e.g. player_index, entity_number, are now branded numbers with their own type, e.g. `PlayerIndex` and `EntityNumber`. See the README for more info.
+- Added custom-index-template.d.ts to assist trying out custom changes to types in a project.
 
 # v0.19.0
 
@@ -39,8 +44,8 @@
 # v0.15.0
 
 - Table or array concepts are now declared in table form wherever it is an "read" position.
-  - This works with setter overloading for applicable properties: `player.color.x; player.color = [1, 1, 1]` is now valid!
-  - This also applies to concepts/complex types which contain table_or_array properties.
+    - This works with setter overloading for applicable properties: `player.color.x; player.color = [1, 1, 1]` is now valid!
+    - This also applies to concepts/complex types which contain table_or_array properties.
 - Some concepts now also have a special form where it is known to be in a "read" position, where all table_or_array concepts are declared in table form. These concepts are suffixed with "Read", e.g. `ScriptAreaRead`.
 - Arrays which are known to be in a "write" only form (e.g. method parameters) now are marked readonly. This means you can now pass readonly arrays to these methods.
 - `MapPosition` is now a table or array concept.
@@ -56,17 +61,17 @@
 - LuaStyle size, margin/padding setters now have more specific array types. These array types are `SizeArray` and `StyleValuesArray` for size and margin/padding, respectively.
 - `@noSelf` annotation is now only present when necessary.
 - For classes with subclasses:
-  - The original class name (e.g. `LuaItemStack`) still contains attributes of all subclasses (same as before).
-  - There is now a `Base` type (e.g. `BaseItemStack`) which only includes attributes common to all subclasses.
-  - There is a separate type definition for each subclass, e.g. `BlueprintItem`. Note that one instance may still belong to multiple subclasses (the subclasses are not mutually exclusive).
-  - The above two can be optionally used for stricter types.
+    - The original class name (e.g. `LuaItemStack`) still contains attributes of all subclasses (same as before).
+    - There is now a `Base` type (e.g. `BaseItemStack`) which only includes attributes common to all subclasses.
+    - There is a separate type definition for each subclass, e.g. `BlueprintItem`. Note that one instance may still belong to multiple subclasses (the subclasses are not mutually exclusive).
+    - The above two can be optionally used for stricter types.
 
 # v0.13.2
 
 - Fix: resize_to_sprite property should not be on subclass sprite-button
 - Fix: ChooseElemButtonSpec filters should be named elem_filters
 - Switch back to `/latest` api docs link
-  - New version of web api docs is now active
+    - New version of web api docs is now active
 
 # v0.13.0
 
@@ -102,7 +107,7 @@
 # v0.7.3
 
 - Update to factorio version 1.1.42
-  - No api changes, but improvements to descriptions
+    - No api changes, but improvements to descriptions
 
 # v0.7.2
 

package/README.md

@@ -30,10 +30,7 @@ yarn add typed-factorio
 
 This will add the types for the runtime stage to your entire project.
 
-Notes:
-> When types are updated, or released for a new factorio version, you will need update your package version to get the types.
-> 
-> There is an opt-in feature for stricter index types, see [Strict index types](#Strict index types) for more details.
+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
 
@@ -114,7 +111,6 @@ Table-or-array types will appear in the Table form when known to be in a read po
 
 For some concepts, there is also a special form for when the concept is used in a "read" position, where all table-or-array types are in Table form. These types are suffixed with `Read`, e.g. `ScriptPositionRead`.
 
-
 ### Types with subclasses
 
 Some classes have attributes that are documented to only work on particular subclasses. For these classes, e.g. `LuaEntity`, there are specific types that you can _optionally_ use:
@@ -134,11 +130,9 @@ This is done both to provide more accurate types, and for possible integration w
 
 ### Strict index types
 
-This feature is recommended, but currently is a **opt-in**. To opt in, use `typed-factorio/runtime/strict-index-types` instead of `typed-factorio/runtime` in your `tsconfig.json`.
-
-Some `uint` types which represent indices, e.g. player_index, entity_number, are now "branded" numbers with their own type, e.g. `PlayerIndex` and `EntityNumber`. These are assignable to `number`, but `number` is not assignable to them.
-These are indices that do not index into an array-like structure, and otherwise should usually not have arithmetic done to them. So, using a separate type helps ensure correctness.
-You can still use these types as keys in an index signature, e.g. `{ [index: PlayerIndex]: "foo" }`.
-You can cast "plain" numbers to these types, e.g. `2 as PlayerIndex`, only do this with some care.
+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"`).
 
-- `player_index` and `surface_index` still allow the numeric constant 1 as a valid index, representing the first player or the default surface, respectively. This is allowed as this is a common enough use case.
+Some `uint` types which represent indices, e.g. player_index, entity_number, can be "branded" numbers with their own type, e.g. `PlayerIndex` and `EntityNumber`. These are assignable to `number`, but a plain `number` is not directly assignable to them. This helps ensure correctness.
+These are indices that do not index into an array-like structure, and otherwise should usually not have arithmetic done to them.
+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/custom-index-template.d.ts

@@ -2,8 +2,6 @@
 // For example, if you want to modify a file, copy the file you want to modify to your project and make the changes. Then, copy this template file into your project and remove the line corresponding to modified file.
 // If you think your modification will be useful to others, please consider making a change suggestion by creating an issue on GitHub.
 
-// Replace "index-types.d.ts" with "index-types-strict.d.ts" below if you want strict index types.
-
 /// <reference types="lua-types/5.2" />
 
 // generated

package/generated/classes.d.ts

@@ -1895,25 +1895,25 @@ interface LuaCustomInputPrototype {
    */
   readonly action: string
   /**
-   * If this custom input is enabled. Disabled custom inputs exist but are not used by the game.
+   * Whether this custom input is enabled. Disabled custom inputs exist but are not used by the game.
    *
    * {@link https://lua-api.factorio.com/latest/LuaCustomInputPrototype.html#LuaCustomInputPrototype.enabled View documentation}
    */
   readonly enabled: boolean
   /**
-   * If this custom input is enabled while using the spectator controller.
+   * Whether this custom input is enabled while using the spectator controller.
    *
    * {@link https://lua-api.factorio.com/latest/LuaCustomInputPrototype.html#LuaCustomInputPrototype.enabled_while_spectating View documentation}
    */
   readonly enabled_while_spectating: boolean
   /**
-   * If this custom input is enabled while using the cutscene controller.
+   * Whether this custom input is enabled while using the cutscene controller.
    *
    * {@link https://lua-api.factorio.com/latest/LuaCustomInputPrototype.html#LuaCustomInputPrototype.enabled_while_in_cutscene View documentation}
    */
   readonly enabled_while_in_cutscene: boolean
   /**
-   * If this custom input will include the selected prototype (if any) when triggered.
+   * Whether this custom input will include the selected prototype (if any) when triggered.
    *
    * {@link https://lua-api.factorio.com/latest/LuaCustomInputPrototype.html#LuaCustomInputPrototype.include_selected_prototype View documentation}
    */
@@ -2000,7 +2000,12 @@ interface LuaCustomTableMembers {
  */
 type LuaCustomTable<K extends string | number, V> = LuaCustomTableMembers &
   CustomTableIndexer<K, V> &
-  LuaPairsIterable<[number] extends [K] ? number : K, V>
+  LuaPairsIterable<
+    // this convoluted expression gives a number type if K includes a number, even if it includes a string, and K otherwise.
+    // it also preserves number branding
+    [number] extends [K extends number & IndexBrand<infer A> ? number : K] ? (K extends string ? never : K) : K,
+    V
+  >
 
 /**
  * Prototype of a damage.
@@ -4454,6 +4459,14 @@ interface LuaEntity extends LuaControl {
    * @remarks Can also be used on entity ghost if it contains linked-belt<br>May return entity ghost which contains linked belt to which connection is made
    */
   readonly linked_belt_neighbour: LuaEntity | undefined
+  /**
+   * The current radar scan progress, as a number in range [0, 1].
+   *
+   * _Can only be used if this is Radar_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaEntity.html#LuaEntity.radar_scan_progress View documentation}
+   */
+  readonly radar_scan_progress: float
   /**
    * Is this object valid? This Lua object holds a reference to an object within the game engine. It is possible that the game-engine object is removed whilst a mod still holds the corresponding Lua object. If that happens, the object becomes invalid, i.e. this attribute will be `false`. Mods are advised to check for object validity if any change to the game state might have occurred between the creation of the Lua object and its access.
    */
@@ -6999,6 +7012,17 @@ interface SmokeWithTriggerEntity extends BaseEntity {
   time_to_next_effect: uint
 }
 
+interface RadarEntity extends BaseEntity {
+  /**
+   * The current radar scan progress, as a number in range [0, 1].
+   *
+   * _Can only be used if this is Radar_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaEntity.html#LuaEntity.radar_scan_progress View documentation}
+   */
+  readonly radar_scan_progress: float
+}
+
 /**
  * Prototype of an entity.
  *
@@ -7631,6 +7655,12 @@ interface LuaEntityPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.void_energy_source_prototype View documentation}
    */
   readonly void_energy_source_prototype: LuaVoidEnergySourcePrototype | undefined
+  /**
+   * The heat buffer prototype this entity uses or `nil`.
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.heat_buffer_prototype View documentation}
+   */
+  readonly heat_buffer_prototype: LuaHeatBufferPrototype | undefined
   /**
    * The log2 of grid size of the building
    *
@@ -7649,6 +7679,30 @@ interface LuaEntityPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.maximum_temperature View documentation}
    */
   readonly maximum_temperature: double | undefined
+  /**
+   * If this generator prototype burns fluid.
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.burns_fluid View documentation}
+   */
+  readonly burns_fluid: boolean
+  /**
+   * If this generator prototype scales fluid usage.
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.scale_fluid_usage View documentation}
+   */
+  readonly scale_fluid_usage: boolean
+  /**
+   * If this generator prototype destroys non fuel fluids.
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.destroy_non_fuel_fluid View documentation}
+   */
+  readonly destroy_non_fuel_fluid: boolean
+  /**
+   * The default maximum power output of this generator prototype or `nil`.
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.max_power_output View documentation}
+   */
+  readonly max_power_output: double | undefined
   /**
    * The target temperature of this boiler prototype or `nil`.
    *
@@ -8230,6 +8284,31 @@ interface LuaEntityPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.allow_run_time_change_of_is_military_target View documentation}
    */
   readonly allow_run_time_change_of_is_military_target: boolean
+  /**
+   * The logistic parameters for this roboport. or `nil`.
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.logistic_parameters View documentation}
+   * @remarks Both the `charging_station_shift` and `stationing_offset` vectors are tables with `x` and `y` keys instead of an array.
+   */
+  readonly logistic_parameters:
+    | {
+        readonly spawn_and_station_height: float
+        readonly spawn_and_station_shadow_height_offset: float
+        readonly charge_approach_distance: float
+        readonly logistic_radius: float
+        readonly construction_radius: float
+        readonly charging_station_count: uint
+        readonly charging_distance: float
+        readonly charging_station_shift: Vector
+        readonly charging_energy: double
+        readonly charging_threshold_distance: float
+        readonly robot_vertical_acceleration: float
+        readonly stationing_offset: Vector
+        readonly robot_limit: uint
+        readonly logistics_connection_distance: float
+        readonly robots_shrink_when_entering_and_exiting: boolean
+      }
+    | undefined
   /**
    * Gets the current movement speed of this character, including effects from exoskeletons, tiles, stickers and shooting.
    *
@@ -8965,6 +9044,12 @@ interface BaseEntityPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.void_energy_source_prototype View documentation}
    */
   readonly void_energy_source_prototype: LuaVoidEnergySourcePrototype | undefined
+  /**
+   * The heat buffer prototype this entity uses or `nil`.
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.heat_buffer_prototype View documentation}
+   */
+  readonly heat_buffer_prototype: LuaHeatBufferPrototype | undefined
   /**
    * The log2 of grid size of the building
    *
@@ -8983,6 +9068,30 @@ interface BaseEntityPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.maximum_temperature View documentation}
    */
   readonly maximum_temperature: double | undefined
+  /**
+   * If this generator prototype burns fluid.
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.burns_fluid View documentation}
+   */
+  readonly burns_fluid: boolean
+  /**
+   * If this generator prototype scales fluid usage.
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.scale_fluid_usage View documentation}
+   */
+  readonly scale_fluid_usage: boolean
+  /**
+   * If this generator prototype destroys non fuel fluids.
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.destroy_non_fuel_fluid View documentation}
+   */
+  readonly destroy_non_fuel_fluid: boolean
+  /**
+   * The default maximum power output of this generator prototype or `nil`.
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.max_power_output View documentation}
+   */
+  readonly max_power_output: double | undefined
   /**
    * The target temperature of this boiler prototype or `nil`.
    *
@@ -9486,6 +9595,31 @@ interface BaseEntityPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.is_entity_with_owner View documentation}
    */
   readonly is_entity_with_owner: boolean
+  /**
+   * The logistic parameters for this roboport. or `nil`.
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaEntityPrototype.html#LuaEntityPrototype.logistic_parameters View documentation}
+   * @remarks Both the `charging_station_shift` and `stationing_offset` vectors are tables with `x` and `y` keys instead of an array.
+   */
+  readonly logistic_parameters:
+    | {
+        readonly spawn_and_station_height: float
+        readonly spawn_and_station_shadow_height_offset: float
+        readonly charge_approach_distance: float
+        readonly logistic_radius: float
+        readonly construction_radius: float
+        readonly charging_station_count: uint
+        readonly charging_distance: float
+        readonly charging_station_shift: Vector
+        readonly charging_energy: double
+        readonly charging_threshold_distance: float
+        readonly robot_vertical_acceleration: float
+        readonly stationing_offset: Vector
+        readonly robot_limit: uint
+        readonly logistics_connection_distance: float
+        readonly robots_shrink_when_entering_and_exiting: boolean
+      }
+    | undefined
   /**
    * Is this object valid? This Lua object holds a reference to an object within the game engine. It is possible that the game-engine object is removed whilst a mod still holds the corresponding Lua object. If that happens, the object becomes invalid, i.e. this attribute will be `false`. Mods are advised to check for object validity if any change to the game state might have occurred between the creation of the Lua object and its access.
    */
@@ -11530,7 +11664,7 @@ interface LuaGameScript {
    */
   regenerate_entity(entities: string | readonly string[]): void
   /**
-   * Take a screenshot and save it to a file. The filename should include a file extension indicating the desired image format. Supports `.png`, `.jpg` / `.jpeg`, `.tga` and `.bmp`.
+   * Take a screenshot of the game and save it to the `script-output` folder, located in the game's {@link https://wiki.factorio.com/User_data_directory user data directory}. The name of the image file can be specified via the `path` parameter.
    *
    * {@link https://lua-api.factorio.com/latest/LuaGameScript.html#LuaGameScript.take_screenshot View documentation}
    * @remarks If Factorio is running headless, this function will do nothing.
@@ -11561,7 +11695,7 @@ interface LuaGameScript {
      */
     readonly zoom?: double
     /**
-     * The sub-path in `"script-output"` to save the screenshot to. Defaults to `"screenshot.png"`.
+     * The name of the image file. It should include a file extension indicating the desired format. Supports `.png`, `.jpg` /`.jpeg`, `.tga` and `.bmp`. Providing a directory path (ex. `"save/here/screenshot.png"`) will create the necessary folder structure in `script-output`. Defaults to `"screenshot.png"`.
      */
     readonly path?: string
     /**
@@ -11608,7 +11742,7 @@ interface LuaGameScript {
    */
   set_wait_for_screenshots_to_finish(): void
   /**
-   * Take a screenshot of the technology screen and save it to a file. The filename should include a file extension indicating the desired image format. Supports `.png`, `.jpg` / `.jpeg`, `.tga` and `.bmp`.
+   * Take a screenshot of the technology screen and save it to the `script-output` folder, located in the game's {@link https://wiki.factorio.com/User_data_directory user data directory}. The name of the image file can be specified via the `path` parameter.
    *
    * {@link https://lua-api.factorio.com/latest/LuaGameScript.html#LuaGameScript.take_technology_screenshot View documentation}
    */
@@ -11618,7 +11752,7 @@ interface LuaGameScript {
      */
     readonly force?: ForceIdentification
     /**
-     * The sub-path in `"script-output"` to save the screenshot to. Defaults to `"technology-screenshot.png"`.
+     * The name of the image file. It should include a file extension indicating the desired format. Supports `.png`, `.jpg` /`.jpeg`, `.tga` and `.bmp`. Providing a directory path (ex. `"save/here/screenshot.png"`) will create the necessary folder structure in `script-output`. Defaults to `"technology-screenshot.png"`.
      */
     readonly path?: string
     /**
@@ -11653,20 +11787,20 @@ interface LuaGameScript {
    */
   json_to_table(json: string): AnyBasic | undefined
   /**
-   * Write a string to a file.
+   * Write a file to the `script-output` folder, located in the game's {@link https://wiki.factorio.com/User_data_directory user data directory}. The name and file extension of the file can be specified via the `filename` parameter.
    *
    * {@link https://lua-api.factorio.com/latest/LuaGameScript.html#LuaGameScript.write_file View documentation}
-   * @param filename Path to the file to write to.
-   * @param data File content
-   * @param append When `true`, this will append to the end of the file. Defaults to `false`, which will overwrite any pre-existing file with the new data.
-   * @param for_player If given, the file will only be written for this player_index. 0 means only the server if one exists.
+   * @param filename The name of the file. Providing a directory path (ex. `"save/here/example.txt"`) will create the necessary folder structure in `script-output`.
+   * @param data The content to write to the file.
+   * @param append If `true`, `data` will be appended to the end of the file. Defaults to `false`, which will overwrite any pre-existing file with the new `data`.
+   * @param for_player If given, the file will only be written for this `player_index`. Providing `0` will only write to the server's output if present.
    */
   write_file(filename: string, data: LocalisedString, append?: boolean, for_player?: uint): void
   /**
-   * Remove file or directory. Given path is taken relative to the script output directory. Can be used to remove files created by {@link LuaGameScript#write_file LuaGameScript::write_file}.
+   * Remove a file or directory in the `script-output` folder, located in the game's {@link https://wiki.factorio.com/User_data_directory user data directory}. Can be used to remove files created by {@link LuaGameScript#write_file LuaGameScript::write_file}.
    *
    * {@link https://lua-api.factorio.com/latest/LuaGameScript.html#LuaGameScript.remove_path View documentation}
-   * @param path Path to remove, relative to the script output directory
+   * @param path The path to the file or directory to remove, relative to `script-output`.
    */
   remove_path(path: string): void
   /**
@@ -14001,7 +14135,7 @@ interface CameraGuiElementMembers extends BaseGuiElement {
    */
   surface_index: SurfaceIndex
   /**
-   * The zoom this camera or minimap is using.
+   * The zoom this camera or minimap is using. This value must be positive.
    *
    * {@link https://lua-api.factorio.com/latest/LuaGuiElement.html#LuaGuiElement.zoom View documentation}
    */
@@ -14197,7 +14331,7 @@ interface MinimapGuiElementMembers extends BaseGuiElement {
    */
   surface_index: SurfaceIndex
   /**
-   * The zoom this camera or minimap is using.
+   * The zoom this camera or minimap is using. This value must be positive.
    *
    * {@link https://lua-api.factorio.com/latest/LuaGuiElement.html#LuaGuiElement.zoom View documentation}
    */
@@ -14693,6 +14827,35 @@ type GuiElementMembers =
  */
 type LuaGuiElement = GuiElementMembers & GuiElementIndexer
 
+/**
+ * Prototype of a heat buffer.
+ *
+ * {@link https://lua-api.factorio.com/latest/LuaHeatBufferPrototype.html View documentation}
+ * @noSelf
+ */
+interface LuaHeatBufferPrototype {
+  readonly max_temperature: double
+  readonly default_temperature: double
+  readonly specific_heat: double
+  readonly max_transfer: double
+  readonly min_temperature_gradient: double
+  readonly min_working_temperature: double
+  readonly minimum_glow_temperature: double
+  readonly connections: HeatConnection[]
+  /**
+   * Is this object valid? This Lua object holds a reference to an object within the game engine. It is possible that the game-engine object is removed whilst a mod still holds the corresponding Lua object. If that happens, the object becomes invalid, i.e. this attribute will be `false`. Mods are advised to check for object validity if any change to the game state might have occurred between the creation of the Lua object and its access.
+   */
+  readonly valid: boolean
+  /**
+   * The class name of this object. Available even when `valid` is false. For LuaStruct objects it may also be suffixed with a dotted path to a member of the struct.
+   */
+  readonly object_name: "LuaHeatBufferPrototype"
+  /**
+   * All methods and properties that this object supports.
+   */
+  help(): string
+}
+
 /**
  * Prototype of a heat energy source.
  *
@@ -14711,6 +14874,7 @@ interface LuaHeatEnergySourcePrototype {
   readonly min_working_temperature: double
   readonly minimum_glow_temperature: double
   readonly connections: HeatConnection[]
+  readonly heat_buffer_prototype: LuaHeatBufferPrototype
   /**
    * Is this object valid? This Lua object holds a reference to an object within the game engine. It is possible that the game-engine object is removed whilst a mod still holds the corresponding Lua object. If that happens, the object becomes invalid, i.e. this attribute will be `false`. Mods are advised to check for object validity if any change to the game state might have occurred between the creation of the Lua object and its access.
    */
@@ -15376,6 +15540,14 @@ interface LuaItemPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.alt_selection_border_color View documentation}
    */
   readonly alt_selection_border_color: ColorTable
+  /**
+   * The color used when doing reverse selection with this selection tool prototype.
+   *
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_selection_border_color View documentation}
+   */
+  readonly reverse_selection_border_color: ColorTable
   /**
    * Flags that affect which entities will be selected.
    *
@@ -15392,6 +15564,14 @@ interface LuaItemPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.alt_selection_mode_flags View documentation}
    */
   readonly alt_selection_mode_flags: SelectionModeFlags
+  /**
+   * Flags that affect which entities will be selected during reverse selection.
+   *
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_selection_mode_flags View documentation}
+   */
+  readonly reverse_selection_mode_flags: SelectionModeFlags
   /**
    * _Can only be used if this is SelectionTool_
    *
@@ -15404,6 +15584,12 @@ interface LuaItemPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.alt_selection_cursor_box_type View documentation}
    */
   readonly alt_selection_cursor_box_type: string
+  /**
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_selection_cursor_box_type View documentation}
+   */
+  readonly reverse_selection_cursor_box_type: string
   /**
    * If tiles area always included when doing selection with this selection tool prototype.
    *
@@ -15428,6 +15614,14 @@ interface LuaItemPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.alt_entity_filter_mode View documentation}
    */
   readonly alt_entity_filter_mode: string
+  /**
+   * The reverse entity filter mode used by this selection tool.
+   *
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_alt_entity_filter_mode View documentation}
+   */
+  readonly reverse_alt_entity_filter_mode: string
   /**
    * The tile filter mode used by this selection tool.
    *
@@ -15444,6 +15638,14 @@ interface LuaItemPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.alt_tile_filter_mode View documentation}
    */
   readonly alt_tile_filter_mode: string
+  /**
+   * The reverse tile filter mode used by this selection tool.
+   *
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_tile_filter_mode View documentation}
+   */
+  readonly reverse_tile_filter_mode: string
   /**
    * The entity filters used by this selection tool indexed by entity name.
    *
@@ -15460,6 +15662,14 @@ interface LuaItemPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.alt_entity_filters View documentation}
    */
   readonly alt_entity_filters: Record<string, LuaEntityPrototype>
+  /**
+   * The reverse entity filters used by this selection tool indexed by entity name.
+   *
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_entity_filters View documentation}
+   */
+  readonly reverse_entity_filters: Record<string, LuaEntityPrototype>
   /**
    * The entity type filters used by this selection tool indexed by entity type.
    *
@@ -15478,6 +15688,15 @@ interface LuaItemPrototype {
    * @remarks The boolean value is meaningless and is used to allow easy lookup if a type exists in the dictionary.
    */
   readonly alt_entity_type_filters: Record<string, boolean>
+  /**
+   * The reverse entity type filters used by this selection tool indexed by entity type.
+   *
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_entity_type_filters View documentation}
+   * @remarks The boolean value is meaningless and is used to allow easy lookup if a type exists in the dictionary.
+   */
+  readonly reverse_entity_type_filters: Record<string, boolean>
   /**
    * The tile filters used by this selection tool indexed by tile name.
    *
@@ -15494,6 +15713,14 @@ interface LuaItemPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.alt_tile_filters View documentation}
    */
   readonly alt_tile_filters: Record<string, LuaTilePrototype>
+  /**
+   * The reverse tile filters used by this selection tool indexed by tile name.
+   *
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_tile_filters View documentation}
+   */
+  readonly reverse_tile_filters: Record<string, LuaTilePrototype>
   /**
    * The number of entity filters this deconstruction item has or `nil` if this isn't a deconstruction item prototype.
    *
@@ -15939,6 +16166,14 @@ interface SelectionToolItemPrototype extends BaseItemPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.alt_selection_border_color View documentation}
    */
   readonly alt_selection_border_color: ColorTable
+  /**
+   * The color used when doing reverse selection with this selection tool prototype.
+   *
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_selection_border_color View documentation}
+   */
+  readonly reverse_selection_border_color: ColorTable
   /**
    * Flags that affect which entities will be selected.
    *
@@ -15955,6 +16190,14 @@ interface SelectionToolItemPrototype extends BaseItemPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.alt_selection_mode_flags View documentation}
    */
   readonly alt_selection_mode_flags: SelectionModeFlags
+  /**
+   * Flags that affect which entities will be selected during reverse selection.
+   *
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_selection_mode_flags View documentation}
+   */
+  readonly reverse_selection_mode_flags: SelectionModeFlags
   /**
    * _Can only be used if this is SelectionTool_
    *
@@ -15967,6 +16210,12 @@ interface SelectionToolItemPrototype extends BaseItemPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.alt_selection_cursor_box_type View documentation}
    */
   readonly alt_selection_cursor_box_type: string
+  /**
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_selection_cursor_box_type View documentation}
+   */
+  readonly reverse_selection_cursor_box_type: string
   /**
    * If tiles area always included when doing selection with this selection tool prototype.
    *
@@ -15991,6 +16240,14 @@ interface SelectionToolItemPrototype extends BaseItemPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.alt_entity_filter_mode View documentation}
    */
   readonly alt_entity_filter_mode: string
+  /**
+   * The reverse entity filter mode used by this selection tool.
+   *
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_alt_entity_filter_mode View documentation}
+   */
+  readonly reverse_alt_entity_filter_mode: string
   /**
    * The tile filter mode used by this selection tool.
    *
@@ -16007,6 +16264,14 @@ interface SelectionToolItemPrototype extends BaseItemPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.alt_tile_filter_mode View documentation}
    */
   readonly alt_tile_filter_mode: string
+  /**
+   * The reverse tile filter mode used by this selection tool.
+   *
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_tile_filter_mode View documentation}
+   */
+  readonly reverse_tile_filter_mode: string
   /**
    * The entity filters used by this selection tool indexed by entity name.
    *
@@ -16023,6 +16288,14 @@ interface SelectionToolItemPrototype extends BaseItemPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.alt_entity_filters View documentation}
    */
   readonly alt_entity_filters: Record<string, LuaEntityPrototype>
+  /**
+   * The reverse entity filters used by this selection tool indexed by entity name.
+   *
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_entity_filters View documentation}
+   */
+  readonly reverse_entity_filters: Record<string, LuaEntityPrototype>
   /**
    * The entity type filters used by this selection tool indexed by entity type.
    *
@@ -16041,6 +16314,15 @@ interface SelectionToolItemPrototype extends BaseItemPrototype {
    * @remarks The boolean value is meaningless and is used to allow easy lookup if a type exists in the dictionary.
    */
   readonly alt_entity_type_filters: Record<string, boolean>
+  /**
+   * The reverse entity type filters used by this selection tool indexed by entity type.
+   *
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_entity_type_filters View documentation}
+   * @remarks The boolean value is meaningless and is used to allow easy lookup if a type exists in the dictionary.
+   */
+  readonly reverse_entity_type_filters: Record<string, boolean>
   /**
    * The tile filters used by this selection tool indexed by tile name.
    *
@@ -16057,6 +16339,14 @@ interface SelectionToolItemPrototype extends BaseItemPrototype {
    * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.alt_tile_filters View documentation}
    */
   readonly alt_tile_filters: Record<string, LuaTilePrototype>
+  /**
+   * The reverse tile filters used by this selection tool indexed by tile name.
+   *
+   * _Can only be used if this is SelectionTool_
+   *
+   * {@link https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.reverse_tile_filters View documentation}
+   */
+  readonly reverse_tile_filters: Record<string, LuaTilePrototype>
 }
 
 interface DeconstructionItemPrototype extends BaseItemPrototype {

package/generated/events.d.ts

@@ -21,7 +21,7 @@ interface CustomInputEvent extends EventData {
    */
   readonly cursor_position: MapPositionTable
   /**
-   * Information about the prototype that is selected when the custom input is used. `nil` if none is selected.
+   * Information about the prototype that is selected when the custom input is used. Needs to be enabled on the custom input's prototype. `nil` if none is selected.
    */
   readonly selected_prototype?: SelectedPrototypeData
   /**

package/generated/index-types.d.ts

@@ -3,36 +3,47 @@
 /** @noSelfInFile */
 
 /**
- * See {@link LuaPlayer#index LuaPlayer.index}..
+ * See {@link LuaPlayer#index LuaPlayer.index}.
  *
- * This can be a "branded" type for stricter types; see docs on how to opt-in to this.
+ * If using strict-index-types, and you need to use a plain number for this type, you can use a cast, e.g. `1 as PlayerIndex`.
  */
-type PlayerIndex = uint
+type PlayerIndex = uint & IndexBrand<"_playerIndexBrand">
 
 /**
- * See {@link LuaSurface#index LuaSurface.index}..
+ * See {@link LuaSurface#index LuaSurface.index}.
  *
- * This can be a "branded" type for stricter types; see docs on how to opt-in to this.
+ * If using strict-index-types, and you need to use a plain number for this type, you can use a cast, e.g. `1 as SurfaceIndex`.
  */
-type SurfaceIndex = uint
+type SurfaceIndex = uint & IndexBrand<"_surfaceIndexBrand">
 
 /**
- * See {@link LuaEntity#unit_number LuaEntity.unit_number}..
+ * See {@link LuaEntity#unit_number LuaEntity.unit_number}.
  *
- * This can be a "branded" type for stricter types; see docs on how to opt-in to this.
+ * If using strict-index-types, and you need to use a plain number for this type, you can use a cast, e.g. `1 as UnitNumber`.
  */
-type UnitNumber = uint
+type UnitNumber = uint & IndexBrand<"_unitNumberBrand">
 
 /**
- * See {@link LuaGuiElement#index LuaGuiElement.index}..
+ * See {@link LuaGuiElement#index LuaGuiElement.index}.
  *
- * This can be a "branded" type for stricter types; see docs on how to opt-in to this.
+ * If using strict-index-types, and you need to use a plain number for this type, you can use a cast, e.g. `1 as GuiElementIndex`.
  */
-type GuiElementIndex = uint
+type GuiElementIndex = uint & IndexBrand<"_guiElementIndexBrand">
 
 /**
- * See {@link LuaBootstrap#register_on_entity_destroyed LuaBootstrap.register_on_entity_destroyed}..
+ * See {@link LuaBootstrap#register_on_entity_destroyed LuaBootstrap.register_on_entity_destroyed}.
  *
- * This can be a "branded" type for stricter types; see docs on how to opt-in to this.
+ * If using strict-index-types, and you need to use a plain number for this type, you can use a cast, e.g. `1 as RegistrationNumber`.
  */
-type RegistrationNumber = uint64
+type RegistrationNumber = uint64 & IndexBrand<"_registrationNumberBrand">
+
+interface __OptInFeatures {}
+
+/**
+ * Equals a branded type when __OptInFeatures contains strictIndexTypes, otherwise equals `unknown`.
+ */
+type IndexBrand<B extends string> = "strictIndexTypes" extends keyof __OptInFeatures
+  ? {
+      [K in B]: any
+    }
+  : unknown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typed-factorio",
-  "version": "0.20.0-beta.1",
+  "version": "1.0.0",
   "description": "Featureful typescript definitions for the the Factorio modding lua api.",
   "keywords": [
     "factorio",

package/runtime/pairs.d.ts

@@ -1,15 +1,10 @@
 /** @noSelfInFile */
 ///<reference types="lua-types/5.2" />
 
-/**
- * Iterating with `pairs` will only iterate the array part of a {@link LuaCustomTable}.
- *
- * **Note**: you can also iterate on a LuaCustomTable directly without using `pairs`, e.g. `for(const [k, v] of table)`.
- */
-declare function pairs<V>(table: LuaCustomTable<number | string, V>): LuaIterable<LuaMultiReturn<[number, V]>>
-
 /** **Note**: you can also iterate on a LuaCustomTable directly without using `pairs`, e.g. `for(const [k, v] of table)`. */
-declare function pairs<K extends number | string, V>(table: LuaCustomTable<K, V>): LuaIterable<LuaMultiReturn<[K, V]>>
+declare function pairs<T extends LuaCustomTable<any, any>>(
+  table: T
+): LuaIterable<LuaMultiReturn<T extends Iterable<infer E> ? E : never>>
 
 /** @deprecated {@link LuaCustomTable} cannot be iterated with `ipairs`; Use {@link pairs} instead. */
 declare function ipairs(table: LuaCustomTable<any, any>): never

package/strict-index-types.d.ts

@@ -0,0 +1,3 @@
+interface __OptInFeatures {
+  strictIndexTypes: true
+}

package/generated/index-types-strict.d.ts

@@ -1,52 +0,0 @@
-// This is an auto-generated file. Do not edit directly!
-
-/** @noSelfInFile */
-
-/**
- * See {@link LuaPlayer#index LuaPlayer.index}.
- *
- * If you need to use a number/numeric literal for this type, you can use a cast, e.g. `2 as PlayerIndex`.
- */
-type PlayerIndex =
-  | (uint & {
-      _playerIndexBrand: void
-    })
-  | 1
-
-/**
- * See {@link LuaSurface#index LuaSurface.index}.
- *
- * If you need to use a number/numeric literal for this type, you can use a cast, e.g. `2 as SurfaceIndex`.
- */
-type SurfaceIndex =
-  | (uint & {
-      _surfaceIndexBrand: void
-    })
-  | 1
-
-/**
- * See {@link LuaEntity#unit_number LuaEntity.unit_number}.
- *
- * If you need to use a number/numeric literal for this type, you can use a cast, e.g. `2 as UnitNumber`.
- */
-type UnitNumber = uint & {
-  _unitNumberBrand: void
-}
-
-/**
- * See {@link LuaGuiElement#index LuaGuiElement.index}.
- *
- * If you need to use a number/numeric literal for this type, you can use a cast, e.g. `2 as GuiElementIndex`.
- */
-type GuiElementIndex = uint & {
-  _guiElementIndexBrand: void
-}
-
-/**
- * See {@link LuaBootstrap#register_on_entity_destroyed LuaBootstrap.register_on_entity_destroyed}.
- *
- * If you need to use a number/numeric literal for this type, you can use a cast, e.g. `2 as RegistrationNumber`.
- */
-type RegistrationNumber = uint64 & {
-  _registrationNumberBrand: void
-}

package/runtime/strict-index-types.d.ts

@@ -1,18 +0,0 @@
-/// <reference types="lua-types/5.2" />
-
-// generated
-/// <reference path="../generated/builtin-types.d.ts" />
-/// <reference path="../generated/global-objects.d.ts" />
-/// <reference path="../generated/defines.d.ts" />
-/// <reference path="../generated/events.d.ts" />
-/// <reference path="../generated/classes.d.ts" />
-/// <reference path="../generated/concepts.d.ts" />
-/// <reference path="../generated/index-types-strict.d.ts" />
-
-// other runtime
-/// <reference path="librariesAndFunctions.d.ts" />
-/// <reference path="pairs.d.ts" />
-
-// lualib
-/// <reference path="util.d.ts" />
-/// <reference path="mod-gui.d.ts" />