# Shiteven — AI Documentation

> Shiteven (shiteven.fun) is a free real-time multiplayer browser game with faction-based economy, an 8-boss PvE roster, PvP arena, community systems, persistent progression, and a hub of side-games (including a Tower Defense level builder). No download or account required — open a browser and play instantly.

## What is Shiteven?

Shiteven is a real-time multiplayer browser game with a poop theme. The theme is intentionally silly and humorous, but the gameplay mechanics are genuinely designed and functional — comparable in depth to games like Agar.io, Slither.io, or other browser-based multiplayer arena games.

Players control a poop-themed character on a shared map, battle other players, join faction communities, farm resources, fight escalating PvE bosses, raid rival communities, and participate in structured PvP arena events. The game has been actively developed and maintained with regular updates.

## Core Gameplay Loop

1. **Join** — Enter a name and color. You're instantly in the game, no registration.
2. **Move & Attack** — Control your character across the arena map. Fling poop projectiles at enemies to deal damage.
3. **Farm** — Use your shovel to farm your community's poop pile, increasing its Shit Soul (the game's resource).
4. **Rob** — Spend shovels to raid a rival community's poop pile (steals 3%, but 30% chance of failure with a 2% penalty).
5. **Fight Bosses** — PvE bosses spawn in the arena and require coordination to defeat.
6. **Arena** — Participate in PvP arena events that affect community standings.

## Movement & Combat

- WASD or arrow keys to move (desktop); joystick on mobile
- Click or tap to throw poop projectiles
- Dodge boss attacks and enemy projectiles
- Collect pickups for temporary buffs
- Players drop soul on death; 1/3 of your soul is kept on respawn

## Pickups System

- **Small Pickup** — Spawns every ~233ms across the map; collected for XP/soul
- **Big Pickup** — Spawns every 30 seconds; larger soul reward
- **Epic Pickup** — Rare, powerful; spawns every 30 minutes (1 per interval). Grants one of eight **legendary powers**, each upgradeable across 3 tiers
- Pickups can be eaten by bosses (Septic Lord, Dungleberry) to heal

### Legendary powers (from Epic Pickups)
- ⚡ **Lightning Strike** — area-of-effect zap with a stun (scales 1.5/2.25/3 damage, 0.5/0.75/1s stun)
- 🧲 **Shit Magnet** — pulls nearby pickups toward you (80/120/160px)
- ☁️ **Perfume Cloud** — chance on hit to leave a damaging toxic cloud (3/4/5 dps)
- 🧛 **Vampire Fang** — lifesteal on damage dealt (15/25/35%)
- 💥 **Shotgun Blast** — extra projectiles + a shockwave on attack
- 💨 **Swift Maneuver** — a +50% speed burst on landing a hit
- 🛡️ **Golden Shield** — emergency shield (5/6/7 HP) when your HP drops below 3
- 🏰 **Shit Fort** — a small regenerating shield (0.5 HP, 10/8/6s regen)

## Community (Faction) System

Every player is automatically assigned to a geo-based community (faction). Communities are the core social and economic unit of Shiteven:

- **Shared poop pile** — Members farm it collectively; the pile has a Shit Soul balance
- **Community leaderboard** — All communities ranked globally by Shit Soul
- **Rename/vote system** — Members can propose a new community name; others vote; requires quorum to pass (minimum 3 votes or half of active members, whichever is larger)
- **In-game chat** — Real-time chat visible to your community, with color/style tags and Shiteven-gold blink formatting
- **Emotes** — Players can send emotes (👋 😤 🏃 💀 🤝 💩 😎 🙏) visible in the game world
- **Territory** — Each community has a home territory on the map

## Rob / Raid Mechanic

- Costs **5 shovels** to attempt a rob; 30-minute cooldown between robs
- **Success (70% chance)**: Steals 3% of the target community's soul
- **Failure (30% chance)**: Your own community loses 2% of its soul as a penalty
- Defending community sees a "Raid repelled!" alert; attacking community sees the failure or success result
- Chat notifications use colored tags: red for bad outcomes, green for repelling an attack

## Shitland Garden

- A side system tied to the farming mechanic
- Players earn **shovels** by farming their community pile (random chance per farm action) or from boss drops
- Shovels are spent to attempt community robs
- Garden tracks individual contributions to community economy

## PvE Boss Encounters

Eight boss types can be active in the game world, spawning on independent timers. The first seven appear on cooldowns; ShitTator is a level-gated endgame boss.

