From f7140fb3cc828648210c6678a332eefa413cc228 Mon Sep 17 00:00:00 2001 From: Vanic Date: Sun, 8 Feb 2026 20:26:17 +0300 Subject: [PATCH] `Entity`: reating a wrapper class for an entity. Close #26 --- mods/CORE/Entity/init.lua | 2 +- mods/CORE/Entity/src/Entity.lua | 66 ++++++++++++++-- mods/CORE/Entity/src/Entity/Callbacks.lua | 75 +++++++++++++++++++ .../Entity/src/Entity/EntityDefinition.lua | 4 +- mods/CORE/Entity/src/Entity/Settings.lua | 14 ++++ 5 files changed, 151 insertions(+), 10 deletions(-) create mode 100644 mods/CORE/Entity/src/Entity/Callbacks.lua create mode 100644 mods/CORE/Entity/src/Entity/Settings.lua diff --git a/mods/CORE/Entity/init.lua b/mods/CORE/Entity/init.lua index 0a99975..6d18571 100644 --- a/mods/CORE/Entity/init.lua +++ b/mods/CORE/Entity/init.lua @@ -1,4 +1,4 @@ local modInfo = Mod.getInfo('smc__core__entity') local require = modInfo.require -return require('Entity') \ No newline at end of file +return require('Entity') diff --git a/mods/CORE/Entity/src/Entity.lua b/mods/CORE/Entity/src/Entity.lua index d7ca351..b46df62 100644 --- a/mods/CORE/Entity/src/Entity.lua +++ b/mods/CORE/Entity/src/Entity.lua @@ -1,16 +1,68 @@ local getInstance = Class.getInstance +local tableCopy, tableMerge = table.copy, table.merge + ---@class Entity -local Entity = {} +---@field entityDef Entity.EntityDefinition +---@field luantiDef EntityDefinition +---@field defaultDef Entity.EntityDefinition +local Entity = { + defaultDef = { + settings = { + _name = '', + _add_mod_name = true, + initial_properties = {}, + }, + callbacks = {} + } +} ----@param def Entity.EntityDefinition ----@return Entity -function Entity:new(def) - local instance = getInstance(self, { +---The alias `table.merge` for EmmyLua +---@type fun(...):(EntityDefinition) +local defMerge = function(...) + return tableMerge(...) +end - }) +---@param entityDef Entity.EntityDefinition +---@return EntityDefinition +local function entityDefToLuantiDef(entityDef) + entityDef = tableCopy(entityDef) + local s = entityDef.settings + local c = entityDef.callbacks + + local luantiDef = defMerge(s, c) + + return luantiDef +end + +---The alias `table.merge` for EmmyLua +---@type fun(...):(Entity.EntityDefinition) +local defMerge = function(...) + return tableMerge(...) +end + +---@param entityDef Entity.EntityDefinition +---@return Entity +function Entity:new(entityDef) + -- Adding default parameters + entityDef = defMerge(entityDef, self.defaultDef, true) + local s = entityDef.settings + + if s._add_mod_name then + s._name = Mod.getInfo().shortName .. ':' .. s._name + end + + ---@type Entity + local instance = getInstance(self, {}) + + local luantiDef = entityDefToLuantiDef(entityDef) + + instance.entityDef = entityDef + instance.luantiDef = luantiDef + + core.register_entity(s._name, luantiDef) return instance end -return Entity \ No newline at end of file +return Entity diff --git a/mods/CORE/Entity/src/Entity/Callbacks.lua b/mods/CORE/Entity/src/Entity/Callbacks.lua new file mode 100644 index 0000000..adfa3c3 --- /dev/null +++ b/mods/CORE/Entity/src/Entity/Callbacks.lua @@ -0,0 +1,75 @@ +---@class Entity.Callbacks +local Callbacks = {} + +---Called when the object is instantiated. +--- * `dtime_s` is the time passed since the object was unloaded, +---which can be used for updating the entity state. +---@type fun(self, staticdata:string, dtime_s:number)? +Callbacks.on_activate = nil + +---Called when the object is about to get removed or unloaded. +--- * `removal`: boolean indicating whether the object is about to get removed. +--- Calling `object:remove()` on an active object will call this with `removal=true`. +--- The mapblock the entity resides in being unloaded will call this with `removal=false`. +--- +---Note that this won't be called if the object hasn't been activated in the first place. +---In particular, `core.clear_objects({mode = "full"})` won't call this, +---whereas `core.clear_objects({mode = "quick"})` might call this. +---@type fun(self, removal:boolean)? +Callbacks.on_deactivate = nil + +---Called on every server tick, after movement and collision processing. +--- * `dtime`: elapsed time since last call +--- * `s`: table with collision info (only available if `physical=true`) +---@type fun(self, dtime:number, moveresult:table)? -- TODO: дописать более точный тип moveresult +Callbacks.on_step = nil + + +---Called when somebody punches the object. +---Note that you probably want to handle most punches using the automatic armor group system. +--- * `puncher`: an `ObjectRef `(can be `nil`) +--- * `time_from_last_punch`: Meant for disallowing spamming of clicks (can be `nil`). +--- * `tool_capabilities`: capability table of used item +--- * `dir`: unit vector of direction of punch. Always defined. Points from the puncher to the punched. +--- * `damage``: damage that will be done to entity. +--- +---Can return `true` to prevent the default damage mechanism. +---@type (fun(self, puncher:ObjectRef|Player|nil, time_from_last_punch:number|nil, tool_capabilities:table|nil, dir:vector, damage:number):boolean)? -- TODO: дописать более точный тип для tool_capabilities +Callbacks.on_punch = nil + +---Called when the object dies. +--- * `killer`: an `ObjectRef` (can be `nil`) +---@type fun(self, killer:ObjectRef|Player|nil)? +Callbacks.on_death = nil + +---Called when `clicker` pressed the 'place/use' key while +---pointing to the object (not necessarily an actual rightclick) +--- * `clicker`: an `ObjectRef` (may or may not be a player) +---@type fun(self, clicker:ObjectRef|Player)? +Callbacks.on_rightclick = nil + + +---Called after another object is attached to this object. +--- * `child`: an `ObjectRef` of the child +---@type fun(self, child:ObjectRef)? +Callbacks.on_attach_child = nil + +---Called after another object has detached from this object. +--- * `child`: an `ObjectRef` of the child +---@type fun(self, child:ObjectRef)? +Callbacks.on_detach_child = nil + + +---Called after detaching from another object. +--- * `parent`: an ObjectRef from where it got detached +--- +---**Note**: this is also called before removal from the world. +---@type fun(self, parent)? +Callbacks.on_detach = nil + +---Should return a string that will be passed to `on_activate` when the object +---is instantiated the next time. +---@type (fun(self):string)? +Callbacks.get_staticdata = nil + +return Callbacks diff --git a/mods/CORE/Entity/src/Entity/EntityDefinition.lua b/mods/CORE/Entity/src/Entity/EntityDefinition.lua index 2bbd6ed..e87113f 100644 --- a/mods/CORE/Entity/src/Entity/EntityDefinition.lua +++ b/mods/CORE/Entity/src/Entity/EntityDefinition.lua @@ -1,6 +1,6 @@ ---@class Entity.EntityDefinition ----@field settings Item.Settings ----@field callbacks Item.Callbacks? +---@field settings Entity.Settings +---@field callbacks Entity.Callbacks? local EntityDefinition = {} return EntityDefinition diff --git a/mods/CORE/Entity/src/Entity/Settings.lua b/mods/CORE/Entity/src/Entity/Settings.lua new file mode 100644 index 0000000..9d5bf72 --- /dev/null +++ b/mods/CORE/Entity/src/Entity/Settings.lua @@ -0,0 +1,14 @@ +---@class Entity.Settings +local Settings = {} + +---Registration name for the entity. Must be unique. +---@type string +Settings._name = nil + +---Whether to add the mod name to the settings._name. Default: `true` +Settings._add_mod_name = nil + +---@type ObjectProperties +Settings.initial_properties = nil + +return Settings