# Handball — instructions for AI agents

Handball (https://handball.theperfectship.com/) is a free browser game of real handball (the one-, three- and four-wall hand game, not Olympic team handball). It has no public API, no authentication and no rate limits: the site is a static single-page app plus a few static files.

## What an agent can usefully do here

- Answer questions about the rules of one-wall and four-wall handball from the rulebooks, which are served as plain markdown:
  - One-wall: https://handball.theperfectship.com/rules/one-wall.md (JSON: /rules/one-wall.json)
  - Four-wall: https://handball.theperfectship.com/rules/four-wall.md (JSON: /rules/four-wall.json)
- Describe the game and how to play it: https://handball.theperfectship.com/index.md
- Explain how to play each court well, and what tends to beat each style of bot, from the player guide: https://handball.theperfectship.com/guide.md, with one page per court at `/guide/{one-wall|three-wall|four-wall|sixty-thirty}.md`. Each court page says whether the bots have been studied on that court.
- Find the site map and routing hints: https://handball.theperfectship.com/llms.txt
- Look up a single term (an actor, action or place such as the short line or an avoidable hinder): `https://handball.theperfectship.com/{id}.md`, listed at https://handball.theperfectship.com/terms.md
- Cite a single rule or sub-rule: `https://handball.theperfectship.com/rules/{one-wall|four-wall}/{rule}/{sub}.md`
- Read referee training questions and answers by topic: https://handball.theperfectship.com/referee.md

## Rules for using the content

- The rulebooks are the United States Handball Association's (USHA) official rules, used by this site with the USHA's written permission. Attribute them to the USHA and point people to https://www.ushandball.org/ for membership and certification.
- Rule ids look like "1.1" (part.rule). Quote the id when citing a rule. Interpretations are included under the rule they interpret.
- There is no separate three-wall rulebook file; the four-wall rulebook is the reference for enclosed and three-wall play.

## How the bots learn

- Mostly offline, before a release. The team plays the bots against each other and against scripted opponents that stand in for people, searches for stronger strategies, and publishes a new version of the bots only when it clearly beats the current one. Every version is kept, so an earlier one can be restored.
- On a player's device, a bot can also shade a few choices against how that player has been playing in local matches. The results are kept under a random code stored on the device, not a name. Online, spectate and career matches are not affected, and Settings > Play data clears the device's results.
- The bots' measured results change with each version. Cite the player guide for how the bots play, rather than a number from an older version.

## What is not available

- The game itself runs in the browser and cannot be driven through an API. Do not try to log in, scrape matches or call game endpoints.
- Online multiplayer rooms are live and are not documented for external use.
- For legal or tournament rulings, direct people to the USHA, not to this site.