generated from wisnia74/openrct2-typescript-mod-template
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
210304c
commit d721b47
Showing
1 changed file
with
34 additions
and
76 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,105 +1,63 @@ | ||
| # 🎢 openrct2-typescript-mod-template | ||
| # 🎢 CostInflator plugin for OpenRCT2 | ||
| [](https://dependabot.com/) | ||
|
|
||
| Template repository for OpenRCT2 mods written in TypeScript. | ||
| *CostInflator* is a plug-in for OpenRCT2 that allows you to increase (or decrease) the cost of various expenses, such as staff wages or ride upkeep. | ||
|
|
||
| ## Table of contents | ||
| * [About](#about) | ||
| * [Features](#features) | ||
| * [Installation](#installation) | ||
| * [Usage](#usage) | ||
| * [How it works](#how-it-works) | ||
| * [npm scripts](#npm-scripts) | ||
| * [Releasing your mod](#releasing-your-mod) | ||
| * [Notes](#notes) | ||
| * [Useful links](#useful-links) | ||
| * [How it works](#how-it-works) | ||
|
|
||
| ## About | ||
|
|
||
| This repository was created to serve as a template TypeScript mod repository for OpenRCT2. | ||
|
|
||
| I wanted to leverage [OpenRCT2 hot reload feature](https://github.com/OpenRCT2/OpenRCT2/blob/master/distribution/scripting.md#writing-scripts) to make it even more painless to write and debug mods in real time. | ||
| The purpose of the *CostInflator* plugin is to enable a player of OpenRCT2 to dynamically change the balance of the financial aspect of the Rollercoaster Tycoon by adjusting the cost of various expenses. | ||
|
|
||
| This template repository comes with [Nodemon](https://nodemon.io/), [ESLint](https://eslint.org/) and [TypeScript](https://www.typescriptlang.org/) on board. | ||
| ## Features | ||
|
|
||
| The idea was to use Nodemon to start a local server that will be watching your mod files, then on each save make it build `.ts` files to ES5 `.js` files, place them inside OpenRCT2 `plugin` directory, and let hot reload feature do the rest (i.e. reload the mod in-game). | ||
|  | ||
|
|
||
| ## Installation | ||
| The initial release of CostInflator can be used to adjust Ride and Stall/Facility running costs (upkeep) separately, each of which can be increased (or decreased) by specifying a multiplier in the settings window (shown above). When the game calculates the running costs for these cost categories, the plugin multiplies the result by the corresponding Multiplier setting. For example, a Ride Running Costs Multiplier of `2.00` will double the running costs for all rides, while a multiplier of `0.50` will half it. Multiplier settings can range from `0.00` (for no costs) up to `99.99`. | ||
|
|
||
| 1. Install latest versions of [Node](https://nodejs.org/en/) and [npm](https://www.npmjs.com/get-npm) | ||
| 2. [Create your own repository using this one as a template](https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template) and clone it anywhere to your PC | ||
| 3. `cd` into it and run `npm install` | ||
| 4. Find `openrct2.d.ts` TypeScript API declaration file in OpenRCT2 files and copy it to `lib` folder (this file can usually be found in `C:\Users\<USER>\Documents\OpenRCT2\bin` or `C:\Program Files\OpenRCT2\openrct2.d.ts`) | ||
| - alternatively, you can make a symbolic link instead of copying the file, which will keep the file up to date whenever you install new versions of OpenRCT2. To do this on Windows: | ||
| - run command prompt as administrator | ||
| - `cd` into your repo (wherever you cloned it) | ||
| - run `mklink ./lib/openrct2.d.ts <path to openrct2.d.ts>` | ||
| 5. Edit `./config.json`: | ||
| - `modName` - will be used in `./src/registerPlugin.ts`, `./rollup.config.dev.js` and `./rollup.config.prod.js` | ||
| - `modURL` - will be used in `./src/registerPlugin.ts` and `package.json` | ||
| - use the URL created as a result of step 2 (link to your mod repo) - it should look like `https://github.com/<author>/<repository>` | ||
| - `gamePath` - will be used in `./rollup.config.dev.js` | ||
| - make sure this path uses `/` instead of `\` | ||
| - this path is the one that holds the `plugin` folder, not the installation path | ||
| - typically `C:\Users\<USER>\Documents\OpenRCT2` | ||
| 6. Run `npm run init` - it will replace all the data and then commit the results | ||
| 7. You can start modding :) | ||
| In addition to the Multiplier setting, the Inflation setting determines the 'inflation rate' of the corresponding multiplier: At the start of each month, the value of the Inflation setting is added to the multiplier. For example, a Ride Running Costs Inflation of '0.10' will increase the Ride Running Cost Multiplier by 0.1 at the start of every month. Inflation settings can range from `-99.99` to `99.99`. | ||
|
|
||
| Of course it's a template, so you can edit anything you like. | ||
| ### Cost categories | ||
|
|
||
| If you want to alter plugin data, refer to [OpenRCT2 scripting guide](https://github.com/OpenRCT2/OpenRCT2/blob/master/distribution/scripting.md). | ||
| The initial release of CostInflator supports the following categories: | ||
|
|
||
| ## Usage | ||
| - Ride running costs (upkeep) | ||
| - Stall/facility running costs (upkeep) | ||
|
|
||
| 1. Make sure you've enabled [OpenRCT2 hot reload feature](https://github.com/OpenRCT2/OpenRCT2/blob/master/distribution/scripting.md#writing-scripts) by setting `enable_hot_reloading = true` in your `/OpenRCT2/config.ini` | ||
| 2. `cd` into repo | ||
| 3. run `npm start` (this will place compiled and minified mod inside `PATH_TO_OPENRCT2/plugin/` directory) | ||
| 4. Open `./src/main.ts` in your code editor | ||
| 5. [Start OpenRCT2 with console](https://github.com/OpenRCT2/OpenRCT2/blob/master/distribution/scripting.md#writing-scripts) and load save/start new game | ||
| 6. Each time you save any of the files in `./src/`, the server will compile `./src/registerPlugin.ts` and place compiled file inside `PATH_TO_OPENRCT2/plugin/` directory as `MOD_NAME.js` | ||
| 7. OpenRCT2 will notice file changes and it will reload the mods | ||
| More will be added in future releases. | ||
|
|
||
| ### How it works | ||
| ## Installation and usage | ||
|
|
||
| Your mod files live in `./src/` directory. That's the ones you will be writing code in. | ||
| Upon starting Nodemon server, it will start watching changes you make to files in `./src/`, and it will build them accordingly. | ||
| The plugin has been tested with OpenRCT2 version 0.4.0. It hasn't been tested with earlier releases. | ||
|
|
||
| The entry point is `./src/registerPlugin.ts`. Any file, class, module you create in `./src/` needs to be imported to `registerPlugin.ts` one way or another. | ||
| 1. Download the latest version of the plugin from the [Releases](https://github.com/DanStevens/openrct2-CostInflator/releases) page. | ||
| 2. To install it, copy the downloaded `*.js` file into your `/OpenRCT2/`plugin folder. | ||
| - The easiest way to find the OpenRCT2-folder is by launching the OpenRCT2 game, click and hold on the red toolbox in the main menu, and select "Open custom content folder". | ||
| - Otherwise this folder is commonly found in `C:/Users/<YOUR NAME>/Documents/OpenRCT2/plugin` on Windows. | ||
| - If you already had this plugin installed before, you can safely overwrite the old file. | ||
| 3. Once installed, find the 'Cost Inflator' menu item within the map menu in the toolbar to open the settings window | ||
|
|
||
| Template uses [Terser](https://github.com/terser/terser) to minify your output mod bundle file and to resolve any dependencies. | ||
| ## Building the source code | ||
|
|
||
| ### npm scripts | ||
| This project is based on [wisnia74's Typescript modding template](https://github.com/wisnia74/openrct2-typescript-mod-template) and uses [Nodemon](https://nodemon.io/), [ESLint](https://eslint.org/) and [TypeScript](https://www.typescriptlang.org/) from this template. | ||
|
|
||
| |script|function| | ||
| |--|--| | ||
| |`npm start`|starts Nodemon server that will be watching `./src/` directory for any changes you make to any files inside it| | ||
| |`npm run lint`|lints your `.ts` and `.js` files from `./src/` directory| | ||
| |`npm run build:dev`|compiles `registerPlugin.ts` and minifies it, then places it inside `PATH_TO_OPENRCT2/plugin/` as `MOD_NAME.js`| | ||
| |`npm run build`|runs `npm run lint` and if no linting errors are found, compiles `registerPlugin.ts` and minifies it, then places it inside `./dist/` folder as `MOD_NAME.js` - this is your final mod file| | ||
| 1. Install latest version of [Node](https://nodejs.org/en/) and make sure to include NPM in the installation options. | ||
| 2. Clone the project to a location of your choice on your PC. | ||
| 3. Open command prompt, use `cd` to change your current directory to the root folder of this project and run `npm install`. | ||
| 4. Open the file `src/registerPlugin.ts` and adjust the path to `openrct2.d.ts` appropriate for your environment (for example, `C:/Program Files/OpenRCT2/bin/openrct2.d.ts`). | ||
| 6. Run `npm run build` (release build) or `npm run build:dev` (develop build) to build the project. | ||
| - The default output folder is `./dist` for release and `./dev-build` for development and can be changed in `rollup.config.prod.js` and `rollup.config.dev.js` respectively. | ||
|
|
||
| ## Releasing your mod | ||
| ## How it works | ||
|
|
||
| After running `npm run build` locally, `./dist/` directory will be created that will contain `MOD_NAME.js`. | ||
| It's up to you, if you want to edit `.gitignore` to actually include `./dist/` contents and push them to your remote or if you want to manually copy the contents of `./dist/` and publish them somewhere. However creating a GitHub release using contents of `./dist/` directory sounds like a cool idea. You would have your mod file available for download straight from the repo. | ||
| Don't forget to update `README.md` to reflect your mod and update version numbers for future releases. | ||
| The plugin subscribes to the `'ride.ratings.calculate'` API hook, which the OpenRCT2 game engine invokes each time the running cost of a ride, stall or facility is calculated. The ride object is retrieved by ID via the `map.getRide` plugin API method and the `runningCost` property is adjusted according to the multiplier. | ||
|
|
||
| ## Notes | ||
| The plugin also subscribes to the `'interval.day'` API hook, which the OpenRCT2 game engine invokes once per day in-game time. If `date.monthProgress` is zero (meaning the month has just begun), the plugin updates the Multiplier setting for each cost category, according to the corresponding Inflation setting. | ||
|
|
||
| If you've added a new mod folder to `plugin`, and the OpenRCT2 didn't seem like it registered it (and you had a running park), just load the save/start a new park, so OpenRCT2 loads the mods again. Now when you overwrite them during development, there shouldn't be any problems with hot reload noticing file changes. | ||
|
|
||
| Don't touch `app.js`. Its existence makes Nodemon happy. | ||
|
|
||
| Nodemon is what watches your files for changes & fires off new dev builds for hot reloading. | ||
| Furthermore, it's used for resolving root directory of the project - that's used, for example, in init script. | ||
|
|
||
| Nodemon will watch all the files in `./src/` directory. You can also freely create classes, modules, import them in your mod files. | ||
| Sky's the limit :) | ||
|
|
||
| ## Useful links | ||
|
|
||
| - [OpenRCT2 website](https://openrct2.io/) | ||
| - [OpenRCT2 on GitHub](https://github.com/OpenRCT2) | ||
| - [OpenRCT2 on Reddit](https://www.reddit.com/r/openrct2) | ||
| - [OpenRCT2 plugins website](https://openrct2plugins.org/) | ||
| - [OpenRCT2 example plugins repository](https://github.com/OpenRCT2/plugin-samples) | ||
| - [OpenRCT2 scripting guide](https://github.com/OpenRCT2/OpenRCT2/blob/develop/distribution/scripting.md) | ||
| - [OpenRCT2 hot reload feature presentation](https://www.youtube.com/watch?v=jmjWzEhmDjk) | ||
| Whenever settings are changed, they are stored in the park file (via `parkStorage` API object). |