Skip to content

Commit

Permalink
Simplify README a bit, probably still needs more
Browse files Browse the repository at this point in the history
  • Loading branch information
@dumbmatter
dumbmatter committed Jan 19, 2025
1 parent bde950b commit 59d4a13
Show file tree
Hide file tree
Showing 7 changed files with 155 additions and 202 deletions.
146 changes: 43 additions & 103 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,33 +6,30 @@ are implemented entirely in client-side JavaScript, backed by IndexedDB.

Copyright (C) ZenGM, LLC. All rights reserved.

Email: [email protected]
Email: <[email protected]>

Website: <https://zengm.com/>

Development: <https://github.com/zengm-games/zengm>

Discussion:

* <https://www.reddit.com/r/BasketballGM/>
* <https://www.reddit.com/r/Football_GM/>
* <https://www.reddit.com/r/ZenGMBaseball/>
* <https://www.reddit.com/r/ZenGMHockey/>
* <https://zengm.com/discord/>
* [Discord](https://zengm.com/discord/)
* Reddit: [Basketball GM](https://www.reddit.com/r/BasketballGM/),
[Football GM](https://www.reddit.com/r/Football_GM/),
[ZenGM Baseball](https://www.reddit.com/r/ZenGMBaseball/),
[ZenGM Hockey](https://www.reddit.com/r/ZenGMHockey/)

**This project is NOT open source, but it is also not completely closed. Please
see [LICENSE.md](LICENSE.md) for details.**

## Development Info
## Who is this for?

If you just want to play the game, go to <https://zengm.com/>. Instructions
below are for developers who want to run a copy locally so they can make changes
to the code.
If you just want to play a game, go to <https://zengm.com/>. Instructions below
are for developers who want to run a copy locally so they can make changes to
the code.

If you want to contribute but get stuck somewhere, please contact me! I'm happy
to help.

### License and Contributor License Agreement
## License and contributor license agreement

**This project is NOT open source, but it is also not completely closed. Please
see [LICENSE.md](LICENSE.md) for details.**
Expand All @@ -48,81 +45,63 @@ Make a copy of the form, fill in your information at the bottom, and send an
email to [email protected] with the subject line, "Contributor License Agreement
from YOUR_NAME_HERE (GITHUB_USERNAME_HERE)".

### Step 1 - Installing

Make sure you're using a recent version of [Node.js](https://nodejs.org/), older
versions probably won't work. Then, all of the tooling used in development can
be set up by simply installing [pnpm](https://pnpm.io/) and
running:

pnpm install

from within this folder.
## Setup

### Step 2 - Building
First install [Node.js](https://nodejs.org/) 22 and [pnpm](https://pnpm.io/) 9.

To build the app along with all its assets, run
Then within this folder run:

pnpm run build
pnpm install

However during development, you probably would rather do
to install dependencies and:

pnpm run start-watch
pnpm run dev

which will start the server and watch JS and CSS files for changes and
recompile. This simply runs both `pnpm run start` and `pnpm run watch` together,
which alternatively can be run separately if you wish.
to start the dev server and watch the source code for changes.

By default this will build the basketball version of the game. For other sports,
set the SPORT environment variable to "football", "baseball", or "hockey", like:

SPORT=football pnpm run start-watch

Open `package.json` to see all available development scripts.

### Step 3 - Running

To run the game locally, you need some way of running a web server to display
the content. There are currently two ways to do it. It doesn't matter which you
use as long as you can get it to run on your computer.
SPORT=football pnpm run dev

#### 1. Node.js (easiest)
The `dev` script will also tell you a URL to open in your browser to view the
game, <http://localhost:3000> unless that port is already in use.

Run
## Other dev info

pnpm run start

and point your browser to <http://localhost:3000/> (or it will use a different
port if 3000 is already used by somethign else). If you use the command `pnpm
run start-watch` from above, then running the command `pnpm run start` is not
necessary.

#### 2. Apache

The mod_rewrite rules in `.htaccess` let the game run in Apache. Everything
should work if you point it at the `build` folder with mod_rewrite enabled.

### Step 4 - Testing
### Tests

TypeScript and ESLint are used to enforce some coding standards. To run them on
the entire codebase, run
the entire codebase, run:

pnpm run lint

Integration and unit tests spread out through the codebase in *.test.ts files.
Coverage is not great. They can be run from the command line with
Coverage is not great. They can be run from the command line with:

pnpm test
pnpm run test

There is also a single end-to-end test which creates a league and simulates a
season. To execute the end-to-end test, run
season. To execute the end-to-end test, run:

pnpm run test-e2e

For the end-to-end test, by default it is basketball. If you want it to do
football, stick `SPORT=football ` in front.
Like the dev command, you can stick `SPORT=football ` or whatever in front of
this command to run it for a non-basketball sport.

### Git workflow

If you want to contribute changes back to the project, first create a fork on
GitHub. Then make your changes in a new branch. Confirm that the tests
(hopefully including new ones you wrote!) and lint scripts all pass. Finally,
send me a pull request.

It's also probably a good idea to create an [issue on
GitHub](https://github.com/zengm-games/zengm/issues) before you start working
on something to keep me in the loop. I don't want you to spend lots of time on
something that I don't want to put in the game!

### Code Overview
### Code overview

This is a single-page app that runs almost entirely client-side by storing data
in IndexedDB. The core of the game runs inside a Shared Worker (or a Web Worker
Expand All @@ -149,7 +128,7 @@ In both the worker and UI processes, there is a global variable `self.bbgm`
which gives you access to many of the internal functions of the game from
within your browser.

### Shared Worker Debugging
### Shared Worker debugging

As mentioned above, the core of a game runs in a Shared Worker. This makes
debugging a little tricky. For instance, in Chrome, if you `console.log`
Expand All @@ -161,45 +140,6 @@ In any browser, if you have two tabs open and you reload one of them, the worker
process will not reload. So make sure you close all tabs except one before
reloading if you want to see changes in the worker.

### Service Worker

This only applies if you use Apache, not if you use `pnpm run start`!

A service worker is used for offline caching. This can make development tricky,
because if you load the game in your browser, make a change, wait for
build/watch to finish, and then reload... you will not see your change because
it will cache the original version and then not update it on a reload. This is
the normal behavior for service workers (they only switch to a new version when
you actually close the website and reopen it, not on a reload), but it makes
development annoying.

To work around that, in Chrome you can [use the "Update on reload" option][1]
and keep your devtools open. Then reloading will always get you the latest
version.

Even with that, ctrl+shift+r may be a good idea to make sure you're seeing your
latest changes.

[1]: https://developers.google.com/web/fundamentals/primers/service-workers/lifecycle#update_on_reload

### Git Workflow

If you want to contribute changes back to the project, first create a fork on
GitHub. Then make your changes in a new branch. Confirm that the tests
(hopefully including new ones you wrote!) and ESLint all pass. Finally, send me
a pull request.

It's also probably a good idea to create an [issue on
GitHub](https://github.com/zengm-games/zengm/issues) before you start working
on something to keep me in the loop.

## Less Important Development Info

### Sport-specific stuff

Abbreviations of stats should be done like basketball-reference.com and
football-reference.com stat pages. For instance, "defensive rebounds" is "drb".

### Thank you BrowserStack

Shout out to [BrowserStack](https://www.browserstack.com/) for helping with
Expand Down
3 changes: 3 additions & 0 deletions TODO
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
cli/dev/preview
- restore cursor on ctrl+c?

GOAT lab and GOAT season date range filters https://discord.com/channels/290013534023057409/331882115119448065/1327680226477604895
- for players, implement similar to Advanced Player Search

Expand Down
5 changes: 2 additions & 3 deletions package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,11 @@
"url": "https://github.com/zengm-games/zengm.git"
},
"scripts": {
"start": "node --experimental-strip-types --disable-warning=ExperimentalWarning tools/server.ts",
"build": "node --experimental-strip-types --disable-warning=ExperimentalWarning tools/build.ts",
"deploy": "node --run lint && node --run test && node --experimental-strip-types --disable-warning=ExperimentalWarning tools/deploy.ts",
"deploy-all": "node --run lint && node --run test && node --experimental-strip-types --disable-warning=ExperimentalWarning tools/deploy-all.ts",
"start-watch": "concurrently --kill-others \"node --run start\" \"node --run watch\"",
"watch": "node --experimental-strip-types --disable-warning=ExperimentalWarning tools/watch/cli.ts",
"dev": "node --experimental-strip-types --disable-warning=ExperimentalWarning tools/watch/cli.ts",
"preview": "node --experimental-strip-types --disable-warning=ExperimentalWarning tools/preview.ts",
"lint": "concurrently --raw \"node --run lint-js\" \"node --run lint-ts\"",
"lint-js": "eslint",
"lint-ts": "node --run pre-test && tsc",
Expand Down
3 changes: 3 additions & 0 deletions tools/preview.ts
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
import { startServer } from "./watch/server.ts";

await startServer();
62 changes: 4 additions & 58 deletions tools/watch/cli.ts
View file
Original file line number Diff line number Diff line change
@@ -1,67 +1,13 @@
import { statSync } from "fs";
import yoctocolors from "yoctocolors";
import { Spinners } from "./Spinners.ts";
import { spinners } from "./spinners.ts";
import watchCSS from "./watchCSS.ts";
import watchFiles from "./watchFiles.ts";
import watchJS from "./watchJS.ts";
import watchJSONSchema from "./watchJSONSchema.ts";
import { startServer } from "./server.ts";

const TIME_CUTOFF_SPIN_1 = 1_000;
const TIME_CUTOFF_SPIN_2 = 5_000;
const TIME_CUTOFF_SUCCESS_1 = 10_000;
const TIME_CUTOFF_SUCCESS_2 = 30_000;

const spinners = new Spinners(
({ key, info, symbol }) => {
const symbolAndText = `${symbol} ${key}`;

if (info.status === "spin") {
const dateStart = info.dateStart;
const millisecondsElapsed = Date.now() - dateStart.getTime();
const time = dateStart.toLocaleTimeString();
let coloredTime;
if (millisecondsElapsed > TIME_CUTOFF_SPIN_2) {
coloredTime = yoctocolors.red(time);
} else if (millisecondsElapsed > TIME_CUTOFF_SPIN_1) {
coloredTime = yoctocolors.yellow(time);
} else {
coloredTime = time;
}

return `${symbolAndText}: build started at ${coloredTime}`;
}
if (info.status === "error") {
return `${symbolAndText} ${info.error.stack ?? "See error above from ESBuild"}`;
}

if (info.status === "success") {
const { dateStart, dateEnd, size } = info;

const duration = (dateEnd.getTime() - dateStart.getTime()) / 1000;
const megabytes =
size !== undefined ? (size / 1024 / 1024).toFixed(2) : undefined;

const millisecondsElapsed = Date.now() - dateEnd.getTime();
const time = dateEnd.toLocaleTimeString();
let coloredTime;
if (millisecondsElapsed < TIME_CUTOFF_SUCCESS_1) {
coloredTime = yoctocolors.green(time);
} else if (millisecondsElapsed < TIME_CUTOFF_SUCCESS_2) {
coloredTime = yoctocolors.yellow(time);
} else {
coloredTime = time;
}

return `${symbolAndText}: ${megabytes !== undefined ? `${megabytes} MB in ` : ""}${duration} seconds at ${coloredTime}`;
}

return symbolAndText;
},
{
// Don't need to pass "spin" ones because it's always rendering while spinning
success: [TIME_CUTOFF_SUCCESS_1, TIME_CUTOFF_SUCCESS_2],
},
);
await startServer();
console.log("");

const updateStart = (filename: string) => {
spinners.setStatus(filename, {
Expand Down
Loading

0 comments on commit 59d4a13

Please sign in to comment.