Pigeon Trash

Production-ready persistent dumpster inventory system for FiveM using ox_inventory, featuring precise stash persistence, automatic database migrations, security hardening, and production-grade repository architecture.
Built for scalable FiveM server infrastructure, long-term persistence stability, and professional development workflows.

---

⚠️ This repository is actively maintained and production deployed.

---

🔍 Repository Information

Field	Value
Repository Name	pigeon-trash
Language	Lua
Framework Support	Standalone / ox
Category	Persistent Storage System
Game	FiveM
Inventory System	ox_inventory
Target System	ox_target
Database	oxmysql
Architecture	Persistent Dynamic Stashes
Persistence Model	Coordinate-Based
Original Author / Studio	Pigeon Studios
Status	Production Stable

---

🧩 Overview

Pigeon Trash is a production-ready persistent dumpster inventory system for FiveM servers using ox_inventory.

The resource dynamically creates and persists dumpster inventories using precise world coordinates, allowing dumpster contents to remain permanently stored across server restarts.

Designed specifically for scalable FiveM infrastructure, the system includes:

• automatic database migrations
• collision-safe stash persistence
• anti-spam protection
• secure event validation
• lazy stash recovery
• production-grade migration handling
• self-healing legacy stash repair
• centralized constants architecture
• configurable dumpster types
• production-safe logging systems

The resource is built around long-term persistence stability and maintainable production architecture rather than temporary gameplay-only storage.

---

⚡ Quick Start

git clone https://github.com/WelshPigeon/pigeon-trash

Move the resource into your server resources folder:

resources/[standalone]/pigeon-trash

Ensure dependencies are started:

ensure ox_lib
ensure oxmysql
ensure ox_inventory
ensure ox_target

ensure pigeon-trash

---

🚀 Core Features

Persistent Inventory System

Feature	Included
Persistent Dumpster Inventories	✅
Dynamic Stash Registration	✅
Precise Coordinate Persistence	✅
Restart-Safe Storage	✅
Lazy Stash Recovery	✅
Configurable Dumpster Types	✅

---

Database & Persistence

Feature	Included
Automatic Database Migrations	✅
MariaDB Compatibility	✅
MySQL Compatibility	✅
Self-Healing Duplicate Repair	✅
Unique Coordinate Validation	✅
Unique Stash Validation	✅

---

Security Features

Feature	Included
Anti-Event Spam Protection	✅
Cooldown Validation	✅
Dumpster Model Validation	✅
Payload Validation	✅
Distance Validation	✅
Suspicious Activity Logging	✅

---

Production Features

Feature	Included
Centralized Constants Architecture	✅
Version Checker Integration	✅
Resource Cleanup Handling	✅
Configurable Logging	✅
Config-Driven Architecture	✅
Production Repository Workflow	✅

---

🔄 System Flow

Player Interaction
        ↓
ox_target Interaction
        ↓
Server Validation
        ↓
Dumpster Persistence Lookup
        ↓
ox_inventory Stash Registration
        ↓
Persistent Dumpster Inventory

---

📁 Repository Structure

Path	Description
.github/ISSUE_TEMPLATE/	GitHub issue templates
.github/workflows/	GitHub Actions CI workflows
.github/CODEOWNERS	Repository ownership configuration
.github/pull_request_template.md	Pull request template
client/	Client-side interaction handling
server/	Server-side persistence and validation
shared/	Shared constants and configuration
examples/	Example setup documentation
web/img/	Repository branding and social preview assets
fxmanifest.lua	FiveM resource manifest
README.md	Primary repository documentation
CONTRIBUTING.md	Contribution guidelines and workflow standards
CHANGELOG.md	Repository version and release tracking
LICENSE	Plain-text GitHub-recognised proprietary license
LICENSE.md	Fully formatted enterprise license agreement
version	Remote version checker version file
changelog.txt	Remote version checker changelog

---

⚙️ Dependencies

Required

• ox_inventory
• ox_target
• oxmysql
• ox_lib

---

📦 Versioning

This repository follows semantic versioning.

Version Type	Description
Major	Breaking changes
Minor	New features and functionality
Patch	Fixes, optimisations, and improvements

---

⚙️ Installation

1) Download Repository

Clone or download the repository:

git clone https://github.com/WelshPigeon/pigeon-trash

---

2) Move Resource

Move into:

resources/[standalone]/pigeon-trash

---

3) Ensure Dependencies

Required:

ensure ox_lib
ensure oxmysql
ensure ox_inventory
ensure ox_target

---

4) Start Resource

ensure pigeon-trash

---

5) Restart Server

The resource will automatically:

• create database tables
• apply migrations
• repair legacy stash collisions
• register persistent dumpsters

No manual SQL import is required.

---

⚙️ Configuration

Main configuration file:

shared/config.lua

---

Dumpster Types

Example:

Config.DumpsterTypes = {

    default = {
        label = 'Dumpster',
        slots = 60,
        maxWeight = 200000
    },

    large = {
        label = 'Industrial Dumpster',
        slots = 100,
        maxWeight = 400000
    }
}

---

Security Configuration

Example:

Config.Security = {
    cooldown = 1.0,
    validateDumpsterModels = true,
    blockInvalidPayloads = true
}

---

Logging Configuration

Example:

Config.Logging = {
    enabled = true,
    webhook = ''
}

---

🛡 Security Notes

Pigeon Trash includes production-grade security validation systems:

• server-side payload validation
• dumpster model validation
• coordinate normalization
• anti-spam cooldown protection
• suspicious activity logging
• stash integrity validation

---

🚦 Production Recommendations

Recommended configuration:

Config.Debug = false

Recommended infrastructure:

• protected GitHub branches
• staging validation workflow
• production release tagging
• separate development branch
• secure webhook management
• CI validation enabled

---

🛠 Troubleshooting

Dumpster Does Not Open

Check:

• ox_inventory is running
• ox_target is running
• ox_lib is running
• dumpster model exists in config

---

Stashes Not Persisting

Check:

• oxmysql is running
• database permissions are correct
• migrations completed successfully
• no SQL errors occurred during startup

---

Duplicate Stash Errors

The migration system now automatically repairs legacy duplicate stash identifiers during startup.

Restart the resource after updating.

---

🧪 Migration System

The migration system automatically handles:

• table creation
• schema upgrades
• duplicate stash repair
• unique index validation
• legacy persistence recovery

No manual migration execution is required.

---

🆘 Support

For deployment issues, bug reports, or infrastructure assistance:

• Open a GitHub Issue
• Submit a Feature Request
• Review the troubleshooting section
• Contact Pigeon Studios

---

📄 Licensing & Usage

Copyright © Pigeon Studios

This repository and all associated source code remain the exclusive property of Pigeon Studios.

Redistribution, resale, sublicensing, relicensing, public mirroring, or unauthorised commercial usage without explicit written permission from Pigeon Studios is strictly prohibited.

Licensed deployments are restricted to authorised environments only.

Refer to the LICENSE file for full proprietary licensing terms.

---

🤝 Credits

Developed by Pigeon Studios

Built for scalable FiveM infrastructure, production-grade persistence systems, and long-term server stability.