-
Notifications
You must be signed in to change notification settings - Fork 184
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(explorer): update readme (#3093)
Co-authored-by: Ori Pomerantz <[email protected]>
- Loading branch information
Showing
1 changed file
with
42 additions
and
36 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,32 +1,38 @@ | ||
# World Explorer | ||
|
||
World Explorer is a GUI tool designed for visually exploring and manipulating the state of worlds. | ||
For the full information about it, [see the official docs](http://mud.dev/world-explorer). | ||
|
||
## Getting started | ||
|
||
1. **Install the package** | ||
### Prerequisites | ||
|
||
```sh | ||
pnpm add @latticexyz/explorer | ||
``` | ||
World Explorer is not intended to be used alone, and includes the following prerequisites: | ||
|
||
2. **Start a local development chain** | ||
- [MUD project](https://mud.dev/introduction) | ||
- [anvil development chain](https://book.getfoundry.sh/anvil/) | ||
- [@latticexyz/store-indexer](https://www.npmjs.com/package/@latticexyz/store-indexer) | ||
|
||
Ensure you have a local development chain running. | ||
### Install and run | ||
|
||
3. **Run the World Explorer** | ||
```sh | ||
pnpm add @latticexyz/explorer | ||
pnpm explorer | ||
``` | ||
|
||
```sh | ||
npx @latticexyz/explorer --worldAddress <YOUR_WORLD_ADDRESS> | ||
``` | ||
Or, can be executed with a package bin directly: | ||
|
||
Alternatively, if you have a worlds configuration file: | ||
```sh | ||
npx @latticexyz/explorer | ||
``` | ||
|
||
```sh | ||
npx @latticexyz/explorer --worldsConfigPath <PATH_TO_WORLDS_CONFIG> | ||
``` | ||
**Note:** `worlds.json` is the default file used to configure the world. If you're using a different file or if the file is located in a different path than where you're running the command, you can specify it with the `--worldsFile` flag, or use `--worldAddress` to point to the world address directly. Accordingly, `indexer.db` is the default database file used to index the world state. If you're using a different database file or if the file is located in a different path than where you're running the command, you can specify it with the `--indexerDatabase` flag. | ||
|
||
### Example setup | ||
|
||
For a full working setup, check out the [local-explorer](https://github.com/latticexyz/mud/tree/main/examples/local-explorer) example. | ||
|
||
Note: You can use `@latticexyz/store-indexer` for indexing your world's data. | ||
You may also want to check out the MUD [Quickstart guide](https://mud.dev/quickstart) to set up a new MUD template project that already comes with the World Explorer included, along with all the prerequisites. | ||
|
||
## CLI arguments | ||
|
||
|
@@ -35,51 +41,51 @@ The World Explorer accepts the following CLI arguments: | |
| Argument | Description | Default value | | ||
| ----------------- | -------------------------------------------------------------------------------- | ------------- | | ||
| `worldAddress` | The address of the world to explore | None | | ||
| `worldsFile` | Path to a worlds configuration file (used to resolve world address) | None | | ||
| `worldsFile` | Path to a worlds configuration file (used to resolve world address) | "worlds.json" | | ||
| `indexerDatabase` | Path to your SQLite indexer database | "indexer.db" | | ||
| `chainId` | The chain ID of the network | 31337 | | ||
| `port` | The port on which to run the World Explorer | 13690 | | ||
| `env` | The environment to run the World Explorer in (e.g., "development", "production") | "production" | | ||
|
||
## Example setup | ||
## Contributing | ||
|
||
An example setup is provided in the `examples/local-explorer` directory, demonstrating a full setup for using the World Explorer in a local development environment: | ||
To contribute to World Explorer, first get familiar with the [MUD contribution guidelines](https://mud.dev/contribute). Then, set up the development environment for World Explorer: | ||
|
||
1. **Setup** | ||
1. **Clone MUD** | ||
|
||
```sh | ||
cd examples/local-explorer && pnpm install | ||
git clone [email protected]:latticexyz/mud.git | ||
cd mud | ||
pnpm install | ||
pnpm build | ||
``` | ||
|
||
2. **Run** | ||
2. **Setup** | ||
|
||
Navigate to the `examples/local-explorer` and install dependencies. | ||
|
||
```sh | ||
pnpm dev | ||
cd examples/local-explorer | ||
pnpm install | ||
``` | ||
|
||
This command starts all necessary processes, including a local chain, indexer, and the explorer. | ||
## Contributing | ||
To contribute to or modify the World Explorer, the easiest way is to run the example setup in `development` mode: | ||
1. **Setup** | ||
3. **Configure** | ||
|
||
Navigate to the `examples/local-explorer` directory and locate the `mprocs.yaml` file. | ||
2. **Configure** | ||
In `mprocs.yaml`, ensure the `explorer` command is set up correctly. For example: | ||
In `mprocs.yaml`, ensure the `explorer` command is set to run the World Explorer in `development` mode. | ||
|
||
```yaml | ||
explorer: | ||
shell: pnpm explorer --worldsConfigPath packages/contracts/worlds.json --env development | ||
shell: pnpm explorer --env development | ||
``` | ||
|
||
3. **Run** | ||
4. **Run** | ||
|
||
```sh | ||
pnpm dev | ||
``` | ||
|
||
Files can now be edited in the `packages/explorer` directory, and changes will be reflected in the running World Explorer instance. | ||
|
||
## Links | ||
|
||
- [Official World Explorer docs](https://mud.dev/world-explorer) |