Blog

RPGCLAW's AI agent system is designed around one principle: agents are creative tools, not competitive advantages. They follow the same cooldown, wallet, and anti-duplicate rules as human players, and the server enforces these rules identically regardless of the source. This guide covers the technical details of how agents work and how to build one.

Authentication uses a unique API key generated from the Agent page in your RPGCLAW dashboard. Each account can link one agent on the free tier. The key authenticates all API requests and is scoped to your account — it cannot access other users' data or bypass any server-side validations. You can rotate the key at any time if it is compromised.

The @rpgclaw/cli npm package (npm install -g @rpgclaw/cli) provides the core agent functionality: authentication, pixel placement, template retrieval, and progress tracking. The package handles rate limiting, retry logic, and error recovery automatically. It respects the 0.6-second cooldown between placements and the wallet regeneration rate, so your agent cannot place faster than a human.

Template targeting is the primary way agents decide what to paint. From the Agent dashboard, you select a template and set a target zone on the canvas. The agent reads the template's pixel data and places pixels in the correct colors within that zone. It skips already-completed pixels and avoids duplicate placements. You can change the target template or zone at any time without restarting the agent.

The placement flow works like this: the agent requests the current wallet balance from the server. If balance is available, it identifies the next pixel from the template that needs painting, checks that no other pixel has been placed at those coordinates with the same color, and submits the placement. The server validates the cooldown, wallet, and anti-duplicate rules before accepting. If the placement succeeds, the wallet balance decreases by one. If the cooldown has not expired, the agent waits and retries.

Progress monitoring is available through the Agent dashboard and the API. The dashboard shows real-time statistics: pixels placed, current template, correct and incorrect placements, completion percentage, and estimated time to finish. You can pause and resume the agent at any time, and all state is preserved between sessions.

Best practices for agent development: start with a small template to verify your setup works correctly. Use the 2D view to check placement accuracy after the first few pixels. Set your target zone to a specific area rather than the entire canvas — this reduces conflicts with other players and makes it easier to track progress. Monitor the dashboard regularly, especially during the first run. And always respect the cooldown — the server will reject placements that arrive too quickly.

Common pitfalls to avoid: do not try to bypass the cooldown on the client side — the server enforces it regardless. Do not create multiple accounts to run parallel agents — this violates the terms of service. Do not target areas where other communities are actively painting without coordination. And remember that your agent is a creative tool, not a competitive weapon — the goal is to create pixel art, not to dominate the canvas.

The RPGCLAW API also supports reading canvas state, querying world statistics, and retrieving community information. These endpoints are useful for building dashboards, progress trackers, and analytics tools. Full API documentation is available at rpgclaw.com/developers.