From 0f2ed35378327d9eacf8d03eac3e9257d3ca1100 Mon Sep 17 00:00:00 2001 From: Lewis Dunn <99176798+ldunnplaymint@users.noreply.github.com> Date: Thu, 18 Jul 2024 10:34:35 +0100 Subject: [PATCH 1/8] Remove advanced section from top readme --- README.md | 150 ------------------------------------------------------ 1 file changed, 150 deletions(-) diff --git a/README.md b/README.md index b4077e485..a92f6e08f 100644 --- a/README.md +++ b/README.md @@ -11,156 +11,6 @@ Downstream is deployed to Redstone, a mainnet L2! Follow the guide to [start building on mainnet](./tutorial/README.md). ------------------------------------ - -# [Advanced] Instructions for Local Development - -
-Expand for more information! - -

Get building on top of Downstream

-
-Clone Repository (with submodules and LFS) - -## Clone Repository - -The repository needs cloning with LFS and recursive submodules. - -- **Install Git:** [Git SCM](https://git-scm.com/download/) for download and installation. -- **Install Git-LFS:** Visit [Git-LFS](https://git-lfs.com/) -- **Initialise Git-LFS:** Run the following command: - ``` - git lfs install - ``` -- **Clone the Repository:** Use the following command: - ``` - git clone --recurse-submodules https://github.com/playmint/ds - ``` - -## **_⚠️ 🖥 Windows_** - -Windows users must ensure they have symlinks enabled. - -- **Go to ds** - ``` - cd ds - ``` -- **Set symlinks to true** - ``` - git config core.symlinks true - ``` -
- -
-Running with Docker - -## Running with Docker - -If you only need a local copy of the game built (without development helpers -like hot reloading etc), then the easiest way is to provision using -Docker Compose. - -[Install Docker Desktop](https://docs.docker.com/get-docker/) - -``` -docker compose up --pull=always -``` - -This will fetch the most recently built images for the game and run them -without requiring a full build. - -Once ready, the client will be available at http://localhost:3000 - -See "Running Local with different Map Setups" section for deploying different maps, - -
-Docker Trouble shooting - -## Docker Trouble shooting - -**1. Hardware Virtualisation** -If when trying to run Docker you hit this error: -``` -hardware assisted virtualization and data execution protection must be enabled in the bios -``` -You will need to enter your BIOS and activate Hardware Virtualisation. This is usually the case for AMD processors. -
-
- -

Advanced options for contributors

