Sorted List

Reference for gameplay_util_sortedList, a generic container that manages a list of named, ID-bearing objects with sorted ordering, name-based lookup, and serialization support.

Constructor

local list = require('gameplay/util/sortedList')(name, parent, objectConstructor)

Methods (C)

Core Operations

Lookup

Debug

Serialization

Overridable Callbacks

Data Structures

list.objects (table)

ID-keyed table of all objects. Has a metatable that returns a sentinel {name="Missing!", missing=true, id=-1} for missing keys.

list.sorted (array)

Objects sorted by sortOrder. Rebuilt on every mutation.

list.byName (table)

Name-keyed lookup table. Only populated when buildNamesDir() is called explicitly. First object with a given name wins.

How It Works

1. Objects are created via the provided constructor and stored by ID
2. After every insert/remove, sort() rebuilds the sorted array
3. Sort order is based on sortOrder property (renumbered sequentially after each sort)
4. move() swaps two adjacent objects' sort positions
5. Procedural objects (isProcedural = true) are excluded from serialization
6. Deserialization recreates objects, tracking old→new ID mappings via oldIdMap

Usage Example

local sortedList = require('gameplay/util/sortedList')

-- Create a list with a simple constructor
local myList = sortedList("myObjects", parentObj, function(parent, name, forceId)
  local id = forceId or getNextId()
  return {id = id, name = name, sortOrder = id, parent = parent}
end)

-- Add objects
local obj1 = myList:create("First")
local obj2 = myList:create("Second")

-- Reorder
myList:move(obj1.id, 1)  -- move down

-- Lookup by name
myList:buildNamesDir()
local found = myList.byName["First"]

-- Iterate in order
for _, obj in ipairs(myList.sorted) do
  log("I", "", obj.name)
end

-- Serialize
local data = myList:onSerialize()

See Also

• gameplay/util/crashDetection - Vehicle Crash Detection System - Related reference
• gameplay/util/damageAssessment - Vehicle Damage Location Assessment - Related reference
• gameplay/util/groundContact - Ground Contact Detection - Related reference
• Gameplay Systems Guide - Guide