From 41d4c7ceb2c95fb596adbbda4fa8cd5ddd245aa8 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Mon, 25 Sep 2023 18:17:54 -0500 Subject: [PATCH] docs: update minimal tutorials to next.9 (#1610) next.9 broke tutorials, so I'm going to ignore reviews and just update them. --- docs/pages/tutorials/minimal/add-system.mdx | 94 +++++++++++++++++---- docs/pages/tutorials/minimal/add-table.mdx | 4 +- 2 files changed, 78 insertions(+), 20 deletions(-) diff --git a/docs/pages/tutorials/minimal/add-system.mdx b/docs/pages/tutorials/minimal/add-system.mdx index 5f19f3cb75..1179d0ef52 100644 --- a/docs/pages/tutorials/minimal/add-system.mdx +++ b/docs/pages/tutorials/minimal/add-system.mdx @@ -1,3 +1,5 @@ +import { CollapseCode } from "../../../components/CollapseCode"; + # Add a system In this tutorial you add a system to decrement the counter and update the application to use it. @@ -8,12 +10,12 @@ Create a file `packages/contracts/src/systems/DecrementSystem.sol`. Note that we could have just added a function to the existing system, `IncrementSystem.sol`. The only reason we are adding a new system here is to see how to do it. -```solidity filename="DecrementSystem.sol" copy +```solidity filename="DecrementSystem.sol" copy showLineNumbers // SPDX-License-Identifier: MIT pragma solidity >=0.8.0; import { System } from "@latticexyz/world/src/System.sol"; -import { Counter } from "../codegen/Tables.sol"; +import { Counter } from "../codegen/index.sol"; contract DecrementSystem is System { function decrement() public returns (uint32) { @@ -32,7 +34,7 @@ contract DecrementSystem is System { ```solidity import { System } from "@latticexyz/world/src/System.sol"; -import { Counter } from "../codegen/Tables.sol"; +import { Counter } from "../codegen/index.sol"; ``` The two things the system needs to know: how to be a `System` and how to access the `Counter`. @@ -59,25 +61,58 @@ In this case, the vanilla getting started front end. 1. Edit `packages/client/src/mud/createSystemCalls.ts` to include `decrement`. This is the file after the changes: - ```typescript filename="createSystemCalls.ts" copy + + + ```typescript filename="createSystemCalls.ts" copy showLineNumbers {47-51,55} + /* + * Create the system calls that the client can use to ask + * for changes in the World state (using the System contracts). + */ + + import { getComponentValue } from "@latticexyz/recs"; import { ClientComponents } from "./createClientComponents"; import { SetupNetworkResult } from "./setupNetwork"; + import { singletonEntity } from "@latticexyz/store-sync/recs"; export type SystemCalls = ReturnType; export function createSystemCalls( - { worldSend, txReduced$, singletonEntity }: SetupNetworkResult, + /* + * The parameter list informs TypeScript that: + * + * - The first parameter is expected to be a + * SetupNetworkResult, as defined in setupNetwork.ts + * + * - Out of this parameter, we only care about two fields: + * - worldContract (which comes from createContract, see + * https://github.com/latticexyz/mud/blob/26dabb34321eedff7a43f3fcb46da4f3f5ba3708/templates/vanilla/packages/client/src/mu$ + * - waitForTransaction (which comes from syncToRecs, see + * https://github.com/latticexyz/mud/blob/26dabb34321eedff7a43f3fcb46da4f3f5ba3708/templates/vanilla/packages/client/src/mu$ + * + * - From the second parameter, which is a ClientComponent, + * we only care about Counter. This parameter comes to use + * through createClientComponents.ts, but it originates in + * syncToRecs + (https://github.com/latticexyz/mud/blob/26dabb34321eedff7a43f3fcb46da4f3f5ba3708/templates/vanilla/packages/client/src/mud/setupN$ + */ + { worldContract, waitForTransaction }: SetupNetworkResult, { Counter }: ClientComponents ) { const increment = async () => { - const tx = await worldSend("increment", []); - await awaitStreamValue(txReduced$, (txHash) => txHash === tx.hash); + /* + * Because IncrementSystem + * (https://mud.dev/tutorials/walkthrough/minimal-onchain#incrementsystemsol) + * is in the root namespace, `.increment` can be called directly + * on the World contract. + */ + const tx = await worldContract.write.increment(); + await waitForTransaction(tx); return getComponentValue(Counter, singletonEntity); }; const decrement = async () => { - const tx = await worldSend("decrement", []); - await awaitStreamValue(txReduced$, (txHash) => txHash === tx.hash); + const tx = await worldContract.write.decrement(); + await waitForTransaction(tx); return getComponentValue(Counter, singletonEntity); }; @@ -88,6 +123,8 @@ In this case, the vanilla getting started front end. } ``` + +
Explanation @@ -104,15 +141,13 @@ In this case, the vanilla getting started front end. This function involves sending a transaction, which is a slow process, so it needs to be [asynchronous](https://www.w3schools.com/js/js_async.asp). ```typescript - const tx = await worldSend("decrement", []); + const tx = await worldContract.write.decrement(); ``` This is the way we call functions in top-level systems in a world. - The second parameter, the list, is for the function parameters. - In this case there aren't any, so it is empty. ```typescript - await awaitStreamValue(txReduced$, (txHash) => txHash === tx.hash); + await waitForTransaction(tx); ``` Await until we receive confirmation that the transaction has been added to a block. @@ -139,13 +174,16 @@ In this case, the vanilla getting started front end. 1. Update `packages/client/src/index.ts` to include `decrement`. This is the file after the changes: - ```typescript filename="index.ts" copy - import { mount as mountDevTools } from "@latticexyz/dev-tools"; + + + ```typescript filename="index.ts" copy showLineNumbers {6,23-25} import { setup } from "./mud/setup"; + import mudConfig from "contracts/mud.config"; const { components, - systemCalls: { decrement, increment }, + systemCalls: { increment, decrement }, + network, } = await setup(); // Components expose a stream that triggers when the component is updated. @@ -165,9 +203,25 @@ In this case, the vanilla getting started front end. console.log("new counter value:", await decrement()); }; - mountDevTools(); + // https://vitejs.dev/guide/env-and-mode.html + 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$, + storedBlockLogs$: network.storedBlockLogs$, + worldAddress: network.worldContract.address, + worldAbi: network.worldContract.abi, + write$: network.write$, + recsWorld: network.world, + }); + } ``` + +
Explanation @@ -199,7 +253,9 @@ In this case, the vanilla getting started front end. 1. Modify `packages/client/index.html` to add a decrement button. This is the file after the changes: - ```html filename="index.html" copy + + + ```html filename="index.html" copy showLineNumbers {12} @@ -216,6 +272,8 @@ In this case, the vanilla getting started front end. ``` + +
Explanation diff --git a/docs/pages/tutorials/minimal/add-table.mdx b/docs/pages/tutorials/minimal/add-table.mdx index 404804ae06..57d4d991f8 100644 --- a/docs/pages/tutorials/minimal/add-table.mdx +++ b/docs/pages/tutorials/minimal/add-table.mdx @@ -77,7 +77,7 @@ Block numbers and timestamps can be values up to `uint256`, so we'll use this ty pragma solidity >=0.8.0; import { System } from "@latticexyz/world/src/System.sol"; -import { Counter, History, HistoryData } from "../codegen/Tables.sol"; +import { Counter, History, HistoryData } from "../codegen/index.sol"; contract IncrementSystem is System { function increment() public returns (uint32) { @@ -96,7 +96,7 @@ contract IncrementSystem is System { Explanation ```solidity -import { Counter, History, HistoryData } from "../codegen/Tables.sol"; +import { Counter, History, HistoryData } from "../codegen/index.sol"; ``` 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.