You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This document outlines guides to get started on developing the starter kit.
4
+
5
+
## Contributing to the Wiki
6
+
7
+
We welcome contributions to the wiki! We're looking for ways to make the starter kit documentation better, as well as many other tips and guides about TypeScript in general.
8
+
9
+
## The Five Golden Rules
10
+
11
+
The simple steps of contributing to any GitHub project are as follows:
12
+
13
+
1.[Fork the repository](https://github.com/screepers/screeps-typescript-starter/fork)
14
+
2. Create your feature branch: `git checkout -b my-new-feature`
15
+
3. Commit your changes: `git commit -am 'Add some feature'`
16
+
4. Push to the branch: `git push -u origin my-new-feature`
17
+
5. Create a [Pull Request](https://github.com/screepers/screeps-typescript-starter/pulls)!
18
+
19
+
To keep your fork of in sync with this repository, [follow this guide](https://help.github.com/articles/syncing-a-fork/).
20
+
21
+
## Submitting a Pull Request
22
+
23
+
We accept almost all pull requests, as long as the following criterias are met:
24
+
25
+
* Your code must pass all of the linter checks (`npm run lint && npm run lint-webpack`)
26
+
* When adding a new feature, make sure it doesn't increase the complexity of the tooling. We want this starter kit to be approachable to folks who have little to no knowledge of TypeScript, or even JavaScript.
27
+
* When making changes that are potentially breaking, careful discussion must be done with the community at large. Generally we do this either on the [#typescript](https://screeps.slack.com/messages/typecript/) channel on the Screeps Slack, or on the corresponding pull request discussion thread.
@@ -9,14 +9,22 @@ It is based on [the original starter kit](https://github.com/MarkoSulamagi/Scree
9
9
10
10
[Download the latest zipped copy here.](https://github.com/screepers/screeps-typescript-starter/archive/master.zip)
11
11
12
-
## Table of Contents
12
+
## What's new
13
+
14
+
*[@bonzaiferroni](https://github.com/bonzaiferroni) has put out some really useful guides to get started with TypeScript development on Screeps Go read them!([Guide #1](https://screepsworld.com/2017/07/typescreeps-getting-started-with-ts-in-screeps/), [Guide #2](https://screepsworld.com/2017/07/typescreeps-installing-everything-you-need/))
15
+
* We've consolidated all of our guides into the [wiki page](https://github.com/screepers/screeps-typescript-starter/wiki). This README will be simplified to include the essentials to get you up and running. Feel free to contribute to the wiki as well!
16
+
17
+
---
18
+
19
+
## Table of contents
13
20
14
21
*[Features](#features)
15
-
*[Quick Start](#quick-start)
16
-
*[Configuration](#configuration)
17
-
*[Testing](#testing)
18
-
*[Notes](#notes)
22
+
*[Quick start](#quick-start)
23
+
*[Initial configuration](#initial-configuration)
24
+
*[Running the compiler](#running-the-compiler)
25
+
*[Further reading](#further-reading)
19
26
*[Contributing](#contributing)
27
+
*[Special thanks](#special-thanks)
20
28
21
29
## Features
22
30
@@ -30,26 +38,22 @@ It is based on [the original starter kit](https://github.com/MarkoSulamagi/Scree
30
38
- "Snippets" directory for code you want to save, but don't want compiled or linted
31
39
- Modest starter code to get you started, but not hold your hand
32
40
41
+
## Quick start
33
42
34
-
## Quick Start
43
+
By far, the easiest and quickest way to get started with TypeScript development on Screeps is to follow @bonzaiferroni's guides on Screeps World. Go read them!
35
44
36
-
**NEW!** Check out [this awesome guide](https://screepsworld.com/2017/07/typescreeps-installing-everything-you-need/) by @bonzaiferroni on Screeps World to easily get started with writing TypeScript code on Screeps.
*[Yarn](https://yarnpkg.com/en/) - Optional. You can use `npm` if you don't want to, but this is for your own sanity.
43
55
44
-
For testing **NOTE**_Testing is currently a work-in-progress_:
45
-
46
-
*[Mocha](https://mochajs.org/) test runner and [NYC](https://istanbul.js.org/) for code coverage - `yarn global add nyc mocha`
47
-
48
-
### Download
49
-
50
-
To get started, [download a zipped copy](https://github.com/screepers/screeps-typescript-starter/archive/master.zip) of the starter kit and extract it somewhere, or clone this repo.
51
-
52
-
### Install all required modules!
56
+
### Installing the modules
53
57
54
58
Run the following the command to install the required packages and TypeScript declaration files if you are using yarn:
55
59
@@ -62,11 +66,14 @@ or, for npm:
62
66
```bash
63
67
$ npm install
64
68
```
65
-
### Configure Screeps credentials
69
+
70
+
## Initial configuration
71
+
72
+
### Configuring Screeps credentials
66
73
67
74
Create a copy of `config/credentials.example.json` and rename it to `config/credentials.json`.
68
75
69
-
**WARNING:DO NOT** commit this file into your repository!
76
+
**WARNING:** This file contains your secret credentials. **DO NOT** commit it into your repository!
In the newly created `credentials.json` file, change the `email` and `password` properties with your Screeps credentials. The `serverPassword`, `token`, and `gzip` options are only for private servers that support them. If you are uploading to the public Screeps server, you should delete these fields from your credentials file.
77
84
78
-
See [Configuration](#configuration) for more in-depth info on configuration options.
79
-
80
-
### Run the compiler
81
-
82
-
```bash
83
-
# To compile and upload your TypeScript files on the fly in "watch mode":
84
-
$ npm start
85
-
86
-
# To compile and deploy once:
87
-
$ npm run deploy
88
-
```
89
-
90
-
91
-
## Configuration
92
-
93
-
This project is configured in two places. `config/` is for deployment configuration, and contains your screeps login credentials along with other options.
94
-
`src/config/` contains a file you can use to configure your runtime Screeps code.
95
-
96
-
### Runtime config
97
-
98
-
You can use the configuration variables in `src/config` by importing the file:
99
-
100
-
```js
101
-
import*asConfigfrom"../path/to/config";
102
-
```
103
-
104
-
... and simply calling the config variables with `Config.CONFIG_VARIABLE` in your code.
105
-
106
-
This file mostly serves as an example for making configurable code. We've included some built-in config variables that you might want to take a look at:
107
-
108
-
```js
109
-
// You can enable/disable the Screeps Profiler here. This will reduce your CPU usage.
110
-
exportconst USE_PROFILER:boolean=true;
111
-
112
-
// Set these to false to remove sourcemaps from the output logs, which will also reduce CPU usage.
113
-
exportconst LOG_PRINT_LINES:boolean=true;
114
-
exportconst LOG_LOAD_SOURCE_MAP:boolean=true;
115
-
```
116
-
117
-
_**NOTE**: You may want to consider adding this file to `.gitignore` if you end up storing confidential information there._
118
-
119
-
### Deployment / Compiling configuration
120
-
121
-
The files under `config/`, as well as `webpack.config.ts` are where deployment configuration options are set.
122
-
123
-
It's helpful to remember that the config is just a javascript object, and can be passed around and modifide using [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain).
124
-
125
-
126
-
#### Environment:
127
-
128
-
`webpack.config.ts` is for setting environment variables defaults throughout the rest of the config.
129
-
You can use these variables to pass options to the rest of the config through the command line.
130
-
For example:
131
-
132
-
```bash
133
-
# (npm requires arguments be seperated by a double dash)
134
-
$ npm run build -- --env.TEST=true
135
-
```
136
-
Will set the member `TEST` to `true` on the options object.
137
-
138
-
Remember, the config code is just a typescript function that return a config object, so you can hypothetically configure it wherever and however is most convenient.
Inside `config.common.ts` is where the majority of the webpack configuration happens.
143
-
144
-
Of particular interest is the Plugins section where `DefinePlugin` is configured (look for the line about half-way down statring with `config.plugin("define")`).
145
-
146
-
Variables set in the object here will be replaced in the actual output JS code.
147
-
When compiling your code, webpack will perform a search and replace, replacing the variable names with the output of the supplied expression or value.
148
-
149
-
Because these values are evaluated once as a string (for the find-and-replace), and once as an expression, they either need to be wrapped in `JSON.stringify` or double quoted (ex. `VARIABLE: '"value-in-double-quotes"'`).
150
-
151
-
Webpack can do a lot with these variables and dead code elimination.
152
-
153
-
*__Caveats__: you need to let typescript know about these variables by declaring them in a type definitions (`.d.ts`) file.
154
-
Also be careful not to use too common of a name, because it will replace it throughout your code without warning.
155
-
A good standard is to make the variables all caps, and surrounded by double underscores, so they stand out (ex: `__REVISION__`).*
156
-
157
-
#### Additional Options
158
-
159
-
`config.common.ts` is for config options common to all environments. Other environments can inherit from this file, and add to, or override options on the config object.
160
-
161
-
`config.dev.ts` is a specific environment configuration. You can potentially have as many environments as you make files for. To specify which environment to use, append `--env.ENV=` and the environment name to any commands. An example is provided in `package.json`.
162
-
163
-
`config.local.ts` is an example configuration for local deploys. If you want to deploy to a local server for testing, just edit the path in the file and run with `npm run local` or `npm run watch-local`.
164
-
165
-
Common options you may wish to configure:
166
-
167
-
`output.path`: This is the output path for the compiled js. If you are running a local server, you may consider adding an environment that outputs directly to the screeps local folder. This is equivalent to the `localPath` setting in older versions of the screeps-typescript-starter.
168
-
169
-
`watchOptions.ignored`: This option is only to save computer resources, since watch-mode (`npm start`) can be CPU intensive. You can exclude directories you know don't need to be watched.
85
+
### Changing the upload branch
170
86
171
-
`module.rules`: These are the individual rules webpack uses to process your code. The defaults are generally all you will need. The most useful change you may want to make here is to explicity `exclude` files or directories from being compiled or linted (in case of 3rd party code, for example). These values, like all others can be passed around and modified before webpack acts on them.
172
-
173
-
#### Change the upload branch
174
-
175
-
You code is uploaded to the branch configured by the `branch` property on the object sent to `new ScreepsWebpackPlugin` (see `config/config.dev.ts`). You have three ways to customize this:
176
-
177
-
1. Multiple config environment files, each with a seperate branch
178
-
2. Use the special variables `'$activeWorld'` to upload to whatever brach is active in the Screeps world
179
-
3. Configure a new environment variable in `webpack.config.ts` and use that in your code. For example:
The above example will automatically set your upload branch to be the same as your active git branch. This is functionally equivalent to the option `"autobranch": true` in older versions.
194
-
195
-
You still have to create matching branch in screeps client by cloning an existing branch (API limitation). This is useful when setting up deployment pipelines that upload on commit after successful build (so a commit to `major_refactoring` branch doesn't overwrite your default branch in the middle of epic alliance action just because you forgot to update a pipeline configuration).
196
-
197
-
198
-
## Testing
199
-
200
-
### Running Tests
201
-
202
-
**WARNING**_Testing functionality is currently not finished in the 2.0 build of the Starter._
203
-
204
-
To enable tests as part of the build and deploy process, flip the `test` flag in your `config.json` to `true`.
205
-
206
-
You can always run tests by running `npm test`. You can get a code coverage report by running
207
-
`npm test:coverage`. Then opening `coverage/index.html` in your browser.
208
-
209
-
### Writing Tests
210
-
211
-
All tests should go in the `test/` directory and end in the extension `.test.ts`.
212
-
213
-
All constants are available globally as normal.
214
-
215
-
The game state is no simulated, so you must mock all game objects and state that your code requires.
216
-
As part of this project, we hope to provide some helpers for generating game objects.
217
-
218
-
It is recommended to test the smallest pieces of your code at a time. That is, write tests that
219
-
assert the behavior of single, small functions. The advantages of this are:
220
-
221
-
1. less mocking to setup and maintain
222
-
2. allows you to test behavior, not implementation
223
-
224
-
See [test/components/creeps/creepActions.test.ts](test/components/creeps/creepActions.test.ts) as
225
-
an example on how to write a test, including the latest game object mocking support.
226
-
227
-
For writing assertions we provide [chai](http://chaijs.com). Check out their
228
-
[documentation](http://chaijs.com/guide/styles/) to learn how to write assertions in your tests.
229
-
230
-
**Important:** In your tests, if you want to use lodash you must import it explicitly to avoid errors:
231
-
232
-
```js
233
-
import*as_from"lodash"
91
+
credentials.branch="dev";
234
92
```
235
93
236
-
## Notes
237
-
238
-
### Sample code
239
-
240
-
This starter kit includes a bit of sample code, which uses some of the new TS2 features mentioned earlier. Feel free to build upon this as you please, but if you don't want to use them, you can remove everything from within the `src/` directory and start from scratch.
94
+
Change the `credentials.branch` property you want to initially build and upload to, e.g. `"default"`. Note that due to the Screeps API limitations, you still have to create a branch with a matching name in the Screeps client by cloning an existing branch. The compiler will yell at you when you forgot to do so.
241
95
242
-
When starting from scratch, make sure a `main.ts` file exists with a `loop()` function. This is necessary in order to run the game loop.
See [Configuration page](https://github.com/screepers/screeps-typescript-starter/wiki/Configuration) on the screeps-typescript-starter wiki for more in-depth info on configuration options.
245
99
246
-
### `--strict` mode
100
+
##Running the compiler
247
101
248
-
The `--strict` mode was introduced in TypeScript 2.3 which sets all strict type-checking options to `true` by default. The options affected under the `--strict` mode are as follows (and may in the future include more options):
249
-
250
-
*`--strictNullChecks`
251
-
*`--noImplicitAny`
252
-
*`--noImplicitThis`
253
-
*`--alwaysStrict`
254
-
255
-
Starting from version 2.0 of the starter kit, the `tsconfig.json` file will include a `"strict": true` setting in the `"compilerOptions"` section, to conform with the TS 2.3 defaults. If this gives you compile errors, you can try setting `"strict"` to `false`, or by overriding one or more of the options listed above.
256
-
257
-
**For more info:**https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-3.html#new---strict-master-option
258
-
259
-
260
-
### TSLint
261
-
262
-
TSLint checks your TypeScript code for readability, maintainability, and functionality errors, and can also enforce coding style standards.
263
-
264
-
After each successful compiling of the project, TSLint will parse the TypeScript source files and display a warning for any issues it will find.
265
-
266
-
You can change the file paths checked automatically by editing the paths in the `tslint` section of `config.json`.
267
-
268
-
This project provides TSLint rules through a `tslint.json` file, which extends the recommended set of rules from TSLint github repository: https://github.com/palantir/tslint/blob/next/src/configs/recommended.ts
269
-
270
-
We made some changes to those rules, which we considered necessary and/or relevant to a proper Screeps project:
271
-
272
-
- set the [forin](http://palantir.github.io/tslint/rules/forin/) rule to `false`, it was forcing `for ( ... in ...)` loops to check if object members were not coming from the class prototype.
273
-
- set the [interface-name](http://palantir.github.io/tslint/rules/interface-name/) rule to `false`, in order to allow interfaces that are not prefixed with `I`.
274
-
- set the [no-console](http://palantir.github.io/tslint/rules/no-console/) rule to `false`, in order to allow using `console`.
275
-
- in the [variable-name](http://palantir.github.io/tslint/rules/variable-name/) rule, added `allow-leading-underscore`.
276
-
277
-
If you believe that some rules should not apply to a part of your code, you can use flags to let TSLint know about it: https://palantir.github.io/tslint/usage/rule-flags/
278
-
279
-
**More info about TSLint:**https://palantir.github.io/tslint/
280
-
281
-
### Sample library: logger
282
-
283
-
We've also included a sample library for detailed logging, with support for log levels and sourcemaps. If your code is committed to a source control (like GitHub or GitLab) it can also generate a link back to your repository with the appropriate line marked. Code has to be committed at build time and pushed to remote at run time for this to work correctly.
The logger works out of the box, uses default values from your runtime config (`src/config/config.ts`) and stores it to your memory. You can also change these configs directly from the Screeps console, for example:
102
+
```bash
103
+
# To compile and upload your TypeScript files on the fly in "watch mode":
104
+
$ npm start
288
105
289
-
```js
290
-
// print errors only, hide ticks and source locations
291
-
log.level=1;
292
-
log.showSource=false;
293
-
log.showTick=false;
106
+
# To compile and deploy once:
107
+
$ npm run deploy
294
108
```
295
109
110
+
## Further reading
296
111
297
-
**Note:** At the moment, the source maps feature doesn't work in Simulation mode, since Simulation mode does a lot of evals with scripts.
298
-
299
-
**Note:** As a side effect of changing the project to webpack, the built-in URL template is no longer automatically configured. Currently it is hardcoded to work with GitHub and GitLab. If you use Bitbucket, replace `LOG_VSC_URL_TEMPLATE` on your `config.ts` with this:
(Thanks to crzytrane on Slack for this code sample!)
112
+
To find out more about what else you can do with screeps-typescript-starter, head over to the [screeps-typescript-starter wiki](https://github.com/screepers/screeps-typescript-starter/wiki) to find more guides, tips and tricks.
0 commit comments