typed-factorio 2.5.2 → 2.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -21
- package/README.md +38 -23
- package/common/serpent.d.ts +8 -7
- package/common/types.d.ts +28 -0
- package/package.json +17 -16
- package/prototype/generated/prototypes.d.ts +1920 -1908
- package/prototype/generated/types.d.ts +1606 -1437
- package/runtime/generated/builtin-types.d.ts +12 -12
- package/runtime/generated/classes.d.ts +3432 -3346
- package/runtime/generated/concepts.d.ts +399 -326
- package/runtime/generated/defines.d.ts +120 -120
- package/runtime/generated/events.d.ts +185 -185
- package/runtime/generated/global-functions.d.ts +3 -3
- package/runtime/generated/global-objects.d.ts +6 -6
package/LICENSE
CHANGED
@@ -1,21 +1,21 @@
|
|
1
|
-
MIT License
|
2
|
-
|
3
|
-
Copyright (c) 2021 Benjamin Ye
|
4
|
-
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
7
|
-
in the Software without restriction, including without limitation the rights
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
10
|
-
furnished to do so, subject to the following conditions:
|
11
|
-
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
13
|
-
copies or substantial portions of the Software.
|
14
|
-
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
21
|
-
SOFTWARE.
|
1
|
+
MIT License
|
2
|
+
|
3
|
+
Copyright (c) 2021 Benjamin Ye
|
4
|
+
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
7
|
+
in the Software without restriction, including without limitation the rights
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
10
|
+
furnished to do so, subject to the following conditions:
|
11
|
+
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
13
|
+
copies or substantial portions of the Software.
|
14
|
+
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
@@ -1,8 +1,8 @@
|
|
1
1
|
# Typed Factorio
|
2
2
|
|
3
|
-
Complete and featureful typescript definitions for the Factorio modding lua
|
3
|
+
Complete and featureful typescript definitions for the Factorio modding lua API, for use with [TypescriptToLua](https://typescripttolua.github.io/).
|
4
4
|
|
5
|
-
This project aims to provide type definitions
|
5
|
+
This project aims to provide type definitions are as complete as possible.
|
6
6
|
The generator uses both the Factorio api docs JSON and manually defined additions.
|
7
7
|
|
8
8
|
## Installation
|
@@ -10,14 +10,15 @@ The generator uses both the Factorio api docs JSON and manually defined addition
|
|
10
10
|
To use in your [TypescriptToLua](https://typescripttolua.github.io/) project:
|
11
11
|
|
12
12
|
1. Install this package: `npm install typed-factorio`
|
13
|
-
- Note: When types are updated for a new factorio version, you will need to
|
13
|
+
- Note: When types are updated for a new factorio version, you will need to update this package.
|
14
14
|
|
15
|
-
2. Add
|
15
|
+
2. Add types for the [stages](https://lua-api.factorio.com/1.1.89/index.html) used to `tsconfig.json > compilerOptions > types`.
|
16
16
|
The available stages are `"typed-factorio/settings"`, `"typed-factorio/prototype"`, and `"typed-factorio/runtime"`.
|
17
17
|
|
18
18
|
Example:
|
19
19
|
|
20
20
|
```diff
|
21
|
+
// in tsconfig.json
|
21
22
|
{
|
22
23
|
"compilerOptions": {
|
23
24
|
+ "types": [ "typed-factorio/runtime" ]
|
@@ -25,14 +26,14 @@ Example:
|
|
25
26
|
}
|
26
27
|
```
|
27
28
|
|
28
|
-
The stages
|
29
|
-
|
29
|
+
The stages used will select the global variables defined.
|
30
|
+
You can include multiple stages, but there are some caveats. See [Using multiple stages in the same project](#using-multiple-stages-in-the-same-project) for more info.
|
30
31
|
|
31
|
-
## Usage
|
32
|
+
## Usage notes
|
32
33
|
|
33
|
-
|
34
|
+
Here are some notes on using the types:
|
34
35
|
|
35
|
-
### Types
|
36
|
+
### Types for other stages
|
36
37
|
|
37
38
|
No matter which stage(s) are selected, _type_ definitions for all stages are available in the modules `"factorio:settings"`, `"factorio:prototype"`, and `"factorio:runtime"`:
|
38
39
|
```ts
|
@@ -41,7 +42,9 @@ import { ItemPrototype } from "factorio:prototype"
|
|
41
42
|
import { LuaEntity } from "factorio:runtime"
|
42
43
|
```
|
43
44
|
|
44
|
-
|
45
|
+
You can also include just `"typed-factorio"` in your `types` field. This will include only global variables available to _all_ stages.
|
46
|
+
|
47
|
+
### `data.extend()` types
|
45
48
|
In the settings and prototype stages, the `data` global variable is available.
|
46
49
|
|
47
50
|
For [performance reasons](https://github.com/microsoft/TypeScript/wiki/Performance#preferring-base-types-over-unions), `data.extend()` is by default loosely typed.
|
@@ -98,37 +101,33 @@ If you wish to see types for more lualib modules, feel free to open an issue or
|
|
98
101
|
|
99
102
|
### The `global` table
|
100
103
|
|
101
|
-
The `global` table (in the runtime stage) can have any shape, so it is not defined here. Instead, you can:
|
104
|
+
The `global` table (in the runtime stage) can have any shape, so it is not defined here. Instead, you can define it yourself:
|
102
105
|
|
103
|
-
-
|
104
|
-
-
|
106
|
+
- Add `declare const global: <Your type>` in a `.d.ts` file included in your project, to apply it project-wide.
|
107
|
+
- Add `declare const global: {...}` to each file where needed. This way, you can define only properties that each file specifically uses.
|
105
108
|
|
106
109
|
## Using multiple stages in the same project
|
107
110
|
|
108
111
|
Every Factorio loading stage declares different global variables.
|
109
|
-
To add types for multiple Factorio stages, you have a few options
|
112
|
+
To add types for multiple Factorio stages, you have a few options:
|
110
113
|
|
111
114
|
1. Add multiple stages to the "types" field, e.g. `"types": ["typed-factorio/prototype", "typed-factorio/runtime"]`. This will define global variables for _all_ stages selected. With this option, take care that you only use global variables available in the stages the code is run.
|
112
|
-
2. Add _only_ the runtime stage
|
115
|
+
2. Add _only_ the runtime stage, then manually declare other global variables in files that use them. There are types in `"factorio:common"` to allow this:
|
113
116
|
```ts
|
114
117
|
// -- For the prototype stage --
|
115
118
|
import { PrototypeData, ActiveMods } from "factorio:common"
|
116
|
-
declare const data:
|
119
|
+
declare const data: PrototypeData
|
117
120
|
declare const mods: ActiveMods
|
118
121
|
// The `settings` global variable is already declared in the runtime stage.
|
119
|
-
// However, in the prototype stage _only_ startup
|
122
|
+
// However, in the prototype stage _only_ `settings.startup` are available.
|
120
123
|
```
|
121
124
|
```ts
|
122
125
|
// -- For the settings stage --
|
123
126
|
import { SettingsData, ActiveMods } from "factorio:common"
|
124
|
-
declare const
|
127
|
+
declare const data: SettingsData
|
125
128
|
declare const mods: ActiveMods
|
126
129
|
```
|
127
|
-
3. Use a separate `tsconfig.json` for each stage. In each `tsconfig.json`,
|
128
|
-
|
129
|
-
### Additional notes
|
130
|
-
|
131
|
-
You can also include just `"typed-factorio"` in your `types` field. This will include only global variables available to _all_ stages.
|
130
|
+
3. Use a separate `tsconfig.json` for each stage. In each `tsconfig.json`, add only files in that stage to the `"include"` field, e.g. `include: ["src/control.ts"]` for the runtime stage. However, this means you need to run `tstl` separately for each stage, and files shared by multiple stages will be compiled multiple times.
|
132
131
|
|
133
132
|
## Type features
|
134
133
|
|
@@ -149,6 +148,22 @@ Event IDs (`defines.events`) hold type info for their corresponding event type a
|
|
149
148
|
|
150
149
|
You can pass an event data type parameter to `script.generate_event_name<T>()`, and it will return a `CustomEventId` that includes type info.
|
151
150
|
|
151
|
+
### Optional custominput name checking
|
152
|
+
You can optionally enable type-checking for custom input names (for `script.on_event` and `CustomInputPrototype`).
|
153
|
+
To do so, specify names by extending the CustomInputNames interface like so:
|
154
|
+
|
155
|
+
```ts
|
156
|
+
declare module "factorio:common" {
|
157
|
+
export interface CustomInputNames {
|
158
|
+
"my-custom-input": any
|
159
|
+
}
|
160
|
+
}
|
161
|
+
|
162
|
+
script.on_event("my-custom-input", ()=>{}) // type-checked
|
163
|
+
```
|
164
|
+
|
165
|
+
If not specified, `CustomInputName` defaults to just `string`.
|
166
|
+
|
152
167
|
### Array-like classes
|
153
168
|
|
154
169
|
Classes that have an index operator, a length operator, and have an array-like structure subclass from `(Readonly)Array`. These are `LuaInventory`, `LuaFluidBox`, `LuaTransportLine`.
|
package/common/serpent.d.ts
CHANGED
@@ -1,15 +1,16 @@
|
|
1
1
|
// from https://lua-api.factorio.com/latest/Libraries.html
|
2
|
-
// last updated for 1.1.35, 1.1.36, 1.1.37
|
3
2
|
|
4
3
|
/** @noSelfInFile */
|
5
4
|
|
6
5
|
/**
|
7
|
-
* Factorio provides the {@link https://github.com/pkulchenko/serpent serpent library} as a global variable
|
8
|
-
* all mods to use.
|
9
|
-
*
|
10
|
-
*
|
11
|
-
*
|
12
|
-
*
|
6
|
+
* Factorio provides the {@link https://github.com/pkulchenko/serpent serpent library} as a global variable named
|
7
|
+
* `serpent` for all mods to use. Its purpose is to allow for easy printing of Lua tables (using `serpent.block()` for
|
8
|
+
* example), which can be useful when debugging. It can't pretty-print LuaObjects such as {@link LuaEntity} however.
|
9
|
+
*
|
10
|
+
* The serpent library was modified for determinism, e.g. comments are turned off by default to avoid returning table
|
11
|
+
* addresses. Furthermore, two options were added: `refcomment` (true/false/maxlevel) and `tablecomment`
|
12
|
+
* (true/false/maxlevel), which allow to separately control the self-reference and table value output of the comment
|
13
|
+
* option.
|
13
14
|
*/
|
14
15
|
declare namespace serpent {
|
15
16
|
/** @noSelf */
|
package/common/types.d.ts
CHANGED
@@ -71,4 +71,32 @@ declare module "factorio:common" {
|
|
71
71
|
* ```
|
72
72
|
*/
|
73
73
|
export type SettingsData = DataGlobal<SettingsPrototypeMap>
|
74
|
+
|
75
|
+
/**
|
76
|
+
* You can optionally extend this interface to provide type checking and autocompletion for custom input names, like so:
|
77
|
+
* ```ts
|
78
|
+
* declare module "factorio:common" {
|
79
|
+
* export interface CustomInputNames {
|
80
|
+
* "my-custom-event": true
|
81
|
+
* }
|
82
|
+
* }
|
83
|
+
*
|
84
|
+
* // this enables type checking for the following:
|
85
|
+
* script.on_event("my-custom-event", ...)
|
86
|
+
*
|
87
|
+
* data.extend<CustomInputPrototype>([{
|
88
|
+
* type: "custom-input",
|
89
|
+
* name: "my-custom-event", // type checked
|
90
|
+
* }])
|
91
|
+
* ```
|
92
|
+
* @see CustomInputName
|
93
|
+
*/
|
94
|
+
export interface CustomInputNames {}
|
95
|
+
|
96
|
+
/**
|
97
|
+
* All custom event names. See {@link CustomInputNames}.
|
98
|
+
*
|
99
|
+
* If none are specified, this is just `string`.
|
100
|
+
*/
|
101
|
+
export type CustomInputName = [keyof CustomInputNames] extends [never] ? string : keyof CustomInputNames
|
74
102
|
}
|
package/package.json
CHANGED
@@ -1,6 +1,6 @@
|
|
1
1
|
{
|
2
2
|
"name": "typed-factorio",
|
3
|
-
"version": "2.
|
3
|
+
"version": "2.6.0",
|
4
4
|
"description": "Featureful typescript definitions for the Factorio modding api.",
|
5
5
|
"keywords": [
|
6
6
|
"factorio",
|
@@ -9,6 +9,7 @@
|
|
9
9
|
"tstl"
|
10
10
|
],
|
11
11
|
"repository": "https://github.com/GlassBricks/typed-factorio",
|
12
|
+
"homepage": "https://github.com/GlassBricks/typed-factorio#readme",
|
12
13
|
"license": "MIT",
|
13
14
|
"files": [
|
14
15
|
"**/*.d.ts",
|
@@ -16,7 +17,7 @@
|
|
16
17
|
"!generator/**/*"
|
17
18
|
],
|
18
19
|
"type": "module",
|
19
|
-
"
|
20
|
+
"packageManager": "npm@9.5.0",
|
20
21
|
"scripts": {
|
21
22
|
"generate": "ts-node --esm -P generator/tsconfig.json generator/main.ts",
|
22
23
|
"generate-no-format": "ts-node --swc -T --esm -P generator/tsconfig.json generator/main.ts --no-format",
|
@@ -34,25 +35,25 @@
|
|
34
35
|
"typescript-to-lua": "^1.10.0"
|
35
36
|
},
|
36
37
|
"devDependencies": {
|
37
|
-
"@swc/core": "^1.3.
|
38
|
-
"@types/download": "^8.0.
|
39
|
-
"@types/node": "^20.5
|
40
|
-
"@typescript-eslint/eslint-plugin": "^6.
|
41
|
-
"@typescript-eslint/parser": "^6.
|
38
|
+
"@swc/core": "^1.3.101",
|
39
|
+
"@types/download": "^8.0.5",
|
40
|
+
"@types/node": "^20.10.5",
|
41
|
+
"@typescript-eslint/eslint-plugin": "^6.16.0",
|
42
|
+
"@typescript-eslint/parser": "^6.16.0",
|
42
43
|
"chalk": "^5.3.0",
|
43
44
|
"download": "^8.0.0",
|
44
|
-
"eslint": "~8.
|
45
|
-
"eslint-config-prettier": "^9.
|
46
|
-
"eslint-import-resolver-typescript": "^3.6.
|
45
|
+
"eslint": "~8.56.0",
|
46
|
+
"eslint-config-prettier": "^9.1.0",
|
47
|
+
"eslint-import-resolver-typescript": "^3.6.1",
|
47
48
|
"eslint-plugin-eslint-comments": "^3.2.0",
|
48
|
-
"eslint-plugin-import": "^2.
|
49
|
+
"eslint-plugin-import": "^2.29.1",
|
49
50
|
"eslint-plugin-node": "^11.1.0",
|
50
|
-
"eslint-plugin-prettier": "^5.
|
51
|
+
"eslint-plugin-prettier": "^5.1.2",
|
51
52
|
"lua-types": "^2.13.1",
|
52
|
-
"prettier": "^3.
|
53
|
-
"rimraf": "^5.0.
|
54
|
-
"ts-node": "^10.9.
|
53
|
+
"prettier": "^3.1.1",
|
54
|
+
"rimraf": "^5.0.5",
|
55
|
+
"ts-node": "^10.9.2",
|
55
56
|
"typescript": "~5.2.2",
|
56
|
-
"typescript-to-lua": "^1.
|
57
|
+
"typescript-to-lua": "^1.22.0"
|
57
58
|
}
|
58
59
|
}
|