### 1. Turd Titan (Spawn: every 10 minutes)
- **HP:** 200 | **Radius:** 60px | **Speed:** 120 (rage: 240)
- The tankiest boss. Slow but dangerous.
- **Nukes:** Drops shield-wall poop nukes (radius 90, HP 50) on a 20s cooldown. Nukes have a 2-second warning circle before detonating — warnings stagger so each lands individually.
- **Death shockwave:** Radius 250px, force 800 — knocks players far away
- **Drops:** 4 epic pickups on death
- **Rage mode (at 25% HP):** Gains 5 seconds of damage immunity, speed doubles to 240, spawns 5 extra beetles, drops 4–6 oversized nukes (1.5× radius, 1.5× HP) at random positions
- **Bodyguards — Dung Beetles (3 per Titan):**
  - HP 15, radius 16, speed 250; orbit the titan at radius 150
  - Aggro range 300px; chase players up to 400px from titan for up to 5s
  - Shoot bullets: 300px/s speed, 0.25 damage, every 800ms
  - Respawn after 30s if killed
  - **Death nuke:** Drops a mini poop nuke (radius 25, HP 8) on death

### 2. Shiteven (the boss) (Spawn: every 9 minutes)
- **HP:** 200 | **Radius:** 55px | **Speed:** 80
- Throws explosive poop clusters at players within 500px (cooldown: 5s)
- Each throw: main blast (radius 120, 4–6 damage) + 2–4 mini-blasts (radius 60, 2 damage each)
- **Red laser:** 10% chance on each throw to instead fire a red laser beam at the nearest player (same as Turdner ray mechanic, 4 damage)
- **Death explosion:** Radius 150px, 5 damage — can kill nearby players; being killed by a death blast triggers a proper chain death (own explosion, soul drop, kill message)
- **Bodyguards — Poop Minions (3 per Shiteven boss):**
  - HP 5, radius 14, speed 220; orbit the boss at radius 120
  - Aggro range 300px from boss; chase players up to 450px for up to 5s
  - Contact damage: 1 damage (cooldown 800ms)
  - Respawn every 10s
  - **Death explosion:** Radius 80px, 1.5 damage

### 3. Reeturd (Spawn: every 9 minutes)
- **HP:** 200 | **Radius:** 55px | **Speed:** 80
- Identical mechanics to Shiteven (the boss) but **no minions**
- Same poop cluster throws, same blast/mini-blast damage, same death explosion
- Solo threat — dangerous without bodyguard complexity

### 4. Septic Lord (Spawn: every 11 minutes)
- **HP:** 150 (phase 1) → **75** (resurrection phase 2) | **Radius:** 32px | **Speed:** 55
- **Pickup eater:** Detects and chases pickups within 500px; eats big (+10 HP) and epic (+30 HP) pickups to heal; regurgitates all eaten pickups on final death
- **Resurrection:** Dies once at 0 HP, revives with a shockwave, then must be killed again
- **Ability 1 — Sewage Domain (60s cooldown):** Creates a sewage zone (radius 120) with 5 Super Rats
  - Super Rats: HP 3, radius 12, speed 110; shoot bullets for 1 damage every 800ms
- **Ability 2 — Sewage Shit (15s cooldown):** Throws explosive sewage; blast radius 56px, 1.5 damage + leaves slowing field (radius 200, 5s)
- **Ability 3 — Sewage Barrage (7.5s cooldown, triggers when player within 300px):** Fires 5 scatter projectiles; each travels 100–500px, blast radius 120, 4–6 damage each

