Tekstowa gra RPG na Discordzie napisana w TypeScript. Walka rundowa, ekspedycje, bossowie, dungeony, party, crafting, NPC z dialogami i sklepy w prywatnych wątkach. Slash commands z autocomplete + klasyczne komendy .message-style.

# 1. Klonuj i zainstaluj zależności
git clone <repo> && cd discord-bot
bun install   # lub npm install

# 2. Konfiguracja
cp .env.example .env   # uzupełnij DISCORD_TOKEN itd.

# 3. Uruchom
bun start              # bun (zalecane)
npm run start:node     # node (z dist/)
npm run dev            # watch mode

DISCORD_TOKEN=<bot_token>
DISCORD_GUILD_ID=<server_id>     # opcjonalnie — instant slash registration; bez tego: globalnie (~1h propagacji)
OLLAMA_MODEL=qwen2.5:7b           # model dla .ask (jeśli używasz Ollama)
TMDB_API_KEY=<key>                # opcjonalnie — dla .ask-movie / movie-of-the-day
THREAD_TTL_MIN=60                 # auto-cleanup nieaktywnych wątków
AMBUSH_CHECK_INTERVAL_MS=300000   # 5 min — częstotliwość losowania ambush
AMBUSH_CHANCE=0.25                # 25% szansy na ambush per check

Bot wymaga scope bot ORAZ applications.commands żeby slash commands działały. W Discord Developer Portal → twoja aplikacja → OAuth2 → URL Generator:

• Scopes: bot + applications.commands
• Bot Permissions: Send Messages, Manage Threads, Read Message History, Use Application Commands, Add Reactions

Wszystkie komendy działają w obu wariantach: /slash (ephemeral, tylko widoczne dla wywołującego, z autocomplete) i .message (publiczne).

• Akcje per runda: Atak / Obrona / Skill / Item — wybierane via ephemeral panel po kliknięciu "🎮 Otwórz panel"
• Stats efektywne: baza crit 15% + AGI×0.5 + atrybut crit + ekwipunek (weapon/armor/tool — wszystkie wliczają do dmg/def/HP/crit)
• Mikstury: tylko z plecaka (gracze); AI/bossy mają własne pule
• Dodge 15%, block 75% (przy obronie), crit ×2 dmg
• Skille klas z cooldownami, buffy/debuffy (DoT, HoT, shield, taunt, paraliż)

• Battle threads (boss/duel/dungeon/ambush) — publiczne, podsumowanie idzie na parent channel, archiwizacja + delete za 120s
• Shop / inventory threads — prywatne, ✖ Zamknij usuwa od razu
• Idle timeout 5 min dla shop/inventory

• 4 regiony × 5 tierów = 15 ekspedycji
• Region wymaga combat lvl: R1=1, R2=8, R3=16, R4=24
• Ekspedycja T2+ wymaga (tier-1)*8 combat lvl
• Ambush co 5 min z 25% szansą — moby tier-aware do combat lvl gracza

• Stateless graf dialogowy (startNodeId + nodes: Record<id, node>)
• Każdy NPC ma dialog: Dialog z opcjami {label, goto} ('end' kończy)
• Pliki w src/modules/game/npcs/{cityId}/{npc}.npc.ts

src/
├── commands/                  Komendy chat (Ollama-based: ask, movie, etc.)
├── managers/                  CommandManager (dispatch, slash registration)
├── modules/game/
│   ├── cities/                Miasta + handlarze (Port Cikada, Oakhaven, Krasnoludzka Twierdza, Czarna Cytadela)
│   ├── classes/               Klasy + subklasy (tier-1 i tier-2)
│   ├── races/                 Rasy
│   ├── mobs/                  Boss-moby (8) + ambush-moby (10) z tier-multiplier
│   ├── npcs/                  NPC z dialogami (grouped per cityId)
│   ├── skills/                Skille klas (35+) z apply/cooldown
│   ├── engine/                Combat-battle, AI, buffy, ambush loop
│   ├── ui/                    Builder buttonów (battle, shop, menu, expedition, craft, boss, city, dialog)
│   ├── services/              Stan + logika: stats, party, expedition, boss, dungeon, duel, city, craft, inventory, dialog, menu
│   ├── commands/              Cienkie access-pointy (parsują args, delegują do services)
│   └── index.ts               registerGameCommands — DI wiring
├── types/                     ICommand + ISlashCommand interfejsy
├── ollama.ts                  Streaming Ollama API
├── tools.ts                   Function-calling tools (TMDB, etc.)
└── index.ts                   Bot bootstrap, slash registration on ready

Konwencje (utrwalone w pamięci między sesjami):

• Komendy = cienkie access-pointy — logika w *.service.ts, komendy tylko parsują args
• No as casts — proper typing / type guards / generics zamiast
• Effective stats SoT — PlayerStatsService.effective*() jako single source of truth dla UI i buildPlayerCombatant

npm run typecheck     # tsc --noEmit
npm run lint          # ESLint
npm run lint:fix      # auto-fix
npm test              # Jest (260+ testów)
npm run format        # Prettier
npm run build         # tsc → dist/

Tests: unit (test/unit/) i feature (test/feature/) — kombinują real PlayerStatsService z fake interaction objects, sprawdzają cały flow buttonów i slash commands.

• Runtime: Bun (preferred) lub Node 18+
• Discord: discord.js 14 (slash commands, buttons, threads, autocomplete)
• AI chat: Ollama (qwen2.5:7b default) — opcjonalne dla .ask
• TS: TypeScript 6, strict mode, ESM-only
• Test: Jest + ts-jest
• Lint: ESLint 9 + typescript-eslint, Prettier

Tagi semver per release. Aktualnie v1.7.0 (sell items from inventory). Pełna historia w git log.