🏠Routing Bucket System

🏠 Routing Bucket System

NEW FEATURE! Pets now work seamlessly in apartments and houses with full routing bucket support!

📋 Overview

The Routing Bucket System enables pets to function properly inside apartments, houses, and other instanced areas that use FiveM's routing bucket technology. Players can spawn and interact with their pets anywhere, regardless of which bucket they're in.

Perfect for:

• 🏘️ Apartment systems (qb-apartments, qbx_properties)

• 🏡 Housing scripts with instancing

• 🎮 Custom housing systems using buckets

• 🔄 Multi-instance gameplay

---

✨ Key Features

🖥️ Server-Side Spawning

Pets spawned server-side for proper bucket synchronization

🔄 Auto-Sync System

Pets automatically stored/restored on bucket changes

🏠 Full Housing Support

Works with qb-apartments, qbx_properties, ps-housing and more

⚡ Zero Performance Impact

Minimal server overhead (~0.01ms per spawn)

Complete Feature List

• ✅ Server-Side Pet Spawning - Pets spawned on server for bucket compatibility

• ✅ Auto-Store on Bucket Change - Pets automatically stored when changing buckets

• ✅ Apartment/House Support - Full compatibility with housing scripts

• ✅ Seamless Transitions - Smooth pet handling across bucket changes

• ✅ Framework Agnostic - Works with any framework or housing system

• ✅ Backward Compatible - Existing pets work without migration

• ✅ Performance Optimized - Minimal impact on server performance

---

🎮 How It Works

What is a Routing Bucket?

Understanding Routing Buckets

Routing Buckets create isolated "instances" of the game world. Players in different buckets cannot see or interact with each other.

Common Use Cases:

🏠 Apartments

• Each apartment is a separate bucket

• Only people inside see each other

• Prevents interference from outside players

🏡 Houses

• Private instances for property owners

• Isolated from main world

• Multiple houses can exist in same location

🎮 Custom Instances

• Special events or missions

• PvP arenas

• Admin areas

How Buckets Work

Default World (Bucket 0):

All players spawn here by default Main city, streets, public áreas

Apartment Example (Bucket 5):

Player enters apartment → Moved to bucket 5 Only players in bucket 5 can see each other Player exits → Returns to bucket 0

Without routing bucket support: Pets would become invisible or glitched when players enter apartments!

System Flow

Complete System Flow

Step-by-Step Process:

1. Player in Main World (Bucket 0)

Player has pet spawned Pet visible to everyone in bucket 0

1. Player Enters Apartment

Housing script changes bucket (0 → 5) Pet Manager detects bucket change If AutoSyncBucket = true → Pet auto-stored

1. Inside Apartment (Bucket 5)

Player spawns pet normally Pet spawns in bucket 5 (server-side) Pet visible only to players in bucket 5

1. Player Exits Apartment

Housing script returns to bucket 0 Pet Manager detects bucket change Pet auto-stored again

1. Back in Main World

Player can spawn pet normally Pet spawns in bucket 0 Everything works as before

Configuration

System Configuration

You can find this configs inside the file config.lua:

    RoutingBucket = {
        -- ⚠️ IMPORTANT: Does not affect existing clients or saved pets
        -- 📊 PERFORMANCE: TRUE = +0.01ms per active pet | FALSE = No impact
        UseServerSideSpawning = false, -- Default: false (backward compatible)

        -- Automatically stores pet when player enters different dimension-- (e.g., entering apartment, garage, or house)
        -- ⚠️ REQUIREMENT: Only works if UseServerSideSpawning = true
        -- 📊 PERFORMANCE: TRUE = +0.01ms per second | FALSE = No impact
        AutoSyncBucket = true, -- Default: true

        -- How often (in seconds) to check for dimension changes
        -- ⚠️ REQUIREMENT: Only works if AutoSyncBucket = true
        -- 📊 PERFORMANCE: 1 second = ~0.01ms/s | 5 seconds = ~0.002ms/s
        BucketCheckInterval = 1, -- Default: 1 second (recommended)

        Notifications = {
            -- Show notification when pet is auto-stored due to dimension change
            ShowAutoDespawnNotification = true, -- Default: true (recommended)
        },

        -- Logs routing bucket operations to server console
        DebugLogging = true, -- Default: false (recommended for production)
    },

Configuration Options

UseServerSideSpawning

REQUIRED: Must be true for routing bucket support!

Value	Effect
true	✅ Pets spawn server-side, work in all buckets
false	❌ Pets spawn client-side, won't work in apartments

When to use true:

• You have apartment/housing scripts

• You use any system with routing buckets

• You want maximum compatibility

When to use false:

• When you don't use any RoutingBucket System , and need better perfomance

---

AutoSyncBucket

RECOMMENDED: Set to true to prevent pet glitches!

Value	Behavior
true	✅ Pet auto-stored on bucket change (recommended)
false	⚠️ Pet may glitch/become invisible on bucket change

When to use true:

• You want automatic, seamless behavior

• You don't want players to manually store pets

• Best user experience (recommended)

When to use false:

• You want manual control over pet storage

• Custom implementation needed

• Advanced use cases only

---

🔧 Installation

