Merge pull request #7 from themetacat/main

add MUD PixeLAW Core book

src/build-app/1-build-app-mud.md

@@ -2,3 +2,140 @@
 
 > **_REQUIRED:_** To create your own application in PixeLAW, you must have [set up the PixeLAW Core](../getting-started/quick-start-mud.md) environment locally.
 
+## PixeLAW in 15 minutes
+
+Lets check out the folder structure first of the [App Template](https://github.com/themetacat/pixelaw_app_template_mud):
+
+- **`contracts/` contains all your solidity contracts and scripts for deployment**
+  - `src/` contains your app's codegen and logic.
+    - `codegen/` contains your app's store codegen and contracts interface.
+    - `core_codegen/` contains PixeLAW Core's store codegen and contracts interface.
+    - `systems/` contains your app's logic contract.
+  - `test/` contains your app's test contract.
+  - `script/` contains your app's extension contract.
+  - `scripts/` contains scripts for deployment.
+    - `deploy.sh` deploy your app contract and init your app.
+    - `upload_json.sh` upload your abi to github.
+  - `mud.config.ts` your app's table and namespace config.
+  - `.env` contains the values required to deploy the MUD and PixeLAW core
+
+The default App Template includes the contract code of Paint App which allows users to paint any pixel with any color.
+
+You can either directly [deploy it to the Core](2-deploy-app-mud.md) or adjust the code as you see fit.
+
+Let's dive into the code of the [App Template](https://github.com/themetacat/pixelaw_app_template_mud/tree/main).
+
+### Imports
+
+At first we require certain imports from the core to enable our paint app. Depending on your use case you might require different imports. Refer to the [PixeLAW Core](https://github.com/themetacat/pixelaw_core),
+
+```solidity
+import { System } from "@latticexyz/world/src/System.sol";
+import { ICoreSystem } from "../core_codegen/world/ICoreSystem.sol";
+import { PermissionsData, DefaultParameters, Position, PixelUpdateData, Pixel, PixelData, TestParameters } from "../core_codegen/index.sol";
+```
+
+### Declaring your App
+
+1. The **APP_ICON** will define the icon shown on the front-end to select your app.
+
+
+2. The **NAMESPACE** is the namespace you set in mud.config.ts, which is the namespace after the current app contract is deployed.
+
+3. The **SYSTEM_NAME** is the system name set for the current contract in systems of mud.config.ts
+
+4. The **APP_NAME** is the unique username of your app, and has to be the same across the entire platform.
+
+5. The **APP_MANIFEST** simply has to be adjusted according to your APP_NAME.
+
+```solidity
+// Core only supports unicode icons for now
+string constant APP_ICON = 'U+1F58B';
+
+// The NAMESPACE and SYSTEM_NAME of the current contract in mudConfig
+string constant NAMESPACE = 'myapp';
+string constant SYSTEM_NAME = 'MyAppSystem';
+
+// APP_NAME must be unique across the entire platform
+string constant APP_NAME = 'myapp';
+
+// prefixing with BASE means using the server's default abi.json handler, the following is consistent with the current contract name.
+string constant APP_MANIFEST = 'BASE/MyAppSystem';
+```
+
+### App Contract
+The `init` and `interact` function are required for any PixeLAW App.
+
+Additionally, we provide the permission to another app called Snake to interact with any Pixel occupied by our app.
+```solidity
+function init() public {
+    
+    // init my app
+    ICoreSystem(_world()).update_app(APP_NAME, APP_ICON, APP_MANIFEST, NAMESPACE, SYSTEM_NAME);
+
+    // Grant permission to the snake App
+    ICoreSystem(_world()).update_permission("snake", 
+    PermissionsData({
+      app: true, color: true, owner: true, text: true, timestamp: false, action: false
+      })); 
+  }
+
+```
+Now that we get to the interact function, which is called by default by the front end unless otherwise specified. 
+
+Most importantly it calls the `ICoreSystem(_world()).update_pixel` to change the color of a pixel that has been clicked.
+
+When calling update_pixel, if you do not want to set a value for one of the parameters or change the original value of the pixel, please do this:
+
+If the parameter type is address, please pass in address(1),
+If the parameter type is string, please pass in "_Null"
+This will automatically skip the permission check and assignment of the parameter.
+
+```solidity
+  //Put color on a certain position
+  // Arguments
+  //`position` - Position of the pixel.
+  //`new_color` - Color to set the pixel to.
+  function interact(DefaultParameters memory default_parameters) public {
+    // Load important variables
+    Position memory position = default_parameters.position;
+    address player = default_parameters.for_player;
+    string memory app = default_parameters.for_app;
+
+    // Load the Pixel
+    PixelData memory pixel = Pixel.get(position.x, position.y);
+
+    // TODO: Load MyApp App Settings like the fade steptime
+    // For example for the Cooldown feature
+    uint256 COOLDOWN_SECS = 5;
+
+    // Check if 5 seconds have passed or if the sender is the owner
+    require(pixel.owner == address(0) || pixel.owner == player || block.timestamp - pixel.timestamp < COOLDOWN_SECS, 'Cooldown not over');
+
+    // We can now update color of the pixel
+
+    // If you don't want to assign a value of type address(like owner), you should pass in address(1)
+    // If you don't want to assign a value of type string(like app、color、text...), you should pass in "_Null"
+    ICoreSystem(_world()).update_pixel(
+      PixelUpdateData({
+        x: position.x,
+        y: position.y,
+        color: default_parameters.color,
+        timestamp: 0,
+        text: "_Null",
+        app: app,
+        owner: player,
+        action: "_Null"
+      }));
+  }
+  
+```
+
+The above specifies the same functionality like our Paint App. Feel free to [deploy it locally](./2-deploy-app-mud.md), make changes and try it out.
+
+## Next Steps
+
+The guide above should get you familiar with how the Paint App is structured. The next step would be to:
+- [Deploy your app](./2-deploy-app-mud.md) to the front-end.
+- Check out other [tutorials](../how-to-play/tutorials.md) of other PixeLAW Apps.
+- Check out the [PixeLAW Core](https://github.com/themetacat/pixelaw_core/tree/main).

src/build-app/2-deploy-app-mud.md

@@ -1,2 +1,75 @@
 # Deploy your app locally
 
+## Building your contracts
+Before deploy your smart contracts, you should run the following to compile the solidity contracts.
+Make sure you are currently in the `pixelaw_app_template_mud/contracts/`
+````sh
+pnpm mud build
+````
+
+## Deploy/Update your App:
+This will deploy your contracts to the local PixeLAW world and init your app.
+##### If the app contract is deployed for the first time: 
+```sh
+pnpm run deploy
+```
+
+##### If you want to update a deployed app：
+First comment out the registerNamespace and registerFunctionSelector parts in ./script/MyAppExtension.s.sol:
+```solidity
+// world.registerNamespace(namespaceResource);
+
+// world.registerFunctionSelector(systemResource, "init()");
+// world.registerFunctionSelector(systemResource, "interact((address,string,(uint32,uint32),string))");
+```
+then:
+```sh
+pnpm run deploy INIT=false
+```
+
+#### Upload your ABI JSON:
+```sh
+pnpm run upload
+```
+Awesome, you just successfully deployed your own PixeLAW App! If you fail, please read [app_template README](https://github.com/themetacat/pixelaw_app_template_mud/tree/main) to see another way to deploy.
+
+### Deploying to Demo
+
+#### Building your contracts:
+```sh
+pnpm mud build
+```
+
+#### Deploy/Update your App:
+##### If the app contract is deployed for the first time: 
+```sh
+pnpm run deploy RPC_URL=<replace-this-with-provided-rpc-url> CHAIN_ID=<replace-this-with-chain-id>
+```
+
+##### If you want to update a deployed app：
+First comment out the registerNamespace and registerFunctionSelector parts in ./script/MyAppExtension.s.sol:
+```solidity
+// world.registerNamespace(namespaceResource);
+
+// world.registerFunctionSelector(systemResource, "init()");
+// world.registerFunctionSelector(systemResource, "interact((address,string,(uint32,uint32),string))");
+```
+then:
+```sh
+pnpm run deploy INIT=false RPC_URL=<replace-this-with-provided-rpc-url> CHAIN_ID=<replace-this-with-chain-id>
+```
+
+#### Upload your ABI JSON:
+```sh
+pnpm run upload
+```
+
+## Command
+### pnpm run deploy
+##### if you set RPC_URL, you should set CHAIN_ID
+```sh
+pnpm run deploy
+    INIT if INIT=false,update the system, default true
+    RPC_URL, default http://127.0.0.1:8545
+    CHAIN_ID, default 31337
+```

src/getting-started/quick-start-mud.md

@@ -26,20 +26,23 @@ git clone https://github.com/themetacat/pixelaw_core pixelaw_core
 
 To make sure everything is working correctly, run the following command to do all things:
 
-```console
-cd pixelaw_core && chmod u+x ./start.sh && ./start.sh
+```sh
+cd pixelaw_core && pnpm install
+```
+```sh
+pnpm run start
 ```
 
 After some time (around 10 minute) you should be able to see PixeLAW running on [http://localhost:3000](http://localhost:3000).
 
 You should be able to see PixeLAW in its true glory: ![PixelCore](../images/PixelCore.png)
 
-If you run into any issues you can check out the [github repo](https://github.com/pixelaw/app_template/tree/main), and read [start.sh](https://github.com/themetacat/pixelaw_core/blob/main/start.sh) to see the build and deploy details.
+If you run into any issues you can check out the [github repo](https://github.com/themetacat/pixelaw_app_template_mud/tree/main), and read [start.sh](https://github.com/themetacat/pixelaw_core/blob/main/start.sh) to see the build and deploy details.
 
 ## Next Step
 
 Awesome, you just successfully deployed the Pixel Core. 
 
 The next step should be for you to build your own PixeLAW App. We will remain in the `app_template_mud` repo.
 
-Go and be a Pixel Builder and [deploy your own App to the core](../build-app/build-app-mud.md)!
+Go and be a Pixel Builder and [deploy your own App to the core](../build-app/1-build-app-mud.md)!