-
-Building from Source - -## Building from Source - -For deploying locally with maximum flexibility and minimum rebuild times, you can install the whole tool chain and then create a local build with make. - -### Install tools - -Follow the [instructions for installing tools](./install-tools.md). - -### Build & Run -In the ds directory, run -``` -make dev -``` -In your browser, open `http://localhost:3000/` - -### Rebuilding after core changes: -If you have built the map during the `make dev` flow and since, there have been changes in the Unity scene -you will need to rebuild the map. To do this, it is adviced to clean all build artifacts with - -``` -make clean -``` - -Once you are done, you can either build everything again with `make dev` or you can just -build the map by using the `make map` command. -
- -
-Running locally with different maps - -# Running locally with different maps - -By Default, running `make dev` will spawn a one hex sized map and running with `docker` will spawn (the only slightly larger) "tiny" map. - -## 1. Apply a map after deploying - -After doing a standard `docker` or `make` build, you can run the `ds apply` command and point it at one of the map folders. For example: `ds apply -n local -z 1 -R -f ./contracts/src/maps/quest-map/` - -## 2. Claiming a zone - -Once your build has succeeded, `http://localhost:3000/` will take you to the Downstream homepage. Here you can sign in via Metamask, Wallet connect or use one of our Burner wallets. When deploying locally, a wallet called the "LocalDevAccoint" will already own Zone 1. You can connect using said wallet to speed things up. If you want to claim a new one using any other login method, make sure to note down the Zone Number as you will need to pass it through our `ds cli` tool using the `-z` flag. - -## 3. Build your own map and deploy it - -Once the game is running locally, browsing to `http://localhost:3000/tile-fabricator` will show the Tile Fabricator. - -Once in the Tile Fabricator, you can design and export a map file. If you want to pre-populate your map wih buildings you will need to import .yaml files that define the buildingKinds. - -If you then rename the .yml file to a .yaml and move it to your desired location, you will be able to run the ds apply command, like so: -`ds apply -n local -z 1 -f ./path/to/mymap.yaml` - -## 4. Destroying a map - -The `ds destroy` command essentially acts as the reverse of the `ds apply` command. If the user applies a manifest, running the `ds destroy` command and passing the same manifest will remove it. It is important to note that if you modify the files you recently applied, the destroy command will not work properly. It is worth keeping a copy of anything you have applied in the state you applied it in. - -As an example, if the user was to run this command from the root of the repository `ds apply -n local -z 1 -R -f contracts/src/maps/tutorial-room-1`, they will deploy the kinds, tiles, buildings and bags specified in the folder. If the user then runs `ds destroy -n local -z 1 -R -f contracts/src/maps/tutorial-room-1`, the tiles, buildings and bags specified in the manifest will be removed. The only thing that will remain deployed will be the kinds. - -## 5. Generating the performance-test map - -This is only possible with the `make` deploy flow and cannot be triggered for a `docker` build. To generate the performance-test map (used to push the limits of number of tiles and plugins) run: - -``` -NUM_ARENAS=4 make contracts/src/maps/performance-test -``` - -...this generates a map configuration in `contracts/src/maps/performance-test` - -You can then apply manually with: `ds apply -n local -z 1 -R -f contracts/src/maps/performance-test` - -
-
# References __[For more information, check the reference page](/tutorial/REFERENCE.md)__ From dbea9275f48055c72040620b20533dc8437a44be Mon Sep 17 00:00:00 2001 From: Lewis Dunn <99176798+ldunnplaymint@users.noreply.github.com> Date: Thu, 18 Jul 2024 10:36:30 +0100 Subject: [PATCH 2/8] Remove advanced section from welcome page --- tutorial/README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/tutorial/README.md b/tutorial/README.md index 80476435c..4a741dda9 100644 --- a/tutorial/README.md +++ b/tutorial/README.md @@ -18,9 +18,5 @@ Specific questions? Drop into our [Discord](https://discord.gg/MvYb9PBjGW) where ------------------------------------ -### [Advanced] Tutorials for Local development - -__[For more the Local Development Tutorials, click here](./ADVANCEDTUTORIALS.md)__ - ### References See the [References](./REFERENCE.md) for more detailed information on common tooling and commands. From 867cf1a6af24fdf2326d16d11097886685c9854d Mon Sep 17 00:00:00 2001 From: Lewis Dunn <99176798+ldunnplaymint@users.noreply.github.com> Date: Thu, 18 Jul 2024 10:38:08 +0100 Subject: [PATCH 3/8] Remove local dev tutorials from redstone guide --- tutorial/REDSTONEGUIDE.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/tutorial/REDSTONEGUIDE.md b/tutorial/REDSTONEGUIDE.md index 0a8d198d5..cb4cf1b12 100644 --- a/tutorial/REDSTONEGUIDE.md +++ b/tutorial/REDSTONEGUIDE.md @@ -92,6 +92,8 @@ If you select your building and add it to the map and then follow the same expor ## Further Reading -Check out the [Redstone Cheat Sheet](./RSCHEATSHEET.md) for more detail on the process outlined above +Check out the [Reference Page](./REFERENCE.md) for more detail on the process outlined above + + + -Check out the [Local Dev Tutorials](./ADVANCEDTUTORIALS.md) to set up your own local instance of Downstream and learn a lot more about how everything is built and how you can start building your own games! From c5bba3605a595b936891d85cce1f04bed6ed69a2 Mon Sep 17 00:00:00 2001 From: Lewis Dunn <99176798+ldunnplaymint@users.noreply.github.com> Date: Thu, 18 Jul 2024 10:40:34 +0100 Subject: [PATCH 4/8] Remove references to local from the reference page --- tutorial/REFERENCE.md | 22 ---------------------- 1 file changed, 22 deletions(-) diff --git a/tutorial/REFERENCE.md b/tutorial/REFERENCE.md index 7487eadb3..d02de408a 100644 --- a/tutorial/REFERENCE.md +++ b/tutorial/REFERENCE.md @@ -154,25 +154,3 @@ Dapps on the same chain could interact with these items in standard ways. Any Downstream building can interact with any other contract, including other onchain games, deployed to the same chain. Any other contract on the same chain can interact with the Downstream's read-only contract api but would not be able to send write actions. - -### Local instance - -Build and run a local Downstream instance with Docker. Follow the instructions for "_running with docker_" in the root [README](../README.md). - -The game will be running at [localhost:3000/](http://localhost:3000/). - -To enter a map, select Zone 1 from the list or naviage to [localhost:3000/zones/1](http://localhost:3000/zones/1) - - - -During development, its recommended to always connect with the LocalDevAccount option. - -When working locally, zone 1 is always assigned to the LocalDevAccount - - -# Video Guides - -| Video | Demonstrates | -|-------------------|----------------------| -| | Build and run; Default Map; Deploy example buildings;| -| | Tile Fabricator; Custom Map; | From 7d36b01742a2bde8416a38dd6ade244a7caa2df5 Mon Sep 17 00:00:00 2001 From: Lewis Dunn <99176798+ldunnplaymint@users.noreply.github.com> Date: Thu, 18 Jul 2024 10:41:59 +0100 Subject: [PATCH 5/8] Remove 'TIP' section --- tutorial/REFERENCE.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/tutorial/REFERENCE.md b/tutorial/REFERENCE.md index d02de408a..17b36796d 100644 --- a/tutorial/REFERENCE.md +++ b/tutorial/REFERENCE.md @@ -123,9 +123,6 @@ The files exported from the Building Fabricator act as a starting point for impl | BasicFactory.js | UI and Action dispatching | Implements an `update` function that is called when an instance of the building is clicked on in game. Use the `state` parameter to make control what html and buttons are returned.Dispatch onchain actions on behalf of the selected ***Unit*** with `ds.dispatch` | | BasicFactory.sol | Onchain logic | A solidity contract implementing `BuildingKind` interface. The entry point is the `BuildingKind.use` function, which can dispatch actions on behalf the ***Building***. | -> [!TIP] -> We are working on a tutorial to introduce all of Downstream's creation tools and game logic api. Until then, the examples below and reaching out in Discord are the best way to discover what's possible with your Downstream game. - ## Example Buildings __[All buildings referenced can be found here](../contracts/src/maps)__ From 8f19b187a40372fbe1b30dcc4865f95d5b0f7c45 Mon Sep 17 00:00:00 2001 From: Lewis Dunn <99176798+ldunnplaymint@users.noreply.github.com> Date: Thu, 18 Jul 2024 10:43:30 +0100 Subject: [PATCH 6/8] Added important section for tonk external services --- tutorial/ADVANCEDTUTORIALS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tutorial/ADVANCEDTUTORIALS.md b/tutorial/ADVANCEDTUTORIALS.md index b3a9c75b3..cf353fe78 100644 --- a/tutorial/ADVANCEDTUTORIALS.md +++ b/tutorial/ADVANCEDTUTORIALS.md @@ -33,8 +33,8 @@ __[All example games can be found here](../contracts/src/maps)__ | labyrinth || Game from [RockawayX](https://github.com/rockawayx-labs/ds-dx). Uses: Doors; Password hashing; Combat Stats; Item checking; Quests; Map reset| | duck-burger | | Game by [Playmint](https://www.playmint.com). Learn how to make DVB using [Tutorial 5](../contracts/src/maps/tutorial-room-5/)| -#### Please note: -Tonk attack requires Tonk services to be running: Run with docker using the `tonk` profile: `docker compose --profile tonk up` +> [!IMPORTANT] +> Tonk attack requires Tonk services to be running: Run with docker using the `tonk` profile: `docker compose --profile tonk up` ### References __[For more information, check the reference page](./REFERENCE.md)__ From 7a9896d4226e7134091beca0e716f0d3f731f7f0 Mon Sep 17 00:00:00 2001 From: Lewis Dunn <99176798+ldunnplaymint@users.noreply.github.com> Date: Fri, 19 Jul 2024 10:01:01 +0100 Subject: [PATCH 7/8] Add a line for the contributors page --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index a92f6e08f..1c0ccf345 100644 --- a/README.md +++ b/README.md @@ -14,3 +14,9 @@ Follow the guide to [start building on mainnet](./tutorial/README.md). # References __[For more information, check the reference page](/tutorial/REFERENCE.md)__ + +------------------------------------ + +# Contributors + +For people looking to contribute to the repository, please __[click here](./CONTRIBUTORS.md)__ From 463371b0d0f57dae7244ac37b02496a9a79f4be6 Mon Sep 17 00:00:00 2001 From: Lewis Dunn Date: Fri, 19 Jul 2024 10:03:31 +0100 Subject: [PATCH 8/8] Add contributors file --- CONTRIBUTORS.md | 145 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 CONTRIBUTORS.md diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md new file mode 100644 index 000000000..6ccd59f3f --- /dev/null +++ b/CONTRIBUTORS.md @@ -0,0 +1,145 @@ +# Instructions for Local Development + +

