Skip to content

Commit

Permalink
chore: update readme with new typescript guidelines
Browse files Browse the repository at this point in the history
  • Loading branch information
@tsa96
tsa96 committed Nov 15, 2024
1 parent 4dc75b2 commit 60c8c0c
Showing 1 changed file with 41 additions and 51 deletions.
92 changes: 41 additions & 51 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@
# Structure

The repository primarily consists of XML, SCSS and JavaScript/TypeScript files. It also includes all icons and various
images and videos used by the UI.
The repository primarily consists of XML, SCSS and TypeScript files. It also includes all icons and various images and
videos used by the UI.

For a general overview of Panorama, see the [VDC page](https://developer.valvesoftware.com/wiki/Panorama).

Expand Down Expand Up @@ -33,38 +33,36 @@ in C++ code, which use UpperCamelCase.

## JavaScript/TypeScript

Panorama uses the [V8 JavaScript engine](https://v8.dev) to interpret and run the JavaScript files, found in `scripts/`,
at runtime, which are included in XML files within `<scripts>` tags (similar to regular web development).
Panorama uses the [V8 JavaScript engine](https://v8.dev) to run JavaScript, with TypeScript compiler (tsc) built-in to
the engine to provide native TypeScript support. Scripts can be found in `scripts/`, and are loaded at runtime through
`<scripts>` tags in XML files.

We also support TypeScript - any `.ts` file `scripts/` are compiled to corresponding JavaScript files in `script_dist/`,
whilst `.js` are just copied over. Note that we don't use any kind of import/module/bundling system as it's not
supported in engine code. Instead we just declare the same XML `<scripts>` tags and scripts get the same scope (yeah,
old school). Use `/// <reference path="foo.ts" />` to keep TypeScript happy.
Whilst loading plain JavaScript is still supported, practically all of our code is in TypeScript, and we expect
contributors to use TypeScript for new code.

JavaScript communicates with the game via events and APIs exposed by the game. The
[pano-typed](https://github.com/StrataSource/pano-typed) package (submoduled in `scripts/types/`) which provides types
and documentation for the exposed APIs and events. These are updated manually, and some things may be missing. A full
list of which can be found by running `dump_panorama_events markdown` and `dump_panorama_js_scopes markdown` in-game
(best to the game in `-condebug` and read `momentum/console.log`). Feel free to add any APIs/events to the `pano-typed`
package! If anything is missing completely, please contact us in Discord and we can check in engine code for you.
JavaScript communicates with the game via events and APIs exposed by the game. Types for these are includes in
`scripts/types-mom` and `scripts/types`, which is a submodule of the
[pano-typed](https://github.com/StrataSource/pano-typed) repo. and documentation for the exposed APIs and events. These
are updated manually, and some things may be missing; please let us know if anything seems off and we'll check engine
code.

# Setup

#### Requirements

- Git
- [Node.js](https://nodejs.org/en/download/)
# Contributing

#### Recommendations
Most of our larger systems and components require significant work with (closed-source) game code and thus requires
licensed C++ access or working tandem licensed C++ developer. Our work until now has been done internally by the core
team. For 0.9.1 and onwards, we have exposed enough events and APIs that non-team developers should be able to work on
areas like HUD components (for a good example of non-licensed HUD work, see
[`scripts/hud/cgaz.ts`](scripts/hud/cgaz.ts)). We will continue to expose data as we best see fit for custom panels.

We highly suggest using @braem's
[panorama-languages-support](https://marketplace.visualstudio.com/items?itemName=braemie.panorama-css) VSCode plugin for
language support for Panorama's version of CSS
Those looking to contribute should look for issues **NOT** marked with "Needs C++". We also greatly encourage you to
check out the the #panorama channel in our [Discord](https://discord.gg/momentummod) - whilst Panorama itself is poorly
documented, we are happy to help any potential contributors further there!

### Guide
### Basic Setup

The easiest way to develop for Momentum Mod Panorama is to fork this repository and mount it in your `momentum/custom/`
folder, for example:
For non-licensed developers, you will need to have a Steam build of the game installed. The easiest way to develop
Panorama changes on top of that is to mount the `panorama` folder in your `momentum/custom/` folder, by forking this
repo (if not a team member), then:

```bash
cd <Your Steam Momentum Mod or Momentum Mod Playtest install location>\momentum\custom\
Expand All @@ -75,33 +73,25 @@ git clone https://github.com/<your github account>/panorama.git

You should end up with `momentum/custom/PanoramaDev/panorama` containing the contents of this repository.

This will be mounted on game launch and override the files in your `momentum/panorama/` folder. To avoid any overlaps
(e.g. if your branch renames or moves a file, the original file will still be mounted), you may want to temporarily
rename your `momentum/panorama/` folder. (_NOTE: you'll need to do this after each Momentum Mod Steam update!_)

Install [Node.js](https://nodejs.org/en/download/) if you don't have it already, then in a terminal run:
This will be mounted on game launch and override the files in your `momentum/panorama/` folder. Mind that it's possible
for overlaps, e.g. if your branch renames or moves a file, the original file will still be mounted, but this is very
rarely an issue. If necessary, rename your `momentum/panorama/` folder. (_NOTE: you'll need to do this after each
Momentum Mod Steam update!_)

`npm install`
### Type checking, Linting and Formatting

This will install necessary dev dependencies and setup commit hooks which will lint and auto-format your code on commit.
Since adding native TypeScript support, a Node.js installation is not technically required. However, for performance the
built-in compiler only transpiles to JavaScript, without performing type checks. We run type checks in CI, but you
likely also want an editor with TypeScript support, and may want to run `npm run watch` (script for
`tsc --noEmit --watch`) to check types as you go.

You will need to run:
Linting and formatting is enforced in CI, run `npm install` to setup commit hooks for both, and use
`npm run <format/lint>:<fix/check>` to format/lint your code.

`npm run build`
To get Node.js and NPM go to <https://nodejs.org/en/download/>

at least once to compile JS/TS scripts to JS, and after any changes to files in `scripts/`. Use watch mode if you want
to compile on change with

`npm run watch`

# Contributing

Most of our larger systems and components require significant work with (closed-source) game code and thus requires
licensed C++ access or working tandem licensed C++ developer. Our work until now has been done internally by the core
team. For 0.9.1 and onwards, we have exposed enough events and APIs that non-team developers should be able to work on
areas like HUD components (for an example of non-licensed HUD work, we recommend
[`scripts/hud/cgaz.js`](scripts/hud/cgaz.js)). We will continue to expose data as we best see fit for custom panels.
### Recommendations

Therefore, those looking to contribute should look for issues **NOT** marked with "Needs C++". We also greatly encourage
you to check out the the #panorama channel in our [Discord](https://discord.gg/momentummod) - whilst Panorama itself is
poorly documented, we are happy to help any potential contributors further there!
@braem's [panorama-languages-support](https://marketplace.visualstudio.com/items?itemName=braemie.panorama-css) VSCode
plugin for language support for Panorama's version of CSS, which is invaluable for those unfamiliar with Panorama's
unique CSS properties.

0 comments on commit 60c8c0c

Please sign in to comment.