From 1a30942fc96d08ca885cfb65b865dfc859809213 Mon Sep 17 00:00:00 2001 From: Renzo Barcos Date: Fri, 29 Aug 2025 14:57:39 -0300 Subject: [PATCH 1/3] docs: add Torii indexer overview documentation - Create beginner-friendly overview explaining Torii's role in Dojo - Include what Torii is, why to use it, and how it works - Add API interfaces (GraphQL, gRPC) with endpoints - Provide practical use cases and installation notes - Keep content concise for 2-3 minute reading time - Address GitHub issue #193 for Torii overview documentation --- client-new/pages/deployment/torii/overview.md | 60 +++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 client-new/pages/deployment/torii/overview.md diff --git a/client-new/pages/deployment/torii/overview.md b/client-new/pages/deployment/torii/overview.md new file mode 100644 index 0000000..23de991 --- /dev/null +++ b/client-new/pages/deployment/torii/overview.md @@ -0,0 +1,60 @@ +--- +title: "Torii Indexer Overview" +description: "Learn what Torii is, why you need it, and how it works in the Dojo ecosystem" +--- + +# Torii Indexer Overview + +Torii is Dojo's built-in tool for making your game data fast and easy to access. Think of it as a "search engine" for your on-chain game world—it keeps everything up-to-date in a local database so your apps can query it instantly. + +## What is Torii? + +- **Official Indexing Engine**: Torii is the standard way to index data in Dojo worlds +- **Automatic Syncing**: It watches your blockchain (Starknet) and copies game state changes to a database +- **Efficient Queries**: Provides APIs for quick data access, avoiding slow direct blockchain calls +- **Built in Rust**: Designed for speed and reliability +- **Pre-Installed**: Comes bundled with the Dojo toolchain—no extra setup needed + +## Why Use Torii? + +Directly querying the blockchain is like searching a massive library book-by-book: slow and costly. Torii acts like a catalog system: + +- **Speed**: Instant access to game data +- **Real-Time Updates**: Supports subscriptions for live changes (e.g., player moves) +- **Cost Savings**: Reduces on-chain queries +- **Multiple Options**: Query via GraphQL, gRPC, or even SQL + +## How It Works (Simplified) + +1. **Monitor**: Torii tracks your deployed World contract on Starknet +2. **Capture**: It records every state change (e.g., new player spawns or moves) +3. **Store**: Saves data in a local database for easy access +4. **Serve**: Exposes APIs for your client apps to read the data + +No manual intervention—Torii runs in the background when you deploy or migrate your Dojo project. + +## API Interfaces + +- **GraphQL**: Flexible for custom queries and real-time subscriptions + - Default Endpoint: `http://localhost:8080/graphql` +- **gRPC**: Fast binary protocol for high-performance apps + - Default Endpoint: `http://localhost:8080` + +## When to Use Torii + +- Fetching player stats (e.g., position, score) +- Building leaderboards or dashboards +- Real-time updates in games (e.g., multiplayer sync) +- Analyzing historical data without blockchain delays + +## Installation Note + +Torii is included by default with Dojo. Install Dojo via the official guide, and Torii is ready to go. Run `torii --world ` to start it manually if needed. + +## Next Steps + +- See the [Local Development](../local.md) guide for setup +- Check [Client Integration](./client-integration.md) for using Torii in apps +- For advanced config, visit the [official Dojo docs](https://book.dojoengine.org/toolchain/torii) + +This overview keeps things simple—dive deeper as you build! From 04e1d0f1f32b89f012183c5dd49a9882f4bee36e Mon Sep 17 00:00:00 2001 From: Renzo Barcos Date: Fri, 29 Aug 2025 14:57:51 -0300 Subject: [PATCH 2/3] feat: add Torii indexer navigation to deployment section - Add Torii Indexer subsection under Deployment navigation - Include Overview and Client Integration links - Ensure proper navigation structure for Torii documentation - Maintain consistent navigation patterns with existing sections --- client-new/src/routes.ts | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/client-new/src/routes.ts b/client-new/src/routes.ts index 5658e35..b310af7 100644 --- a/client-new/src/routes.ts +++ b/client-new/src/routes.ts @@ -123,6 +123,20 @@ const sidebarConfig: SidebarItem[] = [ text: 'Slot', link: '/deployment/slot', }, + { + text: 'Torii Indexer', + collapsed: true, + items: [ + { + text: 'Overview', + link: '/deployment/torii/overview', + }, + { + text: 'Client Integration', + link: '/deployment/torii/client-integration', + }, + ], + }, ], }, { From 3304bbaf4e49d9244a4bd19b212f41831bf6f697 Mon Sep 17 00:00:00 2001 From: Renzo Barcos Date: Tue, 9 Sep 2025 23:28:19 -0300 Subject: [PATCH 3/3] docs: updated the client-integration.md and the overview.md to have the correct files --- .../deployment/torii/client-integration.md | 189 ++++++++++++++++++ client-new/pages/deployment/torii/overview.md | 16 +- 2 files changed, 203 insertions(+), 2 deletions(-) create mode 100644 client-new/pages/deployment/torii/client-integration.md diff --git a/client-new/pages/deployment/torii/client-integration.md b/client-new/pages/deployment/torii/client-integration.md new file mode 100644 index 0000000..0c72531 --- /dev/null +++ b/client-new/pages/deployment/torii/client-integration.md @@ -0,0 +1,189 @@ +--- +title: "Torii Client Integration" +description: "Learn how to integrate Torii with your client applications using GraphQL and gRPC" +--- + +# Torii Client Integration + +This guide shows you how to connect your client applications to Torii for efficient data querying and real-time updates. + +## Configuration + +### Environment Setup + +First, configure your Torii URL based on your deployment environment: + +```javascript +// config.js +const config = { + development: { + toriiUrl: "http://localhost:8080" + }, + production: { + toriiUrl: "https://api.cartridge.gg/x/YOUR_INSTANCE_NAME/torii" + } +}; + +export const dojoConfig = config[process.env.NODE_ENV || 'development']; +``` + +### GraphQL Endpoint + +```javascript +const TORII_GRAPHQL_URL = dojoConfig.toriiUrl + "/graphql"; +``` + +## GraphQL Integration + +### Basic Setup + +```javascript +import { createClient } from '@urql/core'; + +const client = createClient({ + url: TORII_GRAPHQL_URL, +}); + +// Example query +const GET_PLAYERS = ` + query GetPlayers { + players { + id + position { + x + y + } + score + } + } +`; + +// Execute query +const result = await client.query(GET_PLAYERS).toPromise(); +console.log(result.data.players); +``` + +### Real-time Subscriptions + +```javascript +// Subscribe to player position updates +const PLAYER_POSITION_SUBSCRIPTION = ` + subscription PlayerPositionUpdates { + playerPositionUpdated { + id + position { + x + y + } + } + } +`; + +const subscription = client.subscription(PLAYER_POSITION_SUBSCRIPTION) + .subscribe({ + next: (result) => { + console.log('Player moved:', result.data.playerPositionUpdated); + }, + error: (error) => { + console.error('Subscription error:', error); + } + }); +``` + +## gRPC Integration + +For high-performance applications, you can use gRPC: + +```javascript +// Example with gRPC-Web +import { grpc } from '@improbable-eng/grpc-web'; + +const client = new grpc.Client(TORII_GRPC_URL); + +// Define your service methods +const playerService = { + getPlayers: (request) => { + return client.unary(PlayerService.GetPlayers, request); + } +}; +``` + +## React Integration + +### Custom Hook Example + +```javascript +import { useEffect, useState } from 'react'; +import { createClient } from '@urql/core'; + +const useToriiQuery = (query, variables = {}) => { + const [data, setData] = useState(null); + const [loading, setLoading] = useState(true); + const [error, setError] = useState(null); + + useEffect(() => { + const client = createClient({ + url: TORII_GRAPHQL_URL, + }); + + client.query(query, variables) + .toPromise() + .then(result => { + setData(result.data); + setLoading(false); + }) + .catch(err => { + setError(err); + setLoading(false); + }); + }, [query, variables]); + + return { data, loading, error }; +}; + +// Usage in component +const PlayerList = () => { + const { data, loading, error } = useToriiQuery(GET_PLAYERS); + + if (loading) return
Loading players...
; + if (error) return
Error: {error.message}
; + + return ( +
+ {data.players.map(player => ( +
+ Player {player.id}: ({player.position.x}, {player.position.y}) +
+ ))} +
+ ); +}; +``` + +## Error Handling + +```javascript +const handleToriiError = (error) => { + if (error.networkError) { + console.error('Network error:', error.networkError); + // Handle connection issues + } else if (error.graphQLErrors) { + console.error('GraphQL errors:', error.graphQLErrors); + // Handle query errors + } +}; +``` + +## Best Practices + +1. **Connection Pooling**: Reuse client instances when possible +2. **Error Boundaries**: Implement proper error handling for network issues +3. **Caching**: Use appropriate caching strategies for frequently accessed data +4. **Subscriptions**: Clean up subscriptions when components unmount +5. **Environment Variables**: Use environment variables for different deployment URLs + +## Next Steps + +- Check the [Torii Overview](./overview.md) for more context +- See [Local Development](../local.md) for setup instructions +- Visit the [official Dojo docs](https://book.dojoengine.org/toolchain/torii) for advanced configuration diff --git a/client-new/pages/deployment/torii/overview.md b/client-new/pages/deployment/torii/overview.md index 23de991..56ffc97 100644 --- a/client-new/pages/deployment/torii/overview.md +++ b/client-new/pages/deployment/torii/overview.md @@ -36,9 +36,21 @@ No manual intervention—Torii runs in the background when you deploy or migrate ## API Interfaces - **GraphQL**: Flexible for custom queries and real-time subscriptions - - Default Endpoint: `http://localhost:8080/graphql` + - Local Development: `http://localhost:8080/graphql` + - Production (Cartridge): `https://api.cartridge.gg/x/YOUR_INSTANCE_NAME/torii/graphql` - **gRPC**: Fast binary protocol for high-performance apps - - Default Endpoint: `http://localhost:8080` + - Local Development: `http://localhost:8080` + - Production (Cartridge): `https://api.cartridge.gg/x/YOUR_INSTANCE_NAME/torii` + +### URL Configuration + +For production deployments, you'll typically configure your Torii URL in your client: + +```javascript +// Example configuration +const TORII_URL = dojoConfig.toriiUrl + "/graphql"; +// Results in: https://api.cartridge.gg/x/YOUR_INSTANCE_NAME/torii/graphql +``` ## When to Use Torii