nata.lua

--- Entity management for Lua.
-- @module nata

local nata = {
	_VERSION = 'Nata v0.3.3',
	_DESCRIPTION = 'Entity management for Lua.',
	_URL = 'https://github.com/tesselode/nata',
	_LICENSE = [[
		MIT License

		Copyright (c) 2020 Andrew Minnich

		Permission is hereby granted, free of charge, to any person obtaining a copy
		of this software and associated documentation files (the "Software"), to deal
		in the Software without restriction, including without limitation the rights
		to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
		copies of the Software, and to permit persons to whom the Software is
		furnished to do so, subject to the following conditions:

		The above copyright notice and this permission notice shall be included in all
		copies or substantial portions of the Software.

		THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
		IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
		FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
		AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
		LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
		OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
		SOFTWARE.
	]]
}

-- gets the error level needed to make an error appear
-- in the user's code, not the library code
local function getUserErrorLevel()
	local source = debug.getinfo(1).source
	local level = 1
	while debug.getinfo(level).source == source do
		level = level + 1
	end
	--[[
		we return level - 1 here and not just level
		because the level was calculated one function
		deeper than the function that will actually
		use this value. if we produced an error *inside*
		this function, level would be correct, but
		for the function calling this function, level - 1
		is correct.
	]]
	return level - 1
end

-- gets the name of the function that the user called
-- that eventually caused an error
local function getUserCalledFunctionName()
	return debug.getinfo(getUserErrorLevel() - 1).name
end

local function checkCondition(condition, message)
	if condition then return end
	error(message, getUserErrorLevel())
end

-- changes a list of types into a human-readable phrase
-- i.e. string, table, number -> "string, table, or number"
local function getAllowedTypesText(...)
	local numberOfArguments = select('#', ...)
	if numberOfArguments >= 3 then
		local text = ''
		for i = 1, numberOfArguments - 1 do
			text = text .. string.format('%s, ', select(i, ...))
		end
		text = text .. string.format('or %s', select(numberOfArguments, ...))
		return text
	elseif numberOfArguments == 2 then
		return string.format('%s or %s', select(1, ...), select(2, ...))
	end
	return select(1, ...)
end

-- checks if an argument is of the correct type, and if not,
-- throws a "bad argument" error consistent with the ones
-- lua and love produce
local function checkArgument(argumentIndex, argument, ...)
	for i = 1, select('#', ...) do
		-- allow tables with the __call metamethod to be treated like functions
		if select(i, ...) == 'function' then
			if type(argument) == 'table' and getmetatable(argument).__call then
				return
			end
		end
		if type(argument) == select(i, ...) then return end
	end
	error(
		string.format(
			"bad argument #%i to '%s' (expected %s, got %s)",
			argumentIndex,
			getUserCalledFunctionName(),
			getAllowedTypesText(...),
			type(argument)
		),
		getUserErrorLevel()
	)
end

local function checkOptionalArgument(argumentIndex, argument, ...)
	if argument == nil then return end
	checkArgument(argumentIndex, argument, ...)
end

local function removeByValue(t, v)
	for i = #t, 1, -1 do
		if t[i] == v then table.remove(t, i) end
	end
end

local function entityHasKeys(entity, keys)
	for _, key in ipairs(keys) do
		if not entity[key] then return false end
	end
	return true
end

local function filterEntity(entity, filter)
	if type(filter) == 'table' then
		return entityHasKeys(entity, filter)
	elseif type(filter) == 'function' then
		return filter(entity)
	end
	return true
end

--- Defines the behaviors of a system.
--
-- There's no constructor for SystemDefinitions. Rather, you simply
-- define a table with functions that correspond to events. These
-- events can be named anything you like. Below are the built-in events
-- that the pool will automatically call.
-- @type SystemDefinition

--- Called when the pool is first created.
-- @function SystemDefinition:init
-- @param ... additional arguments that were passed to `nata.new`.

