factorio-types 1.1.0 → 1.2.1

package/README.md

@@ -10,7 +10,7 @@ Intended to be used with [Typescript to Lua](https://github.com/TypeScriptToLua/
 
 ## Configuration
 
-This library includes [tsconfig.base.json](./tsconfig.base.json) in the root of the package with recommended configuration. This can be used as follows
+This library includes [tsconfig.base.json](https://github.com/sguest/factorio-types/blob/master/tsconfig.base.json) in the root of the package with recommended configuration. This can be used as follows
 
 `tsconfig.json`:
 
@@ -21,24 +21,96 @@ This library includes [tsconfig.base.json](./tsconfig.base.json) in the root of
 }
 ```
 
+## Stages
+
+Factorio mods and the api go through [three distinct stages](https://lua-api.factorio.com/latest/). Types are organized into namespaces `runtime`, `prototype`, and `settings` representing the types to be used in each stage. These types, and therefore their corresponding namespaces, are a compile-time-only feature as lua does not have types, however using a type from the wrong namespace during the wrong stage is likely to result in a runtime error as you will be attempting to access something Factorio does not let you access at that time.
+
+Note there is some overlap between the types for the Settings and Prototype phases since both regularly provide prototype data to `data.extend()`, and in fact the settings-phase prototypes extend `prototype.PrototypeBase`. However, you should only be providing types from the `settings` namespace during the settings phase, and from the `prototype` namespace during the prototype phase.
+
 ## Examples
 
 A very minimal proof-of-concept showing basic toolchain setup can be found [Here](https://github.com/sguest/factorio-fire-armor-typescript)
 
 A slightly more in-depth and realistic mode can be found [Here](https://github.com/sguest/basic-seablock)
 
-## Noise library
+## Primitives
 
-A note on using the `noise` library from within Factorio: Several mods (typically those that deal with terrain generation) will `require('noise')`. While this seems to work, this is not an officially documented part of the Factorio modding API and is not expressed in these types. If you want to use it, you'll want to add the following to your configuration
+Primitive types like `uint8` or `nil` are preserved from the docs to better represent expected data formats, and are aliased as typescript types, so `nil` is `null`, and the various numeric formats such as `uint8`, `float`, etc are aliases for `number`.
 
-`tsconfig.json`:
+Note that since typescript has a single `number` type, the compiler will **not** prevent things like passing a `float` to a method that expects `uint8` because these are both just `number` types under the hood.
+
+## Lualib
+
+Factorio makes various lua functions available to mods via [LuaLib](https://github.com/wube/factorio-data/tree/master/core/lualib)
+
+Unlike the main parts of the factorio API, these do not exist as ambient globals but instead must be imported
+
+```typescript
+import * as noise from "noise";
+let x = noise.var_get('x');
+```
+
+Also unlike the main factorio API, these types are not documented in a machine-readable way and therefore are not generated here along with the main API types. Instead, they are hand-written as needed and as a result are incomplete and more likely to be wrong. See the [existing declarations](https://github.com/sguest/factorio-types/tree/master/src/lualib).
+
+If there are types of lualib that you need but do not exist, either open an issue asking for it, or write the type definitions and open a pull request. If you would like to continue working with these types while they do not exist in `factorio-types`, you can add the import path to `tstl.noResolvePaths` in tsconfig.json, and then `require()` the paths, which will be typed as `any`.
+
+`tsconfig.json`
 
 ```json
 {
     "tstl": {
-        "noResolvePaths": ["noise"]
+        "noResolvePaths": ["math2d"]
     }
 }
 ```
 
-You can then optionally write your own custom type definitions for these types, or leave them as `any`
+`some-file.ts`
+
+```typescript
+const math2d = require('math2d');
+```
+
+### Noise
+
+The `noise` module has mostly-complete type definitions. A couple notes on usage due to the limitations of typescript
+
+The `noise.var` function is named `noise.var_get` since `var` is a reserved word in typscript. It will be emitted as `noise.var` thanks to a [@customName compiler annotation](https://typescripttolua.github.io/docs/advanced/compiler-annotations/#customname).
+
+typescript
+
+```ts
+import * as noise from "noise";
+let x = noise.var_get('x');
+```
+
+output lua
+
+```lua
+local noise = require("noise")
+local x = noise.var("x")
+```
+
+Noise values have operator overloads for common arithmetic operations, however Typescript does not support operator overloading. These are implemented as [Operator map types](https://typescripttolua.github.io/docs/advanced/language-extensions#operator-map-types) in the noise library, which will emit as regular operators in lua. Available operators are named following lua conventions for overloaded operators without the preceding double-underscore:
+
+- Addition: `noise.add`
+- Subraction: `noise.sub`
+- Multiplication: `noise.mul`
+- Division: `noise.div`
+- Unary Negation: `noise.unm`
+- Exponentiation: `noise.pow`
+
+typescript
+
+```ts
+let x = noise.var_get('x');
+let y = noise.var_get('y');
+let sum = noise.add(x, y);
+```
+
+Output lua
+
+```lua
+local x = noise.var("x")
+local y = noise.var("y")
+local sum = x + y;
+```