OV Bot

A mafia-themed RPG Discord bot — commit crimes, steal and collect vehicles, race and attack other players, and climb the leaderboards to become the richest.

Live site: https://ovbot.up.railway.app

---

✨ Features

• Mafia RPG loop: heists, jobs, cooldowns, energy/health systems, prison/escape
• Economy & items: cash, inventory, crates/cases, crafting & upgrades
• Vehicles & racing: collect cars, tune stats, race others, seasonal ladders
• PvP actions: duel, ambush, protection/insurance mechanics
• Leaderboards & stats: global rankings and detailed player profiles
• Moderation helpers: opt-in utilities for admins (rate limits, cleanups)
• Slash commands & cogs: modular command organization for maintainability

This README is aligned with the current repo structure (e.g., cogs/, main.py, functions.py, slash.py, etc.). Update section names as you evolve the codebase.

---

📦 Tech Stack

• Language: Python (Discord bot)
• Discord API: discord.py (or compatible library; confirm in your requirements)
• Structure: Cog-based modular commands
• Hosting: Works locally; easy to deploy on Railway/Render/Docker

---

🗂️ Project Layout

discord-ov-bot/
├─ cogs/ # Command groups (economy, crime, racing, admin, etc.)
├─ main.py # Bot entrypoint
├─ functions.py # Shared helpers/utilities
├─ slash.py # Slash-command registration/helpers
├─ auto_approve.py # Utility / automation script (internal)
├─ simulator.py # Game/race simulations / testing
├─ lists.py # Constants / item & car lists
├─ hangman.py # Mini-game (example)
├─ codes.py # Promo codes / redemption utilities
└─ README.md

---

🚀 Quick Start

1) Prerequisites

• Python 3.10+
• A Discord application & bot token (create at https://discord.com/developers)
• (Optional) A PostgreSQL/SQLite/MongoDB instance if you use persistence

2) Clone

git clone https://github.com/caffe-ian/discord-ov-bot.git
cd discord-ov-bot

3) Create a virtual environment & install deps

python -m venv .venv
# Windows
. .venv/Scripts/activate
# macOS/Linux
source .venv/bin/activate

pip install -r requirements.txt
# If you don't have a requirements.txt yet, install your libs directly, e.g.:
# pip install discord.py python-dotenv

4) Configure environment

Create a .env (or use environment variables in your host):

DISCORD_TOKEN=your-bot-token
# Optional (example keys — include only what you actually use)
DATABASE_URL=...
OWNER_ID=...
GUILD_ID=...          # for guild-only slash command testing

5) Run the bot

python main.py

If slash commands don’t appear immediately, it can take a minute to propagate. During development, registering to a single test guild (GUILD_ID) is faster.

---

🧭 Commands (Examples)

Adjust names to match your actual cogs/commands.

• /profile – View your stats
• /theft – Attempt a vehicle theft (cooldown applies)
• /work – Legit job for safe income
• /storage – View / use items
• /drive <Car ID> – Drive a car
• /race @user - Head-to-head race
• /leaderboard – Global richest/top racers
• /daily – Claim daily reward

---

⚙️ Configuration Tips

• Intents: Ensure MESSAGE_CONTENT and relevant gateway intents are enabled in your bot settings and in code.
• Slash commands: Consider a dedicated slash.py (already present) to register/update app commands on startup.
• Cooldowns & balance: Keep timers and payouts in a single module (easier to tune without breaking the economy).
• Data: If you start simple, a local file/SQLite works; move to PostgreSQL/MongoDB for production.

---

🧪 Development

• Use a test guild to register slash commands for instant updates.
• Add new features as cogs under cogs/ and load them dynamically in main.py.
• Include type hints and docstrings for maintainability.
• Consider black/ruff/mypy for formatting, linting, and static checks.

---

🐳 Docker (Optional)

# Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY . /app
RUN pip install -r requirements.txt
ENV PYTHONUNBUFFERED=1
CMD ["python", "main.py"]

Build & run:

docker build -t ov-bot .
docker run --env-file .env ov-bot

---

☁️ Deploying to Railway (Optional)

• Create a new Railway project, connect this repo, set DISCORD_TOKEN (and other vars) in Variables.
• Set your start command to python main.py.
• Redeploy when pushing to main.

Live site reference: https://ovbot.up.railway.app (update this section if you move hosting).

---

📄 License

This project is licensed under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License (CC BY-NC-ND 4.0).

You are free to view and share this repository for personal or educational purposes, but commercial use, redistribution, modification, or plagiarism without prior written consent from @caffe-ian is strictly prohibited.

For full license terms, visit: https://creativecommons.org/licenses/by-nc-nd/4.0/

---

🙌 Credits

Built by @caffe-ian alone as a personal project at the age of 15.

Community ideas from early players & testers.

Code may not be very beautiful but it was my first ever project that got me into programming.