--- Called when an entity is added to the pool.
-- @function SystemDefinition:add
-- @tparam table e the entity that was added

--- Called when an entity is removed from the pool.
-- @function SystemDefinition:remove
-- @tparam table e the entity that was removed

--- Called when an entity is added to a group.
-- @function SystemDefinition:addToGroup
-- @string groupName the name of the group that the entity was added to
-- @tparam table e the entity that was added

--- Called when an entity is removed from a group.
-- @function SystemDefinition:removeFromGroup
-- @string groupName the name of the group that the entity was removed from
-- @tparam table e the entity that was removed

--- Responds to events in a pool.
--
-- Systems are not created directly. They're created by the @{Pool}
-- according to the @{SystemDefinition}s passed to `nata.new`.
-- Each system instance inherits all of the functions of its
-- @{SystemDefinition}.
-- @type System

--- The @{Pool} that this system is running on.
-- @tfield Pool pool

--- Manages a subset of entities.
-- @type Group

--- The filter that defines which entities are added to this group.
-- Can be either:
--
-- - A list of required keys
-- - A function that takes the entity as the first argument
-- and returns true if the entity should be added to the group
-- @tfield[opt] table|function filter

--- A function that specifies how the entities in this group should be sorted.
-- Has the same requirements as the function argument to Lua's built-in `table.sort`.
-- @tfield[opt] function sort

--- A list of all the entities in the group.
-- @tfield table entities

--- A set of all the entities in the group.
-- @tfield table hasEntity
-- @usage
-- print(pool.groups.physical.hasEntity[e]) -- prints "true" if the entity is in the "physical" group, or "nil" if not

--- Manages entities in a game world.
-- @type Pool
local Pool = {}
Pool.__index = Pool

--- A list of all the entities in the pool.
-- @tfield table entities

--- A set of all the entities in the pool.
-- @tfield table hasEntity
-- @usage
-- print(pool.hasEntity[e]) -- prints "true" if the entity is in the pool, or "nil" if not

--- A dictionary of the @{Group}s in the pool.
-- @tfield table groups

--- A field containing any data you want.
-- @field data

---

function Pool:_validateOptions(options)
	checkOptionalArgument(1, options, 'table')
	if not options then return end
	if options.groups then
		checkCondition(type(options.groups) == 'table', "groups must be a table")
		for groupName, groupOptions in pairs(options.groups) do
			checkCondition(type(groupOptions) == 'table',
				string.format("options for group '$s' must be a table", groupName))
			local filter = groupOptions.filter
			if filter ~= nil then
				checkCondition(type(filter) == 'table' or type(filter) == 'function',
					string.format("filter for group '%s' must be a table or function", groupName))
			end
			local sort = groupOptions.sort
			if sort ~= nil then
				checkCondition(type(sort) == 'function',
					string.format("sort for group '%s' must be a function", groupName))
			end
		end
	end
	if options.systems then
		checkCondition(type(options.systems) == 'table', "systems must be a table")
		for _, system in ipairs(options.systems) do
			checkCondition(type(system) == 'table', "all systems must be tables")
		end
	end
end

function Pool:_init(options, ...)
	self:_validateOptions(options)
	options = options or {}
	-- entities that will be added to the pool on the next flush
	self._queue = {}
	-- a temporary table for entities that will be added to the pool
	-- on the current flush (see Pool.flush for more details)
	self._entitiesToFlush = {}
	self.entities = {}
	self.hasEntity = {}
	self.groups = {}
	self._systems = {}
	self._events = {}
	self.data = options.data or {}
	local groups = options.groups or {}
	local systems = options.systems or {nata.oop()}
	for groupName, groupOptions in pairs(groups) do
		self.groups[groupName] = {
			filter = groupOptions.filter,
			sort = groupOptions.sort,
			entities = {},
			hasEntity = {},
		}
	end
	for _, systemDefinition in ipairs(systems) do
		local system = setmetatable({
			pool = self,
		}, {__index = systemDefinition})
		table.insert(self._systems, system)
	end
	self:emit('init', ...)
