---

name: dojo-entities description: | Use when querying, fetching, or subscribing to game entities in dojo.js. Triggers: entity query, fetch entities, useModel, useEntityQuery, ToriiQueryBuilder, subscribe entities, getEntities, entity subscription, model data

Dojo.js Entity Queries & Subscriptions

When to Use

Use this skill when:

• Fetching game entities from Torii
• Building queries with filters and pagination
• Subscribing to real-time entity updates
• Accessing model data in React components

ToriiQueryBuilder

Build type-safe queries for entities:

Copyimport { ToriiQueryBuilder, KeysClause, MemberClause } from "@dojoengine/sdk";

// Basic query with limit
const query = new ToriiQueryBuilder<typeof schema>()
    .withLimit(100)
    .build();

// Query with clause filter
const query = new ToriiQueryBuilder<typeof schema>()
    .withClause(
        KeysClause(["game-Player"], [playerAddress], "VariableLen").build()
    )
    .withLimit(50)
    .build();

// Query with ordering
const query = new ToriiQueryBuilder<typeof schema>()
    .addOrderBy("game-Player.score", "Desc")
    .withLimit(10)
    .build();

// Query specific models
const query = new ToriiQueryBuilder<typeof schema>()
    .addEntityModel("game-Player")
    .addEntityModel("game-Position")
    .withLimit(100)
    .build();

Query Methods

Pagination

Copyconst query = new ToriiQueryBuilder<typeof schema>()
    .withLimit(50)                    // Max results
    .withCursor(nextCursor)           // Pagination cursor
    .withDirection("Forward")         // "Forward" | "Backward"
    .build();

Clause Types

Copy// Keys clause - filter by entity keys
KeysClause(["namespace-Model"], [key1, key2], "VariableLen")

// Member clause - filter by field value
MemberClause("namespace-Model", "fieldName", "Eq", value)

// Composite clause - combine clauses
CompositeClause("And", [clause1, clause2])

Fetching Entities

Copyconst { sdk } = useDojoSDK();

// One-time fetch
const result = await sdk.getEntities({
    query: new ToriiQueryBuilder<typeof schema>()
        .withClause(clause)
        .withLimit(100)
});

// Access results
result.items.forEach(entity => {
    console.log(entity.entityId, entity.models);
});

// Pagination
if (result.next_cursor) {
    const nextPage = await sdk.getEntities({
        query: new ToriiQueryBuilder<typeof schema>()
            .withCursor(result.next_cursor)
            .withLimit(100)
    });
}

Subscribing to Entities

Copyconst { sdk } = useDojoSDK();

const [initialData, subscription] = await sdk.subscribeEntityQuery({
    query: new ToriiQueryBuilder<typeof schema>()
        .withClause(clause)
        .withLimit(100),
    callback: ({ data, error }) => {
        if (error) {
            console.error("Subscription error:", error);
            return;
        }
        // Handle real-time updates
        console.log("Entity updated:", data);
    }
});

// Clean up subscription
subscription.cancel();

React Hooks

useModel - Single Entity Model

Copyimport { useModel } from "@dojoengine/sdk/react";

function PlayerStats({ entityId }) {
    // Format: "namespace-ModelName"
    const player = useModel(entityId, "game-Player");

    if (!player) return <div>Loading...</div>;

    return <div>Score: {player.score}</div>;
}

useModels - All Entities with Model

Copyimport { useModels } from "@dojoengine/sdk/react";

function Leaderboard() {
    const players = useModels("game-Player");

    return (
        <ul>
            {Object.entries(players).map(([entityId, player]) => (
                <li key={entityId}>{player?.name}: {player?.score}</li>
            ))}
        </ul>
    );
}

useHistoricalModel - Time-series Data

Copyimport { useHistoricalModel } from "@dojoengine/sdk/react";

function PlayerHistory({ entityId }) {
    const history = useHistoricalModel(entityId, "game-Player");

    return (
        <ul>
            {history.map((snapshot, i) => (
                <li key={i}>Score: {snapshot.models.game.Player.score}</li>
            ))}
        </ul>
    );
}

Entity ID Generation

Copyimport { getEntityIdFromKeys } from "@dojoengine/utils";

// Generate entity ID from keys
const entityId = getEntityIdFromKeys([
    BigInt(playerAddress),
    BigInt(gameId)
]);

Common Pitfalls

1. Model name format: Use "namespace-ModelName" format (hyphen-separated)
2. Entity ID type: Must be string, use entityId.toString() if needed
3. Subscription cleanup: Always cancel subscriptions on component unmount
4. Query limits: Default limit is 100, set explicit limits for large datasets