Skip to content

Commit

Permalink
docs: update minimal tutorials to next.9 (#1610)
Browse files Browse the repository at this point in the history 
next.9 broke tutorials, so I'm going to ignore reviews and just update them.
  • Loading branch information
@qbzzt
qbzzt authored Sep 25, 2023
1 parent 3a68889 commit 41d4c7c
Show file tree
Hide file tree
Showing 2 changed files with 78 additions and 20 deletions.
94 changes: 76 additions & 18 deletions docs/pages/tutorials/minimal/add-system.mdx
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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) {
Expand All @@ -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`.
Expand All @@ -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
<CollapseCode>

```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<typeof createSystemCalls>;

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);
};

Expand All @@ -88,6 +123,8 @@ In this case, the vanilla getting started front end.
}
```

</CollapseCode>

<details>

<summary>Explanation</summary>
Expand All @@ -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.
Expand All @@ -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";
<CollapseCode>

```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.
Expand All @@ -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,
});
}
```

</CollapseCode>

<details>

<summary>Explanation</summary>
Expand Down Expand Up @@ -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
<CollapseCode>

```html filename="index.html" copy showLineNumbers {12}
<!DOCTYPE html>
<html lang="en">
<head>
Expand All @@ -216,6 +272,8 @@ In this case, the vanilla getting started front end.
</html>
```

</CollapseCode>

<details>

<summary>Explanation</summary>
Expand Down
4 changes: 2 additions & 2 deletions docs/pages/tutorials/minimal/add-table.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -96,7 +96,7 @@ contract IncrementSystem is System {
<summary>Explanation</summary>

```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.
Expand Down

0 comments on commit 41d4c7c

Please sign in to comment.