Merge pull request #45 from dojoengine/packages

Packages

readme.md

@@ -1,42 +1,41 @@
 ## 📖 The Dojo Book
 
-Dojo is a toolchain for building Autonomous Worlds. Step into the Dojo [now](https://book.dojoengine.org/).
+Explore the world of Autonomous Worlds with Dojo, your trusted toolchain. [Dive in now](https://book.dojoengine.org/).
 
 ### Contributing
-Dojo is open-source and encourages contribution. It is in the early stage of development.
+Embrace the open-source spirit of Dojo. As it's in its nascent phase, we welcome contributors with open arms.
 
-Check our [contributing guidelines](./src/misc/contributors.md). Feel free to contribute wording, sentences, chapters, and guides!
+Peruse our [contributing guidelines](./src/misc/contributors.md). From minor wording adjustments to extensive chapters, every contribution matters!
 
 ### Setup
-1. Rust related packages:
-   - Install toolchain providing `cargo` using [rustup](https://rustup.rs/).
-   - Install [mdBook](https://rust-lang.github.io/mdBook/guide/installation.html) and the translation extension:
-   ```
-   cargo install mdbook mdbook-i18n-helpers
-   ```
-2. Host machine packages:
-   - Install [gettext](https://www.gnu.org/software/gettext/) for translations, usually available with regular package manager:
-     `sudo apt install gettext`.
-3. Clone this repository.
-
-### Work locally (english, main language)
-All the Markdown files **MUST** be edited in english. To work locally in english:
-- Start a local server with `mdbook serve` and visit [localhost:3000](http://localhost:3000) to view the book.
-  You can use the `--open` flag to open the browser automatically: `mdbook serve --open`.
-- Make changes to the book and refresh the browser to see the changes.
-- Open a PR with your changes.
-### Work locally (translations)
-This book is targetting international audience, and aims at being gradually translated in several languages.
-**All files in the `src` directory MUST be written in english**. This ensures that all the translation files can be
-auto-generated and updated by translators.
-To work with translations, those are the steps to update the translated content:
-- Run a local server for the language you want to edit: `./translations.sh es` for instance. If no language is provided, the script will only extract translations from english.
-- Open the translation file you are interested in `po/es.po` for instance. You can also use editors like [poedit](https://poedit.net/) to help you on this task.
-- When you are done, you should only have changes into the `po/xx.po` file. Commit them and open a PR.
-  The PR must stars with `i18n` to let the maintainers know that the PR is only changing translation.
-The translation work is inspired from [Comprehensive Rust repository](https://github.com/google/comprehensive-rust/blob/main/TRANSLATIONS.md).
-#### Initiate a new translation for your language
-If you wish to initiate a new translation for your language without running a local server, consider the following tips:
-- Execute the command `./translations.sh new xx` (replace `xx` with your language code). This method can generate the `xx.po` file of your language for you.
-- To update your `xx.po` file, execute the command `./translations.sh xx` (replace `xx` with your language code), as mentioned in the previous chapter.
-- If the `xx.po` file already exists (which means you are not initiating a new translation), you should not run this command.
+1. **Rust-related Packages**:
+   - Obtain the `cargo` toolchain via [rustup](https://rustup.rs/).
+   - Get [mdBook](https://rust-lang.github.io/mdBook/guide/installation.html) and its translation extension with the command:
+     ```cargo install mdbook mdbook-i18n-helpers```
+2. **Host Machine Packages**:
+   - To assist with translations, install [gettext](https://www.gnu.org/software/gettext/). It's typically accessible via most package managers. Use: `sudo apt install gettext`.
+3. Clone this repository to get started.
+
+### Working Locally (English - Primary Language)
+Always edit Markdown files in English. Here's how to work on it:
+- Spin up a local server using `mdbook serve`. Navigate to [localhost:3000](http://localhost:3000). For an automated browser launch, append the `--open` flag: `mdbook serve --open`.
+- Modify the content as desired. Refresh your browser to review edits.
+- Ready to share? Open a PR with your enhancements.
+
+### Working Locally (Translations)
+Catering to a global audience, we aspire for multilingual content. 
+
+**Note**: Ensure all files in the `src` directory are in English, facilitating automated generation and updates of translation files.
+
+For translation tasks:
+- Start a local server for a specific language, e.g., `./translations.sh es`. Without specifying a language, the script defaults to extracting English translations.
+- Focus on the relevant translation file, such as `po/es.po`. Tools like [poedit](https://poedit.net/) can make this task easier.
+- Conclude your session with changes only in the `po/xx.po` file. Commit and open a PR. Ensure the PR begins with `i18n` to signal it involves translation.
+
+This translation model draws inspiration from the [Comprehensive Rust repository](https://github.com/google/comprehensive-rust/blob/main/TRANSLATIONS.md).
+
+#### Starting a New Language Translation
+If initiating a new language translation without a local server:
+- Use `./translations.sh new xx`, replacing `xx` with your language code. This command spawns the `xx.po` file for your language.
+- Update your `xx.po` file with `./translations.sh xx` (swap `xx` with your language code), as detailed above.
+- For pre-existing `xx.po` files, refrain from using the `new` command.

src/SUMMARY.md

@@ -35,6 +35,12 @@
     -   [ERC1155]()
     -   [DeFi]()
 
+# Client SDKs
+
+-   [Overview](./client/overview.md)
+-   [JS](./client/npm.md)
+    - [Core](./client/npm/core.md)
+
 # Toolchain
 
 -   [Dojoup](./toolchain/dojoup.md)

src/client/npm.md

@@ -0,0 +1,43 @@
+# Javascript Libraries
+
+> Javascript is a great way to get started with Dojo. It's easy to use, and you can get started in minutes.
+
+### Examples using these:
+
+- [Dojo-create-react-app](https://github.com/dojoengine/dojo-starter-react-app)
+- [Dojo-starter-phaser](https://github.com/dojoengine/dojo-starter-phaser)
+
+### @dojoengine/core
+
+This is the lowest level library, and is used by all other downstream libraries. It contains the core functionality of Dojo and exposes the contract interfaces. Use it if you want to build your own library on top of Dojo.
+
+[Documentation](./npm/core.md)
+
+```console
+yarn add @dojoengine/core
+```
+
+### @dojoengine/react
+
+This is a direct fork of [Mud React](https://github.com/latticexyz/mud/tree/main/packages)
+
+This library contains a set of React components that can be used when building React apps using Dojo.
+
+[Documentation](./npm/react.md)
+
+```console
+yarn add @dojoengine/react
+```
+
+
+### @dojoengine/create-burner
+
+Create burner is a simply way to incorporate burner wallets into your Dojo app.
+
+[Reopsitory](https://github.com/dojoengine/create-burner)
+
+```console
+yarn add @dojoengine/create-burner
+```
+
+

src/client/npm/core.md

@@ -0,0 +1,52 @@
+## @dojoengine/core
+
+This library abstracts away the world interface and provides a set of helper functions to interact with the world. It is preferred to use this library over interacting with the world directly.
+
+- World explorers
+- World deployers
+- Games
+- Anaylitics
+
+### Getting Started
+
+```console
+yarn add @dojoengine/core
+```
+
+### Example Usage
+
+This is an example from [Dojo React App](https://github.com/dojoengine/dojo-starter-react-app)
+
+```javascript
+import { defineContractComponents } from "./contractComponents";
+import { world } from "./world";
+import { RPCProvider, Query, } from "@dojoengine/core";
+import { Account, num } from "starknet";
+import { GraphQLClient } from 'graphql-request';
+import { getSdk } from '../generated/graphql';
+
+export const WORLD_ADDRESS = import.meta.env.VITE_PUBLIC_WORLD_ADDRESS!
+
+export type SetupNetworkResult = Awaited<ReturnType<typeof setupNetwork>>;
+
+export async function setupNetwork() {
+
+    const client = new GraphQLClient('http://localhost:8080');
+
+    const graphSdk = getSdk(client);
+
+    const contractComponents = defineContractComponents(world);
+
+    const provider = new RPCProvider(WORLD_ADDRESS);
+
+    return {
+        contractComponents,
+        provider,
+        execute: async (signer: Account, system: string, call_data: num.BigNumberish[]) => provider.execute(signer, system, call_data),
+        entity: async (component: string, query: Query) => provider.entity(component, query),
+        entities: async (component: string, partition: number) => provider.entities(component, partition),
+        world,
+        graphSdk
+    };
+}
+```

src/client/overview.md

@@ -0,0 +1,7 @@
+# Overview
+
+Dojo is BYO client, meaning that you can use any client you want to connect to the Dojo network.
+
+Reference clients are available for the following platforms:
+
+- [npm](./npm.md)