From 18d7889b79465d3a3b92ad275cfe73d2350718e3 Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Thu, 3 Aug 2023 12:37:03 -0500 Subject: [PATCH 01/25] WIP --- docs/pages/tutorials/minimal.mdx | 1 + docs/pages/tutorials/minimal/_meta.js | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/pages/tutorials/minimal.mdx b/docs/pages/tutorials/minimal.mdx index 644660a556..a7bda13506 100644 --- a/docs/pages/tutorials/minimal.mdx +++ b/docs/pages/tutorials/minimal.mdx @@ -28,4 +28,5 @@ To create the basic version to modify, follow these steps: ## The tutorials +- [Extend the schema](minimal/extend_schema) - [Add a system](minimal/add_system) diff --git a/docs/pages/tutorials/minimal/_meta.js b/docs/pages/tutorials/minimal/_meta.js index ffb5e33673..ea7c122f4b 100644 --- a/docs/pages/tutorials/minimal/_meta.js +++ b/docs/pages/tutorials/minimal/_meta.js @@ -1,3 +1,4 @@ export default { - "add_system": "Add a system" + "extend_schema": "Extend the schema", + "add_system": "Add a system", }; From d608f46399224e4a7ccaced721ec7de2c8302ab0 Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Thu, 3 Aug 2023 12:40:57 -0500 Subject: [PATCH 02/25] WIP --- .../pages/tutorials/minimal/extend_schema.mdx | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 docs/pages/tutorials/minimal/extend_schema.mdx diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx new file mode 100644 index 0000000000..5c31535459 --- /dev/null +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -0,0 +1,174 @@ +# Extend the schema + +In this tutorial you extend the schema to add a table of historical counter values and the time in which the counter reached those values. +For the sake of simplicity, we will implement this in the `increment` function rather than use a [storage hook](/store/advanced-features#storage-hooks). + +## Modify the MUD configuration file + +1. In an editor, open `packages/contracts/mud.config.ts` and add this table definition: + + ```ts + History: { + keySchema: { + counterValue: "uint32", + }, + schema: { + blockNumber: "uint256", + time: "uint256" + } + }, + ``` + +
+The complete file +```ts + import { mudConfig } from "@latticexyz/world/register"; + + export default mudConfig({ + tables: { + Counter: { + keySchema: {}, + schema: "uint32", + }, + History: { + keySchema: { + counterValue: "uint32", + }, + schema: { + blockNumber: "uint256", + time: "uint256" + } + }, + }, + }); + + ``` +
+ + ``` + +1. Run this command in `packages/contracts` to regenerate the code. + + ```sh + pnpm build:mud + ``` + +## Update `IncrementSystem` + +1. In an editor, open `packages/contracts/src/systems/IncrementSystem.sol`. + + - Modify the second `import` line to import `History`. + + ```solidity + import { Counter, History, HistoryData } from "../codegen/Tables.sol"; + ``` + + - Modify the `increment` function to also update `History` by adding this line just before `return newValue`. + + ```solidity + History.set(newValue, block.number, block.timestamp); + ``` + + To see the exact functions that are available, you can look at `packages/contracts/src/codegen/tables/History.sol` (that is the reason we regenerated it). + +
+ The complete file + ```solidity + // SPDX-License-Identifier: MIT + pragma solidity >=0.8.0; + + import { System } from "@latticexyz/world/src/System.sol"; + import { Counter, History, HistoryData } from "../codegen/Tables.sol"; + + contract IncrementSystem is System { + function increment() public returns (uint32) { + uint32 counter = Counter.get(); + uint32 newValue = counter + 1; + Counter.set(newValue); + History.set(newValue, block.number, block.timestamp); + return newValue; + } + } + + ``` +
+ + ``` + +1. Run this command in `packages/contracts` to rebuild everything this package produces. + + ```sh + pnpm build + ``` + +## Update the user interface + +You can already run the application and see in the MUD Dev Tools that there is a `:History` table and it gets updates when you click **Increment**. +However, you can also add the history to the user interface. +The directions here apply to the `vanilla` user interface, if you use anything else you'll need to modify them as appropriate. + +1. Install `store-cache`. + Run this command in `packages/client`. + + ```sh + pnpm install @latticexyz/store-cache + ``` + +1. Edit `packages/clients/index.html` to add these lines just before ``. + + ```html +
+

+ History for value: + +

