typed-factorio 0.5.0 → 0.7.0

package/README.md

@@ -34,9 +34,11 @@ Note: When types are updated, or released for a new factorio version, you will n
 
 ### Settings and data stage
 
-There are also basic definitions for the settings/data stage.
+There are also definitions for the settings/data stage.
 
-To avoid type conflicts, the global tables for the settings/data stages have to be declared manually where you need them. The types be imported from `typed-factorio/data-stage-types` and `typed-factorio/settings-stage-types`. Examples:
+To avoid type conflicts, the global tables for the settings/data stages have to be declared manually where you need them. These types can be imported from `typed-factorio/data/types` or `typed-factorio/settings/types`.
+
+Example:
 
 ```ts
 import { Data, Mods } from "typed-factorio/data/types"
@@ -58,27 +60,25 @@ Currently, there are types for the following modules:
 - `util`
 - `mod-gui`
 
-If you have a need for types to more lualib modules, feel free to open an issue or pull request.
+If you have a need for types to more lualib modules, feel free to open an issue or pull request on GitHub.
 
 ## Type features
 
-Typed-factorio has nearly 100% complete types for the runtime stage. Even description-only concepts and some not documented types are filled in manually.
-
-The only incomplete type is `BlueprintControlBehavior`, which isn't documented anywhere.
+Typed-factorio has 100% complete types for the runtime stage. Description-only concepts and some not documented types are filled in manually.
 
 ### Lua features
 
 The types include [TypescriptToLua language extensions](https://typescripttolua.github.io/docs/advanced/language-extensions/)
-and [lua-types](https://github.com/TypeScriptToLua/lua-types) (for v5.2), as dependencies.
+and [lua-types](https://github.com/TypeScriptToLua/lua-types) (for v5.2) as dependencies.
 
 This is to use tstl features such as `LuaLengthMethod` and `LuaMultiReturn`.
 
 ### `nil`
 
 The types consistently use `undefined` to represent `nil`.
-`null` is not used, even though it takes fewer characters to type, because `undefined` in typescript is much more similar to `nil` in lua, and optional parameters/properties already use `undefined`.
+`null` is not used, because `undefined` in typescript is much more similar to `nil` in lua, and optional parameters/properties already use `undefined`.
 
-A class attribute is marked as possibly undefined only if the _read_ type is possibly `nil`. For properties where `nil` is not possible on _read_, but is possible on `write`, you can write `nil` by using `undefined!` or `myNullableValue!`, e.g. `controlBehavior.parameters = undefined!`.
+A class attribute is marked as possibly undefined only if the _read_ type is possibly `nil`. For properties where `nil` is not possible on _read_, but is possible on _write_, you can write `nil` by using `undefined!` or `myNullableValue!`, e.g. `controlBehavior.parameters = undefined!`.
 
 ### Variant parameter types
 
@@ -90,7 +90,7 @@ The type for a specific variant is prefixed with the either variant name or "Oth
 
 `script.on_event()`, `script.get/set_filters()`, and `script.raise_event()` all have type checking on the event data/filter type, inferred from what is passed as the event name/id.
 
-You can pass a type parameter to `script.generate_event_name()` with the type of the event data, and it will return an `EventId` that also holds type info of the event data. Other event functions on `script` can then use the type data when the `EventId` is used.
+You can pass a type parameter to `script.generate_event_name()`, and it will return an `EventId` that holds type info of the event data. Event functions on `script` can then use the type data when the `EventId` is passed.
 
 ### Array-like types
 
@@ -98,7 +98,7 @@ Classes that have an index operator, a length operator, and have an array-like s
 
 ### Table or array types
 
-For table or array types (e.g. Position), there also are types such as `PositionTable` and `PositionArray` types that refer to the table or array form specifically.
+For table or array types (e.g. Position), there also are types such as `PositionTable` and `PositionArray` that refer to the table or array form specifically.
 
 ### LuaGuiElement
 
@@ -110,4 +110,4 @@ This is done both to provide more accurate types, and for possible integration w
 
 ### Examples
 
-Check out the `tests` directory for more examples on particular type features.
+Check out the `test` directory on GitHub for more examples on particular type features.

package/generated/classes.d.ts

@@ -241,11 +241,6 @@ type RaiseableEvents =
   | typeof defines.events.script_raised_revive
   | typeof defines.events.script_raised_set_tiles
 
-/** A custom event id created by {@link LuaBootstrap.generate_event_name}, with type data of the event. */
-type CustomEventId<T extends table> = uint & {
-  _eventData: T
-}
-
 /**
  * Entry point for registering event handlers. It is accessible through the global object named `script`.
  *
@@ -336,14 +331,13 @@ interface LuaBootstrap {
    * @param f - The handler for this event. Passing `nil` will unregister it.
    * @param filters - The filters for this event. Can only be used when registering for individual events.
    */
-  on_event<E extends keyof EventFilters>(
+  on_event<E extends EventId<any, table>>(
     event: E,
-    f: ((data: EventTypes[E]) => void) | undefined,
-    filters?: EventFilters[E][]
+    f: ((data: E["_eventData"]) => void) | undefined,
+    filters?: E["_filter"][]
   ): void
-  on_event<E extends defines.events>(event: E | E[], f: ((data: EventTypes[E]) => void) | undefined): void
+  on_event<E extends EventId<any, any>>(event: E | E[], f: ((data: E["_eventData"]) => void) | undefined): void
   on_event(event: string, f: ((data: CustomInputEvent) => void) | undefined): void
-  on_event<T extends table>(event: CustomEventId<T>, f: ((data: T) => void) | undefined): void
   /**
    * Register a handler to run every nth-tick(s). When the game is on tick 0 it will trigger all registered handlers.
    *
@@ -388,9 +382,8 @@ interface LuaBootstrap {
    * @param event - The event identifier to get a handler for.
    * @returns Reference to the function currently registered as the handler.
    */
-  get_event_handler<E extends defines.events>(event: E): (data: EventTypes[E]) => void
+  get_event_handler<E extends EventId<any>>(event: E): (data: E["_eventData"]) => void
   get_event_handler(event: string): (data: CustomInputEvent) => void
-  get_event_handler<T extends table>(event: CustomEventId<T>): (data: T) => void
   /**
    * Gets the mod event order as a string.
    *
@@ -427,7 +420,7 @@ interface LuaBootstrap {
    * @param event - ID of the event to filter.
    * @param filters - The filters or `nil` to clear them.
    */
-  set_event_filter<E extends keyof EventFilters>(event: E, filters: EventFilters[E][] | undefined): void
+  set_event_filter<E extends EventId<any, table>>(event: E, filters: E["_filter"][] | undefined): void
   /**
    * Gets the filters for the given event.
    *
@@ -436,7 +429,7 @@ interface LuaBootstrap {
    * @param event - ID of the event to get.
    * @returns The filters or `nil` if none are defined.
    */
-  get_event_filter<E extends keyof EventFilters>(event: E): EventFilters[E][] | undefined
+  get_event_filter<E extends EventId<any, table>>(event: E): E["_filter"][] | undefined
   /**
    * Raise an event. Only events generated with
    * {@link LuaBootstrap.generate_event_name LuaBootstrap::generate_event_name} and the following can be raised:
@@ -464,8 +457,10 @@ interface LuaBootstrap {
    * @param event - ID of the event to raise.
    * @param data - Table with extra data that will be passed to the event handler.
    */
-  raise_event<T extends table>(event: CustomEventId<T>, data: T): void
-  raise_event<E extends RaiseableEvents>(event: E, data: Omit<EventTypes[E], keyof EventData>): void
+  raise_event<E extends RaiseableEvents | CustomEventId<any>>(
+    event: E,
+    data: Omit<E["_eventData"], keyof EventData>
+  ): void
   /**
    * Raises {@link OnConsoleChatEvent on_console_chat} with the given parameters.
    *
@@ -6036,7 +6031,7 @@ interface LuaEquipment {
 }
 
 /**
- * Prototype of a equipment category.
+ * Prototype of an equipment category.
  *
  * {@link https://lua-api.factorio.com/next/LuaEquipmentCategoryPrototype.html View documentation}
  *
@@ -8543,6 +8538,15 @@ interface LuaGameScript {
    * {@link https://lua-api.factorio.com/next/LuaGameScript.html#LuaGameScript.players View documentation}
    */
   readonly players: LuaCustomTable<uint | string, LuaPlayer>
+  /**
+   * The currently active set of map settings. Even though this property is marked as read-only, the members of the
+   * dictionary that is returned can be modified mid-game.
+   *
+   * **Note**: This does not contain difficulty settings, use
+   * {@link LuaGameScript.difficulty_settings LuaGameScript::difficulty_settings} instead.
+   *
+   * {@link https://lua-api.factorio.com/next/LuaGameScript.html#LuaGameScript.map_settings View documentation}
+   */
   readonly map_settings: MapSettings
   /**
    * The currently active set of difficulty settings. Even though this property is marked as read-only, the members of
@@ -9271,7 +9275,6 @@ interface ScrollPaneGuiSpec extends BaseGuiSpec {
     | "always"
     | "auto-and-reserve-space"
     | "dont-show-but-allow-scrolling"
-    | "auto"
   /**
    * Policy of the vertical scroll bar. Possible values are `"auto"`, `"never"`, `"always"`,
    * `"auto-and-reserve-space"`, `"dont-show-but-allow-scrolling"`. Defaults to `"auto"`.
@@ -9282,7 +9285,6 @@ interface ScrollPaneGuiSpec extends BaseGuiSpec {
     | "always"
     | "auto-and-reserve-space"
     | "dont-show-but-allow-scrolling"
-    | "auto"
 }
 
 interface DropDownGuiSpec extends BaseGuiSpec {
@@ -9481,7 +9483,7 @@ interface SwitchGuiSpec extends BaseGuiSpec {
    * Possible values are `"left"`, `"right"`, or `"none"`. If set to "none", `allow_none_state` must be `true`.
    * Defaults to `"left"`.
    */
-  readonly switch_state?: "left" | "right" | "none" | "none" | "left"
+  readonly switch_state?: "left" | "right" | "none"
   /** Whether the switch can be set to a middle state. Defaults to `false`. */
   readonly allow_none_state?: boolean
   readonly left_label_caption?: LocalisedString
@@ -10076,7 +10078,7 @@ interface ListBoxGuiElementMembers extends BaseGuiElement {
    * @param scroll_mode - Where the item should be positioned in the scroll-pane. Must be either `"in-view"` or
    *   `"top-third"`. Defaults to `"in-view"`.
    */
-  scroll_to_item(index: int, scroll_mode?: "in-view" | "top-third" | "in-view"): void
+  scroll_to_item(index: int, scroll_mode?: "in-view" | "top-third"): void
 }
 
 type ListBoxGuiElement = ListBoxGuiElementMembers & GuiElementIndex
@@ -10132,7 +10134,7 @@ interface ScrollPaneGuiElementMembers extends BaseGuiElement {
    * @param scroll_mode - Where the element should be positioned in the scroll-pane. Must be either `"in-view"` or
    *   `"top-third"`. Defaults to `"in-view"`.
    */
-  scroll_to_element(element: LuaGuiElement, scroll_mode?: "in-view" | "top-third" | "in-view"): void
+  scroll_to_element(element: LuaGuiElement, scroll_mode?: "in-view" | "top-third"): void
   /**
    * Policy of the horizontal scroll bar. Possible values are `"auto"`, `"never"`, `"always"`,
    * `"auto-and-reserve-space"`, `"dont-show-but-allow-scrolling"`.
@@ -14440,12 +14442,20 @@ interface LuaPlayer extends LuaControl {
   /**
    * The display resolution for this player.
    *
+   * **Note**: During {@link OnPlayerCreatedEvent on_player_created}, this attribute will always return a resolution of
+   * `{width=1920, height=1080}`. To get the actual resolution, listen to the
+   * {@link OnPlayerDisplayResolutionChangedEvent on_player_display_resolution_changed} event raised shortly afterwards.
+   *
    * {@link https://lua-api.factorio.com/next/LuaPlayer.html#LuaPlayer.display_resolution View documentation}
    */
   readonly display_resolution: DisplayResolution
   /**
    * The display scale for this player.
    *
+   * **Note**: During {@link OnPlayerCreatedEvent on_player_created}, this attribute will always return a scale of `1`.
+   * To get the actual scale, listen to the {@link OnPlayerDisplayScaleChangedEvent on_player_display_scale_changed}
+   * event raised shortly afterwards.
+   *
    * {@link https://lua-api.factorio.com/next/LuaPlayer.html#LuaPlayer.display_scale View documentation}
    */
   readonly display_scale: double
@@ -17364,7 +17374,7 @@ interface ResourceSurfaceCreateEntity extends BaseSurfaceCreateEntity {
 
 interface UndergroundBeltSurfaceCreateEntity extends BaseSurfaceCreateEntity {
   /** `"output"` or `"input"`; default is `"input"`. */
-  readonly type?: "output" | "input" | "input"
+  readonly type?: "output" | "input"
 }
 
 interface ProgrammableSpeakerSurfaceCreateEntity extends BaseSurfaceCreateEntity {