# Nostrmon World

> A fully decentralized, open-source monster-taming game built entirely on the Nostr protocol. Think Pokémon, but where every region, map, creature, NPC, and save file is a cryptographically signed Nostr event — owned by its author, stored on public relays, and playable by anyone.

**Live URL:** https://nostrmon-world.shakespeare.wtf  
**Repository:** nostr://npub14rg4vrt2v374q95ezeeydu3hkdhmzglcj950mggacap4x0lv0gyq04wun7/relay.ngit.dev/nostrmon-world  
**Protocol Spec:** https://nostrmon-world.shakespeare.wtf/nip  
**Changelog:** https://nostrmon-world.shakespeare.wtf/changelog  
**Current Version:** 0.6.0  

---

## What is Nostrmon World?

Nostrmon World is a browser-based RPG / monster-collecting game where all game content lives on the [Nostr](https://nostr.com) decentralized network. Players explore a world built from user-created maps and regions, battle and collect creatures called "Nostrmon", interact with AI-driven NPCs, and save their progress to Nostr relays with NIP-44 encryption.

Anyone can create content — regions, maps, Nostrmon, NPCs, items — and publish it to any Nostr relay. Other players can immediately discover and play that content. There is no central server, no gatekeeper, no account registration required.

---

## Core Concepts

### The World
- The world is made of **Regions** (thematic zones like Ashfire Region) containing **Maps** (tile-based 2D environments).
- Maps declare their region membership via a `region` tag; regions don't own their maps.
- Any map can warp to any other map (even from a different author), enabling a truly open, interconnected world.

### Nostrmon
- Creatures called **Nostrmon** are defined as Nostr events (kind 38267) with stats, types, moves, and sprites.
- Wild Nostrmon appear in encounter zones on maps. Players battle and catch them.
- Nostrmon have stats (HP, ATK, DEF, SPATK, SPDEF, SPD), individual values (IVs), effort values (EVs), natures, and a move pool.

### Battles
- **Wild battles**: triggered by walking on encounter tiles. Fight, use items, switch, flee, or catch.
- **Trainer battles**: initiated by talking to NPC trainers. No catching, no fleeing.
- **Auto-catch**: wild Nostrmon at level 1–5 are always caught automatically — ensures new players always get a starter.
- Standard Pokémon-style stat/damage formula.

### AI NPCs
- NPCs can be either **simple** (scripted dialogue) or **AI-driven** (powered by a configurable language model).
- AI NPCs receive a system prompt containing their personality, knowledge, and full world context (map name, region, nearby zones, warps).
- Players can configure any OpenAI-compatible API provider (including Shakespeare AI, OpenAI, or self-hosted models).

### Multiplayer Presence
- On multiplayer-enabled maps, players broadcast their position via ephemeral kind 20001 events every ~5 seconds.
- Other players appear as coloured dots or avatars on the map in real time.
- Position data is ephemeral — never stored permanently.

### Game Saves
- Saves are kind 35253 addressable events, **encrypted with NIP-44** to the player's own pubkey.
- Saved both locally (localStorage) and to Nostr relays.
- Saves track: team, PC box, inventory, world flags, defeated trainers, play time, badges, position.

---

## Nostr Event Kinds (Protocol)

The Nostrmon Protocol is organized into 11 numbered specification documents (NMDs). All events are Nostr events signed by their authors.

| Kind  | NMD       | Name        | Description                                          |
|-------|-----------|-------------|------------------------------------------------------|
| 30597 | NMD-02    | Region      | Named area containing maps (maps reference region)   |
| 30259 | NMD-03    | Map         | 2D tile-based environment with interactive layer     |
| 38267 | NMD-04    | Nostrmon    | Creature species (stats, types, moves, sprite)       |
| 31647 | NMD-05    | Move        | Battle move (power, type, category, effects, PP)     |
| 36011 | NMD-06    | NPC         | Simple or AI-driven character                        |
| 39951 | NMD-07    | Item        | Consumable, hold, key, TM, ball, or badge item       |
| 35253 | NMD-08    | Game Save   | NIP-44 encrypted player progress                     |
| 20001 | NMD-10    | Presence    | Ephemeral: player position on multiplayer maps       |

Full protocol specifications: https://nostrmon-world.shakespeare.wtf/nip

---

## Application Routes

| Path | Description |
|------|-------------|
| `/` | Title screen (Continue, New Game, Create, Explore, Settings) |
| `/play` | Region selection and game start |
| `/play/map/:naddr` | Play a specific map by naddr |
| `/play/region/:naddr` | Play a region (shows region map, switches between maps) |
| `/create` | Create content (region, map, Nostrmon, NPC, item) |
| `/explore` | Browse all published content from all authors |
| `/settings` | AI provider, game options, account, about |
| `/editor/region` | Region editor |
| `/editor/map` | Map editor (5 layers: terrain, interactive, heightmap, encounters, named zones) |
| `/editor/nostrmon` | Nostrmon species editor |
| `/editor/move` | Move editor (power, type, category, effects) |
| `/editor/npc` | NPC editor (simple and AI) |
| `/editor/item` | Item editor |
| `/nip` | Protocol specification (NMD-01 through NMD-11) |
| `/changelog` | Version history and release notes |
| `/llms.txt` | This file |

---

## Technology Stack

- **React 19** with TypeScript — UI framework
- **TailwindCSS 3** — Styling
- **Vite** — Build tool
- **shadcn/ui** — Accessible UI components (Radix UI + Tailwind)
- **Nostrify** — Nostr protocol framework for the browser
- **nostr-tools** — NIP-19 encoding/decoding, key utilities
- **TanStack Query** — Data fetching and caching
- **React Router** — Client-side routing
- **localStorage** — Local save persistence and settings

---

## Source Code Structure

```
src/
  pages/
    TitleScreen.tsx        — Main menu
    Index.tsx              — Content browser / hub page
    PlayScreen.tsx         — Region/game selection
    GameView.tsx           — Core game engine (MapPlayer component, camera, movement, battles)
    ExplorePage.tsx        — Explore all published content
    CreatePage.tsx         — Content creation hub
    SettingsPage.tsx       — Settings (AI, game, account)
    ChangelogPage.tsx      — Version history
    NipPage.tsx            — Protocol spec viewer (redirects to ProtocolPage)
    ProtocolPage.tsx       — Protocol spec viewer with NMD sidebar navigation
    editors/
      RegionEditor.tsx     — Create/edit regions
      MapEditor.tsx        — Create/edit maps (5-layer editor)
      NostrmonEditor.tsx   — Create/edit Nostrmon species
      MoveEditor.tsx       — Create/edit battle moves (kind 31647)
      NPCEditor.tsx        — Create/edit NPCs
      ItemEditor.tsx       — Create/edit items
  components/
    game/
      BattleScreen.tsx     — Battle UI (wild and trainer)
      GameMenu.tsx         — In-game menu (team, bag, save)
      AiNpcDialogue.tsx    — AI NPC chat interface
      MultiplayerPresence.tsx — Real-time player positions
      DebugMenu.tsx        — Developer debug overlay
    auth/                  — Login/logout, account switcher
    ui/                    — shadcn/ui component library
  hooks/
    useNostrmon.ts         — Query hooks for all game content kinds
    useGameSave.ts         — Save/load game state
    useGamepadNav.ts       — Gamepad controller support
  lib/
    version.ts             — Current version number (APP_VERSION)
    moves.ts               — Move type definitions and parsing (NMD-05)
NIP.md                     — Protocol overview (references individual NMDs)
protocol/                  — Full protocol specification documents
  NMD-01-overview.md       — Overview & Architecture
  NMD-02-regions.md        — Regions (kind 30597)
  NMD-03-maps.md           — Maps (kind 30259)
  NMD-04-creatures.md      — Nostrmon Creatures (kind 38267)
  NMD-05-moves.md          — Moves (kind 31647)
  NMD-06-npcs.md           — NPCs (kind 36011)
  NMD-07-items.md          — Items (kind 39951)
  NMD-08-saves.md          — Game Saves (kind 35253)
  NMD-09-battles.md        — Battles & Combat
  NMD-10-presence.md       — Multiplayer Presence (kind 20001)
  NMD-11-scripting.md      — Script System
public/
  llms.txt                 — This file
```

---

## Key Design Decisions

1. **No central server** — All content is Nostr events. The app is purely client-side.
2. **Anyone can create** — No whitelisting. Any Nostr user can publish regions, maps, creatures.
3. **Cross-author warps** — A map by one author can warp to a map by another author, building a shared world.
4. **Encrypted saves** — NIP-44 encryption means only the player can read their own save data.
5. **AI NPCs are optional** — Players configure their own AI provider. No AI calls are made without user consent and their own API key.
6. **Tile map format** — Maps use a simple `number[][]` terrain grid, making them compact and relay-friendly.
7. **Discovery via `#t: nostrmon`** — All game content uses this tag, enabling relay-level filtering.

---

## For AI Assistants Working on This Codebase

- The primary game engine is `src/pages/GameView.tsx` (~1900 lines). Read it carefully before modifying.
- The `MapPlayer` component (inside GameView.tsx) handles: rendering, movement, camera, encounters, warps, NPCs, battles.
- Camera uses a fixed-speed linear approach (pixels/ms = TILE_PX / MOVE_STEP_MS) to match the character CSS transition exactly.
- Character movement uses CSS `transition: left 195ms linear, top 195ms linear` on the player div.
- The input loop runs in a single `requestAnimationFrame` loop that never restarts (all state accessed via refs).
- `src/hooks/useNostrmon.ts` contains all Nostr query hooks for game content.
- `src/hooks/useGameSave.ts` handles the NIP-44 encrypted save system.
- `NIP.md` and the `protocol/` directory are the authoritative protocol specifications — always consult them for event schemas.
- Always update `src/lib/version.ts`, `src/pages/ChangelogPage.tsx`, and this file (`public/llms.txt`) when making changes.

---

*Generated for https://llmstxt.org — provides structured context for AI language models.*