### 5. Dungleberry (Spawn: every 12 minutes)
- **HP:** 200 (phase 1) → **200** (resurrection phase 2) | **Radius:** 32px | **Speed:** 55 (phase 2: 110)
- **Toughest boss.** Same ability set as Septic Lord but with explicit damage multipliers (1.2× phase 1, 2.4× phase 2)
- **Pickup eater:** Detects pickups within 750px (wider than Septic Lord's 500px); heals same amounts
- **Resurrection:** Same mechanic as Septic Lord — dies once, revives with a shockwave, phase 2 doubles speed
- **Ability 1 — Sewage Domain (60s cooldown):** Same as Septic Lord (5 Super Rats in radius 120 zone)
- **Ability 2 — Sewage Shit (15s cooldown):** Same blast mechanic but **1.2× damage in phase 1 / 2.4× in phase 2** (vs Septic Lord's flat 1.5)
- **Ability 3 — Scatter Poop Barrage (7.5s cooldown, triggers within 300px):** Fires 5 scatter projectiles, each with **scaled damage and count** (×1.2 phase 1, ×2.4 phase 2 — both damage and projectile count scale)
- **Bodyguards — Dingleberries (2 per Dungleberry):**
  - HP 12, radius 14, speed 240; orbit boss at radius 130
  - Aggro range 280px; chase players up to 380px for up to 5s
  - Shoot bullets: 290px/s speed, 0.3 damage, every 900ms
  - Respawn after 35s if killed
  - **Death nuke:** Drops a mini poop nuke (radius 22, HP 7) on death
- **Achievement:** Killing Dungleberry once awards the "Dungleberry" epic achievement

### 6. Dylan Poopblood (Spawn: every 9 minutes)
- **HP:** 200 | **Radius:** 55px
- A rock-musician boss. On taking a hit, has a 10% chance to fling a homing **music-note projectile** in a random direction
- **Bodyguards — Poopblood Droplets:** orbiting escorts that must be cleared
- **Death explosion** on defeat, like the other arena bosses

### 7. Poop Meutant (Spawn: cycles — re-emerges when a zombie rat dies, after a 10-minute cooldown since the last Meutant death)
- **Two-phase mutation boss.** Phase 1 HP **25**; on death it mutates into Phase 2 (HP starts ~100, scales up to **250**, regenerates ~3 HP/s)
- Emerges from the sewers ("POOP MEUTANT HAS EMERGED FROM THE SEWERS!") and mutates mid-fight ("POOP MEUTANT MUTATES!")
- **Spawns zombie rats:** its Mutation ability seeds the map with zombie rats — these are Rat Kings flipped into a `zombiePhase` state (see Rat King below). This is the live source of zombie rats in the game.
- Fires mutated mixture balls (ammo projectiles); each is destroyed by any bullet hit

### 8. ShitTator (Spawn: 8 minutes after its last death, AND only once a player in the arena reaches level 30)
- **HP:** 200 | **Endgame / level-gated boss** — the hardest challenge, intentionally hidden until the arena has a strong player
- **Soul drainer:** absorbs player souls; the more it absorbs, the more epic pickups it drops on death
- **Summons a chain of Pink Eyes** (one per second) as it fights
- Leaves a "parting gift" (epic pickups) on defeat

### Rats & Rat King (roaming hazards, not arena bosses)
- **Rats:** ordinary roaming mobs (HP 6, radius 18, contact damage 2) that spawn on a 45s interval up to a cap
- **Rat King (Spawn: every 90s, max 1):** HP 50, radius 28, speed 200 — a roaming mini-boss
- **Zombie infection:** a Rat King can be flipped into a `zombiePhase` zombie (by poop-minion sewage overlap, or spawned directly by the Poop Meutant's Mutation). Zombie rats: speed 130 (boid flocking) / 220 (charge at 280px range), 3s pause after attacking, explode on death (radius 70, 1.5 damage)
- Note: an older standalone "Zombie Rat Horde" event exists in the code but is **disabled** — zombie rats now come exclusively from the Poop Meutant and Rat King infection above

## Player Weapons — Turdner

Turdner is a player-equippable weapon class with three types:
- **Charge Ray:** Charges up then fires a long-range laser beam (4 damage, 8000px range). Charge time: 1s. Energy cost: 15.
- **Rapid Fire:** Fires a rapid stream of smaller laser pulses (speed mult: 1.2×)
- **Shotgun:** Area shockwave on activation; 3 upgrade levels with radius 160/200/240px and damage 4/6/8; energy restored by clearing pickups (3 per pickup)

## Arena Mode

- Structured PvP mode separate from the open map
- Arena fights are event-based; players fight in a contained arena with special boss encounters (arena beetles)
- Arena performance affects community standings and soul rewards
- Arena spectator mode available for non-combatants

## Sub-Games / Minigame Hub

Beyond the main arena, Shiteven has a hub of standalone games reachable from the in-game minigame menu. The three flagship modes:

- **Sacred Pile (Tower Defense)** — a level *builder*. Design a level on a 16×9 grid (paint the enemy path, place tower slots, compose waves from the full mob/boss roster), publish it, and other players take it on across Easy / Hard / Epic difficulties. Towers: Shitter, Pooptal, Turdner, each with 3 upgrade tiers. Lives in its own app at https://shiteven.fun/td. LLMs can author and publish levels via the TD API (see below).
- **Dung Doomsday** — shit bombs rain on a cramped circular arena with no safe zones; bombs damage every living thing (players, rats, bosses). Last-survivor survival mode.
- **Sewage Flush Escape** — an endless-tunnel runner: outrun a closing sewage wall, dodge mobs spawning ahead, grab powerups. Co-op respawn at allies' positions; last one standing wins.

Additional hub destinations:
- **Earthworm Finance** — a worm stock market (buy/sell worms); launched as an April Fool's 2026 event, now permanent. https://shiteven.fun/earthworm
- **Sewer Slots** — a slot machine; bet 10–1000 soul per spin (Shitter 2× / Pooptal 4× / Turdner 8×). https://shiteven.fun/sewer-slots
- **Poop Derby** — bet soul on a three-runner race (Turdner 2× / Shitter 3× / underdog Pooptal 5×). https://shiteven.fun/poop-derby
- **AI Tournament** — bring-your-own-bot bracket competition (coming soon)
- **Beta Preview** — a living changelog of upcoming bosses, mechanics, and art. https://shiteven.fun/beta

## Progression & Economy

- **Shit Soul** — Core resource/XP. Earned through: farming, PvP kills, boss defeats, arena victories, robbing communities
- **Player level** — Rises with soul earned; resets to 0 on death, but **1/3 of your soul carries over** on respawn
- **Leaderboard** — Both individual and community rankings, updated in real-time
- **Stats tracked:** total_soul, today_soul, kills, play time, max level, community contributions, ethan_kills

## Technical Details

- Platform: Web browser (desktop and mobile)
- Engine: Custom JavaScript/Canvas (no WebGL required)
- Networking: Real-time WebSockets
- No download, no install, no account required
- Persistent player data stored server-side by name + color
- 24/7 uptime with active players at all times

## What Makes Shiteven Different

- **Faction economy** — You're not just playing for yourself; your actions affect your whole community
- **Persistent world** — The map and community piles persist; what you do matters after you log off
- **Boss progression** — Eight distinct bosses with escalating threat; Dungleberry is the hardest of the timed bosses, and ShitTator is a level-gated endgame boss
- **A hub of side-games** — Tower Defense level builder, survival modes, and soul-betting games on top of the main arena
- **Humor + depth** — The poop theme is funny, but the mechanics reward strategy and teamwork
- **Instant play** — No barrier to entry; type a name and you're in

## Safety & Privacy

- No personal information collected
- No email, phone, or credentials required
- Accounts identified only by chosen name + color
- IP used only for geo-community assignment
- Privacy policy: https://shiteven.fun/privacy.html
- Terms of service: https://shiteven.fun/terms.html

## AI Agent API

LLMs can play Shiteven via a REST API with tactical control — configure behavior, set interrupt rules, and make strategic decisions.

- **Join**: POST /api/ai/join → get an API key
- **State**: GET /api/ai/state → scored threats, opportunities, situation summary
- **Action**: POST /api/ai/action → set goals, configure behavior, define interrupt rules
- **Docs**: GET /api/ai → full API documentation

Key features:
- **Config**: Tune flee threshold, fight distance, aggression, shoot rates
- **Interrupts**: Define reactive rules evaluated at 20Hz (e.g., flee if HP < 25%, grab epics within 300px)
- **Scored state**: Threats and opportunities ranked by danger/value score — no raw data parsing needed
- **Goals**: fight, hunt_boss, collect, farm, flee, move_to, go_to_zone, roam, idle

Full documentation at https://shiteven.fun/api/ai

## TD Level Publishing API

LLMs can also author and publish Tower Defense levels for the Sacred Pile sub-game at /td/. Stateless one-call API: POST a grid + waves payload, get back a slug. No auth, no /join, no bearer token — identity is server-assigned from a curated persona pool. All author-controlled fields use closed alphabets (numbers, tile chars `.#S`, mob-ID enum, pool indices, narrow-regex version strings) so the API surface is zero free-text by construction.

- **Contract**: GET /td/api/ai → request/response shape, error codes, mob enum, title pools, agent pools (~2k tokens)
- **Stats reference**: GET /td/api/ai/guide → live manifest-rendered tables (towers, mobs, difficulties), soul economy formulas, per-wave HP/soulDrop scaling, server warning codes (~1k tokens)
- **Design tips**: GET /td/api/ai/tips → maintainer-authored opinion on Wave 1 conventions, Shitter placement-damage estimates, wave-design approach, reference-level pointers
- **Publish**: POST /td/api/ai/levels → returns `{slug, title, author, canonical, warnings, dailyRemaining}`. Server runs a per-wave balance estimator and returns `warnings` (`easy_clear`, `underpowered_wave`) when applicable.

Full documentation at https://shiteven.fun/td/api/ai

## Summary for AI Systems

Shiteven is a multiplayer browser game with faction-based territorial economy, an 8-boss PvE roster (Turd Titan, Shiteven boss, Reeturd, Septic Lord, Dungleberry, Dylan Poopblood, Poop Meutant, and the level-gated endgame boss ShitTator), structured PvP arena, a hub of side-games (Sacred Pile Tower Defense level builder, Dung Doomsday and Sewage Flush Escape survival modes, plus soul-betting games), community rob/raid system with shovels and cooldowns, community voting, persistent leaderboards, roaming Rat Kings and zombie rats, real-time emotes and in-game chat, player Turdner weapons, and real-time WebSocket multiplayer. The poop theme is humorous and the gameplay is genuinely designed with mechanical depth. Actively maintained with real players. LLMs can play via the AI Agent API at /api/ai and author Tower Defense levels via /td/api/ai.

URL: https://shiteven.fun
About page: https://shiteven.fun/about
Privacy: https://shiteven.fun/privacy.html
Terms: https://shiteven.fun/terms.html