Get building on top of Downstream

+
+Clone Repository (with submodules and LFS) + +## Clone Repository + +The repository needs cloning with LFS and recursive submodules. + +- **Install Git:** [Git SCM](https://git-scm.com/download/) for download and installation. +- **Install Git-LFS:** Visit [Git-LFS](https://git-lfs.com/) +- **Initialise Git-LFS:** Run the following command: + ``` + git lfs install + ``` +- **Clone the Repository:** Use the following command: + ``` + git clone --recurse-submodules https://github.com/playmint/ds + ``` + +## **_⚠️ 🖥 Windows_** + +Windows users must ensure they have symlinks enabled. + +- **Go to ds** + ``` + cd ds + ``` +- **Set symlinks to true** + ``` + git config core.symlinks true + ``` +
+ +
+Running with Docker + +## Running with Docker + +If you only need a local copy of the game built (without development helpers +like hot reloading etc), then the easiest way is to provision using +Docker Compose. + +[Install Docker Desktop](https://docs.docker.com/get-docker/) + +``` +docker compose up --pull=always +``` + +This will fetch the most recently built images for the game and run them +without requiring a full build. + +Once ready, the client will be available at http://localhost:3000 + +See "Running Local with different Map Setups" section for deploying different maps, + +
+Docker Trouble shooting + +## Docker Trouble shooting + +**1. Hardware Virtualisation** +If when trying to run Docker you hit this error: +``` +hardware assisted virtualization and data execution protection must be enabled in the bios +``` +You will need to enter your BIOS and activate Hardware Virtualisation. This is usually the case for AMD processors. +
+
+ +

