SWS Report

Standalone report system for FiveM with live chat, admin tools, and Discord integration.

---

Preview

Admin View	Player View

More Screenshots

Admin Notes	Player Notes

---

Features

• Player Reports - Create tickets with live chat support
• Voice Messages - Record and send audio messages in chat (optional)
• Admin Panel - Claim, resolve, and manage reports
• Permission Groups (RBAC) - Granular permissions with inheritance (optional)
• Moderation Tools - Teleport, heal, freeze, spectate, kick, screenshot
• Discord Integration - Webhook logging for all events
• Statistics Dashboard - Track team performance
• Inventory Management - View/modify player items (ox_inventory, ESX)
• Multi-Language - English & German included
• Dark/Light Theme - User preference saved

---

Requirements

• FiveM Server
• oxmysql
• Node.js 20+
• screenshot-basic or screencapture (optional, for screenshot features)

---

Quick Start

# 1. Clone to resources
git clone https://github.com/SwisserDev/sws-report.git resources/sws-report

# 2. Import database
mysql -u root -p your_database < resources/sws-report/sql/install.sql

# 3. Build UI
cd resources/sws-report/web && npm install && npm run build

# 4. Add to server.cfg
ensure oxmysql
ensure sws-report

# 5. (Optional) Enable voice messages
mysql -u root -p your_database < resources/sws-report/sql/migrate_voice_messages.sql

# 6. (Optional) Enable inventory management
mysql -u root -p your_database < resources/sws-report/sql/migration_1.0.6_inventory_changes.sql

# 7. (Optional) Enable sound notifications
# Place notification.ogg and message.ogg in web/public/sounds/
# Then rebuild: cd web && npm run build

Upgrading from an older version? See UPGRADING.md

---

Configuration

Edit config/main.lua:

Config.Locale = "en"              -- Language (en/de)
Config.Command = "report"         -- Command to open UI
Config.Cooldown = 60              -- Seconds between reports
Config.MaxActiveReports = 3       -- Max open reports per player

-- Admin access (choose one or both)
Config.AdminAcePermission = "report.admin"
Config.AdminIdentifiers = {
    "license:abc123...",
    "steam:123456..."
}

-- Discord webhook
Config.Discord = {
    enabled = true,
    webhook = "https://discord.com/api/webhooks/..."
}

-- Voice Messages (optional, requires migration)
Config.VoiceMessages = {
    enabled = true,
    maxDurationSeconds = 60,
    maxFileSizeKB = 7500
}

-- Inventory Management (optional, requires migration)
Config.Inventory = {
    enabled = true,
    allowedActions = { add = true, remove = true, set = true, metadata_edit = true },
    maxItemCount = 1000
}

-- Sound Notifications (optional)
Config.Sounds = {
    enabled = true,
    newReport = "notification.ogg",
    newMessage = "message.ogg",
    volume = 0.5
}

-- Screenshot Settings (optional, requires screenshot-basic or screencapture)
Config.Screenshot = {
    provider = "screenshot-basic",  -- "screenshot-basic" or "screencapture"
    encoding = "jpg",               -- "jpg" | "png" | "webp" (webp only with screencapture)
    quality = 0.85,                 -- 0.0-1.0 (screenshot-basic only)
    autoOnCreate = false            -- Auto-screenshot when player creates report
}

-- Permission Groups (optional, omit for legacy full-access behavior)
Config.Permissions = {
    groups = {
        moderator = {
            label = "Moderator",
            permissions = {
                "view_reports", "claim_report", "resolve_report", "set_priority",
                "send_admin_message", "view_notes", "manage_notes",
                "teleport_to", "bring_player", "heal_player", "revive_player",
                "spectate_player", "screenshot_player", "view_player_history",
            }
        },
        admin = {
            label = "Admin",
            inherits = "moderator",  -- inherits all moderator permissions
            permissions = {
                "delete_report", "freeze_player", "ragdoll_player", "kick_player",
                "manage_inventory", "view_statistics",
            }
        },
        superadmin = {
            label = "Super Admin",
            inherits = "admin",
            permissions = {}
        }
    },
    aceGroups = {
        ["report.moderator"]  = "moderator",
        ["report.admin"]      = "admin",
        ["report.superadmin"] = "superadmin",
    },
    identifierGroups = {
        -- ["license:xxx"] = "admin",
    }
}

---

Commands & Exports

Commands

Command	Description
/report	Open report interface

Server Exports

exports["sws-report"]:IsAdmin(source)
exports["sws-report"]:HasPermission(source, permission)
exports["sws-report"]:GetPlayerGroup(source)
exports["sws-report"]:GetReports(filter)
exports["sws-report"]:CloseReport(reportId)
exports["sws-report"]:IsInventoryAvailable()
exports["sws-report"]:GetInventorySystemName()

Client Exports

exports["sws-report"]:OpenUI()
exports["sws-report"]:CloseUI()
exports["sws-report"]:IsUIOpen()

Events

AddEventHandler("sws-report:onCreated", function(report) end)
AddEventHandler("sws-report:onClaimed", function(report, adminId) end)
AddEventHandler("sws-report:onResolved", function(report, adminId) end)

---

Documentation

Document	Description
INVENTORY.md	Inventory management setup, usage & custom adapters
UPGRADING.md	Migration guide for version upgrades

---

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/thing)
3. Commit changes (git commit -m "Add thing")
4. Push to branch (git push origin feature/thing)
5. Open a Pull Request

---

License

MIT

---

_{Built by SwisserDev}

Metrics • Win • Cloud