+ + + + + + + + + +
Block numberTime
+ ``` + +
+ The complete file + ``` blah ``` +
+ +1. Edit `packages/client/src/mud/createSystemCalls.ts` to add `readHistory`. + + ```typescript + + ``` + +
+ The complete file + ``` blah ``` +
+ +1. Edit `packages/client/src/index.ts`. + + - Import `getComponentValue`. + + ```typescript + import { getComponentValue } from "@latticexyz/recs"; + ``` + + - In `components.Counter.update$.subscribe`, add code that updates the selection of history values. + + ```typescript + let options: String = ""; + for (let i = 0; i < nextValue?.value; i++) { + options += ``; + } + document.getElementById("historyValue")!.innerHTML = options; + ``` + +
+ The complete file + ``` blah ``` +
{" "} From 0142f2202cd9f1e88561bad22804935d7cc1e587 Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Mon, 7 Aug 2023 15:52:23 -0500 Subject: [PATCH 03/25] WIP --- .../pages/tutorials/minimal/extend_schema.mdx | 133 ++++++++++-------- 1 file changed, 74 insertions(+), 59 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index 5c31535459..fa5fe54f7d 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -19,9 +19,9 @@ For the sake of simplicity, we will implement this in the `increment` function r }, ``` -
-The complete file -```ts +
+ The complete file + ```ts import { mudConfig } from "@latticexyz/world/register"; export default mudConfig({ @@ -55,51 +55,66 @@ For the sake of simplicity, we will implement this in the `increment` function r ## Update `IncrementSystem` -1. In an editor, open `packages/contracts/src/systems/IncrementSystem.sol`. +1. In an editor, open `packages/contracts/src/systems/IncrementSystem.sol`. - - Modify the second `import` line to import `History`. + - Modify the second `import` line to import `History`. - ```solidity - import { Counter, History, HistoryData } from "../codegen/Tables.sol"; - ``` + ```solidity + import { Counter, History, HistoryData } from "../codegen/Tables.sol"; + ``` - - Modify the `increment` function to also update `History` by adding this line just before `return newValue`. + - Modify the `increment` function to also update `History` by adding this line just before `return newValue`. - ```solidity - History.set(newValue, block.number, block.timestamp); - ``` + ```solidity + History.set(newValue, block.number, block.timestamp); + ``` - To see the exact functions that are available, you can look at `packages/contracts/src/codegen/tables/History.sol` (that is the reason we regenerated it). + To see the exact functions that are available, you can look at `packages/contracts/src/codegen/tables/History.sol` (that is the reason we regenerated it). + + - Create a function to read the history. + + ```solidity + function readHistory(uint32 counterValue) public returns (uint blockNumber, uint timestamp) { + HistoryData memory retval = History.get(counterValue); + return (retval.blockNumber, retval.time); + } + ```
- The complete file - ```solidity - // SPDX-License-Identifier: MIT - pragma solidity >=0.8.0; - - import { System } from "@latticexyz/world/src/System.sol"; - import { Counter, History, HistoryData } from "../codegen/Tables.sol"; - - contract IncrementSystem is System { - function increment() public returns (uint32) { - uint32 counter = Counter.get(); - uint32 newValue = counter + 1; - Counter.set(newValue); - History.set(newValue, block.number, block.timestamp); - return newValue; - } - } + The complete file + ```solidity + // SPDX-License-Identifier: MIT + pragma solidity >=0.8.0; - ``` -
+ import { System } from "@latticexyz/world/src/System.sol"; + import { Counter, History, HistoryData } from "../codegen/Tables.sol"; - ``` + contract IncrementSystem is System { + function increment() public returns (uint32) { + uint32 counter = Counter.get(); + uint32 newValue = counter + 1; + Counter.set(newValue); + History.set(newValue, block.number, block.timestamp); + return newValue; + } -1. Run this command in `packages/contracts` to rebuild everything this package produces. + function readHistory(uint32 counterValue) public returns (uint blockNumber, uint timestamp) { + HistoryData memory retval = History.get(counterValue); + return (retval.blockNumber, retval.time); + } - ```sh - pnpm build - ``` + } + + ``` +
+ + ``` + +1. Run this command in `packages/contracts` to rebuild everything this package produces. + + ```sh + pnpm build + ``` ## Update the user interface @@ -120,7 +135,7 @@ The directions here apply to the `vanilla` user interface, if you use anything e

History for value: - +

@@ -134,28 +149,17 @@ The directions here apply to the `vanilla` user interface, if you use anything e
``` -
- The complete file - ``` blah ``` -
- -1. Edit `packages/client/src/mud/createSystemCalls.ts` to add `readHistory`. - - ```typescript - - ``` - -
- The complete file - ``` blah ``` -
+
+ The complete file + ``` blah ``` +
1. Edit `packages/client/src/index.ts`. - - Import `getComponentValue`. + - Get `readHistory` from the system calls. ```typescript - import { getComponentValue } from "@latticexyz/recs"; + ``` - In `components.Counter.update$.subscribe`, add code that updates the selection of history values. @@ -168,7 +172,18 @@ The directions here apply to the `vanilla` user interface, if you use anything e document.getElementById("historyValue")!.innerHTML = options; ``` -
- The complete file - ``` blah ``` -
{" "} +
+ The complete file + ``` blah ``` +
+ +1. Edit `packages/client/src/mud/createSystemCalls.ts` to add `readHistory`. + +```typescript +vlah; +``` + +
+ The complete file + ``` blah ``` +
From 3050d81d5cb7dafeb6cc445ec0bc04487bbbd1a2 Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Tue, 8 Aug 2023 07:57:14 -0500 Subject: [PATCH 04/25] WIP --- .../pages/tutorials/minimal/extend_schema.mdx | 148 +++++++----------- 1 file changed, 60 insertions(+), 88 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index fa5fe54f7d..fc82cbcdbe 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -19,34 +19,37 @@ For the sake of simplicity, we will implement this in the `increment` function r }, ``` -
- The complete file - ```ts - import { mudConfig } from "@latticexyz/world/register"; +
+The complete file + + ```ts + import { mudConfig } from "@latticexyz/world/register"; export default mudConfig({ - tables: { - Counter: { - keySchema: {}, - schema: "uint32", - }, - History: { - keySchema: { - counterValue: "uint32", - }, - schema: { - blockNumber: "uint256", - time: "uint256" - } - }, - }, + tables: { + Counter: { + keySchema: {}, + schema: "uint32", + }, + History: { + keySchema: { + counterValue: "uint32", + }, + schema: { + blockNumber: "uint256", + time: "uint256", + }, + }, + }, }); - ``` +
``` + ``` + 1. Run this command in `packages/contracts` to regenerate the code. ```sh @@ -55,66 +58,51 @@ For the sake of simplicity, we will implement this in the `increment` function r ## Update `IncrementSystem` -1. In an editor, open `packages/contracts/src/systems/IncrementSystem.sol`. - - - Modify the second `import` line to import `History`. +1. In an editor, open `packages/contracts/src/systems/IncrementSystem.sol`. - ```solidity - import { Counter, History, HistoryData } from "../codegen/Tables.sol"; - ``` + - Modify the second `import` line to import `History`. - - Modify the `increment` function to also update `History` by adding this line just before `return newValue`. - - ```solidity - History.set(newValue, block.number, block.timestamp); - ``` - - To see the exact functions that are available, you can look at `packages/contracts/src/codegen/tables/History.sol` (that is the reason we regenerated it). - - - Create a function to read the history. + ```solidity + import { Counter, History, HistoryData } from "../codegen/Tables.sol"; + ``` - ```solidity - function readHistory(uint32 counterValue) public returns (uint blockNumber, uint timestamp) { - HistoryData memory retval = History.get(counterValue); - return (retval.blockNumber, retval.time); - } - ``` + - Modify the `increment` function to also update `History` by adding this line just before `return newValue`. -
- The complete file - ```solidity - // SPDX-License-Identifier: MIT - pragma solidity >=0.8.0; + ```solidity + History.set(newValue, block.number, block.timestamp); + ``` - import { System } from "@latticexyz/world/src/System.sol"; - import { Counter, History, HistoryData } from "../codegen/Tables.sol"; + To see the exact functions that are available, you can look at `packages/contracts/src/codegen/tables/History.sol` (that is the reason we ran `pnpm build:mud`). - contract IncrementSystem is System { - function increment() public returns (uint32) { - uint32 counter = Counter.get(); - uint32 newValue = counter + 1; - Counter.set(newValue); - History.set(newValue, block.number, block.timestamp); - return newValue; - } +
+The complete file +```solidity +// SPDX-License-Identifier: MIT +pragma solidity >=0.8.0; - function readHistory(uint32 counterValue) public returns (uint blockNumber, uint timestamp) { - HistoryData memory retval = History.get(counterValue); - return (retval.blockNumber, retval.time); - } + import { System } from "@latticexyz/world/src/System.sol"; + import { Counter, History, HistoryData } from "../codegen/Tables.sol"; - } + contract IncrementSystem is System { + function increment() public returns (uint32) { + uint32 counter = Counter.get(); + uint32 newValue = counter + 1; + Counter.set(newValue); + History.set(newValue, block.number, block.timestamp); + return newValue; + } + } - ``` -
+ ``` +
- ``` + ``` -1. Run this command in `packages/contracts` to rebuild everything this package produces. +1. Run this command in `packages/contracts` to rebuild everything this package produces. - ```sh - pnpm build - ``` + ```sh + pnpm build + ``` ## Update the user interface @@ -122,11 +110,12 @@ You can already run the application and see in the MUD Dev Tools that there is a However, you can also add the history to the user interface. The directions here apply to the `vanilla` user interface, if you use anything else you'll need to modify them as appropriate. -1. Install `store-cache`. - Run this command in `packages/client`. +1. Install additional packages. + Run these commands in `packages/client`. ```sh - pnpm install @latticexyz/store-cache + pnpm install @latticexyz/store-cache@next + pnpm install @latticexyz/store-sync@next ``` 1. Edit `packages/clients/index.html` to add these lines just before ``. @@ -156,12 +145,6 @@ The directions here apply to the `vanilla` user interface, if you use anything e 1. Edit `packages/client/src/index.ts`. - - Get `readHistory` from the system calls. - - ```typescript - - ``` - - In `components.Counter.update$.subscribe`, add code that updates the selection of history values. ```typescript @@ -176,14 +159,3 @@ The directions here apply to the `vanilla` user interface, if you use anything e The complete file ``` blah ```
- -1. Edit `packages/client/src/mud/createSystemCalls.ts` to add `readHistory`. - -```typescript -vlah; -``` - -
- The complete file - ``` blah ``` -
From ee0b8494269ba5eba14b63a37326561bc10e791e Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Tue, 8 Aug 2023 08:19:05 -0500 Subject: [PATCH 05/25] WIP --- docs/pages/tutorials/minimal/extend_schema.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index fc82cbcdbe..dabb626bb8 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -20,7 +20,7 @@ For the sake of simplicity, we will implement this in the `increment` function r ```
-The complete file + The complete file ```ts import { mudConfig } from "@latticexyz/world/register"; From 1f3bf2ec4cf42f9014d8e198e01b8ef6c31b4801 Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Tue, 8 Aug 2023 08:20:52 -0500 Subject: [PATCH 06/25] WIP --- .../pages/tutorials/minimal/extend_schema.mdx | 37 ++++++++++--------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index dabb626bb8..898d651f60 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -20,7 +20,7 @@ For the sake of simplicity, we will implement this in the `increment` function r ```
- The complete file + The complete file ```ts import { mudConfig } from "@latticexyz/world/register"; @@ -74,35 +74,36 @@ For the sake of simplicity, we will implement this in the `increment` function r To see the exact functions that are available, you can look at `packages/contracts/src/codegen/tables/History.sol` (that is the reason we ran `pnpm build:mud`). -
+
The complete file + ```solidity // SPDX-License-Identifier: MIT pragma solidity >=0.8.0; - import { System } from "@latticexyz/world/src/System.sol"; - import { Counter, History, HistoryData } from "../codegen/Tables.sol"; +import { System } from "@latticexyz/world/src/System.sol"; +import { Counter, History, HistoryData } from "../codegen/Tables.sol"; - contract IncrementSystem is System { - function increment() public returns (uint32) { - uint32 counter = Counter.get(); - uint32 newValue = counter + 1; - Counter.set(newValue); - History.set(newValue, block.number, block.timestamp); - return newValue; - } - } +contract IncrementSystem is System { + function increment() public returns (uint32) { + uint32 counter = Counter.get(); + uint32 newValue = counter + 1; + Counter.set(newValue); + History.set(newValue, block.number, block.timestamp); + return newValue; + } +} +``` - ```
- ``` +```` 1. Run this command in `packages/contracts` to rebuild everything this package produces. - ```sh - pnpm build - ``` +```sh +pnpm build +```` ## Update the user interface From 4af93aa225e0a091a12c6a8da0b8bc822b3b0bea Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Tue, 8 Aug 2023 08:23:12 -0500 Subject: [PATCH 07/25] WIP --- .../pages/tutorials/minimal/extend_schema.mdx | 38 ++++++++++--------- 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index 898d651f60..658a5620c8 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -20,7 +20,7 @@ For the sake of simplicity, we will implement this in the `increment` function r ```
- The complete file +The complete file ```ts import { mudConfig } from "@latticexyz/world/register"; @@ -75,27 +75,29 @@ For the sake of simplicity, we will implement this in the `increment` function r To see the exact functions that are available, you can look at `packages/contracts/src/codegen/tables/History.sol` (that is the reason we ran `pnpm build:mud`).
-The complete file + + The complete file + -```solidity -// SPDX-License-Identifier: MIT -pragma solidity >=0.8.0; + ```solidity + // SPDX-License-Identifier: MIT + pragma solidity >=0.8.0; -import { System } from "@latticexyz/world/src/System.sol"; -import { Counter, History, HistoryData } from "../codegen/Tables.sol"; + import { System } from "@latticexyz/world/src/System.sol"; + import { Counter, History, HistoryData } from "../codegen/Tables.sol"; -contract IncrementSystem is System { - function increment() public returns (uint32) { - uint32 counter = Counter.get(); - uint32 newValue = counter + 1; - Counter.set(newValue); - History.set(newValue, block.number, block.timestamp); - return newValue; - } -} -``` + contract IncrementSystem is System { + function increment() public returns (uint32) { + uint32 counter = Counter.get(); + uint32 newValue = counter + 1; + Counter.set(newValue); + History.set(newValue, block.number, block.timestamp); + return newValue; + } + } + ``` -
+
```` From 12083faec8d26dcb2066117e6eb56b076918c47b Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Tue, 8 Aug 2023 09:17:20 -0500 Subject: [PATCH 08/25] WIP --- .../pages/tutorials/minimal/extend_schema.mdx | 64 +++++++++---------- 1 file changed, 29 insertions(+), 35 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index 658a5620c8..b6f3aa941c 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -19,38 +19,34 @@ For the sake of simplicity, we will implement this in the `increment` function r }, ``` -
+
The complete file - ```ts - import { mudConfig } from "@latticexyz/world/register"; - - export default mudConfig({ - tables: { - Counter: { - keySchema: {}, - schema: "uint32", - }, - History: { - keySchema: { - counterValue: "uint32", - }, - schema: { - blockNumber: "uint256", - time: "uint256", - }, - }, - }, - }); - ``` - -
- - ``` +```ts +import { mudConfig } from "@latticexyz/world/register"; + +export default mudConfig({ + tables: { + Counter: { + keySchema: {}, + schema: "uint32", + }, + History: { + keySchema: { + counterValue: "uint32", + }, + schema: { + blockNumber: "uint256", + time: "uint256", + }, + }, + }, +}); +``` - ``` +
-1. Run this command in `packages/contracts` to regenerate the code. +2. Run this command in `packages/contracts` to regenerate the code. ```sh pnpm build:mud @@ -74,7 +70,7 @@ For the sake of simplicity, we will implement this in the `increment` function r To see the exact functions that are available, you can look at `packages/contracts/src/codegen/tables/History.sol` (that is the reason we ran `pnpm build:mud`). -
+
The complete file @@ -97,15 +93,13 @@ For the sake of simplicity, we will implement this in the `increment` function r } ``` -
- -```` +
-1. Run this command in `packages/contracts` to rebuild everything this package produces. +2. Run this command in `packages/contracts` to rebuild everything this package produces. ```sh pnpm build -```` +``` ## Update the user interface @@ -146,7 +140,7 @@ The directions here apply to the `vanilla` user interface, if you use anything e ``` blah ```
-1. Edit `packages/client/src/index.ts`. +3. Edit `packages/client/src/index.ts`. - In `components.Counter.update$.subscribe`, add code that updates the selection of history values. From c931df385630753e8f80c0712bad2bbc2247e151 Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Wed, 9 Aug 2023 18:39:43 -0500 Subject: [PATCH 09/25] WIP --- .../pages/tutorials/minimal/extend_schema.mdx | 112 +++++++++++++++++- 1 file changed, 108 insertions(+), 4 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index b6f3aa941c..60e83b3eca 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -46,6 +46,16 @@ export default mudConfig({
+
+Explanation + +A MUD table has two schemas: + +- `keySchema`, which is the key used to find entries +- `schema`, which is the value + +
+ 2. Run this command in `packages/contracts` to regenerate the code. ```sh @@ -104,6 +114,8 @@ pnpm build ## Update the user interface You can already run the application and see in the MUD Dev Tools that there is a `:History` table and it gets updates when you click **Increment**. +Click the **Store data** tab and select the table **:History**. + However, you can also add the history to the user interface. The directions here apply to the `vanilla` user interface, if you use anything else you'll need to modify them as appropriate. @@ -111,8 +123,7 @@ The directions here apply to the `vanilla` user interface, if you use anything e Run these commands in `packages/client`. ```sh - pnpm install @latticexyz/store-cache@next - pnpm install @latticexyz/store-sync@next + pnpm install @latticexyz/store-cache@main @latticexyz/store-sync@main ``` 1. Edit `packages/clients/index.html` to add these lines just before ``. @@ -137,11 +148,50 @@ The directions here apply to the `vanilla` user interface, if you use anything e
The complete file - ``` blah ``` + ```html + + + + + + a minimal MUD client + + + +
Counter: 0
+ + +{" "} +
+

+ History for value: + +

+ + + + + + + + + +
Block numberTime
+ + + + ```
3. Edit `packages/client/src/index.ts`. + - Import two more functions we need. + + ```typescript + import { encodeEntity } from "@latticexyz/store-sync/recs"; + import { getComponentValueStrict } from "@latticexyz/recs"; + ``` + - In `components.Counter.update$.subscribe`, add code that updates the selection of history values. ```typescript @@ -152,7 +202,61 @@ The directions here apply to the `vanilla` user interface, if you use anything e document.getElementById("historyValue")!.innerHTML = options; ``` + - Add this function, called when the user selects a different option. + + ```typescript + (window as any).readHistory = async (counterValue) => { + const History = components.History; + const entity = encodeEntity(History.metadata.keySchema, { counterValue }); + const { blockNumber, time } = getComponentValueStrict(History, entity); + document.getElementById("blockNumber")!.innerHTML = blockNumber; + document.getElementById("timeStamp")!.innerHTML = new Date(parseInt(time.toString()) * 1000); + }; + ``` +
The complete file - ``` blah ``` +``` +import { mount as mountDevTools } from "@latticexyz/dev-tools"; +import { setup } from "./mud/setup"; +import { encodeEntity } from "@latticexyz/store-sync/recs"; +import { getComponentValueStrict } from "@latticexyz/recs"; + +const { +components, +systemCalls: { increment }, +} = await setup(); + +// Components expose a stream that triggers when the component is updated. +components.Counter.update$.subscribe((update) => { +const [nextValue, prevValue] = update.value; +console.log("Counter updated", update, { nextValue, prevValue }); +document.getElementById("counter")!.innerHTML = String(nextValue?.value ?? "unset"); + +let options: String = ""; +for (let i = 0; i < nextValue?.value; i++) { +options += ``; +} +document.getElementById("historyValue")!.innerHTML = options; +}); + +// Just for demonstration purposes: we create a global function that can be +// called to invoke the Increment system contract via the world. +// (See IncrementSystem.sol) +(window as any).increment = async () => { +console.log("new counter value:", await increment()); +}; + +(window as any).readHistory = async counterValue => { +const History = components.History +const entity = encodeEntity(History.metadata.keySchema, { counterValue }); +const { blockNumber, time } = getComponentValueStrict(History, entity); +document.getElementById("blockNumber")!.innerHTML = blockNumber +document.getElementById("timeStamp")!.innerHTML = new Date(parseInt(time.toString()) \* 1000) +} + +mountDevTools(); + +```
+``` From 11d32eb95242b7be6f5c5d01235b88b66ebe1366 Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Wed, 9 Aug 2023 20:56:35 -0500 Subject: [PATCH 10/25] docs: Extend schema tutorial --- .../pages/tutorials/minimal/extend_schema.mdx | 170 +++++++++++++++++- 1 file changed, 161 insertions(+), 9 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index 60e83b3eca..3bd0b00669 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -3,6 +3,15 @@ In this tutorial you extend the schema to add a table of historical counter values and the time in which the counter reached those values. For the sake of simplicity, we will implement this in the `increment` function rather than use a [storage hook](/store/advanced-features#storage-hooks). +## Setup + +Right now you need the `main` version of `mud`, not `next`. +So if you followed the directions, you need to run this command in the root directory. + +```sh +pnpm mud set-version --tag main && pnpm install +``` + ## Modify the MUD configuration file 1. In an editor, open `packages/contracts/mud.config.ts` and add this table definition: @@ -51,8 +60,13 @@ export default mudConfig({ A MUD table has two schemas: -- `keySchema`, which is the key used to find entries -- `schema`, which is the value +- `keySchema`, the key used to find entries +- `schema`, the value in the entry + +Each schema is represented is a structure with field names as keys, and the appropriate [Solidity data types](https://docs.soliditylang.org/en/latest/types.html) as their values. + +In this case, the counter value is represented as a 32 bit unsigned integer, because that is what `Counter` uses. +The block number and time are both the results of opcodes, so they are represented by the standard Solidity data type, `uint256` (unsigned 256 bit integer).
@@ -78,7 +92,7 @@ A MUD table has two schemas: History.set(newValue, block.number, block.timestamp); ``` - To see the exact functions that are available, you can look at `packages/contracts/src/codegen/tables/History.sol` (that is the reason we ran `pnpm build:mud`). + To see the exact functions that are available, you can look at `packages/contracts/src/codegen/tables/History.sol` (that is the reason we ran `pnpm build:mud` to recreate it already).
@@ -105,6 +119,35 @@ A MUD table has two schemas:
+
+Explanation + +```solidity +import { Counter, History, HistoryData } from "../codegen/Tables.sol"; +``` + +When a table has multiple fields in the value schema, MUD generates a [Solidity data structure](https://www.tutorialspoint.com/solidity/solidity_structs.htm) to hold a full value. +Here is `HistoryData`, copied from `packages/contract/src/codegen/History.sol`. + +```solidity +struct HistoryData { + uint256 blockNumber; + uint256 time; +} +``` + +Note that `IncrementSystem` doesn't need to use `HistoryData`, because it only writes to history, it doesn't read from it. +However, this is part of manipulating the schema and therefore included in this tutorial. + +```solidity +History.set(newValue, block.number, block.timestamp); +``` + +Set the value. +All MUD tables have a `.set` function with the parameters being the key schema fields in order and then the value schema fields in order. + + + 2. Run this command in `packages/contracts` to rebuild everything this package produces. ```sh @@ -162,6 +205,7 @@ The directions here apply to the `vanilla` user interface, if you use anything e {" "} +

History for value: @@ -183,6 +227,48 @@ The directions here apply to the `vanilla` user interface, if you use anything e ``` +
+Explanation + +```html +
+

+ History for value: + +

+``` + +This is the [input field](https://www.w3schools.com/tags/tag_select.asp) that lets the user select which counter value they'd like to get information about. +The `id` attribute will be used by `packages/client/src/index.ts` to set the options. The `onInput` attribute is the JavaScript code to execute when the value changes. + +```html +

+``` + +A standard [HTML table](https://www.w3schools.com/html/html_tables.asp). + +```html + + Block number + Time + + + + + +``` + +A location for the values, which will be set by `window.readHistory` in `index.ts`. + +```html + + +``` + +Terminate the row and the table in general. + +
+ 3. Edit `packages/client/src/index.ts`. - Import two more functions we need. @@ -196,7 +282,7 @@ The directions here apply to the `vanilla` user interface, if you use anything e ```typescript let options: String = ""; - for (let i = 0; i < nextValue?.value; i++) { + for (let i = 0; i <= nextValue?.value; i++) { options += ``; } document.getElementById("historyValue")!.innerHTML = options; @@ -210,7 +296,7 @@ The directions here apply to the `vanilla` user interface, if you use anything e const entity = encodeEntity(History.metadata.keySchema, { counterValue }); const { blockNumber, time } = getComponentValueStrict(History, entity); document.getElementById("blockNumber")!.innerHTML = blockNumber; - document.getElementById("timeStamp")!.innerHTML = new Date(parseInt(time.toString()) * 1000); + document.getElementById("timeStamp")!.innerHTML = new Date(Number(time) * 1000); }; ``` @@ -231,10 +317,11 @@ systemCalls: { increment }, components.Counter.update$.subscribe((update) => { const [nextValue, prevValue] = update.value; console.log("Counter updated", update, { nextValue, prevValue }); -document.getElementById("counter")!.innerHTML = String(nextValue?.value ?? "unset"); +document.getElementById("counter")!.innerHTML = +String(nextValue?.value ?? "unset"); let options: String = ""; -for (let i = 0; i < nextValue?.value; i++) { +for (let i = 0; i <= nextValue?.value; i++) { options += ``; } document.getElementById("historyValue")!.innerHTML = options; @@ -252,11 +339,76 @@ const History = components.History const entity = encodeEntity(History.metadata.keySchema, { counterValue }); const { blockNumber, time } = getComponentValueStrict(History, entity); document.getElementById("blockNumber")!.innerHTML = blockNumber -document.getElementById("timeStamp")!.innerHTML = new Date(parseInt(time.toString()) \* 1000) +document.getElementById("timeStamp")!.innerHTML = +new Date(parseInt(Number(time) \* 1000) } mountDevTools(); -``` +````
+ +
+Explanation + +```typescript +let options: String = ""; +```` + +Create `options` as an empty string. +This is the way you define a variable in TypeScript: `let : `. +Here we initialize it to the empty string. + +```typescript +for (let i = 0; i <= nextValue?.value; i++) { + options += ``; +} +``` + +Create the list of options. + +```typescript +document.getElementById("historyValue")!.innerHTML = options; ``` + +Set the internal HTML of the `historyValue` HTML tag to `options`. +Notice the exclamation mark (`!`). +`document.getElementById` may return either a tag that can be changed, or an empty value (if the parameter is not an id of any of the HTML tags). +We know that `historyValue` exists in the HTML, but the TypeScript compiler does not. +This exclamation point tells the compiler that it's OK, there will be a real value there. +[See here for additional information](https://blog.logrocket.com/understanding-exclamation-mark-typescript/). + +```typescript +(window as any).readHistory = async counterValue => { + const History = components.History + const entity = encodeEntity(History.metadata.keySchema, { counterValue }); +``` + +`encodeEntity` creates a key in the format that MUD uses, which is based on [ABI argument encoding](https://docs.soliditylang.org/en/latest/abi-spec.html#argument-encoding). + +```typescript +const { blockNumber, time } = getComponentValueStrict(History, entity); +``` + +Read the actual data. + +```typescript +document.getElementById("blockNumber")!.innerHTML = blockNumber; +``` + +Update the value in the HTML table. + +```typescript + document.getElementById("timeStamp")!.innerHTML = + new Date(parseInt(Number(time) * 1000) +} +``` + +Solidity uses [Unix time](https://en.wikipedia.org/wiki/Unix_time). +JavaScript uses a similar system, but it measures times in milliseconds. +So to get a readable date, we take the time (which is a [`BigInt`](https://www.w3schools.com/js/js_bigint.asp)), multiply it by a thousand, and then convert it to a [`Date`](https://www.w3schools.com/jsref/jsref_obj_date.asp) object. + +
+ +4. Run `pnpm` dev in the application's root directory, browse to the app URL, and click **Increment** a few times. + Then select a counter value and see that the block number and correct time are written to the HTML table. From d12f411b17d2373b1b54ed05143788d822e7ea4b Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Wed, 9 Aug 2023 21:01:14 -0500 Subject: [PATCH 11/25] WIP --- .../pages/tutorials/minimal/extend_schema.mdx | 47 +++++++++---------- 1 file changed, 22 insertions(+), 25 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index 3bd0b00669..6e34b82ab1 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -203,25 +203,21 @@ The directions here apply to the `vanilla` user interface, if you use anything e
Counter: 0
- -{" "} - -
-

- History for value: - -

- - - - - - - - - -
Block numberTime
- +
+

+ History for value: + +

+ + + + + + + + + +
Block numberTime
``` @@ -302,7 +298,7 @@ Terminate the row and the table in general.
The complete file -``` + ```typescript import { mount as mountDevTools } from "@latticexyz/dev-tools"; import { setup } from "./mud/setup"; import { encodeEntity } from "@latticexyz/store-sync/recs"; @@ -320,11 +316,12 @@ console.log("Counter updated", update, { nextValue, prevValue }); document.getElementById("counter")!.innerHTML = String(nextValue?.value ?? "unset"); -let options: String = ""; -for (let i = 0; i <= nextValue?.value; i++) { -options += ``; -} -document.getElementById("historyValue")!.innerHTML = options; + let options: String = ""; + for (let i = 0; i <= nextValue?.value; i++) { + options += ``; + } + document.getElementById("historyValue")!.innerHTML = options; + }); // Just for demonstration purposes: we create a global function that can be From 9a4bc295d9c192e7fd17562acd349419762de8ce Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Wed, 9 Aug 2023 21:03:51 -0500 Subject: [PATCH 12/25] WIP --- docs/pages/tutorials/minimal/extend_schema.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index 6e34b82ab1..db2b0af723 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -297,8 +297,8 @@ Terminate the row and the table in general. ```
- The complete file - ```typescript +The complete file +```typescript import { mount as mountDevTools } from "@latticexyz/dev-tools"; import { setup } from "./mud/setup"; import { encodeEntity } from "@latticexyz/store-sync/recs"; From 13a051d88d18eec7cbeda496261020019a50f40c Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Wed, 9 Aug 2023 21:07:29 -0500 Subject: [PATCH 13/25] WIP --- .../pages/tutorials/minimal/extend_schema.mdx | 33 ++++++++++--------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index db2b0af723..afd79c458f 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -298,23 +298,24 @@ Terminate the row and the table in general.
The complete file -```typescript + +```ts import { mount as mountDevTools } from "@latticexyz/dev-tools"; import { setup } from "./mud/setup"; import { encodeEntity } from "@latticexyz/store-sync/recs"; import { getComponentValueStrict } from "@latticexyz/recs"; const { -components, -systemCalls: { increment }, + components, + systemCalls: { increment }, } = await setup(); // Components expose a stream that triggers when the component is updated. components.Counter.update$.subscribe((update) => { -const [nextValue, prevValue] = update.value; -console.log("Counter updated", update, { nextValue, prevValue }); -document.getElementById("counter")!.innerHTML = -String(nextValue?.value ?? "unset"); + const [nextValue, prevValue] = update.value; + console.log("Counter updated", update, { nextValue, prevValue }); + document.getElementById("counter")!.innerHTML = + String(nextValue?.value ?? "unset"); let options: String = ""; for (let i = 0; i <= nextValue?.value; i++) { @@ -328,21 +329,21 @@ String(nextValue?.value ?? "unset"); // called to invoke the Increment system contract via the world. // (See IncrementSystem.sol) (window as any).increment = async () => { -console.log("new counter value:", await increment()); + console.log("new counter value:", await increment()); }; (window as any).readHistory = async counterValue => { -const History = components.History -const entity = encodeEntity(History.metadata.keySchema, { counterValue }); -const { blockNumber, time } = getComponentValueStrict(History, entity); -document.getElementById("blockNumber")!.innerHTML = blockNumber -document.getElementById("timeStamp")!.innerHTML = -new Date(parseInt(Number(time) \* 1000) + const History = components.History + const entity = encodeEntity(History.metadata.keySchema, { counterValue }); + const { blockNumber, time } = getComponentValueStrict(History, entity); + document.getElementById("blockNumber")!.innerHTML = blockNumber + document.getElementById("timeStamp")!.innerHTML = + new Date(parseInt(Number(time) \* 1000) } mountDevTools(); +``` -````
@@ -350,7 +351,7 @@ mountDevTools(); ```typescript let options: String = ""; -```` +``` Create `options` as an empty string. This is the way you define a variable in TypeScript: `let : `. From 659a2982ed8f738f69070e7bd35fe29d6fbf3f77 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Wed, 9 Aug 2023 21:12:02 -0500 Subject: [PATCH 14/25] Update tutorials.mdx --- docs/pages/tutorials.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/pages/tutorials.mdx b/docs/pages/tutorials.mdx index fb636fae49..6f019f8897 100644 --- a/docs/pages/tutorials.mdx +++ b/docs/pages/tutorials.mdx @@ -7,6 +7,8 @@ These tutorials teach you how to do various things with MUD. [These tutorials](tutorials/minimal) teach you how to make various changes to [the getting started example](https://github.com/latticexyz/mud/tree/main/examples/minimal). This is an easy way to learn how to modify MUD functionality in various ways. +- [Extend the schame](tutorials/minimal/extend_schema): + In this tutorial you extend the schema and learn how to lookup information using a key. - [Add a system](tutorials/minimal/add_system): In this tutorial you add a system to decrement the counter and update the application to use it. From a28e827bc60d3488ef18934bb0f1aa8bf3197395 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Wed, 9 Aug 2023 23:24:45 -0500 Subject: [PATCH 15/25] Update extend_schema.mdx --- docs/pages/tutorials/minimal/extend_schema.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index afd79c458f..7d3d8c4e26 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -408,5 +408,5 @@ So to get a readable date, we take the time (which is a [`BigInt`](https://www.w
-4. Run `pnpm` dev in the application's root directory, browse to the app URL, and click **Increment** a few times. +4. Run `pnpm dev` in the application's root directory, browse to the app URL, and click **Increment** a few times. Then select a counter value and see that the block number and correct time are written to the HTML table. From 5dcc2914b9dae201e5d18e4cd6a2ed0cbcfffa50 Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Thu, 10 Aug 2023 08:06:48 -0500 Subject: [PATCH 16/25] WIP --- docs/pages/tutorials/minimal/extend_schema.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index afd79c458f..f1cf1dec53 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -1,3 +1,5 @@ +import { CollapseCode } from "../../../components/CollapseCode"; + # Extend the schema In this tutorial you extend the schema to add a table of historical counter values and the time in which the counter reached those values. @@ -28,10 +30,9 @@ pnpm mud set-version --tag main && pnpm install }, ``` -
-The complete file + -```ts +```ts filename="mud.config.ts" showLineNumbers import { mudConfig } from "@latticexyz/world/register"; export default mudConfig({ @@ -53,7 +54,7 @@ export default mudConfig({ }); ``` -
+
Explanation From 4228cfeb7662481483d10f97b302df99cba18b3d Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Thu, 10 Aug 2023 08:58:47 -0500 Subject: [PATCH 17/25] docs: Use `` --- .../pages/tutorials/minimal/extend_schema.mdx | 374 +++++++----------- 1 file changed, 151 insertions(+), 223 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index 3aa6595275..c3da20a13a 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -10,51 +10,39 @@ For the sake of simplicity, we will implement this in the `increment` function r Right now you need the `main` version of `mud`, not `next`. So if you followed the directions, you need to run this command in the root directory. -```sh +```sh copy pnpm mud set-version --tag main && pnpm install ``` ## Modify the MUD configuration file -1. In an editor, open `packages/contracts/mud.config.ts` and add this table definition: - - ```ts - History: { - keySchema: { - counterValue: "uint32", - }, - schema: { - blockNumber: "uint256", - time: "uint256" - } - }, +1. In an editor, open `packages/contracts/mud.config.ts` and add a table definition for `History`. + + + + ```ts filename="mud.config.ts" showLineNumbers copy {9-17} + import { mudConfig } from "@latticexyz/world/register"; + + export default mudConfig({ + tables: { + Counter: { + keySchema: {}, + schema: "uint32", + }, + History: { + keySchema: { + counterValue: "uint32", + }, + schema: { + blockNumber: "uint256", + time: "uint256", + }, + }, + }, + }); ``` - - -```ts filename="mud.config.ts" showLineNumbers -import { mudConfig } from "@latticexyz/world/register"; - -export default mudConfig({ - tables: { - Counter: { - keySchema: {}, - schema: "uint32", - }, - History: { - keySchema: { - counterValue: "uint32", - }, - schema: { - blockNumber: "uint256", - time: "uint256", - }, - }, - }, -}); -``` - - +
Explanation @@ -73,7 +61,7 @@ The block number and time are both the results of opcodes, so they are represent 2. Run this command in `packages/contracts` to regenerate the code. - ```sh + ```sh copy pnpm build:mud ``` @@ -81,79 +69,66 @@ The block number and time are both the results of opcodes, so they are represent 1. In an editor, open `packages/contracts/src/systems/IncrementSystem.sol`. - - Modify the second `import` line to import `History`. + - Modify the second `import` line to import `History` (line 5) + - Modify the `increment` function to also update `History` (line 12). + To see the exact functions that are available, you can look at `packages/contracts/src/codegen/tables/History.sol` (that is the reason we ran `pnpm build:mud` to recreate it already). - ```solidity - import { Counter, History, HistoryData } from "../codegen/Tables.sol"; - ``` + + ```solidity filename="IncrementSystem.sol.sol" copy showLineNumbers {5, 12} + // SPDX-License-Identifier: MIT + pragma solidity >=0.8.0; - - Modify the `increment` function to also update `History` by adding this line just before `return newValue`. + import { System } from "@latticexyz/world/src/System.sol"; + import { Counter, History, HistoryData } from "../codegen/Tables.sol"; - ```solidity - History.set(newValue, block.number, block.timestamp); - ``` + contract IncrementSystem is System { + function increment() public returns (uint32) { + uint32 counter = Counter.get(); + uint32 newValue = counter + 1; + Counter.set(newValue); + History.set(newValue, block.number, block.timestamp); + return newValue; + } + } - To see the exact functions that are available, you can look at `packages/contracts/src/codegen/tables/History.sol` (that is the reason we ran `pnpm build:mud` to recreate it already). + ```` + -
- - The complete file - - - ```solidity - // SPDX-License-Identifier: MIT - pragma solidity >=0.8.0; - - import { System } from "@latticexyz/world/src/System.sol"; - import { Counter, History, HistoryData } from "../codegen/Tables.sol"; - - contract IncrementSystem is System { - function increment() public returns (uint32) { - uint32 counter = Counter.get(); - uint32 newValue = counter + 1; - Counter.set(newValue); - History.set(newValue, block.number, block.timestamp); - return newValue; - } - } - ``` - -
-
-Explanation +
+ Explanation -```solidity -import { Counter, History, HistoryData } from "../codegen/Tables.sol"; -``` + ```solidity + import { Counter, History, HistoryData } from "../codegen/Tables.sol"; + ```` -When a table has multiple fields in the value schema, MUD generates a [Solidity data structure](https://www.tutorialspoint.com/solidity/solidity_structs.htm) to hold a full value. -Here is `HistoryData`, copied from `packages/contract/src/codegen/History.sol`. + When a table has multiple fields in the value schema, MUD generates a [Solidity data structure](https://www.tutorialspoint.com/solidity/solidity_structs.htm) to hold a full value. + Here is `HistoryData`, copied from `packages/contract/src/codegen/History.sol`. -```solidity -struct HistoryData { - uint256 blockNumber; - uint256 time; -} -``` + ```solidity + struct HistoryData { + uint256 blockNumber; + uint256 time; + } + ``` -Note that `IncrementSystem` doesn't need to use `HistoryData`, because it only writes to history, it doesn't read from it. -However, this is part of manipulating the schema and therefore included in this tutorial. + Note that `IncrementSystem` doesn't need to use `HistoryData`, because it only writes to history, it doesn't read from it. + However, this is part of manipulating the schema and therefore included in this tutorial. -```solidity -History.set(newValue, block.number, block.timestamp); -``` + ```solidity + History.set(newValue, block.number, block.timestamp); + ``` -Set the value. -All MUD tables have a `.set` function with the parameters being the key schema fields in order and then the value schema fields in order. + Set the value. + All MUD tables have a `
.set` function with the parameters being the key schema fields in order and then the value schema fields in order. - + 2. Run this command in `packages/contracts` to rebuild everything this package produces. -```sh -pnpm build -``` + ```sh copy + pnpm build + ``` ## Update the user interface @@ -163,66 +138,49 @@ Click the **Store data** tab and select the table **:History**. However, you can also add the history to the user interface. The directions here apply to the `vanilla` user interface, if you use anything else you'll need to modify them as appropriate. -1. Install additional packages. - Run these commands in `packages/client`. +1. Install an additional package. + Run this command in `packages/client`. - ```sh - pnpm install @latticexyz/store-cache@main @latticexyz/store-sync@main + ```sh copy + pnpm install @latticexyz/store-sync@main ``` -1. Edit `packages/clients/index.html` to add these lines just before ``. - - ```html -
-

- History for value: - -

-
- - - - - - - - -
Block numberTime
+1. Edit `packages/clients/index.html`. + + + + ```html filename="index.html" copy showLineNumbers {12-26} + + + + + + a minimal MUD client + + + +
Counter: 0
+ +
+

+ History for value: + +

+ + + + + + + + + +
Block numberTime
+ + ``` -
- The complete file - ```html - - - - - - a minimal MUD client - - - -
Counter: 0
- -
-

- History for value: - -

- - - - - - - - - -
Block numberTime
- - - ``` -
+
Explanation @@ -258,94 +216,64 @@ A standard [HTML table](https://www.w3schools.com/html/html_tables.asp). A location for the values, which will be set by `window.readHistory` in `index.ts`. ```html - ``` -Terminate the row and the table in general. +Terminate the table in general.
3. Edit `packages/client/src/index.ts`. - - Import two more functions we need. + - Import two more functions we need (lines 3-4). + - In `components.Counter.update$.subscribe`, add code that updates the selection of history values (lines 18-22). + - Add a function that is called when the user selects a different option (lines 33-40). + + - ```typescript - import { encodeEntity } from "@latticexyz/store-sync/recs"; - import { getComponentValueStrict } from "@latticexyz/recs"; - ``` + ```ts filename="index.ts" copy showLineNumbers {3-4,18-22,33-40} + import { mount as mountDevTools } from "@latticexyz/dev-tools"; + import { setup } from "./mud/setup"; + import { encodeEntity } from "@latticexyz/store-sync/recs"; + import { getComponentValueStrict } from "@latticexyz/recs"; - - In `components.Counter.update$.subscribe`, add code that updates the selection of history values. + const { + components, + systemCalls: { increment }, + } = await setup(); + + // Components expose a stream that triggers when the component is updated. + components.Counter.update$.subscribe((update) => { + const [nextValue, prevValue] = update.value; + console.log("Counter updated", update, { nextValue, prevValue }); + document.getElementById("counter")!.innerHTML = String(nextValue?.value ?? "unset"); - ```typescript let options: String = ""; for (let i = 0; i <= nextValue?.value; i++) { options += ``; } document.getElementById("historyValue")!.innerHTML = options; - ``` - - - Add this function, called when the user selects a different option. - - ```typescript - (window as any).readHistory = async (counterValue) => { - const History = components.History; - const entity = encodeEntity(History.metadata.keySchema, { counterValue }); - const { blockNumber, time } = getComponentValueStrict(History, entity); - document.getElementById("blockNumber")!.innerHTML = blockNumber; - document.getElementById("timeStamp")!.innerHTML = new Date(Number(time) * 1000); - }; - ``` - -
-The complete file - -```ts -import { mount as mountDevTools } from "@latticexyz/dev-tools"; -import { setup } from "./mud/setup"; -import { encodeEntity } from "@latticexyz/store-sync/recs"; -import { getComponentValueStrict } from "@latticexyz/recs"; - -const { - components, - systemCalls: { increment }, -} = await setup(); - -// Components expose a stream that triggers when the component is updated. -components.Counter.update$.subscribe((update) => { - const [nextValue, prevValue] = update.value; - console.log("Counter updated", update, { nextValue, prevValue }); - document.getElementById("counter")!.innerHTML = - String(nextValue?.value ?? "unset"); - - let options: String = ""; - for (let i = 0; i <= nextValue?.value; i++) { - options += ``; - } - document.getElementById("historyValue")!.innerHTML = options; - -}); - -// Just for demonstration purposes: we create a global function that can be -// called to invoke the Increment system contract via the world. -// (See IncrementSystem.sol) -(window as any).increment = async () => { - console.log("new counter value:", await increment()); -}; - -(window as any).readHistory = async counterValue => { - const History = components.History - const entity = encodeEntity(History.metadata.keySchema, { counterValue }); - const { blockNumber, time } = getComponentValueStrict(History, entity); - document.getElementById("blockNumber")!.innerHTML = blockNumber - document.getElementById("timeStamp")!.innerHTML = - new Date(parseInt(Number(time) \* 1000) -} - -mountDevTools(); -``` + }); + + // Just for demonstration purposes: we create a global function that can be + // called to invoke the Increment system contract via the world. + // (See IncrementSystem.sol) + (window as any).increment = async () => { + console.log("new counter value:", await increment()); + }; + + (window as any).readHistory = async (counterValue) => { + const History = components.History; + const entity = encodeEntity(History.metadata.keySchema, { counterValue }); + const { blockNumber, time } = getComponentValueStrict(History, entity); + document.getElementById("blockNumber")!.innerHTML = blockNumber; + document.getElementById("timeStamp")!.innerHTML = new Date(parseInt(Number(time) * 1000)); + }; + + mountDevTools(); + ``` -
+
Explanation @@ -399,7 +327,7 @@ Update the value in the HTML table. ```typescript document.getElementById("timeStamp")!.innerHTML = - new Date(parseInt(Number(time) * 1000) + new Date(parseInt(Number(time) * 1000)) } ``` From 90a20cdcf498e044f4a161147b9a5ef2a8e58b1e Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Thu, 10 Aug 2023 09:01:18 -0500 Subject: [PATCH 18/25] WIP --- docs/pages/tutorials/minimal/extend_schema.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index c3da20a13a..8f369405d2 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -74,9 +74,9 @@ The block number and time are both the results of opcodes, so they are represent To see the exact functions that are available, you can look at `packages/contracts/src/codegen/tables/History.sol` (that is the reason we ran `pnpm build:mud` to recreate it already). - ```solidity filename="IncrementSystem.sol.sol" copy showLineNumbers {5, 12} - // SPDX-License-Identifier: MIT - pragma solidity >=0.8.0; +```solidity filename="IncrementSystem.sol.sol" copy showLineNumbers {5, 12} +// SPDX-License-Identifier: MIT +pragma solidity >=0.8.0; import { System } from "@latticexyz/world/src/System.sol"; import { Counter, History, HistoryData } from "../codegen/Tables.sol"; From e3dd651f07f2a9d69c89c66a0b9258981581890f Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Thu, 10 Aug 2023 09:03:49 -0500 Subject: [PATCH 19/25] WIP --- .../pages/tutorials/minimal/extend_schema.mdx | 68 +++++++++---------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index 8f369405d2..84ae2e427d 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -73,54 +73,54 @@ The block number and time are both the results of opcodes, so they are represent - Modify the `increment` function to also update `History` (line 12). To see the exact functions that are available, you can look at `packages/contracts/src/codegen/tables/History.sol` (that is the reason we ran `pnpm build:mud` to recreate it already). - + + ```solidity filename="IncrementSystem.sol.sol" copy showLineNumbers {5, 12} // SPDX-License-Identifier: MIT pragma solidity >=0.8.0; - import { System } from "@latticexyz/world/src/System.sol"; - import { Counter, History, HistoryData } from "../codegen/Tables.sol"; - - contract IncrementSystem is System { - function increment() public returns (uint32) { - uint32 counter = Counter.get(); - uint32 newValue = counter + 1; - Counter.set(newValue); - History.set(newValue, block.number, block.timestamp); - return newValue; - } - } - - ```` - +import { System } from "@latticexyz/world/src/System.sol"; +import { Counter, History, HistoryData } from "../codegen/Tables.sol"; + +contract IncrementSystem is System { + function increment() public returns (uint32) { + uint32 counter = Counter.get(); + uint32 newValue = counter + 1; + Counter.set(newValue); + History.set(newValue, block.number, block.timestamp); + return newValue; + } +} +``` +
Explanation - ```solidity - import { Counter, History, HistoryData } from "../codegen/Tables.sol"; - ```` +```solidity +import { Counter, History, HistoryData } from "../codegen/Tables.sol"; +``` - When a table has multiple fields in the value schema, MUD generates a [Solidity data structure](https://www.tutorialspoint.com/solidity/solidity_structs.htm) to hold a full value. - Here is `HistoryData`, copied from `packages/contract/src/codegen/History.sol`. +When a table has multiple fields in the value schema, MUD generates a [Solidity data structure](https://www.tutorialspoint.com/solidity/solidity_structs.htm) to hold a full value. +Here is `HistoryData`, copied from `packages/contract/src/codegen/History.sol`. - ```solidity - struct HistoryData { - uint256 blockNumber; - uint256 time; - } - ``` +```solidity +struct HistoryData { + uint256 blockNumber; + uint256 time; +} +``` - Note that `IncrementSystem` doesn't need to use `HistoryData`, because it only writes to history, it doesn't read from it. - However, this is part of manipulating the schema and therefore included in this tutorial. +Note that `IncrementSystem` doesn't need to use `HistoryData`, because it only writes to history, it doesn't read from it. +However, this is part of manipulating the schema and therefore included in this tutorial. - ```solidity - History.set(newValue, block.number, block.timestamp); - ``` +```solidity +History.set(newValue, block.number, block.timestamp); +``` - Set the value. - All MUD tables have a `.set` function with the parameters being the key schema fields in order and then the value schema fields in order. +Set the value. +All MUD tables have a `
.set` function with the parameters being the key schema fields in order and then the value schema fields in order. From 3124b6fc1f9623bc3e70f0185564e6e090a7286b Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Thu, 10 Aug 2023 09:14:40 -0500 Subject: [PATCH 20/25] Prettier run --- docs/pages/tutorials.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/tutorials.mdx b/docs/pages/tutorials.mdx index 6f019f8897..0673298f20 100644 --- a/docs/pages/tutorials.mdx +++ b/docs/pages/tutorials.mdx @@ -7,7 +7,7 @@ These tutorials teach you how to do various things with MUD. [These tutorials](tutorials/minimal) teach you how to make various changes to [the getting started example](https://github.com/latticexyz/mud/tree/main/examples/minimal). This is an easy way to learn how to modify MUD functionality in various ways. -- [Extend the schame](tutorials/minimal/extend_schema): +- [Extend the schame](tutorials/minimal/extend_schema): In this tutorial you extend the schema and learn how to lookup information using a key. - [Add a system](tutorials/minimal/add_system): In this tutorial you add a system to decrement the counter and update the application to use it. From 509db86662f0bd6cf07069a2919d54fa18c3d238 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Mon, 14 Aug 2023 10:06:27 -0500 Subject: [PATCH 21/25] Apply suggestions from code review Co-authored-by: alvarius --- docs/pages/tutorials.mdx | 2 +- docs/pages/tutorials/minimal/extend_schema.mdx | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/pages/tutorials.mdx b/docs/pages/tutorials.mdx index 0673298f20..d929c079b2 100644 --- a/docs/pages/tutorials.mdx +++ b/docs/pages/tutorials.mdx @@ -7,7 +7,7 @@ These tutorials teach you how to do various things with MUD. [These tutorials](tutorials/minimal) teach you how to make various changes to [the getting started example](https://github.com/latticexyz/mud/tree/main/examples/minimal). This is an easy way to learn how to modify MUD functionality in various ways. -- [Extend the schame](tutorials/minimal/extend_schema): +- [Extend the schema](tutorials/minimal/extend_schema): In this tutorial you extend the schema and learn how to lookup information using a key. - [Add a system](tutorials/minimal/add_system): In this tutorial you add a system to decrement the counter and update the application to use it. diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index 84ae2e427d..9476a47d33 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -52,14 +52,14 @@ A MUD table has two schemas: - `keySchema`, the key used to find entries - `schema`, the value in the entry -Each schema is represented is a structure with field names as keys, and the appropriate [Solidity data types](https://docs.soliditylang.org/en/latest/types.html) as their values. +Each schema is represented as a structure with field names as keys, and the appropriate [Solidity data types](https://docs.soliditylang.org/en/latest/types.html) as their values. In this case, the counter value is represented as a 32 bit unsigned integer, because that is what `Counter` uses. The block number and time are both the results of opcodes, so they are represented by the standard Solidity data type, `uint256` (unsigned 256 bit integer). -2. Run this command in `packages/contracts` to regenerate the code. +2. Run this command in `packages/contracts` to regenerate the table libraries. ```sh copy pnpm build:mud @@ -102,7 +102,7 @@ contract IncrementSystem is System { import { Counter, History, HistoryData } from "../codegen/Tables.sol"; ``` -When a table has multiple fields in the value schema, MUD generates a [Solidity data structure](https://www.tutorialspoint.com/solidity/solidity_structs.htm) to hold a full value. +When a table has multiple fields in the value schema, MUD generates a [Struct](https://www.tutorialspoint.com/solidity/solidity_structs.htm) to hold a full value. Here is `HistoryData`, copied from `packages/contract/src/codegen/History.sol`. ```solidity @@ -136,7 +136,7 @@ You can already run the application and see in the MUD Dev Tools that there is a Click the **Store data** tab and select the table **:History**. However, you can also add the history to the user interface. -The directions here apply to the `vanilla` user interface, if you use anything else you'll need to modify them as appropriate. +The directions here apply to the `vanilla` client template, if you use anything else you'll need to modify them as appropriate. 1. Install an additional package. Run this command in `packages/client`. From 30f6e8f427bb6a3e443945e8dce78ba54553cfb3 Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Mon, 14 Aug 2023 10:45:54 -0500 Subject: [PATCH 22/25] Added most comments --- .../pages/tutorials/minimal/extend_schema.mdx | 23 ++++--------------- 1 file changed, 5 insertions(+), 18 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index 9476a47d33..7ad3e86e1e 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -50,12 +50,12 @@ pnpm mud set-version --tag main && pnpm install A MUD table has two schemas: - `keySchema`, the key used to find entries -- `schema`, the value in the entry +- `schema`, the value in the entry (soon to be renamed to `valueSchema`) Each schema is represented as a structure with field names as keys, and the appropriate [Solidity data types](https://docs.soliditylang.org/en/latest/types.html) as their values. In this case, the counter value is represented as a 32 bit unsigned integer, because that is what `Counter` uses. -The block number and time are both the results of opcodes, so they are represented by the standard Solidity data type, `uint256` (unsigned 256 bit integer). +Block numbers and timestamps can be values up to `uint256`, so we'll use this type for these fields. @@ -138,13 +138,6 @@ Click the **Store data** tab and select the table **:History**. However, you can also add the history to the user interface. The directions here apply to the `vanilla` client template, if you use anything else you'll need to modify them as appropriate. -1. Install an additional package. - Run this command in `packages/client`. - - ```sh copy - pnpm install @latticexyz/store-sync@main - ``` - 1. Edit `packages/clients/index.html`. @@ -215,15 +208,9 @@ A standard [HTML table](https://www.w3schools.com/html/html_tables.asp). A location for the values, which will be set by `window.readHistory` in `index.ts`. -```html -
-``` - -Terminate the table in general. -
-3. Edit `packages/client/src/index.ts`. +2. Edit `packages/client/src/index.ts`. - Import two more functions we need (lines 3-4). - In `components.Counter.update$.subscribe`, add code that updates the selection of history values (lines 18-22). @@ -249,7 +236,7 @@ Terminate the table in general. document.getElementById("counter")!.innerHTML = String(nextValue?.value ?? "unset"); let options: String = ""; - for (let i = 0; i <= nextValue?.value; i++) { + for (let i = 1; i <= nextValue?.value; i++) { options += ``; } document.getElementById("historyValue")!.innerHTML = options; @@ -287,7 +274,7 @@ This is the way you define a variable in TypeScript: `let : ${i}`; } ``` From 513cbc01edc64406b4a3cfd6d1c531535ab795f9 Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Mon, 14 Aug 2023 11:08:14 -0500 Subject: [PATCH 23/25] Post @alvarius comments --- .../pages/tutorials/minimal/extend_schema.mdx | 151 +++++++++--------- 1 file changed, 76 insertions(+), 75 deletions(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index 7ad3e86e1e..39a1b7f884 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -138,79 +138,7 @@ Click the **Store data** tab and select the table **:History**. However, you can also add the history to the user interface. The directions here apply to the `vanilla` client template, if you use anything else you'll need to modify them as appropriate. -1. Edit `packages/clients/index.html`. - - - - ```html filename="index.html" copy showLineNumbers {12-26} - - - - - - a minimal MUD client - - - -
Counter: 0
- -
-

- History for value: - -

- - - - - - - - - -
Block numberTime
- - - ``` - - - -
-Explanation - -```html -
-

- History for value: - -

-``` - -This is the [input field](https://www.w3schools.com/tags/tag_select.asp) that lets the user select which counter value they'd like to get information about. -The `id` attribute will be used by `packages/client/src/index.ts` to set the options. The `onInput` attribute is the JavaScript code to execute when the value changes. - -```html -
-``` - -A standard [HTML table](https://www.w3schools.com/html/html_tables.asp). - -```html - - Block number - Time - - - - - -``` - -A location for the values, which will be set by `window.readHistory` in `index.ts`. - -
- -2. Edit `packages/client/src/index.ts`. +1. Edit `packages/client/src/index.ts`. - Import two more functions we need (lines 3-4). - In `components.Counter.update$.subscribe`, add code that updates the selection of history values (lines 18-22). @@ -218,7 +146,7 @@ A location for the values, which will be set by `window.readHistory` in `index.t - ```ts filename="index.ts" copy showLineNumbers {3-4,18-22,33-40} + ```ts filename="index.ts" copy showLineNumbers {3-4,18-22,31-37} import { mount as mountDevTools } from "@latticexyz/dev-tools"; import { setup } from "./mud/setup"; import { encodeEntity } from "@latticexyz/store-sync/recs"; @@ -324,5 +252,78 @@ So to get a readable date, we take the time (which is a [`BigInt`](https://www.w
-4. Run `pnpm dev` in the application's root directory, browse to the app URL, and click **Increment** a few times. +2. Edit `packages/clients/index.html`. + + + + ```html filename="index.html" copy showLineNumbers {12-26} + + + + + + a minimal MUD client + + + +
Counter: 0
+ +
+

+ History for value: + +

+ + + + + + + + + +
Block numberTime
+ + + ``` + + + +
+Explanation + +```html +
+

+ History for value: + +

+``` + +This is the [input field](https://www.w3schools.com/tags/tag_select.asp) that lets the user select which counter value they'd like to get information about. +The `id` attribute is used by `packages/client/src/index.ts` to set the options. +The `onInput` attribute is the JavaScript code to execute when the value changes. + +```html +
+``` + +A standard [HTML table](https://www.w3schools.com/html/html_tables.asp). + +```html + + Block number + Time + + + + + +``` + +A location for the values, which is set by `window.readHistory` in `index.ts`. + +
+ +3. Run `pnpm dev` in the application's root directory, browse to the app URL, and click **Increment** a few times. Then select a counter value and see that the block number and correct time are written to the HTML table. From b0f4156e3af9003cccbf064308ed2158018dbb8b Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Mon, 14 Aug 2023 11:09:09 -0500 Subject: [PATCH 24/25] tiny fix --- docs/pages/tutorials/minimal/extend_schema.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/extend_schema.mdx index 39a1b7f884..e6ddfe3913 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/extend_schema.mdx @@ -142,7 +142,7 @@ The directions here apply to the `vanilla` client template, if you use anything - Import two more functions we need (lines 3-4). - In `components.Counter.update$.subscribe`, add code that updates the selection of history values (lines 18-22). - - Add a function that is called when the user selects a different option (lines 33-40). + - Add a function that is called when the user selects a different option (lines 31-37). From fd29f81bc31edc0bb0cd2055093f1d3321c1b2e9 Mon Sep 17 00:00:00 2001 From: Ori Pomeerantz Date: Fri, 18 Aug 2023 11:40:43 -0500 Subject: [PATCH 25/25] Update with @holic comments --- docs/pages/tutorials.mdx | 4 +- docs/pages/tutorials/minimal.mdx | 2 +- docs/pages/tutorials/minimal/_meta.js | 2 +- .../{extend_schema.mdx => add-table.mdx} | 39 ++++++++++++------- 4 files changed, 28 insertions(+), 19 deletions(-) rename docs/pages/tutorials/minimal/{extend_schema.mdx => add-table.mdx} (90%) diff --git a/docs/pages/tutorials.mdx b/docs/pages/tutorials.mdx index d929c079b2..884e058554 100644 --- a/docs/pages/tutorials.mdx +++ b/docs/pages/tutorials.mdx @@ -7,8 +7,8 @@ These tutorials teach you how to do various things with MUD. [These tutorials](tutorials/minimal) teach you how to make various changes to [the getting started example](https://github.com/latticexyz/mud/tree/main/examples/minimal). This is an easy way to learn how to modify MUD functionality in various ways. -- [Extend the schema](tutorials/minimal/extend_schema): - In this tutorial you extend the schema and learn how to lookup information using a key. +- [Add a table](tutorials/minimal/add-table): + In this tutorial you add a table to preserve counter history, and learn how to lookup information using a key. - [Add a system](tutorials/minimal/add_system): In this tutorial you add a system to decrement the counter and update the application to use it. diff --git a/docs/pages/tutorials/minimal.mdx b/docs/pages/tutorials/minimal.mdx index 686569bdfc..45cbcc91bb 100644 --- a/docs/pages/tutorials/minimal.mdx +++ b/docs/pages/tutorials/minimal.mdx @@ -28,5 +28,5 @@ To create the basic version to modify, follow these steps: ## The tutorials -- [Extend the schema](minimal/extend_schema) +- [Add a table](minimal/add-table) - [Add a system](minimal/add_system) diff --git a/docs/pages/tutorials/minimal/_meta.js b/docs/pages/tutorials/minimal/_meta.js index ea7c122f4b..10a618501e 100644 --- a/docs/pages/tutorials/minimal/_meta.js +++ b/docs/pages/tutorials/minimal/_meta.js @@ -1,4 +1,4 @@ export default { - "extend_schema": "Extend the schema", + "add-table": "Add a table", "add_system": "Add a system", }; diff --git a/docs/pages/tutorials/minimal/extend_schema.mdx b/docs/pages/tutorials/minimal/add-table.mdx similarity index 90% rename from docs/pages/tutorials/minimal/extend_schema.mdx rename to docs/pages/tutorials/minimal/add-table.mdx index e6ddfe3913..39a35466a7 100644 --- a/docs/pages/tutorials/minimal/extend_schema.mdx +++ b/docs/pages/tutorials/minimal/add-table.mdx @@ -1,18 +1,13 @@ import { CollapseCode } from "../../../components/CollapseCode"; -# Extend the schema +# Add a table -In this tutorial you extend the schema to add a table of historical counter values and the time in which the counter reached those values. +In this tutorial you add a table of historical counter values and the time in which the counter reached those values. For the sake of simplicity, we will implement this in the `increment` function rather than use a [storage hook](/store/advanced-features#storage-hooks). ## Setup -Right now you need the `main` version of `mud`, not `next`. -So if you followed the directions, you need to run this command in the root directory. - -```sh copy -pnpm mud set-version --tag main && pnpm install -``` +[Create a new MUD application from the template](../minimal). ## Modify the MUD configuration file @@ -69,8 +64,8 @@ Block numbers and timestamps can be values up to `uint256`, so we'll use this ty 1. In an editor, open `packages/contracts/src/systems/IncrementSystem.sol`. - - Modify the second `import` line to import `History` (line 5) - - Modify the `increment` function to also update `History` (line 12). + - Modify the second `import` line to import `History`. + - Modify the `increment` function to also update `History`. To see the exact functions that are available, you can look at `packages/contracts/src/codegen/tables/History.sol` (that is the reason we ran `pnpm build:mud` to recreate it already). @@ -140,21 +135,22 @@ The directions here apply to the `vanilla` client template, if you use anything 1. Edit `packages/client/src/index.ts`. - - Import two more functions we need (lines 3-4). - - In `components.Counter.update$.subscribe`, add code that updates the selection of history values (lines 18-22). - - Add a function that is called when the user selects a different option (lines 31-37). + - Import two more functions we need. + - In `components.Counter.update$.subscribe`, add code that updates the selection of history values. + - Add a function that is called when the user selects a different option. ```ts filename="index.ts" copy showLineNumbers {3-4,18-22,31-37} - import { mount as mountDevTools } from "@latticexyz/dev-tools"; import { setup } from "./mud/setup"; + import mudConfig from "contracts/mud.config"; import { encodeEntity } from "@latticexyz/store-sync/recs"; import { getComponentValueStrict } from "@latticexyz/recs"; const { components, systemCalls: { increment }, + network, } = await setup(); // Components expose a stream that triggers when the component is updated. @@ -185,7 +181,20 @@ The directions here apply to the `vanilla` client template, if you use anything document.getElementById("timeStamp")!.innerHTML = new Date(parseInt(Number(time) * 1000)); }; - mountDevTools(); + if (import.meta.env.DEV) { + const { mount: mountDevTools } = await import("@latticexyz/dev-tools"); + mountDevTools({ + config: mudConfig, + publicClient: network.publicClient, + walletClient: network.walletClient, + latestBlock$: network.latestBlock$, + blockStorageOperations$: network.blockStorageOperations$, + worldAddress: network.worldContract.address, + worldAbi: network.worldContract.abi, + write$: network.write$, + recsWorld: network.world, + }); + } ```