Buckets

Technical reference only.

See the Guides for usage examples and system flow.

Defines and manages routing buckets used for world separation. This module controls spawn points, access rules, and routing settings for different areas.

Each bucket entry supports fine-grained control over access and world behaviour, making it easy to build layered and modular gameplay systems.

Bucket Configuration

buckets.bucket_list = {
    main = {
        label = "Main World",
        bucket = 0,
        mode = "strict", -- https://docs.fivem.net/natives/?_0xA0F2201F
        population_enabled = false, -- https://docs.fivem.net/natives/?_0xCE51AC2C
        player_cap = false, -- false | number: Max players in bucket if number is set
        staff_only = false, -- Example: { "admin", "mod" }
        vip_only = false, -- Example: 2 = VIP level 2 required
        spawn = vector4(-268.47, -956.98, 31.22, 208.54),
        respawn = vector4(341.28, -1396.83, 32.51, 48.78)
    }
}

---

get_bucket

Returns the full config for a given bucket ID.

buckets.get_bucket(id)

Parameters

• id (string): The bucket ID.

Returns

• table|nil: Bucket config if found, nil otherwise.

---

get_bucket_by_label

Returns a bucket config matching a label (case-insensitive).

buckets.get_bucket_by_label(label)

Parameters

• label (string): The label to search.

Returns

• table|nil: Matching config or nil.

---

get_spawn_point

Returns the spawn position for a bucket.

buckets.get_spawn_point(id)

Parameters

• id (string): The bucket ID.

Returns

• vector4|nil: Spawn location or nil.

---

get_respawn_point

Returns the respawn position for a bucket.

buckets.get_respawn_point(id)

Parameters

• id (string): The bucket ID.

Returns

• vector4|nil: Respawn location or nil.

---

is_staff_only

Checks if the bucket is restricted to specific staff roles.

buckets.is_staff_only(id, role)

Parameters

• id (string): The bucket ID.

• role (string): The role to verify.

Returns

• boolean: True if restricted.

---

is_vip_only

Checks if a player’s VIP level is allowed into the bucket.

buckets.is_vip_only(id, vip_level)

Parameters

• id (string): The bucket ID.

• vip_level (number): The player’s VIP level.

Returns

• boolean: True if VIP level is insufficient.

---

apply_routing_settings

Applies entity lockdown and population rules to all buckets.

buckets.apply_routing_settings()

Returns

• void