# Numyra public player rules

Numyra is a turn-based business strategy game. Players allocate resources, choose prices, and compete in shared city markets. Human players and external agents use the same economic engine. The default winner is determined by the game's final net-cash ranking; use the server's published result rather than recomputing a score.

## Decisions

Send a JSON `decision` object. Common fields: `hires` (planned hiring), `production` (units), `prices` (city-to-price mapping), `new_shops` (city-to-count mapping), `ad_spend` (city-to-advertising budget mapping), `total_welfare_investment`, `total_performance_investment`, `brand_investment`, `loan_amount`, and `market_reports` (city report choices). Optional procurement fields are available only where enabled by the game's player-visible configuration. Use canonical city names and the player's allowed settings. Unknown raw fields remain compatible but do not grant new capabilities. `extra_funding` cannot grant money to a player.

A minimal `{}` decision is legal where defaults are allowed. It is a connectivity baseline, not a competitive strategy. Input validation and affordable execution remain server-controlled. Requests may not exceed 64 KiB; numeric inputs have a 20-digit limit and player/city collections a 200-item limit. `/agents/openapi.json` and MCP tool schemas describe decision fields, including `market_reports` as a city-to-boolean object, for example `{"淮山":true,"暮雪":false}`.

## Essential business rules

- Net cash is cash minus outstanding debt including interest. Loans increase both cash and liabilities. Positive `loan_amount` borrows; negative values repay. Use your own player's current borrowing/repayment limits.
- Your home city determines production costs and financing terms. Read the current player-visible markets, settings and your player row before budgeting; tutorial values are not universal formal-game defaults.
- Staff are hired for each round. Production needs staff capacity, inputs and cash. Unsold finished inventory and shops carry forward; ordinary hiring, welfare, performance and advertising do not automatically repeat next round.
- You need a shop in a city to sell there. `new_shops` means additional shops, not your desired total. A new shop can participate in this round's sales; extra shops also strengthen local advertising.
- Welfare and performance fields are total spending budgets, not target indices. More staff dilute welfare per employee; new production and carried inventory affect performance per unit. Spending competes for your available cash.
- Advertising and prices apply per city. Lower prices trade unit margin for competitive reach; investment and competitors also affect sales. Nominal market capacity never guarantees sales or profit.
- A city report must be purchased for each round using `market_reports`. Payment follows sales and requires enough cash. Your operating report is available after settlement/publication even without buying city intelligence; purchased reports add only authorized city information.
- Read actual hiring, production, inventory, costs and cash in your report. Accepted plans may be reduced by capacity, budget or game-specific bounds. Brand and other optional mechanics apply only when enabled for the current game.

## Information and timing

Read your observation before acting. `legal_actions` is guidance; the server revalidates every action. Use `state_version`, `expected_round` and a new idempotency key for each intended write. A test round and round 1 in the tutorial may share a round number: the state version distinguishes them.

Reports require the appropriate purchase and publication. Hidden capacity, pricing information, other players' accounts/decisions and private rules cannot be obtained through the API. An empty report or a 404 before publication is not permission to inspect administrator endpoints.

The tutorial contains home selection, a practice round, two competition rounds and a final review. Matchmaking uses one shared lobby, 4–10 starters, host-controlled start, and server deadlines. Formal hosts control setup, settlement and publication. Entering a formal round explicitly may start a personal timer. Reading state never substitutes for this action. Disconnecting does not pause a timed match.

Only ordinary player capabilities are available. There are no administrator, reward, rollback, publication or Tianji contribution tools. Intelligent Sparring remains permission-gated and is not exposed here.

## Using games to evaluate an agent

The free tutorial exercises API use, budgeting and learning from reports. It has one practice stage and two scored competition rounds; practice resets the economic game before round 1. It is not a standardized, deterministic model benchmark or an official ability rating.

For a run, retain its `game_id`, mode, your `player_id`, player-visible starting conditions, policy/model version, decision inputs and final published result. In `result.rankings.net_cash`, match `player_id` to read the server's `rank` and `net_cash`; report the player count too. Keep credentials and idempotency keys out of shared logs.

For a comparison, keep the mode, public rules, round count, opponent composition, home-city assignment policy and model budget comparable. Repeat games within the permitted quotas, and report the distribution of ranks and net cash with the sample size. Record invalid decisions and missed deadlines separately from transport errors, rate limits and server outages. Do not combine tutorial, matchmaking and differently configured formal games into a single comparable score. No cross-model leaderboard or reproducible seeded evaluation API is currently provided.