Zum Inhalt

Bucket System

Bucket System

Routing buckets isolate players and entities into separate instances. The framework keeps an internal registry, tracks which bucket each player is currently in, and automatically handles cleanup on disconnect.

Defaults

  • default bucket (ID 0): NPCs disabled, entity lockdown strict.
  • rpworld bucket (ID 1): NPCs disabled, entity lockdown strict.

These are created on resource start.

API

Core Functions

  • cv.getAllBuckets() -> table of all buckets.
  • cv.createBucket(name, id?, settings?) -> bucket table or error.
  • cv.getBucketById(id) / cv.getBucketByName(name) -> bucket or nil.
  • cv.joinBucket(playerId, bucketId) -> true or false, error.
  • cv.getPlayerBucket(playerId) -> bucket table (falls back to ID 0).
  • cv.moveEntityToPlayerBucket(entity, playerId) -> true or false, error.
  • cv.moveEntityToBucket(entity, bucketId) -> true or false, error.

Bulk Operations

  • cv.joinBucketBulk(playerIds, bucketId) -> true, stats or false, error.
  • Moves multiple players to a bucket at once.
  • Returns { success = count, failed = count }.
  • cv.moveBucketPlayers(fromBucketId, toBucketId) -> true, stats or false, error.
  • Moves all players from one bucket to another.
  • cv.moveBucketEntities(fromBucketId, toBucketId) -> true, stats or false, error.
  • Moves all tracked entities between buckets.

Lifecycle Management

  • cv.destroyBucket(bucketId) -> true or false, error.
  • Safely destroys a bucket (cannot destroy default buckets 0/1).
  • Moves players to rpworld bucket.
  • Deletes all tracked entities.
  • Clears expiration timers.
  • cv.cleanupOrphanedEntities(bucketId) -> true, stats or false, error.
  • Removes invalid entities and entities with no valid owner.

Debug & Telemetry

  • cv.getBucketStats(bucketId) -> stats table or nil.
  • Returns { id, name, players, entities, createdAt, settings }.
  • cv.getAllBucketStats() -> table of stats for all buckets.

Settings

  • disableNpcs (boolean): when true, routing bucket population is disabled.
  • lockEntity (boolean): when true, entity lockdown is strict; otherwise relaxed.
  • expiresIn (number): auto-expire time in seconds. Bucket will be destroyed after this time.

Automatic Cleanup

  • On disconnect: Players are automatically removed from their bucket.
  • On resource stop: All players are moved to default bucket, timers are cleared.
  • On expiration: Temporary buckets auto-destroy after expiresIn seconds.

Logging

  • Uses dprint() for debug logs (requires Config.Debug = true).
  • Uses pprint() for important events (always logged).
  • All player movements, bucket creation/destruction, and errors are logged.

Examples

Temporary Dungeon Instance

-- Create a dungeon that expires in 30 minutes
local dungeon = cv.createBucket("dungeon_party_123", nil, {
    disableNpcs = true,
    lockEntity = true,
    expiresIn = 1800  -- 30 minutes
})

-- Move entire party to dungeon
cv.joinBucketBulk({player1, player2, player3, player4}, dungeon.id)

-- When done early, manually destroy
cv.destroyBucket(dungeon.id)

Move Party Between Instances

-- Move all players from instance A to instance B
cv.moveBucketPlayers(bucketA.id, bucketB.id)

-- Or move specific players
local partyMembers = {src1, src2, src3}
cv.joinBucketBulk(partyMembers, newBucket.id)

Debug & Monitoring

-- Get stats for a specific bucket
local stats = cv.getBucketStats(dungeonId)
print("Players: " .. stats.players .. ", Entities: " .. stats.entities)

-- Get all bucket stats
local allStats = cv.getAllBucketStats()
for id, stats in pairs(allStats) do
    print("Bucket " .. id .. ": " .. stats.players .. " players")
end

Notes

  • cv.joinBucket updates player state key bucketId via cv.setPlayerState.
  • Always validate that the bucket exists before moving players or entities.
  • Default buckets (0, 1) cannot be destroyed.
  • Entity tracking is automatic when using cv.moveEntityToBucket.
  • Orphaned entity cleanup runs when entities are deleted or owners disconnect.