Advanced options for contributors

+
+Building from Source + +## Building from Source + +For deploying locally with maximum flexibility and minimum rebuild times, you can install the whole tool chain and then create a local build with make. + +### Install tools + +Follow the [instructions for installing tools](./install-tools.md). + +### Build & Run +In the ds directory, run +``` +make dev +``` +In your browser, open `http://localhost:3000/` + +### Rebuilding after core changes: +If you have built the map during the `make dev` flow and since, there have been changes in the Unity scene +you will need to rebuild the map. To do this, it is adviced to clean all build artifacts with + +``` +make clean +``` + +Once you are done, you can either build everything again with `make dev` or you can just +build the map by using the `make map` command. +
+ +
+Running locally with different maps + +# Running locally with different maps + +By Default, running `make dev` will spawn a one hex sized map and running with `docker` will spawn (the only slightly larger) "tiny" map. + +## 1. Apply a map after deploying + +After doing a standard `docker` or `make` build, you can run the `ds apply` command and point it at one of the map folders. For example: `ds apply -n local -z 1 -R -f ./contracts/src/maps/quest-map/` + +## 2. Claiming a zone + +Once your build has succeeded, `http://localhost:3000/` will take you to the Downstream homepage. Here you can sign in via Metamask, Wallet connect or use one of our Burner wallets. When deploying locally, a wallet called the "LocalDevAccoint" will already own Zone 1. You can connect using said wallet to speed things up. If you want to claim a new one using any other login method, make sure to note down the Zone Number as you will need to pass it through our `ds cli` tool using the `-z` flag. + +## 3. Build your own map and deploy it + +Once the game is running locally, browsing to `http://localhost:3000/tile-fabricator` will show the Tile Fabricator. + +Once in the Tile Fabricator, you can design and export a map file. If you want to pre-populate your map wih buildings you will need to import .yaml files that define the buildingKinds. + +If you then rename the .yml file to a .yaml and move it to your desired location, you will be able to run the ds apply command, like so: +`ds apply -n local -z 1 -f ./path/to/mymap.yaml` + +## 4. Destroying a map + +The `ds destroy` command essentially acts as the reverse of the `ds apply` command. If the user applies a manifest, running the `ds destroy` command and passing the same manifest will remove it. It is important to note that if you modify the files you recently applied, the destroy command will not work properly. It is worth keeping a copy of anything you have applied in the state you applied it in. + +As an example, if the user was to run this command from the root of the repository `ds apply -n local -z 1 -R -f contracts/src/maps/tutorial-room-1`, they will deploy the kinds, tiles, buildings and bags specified in the folder. If the user then runs `ds destroy -n local -z 1 -R -f contracts/src/maps/tutorial-room-1`, the tiles, buildings and bags specified in the manifest will be removed. The only thing that will remain deployed will be the kinds. + +## 5. Generating the performance-test map + +This is only possible with the `make` deploy flow and cannot be triggered for a `docker` build. To generate the performance-test map (used to push the limits of number of tiles and plugins) run: + +``` +NUM_ARENAS=4 make contracts/src/maps/performance-test +``` + +...this generates a map configuration in `contracts/src/maps/performance-test` + +You can then apply manually with: `ds apply -n local -z 1 -R -f contracts/src/maps/performance-test` + +