📝 [DOCS] Document Controller Connector setup

[jimenezz22]

📝 Issue Title: Document the cartridgeConnector.tsx configuration file for Controller Connector setup

🔍 Scope

Create comprehensive documentation for the cartridgeConnector.tsx configuration file that demonstrates how to properly set up Cartridge Controller integration in Dojo games. This documentation should explain every part of the configuration, from environment-specific RPC URLs to session policies, helping developers understand how to configure the controller for seamless wallet integration in their Dojo games.

This will be part of the React integration section under /integrations/react/controller-connector and should serve as the definitive guide for configuring the Cartridge Controller connector.

🔄 How to Implement the Issue

Documentation Structure:

• Step 1: Create /client/pages/integrations/react/ControllerConnector.md following the established documentation format
• Step 2: Document each section of the cartridgeConnector.tsx file with detailed explanations
• Step 3: Explain the environment configuration pattern and its benefits
• Step 4: Detail the session policies configuration for game actions
• Step 5: Include practical examples and common use cases

Content Requirements:

• Step 1: File Overview & Purpose

  • Explain what the cartridgeConnector.tsx file does
  • Why this configuration is needed for Dojo games
  • How it integrates with the Starknet React ecosystem

• Step 2: Imports and Dependencies

  import { Connector } from "@starknet-react/core";
  import { ControllerConnector } from "@cartridge/connector";
  import { ControllerOptions } from "@cartridge/controller";
  import { constants } from "starknet";
  import { manifest } from "./manifest";

  • Explain each import and its role
  • Document the required package dependencies

• Step 3: Environment Configuration

  • Document the VITE_PUBLIC_DEPLOY_TYPE environment variable usage
  • Explain the getRpcUrl() function and network-specific endpoints
  • Detail the getDefaultChainId() function and chain ID mapping
  • Show how to configure for localhost, sepolia, and mainnet

• Step 4: Contract Address Resolution

  const getGameContractAddress = () => {
    return manifest.contracts[0].address;
  };

  • Explain how contract addresses are resolved from the manifest
  • Document the relationship with the Dojo manifest file
  • Show alternative ways to handle multiple contracts

• Step 5: Session Policies Configuration

  const policies = {
    contracts: {
      [CONTRACT_ADDRESS_GAME]: {
        methods: [
          { name: "spawn_player", entrypoint: "spawn_player" },
          { name: "train", entrypoint: "train" },
          { name: "mine", entrypoint: "mine" },
          { name: "rest", entrypoint: "rest" },
        ],
      },
    },
  }

  • Explain what session policies are and why they're crucial for gaming UX
  • Document how to add new game methods to policies
  • Show examples of different policy configurations

• Step 6: Controller Options Configuration

  const options: ControllerOptions = {
    chains: [{ rpcUrl: getRpcUrl() }],
    defaultChainId: getDefaultChainId(),
    policies,
    namespace: "full_starter_react",
    slot: "full-starter-react",
  };

  • Explain each option property and its purpose
  • Document the namespace and slot configuration
  • Show how to customize for different games

• Step 7: Connector Instantiation

  const cartridgeConnector = new ControllerConnector(
    options,
  ) as never as Connector;

  • Explain the TypeScript casting and why it's needed
  • Document how this integrates with Starknet React

• Step 8: Customization Examples

  • Show how to modify the configuration for different game types
  • Provide examples of adding new contract methods
  • Demonstrate multi-contract policy configurations

✅ Acceptance Criteria

Code Documentation:

• Every line of the cartridgeConnector.tsx file is explained with clear context
• All function parameters and return values are documented
• TypeScript types and interfaces are explained
• Environment variable usage is thoroughly documented

Configuration Patterns:

• Network switching pattern (localhost/sepolia/mainnet) is clearly explained
• Session policies configuration is documented with game-specific examples
• Contract address resolution from manifest is explained
• Namespace and slot configuration purpose is detailed

Practical Examples:

• Shows how to add new game methods to session policies
• Demonstrates configuration for different deployment environments
• Includes examples of handling multiple contracts

Integration Context:

• Explains how this file integrates with the broader Dojo ecosystem
• Documents the relationship with manifest.json
• Shows how environment variables should be configured
• Explains the connection to StarknetProvider setup

📸 Additional Context

Source File Location:
/client/src/config/cartridgeConnector.tsx from the Dojo-Game-Starter repository

Key Configuration Elements to Document:

• Environment switching: How VITE_PUBLIC_DEPLOY_TYPE controls network selection
• RPC URLs: Different endpoints for each network (localhost:5050, Cartridge API endpoints)
• Chain IDs: Mapping between deploy types and Starknet chain identifiers
• Session policies: Pre-approved method calls for seamless gaming UX
• Manifest integration: How contract addresses are dynamically resolved

Related Files to Reference:

• manifest.json - Contract deployment information
• starknet-provider.tsx - Provider integration
• Environment configuration (.env files)

Success Criteria:

• A developer can understand and modify the connector configuration
• All configuration options are clearly explained with practical examples
• The file serves as a reference for similar connector setups in other Dojo games

Contribution Guidelines

• Please ensure you read and follow the contribution guidelines in the project's [README](/README.md) file
• Use the exact code from the cartridgeConnector.tsx file as the primary reference
• Test any configuration examples in a local Dojo environment
• Follow the established documentation format used in other integration guides

[ryzen-xp]

Hi,
I am proficient Blockchain developer expert in Cairo , Rust and Solidity and also in web development.
I have already make intigrated this feature in aqua stark and stark brawl.
please /assign Me this issue .
Thank You !!
ETA: 24 hours