diff --git a/examples/example-vite-react-sdk/src/App.tsx b/examples/example-vite-react-sdk/src/App.tsx index 78cad8ba..8c96c9da 100644 --- a/examples/example-vite-react-sdk/src/App.tsx +++ b/examples/example-vite-react-sdk/src/App.tsx @@ -8,8 +8,17 @@ import { useDojo } from "./useDojo.tsx"; import useModel from "./useModel.tsx"; import { useSystemCalls } from "./useSystemCalls.ts"; +/** + * Global store for managing Dojo game state. + */ export const useDojoStore = createDojoStore(); +/** + * Main application component that provides game functionality and UI. + * Handles entity subscriptions, state management, and user interactions. + * + * @param props.sdk - The Dojo SDK instance configured with the game schema + */ function App({ sdk }: { sdk: SDK }) { const { account, diff --git a/examples/example-vite-react-sdk/src/DojoContext.tsx b/examples/example-vite-react-sdk/src/DojoContext.tsx index 84d0cf2a..8c3b3544 100644 --- a/examples/example-vite-react-sdk/src/DojoContext.tsx +++ b/examples/example-vite-react-sdk/src/DojoContext.tsx @@ -9,14 +9,30 @@ import { dojoConfig } from "../dojoConfig"; import { DojoProvider } from "@dojoengine/core"; import { client } from "./contracts.gen"; +/** + * Interface defining the shape of the Dojo context. + */ interface DojoContextType { + /** The master account used for administrative operations */ masterAccount: Account; + /** The Dojo client instance */ client: ReturnType; + /** The current burner account information */ account: BurnerAccount; } +/** + * React context for sharing Dojo-related data throughout the application. + */ export const DojoContext = createContext(null); +/** + * Provider component that makes Dojo context available to child components. + * + * @param props.children - Child components that will have access to the Dojo context + * @param props.burnerManager - Instance of BurnerManager for handling burner accounts + * @throws {Error} If DojoProvider is used more than once in the component tree + */ export const DojoContextProvider = ({ children, burnerManager, diff --git a/examples/example-vite-react-sdk/src/bindings.ts b/examples/example-vite-react-sdk/src/bindings.ts index eec0eb34..5701d5ed 100644 --- a/examples/example-vite-react-sdk/src/bindings.ts +++ b/examples/example-vite-react-sdk/src/bindings.ts @@ -1,23 +1,46 @@ +/** + * Interface representing a player's movement capabilities and state. + */ interface Moves { + /** Order of fields in the model */ fieldOrder: string[]; + /** Player identifier */ player: string; + /** Number of moves remaining */ remaining: number; + /** Last direction moved */ last_direction: Direction; + /** Whether the player can currently move */ can_move: boolean; } +/** + * Interface representing available movement directions for a player. + */ interface DirectionsAvailable { + /** Order of fields in the model */ fieldOrder: string[]; + /** Player identifier */ player: string; + /** List of available directions */ directions: Direction[]; } +/** + * Interface representing a player's position in the game world. + */ interface Position { + /** Order of fields in the model */ fieldOrder: string[]; + /** Player identifier */ player: string; + /** 2D vector representing position */ vec: Vec2; } +/** + * Enum representing possible movement directions. + */ enum Direction { None = "0", Left = "1", @@ -26,11 +49,19 @@ enum Direction { Down = "4", } +/** + * Interface representing a 2D vector. + */ interface Vec2 { + /** X coordinate */ x: number; + /** Y coordinate */ y: number; } +/** + * Type representing the complete schema of game models. + */ type Schema = { dojo_starter: { Moves: Moves; @@ -39,6 +70,9 @@ type Schema = { }; }; +/** + * Enum representing model identifiers in the format "namespace-modelName". + */ enum Models { Moves = "dojo_starter-Moves", DirectionsAvailable = "dojo_starter-DirectionsAvailable", diff --git a/examples/example-vite-react-sdk/src/main.tsx b/examples/example-vite-react-sdk/src/main.tsx index ebd71384..f5ce597b 100644 --- a/examples/example-vite-react-sdk/src/main.tsx +++ b/examples/example-vite-react-sdk/src/main.tsx @@ -10,6 +10,12 @@ import { dojoConfig } from "../dojoConfig.ts"; import { DojoContextProvider } from "./DojoContext.tsx"; import { setupBurnerManager } from "@dojoengine/create-burner"; +/** + * Initializes and bootstraps the Dojo application. + * Sets up the SDK, burner manager, and renders the root component. + * + * @throws {Error} If initialization fails + */ async function main() { const sdk = await init( { diff --git a/examples/example-vite-react-sdk/src/useDojo.tsx b/examples/example-vite-react-sdk/src/useDojo.tsx index 94080948..9d18a9f2 100644 --- a/examples/example-vite-react-sdk/src/useDojo.tsx +++ b/examples/example-vite-react-sdk/src/useDojo.tsx @@ -1,6 +1,15 @@ import { useContext } from "react"; import { DojoContext } from "./DojoContext"; +/** + * Custom hook to access the Dojo context and account information. + * Must be used within a DojoProvider component. + * + * @returns An object containing: + * - setup: The Dojo setup configuration + * - account: The current account information + * @throws {Error} If used outside of a DojoProvider context + */ export const useDojo = () => { const context = useContext(DojoContext); diff --git a/examples/example-vite-react-sdk/src/useModel.tsx b/examples/example-vite-react-sdk/src/useModel.tsx index 228e4cc7..0dbc420c 100644 --- a/examples/example-vite-react-sdk/src/useModel.tsx +++ b/examples/example-vite-react-sdk/src/useModel.tsx @@ -8,10 +8,10 @@ import { Schema } from "./bindings"; * @param model - The model to retrieve, specified as a string in the format "namespace-modelName". * @returns The model structure if found, otherwise undefined. */ -function useModel( - entityId: string, - model: `${N}-${M}` -): Schema[N][M] | undefined { +function useModel< + N extends keyof Schema, + M extends keyof Schema[N] & string +>(entityId: string, model: `${N}-${M}`): Schema[N][M] | undefined { const [namespace, modelName] = model.split("-") as [N, M]; // Select only the specific model data for the given entityId diff --git a/examples/example-vite-react-sdk/src/useSystemCalls.ts b/examples/example-vite-react-sdk/src/useSystemCalls.ts index 17fa419c..06c80303 100644 --- a/examples/example-vite-react-sdk/src/useSystemCalls.ts +++ b/examples/example-vite-react-sdk/src/useSystemCalls.ts @@ -3,6 +3,13 @@ import { useDojoStore } from "./App"; import { useDojo } from "./useDojo"; import { v4 as uuidv4 } from "uuid"; +/** + * Custom hook to handle system calls and state management in the Dojo application. + * Provides functionality for spawning entities and managing optimistic updates. + * + * @returns An object containing system call functions: + * - spawn: Function to spawn a new entity with initial moves + */ export const useSystemCalls = () => { const state = useDojoStore((state) => state); @@ -11,10 +18,19 @@ export const useSystemCalls = () => { account: { account }, } = useDojo(); + /** + * Generates a unique entity ID based on the current account address. + * @returns {string} The generated entity ID + */ const generateEntityId = () => { return getEntityIdFromKeys([BigInt(account?.address)]); }; + /** + * Spawns a new entity with initial moves and handles optimistic updates. + * @returns {Promise} + * @throws {Error} If the spawn action fails + */ const spawn = async () => { // Generate a unique entity ID const entityId = generateEntityId();