OCS RPG Discord Bot

An Epic RPG-inspired Discord bot built with TypeScript and discord.js. Players grow a character through hunting, gathering, dungeons, bosses, farming, pet taming, gacha boxes, crafting, and a full economy — all inside Discord slash commands.

Features

• Combat — hunt mobs, fight area bosses, run multi-floor dungeons with persistent sessions
• Skilling — mining, woodcutting, fishing, herbalism, crafting, cooking, alchemy
• Gathering — collect resources tied to your skill levels
• Farming — plant crops on unlockable plots; harvest for food, materials, and gold
• Pets — tame animals from the wild; level and feed them for passive stat bonuses
• Gacha — open Common, Uncommon, Rare, and Legendary boxes for gear and items
• Inventory & Equipment — 5 equipment slots (weapon, armor, helmet, boots, accessory) plus full item management
• Shop — buy gear and consumables; sell loot and crafted items
• Profile — level, class, stats, equipment, HP, gold, and gems on one embed
• Leaderboards — level, gold, boss kills, dungeon completions
• Cooldown system — every action has a cooldown tracked in Redis, just like Epic RPG

Tech Stack

Project Structure

src/
  commands/
    common/       # Utility commands (hello, help)
    rpg/          # All RPG slash commands
  events/
    main/         # Discord gateway events
  services/       # Business logic (no Discord imports)
  database/       # Prisma and Redis singletons
  structs/        # ExtendedClient, Command, Event types
  utils/          # Embeds, formatters, constants
prisma/
  schema.prisma   # Database schema
docs/
  ARCHITECTURE.md
  DATABASE_SCHEMA.md
  GAME_DESIGN.md
  RULES.md

See docs/ARCHITECTURE.md for the full project layout and request lifecycle.

Getting Started

Prerequisites

• Node.js 18+
• PostgreSQL database
• Redis instance
• Discord bot token and application

Installation

git clone https://github.com/Pscodium/ocs-rpg-discord.git
cd ocs-rpg-discord
npm install

Environment Variables

Create a .env file at the project root:

BOT_TOKEN=your_discord_bot_token
CLIENT_ID=your_discord_application_client_id
DATABASE_URL=postgresql://user:password@localhost:5432/ocs_rpg
REDIS_URL=redis://localhost:6379

Database Setup

npx prisma migrate dev --name init
npx prisma generate

Running

npm run dev       # Development mode (nodemon + ts-node)
npm run build     # Compile TypeScript to dist/
node dist/index   # Run compiled build

Produção — EasyPanel (VPS)

Este guia cobre o deploy completo do zero: criar o bot no Discord, configurar a VPS e rodar os seeds.

1. Criar o Bot no Discord

1. Acesse discord.com/developers/applications → New Application
2. Vá em Bot → Reset Token → copie o BOT_TOKEN
3. Em OAuth2 → General copie o CLIENT_ID
4. Em Bot habilite os Privileged Intents: Server Members Intent e Message Content Intent
5. Para convidar o bot ao servidor: https://discord.com/oauth2/authorize?client_id=SEU_CLIENT_ID&scope=bot+applications.commands&permissions=277025392640

2. Registrar os Slash Commands

Antes de subir para produção, rode localmente uma vez para registrar os comandos na API do Discord:

# Configure o .env local com BOT_TOKEN e CLIENT_ID reais
cp .env.example .env
# edite o .env com seus valores

npm install
npx ts-node src/index.ts
# aguarde "✅ Slash commands registrados" no log e encerre com Ctrl+C

Os slash commands ficam persistidos na API do Discord — só precisa rodar de novo se adicionar novos comandos.

3. EasyPanel — Criar os Serviços de Infraestrutura

No painel do EasyPanel na sua VPS:

PostgreSQL

1. + New Service → PostgreSQL
2. Nome: rpg-postgres
3. Anote os valores gerados: usuário, senha, database e hostname interno (ex: rpg-postgres:5432)
4. Monte o DATABASE_URL no formato:

Redis

1. + New Service → Redis
2. Nome: rpg-redis
3. Hostname interno será rpg-redis:6379
4. Monte o REDIS_URL:

4. EasyPanel — Criar o App do Bot

1. + New Service → App
2. Nome: ocs-rpg-discord
3. Em Source: aponte para o repositório GitHub (ou suba a imagem manualmente — veja abaixo)
4. Em Build: selecione Dockerfile — o EasyPanel detecta o Dockerfile na raiz automaticamente
5. Em Environment Variables, adicione:
6. Não precisa expor nenhuma porta — o bot só faz conexões de saída para a API do Discord.

5. Primeiro Deploy — Rodar as Migrations e Seeds

O container roda prisma migrate deploy automaticamente a cada start (via docker-entrypoint.sh), então as migrations são aplicadas sozinhas.

Os seeds (mobs, itens, masmorras, quests, loja etc.) precisam ser rodados uma única vez após o primeiro deploy.

No EasyPanel, abra o Terminal do container e rode:

node dist/prisma/seed.js

O seed é compilado junto com o projeto durante o build. Não use prisma db seed nem npm run seed em produção — o ts-node não está disponível no container.

6. Atualizações (Redeploy)

A cada push para a branch principal:

1. EasyPanel rebuilda a imagem automaticamente (se integração com GitHub estiver ativa)
2. docker-entrypoint.sh roda prisma migrate deploy antes de iniciar — novas migrations são aplicadas automaticamente
3. Seeds não precisam ser rerodados — eles usam upsert e são idempotentes

Para forçar redeploy manualmente no EasyPanel: Deploy → Redeploy.

7. Build e Push Manual (sem integração GitHub)

Se preferir buildar localmente e enviar a imagem:

# Build
docker build -t ghcr.io/seu-usuario/ocs-rpg-discord:latest .

# Login no registry (GitHub Container Registry como exemplo)
echo $GITHUB_TOKEN | docker login ghcr.io -u seu-usuario --password-stdin

# Push
docker push ghcr.io/seu-usuario/ocs-rpg-discord:latest

No EasyPanel, aponte o app para a imagem ghcr.io/seu-usuario/ocs-rpg-discord:latest.

8. Verificar se está Rodando

# Logs em tempo real via EasyPanel → Logs, ou via SSH:
docker logs -f <nome-do-container>

Saída esperada na inicialização:

[entrypoint] Running database migrations...
Environment variables loaded.
...
✅ Slash commands registrados
🤖 Bot online como NomeDoBot#1234

Se aparecer [entrypoint] Running database migrations... e travar por mais de 30 segundos, verifique se o DATABASE_URL está correto e se o container do PostgreSQL está no mesmo projeto EasyPanel (rede interna).

Desenvolvimento Local

Pré-requisitos

• Node.js 18+
• Docker (para PostgreSQL e Redis locais)

Setup

git clone https://github.com/Pscodium/ocs-rpg-discord.git
cd ocs-rpg-discord
npm install
cp .env.example .env
# edite .env com suas credenciais

Subir banco e Redis localmente

docker-compose up -d        # sobe PostgreSQL + Redis em background

Migrations e Seeds

npx prisma migrate dev      # aplica migrations + gera o client
npx prisma db seed          # popula mobs, itens, quests, loja etc.

Rode npx prisma db seed toda vez que adicionar dados novos ao prisma/seed.ts.

Rodar

npm run dev                 # nodemon — reinicia ao salvar

Outros Comandos Úteis

npm run build               # compila TypeScript → dist/
npx prisma studio           # interface web para o banco de dados
npx prisma migrate reset --force && npx prisma db seed   # resetar banco e reseedar

Documentação

Adding a Command

1. Create src/commands/rpg/mycommand.ts using the Command class
2. Check cooldown → call a service → build an embed → reply
3. Auto-loaded on startup — no registration needed

See CLAUDE.md for full development guidelines and coding conventions.

License

ISC