end

--- Queues an entity to be added to the pool.
-- @tparam table entity the entity to add
-- @treturn table the queued entity
function Pool:queue(entity)
	table.insert(self._queue, entity)
	return entity
end

--- Adds the queued entities to the pool. Entities are added
-- in the order they were queued.
function Pool:flush()
	--[[
		Move the currently queued entities to a temporary
		table. This way, if an add/addToGroup/removeToGroup
		event emission leads to another entity being queued,
		it will be saved for the next flush, rather than
		adding entities to the table we're in the middle
		of iterating over, which would lead to an array with
		holes and screw everything up.
	]]
	for i = 1, #self._queue do
		local entity = self._queue[i]
		self._entitiesToFlush[i] = entity
		self._queue[i] = nil
	end
	for i = 1, #self._entitiesToFlush do
		local entity = self._entitiesToFlush[i]
		-- check if the entity belongs in each group and
		-- add it to/remove it from the group as needed
		for groupName, group in pairs(self.groups) do
			if filterEntity(entity, group.filter) then
				if not group.hasEntity[entity] then
					table.insert(group.entities, entity)
					group.hasEntity[entity] = true
					self:emit('addToGroup', groupName, entity)
				end
				if group.sort then group._needsResort = true end
			elseif group.hasEntity[entity] then
				removeByValue(group.entities, entity)
				group.hasEntity[entity] = nil
				self:emit('removeFromGroup', groupName, entity)
			end
		end
		-- add the entity to the pool if it hasn't been added already
		if not self.hasEntity[entity] then
			table.insert(self.entities, entity)
			self.hasEntity[entity] = true
			self:emit('add', entity)
		end
		self._entitiesToFlush[i] = nil
	end
	-- re-sort groups
	for _, group in pairs(self.groups) do
		if group._needsResort then
			table.sort(group.entities, group.sort)
			group._needsResort = nil
		end
	end
end

--- Removes entities from the pool.
-- @tparam function f the condition upon which an entity should be
-- removed. The function should take an entity as the first argument
-- and return `true` if the entity should be removed.
function Pool:remove(f)
	checkArgument(1, f, 'function')
	for groupName, group in pairs(self.groups) do
		for i = #group.entities, 1, -1 do
			local entity = group.entities[i]
			if f(entity) then
				self:emit('removeFromGroup', groupName, entity)
				table.remove(group.entities, i)
				group.hasEntity[entity] = nil
			end
		end
	end
	for i = #self.entities, 1, -1 do
		local entity = self.entities[i]
		if f(entity) then
			self:emit('remove', entity)
			table.remove(self.entities, i)
			self.hasEntity[entity] = nil
		end
	end
end

--- Registers a function to be called when an event is emitted.
-- @string event the event to listen for
-- @tparam function f the function to call
-- @treturn function the function that was registered
function Pool:on(event, f)
	checkCondition(event ~= nil, "event cannot be nil")
	checkArgument(2, f, 'function')
	self._events[event] = self._events[event] or {}
	table.insert(self._events[event], f)
	return f
end

--- Unregisters a function from an event.
-- @string event the event to unregister the function from
-- @tparam function f the function to unregister
function Pool:off(event, f)
	checkCondition(event ~= nil, "event cannot be nil")
	checkArgument(2, f, 'function')
	if self._events[event] then
		removeByValue(self._events[event], f)
	end
end

--- Emits an event. The `system[event]` function will be called
-- for each system that has it, and functions registered
-- to the event will be called as well.
-- @string event the event to emit
-- @param ... additional arguments to pass to the functions that are called
function Pool:emit(event, ...)
	checkCondition(event ~= nil, "event cannot be nil")
	for _, system in ipairs(self._systems) do
		if type(system[event]) == 'function' then
			system[event](system, ...)
		end
	end
	if self._events[event] then
		for _, f in ipairs(self._events[event]) do
			f(...)
		end
	end
