Collections

Getting it

local Collections = Engine:GetPackage("Collections")

Overview

Plain Luau tables are great for arrays and dictionaries, but some jobs need a data structure with different guarantees: removing from the front of a list without shifting it, always getting the smallest item, or forgetting the oldest entries automatically. Collections provides those, each with a small consistent API.

All collections have a read-only Size and IsEmpty. Popping or peeking an empty collection raises an error, so check IsEmpty first when it might be empty.

local Collections = Engine:GetPackage("Collections")

local queue = Collections.Queue()
queue:Push("first")
queue:Push("second")
print(queue:Pop()) --> first

local recent = Collections.RingBuffer(10) -- keeps the last 10 entries
for i = 1, 25 do
	recent:Push(i)
end
print(recent:Oldest(), recent:Newest()) --> 16 25

Queue

Collections.Queue(items: { any }?): Queue

First in, first out. Push adds to the back, Pop and Peek use the front.

Stack

Collections.Stack(items: { any }?): Stack

Last in, first out. Same members as Queue, but Pop and Peek use the most recently pushed item.

Deque

Collections.Deque(items: { any }?): Deque

A double-ended queue: add and remove at both ends in constant time.

PriorityQueue

Collections.PriorityQueue(less: ((a: number, b: number) -> boolean)?): PriorityQueue

Always hands out the item with the lowest priority number first (a binary heap). Pass your own less to change the order, for example function(a, b) return a > b end for highest first.

local jobs = Collections.PriorityQueue()
jobs:Push("save", 2)
jobs:Push("kick cheater", 1)
local job, priority = jobs:Pop() --> "kick cheater", 1

RingBuffer

Collections.RingBuffer(capacity: number?): RingBuffer

A fixed-size buffer that overwrites its oldest item once full. Ideal for "the last N" of anything: chat lines, frame times, positions. Capacity defaults to the DefaultRingBufferCapacity setting.

LRUCache

Collections.LRUCache(capacity: number?): LRUCache

A key-value cache that evicts the least recently used entry when it is full. Capacity defaults to the DefaultLRUCacheCapacity setting.

local thumbnails = Collections.LRUCache(200)

thumbnails.Evicted:Connect(function(userId, image)
	print("dropped", userId)
end)

local function getThumbnail(userId)
	local cached = thumbnails:Get(userId)
	if cached then
		return cached
	end
	local image = Players:GetUserThumbnailAsync(userId, Enum.ThumbnailType.HeadShot, Enum.ThumbnailSize.Size100x100)
	thumbnails:Set(userId, image)
	return image
end

Set

Collections.Set(items: { any }?): Set

A collection of unique items.

Multiset

Collections.Multiset(items: { any }?): Multiset

A set that counts how many of each item it holds, like an inventory of stackable items.

Configuration