1

Update Resource Files

Replace all files in your cdev_pets folder with the new version.

Backup First: Always backup your current version before updating!

2

Add Configuration

Open config.lua and add the routing bucket section and follow settings bellow:

    RoutingBucket = {
        -- ⚠️ IMPORTANT: Does not affect existing clients or saved pets
        -- 📊 PERFORMANCE: TRUE = +0.01ms per active pet | FALSE = No impact
        UseServerSideSpawning = true, -- Default: false (backward compatible)

        -- Automatically stores pet when player enters different dimension-- (e.g., entering apartment, garage, or house)
        -- ⚠️ REQUIREMENT: Only works if UseServerSideSpawning = true
        -- 📊 PERFORMANCE: TRUE = +0.01ms per second | FALSE = No impact
        AutoSyncBucket = true, -- Default: true

        -- How often (in seconds) to check for dimension changes
        -- ⚠️ REQUIREMENT: Only works if AutoSyncBucket = true
        -- 📊 PERFORMANCE: 1 second = ~0.01ms/s | 5 seconds = ~0.002ms/s
        BucketCheckInterval = 1, -- Default: 1 second (recommended)

        Notifications = {
            -- Show notification when pet is auto-stored due to dimension change
            ShowAutoDespawnNotification = true, -- Default: true (recommended)
        },

        -- Logs routing bucket operations to server console
        DebugLogging = true, -- Default: false (recommended for production)
    },

3

Restart Resource

restart cdev_lib ensure cdev_pets

✅ No database changes needed! System is fully backward compatible.

---

🏘️ Housing Compatibility

Supported Scripts

Housing Script	Status	Notes
vms-housing	✅ Tested	Full compatibility, works out of box
qbx_properties	✅ Tested	Full compatibility, works out of box
ps-housing	✅ Compatible	Should work with default config
Custom Scripts	✅ Compatible	Works with any script using routing buckets

---

📊 Performance

Server Impact

Minimal Impact: System adds negligible overhead to server performance.

Measurements:

Operation	Time	Impact
Pet Spawn (Server-Side)	~0.01ms	Negligible
Bucket Change Detection	~0.001ms	Negligible
Auto-Store Pet	~0.005ms	Negligible

Comparison:

Operation	Server-Side	Client-Side	Difference
Pet Spawn	~0.01ms	~0.001ms	+0.009ms per spawn (insignificant)
Bucket Change Detection	~0.001ms	No additional	+0.001ms per pet spawned in server-side
Auto-Store Pet	~0.005ms	No additional	+0.005ms per pet spawned in server-side

Client Impact

Zero Additional Impact: No extra client-side processing required!

• Same resource usage as before

• No additional rendering cost

• No FPS impact

---

🔍 Troubleshooting

Pet Disappears in Apartment

Problem: Pet disappears when entering apartment

Symptoms:

• Pet visible in main world

• Pet disappears when entering apartment

• No errors in console

Solution:

1. Enable Auto-Sync:

AutoSyncBucket = true, -- Must be true

1. Verify Server-Side Spawning:

UseServerSideSpawning = true, -- Must be true

1. Restart Resources:

/restart cdev_lib
/ensure cdev_pets

1. Test Again:

   • Spawn pet in main world

   • Enter apartment

   • Pet should auto-store (check inventory/menu)

   • Spawn pet inside apartment

Fixed: Pet now auto-stores on bucket change!

Pet Not Visible to Others

Problem: Pet not visible to other players in apartment

Symptoms:

• You see your pet

• Other players don't see your pet

• They're in same apartment

Solution:

1. Check Server-Side Spawning:

UseServerSideSpawning = true, -- MUST be enabled

1. Verify Both Players in Same Bucket:

   • Both should be in same bucket number

2. Check Console for Errors:

   • Look for pet spawn errors

   • Check server console

3. Restart Resources:

/restart cdev_lib
/ensure cdev_pets

Note: This usually means server-side spawning is disabled. Always keep it true!

---

📚 FAQ

Do I need to update my database?

No! The system is fully backward compatible. All existing pets work without any database changes.

Will this break existing pets?

No. All existing pets continue working exactly as before. The new system only adds routing bucket support - it doesn't change how pets work in the main world (bucket 0).

Does this work with ESX/QBCore/custom frameworks?

Yes! The routing bucket system is framework-agnostic. It works with:

• ESX

• QBCore

• QBox

• Custom frameworks

• No framework at all

Can I disable it if I don't use apartments?

Yes, if you are not using any system that requires RoutingBucket, it is recommended that you do not enable the RoutingBucket settings. With this system disabled, your server will have better performance.

If you really want to disable:

RoutingBucket = {
 UseServerSideSpawning = false,
 AutoSyncBucket = false,
},

What happens if a player's internet disconnects in an apartment?

The pet behaves the same as disconnecting anywhere else:

• Pet despawns on disconnect

• Data saved to database

• Pet available when player reconnects

• No data loss

Can admins see pets in all buckets?

No. Admins are subject to the same routing bucket restrictions as regular players. This is a FiveM limitation - entities only render in the same bucket.

To view/manage all pets, use the Pet Manager admin tool (/petmanager).

---