end

--- Gets this pool's instance of a system.
-- @tparam SystemDefinition systemDefinition the system class to get the instance of
-- @treturn System the instance of the system running in this pool
function Pool:getSystem(systemDefinition)
	checkArgument(1, systemDefinition, 'table')
	for _, system in ipairs(self._systems) do
		if getmetatable(system).__index == systemDefinition then
			return system
		end
	end
end

---
-- @section end

local function validateOopOptions(options)
	checkOptionalArgument(1, options, 'table')
	if not options then return end
	if options.include then
		checkCondition(type(options.include) == 'table', "include must be a table")
	end
	if options.exclude then
		checkCondition(type(options.exclude) == 'table', "exclude must be a table")
	end
end

--- Defines the behavior of an OOP system.
-- @type OopOptions
-- @see nata.oop

--- A list of events to forward to entities. If not defined,
-- the system will forward all events to entities (except
-- for the ones in the exclude list).
-- @tfield table include

--- A list of events *not* to forward to entities.
-- @tfield table exclude

--- The name of the group of entities to forward events to.
-- If not defined, the system will forward events to all entities.
-- @tfield string group

---
-- @section end

--- Creates a new OOP system definition.
-- An OOP system, upon receiving an event, will call
-- the function of the same name on each entity it monitors
-- (if it exists). This facilitates a more traditional, OOP-style
-- entity management, where you loop over a table of entities and
-- call update and draw functions on them.
-- @tparam[opt] OopOptions options how to set up the OOP system
-- @treturn SystemDefinition the new OOP system definition
function nata.oop(options)
	validateOopOptions(options)
	local group = options and options.group
	local include, exclude
	if options and options.include then
		include = {}
		for _, event in ipairs(options.include) do
			include[event] = true
		end
	end
	if options and options.exclude then
		exclude = {}
		for _, event in ipairs(options.exclude) do
			exclude[event] = true
		end
	end
	return setmetatable({_cache = {}}, {
		__index = function(t, event)
			t._cache[event] = t._cache[event] or function(self, ...)
				local shouldCallEvent = true
				if include and not include[event] then shouldCallEvent = false end
				if exclude and exclude[event] then shouldCallEvent = false end
				if shouldCallEvent then
					local entities
					-- not using ternary here because if the group doesn't exist,
					-- i'd rather it cause an error than just silently falling back
					-- to the main entity pool
					if group then
						entities = self.pool.groups[group].entities
					else
						entities = self.pool.entities
					end
					for _, entity in ipairs(entities) do
						if type(entity[event]) == 'function' then
							entity[event](entity, ...)
						end
					end
				end
			end
			return t._cache[event]
		end
	})
end

--- Defines the filter and sort function for a @{Group}.
-- @type GroupOptions

--- The filter that defines which entities are added to this group.
-- Can be either:
--
-- - A list of required keys
-- - A function that takes the entity as the first argument
-- and returns true if the entity should be added to the group
-- @tfield[opt] table|function filter

--- A function that specifies how the entities in this group should be sorted.
-- Has the same requirements as the function argument to Lua's built-in `table.sort`.
-- @tfield[opt] function sort

--- Defines the groups and systems for a @{Pool}.
-- @type PoolOptions

--- A dictionary of groups for the pool to have.
-- Each key is the name of the group, and each value
-- should be a @{GroupOptions} table.
-- @tfield[opt={}] table groups

--- A list of @{SystemDefinition}s for the pool to use.
-- @tfield[opt={nata.oop()}] table systems

--- An initial value to set @{Pool.data} to.
-- @field[opt={}] data

---
-- @section end

--- Creates a new @{Pool}.
-- @tparam[opt] PoolOptions options how to set up the pool
-- @param[opt] ... additional arguments to pass to the pool's init event
-- @treturn Pool the new pool
function nata.new(options, ...)
	local pool = setmetatable({}, Pool)
	pool:_init(options, ...)
	return pool
end

return nata