typed-factorio 1.14.0 → 1.16.0

package/runtime/generated/concepts.d.ts

@@ -9,7 +9,7 @@
  *
  * The template can contain placeholders such as `__1__` or `__2__`. These will be replaced by the respective parameter in the LocalisedString. The parameters themselves can be other localised strings, which will be processed recursively in the same fashion. Localised strings can not be recursed deeper than 20 levels and can not have more than 20 parameters.
  *
- * As a special case, when the key is just the empty string, all the parameters will be concatenated (after processing, if any are localised strings). If there is only one parameter, it will be used as is.
+ * There are two special flags for the localised string, indicated by the key being a particular string. First, if the key is the empty string (`""`), then all parameters will be concatenated (after processing, if any are localised strings themselves). Second, if the key is a question mark (`"?"`), then the first valid parameter will be used. A parameter can be invalid if its name doesn't match any string template. If no parameters are valid, the last one is returned. This is useful to implement a fallback for missing locale templates.
  *
  * Furthermore, when an API function expects a localised string, it will also accept a regular string (i.e. not a table) which will not be translated, as well as a number, boolean or `nil`, which will be converted to their textual representation.
  * @example In the English translation, this will print `"No ammo"`; in the Czech translation, it will print `"Bez munice"`:
@@ -34,6 +34,13 @@
  * ```
  * game.print({"", {"item-name.iron-plate"}, ": ", 60})
  * ```
