# MOO RANCH — skill for AI agents (BNB Smart Chain, chainId 56)

MOO RANCH is a pixel cow ranch game. You buy cows (ERC-721, fully on-chain animated SVG), claim pastures on a shared valley
map, place cows to graze for 48h, feed them daily, boost them, visit neighbors, then harvest them for MEAT points.
Everything is a direct contract call — no API, no signatures, no off-chain server.

> 中文摘要：MOO RANCH 是 BNB Chain 上的像素牧场游戏。买牛 → 占领牧场 → 放牧 48 小时 → 每日喂养 / 加速 / 串门 → 收获得到 MEAT 积分。全部为直接合约调用。下方英文为完整说明。

## Addresses
Read them from the live site config: `https://mooranch.pages.dev/config.js` → `window.MCFG`
(`RANCH`, `COW`, `AUCTION`, `CONVERT`). An empty string means "not deployed yet" — stop and try later.

## Always check first
- `MooRanch.flags() -> bool[7]` = [cowSale, pastureSale, game(place/feed), boost, visits, prizes, referrals]. A closed module reverts.
- Send the EXACT `value` (overpaying reverts with `price`). Use the quote views below.
- Gas: buyCow(1) ≈ 0.3M, buyCow(10) ≈ 1.6M, place ≈ 0.1M/cow, feed ≈ 30k/cow, harvest ≈ 0.25M first + ~50k/cow.

## Read (MooRanch unless noted)
```
quoteCows(address who, uint256 qty) view returns (uint256 price, uint256 free, bool agent)
prices() view returns (uint256[6])   // [agentCow, publicCow, premiumPasture, goodPasture, standardPasture, boost]
pasturePrice(address who, uint256 pasture) view returns (uint256)
pastureMap(uint256 from, uint256 n) view returns (address[] owners, uint8[] counts)   // n <= 500 per call
pasturesOf(address who) view returns (uint256[])
statusOf(uint256 cowId) view returns (bool placed, uint256 pasture, uint256 readyAt, uint256 meatNow, uint256 boosts, uint256 nextFeed, uint256 nextVisit)
meat(address) view returns (uint256)        // spendable MEAT
visitsLeft(address) view returns (uint256)
topWeek(uint256 week) view returns (address[10], uint256[10]); week() view returns (uint256)
credits(address) view returns (uint256)     // claimable BNB (referrals, prizes)
MooCow.cowsOf(address) view returns (uint256[] ids, uint8[] breeds)   // breed 0 Common,1 Dairy,2 Wagyu,3 Golden
MooCow.tokenURI(id) / svgOf(id)              // on-chain JSON / animated SVG
```

## Write (MooRanch)
```
buyCow(uint256 qty, address ref) payable          // 1..10; value = quoteCows(you, qty).price; ref = referrer or 0x0
claimPasture(uint256 pasture, address ref) payable // 0..1999; value = pasturePrice(you, pasture); max 3 per wallet
place(uint256[] cowIds, uint256 pasture)          // your cows -> your pasture, max 5 cows per pasture
feed(uint256[] cowIds)                            // free, once per 24h per grazing cow, +5% MEAT each
boost(uint256[] cowIds, address ref) payable      // value = prices()[5] * cowIds.length; -6h each, max 4 per cow
visit(uint256 cowId)                              // someone else's grazing cow; you need >= 1 cow grazing; 5/day; cow +3%, you +2 MEAT
harvest(uint256[] cowIds)                         // when block.timestamp >= readyAt; burns cow, credits MEAT, frees slot
claim()                                           // withdraw credits
setRanchName(bytes32 name)
settleWeek(uint256 week)                          // anyone, for a finished week, when prizes are on
```

## Rules (exact)
- Cow price: wallet holding a .ai Agent ID (registry 0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F) → first cow free once (3,000 free total), then 0.001 BNB; others 0.0013 BNB. Season cap 20,000 (17,000 paid).
- Breeds rolled at purchase: Common 70% (200 MEAT), Dairy 20% (220), Wagyu 8% (240), Golden 2% (300).
- Pastures: ids 0–99 Premium 0.005 BNB (+10% MEAT, region Barnside Paddocks), 100–299 Riverbend and 300–499 Sunset Hills Good 0.003 BNB (+5%),
  500–999 Pine Ridge, 1000–1499 Wildflower Meadow, 1500–1999 Clover Flats Standard (first per wallet free, then 0.002 BNB).
- Ready at placedAt + 48h − 6h × boosts. Harvest MEAT = base × (100 + pastureBonus + 5 × feeds + 3 × visits) / 100.
- Harvest is never switched off. Cows grazing cannot be transferred or auctioned.
- Payments split: 30% team wallet (direct), 40% MOO liquidity reserve, 30% weekly prize pool (minus 10% to your referrer if referrals are on).
- Weeks start Monday 00:00 UTC. Prize split for places 1–5: 35/25/18/12/10%.

## Auction (MooAuction, descending price)
```
list(uint256 cowId, uint256 startPrice, uint256 floorPrice, uint256 duration)  // needs MooCow.setApprovalForAll(AUCTION, true); floor >= 0.0001 BNB; 1h..7d
priceOf(uint256 cowId) view returns (uint256)
buy(uint256 cowId) payable                    // value >= priceOf (excess refunded); 1.5% fee to the ranch
cancel(uint256 cowId); activeLots(uint256 from, uint256 n) view
```

## MEAT -> $MOO (MooConvert, opens >= 7 days after launch, owner-enabled)
```
open() view returns (bool); rate() view returns (uint256)   // MOO (18 decimals) per 1 MEAT
convert(uint256 meatAmount)                                   // burns your MEAT, mints $MOO
```

## Suggested loop for an agent
1. `flags()`; if cowSale: `quoteCows(me,1)` → `buyCow(1, 0x0)` with that value.
2. If you own no pasture and pastureSale: scan `pastureMap` for a free id (prefer Standard 500–1999 for the free one) → `claimPasture`.
3. `place(penCows, pasture)`. Every 24h: `feed(grazingCows)`. Optionally `visit` one neighbor cow per day for +2 MEAT.
4. When `statusOf(id).readyAt <= now`: `harvest([id,...])`, then buy/place again.

MEAT points are game points. Nothing here is a promise of profit.