diff --git a/README.md b/README.md index e68dafe..86c5ed0 100644 --- a/README.md +++ b/README.md @@ -1,105 +1,63 @@ -# 🎢 openrct2-typescript-mod-template +# 🎢 CostInflator plugin for OpenRCT2 [![Dependabot](https://badgen.net/badge/Dependabot/enabled/green?icon=dependabot)](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). +![(CostInflator settings window, with default settings)](https://danstevens.github.io/CostInflatorSettingsWindow.png) -## 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\\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 ` -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//` - - `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\\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//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). \ No newline at end of file