The project is based on Patrick Massot's prototype: [NNG4](https://github.com/PatrickMassot/NNG4).
## Creating a Game
## Creating a Game
Please follow the tutorial [Creating a Game](doc/create_game.md).
Please follow the tutorial [Creating a Game](doc/create_game.md). In particular, the following steps might be of interest:
In particular step 5 thereof explains [How to Run Games Locally](doc/running_locally.md).
### Publishing a Game
* Step 5: [How to Run Games Locally](doc/running_locally.md)
* Step 7: [How to Update an existing Game](doc/update_game.md)
* Step 8: [How to Publishing a Game](doc/publish_game.md)
We encourage anybody to have games hosted on our [Lean Game Server](https://adam.math.hhu.de) for anybody to play. For that you simply need to contact us with the link to your game repo. We are also happy to add work-in-progress games and games in any language.
## Documentation
For example, you can [contact Jon on Zulip](https://leanprover.zulipchat.com/#narrow/dm/385895-Jon-Eugster). Or [via Email](https://www.math.hhu.de/en/lehrstuehle-/-personen-/-ansprechpartner/innen/lehrstuehle-des-mathematischen-instituts/lehrstuhl-fuer-algebraische-geometrie/team/jon-eugster).
The documentation is very much work in progress but the linked documentation here
should be up-to-date:
## Documentation
### Game creation API
- [Creating a Game](doc/create_game.md): **the main document to consult**.
- [More about Hints](doc/hints.md): describes the `Hint` and `Branch` tactic.
The documentation for the game engine itself is still missing, but there is [Creating a Game](doc/create_game.md) explaining the API to create a game.
### Frontend API
Some documentation:
* [How to Run Games Locally](doc/running_locally.md): play a game on your computer
* [How to Update an existing Game](doc/update_game.md): update to a new lean version
* [How to Publishing a Game](doc/publish_game.md): load your game to adam.math.hhu.de for others to play
- [NPM Scripts](doc/npm_scripts.md)
### Backend
- [Old documentation](doc/DOCUMENTATION.md)
not written yet
## Contributing
## Contributing
@ -34,3 +37,10 @@ Contributions to `lean4game` are always welcome!
## Security
## Security
Providing the use access to a Lean instance running on the server is a severe security risk. That is why we start the Lean server with bubblewrap.
Providing the use access to a Lean instance running on the server is a severe security risk. That is why we start the Lean server with bubblewrap.
## Credits
The project is based on ideas from the [Lean Game Maker](https://github.com/mpedramfar/Lean-game-maker) and the [Natural Number Game
@ -4,7 +4,7 @@ This tutorial walks you through creating a new game for lean4. It covers from wr
## 1. Create the project
## 1. Create the project
1. Use the [NNG template](https://github.com/hhu-adam/NNG4) to create a new github repo for your game: On github, click on "Use this template" > "Create a new repository".
1. Use the [GameSkeleton template](https://github.com/hhu-adam/GameSkeleton) to create a new github repo for your game: On github, click on "Use this template" > "Create a new repository".
2. Clone the game repo.
2. Clone the game repo.
3. Call `lake update && lake exe cache get && lake build` to build the Lean project.
3. Call `lake update && lake exe cache get && lake build` to build the Lean project.
@ -223,25 +223,40 @@ One thing to keep in mind is that the game will look at the main proof to figure
Most important for game development are probably the `Hints`.
Most important for game development are probably the `Hints`.
The hints will be displayed whenever the player's current goal matches the goal the hint is
The hints will be displayed whenever the player's current goal matches the goal the hint is
placed at inside the sample proof. You can use `Branch` to place hints in dead ends or alternative proof strands. If you specify
placed at inside the sample proof. You can use `Branch` to place hints in dead ends or alternative proof strands.
```
Read [More about Hints](doc/hints.md) for how they work and what the options are.
Hint (strict := true) "some hidden hint"
```
a hint only matches iff the assumptions match exactly one-to-one. (Otherwise, it does not care if there are additional assumptions in context)
### 6. e) Extra: Images
You can add images on any layer of the game (i.e. game/world/level). These will be displayed in your game.
Further, you can choose to hide hints and only have them displayed when the player presses "More Help":
The images need to be placed in `images/` and you need to add a command like `Image "images/path/to/myWorldImage.png"`
```
in one of the files you created in 2), 3), or 4) (i.e. game/world/level).
Hint (hidden := true) "some hidden hint"
```
Lastly, you should put variable names in hints inside brackets:
NOTE: At present, only the images for a world are displayed. They appear in the introduction of the world.
## 7. Update your game
In principle, it is as simple as modifying `lean-toolchain` to update your game to a new Lean version. However, you should read about the details in [Update An Existing Game](doc/update_game.md).
## 8. Publish your game
To publish your game on the official server, see [Publishing a game](doc/publish_game.md)
There are a few more options you can add in `Game.lean` before the `MakeGame` command, which describe the tile that is visible on the server's landing page:
```lean
Languages "English"
CaptionShort "Game Template"
CaptionLong "You should use this game as a template for your own game and add your own levels."
Prerequisites "NNG"
CoverImage "images/cover.png"
```
```
Hint "now use `rw [{h}]` to use your assumption {h}."
* `Languages`: Currently only a single language (capital English name). The tile will show a corresponding flag.
```
* `CaptionShort`: One catch phrase. Appears above the image.
That way, the game will replace it with the actual name the assumption has in the player's proof state.
* `CaptionLong`: 2-4 sentences to describe the game.
* `Prerequisites` a list of other games you should play before this one, e.g. `Prerequisites "NNG" "STG"`. The game names are free-text.
* `CoverImage`: You can create a folder `images/` and put images there for the game to use. The maximal ratio is ca. 500x200 (W x H) but it might be cropped horizontally on narrow screens.
where `{USER}` and `{REPOSITORY}` are replaced with the github user and repository name.
You should see a white screen which shows import updates and eventually reports "Done."
## 3. Play the game
Now you can immediately play the game at `adam.math.hhu.de/#/g/{USER}/{REPOSITORY}`!
## 4. Main page
Adding games to the main page happens manually by the server maintainers. Tell us if you want us
to add a tile for your game!
For example, you can [contact Jon on Zulip](https://leanprover.zulipchat.com/#narrow/dm/385895-Jon-Eugster). Or [via Email](https://www.math.hhu.de/en/lehrstuehle-/-personen-/-ansprechpartner/innen/lehrstuehle-des-mathematischen-instituts/lehrstuhl-fuer-algebraische-geometrie/team/jon-eugster).
@ -4,13 +4,15 @@ The installation instructions are not yet tested on Mac/Windows. Comments very w
There are several options to play a game locally:
There are several options to play a game locally:
- VSCode Dev Container: needs `docker` installed on your machine
1. VSCode Dev Container: needs `docker` installed on your machine
- Codespaces: Needs active internet connection and computing time is limited.
2. Codespaces: Needs active internet connection and computing time is limited.
- Gitpod: does not work yet (I that true?)
3. Gitpod: does not work yet (Is that true?)
- Manual installation: Needs `npm` installed on your system
4. Manual installation: Needs `npm` installed on your system
The recommended option is "VSCode Dev containers" but you may choose any option above depending on your setup.
The recommended option is "VSCode Dev containers" but you may choose any option above depending on your setup.
The template game [GameSkeleton](https://github.com/hhu-adam/GameSkeleton) contains all the relevant files to make your local setup (dev container / gitpod / codespaces) work. You might need to update these files manually by copying them from there if you need any new improvements to the dev setup you're using in an existing game.
## VSCode Dev Containers
## VSCode Dev Containers
1. **Install Docker and Dev Containers***(once)*:<br/>
1. **Install Docker and Dev Containers***(once)*:<br/>
@ -27,9 +29,9 @@ The recommended option is "VSCode Dev containers" but you may choose any option
Once you have the Dev Containers Extension installed, (re)open the project folder of your game in VSCode.
Once you have the Dev Containers Extension installed, (re)open the project folder of your game in VSCode.
A message appears asking you to "Reopen in Container".
A message appears asking you to "Reopen in Container".
* The first start will take a while, ca. 2-10 minutes. After the first
* The first start will take a while, ca. 2-15 minutes. After the first
start this should be very quickly.
start this should be very quickly.
* Once built, you can open http://localhost:3000 in your browser. which should load the game
* Once built, you can open http://localhost:3000 in your browser. which should load the game.
3. **Editing Files***(everytime)*:<br/>
3. **Editing Files***(everytime)*:<br/>
After editing some Lean files in VSCode, open VSCode's terminal (View > Terminal) and run `lake build`. Now you can reload your browser to see the changes.
After editing some Lean files in VSCode, open VSCode's terminal (View > Terminal) and run `lake build`. Now you can reload your browser to see the changes.
@ -42,12 +44,13 @@ The recommended option is "VSCode Dev containers" but you may choose any option
you might have deleted stuff from docker via your shell. Try deleting the container and image
you might have deleted stuff from docker via your shell. Try deleting the container and image
explicitely in VSCode (left side, "Docker" icon). Then reopen vscode and let it rebuild the
explicitely in VSCode (left side, "Docker" icon). Then reopen vscode and let it rebuild the
container. (this will again take some time)
container. (this will again take some time)
* On a working dev container setup, http://localhost:3000 should directly redirect you to http://localhost:3000/#/g/local/game, try if the latter is accessible.
## Codespaces
## Codespaces
You can work on your game using Github codespaces (click "Code" and then "Codespaces" and then "create codespace on main"). It it should run the game locally in the background. You can open it for example under "Ports" and clicking on "Open in Browser".
You can work on your game using Github codespaces (click "Code" and then "Codespaces" and then "create codespace on main"). It it should run the game locally in the background. You can open it for example under "Ports" and clicking on "Open in Browser".
Note: You have to wait until npm started properly. In particular, this is after a message like `[client] webpack 5.81.0 compiled successfully in 38119 ms` appears in the terminal, which might take a good while.
Note: You have to wait until npm started properly, which might take a good while.
As with devcontainers, you need to run `lake build` after changing any lean files and then reload the browser.
As with devcontainers, you need to run `lake build` after changing any lean files and then reload the browser.
The folders `NNG4` and `lean4game` must be in the same directory!
The folders `GameSkeleton` and `lean4game` must be in the same directory!
In `lean4game`, install dependencies:
In `lean4game`, install dependencies:
```bash
```bash
@ -106,16 +108,16 @@ Run the game:
npm start
npm start
```
```
This takes a little time. Eventually, the game is available on http://localhost:3000/#/g/local/NNG4. Replace `NNG4` with the folder name of your local game.
This takes a little time. Eventually, the game is available on http://localhost:3000/#/g/local/GameSkeleton. Replace `GameSkeleton` with the folder name of your local game.
## Modifying the GameServer
## Modifying the GameServer
When modifying the game engine itself (in particular the content in `lean4game/server`) you can test it live with the same setup as above (manual installation) by setting `export NODE_ENV=development` inside your local game before building it:
When modifying the game engine itself (in particular the content in `lean4game/server`) you can test it live with the same setup as above (manual installation) by using `lake update -R -Klean4game.local`:
```bash
```bash
cd NNG4
cd NNG4
export NODE_ENV=development
lake update -R -Klean4game.local
lake update
lake build
lake build
```
```
This causes lake to search locally for the `GameServer` lake package instead of using the version from github. Therefore, when you `lake build` your game, it will rebuild with the modified `GameServer`.
This causes lake to search locally for the `GameServer` lake package instead of using the version from github. Therefore, you can the local copy of the edit `GameServer` in `../lean4game` and
`lake build` will then directly use this modified copy to build your game.
In order to set up the server to allow imports, one needs to create a
[Github Access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). A fine-grained access token with only reading rights for public
repos will suffice.
You need to set the environment variables `LEAN4GAME_GITHUB_USER` and `LEAN4GAME_GITHUB_TOKEN`
with your user name and access token. For example, you can seet these in `ecosystem.config.cjs` if
you're using `pm2`
Then people can call:
> https://{website}/import/trigger/{owner}/{repo}
where you replace:
- website: The website your server runs on, e.g. `localhost:3000`
- owner, repo: The owner and repository name of the game you want to load from github.
will trigger to download the latest version of your game from github onto your server.
Once this import reports "Done", you should be able to play your game under:
> https://{website}/#/g/{owner}/{repo}
## data management
Everything downloaded remains in the folder `lean4game/games`.
the subfolder `tmp` contains downloaded artifacts and can be deleted without loss.
The other folders should only contain the built lean-games, sorted by owner and repo.
"deprecated":"Please upgrade to version 7 or higher. Older versions may use Math.random() in certain circumstances, which is known to be problematic. See https://v8.dev/blog/math-random for details.",
Jon Eugster
3 years ago
committed by
GitHub
