typed-factorio 1.13.0 → 1.15.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:
  *
@@ -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
   /**
@@ -3093,14 +3089,15 @@ type SimpleItemStack = string | ItemStackDefinition
 type FluidIdentification = string | LuaFluidPrototype | Fluid
 
 /**
- * A force may be specified in one of two ways.
+ * A force may be specified in one of three ways.
  *
  * **Options:**
+ * - ForceIndex: The force index.
  * - `string`: The force name.
  * - {@link LuaForce}: A reference to {@link LuaForce} may be passed directly.
  * @see {@link https://lua-api.factorio.com/latest/Concepts.html#ForceIdentification Online documentation}
  */
-type ForceIdentification = string | LuaForce
+type ForceIdentification = ForceIndex | string | LuaForce
 
 /**
  * A technology may be specified in one of three ways.
@@ -4143,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 {
@@ -4232,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 {
@@ -4252,15 +4259,11 @@ 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.
    */
-  readonly value: int | double | boolean | string
+  readonly value: int | double | boolean | string | Color
 }
 
 /**
@@ -5194,7 +5197,7 @@ type ModSettingPrototypeFilter =
  */
 interface BaseTechnologyPrototypeFilter {
   /**
-   * The condition to filter on. One of `"enabled"`, `"hidden"`, `"upgrade"`, `"visible-when-disabled"`, `"has-effects"`, `"has-prerequisites"`, `"research-unit-ingredient"`, `"level"`, `"max-level"`, `"time"`.
+   * The condition to filter on. One of `"enabled"`, `"hidden"`, `"upgrade"`, `"visible-when-disabled"`, `"has-effects"`, `"has-prerequisites"`, `"research-unit-ingredient"`, `"unlocks-recipe"`, `"level"`, `"max-level"`, `"time"`.
    */
   readonly filter:
     | "enabled"
@@ -5204,6 +5207,7 @@ interface BaseTechnologyPrototypeFilter {
     | "has-effects"
     | "has-prerequisites"
     | "research-unit-ingredient"
+    | "unlocks-recipe"
     | "level"
     | "max-level"
     | "time"
@@ -5228,6 +5232,17 @@ interface ResearchUnitIngredientTechnologyPrototypeFilter extends BaseTechnology
   readonly ingredient: string
 }
 
+/**
+ * `"unlocks-recipe"` variant of {@link TechnologyPrototypeFilter}.
+ */
+interface UnlocksRecipeTechnologyPrototypeFilter extends BaseTechnologyPrototypeFilter {
+  readonly filter: "unlocks-recipe"
+  /**
+   * The recipe to check.
+   */
+  readonly recipe: string
+}
+
 /**
  * `"level"` variant of {@link TechnologyPrototypeFilter}.
  */
@@ -5305,6 +5320,7 @@ interface OtherTechnologyPrototypeFilter extends BaseTechnologyPrototypeFilter {
  *
  * Other attributes may be specified depending on `filter`:
  * - `"research-unit-ingredient"`: {@link ResearchUnitIngredientTechnologyPrototypeFilter}
+ * - `"unlocks-recipe"`: {@link UnlocksRecipeTechnologyPrototypeFilter}
  * - `"level"`: {@link LevelTechnologyPrototypeFilter}
  * - `"max-level"`: {@link MaxLevelTechnologyPrototypeFilter}
  * - `"time"`: {@link TimeTechnologyPrototypeFilter}
@@ -5312,6 +5328,7 @@ interface OtherTechnologyPrototypeFilter extends BaseTechnologyPrototypeFilter {
  */
 type TechnologyPrototypeFilter =
   | ResearchUnitIngredientTechnologyPrototypeFilter
+  | UnlocksRecipeTechnologyPrototypeFilter
   | LevelTechnologyPrototypeFilter
   | MaxLevelTechnologyPrototypeFilter
   | TimeTechnologyPrototypeFilter
@@ -5323,6 +5340,7 @@ type TechnologyPrototypeFilter =
  */
 type TechnologyPrototypeFilterWrite =
   | ResearchUnitIngredientTechnologyPrototypeFilter
+  | UnlocksRecipeTechnologyPrototypeFilter
   | LevelTechnologyPrototypeFilterWrite
   | MaxLevelTechnologyPrototypeFilterWrite
   | TimeTechnologyPrototypeFilterWrite
@@ -7314,6 +7332,120 @@ type LuaPlayerRepairedEntityEventFilter =
   | GhostNamePlayerRepairedEntityEventFilter
   | OtherPlayerRepairedEntityEventFilter
 
+/**
+ * Common attributes to all variants of {@link LuaScriptRaisedTeleportedEventFilter}.
+ */
+interface BaseScriptRaisedTeleportedEventFilter {
+  /**
+   * The condition to filter on. One of `"ghost"`, `"rail"`, `"rail-signal"`, `"rolling-stock"`, `"robot-with-logistics-interface"`, `"vehicle"`, `"turret"`, `"crafting-machine"`, `"wall-connectable"`, `"transport-belt-connectable"`, `"circuit-network-connectable"`, `"type"`, `"name"`, `"ghost_type"`, `"ghost_name"`.
+   */
+  readonly filter:
+    | "ghost"
+    | "rail"
+    | "rail-signal"
+    | "rolling-stock"
+    | "robot-with-logistics-interface"
+    | "vehicle"
+    | "turret"
+    | "crafting-machine"
+    | "wall-connectable"
+    | "transport-belt-connectable"
+    | "circuit-network-connectable"
+    | "type"
+    | "name"
+    | "ghost_type"
+    | "ghost_name"
+  /**
+   * How to combine this with the previous filter. Must be `"or"` or `"and"`. Defaults to `"or"`. When evaluating the filters, `"and"` has higher precedence than `"or"`.
+   */
+  readonly mode?: "or" | "and"
+  /**
+   * Inverts the condition. Default is `false`.
+   */
+  readonly invert?: boolean
+}
+
+/**
+ * `"type"` variant of {@link LuaScriptRaisedTeleportedEventFilter}.
+ */
+interface TypeScriptRaisedTeleportedEventFilter extends BaseScriptRaisedTeleportedEventFilter {
+  readonly filter: "type"
+  /**
+   * The prototype type
+   */
+  readonly type: string
+}
+
+/**
+ * `"name"` variant of {@link LuaScriptRaisedTeleportedEventFilter}.
+ */
+interface NameScriptRaisedTeleportedEventFilter extends BaseScriptRaisedTeleportedEventFilter {
+  readonly filter: "name"
+  /**
+   * The prototype name
+   */
+  readonly name: string
+}
+
+/**
+ * `"ghost_type"` variant of {@link LuaScriptRaisedTeleportedEventFilter}.
+ */
+interface GhostTypeScriptRaisedTeleportedEventFilter extends BaseScriptRaisedTeleportedEventFilter {
+  readonly filter: "ghost_type"
+  /**
+   * The ghost prototype type
+   */
+  readonly type: string
+}
+
+/**
+ * `"ghost_name"` variant of {@link LuaScriptRaisedTeleportedEventFilter}.
+ */
+interface GhostNameScriptRaisedTeleportedEventFilter extends BaseScriptRaisedTeleportedEventFilter {
+  readonly filter: "ghost_name"
+  /**
+   * The ghost prototype name
+   */
+  readonly name: string
+}
+
+/**
+ * Variants of {@link LuaScriptRaisedTeleportedEventFilter} with no additional attributes.
+ */
+interface OtherScriptRaisedTeleportedEventFilter extends BaseScriptRaisedTeleportedEventFilter {
+  readonly filter:
+    | "ghost"
+    | "rail"
+    | "rail-signal"
+    | "rolling-stock"
+    | "robot-with-logistics-interface"
+    | "vehicle"
+    | "turret"
+    | "crafting-machine"
+    | "wall-connectable"
+    | "transport-belt-connectable"
+    | "circuit-network-connectable"
+}
+
+/**
+ * Depending on the value of `filter`, the table may take additional fields. `filter` may be one of the following:
+ *
+ * Base attributes: {@link BaseScriptRaisedTeleportedEventFilter}
+ *
+ * Other attributes may be specified depending on `filter`:
+ * - `"type"`: {@link TypeScriptRaisedTeleportedEventFilter}
+ * - `"name"`: {@link NameScriptRaisedTeleportedEventFilter}
+ * - `"ghost_type"`: {@link GhostTypeScriptRaisedTeleportedEventFilter}
+ * - `"ghost_name"`: {@link GhostNameScriptRaisedTeleportedEventFilter}
+ * @see {@link https://lua-api.factorio.com/latest/Concepts.html#LuaScriptRaisedTeleportedEventFilter Online documentation}
+ */
+type LuaScriptRaisedTeleportedEventFilter =
+  | TypeScriptRaisedTeleportedEventFilter
+  | NameScriptRaisedTeleportedEventFilter
+  | GhostTypeScriptRaisedTeleportedEventFilter
+  | GhostNameScriptRaisedTeleportedEventFilter
+  | OtherScriptRaisedTeleportedEventFilter
+
 /**
  * Common attributes to all variants of {@link LuaEntityMarkedForUpgradeEventFilter}.
  */

package/runtime/generated/defines.d.ts

@@ -939,6 +939,12 @@ declare namespace defines {
      * Event filter: {@link LuaScriptRaisedReviveEventFilter}
      */
     const script_raised_revive: EventId<ScriptRaisedReviveEvent, LuaScriptRaisedReviveEventFilter>
+    /**
+     * Event type: {@link ScriptRaisedTeleportedEvent}
+     *
+     * Event filter: {@link LuaScriptRaisedTeleportedEventFilter}
+     */
+    const script_raised_teleported: EventId<ScriptRaisedTeleportedEvent, LuaScriptRaisedTeleportedEventFilter>
     /**
      * Event type: {@link ScriptRaisedSetTilesEvent}
      */
@@ -1327,6 +1333,22 @@ 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 OnCutsceneStartedEvent}
+     */
+    const on_cutscene_started: EventId<OnCutsceneStartedEvent>
+    /**
+     * Event type: {@link OnCutsceneFinishedEvent}
+     */
+    const on_cutscene_finished: EventId<OnCutsceneFinishedEvent>
   }
   /**
    * 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.
@@ -1452,6 +1474,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

@@ -449,6 +449,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.
  *
@@ -1083,6 +1121,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 +2046,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 {
@@ -2455,12 +2539,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 +3242,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
   /**
@@ -3802,7 +3886,7 @@ interface OnSpiderCommandCompletedEvent extends EventData {
 }
 
 /**
- * Called when a translation request generated through {@link LuaPlayer#request_translation LuaPlayer::request_translation} is translated.
+ * Called when a translation request generated through {@link LuaPlayer#request_translation LuaPlayer::request_translation} or {@link LuaPlayer#request_translations LuaPlayer::request_translations} has been completed.
  * @see {@link https://lua-api.factorio.com/latest/events.html#on_string_translated Online documentation}
  */
 interface OnStringTranslatedEvent extends EventData {
@@ -3886,7 +3970,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 {
@@ -4215,6 +4299,33 @@ interface ScriptRaisedSetTilesEvent extends EventData {
   readonly tick: uint
 }
 
+/**
+ * A static event mods can use to tell other mods they teleported something by script. This event is only raised if a mod does so with {@link LuaBootstrap#raise_event LuaBootstrap::raise_event} or {@link LuaBootstrap#raise_script_teleported LuaBootstrap::raise_script_teleported}, or when `raise_teleported` is passed to {@link LuaControl#teleport LuaControl::teleport}. Can be filtered using {@link LuaScriptRaisedTeleportedEventFilter}.
+ * @see {@link https://lua-api.factorio.com/latest/events.html#script_raised_teleported Online documentation}
+ */
+interface ScriptRaisedTeleportedEvent extends EventData {
+  /**
+   * The entity that was teleported.
+   */
+  readonly entity: LuaEntity
+  /**
+   * The entity's surface before the teleportation.
+   */
+  readonly old_surface_index: uint8
+  /**
+   * The entity's position before the teleportation.
+   */
+  readonly old_position: MapPosition
+  /**
+   * Identifier of the event
+   */
+  readonly name: typeof defines.events.script_raised_teleported
+  /**
+   * Tick the event was generated.
+   */
+  readonly tick: uint
+}
+
 /** An event id. */
 type EventId<T extends table, F = unknown> = uint & {
   readonly _eventData: T

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

@@ -16,6 +16,13 @@ type PlayerIndex = uint & IndexBrand<"_playerIndexBrand">
  */
 type SurfaceIndex = uint & IndexBrand<"_surfaceIndexBrand">
 
+/**
+ * See {@link LuaForce#index LuaForce.index}.
+ *
+ * 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 ForceIndex`.
+ */
+type ForceIndex = uint & IndexBrand<"_forceIndexBrand">
+
 /**
  * See {@link LuaEntity#unit_number LuaEntity.unit_number}.
  *