--!optimize 2 --!native --!strict --draft 4 type i53 = number type i24 = number type Ty = {i53} type ArchetypeId = number type Column = {any} type Archetype = { id: number, edges: { [i24]: { add: Archetype, remove: Archetype, }, }, types: Ty, type: string | number, entities: {number}, columns: {Column}, records: {}, } type Record = { archetype: Archetype, row: number, } type EntityIndex = {[i24]: Record} type ComponentIndex = {[i24]: ArchetypeMap} type ArchetypeRecord = number type ArchetypeMap = {sparse: {[ArchetypeId]: ArchetypeRecord}, size: number} type Archetypes = {[ArchetypeId]: Archetype} type ArchetypeDiff = { added: Ty, removed: Ty, } local HI_COMPONENT_ID = 256 local ON_ADD = HI_COMPONENT_ID + 1 local ON_REMOVE = HI_COMPONENT_ID + 2 local ON_SET = HI_COMPONENT_ID + 3 local REST = HI_COMPONENT_ID + 4 local function transitionArchetype( entityIndex: EntityIndex, to: Archetype, destinationRow: i24, from: Archetype, sourceRow: i24 ) local columns = from.columns local sourceEntities = from.entities local destinationEntities = to.entities local destinationColumns = to.columns local tr = to.records local types = from.types for i, column in columns do -- Retrieves the new column index from the source archetype's record from each component -- We have to do this because the columns are tightly packed and indexes may not correspond to each other. local targetColumn = destinationColumns[tr[types[i]]] -- Sometimes target column may not exist, e.g. when you remove a component. if targetColumn then targetColumn[destinationRow] = column[sourceRow] end -- If the entity is the last row in the archetype then swapping it would be meaningless. local last = #column if sourceRow ~= last then -- Swap rempves columns to ensure there are no holes in the archetype. column[sourceRow] = column[last] end column[last] = nil end -- Move the entity from the source to the destination archetype. local atSourceRow = sourceEntities[sourceRow] destinationEntities[destinationRow] = atSourceRow entityIndex[atSourceRow].row = destinationRow -- Because we have swapped columns we now have to update the records -- corresponding to the entities' rows that were swapped. local movedAway = #sourceEntities if sourceRow ~= movedAway then local atMovedAway = sourceEntities[movedAway] sourceEntities[sourceRow] = atMovedAway entityIndex[atMovedAway].row = sourceRow end sourceEntities[movedAway] = nil end local function archetypeAppend(entity: number, archetype: Archetype): number local entities = archetype.entities local length = #entities + 1 entities[length] = entity return length end local function newEntity(entityId: i53, record: Record, archetype: Archetype) local row = archetypeAppend(entityId, archetype) record.archetype = archetype record.row = row return record end local function moveEntity(entityIndex, entityId: i53, record: Record, to: Archetype) local sourceRow = record.row local from = record.archetype local destinationRow = archetypeAppend(entityId, to) transitionArchetype(entityIndex, to, destinationRow, from, sourceRow) record.archetype = to record.row = destinationRow end local function hash(arr): string | number return table.concat(arr, "_") end local function createArchetypeRecords(componentIndex: ComponentIndex, to: Archetype, _from: Archetype?) local destinationIds = to.types local records = to.records local id = to.id for i, destinationId in destinationIds do local archetypesMap = componentIndex[destinationId] if not archetypesMap then archetypesMap = {size = 0, sparse = {}} componentIndex[destinationId] = archetypesMap end archetypesMap.sparse[id] = i records[destinationId] = i end end local function archetypeOf(world: any, types: {i24}, prev: Archetype?): Archetype local ty = hash(types) local id = world.nextArchetypeId + 1 world.nextArchetypeId = id local length = #types local columns = table.create(length) for index in types do columns[index] = {} end local archetype = { columns = columns; edges = {}; entities = {}; id = id; records = {}; type = ty; types = types; } world.archetypeIndex[ty] = archetype world.archetypes[id] = archetype if length > 0 then createArchetypeRecords(world.componentIndex, archetype, prev) end return archetype end local function ensureArchetype(world: World, types, prev) if #types < 1 then return world.ROOT_ARCHETYPE end local ty = hash(types) local archetype = world.archetypeIndex[ty] if archetype then return archetype end return archetypeOf(world, types, prev) end local function findInsert(types: {i53}, toAdd: i53) for i, id in types do if id == toAdd then return -1 end if id > toAdd then return i end end return #types + 1 end local function findArchetypeWith(world: World, node: Archetype, componentId: i53) local types = node.types -- Component IDs are added incrementally, so inserting and sorting -- them each time would be expensive. Instead this insertion sort can find the insertion -- point in the types array. local at = findInsert(types, componentId) if at == -1 then -- If it finds a duplicate, it just means it is the same archetype so it can return it -- directly instead of needing to hash types for a lookup to the archetype. return node end local destinationType = table.clone(node.types) table.insert(destinationType, at, componentId) return ensureArchetype(world, destinationType, node) end local function ensureEdge(archetype: Archetype, componentId: i53) local edges = archetype.edges local edge = edges[componentId] if not edge then edge = {} :: any edges[componentId] = edge end return edge end local function archetypeTraverseAdd(world: World, componentId: i53, from: Archetype): Archetype from = from or world.ROOT_ARCHETYPE local edge = ensureEdge(from, componentId) local add = edge.add if not add then -- Save an edge using the component ID to the archetype to allow -- faster traversals to adjacent archetypes. add = findArchetypeWith(world, from, componentId) edge.add = add :: never end return add end local function ensureRecord(world, entityId: i53): Record local entityIndex = world.entityIndex local record = entityIndex[entityId] if record then return record end local ROOT = world.ROOT_ARCHETYPE local row = #ROOT.entities + 1 ROOT.entities[row] = entityId record = { archetype = ROOT, row = row } entityIndex[entityId] = record return record end local World = {} World.__index = World function World.new() local self = setmetatable({ archetypeIndex = {}; archetypes = {}; componentIndex = {}; entityIndex = {}; hooks = { [ON_ADD] = {}; }; nextArchetypeId = 0; nextComponentId = 0; nextEntityId = 0; ROOT_ARCHETYPE = (nil :: any) :: Archetype; }, World) self.ROOT_ARCHETYPE = archetypeOf(self, {}, nil) return self end local function emit(world, eventDescription) local event = eventDescription.event table.insert(world.hooks[event], { archetype = eventDescription.archetype; ids = eventDescription.ids; offset = eventDescription.offset; otherArchetype = eventDescription.otherArchetype; }) end local function onNotifyAdd(world, archetype, otherArchetype, row: number, added: Ty) if #added > 0 then emit(world, { archetype = archetype; event = ON_ADD; ids = added; offset = row; otherArchetype = otherArchetype; }) end end export type World = typeof(World.new()) function World.add(world: World, entityId: i53, componentId: i53) local record = ensureRecord(world, entityId) local from = record.archetype local to = archetypeTraverseAdd(world, componentId, from) if from and not (from == world.ROOT_ARCHETYPE) then moveEntity(world.entityIndex, entityId, record, to) else if #to.types > 0 then newEntity(entityId, record, to) onNotifyAdd(world, to, from, record.row, { componentId }) end end end -- Symmetric like `World.add` but idempotent function World.set(world: World, entityId: i53, componentId: i53, data: unknown) local record = ensureRecord(world, entityId) local from = record.archetype local archetypeRecord = from.records[componentId] if archetypeRecord then -- If the archetypes are the same it can avoid moving the entity -- and just set the data directly. from.columns[archetypeRecord][record.row] = data -- Should fire an OnSet event here. return end local to = archetypeTraverseAdd(world, componentId, from) if from then -- If there was a previous archetype, then the entity needs to move the archetype moveEntity(world.entityIndex, entityId, record, to) else if #to.types > 0 then -- When there is no previous archetype it should create the archetype newEntity(entityId, record, to) --onNotifyAdd(world, to, from, record.row, {componentId}) end end archetypeRecord = to.records[componentId] to.columns[archetypeRecord][record.row] = data end local function archetypeTraverseRemove(world: World, componentId: i53, from: Archetype): Archetype local edge = ensureEdge(from, componentId) local remove = edge.remove if not remove then local to = table.clone(from.types) local at = table.find(to, componentId) if not at then return from end table.remove(to, at) remove = ensureArchetype(world, to, from) edge.remove = remove :: never end return remove end function World.remove(world: World, entityId: i53, componentId: i53) local record = ensureRecord(world, entityId) local sourceArchetype = record.archetype local destinationArchetype = archetypeTraverseRemove(world, componentId, sourceArchetype) if sourceArchetype and not (sourceArchetype == destinationArchetype) then moveEntity(world.entityIndex, entityId, record, destinationArchetype) end end -- Keeping the function as small as possible to enable inlining local function get(record: Record, componentId: i24) local archetype = record.archetype local archetypeRecord = archetype.records[componentId] if not archetypeRecord then return nil end return archetype.columns[archetypeRecord][record.row] end function World.get(world: World, entityId: i53, a: i53, b: i53?, c: i53?, d: i53?, e: i53?) local id = entityId local record = world.entityIndex[id] if not record then return nil end local va = get(record, a) if b == nil then return va elseif c == nil then return va, get(record, b) elseif d == nil then return va, get(record, b), get(record, c) elseif e == nil then return va, get(record, b), get(record, c), get(record, d) else error("args exceeded") end end -- the less creation the better local function actualNoOperation() end local function noop(_self: Query, ...: i53): () -> (number, ...any) return actualNoOperation :: any end local EmptyQuery = { __iter = noop; without = noop; } EmptyQuery.__index = EmptyQuery setmetatable(EmptyQuery, EmptyQuery) export type Query = typeof(EmptyQuery) function World.query(world: World, ...: i53): Query -- breaking? if (...) == nil then error("Missing components") end local compatibleArchetypes = {} local length = 0 local components = {...} local archetypes = world.archetypes local queryLength = #components local firstArchetypeMap local componentIndex = world.componentIndex for _, componentId in components do local map = componentIndex[componentId] if not map then return EmptyQuery end if firstArchetypeMap == nil or map.size < firstArchetypeMap.size then firstArchetypeMap = map end end for id in firstArchetypeMap.sparse do local archetype = archetypes[id] local archetypeRecords = archetype.records local indices = {} local skip = false for i, componentId in components do local index = archetypeRecords[componentId] if not index then skip = true break end indices[i] = index end if skip then continue end length += 1 compatibleArchetypes[length] = {archetype, indices} end local lastArchetype, compatibleArchetype = next(compatibleArchetypes) if not lastArchetype then return EmptyQuery end local preparedQuery = {} preparedQuery.__index = preparedQuery function preparedQuery:without(...) local withoutComponents = {...} for i = #compatibleArchetypes, 1, -1 do local archetype = compatibleArchetypes[i][1] local records = archetype.records local shouldRemove = false for _, componentId in withoutComponents do if records[componentId] then shouldRemove = true break end end if shouldRemove then table.remove(compatibleArchetypes, i) end end lastArchetype, compatibleArchetype = next(compatibleArchetypes) if not lastArchetype then return EmptyQuery end return self end local lastRow local queryOutput = {} function preparedQuery:__iter() return function() local archetype = compatibleArchetype[1] local row = next(archetype.entities, lastRow) while row == nil do lastArchetype, compatibleArchetype = next(compatibleArchetypes, lastArchetype) if lastArchetype == nil then return end archetype = compatibleArchetype[1] row = next(archetype.entities, row) end lastRow = row local entityId = archetype.entities[row :: number] local columns = archetype.columns local tr = compatibleArchetype[2] if queryLength == 1 then return entityId, columns[tr[1]][row] elseif queryLength == 2 then return entityId, columns[tr[1]][row], columns[tr[2]][row] elseif queryLength == 3 then return entityId, columns[tr[1]][row], columns[tr[2]][row], columns[tr[3]][row] elseif queryLength == 4 then return entityId, columns[tr[1]][row], columns[tr[2]][row], columns[tr[3]][row], columns[tr[4]][row] elseif queryLength == 5 then return entityId, columns[tr[1]][row], columns[tr[2]][row], columns[tr[3]][row], columns[tr[4]][row], columns[tr[5]][row] elseif queryLength == 6 then return entityId, columns[tr[1]][row], columns[tr[2]][row], columns[tr[3]][row], columns[tr[4]][row], columns[tr[5]][row], columns[tr[6]][row] elseif queryLength == 7 then return entityId, columns[tr[1]][row], columns[tr[2]][row], columns[tr[3]][row], columns[tr[4]][row], columns[tr[5]][row], columns[tr[6]][row], columns[tr[7]][row] elseif queryLength == 8 then return entityId, columns[tr[1]][row], columns[tr[2]][row], columns[tr[3]][row], columns[tr[4]][row], columns[tr[5]][row], columns[tr[6]][row], columns[tr[7]][row], columns[tr[8]][row] end for i in components do queryOutput[i] = columns[tr[i]][row] end return entityId, unpack(queryOutput, 1, queryLength) end end return setmetatable({}, preparedQuery) :: any end function World.component(world: World) local componentId = world.nextComponentId + 1 if componentId > HI_COMPONENT_ID then -- IDs are partitioned into ranges because component IDs are not nominal, -- so it needs to error when IDs intersect into the entity range. error("Too many components, consider using world:entity() instead to create components.") end world.nextComponentId = componentId return componentId end function World.entity(world: World) local nextEntityId = world.nextEntityId + 1 world.nextEntityId = nextEntityId return nextEntityId + REST end -- should reuse this logic in World.set instead of swap removing in transition archetype local function destructColumns(columns, count, row) if row == count then for _, column in columns do column[count] = nil end else for _, column in columns do column[row] = column[count] column[count] = nil end end end local function archetypeDelete(entityIndex, archetype: Archetype, row: i24, destruct: boolean) local entities = archetype.entities local last = #entities local entityToMove = entities[last] --local entityToDelete = entities[row] entities[row] = entityToMove entities[last] = nil if row ~= last then local recordToMove = entityIndex[entityToMove] if recordToMove then recordToMove.row = row end end local columns = archetype.columns if not destruct then return end destructColumns(columns, last, row) end function World.delete(world: World, entityId: i53) local entityIndex = world.entityIndex local record = entityIndex[entityId] local archetype = record.archetype archetypeDelete(entityIndex, archetype, record.row, true) entityIndex[entityId] = nil end function World.__iter(world: World): () -> (number?, unknown?) local entityIndex = world.entityIndex local last return function() local entity, record = next(entityIndex, last) if not entity then return end last = entity local archetype = record.archetype if not archetype then -- Returns only the entity id as an entity without data should not return -- data and allow the user to get an error if they don't handle the case. return entity end local row = record.row local types = archetype.types local columns = archetype.columns local entityData = {} for i, column in columns do -- We use types because the key should be the component ID not the column index entityData[types[i]] = column[row] end return entity, entityData end end return table.freeze({ World = World; ON_ADD = ON_ADD; ON_REMOVE = ON_REMOVE; ON_SET = ON_SET; })