diff --git a/docs/.gitbook/assets/authenticating-1.png b/docs/.gitbook/assets/authenticating-1.png new file mode 100644 index 0000000..9c18b26 Binary files /dev/null and b/docs/.gitbook/assets/authenticating-1.png differ diff --git a/docs/.gitbook/assets/authenticating-2.png b/docs/.gitbook/assets/authenticating-2.png new file mode 100644 index 0000000..a47e05a Binary files /dev/null and b/docs/.gitbook/assets/authenticating-2.png differ diff --git a/docs/.gitbook/assets/authenticating-3.png b/docs/.gitbook/assets/authenticating-3.png new file mode 100644 index 0000000..1bacad9 Binary files /dev/null and b/docs/.gitbook/assets/authenticating-3.png differ diff --git a/docs/.gitbook/assets/authenticating-4.png b/docs/.gitbook/assets/authenticating-4.png new file mode 100644 index 0000000..dda8c2e Binary files /dev/null and b/docs/.gitbook/assets/authenticating-4.png differ diff --git a/docs/.gitbook/assets/deploying-2.png b/docs/.gitbook/assets/deploying-2.png new file mode 100644 index 0000000..5d62597 Binary files /dev/null and b/docs/.gitbook/assets/deploying-2.png differ diff --git a/docs/README.md b/docs/README.md index 11d6511..5249edd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,10 +1,10 @@ -# Screeps Typescript Starter +# Introduction Screeps Typescript Starter is a starting point for a Screeps AI written in [Typescript](http://www.typescriptlang.org/). It provides everything you need to start writing your AI whilst leaving `main.ts` as empty as possible. [View on GitHub](https://github.com/screepers/screeps-typescript-starter) -## What's new (v3.0) +## What's new \(v3.0\) ### Simpler setup! @@ -14,7 +14,7 @@ The new version does away with all this and only provides only the code and tool ### Rollup! -We have swapped the bundler from Webpack to [Rollup](https://rollupjs.org/). Rollup is easier to configure and can be set up to do everything needed for Screeps. It also comes with various improvements over Webpack, which you can learn more about [here](./in-depth/module-bundling.md). +We have swapped the bundler from Webpack to [Rollup](https://rollupjs.org/). Rollup is easier to configure and can be set up to do everything needed for Screeps. It also comes with various improvements over Webpack, which you can learn more about [here](in-depth/module-bundling.md). ### Better docs! @@ -30,4 +30,5 @@ Download the latest source [here](https://github.com/screepers/screeps-typescrip git clone https://github.com/screepers/screeps-typescript-starter.git ``` -Extract it to a folder, and [let's get started](./getting-started/installation.md)! +Extract it to a folder, and [let's get started](getting-started/installation.md)! + diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 125c8f0..cc2830b 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,26 +1,22 @@ -# Summary +# Table of contents * [Introduction](README.md) ---- +## Getting Started -### Getting Started +* [Installation](getting-started/installation.md) +* [Authenticating with Screeps](getting-started/authenticating.md) +* [Deploying](getting-started/deploying.md) -* [Installation](./getting-started/installation.md) -* [Authenticating with Screeps](./getting-started/authenticating.md) -* [Deploying](./getting-started/deploying.md) +## In-Depth -### In-Depth +* [Module bundling](in-depth/module-bundling.md) +* [Deploy destinations](in-depth/deploy-destinations.md) +* [TypeScript](in-depth/typescript.md) +* [Prettier](in-depth/prettier.md) +* [Cookbook](in-depth/cookbook/README.md) + * [Environment variables](in-depth/cookbook/environment-variables.md) + * [One-line PowerShell setup](in-depth/cookbook/one-line-powershell.md) +* [Troubleshooting](in-depth/troubleshooting.md) +* [Contributing to the docs](in-depth/contributing.md) -* [Module bundling](./in-depth/module-bundling.md) -* [Deploy destinations](./in-depth/deploy-destinations.md) -* [TypeScript](./in-depth/typescript.md) -* [Prettier](./in-depth/prettier.md) -* [Cookbook](./in-depth/cookbook.md) - * [Environment variables](./in-depth/cookbook/environment-variables.md) - * [One-line PowerShell setup](./in-depth/cookbook/one-line-powershell.md) - ---- - -* [Troubleshooting](./troubleshooting.md) -* [Contributing to the docs](./contributing.md) diff --git a/docs/getting-started/authenticating.md b/docs/getting-started/authenticating.md index 42f2242..ad4fe7b 100644 --- a/docs/getting-started/authenticating.md +++ b/docs/getting-started/authenticating.md @@ -12,7 +12,7 @@ If you have an existing copy of your starter kit, follow these steps: ## Seting up Screeps authentication -The authentication token is pulled by the starter kit from a file named `screeps.json`. A sample config file (`screeps.sample.json`) is provided within the project, to use it, simply make a copy and rename it to `screeps.json`. +The authentication token is pulled by the starter kit from a file named `screeps.json`. A sample config file \(`screeps.sample.json`\) is provided within the project, to use it, simply make a copy and rename it to `screeps.json`. ```bash cp screeps.sample.json screeps.json @@ -22,23 +22,23 @@ cp screeps.sample.json screeps.json ## Generating an auth token -To generate an authentication token, click **[your username] > Manage account**. You should see the **Auth tokens** in the options now, click it. +To generate an authentication token, click **\[your username\] > Manage account**. You should see the **Auth tokens** in the options now, click it. -![authenticating-1](img/authenticating-1.png) +![authenticating-1](../.gitbook/assets/authenticating-1.png) On the next screen, we'll create a full access token. We pick the **Full access** option, then click the **Generate Token** button. -![authenticating-2](img/authenticating-2.png) +![authenticating-2](../.gitbook/assets/authenticating-2.png) Your generated token should now be shown on your screen. Copy it to your clipboard. -![authenticating-3](img/authenticating-3.png) +![authenticating-3](../.gitbook/assets/authenticating-3.png) > **Note:** This token will be displayed **only once**! Make sure to never lose it. However, if you did lose it, simply remove said token from your account, and create a new one. Now, paste it to your `screeps.json` file. -![authenticating-4](img/authenticating-4.png) +![authenticating-4](../.gitbook/assets/authenticating-4.png) ## Sanity check @@ -52,4 +52,5 @@ Now go to your Screeps client and check if the `main` branch is created, or if s It works? Good, you've successfully authenticated! -Next up, we'll configure our environment and [run our first code deploy](./deploying.md). +Next up, we'll configure our environment and [run our first code deploy](deploying.md). + diff --git a/docs/getting-started/deploying.md b/docs/getting-started/deploying.md index 073cd49..cfb5870 100644 --- a/docs/getting-started/deploying.md +++ b/docs/getting-started/deploying.md @@ -6,7 +6,7 @@ The starter kit builds your code using `rollup`, which uses a `screeps.json` fil The `screeps.json` file is a JSON configuration file separated into multiple environments. We're going to focus on the `main` environment to get you started. If you'd like to deploy to a different branch, be sure to change the `branch` key to the branch you'd like to deploy to. -![authenticating-4](img/authenticating-4.png) +![authenticating-4](../.gitbook/assets/authenticating-4.png) > **Note:** You don't have to manually create the target branch in your Screeps client if it doesn't exist yet. `rollup-plugin-screeps` will do it for you. @@ -20,6 +20,7 @@ npm run push-main You're done! Now go to your Screeps client and make sure your code is deployed properly. -![deploying-2](img/deploying-2.png) +![deploying-2](../.gitbook/assets/deploying-2.png) Ready for something extra? [Read on.](../in-depth/module-bundling.md) + diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index ec9dbe6..dddfa04 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -4,9 +4,9 @@ You will need: - - [Node.JS](https://nodejs.org/en/download) (>= 8.0.0) - - A Package Manager ([Yarn](https://yarnpkg.com/en/docs/getting-started) or [npm](https://docs.npmjs.com/getting-started/installing-node)) - - Rollup CLI (Optional, install via `npm install -g rollup`) +* [Node.JS](https://nodejs.org/en/download) \(>= 8.0.0\) +* A Package Manager \([Yarn](https://yarnpkg.com/en/docs/getting-started) or [npm](https://docs.npmjs.com/getting-started/installing-node)\) +* Rollup CLI \(Optional, install via `npm install -g rollup`\) ## Installing `npm` modules @@ -20,4 +20,5 @@ npm install yarn ``` -Once that's all done, let's [authenticate with the Screeps server](./authenticating.md). +Once that's all done, let's [authenticate with the Screeps server](authenticating.md). + diff --git a/docs/contributing.md b/docs/in-depth/contributing.md similarity index 99% rename from docs/contributing.md rename to docs/in-depth/contributing.md index a2cfa8e..4836e04 100644 --- a/docs/contributing.md +++ b/docs/in-depth/contributing.md @@ -17,3 +17,4 @@ To run a local Gitbook server, run the following command on the project's root d ```bash gitbook serve ``` + diff --git a/docs/in-depth/cookbook.md b/docs/in-depth/cookbook/README.md similarity index 99% rename from docs/in-depth/cookbook.md rename to docs/in-depth/cookbook/README.md index 6dc0b76..4d9dfe5 100644 --- a/docs/in-depth/cookbook.md +++ b/docs/in-depth/cookbook/README.md @@ -1,3 +1,4 @@ # Cookbook This section contains a community-maintained list of slightly more advanced tips and tricks to help better improve your Screeps AI development workflow with TypeScript. Feel free to [contribute your own](https://github.com/screepers/screeps-typescript-starter/tree/master/docs)! + diff --git a/docs/in-depth/cookbook/environment-variables.md b/docs/in-depth/cookbook/environment-variables.md index 8f69515..9342c5c 100644 --- a/docs/in-depth/cookbook/environment-variables.md +++ b/docs/in-depth/cookbook/environment-variables.md @@ -1,4 +1,4 @@ -# Managing deploys with environment variables +# Environment variables Environment variables provide a more streamlined way to manage your build process. We can also use it to define "build toggles", or environment-based variables that will be injected into your scripts to be used during runtime. @@ -6,7 +6,7 @@ Environment variables provide a more streamlined way to manage your build proces Let's say that we want to set `NODE_ENV` to `production` for uploading to our main branch, and `development` for uploading to our Simulation branch. First we'll catch the environment variable and assign the compile target based on it. -```js +```javascript // rollup.config.js const isProduction = process.env.NODE_ENV === 'production' @@ -31,7 +31,7 @@ export default { Then we'll change the build tasks on `package.json` to pass the environment variable before running the rollup command. -```json +```javascript { "tasks": { "deploy-prod": "NODE_ENV=production rollup -c", @@ -46,7 +46,7 @@ Then we'll change the build tasks on `package.json` to pass the environment vari npm install --save-dev cross-env ``` -```json +```javascript { "tasks": { "deploy-prod": "cross-env NODE_ENV=production rollup -c", @@ -59,7 +59,7 @@ Now let's give it a try! Run `npm run deploy-dev` or `npm run deploy-prod` and s ## Setting up build toggles -You can also setup deployment-dependent variables (aka. "build toggles") that are injected to your code during build time to allow for more advanced optimisations like dead code elimination. +You can also setup deployment-dependent variables \(aka. "build toggles"\) that are injected to your code during build time to allow for more advanced optimisations like dead code elimination. To do this, install `rollup-plugin-replace`. @@ -73,7 +73,7 @@ $ yarn add --dev rollup-plugin-replace Then configure your `rollup.config.js` to include your desired variables. -```js +```javascript // rollup.config.js import replace from 'rollup-plugin-replace'; @@ -91,15 +91,15 @@ export default { }; ``` -> **Note:** Generally, you need to ensure that `rollup-plugin-replace` goes *before* other plugins, so we can be sure Rollup replaces these variables correctly and the remaining plugins can apply any optimisations (e.g. dead code elimination) correctly. - -> **Note:** Because these values are evaluated once as a string (for the find-and-replace), and once as an expression, they need to be wrapped in `JSON.stringify`. +> **Note:** Generally, you need to ensure that `rollup-plugin-replace` goes _before_ other plugins, so we can be sure Rollup replaces these variables correctly and the remaining plugins can apply any optimisations \(e.g. dead code elimination\) correctly. +> +> **Note:** Because these values are evaluated once as a string \(for the find-and-replace\), and once as an expression, they need to be wrapped in `JSON.stringify`. Variables set by this plugin will be replaced in the actual output JS code. When compiling your code, Rollup will replace the variable names with the output of the supplied expression or value. Once it's set up, you use it in your code. -```ts +```typescript // log the latest commit ID from git if (__REVISION__) { console.log(`Revision ID: ${__REVISION__}`) @@ -115,13 +115,14 @@ export function loop() { ### Notes -Since TypeScript won't recognise these variables if you pass it blindly into your code, you will still need to declare them in a type definition (.d.ts) file. +Since TypeScript won't recognise these variables if you pass it blindly into your code, you will still need to declare them in a type definition \(.d.ts\) file. -```ts +```typescript // file.d.ts declare const __REVISION__: string; declare const __BUILD_TIME__: string; ``` -Also, be careful not to use too common of a name, because it will replace it throughout your code without warning. A good standard is to make the variables all caps, and surrounded by double underscores, so they stand out (e.g. `__REVISION__`). +Also, be careful not to use too common of a name, because it will replace it throughout your code without warning. A good standard is to make the variables all caps, and surrounded by double underscores, so they stand out \(e.g. `__REVISION__`\). + diff --git a/docs/in-depth/cookbook/one-line-powershell.md b/docs/in-depth/cookbook/one-line-powershell.md index 4737910..78d1384 100644 --- a/docs/in-depth/cookbook/one-line-powershell.md +++ b/docs/in-depth/cookbook/one-line-powershell.md @@ -1,19 +1,22 @@ # One-line PowerShell setup -> **Note:** As of v3.0, this no longer works. This issue is being tracked [here](https://github.com/ChrisTaylorRocks/screeps-typescript-starter-setup/issues/1). +{% hint style="warning" %} +**Note:** As of v3.0, this no longer works. This issue is being tracked [here](https://github.com/ChrisTaylorRocks/screeps-typescript-starter-setup/issues/1). +{% endhint %} [@ChrisTaylorRocks](https://github.com/ChrisTaylorRocks) has made a PowerShell script to get the starter kit up and running with a single command. Go check it out [here](https://github.com/ChrisTaylorRocks/screeps-typescript-starter-setup)! ## Usage -PowerShell < 5.0: +PowerShell < 5.0: -``` +```text PS> (new-object Net.WebClient).DownloadString('http://bit.ly/2z2QDJI') | iex; New-ScreepsTypeScriptSetup ``` PowerShell 5.0+: -``` +```text PS> curl http://bit.ly/2z2QDJI | iex; New-ScreepsTypeScriptSetup ``` + diff --git a/docs/in-depth/deploy-destinations.md b/docs/in-depth/deploy-destinations.md index 86f2c88..7cb1855 100644 --- a/docs/in-depth/deploy-destinations.md +++ b/docs/in-depth/deploy-destinations.md @@ -1,8 +1,8 @@ -# Deploy destination +# Deploy destinations The `screeps.json` file is a JSON configuration file separated into multiple deploy destinations. We've given you three primary destinations by default. -```json +```javascript { // Used for deploying to the main world "main": { @@ -44,3 +44,4 @@ rollup -c --environment DEST:main ``` Omitting the destination will perform a dry run, which will compile and bundle the code without uploading it. + diff --git a/docs/in-depth/module-bundling.md b/docs/in-depth/module-bundling.md index f6dd53d..a184e6b 100644 --- a/docs/in-depth/module-bundling.md +++ b/docs/in-depth/module-bundling.md @@ -10,27 +10,27 @@ npm install screeps-profiler Then you can import these libraries just like you would any other `npm` module. When you run the module bundler, it will bundle up all your files and third-party modules into one single JS file. -Some module bundlers even support performing further optimisations like eliminating unused module functions from your final bundled code (aka. _tree-shaking_), reducing the size of your final bundled JS even further. +Some module bundlers even support performing further optimisations like eliminating unused module functions from your final bundled code \(aka. _tree-shaking_\), reducing the size of your final bundled JS even further. ## Rollup From version 3.0 onwards, the starter kit uses Rollup as its main module bundler. Some useful features of Rollup include: -* Bundled modules are entirely flat (no weird boilerplate code emitted like in Webpack) -* Advanced tree-shaking (eliminates unused modules from the final bundle) -* Simpler configuration (compared to Webpack) +* Bundled modules are entirely flat \(no weird boilerplate code emitted like in Webpack\) +* Advanced tree-shaking \(eliminates unused modules from the final bundle\) +* Simpler configuration \(compared to Webpack\) If you're still comfortable with using Webpack, the old version of the starter kit is available [here](https://github.com/screepers/screeps-typescript-starter/tree/legacy/webpack), but moving forward, no new features will be added to the Webpack version. ### Note: Rollup and named exports -By default, Rollup recognises ES6 modules. This means that some adjustments are necessary in order for Rollup to work well with CommonJS modules, particularly those with named exports like `screeps-profiler`. (See [#77](https://github.com/screepers/screeps-typescript-starter/issues/77)) +By default, Rollup recognises ES6 modules. This means that some adjustments are necessary in order for Rollup to work well with CommonJS modules, particularly those with named exports like `screeps-profiler`. \(See [\#77](https://github.com/screepers/screeps-typescript-starter/issues/77)\) In this case, you will have to manually specify the named exports you use, which is where the `rollup-plugin-commonjs` plugin comes into play. This plugin resolves any CommonJS modules and converts them to ES6 modules, which can be bundled. Simply include the modules you want to bundle complete with its named exports, like so: -```js +```javascript commonjs({ namedExports: { // left-hand side can be an absolute path, a path @@ -42,3 +42,4 @@ commonjs({ ``` **For more info:** [`rollup-plugin-commonjs` docs](https://github.com/rollup/rollup-plugin-commonjs) + diff --git a/docs/in-depth/prettier.md b/docs/in-depth/prettier.md index 9ab8803..60b56d1 100644 --- a/docs/in-depth/prettier.md +++ b/docs/in-depth/prettier.md @@ -1,10 +1,10 @@ -# Code formatting with Prettier +# Prettier [Prettier](https://prettier.io/) is an automatic code formatter which supports various languages, including TypeScript. It also has extensions for various text editors like [VSCode](https://github.com/prettier/prettier-vscode), [Atom](https://github.com/prettier/prettier-atom), and even [Vim](https://github.com/prettier/vim-prettier). If you have installed these extensions, it will use Prettier's service to automatically format your code after saving. If you would rather not use Prettier instead, you can easily disable it too. In VSCode, open `.vscode/settings.json`, then change the `"editor.formatOnSave"` option to `false`: -```json +```javascript { "[json]": { "editor.formatOnSave": false @@ -22,7 +22,7 @@ If you would rather not use Prettier instead, you can easily disable it too. In The `.prettierrc` file configures how Prettier formats your code. By default we use the following options. -```json +```javascript { "semi": true, "tabWidth": 2, @@ -34,7 +34,7 @@ The `.prettierrc` file configures how Prettier formats your code. By default we We can use `tslint-config-prettier` to override some TSLint rules with its Prettier counterparts. In your `tslint.json` file, extend `tslint-config-prettier`. -```json +```javascript { "extends" : [ "tslint:recommended", @@ -49,7 +49,7 @@ To make Prettier error out on formatting errors, we can also use `tslint-plugin- yarn add --dev tslint-plugin-prettier ``` -```json +```javascript { "rulesDirectory": ["tslint-plugin-prettier"], "rules": { @@ -57,3 +57,4 @@ yarn add --dev tslint-plugin-prettier } } ``` + diff --git a/docs/troubleshooting.md b/docs/in-depth/troubleshooting.md similarity index 61% rename from docs/troubleshooting.md rename to docs/in-depth/troubleshooting.md index 90880b5..9285725 100644 --- a/docs/troubleshooting.md +++ b/docs/in-depth/troubleshooting.md @@ -6,17 +6,18 @@ This page outlines any common issues that you'll run into while setting up the T If you're getting the following error: -``` +```text (node:80116) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): Error: Cannot POST /api/auth/signin ``` Make sure you have [screepsmod-auth](https://github.com/ScreepsMods/screepsmod-auth) installed on your private server, and you've set a password on the account in your private server as well. -## Unable to extend type interfaces (e.g. `Game`, `Memory`) +## Unable to extend type interfaces \(e.g. `Game`, `Memory`\) -Make sure you declare any extensions to the type interfaces as an [*ambient declaration*](https://stackoverflow.com/a/40916055). You can either: +Make sure you declare any extensions to the type interfaces as an [_ambient declaration_](https://stackoverflow.com/a/40916055). You can either: * put them inside a `*.d.ts` file, or -* in an existing `.ts` file (with at least one `import` or `export`), you can use `declare global { interface CreepMemory { ... } }` to accomplish the same effect. +* in an existing `.ts` file \(with at least one `import` or `export`\), you can use `declare global { interface CreepMemory { ... } }` to accomplish the same effect. + +**For more info:** [https://github.com/screepers/typed-screeps/issues/27](https://github.com/screepers/typed-screeps/issues/27) -**For more info:** https://github.com/screepers/typed-screeps/issues/27 diff --git a/docs/in-depth/typescript.md b/docs/in-depth/typescript.md index eaf9fd1..6a811df 100644 --- a/docs/in-depth/typescript.md +++ b/docs/in-depth/typescript.md @@ -6,7 +6,7 @@ Static type checkers like TypeScript and [Flow](https://flow.org/) help reduce t To read more about how TypeScript can help you in Screeps, read [this Screeps World article](https://screepsworld.com/2017/07/typescreeps-getting-started-with-ts-in-screeps/) by [@bonzaiferroni](https://github.com/bonzaiferroni). -This section provides TypeScript-specific tips & tricks for you to make the best out of the ecosystem. +This section provides TypeScript-specific tips & tricks for you to make the best out of the ecosystem. ## Strict mode @@ -23,7 +23,7 @@ As of TypeScript 2.7, the affected options are: Starting from version 2.0 of the starter kit, we've enabled the `--strict` flag in `tsconfig.json`. If this gives you compile time errors, you can try setting `"strict"` to `false`, or by overriding one or more of the options listed above. -**For more info:** https://blog.mariusschulz.com/2017/06/09/typescript-2-3-the-strict-compiler-option +**For more info:** [https://blog.mariusschulz.com/2017/06/09/typescript-2-3-the-strict-compiler-option](https://blog.mariusschulz.com/2017/06/09/typescript-2-3-the-strict-compiler-option) ## TSLint @@ -42,6 +42,7 @@ We've made some changes to these rules, which we considered necessary and/or rel You can also customise your `tslint.json` file to match the preferences of your codebase. Click [here](https://palantir.github.io/tslint/usage/configuration/), to find out how, and click [here](https://palantir.github.io/tslint/rules/) for a complete list of rules available. -If you believe that some rules should not apply to a part of your code (e.g. for one-off cases like having to use `require()` to include a module), you can use flags to let TSLint know about it: https://palantir.github.io/tslint/usage/rule-flags/ +If you believe that some rules should not apply to a part of your code \(e.g. for one-off cases like having to use `require()` to include a module\), you can use flags to let TSLint know about it: [https://palantir.github.io/tslint/usage/rule-flags/](https://palantir.github.io/tslint/usage/rule-flags/) + +**More info about TSLint:** [https://palantir.github.io/tslint/](https://palantir.github.io/tslint/) -**More info about TSLint:** https://palantir.github.io/tslint/