+ * @example As an example of a localised string with fallback, consider this:
+ *
+ * ```
+ * {"?", {"", {"entity-description.furnace"}, "\n"}, {"item-description.furnace"}, "optional fallback"}
+ * ```
+ *
+ *  If `entity-description.furnace` exists, it is concatenated with `"\n"` and returned. Otherwise, if `item-description.furnace` exists, it is returned as-is. Otherwise, `"optional fallback"` is returned. If this value wasn't specified, the translation result would be `"Unknown key: 'item-description.furnace'"`.
  * @see {@link https://lua-api.factorio.com/latest/Concepts.html#LocalisedString Online documentation}
  */
 type LocalisedString = string | number | boolean | LuaObject | nil | readonly [string, ...LocalisedString[]]
@@ -291,7 +298,7 @@ interface SmokeSource {
 type Vector = MapPositionArray
 
 /**
- * Two positions, specifying the top-left and bottom-right corner of the box respectively. Like with {@link MapPosition}, the names of the members may be omitted. When read from the game, the third member `orientation` is present if it is non-zero, however it is ignored when provided to the game.
+ * Two positions, specifying the top-left and bottom-right corner of the box respectively. Like with {@link MapPosition}, the names of the members may be omitted. When read from the game, the third member `orientation` is present if it is non-zero.
  * @see BoundingBoxArray
  * @example Explicit definition:
  *
@@ -793,26 +800,26 @@ interface EnemyExpansionMapSettings {
    */
   readonly settler_group_max_size: uint
   /**
-   * The minimum time between expansions in ticks. The actual cooldown is adjusted to the current evolution levels. Defaults to `4*3,600=14,400` ticks.
+   * The minimum time between expansions in ticks. The actual cooldown is adjusted to the current evolution levels. Defaults to `4*3'600=14'400` ticks.
    */
   readonly min_expansion_cooldown: uint
   /**
-   * The maximum time between expansions in ticks. The actual cooldown is adjusted to the current evolution levels. Defaults to `60*3,600=216,000` ticks.
+   * The maximum time between expansions in ticks. The actual cooldown is adjusted to the current evolution levels. Defaults to `60*3'600=216'000` ticks.
    */
   readonly max_expansion_cooldown: uint
 }
 
 interface UnitGroupMapSettings {
   /**
-   * The minimum amount of time in ticks a group will spend gathering before setting off. The actual time is a random time between the minimum and maximum times. Defaults to `3,600` ticks.
+   * The minimum amount of time in ticks a group will spend gathering before setting off. The actual time is a random time between the minimum and maximum times. Defaults to `3'600` ticks.
    */
   readonly min_group_gathering_time: uint
   /**
-   * The maximum amount of time in ticks a group will spend gathering before setting off. The actual time is a random time between the minimum and maximum times. Defaults to `10*3,600=36,000` ticks.
+   * The maximum amount of time in ticks a group will spend gathering before setting off. The actual time is a random time between the minimum and maximum times. Defaults to `10*3'600=36'000` ticks.
    */
   readonly max_group_gathering_time: uint
   /**
-   * After gathering has finished, the group is allowed to wait this long in ticks for delayed members. New members are not accepted anymore however. Defaults to `2*3,600=7,200` ticks.
+   * After gathering has finished, the group is allowed to wait this long in ticks for delayed members. New members are not accepted anymore however. Defaults to `2*3'600=7'200` ticks.
    */
   readonly max_wait_time_for_late_members: uint
   /**
@@ -882,11 +889,11 @@ interface PathFinderMapSettings {
    */
   readonly goal_pressure_ratio: double
   /**
-   * The maximum number of nodes that are expanded per tick. Defaults to `1,000`.
+   * The maximum number of nodes that are expanded per tick. Defaults to `1'000`.
    */
   readonly max_steps_worked_per_tick: double
   /**
-   * The maximum amount of work each pathfinding job is allowed to do per tick. Defaults to `8,000`.
+   * The maximum amount of work each pathfinding job is allowed to do per tick. Defaults to `8'000`.
    */
   readonly max_work_done_per_tick: uint
   /**
@@ -1073,17 +1080,6 @@ interface MapExchangeStringData {
   readonly map_gen_settings: MapGenSettings
 }
 
-interface BlueprintItemIcon {
-  /**
-   * Name of the item prototype whose icon should be used.
-   */
-  readonly name: string
-  /**
-   * Index of the icon in the blueprint icons slots. Has to be an integer in the range [1, 4].
-   */
-  readonly index: uint
-}
-
 interface BlueprintSignalIcon {
   /**
    * The icon to use. It can be any item icon as well as any virtual signal icon.
@@ -2631,7 +2627,7 @@ interface CircuitConnectionDefinition {
 
 interface WireConnectionDefinition {
   /**
-   * Wire color, either {@link defines.wire_type.red} or {@link defines.wire_type.green}.
+   * The type of wire used.
    */
   readonly wire: defines.wire_type
   /**
@@ -4144,7 +4140,9 @@ type CapsuleAction =
  * - `"entity-with-force"`: Deprecated. Replaced by `is-military-target`.
  * - `"is-military-target"`: Selects entities that are {@link LuaEntity#is_military_target military targets}.
  * - `"entity-with-owner"`: Selects entities that are {@link LuaEntity#is_entity_with_owner entities with owner}.
- * - `"avoid-rolling-stock"`: Selects entities that are not `rolling-stocks`.
+ * - `"avoid-rolling-stock"`: Selects entities that are not `rolling-stock`s.
+ * - `"entity-ghost"`: Selects entities that are `entity-ghost`s.
+ * - `"tile-ghost"`: Selects entities that are `tile-ghost`s.
  * @see {@link https://lua-api.factorio.com/latest/Concepts.html#SelectionModeFlags Online documentation}
  */
 interface SelectionModeFlags {
@@ -4233,9 +4231,17 @@ interface SelectionModeFlags {
    */
   readonly "entity-with-owner"?: true
   /**
-   * Selects entities that are not `rolling-stocks`.
+   * Selects entities that are not `rolling-stock`s.
    */
   readonly "avoid-rolling-stock"?: true
+  /**
+   * Selects entities that are `entity-ghost`s.
+   */
+  readonly "entity-ghost"?: true
+  /**
+   * Selects entities that are `tile-ghost`s.
+   */
+  readonly "tile-ghost"?: true
 }
 
 interface LogisticFilter {
@@ -4253,10 +4259,6 @@ interface LogisticFilter {
   readonly count: uint
 }
 
-/**
- * @remarks Runtime settings can be changed through console commands and by the mod that owns the settings by writing a new table to the ModSetting.
- * @see {@link https://lua-api.factorio.com/latest/Concepts.html#ModSetting Online documentation}
- */
 interface ModSetting {
   /**
    * The value of the mod setting. The type depends on the kind of setting.

package/runtime/generated/defines.d.ts

@@ -1333,6 +1333,30 @@ declare namespace defines {
      * Event type: {@link OnPlayerAltReverseSelectedAreaEvent}
      */
     const on_player_alt_reverse_selected_area: EventId<OnPlayerAltReverseSelectedAreaEvent>
+    /**
+     * Event type: {@link OnGuiHoverEvent}
+     */
+    const on_gui_hover: EventId<OnGuiHoverEvent>
+    /**
+     * Event type: {@link OnGuiLeaveEvent}
+     */
+    const on_gui_leave: EventId<OnGuiLeaveEvent>
+    /**
+     * Event type: {@link OnEntityColorChangedEvent}
+     */
+    const on_entity_color_changed: EventId<OnEntityColorChangedEvent>
+    /**
+     * Event type: {@link OnCutsceneStartedEvent}
+     */
+    const on_cutscene_started: EventId<OnCutsceneStartedEvent>
+    /**
+     * Event type: {@link OnCutsceneFinishedEvent}
+     */
+    const on_cutscene_finished: EventId<OnCutsceneFinishedEvent>
+    /**
+     * Event type: {@link OnPlayerInputMethodChangedEvent}
+     */
+    const on_player_input_method_changed: EventId<OnPlayerInputMethodChangedEvent>
   }
   /**
    * See the {@linkplain https://lua-api.factorio.com/latest/events.html events page} for more info on what events contain and when they get raised.
@@ -1349,6 +1373,23 @@ declare namespace defines {
     two_hundred_fifty_hours,
     one_thousand_hours,
   }
+  enum game_controller_interaction {
+    /**
+     * Game controller will always hover this element regardless of type or state.
+     * @see {@link https://lua-api.factorio.com/latest/defines.html#defines.game_controller_interaction.always Online documentation}
+     */
+    always,
+    /**
+     * Hover according to the element type and implementation.
+     * @see {@link https://lua-api.factorio.com/latest/defines.html#defines.game_controller_interaction.never Online documentation}
+     */
+    never,
+    /**
+     * Never hover this element with a game controller.
+     * @see {@link https://lua-api.factorio.com/latest/defines.html#defines.game_controller_interaction.normal Online documentation}
+     */
+    normal,
+  }
   enum group_state {
     gathering,
     moving,
@@ -1458,6 +1499,8 @@ declare namespace defines {
     gui_click,
     gui_confirmed,
     gui_elem_changed,
+    gui_hover,
+    gui_leave,
     gui_location_changed,
     gui_selected_tab_changed,
     gui_selection_state_changed,

package/runtime/generated/events.d.ts

@@ -19,6 +19,10 @@ interface CustomInputEvent extends EventData {
    * The mouse cursor position when the custom input was activated.
    */
   readonly cursor_position: MapPosition
+  /**
+   * The mouse cursor display location when the custom input was activated.
+   */
+  readonly cursor_display_location: GuiLocation
   /**
    * 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.
    */
@@ -449,6 +453,44 @@ interface OnCutsceneCancelledEvent extends EventData {
   readonly tick: uint
 }
 
+/**
+ * Called when a cutscene finishes naturally (was not cancelled).
+ * @see {@link https://lua-api.factorio.com/latest/events.html#on_cutscene_finished Online documentation}
+ */
+interface OnCutsceneFinishedEvent extends EventData {
+  /**
+   * The player the cutscene was shown to.
+   */
+  readonly player_index: PlayerIndex
+  /**
+   * Identifier of the event
+   */
+  readonly name: typeof defines.events.on_cutscene_finished
+  /**
+   * Tick the event was generated.
+   */
+  readonly tick: uint
+}
+
+/**
+ * Called when a cutscene starts.
+ * @see {@link https://lua-api.factorio.com/latest/events.html#on_cutscene_started Online documentation}
+ */
+interface OnCutsceneStartedEvent extends EventData {
+  /**
+   * The player the cutscene is being shown to.
+   */
+  readonly player_index: PlayerIndex
+  /**
+   * Identifier of the event
+   */
+  readonly name: typeof defines.events.on_cutscene_started
+  /**
+   * Tick the event was generated.
+   */
+  readonly tick: uint
+}
+
 /**
  * Called when a cutscene is playing, each time it reaches a waypoint in that cutscene.
  *
@@ -510,6 +552,25 @@ interface OnEntityClonedEvent extends EventData {
   readonly tick: uint
 }
 
+/**
+ * Called after an entity has been recolored either by the player or through script.
+ * @see {@link https://lua-api.factorio.com/latest/events.html#on_entity_color_changed Online documentation}
+ */
+interface OnEntityColorChangedEvent extends EventData {
+  /**
+   * The entity that was recolored.
+   */
+  readonly entity: LuaEntity
+  /**
+   * Identifier of the event
+   */
+  readonly name: typeof defines.events.on_entity_color_changed
+  /**
+   * Tick the event was generated.
+   */
+  readonly tick: uint
+}
+
 /**
  * Called when an entity is damaged. Can be filtered using {@link LuaEntityDamagedEventFilter}.
  * @remarks This is not called when an entities health is set directly by another mod.
@@ -945,6 +1006,10 @@ interface OnGuiClickEvent extends EventData {
    * The mouse button used if any.
    */
   readonly button: defines.mouse_button_type
+  /**
+   * The display location of the player's cursor.
+   */
+  readonly cursor_display_location: GuiLocation
   /**
    * If alt was pressed.
    */
@@ -1083,6 +1148,52 @@ interface OnGuiElemChangedEvent extends EventData {
   readonly tick: uint
 }
 
+/**
+ * Called when {@link LuaGuiElement} is hovered by the mouse.
+ * @see {@link https://lua-api.factorio.com/latest/events.html#on_gui_hover Online documentation}
+ */
+interface OnGuiHoverEvent extends EventData {
+  /**
+   * The element that is being hovered over.
+   */
+  readonly element: LuaGuiElement
+  /**
+   * The player whose cursor is hovering.
+   */
+  readonly player_index: PlayerIndex
+  /**
+   * Identifier of the event
+   */
+  readonly name: typeof defines.events.on_gui_hover
+  /**
+   * Tick the event was generated.
+   */
+  readonly tick: uint
+}
+
+/**
+ * Called when the player's cursor leaves a {@link LuaGuiElement} that was previously hovered.
+ * @see {@link https://lua-api.factorio.com/latest/events.html#on_gui_leave Online documentation}
+ */
+interface OnGuiLeaveEvent extends EventData {
+  /**
+   * The element that was being hovered.
+   */
+  readonly element: LuaGuiElement
+  /**
+   * The player whose cursor was hovering.
+   */
+  readonly player_index: PlayerIndex
+  /**
+   * Identifier of the event
+   */
+  readonly name: typeof defines.events.on_gui_leave
+  /**
+   * Tick the event was generated.
+   */
+  readonly tick: uint
+}
+
 /**
  * Called when {@link LuaGuiElement} element location is changed (related to frames in `player.gui.screen`).
  * @see {@link https://lua-api.factorio.com/latest/events.html#on_gui_location_changed Online documentation}
@@ -1962,7 +2073,7 @@ interface OnPlayerCreatedEvent extends EventData {
 }
 
 /**
- * Called after a players cursorstack changed in some way.
+ * Called after a player's {@link LuaControl#cursor_stack cursor stack} changed in some way.
  * @see {@link https://lua-api.factorio.com/latest/events.html#on_player_cursor_stack_changed Online documentation}
  */
 interface OnPlayerCursorStackChangedEvent extends EventData {
@@ -2217,6 +2328,26 @@ interface OnPlayerGunInventoryChangedEvent extends EventData {
   readonly tick: uint
 }
 
+/**
+ * Called when a player's input method changes.
+ * @remarks See {@link LuaPlayer#input_method LuaPlayer::input_method}.
+ * @see {@link https://lua-api.factorio.com/latest/events.html#on_player_input_method_changed Online documentation}
+ */
+interface OnPlayerInputMethodChangedEvent extends EventData {
+  /**
+   * The player whose input method changed.
+   */
+  readonly player_index: PlayerIndex
+  /**
+   * Identifier of the event
+   */
+  readonly name: typeof defines.events.on_player_input_method_changed
+  /**
+   * Tick the event was generated.
+   */
+  readonly tick: uint
+}
+
 /**
  * Called after a player joins the game. This is not called when loading a save file in singleplayer, as the player doesn't actually leave the game, and the save is just on pause until they rejoin.
  * @see {@link https://lua-api.factorio.com/latest/events.html#on_player_joined_game Online documentation}
@@ -2455,12 +2586,12 @@ interface OnPlayerPromotedEvent extends EventData {
 }
 
 /**
- * Called when a player is removed (deleted) from the game. Not to be confused with the player logging of this is different in that the player is deleted as if he never existed in the save file.
+ * Called when a player is removed (deleted) from the game. This is markedly different from a player temporarily {@link OnPlayerLeftGameEvent leaving} the game, and instead behaves like the player never existed in the save file.
  * @see {@link https://lua-api.factorio.com/latest/events.html#on_player_removed Online documentation}
  */
 interface OnPlayerRemovedEvent extends EventData {
   /**
-   * The player index that was removed
+   * The index of the removed player.
    */
   readonly player_index: PlayerIndex
   /**
@@ -3158,12 +3289,12 @@ interface OnPrePlayerMinedItemEvent extends EventData {
 }
 
 /**
- * Called before a player is removed (deleted) from the game. Not to be confused with the player logging of this is different in that the player is deleted as if he never existed in the save file.
+ * Called before a player is removed (deleted) from the game. This is markedly different from a player temporarily {@link OnPlayerLeftGameEvent leaving} the game, and instead behaves like the player never existed in the save file.
  * @see {@link https://lua-api.factorio.com/latest/events.html#on_pre_player_removed Online documentation}
  */
 interface OnPrePlayerRemovedEvent extends EventData {
   /**
-   * The player index that will be removed
+   * The index of the removed player.
    */
   readonly player_index: PlayerIndex
   /**
@@ -3886,7 +4017,7 @@ interface OnSurfaceDeletedEvent extends EventData {
 }
 
 /**
- * Called after a surface is imported.
+ * Called after a surface is imported via the map editor.
  * @see {@link https://lua-api.factorio.com/latest/events.html#on_surface_imported Online documentation}
  */
 interface OnSurfaceImportedEvent extends EventData {