CODEX ARENA // docs

CODEX ARENA is a four-layer stack:

1. 1 Ingest — a scheduled job mirrors the public codex-pet-share feed into our database every ~10 minutes.
2. 2 Derive — a pure function (computeStats) turns each pet's public metadata into four 1-99 battle stats.
3. 3 Account — signing in spins up an in-app Solana wallet, drops 5 free starter pets in your collection, and starts tracking your points/wins.
4. 4 Codex Arena — rooms run a host-authoritative simulation and sync state to everyone via Supabase Realtime broadcast.

Every pet on CODEX ARENA originates from codex-pet-share, the public community archive of pets hatched inside the Codex desktop app (shipped by OpenAI in May 2026). We do not generate new pets — we mirror what's already public.

Codex Pets ship as a single PNG spritesheet. CODEX ARENA reads the metadata header and renders any frame on the fly via CSSbackground-position animation — no canvas, no JS tweens.

The renderer (PetSprite) is dumb on purpose: it sets CSS variables and lets the browser composite. That's how 100+ pets can animate on the same page without dropping a frame.

Every pet has four stats in 1..99: PWR, SPD, DEF, STA. They are 100% deterministic — the same pet always yields the same numbers. No DB writes, no RNG.

◇ Inputs

◇ Formulas

// diminishing-returns curve, 0..1
curve(n, k) = 1 - 1 / (1 + n / k)

// per-stat jitter from FNV-1a hash of (id + seed), in ±10
jitter(seed) = (hash01(id + seed) - 0.5) * 20

power   = clamp(20 + curve(likes,     8) * 75 + jitter("p"))
speed   = clamp(25 + (1 - min(name,24)/24) * 60 + salt*20 + jitter("s"))
defense = clamp(20 + curve(downloads, 6) * 70 + jitter("d"))
stamina = clamp(20 + curve(views,    40) * 75 + jitter("e"))

overall = round((power + speed + defense + stamina) / 4)

◇ Why diminishing returns?

Without a curve, a pet with 9000 likes would crush a pet with 90 likes by 100×. The curve() function squashes huge counts into the top of the 0-1 range, so a pet with 8 likes still gets ~50 % of max PWR, and a pet with 800 likes gets ~99 %. The k constants (8, 6, 40) calibrate each stat's "how much is enough" threshold.

Most of CODEX ARENA is browseable without an account, but to create rooms, submit pets, claim starters, or buy from the shop you need to sign in at /auth (email + password, or Google). The same account follows you across the site and is the owner of your pets, points, and in-app wallet.

Every account gets an in-app Solana wallet generated server-side on first login. The keypair is encrypted at rest and only used to pay for actions inside CODEX ARENA — there is no external signing flow, no browser extension required.

The shop at /shop mints a random pet straight into your collection. Payment is debited from your in-app wallet — no external wallet popup.

The boost is added to the pet's derived stats when it shows up in your collection — so a rare Goku hits harder than the same Goku in the public archive.

There is no automatic matchmaker. You either create a room or join one from the lobby at /play. Rooms are stored in the database so anyone with the code (or browsing public rooms) can drop in.

1. 1 Sign in and pick a pet from your collection.
2. 2 Hit Create public room (listed in the lobby) or Create private room (code-only).
3. 3 Share the 4-char room code (e.g. R7K2) — friends join via the lobby or by pasting it.
4. 4 The room creator becomes the host and runs the authoritative simulation for everyone in the room.
5. 5 Round starts when the host launches it. Last pet standing wins; the winner gets points credited to their profile.

The arena runs a fixed-step host-authoritative loop. The host client steps physics, resolves combat, and broadcasts snapshots; other clients send inputs and render the latest snapshot.

The leaderboard at /leaderboard (linked as ranks in the header) sorts every account by total points, with wins shown alongside.