diff --git a/mods/API/Mod/init.lua b/mods/API/Mod/init.lua index 3ad3e73..998707f 100644 --- a/mods/API/Mod/init.lua +++ b/mods/API/Mod/init.lua @@ -1,10 +1,10 @@ ---- Luanti mod +---Luanti mod ---@class Mod ----@field public name string Technical name of the mod. ----@field public shortName string ----@field public path string Path to the mod folder. ----@field public Class table A public class that provides a mod. ----@field public require fun(FileName:string):table +---@field name string Technical name of the mod. +---@field shortName string +---@field path string Path to the mod folder. +---@field Class table A public class that provides a mod. +---@field require fun(FileName:string):table Mod = {} ---Returns the mod name without prefixes @@ -16,7 +16,7 @@ local function getShortModName(name) return shortName end ---- Return table with mod name, path and require function. +---Return table with mod name, path and require function. ---@return {name: string, shortName: string, path: string, require: fun(FileName : string): table} function Mod.getInfo() local name = core.get_current_modname() @@ -29,40 +29,36 @@ end function Mod:new() ---@type Mod - self = setmetatable(Mod.getInfo(), { __index = self }) - - return self -end - ---- Get an instance of a public class provided by a mod ----@param ... any? ----@return table --- TODO: возможно стоит создать какой-то абстрактный класс, --- который будет является алеасом на table и будет обозначать наш класс -function Mod:getModClassInstance(...) - local instance = self.Class:new(...) + local instance = setmetatable(Mod.getInfo(), { __index = self }) return instance end ---- Inherits a child class from a parent class ----@static +---Get an instance of a public class provided by a mod +---@param ... any? +---@return table +function Mod:getModClassInstance(...) + local classInstance = self.Class:new(...) + + return classInstance +end + +---Inherits a child class from a parent class ---@param ParentClass table ---@param ChildClass table? ----@return table +---@return table function Mod:getClassExtended(ParentClass, ChildClass) - local ChildClass = setmetatable(ChildClass or {}, { __index = ParentClass }) + local childClass = setmetatable(ChildClass or {}, { __index = ParentClass }) - return ChildClass + return childClass end ---- Inherits a child class from a parent public class provided by the mod. ----@static +---Inherits a child class from a parent public class provided by the mod. ---@param ChildClass table? ----@return table +---@return table function Mod:getModClassExtended(ChildClass) - local ChildClass = Mod:getClassExtended(self.Class, ChildClass or {}) + local childClass = Mod:getClassExtended(self.Class, ChildClass or {}) - return ChildClass + return childClass end diff --git a/mods/CORE/Item/src/Item.lua b/mods/CORE/Item/src/Item.lua index 2c703d0..5413e9e 100644 --- a/mods/CORE/Item/src/Item.lua +++ b/mods/CORE/Item/src/Item.lua @@ -19,22 +19,27 @@ local Item = { } } +---The alias `table.merge` for EmmyLua +---@type fun(...):(NodeDefinition|ItemDefinition) +local defMerge = function(...) + return table.merge(...) +end + ---@param itemDef Item.ItemDefinition +---@return NodeDefinition|ItemDefinition local function itemDefToLuantiDef(itemDef) - -- TODO: удалить следующую строчку, когда подключим ide-helper от Алека - ---@diagnostic disable-next-line: undefined-field itemDef = table.copy(itemDef) local s = itemDef.settings local c = itemDef.callbacks local description = s.title .. "\n" .. s.description s.title, s.description = nil, description - local luantiDef = table.merge(s, c) + local luantiDef = defMerge(s, c) return luantiDef end ----@param luantiDef table +---@param luantiDef NodeDefinition|ItemDefinition local function register3dItem(luantiDef) local ld = luantiDef local name = ld.name @@ -42,7 +47,7 @@ local function register3dItem(luantiDef) core.register_node(':'..name, luantiDef) end ----@param luantiDef table +---@param luantiDef ItemDefinition local function registerFlatItem(luantiDef) local ld = luantiDef local name = ld.name @@ -50,14 +55,14 @@ local function registerFlatItem(luantiDef) core.register_craftitem(':'..name, luantiDef) end ----The aleas `table.merge` for EmmyLua +---The alias `table.merge` for EmmyLua ---@type fun(...):(Item.ItemDefinition) local defMerge = function(...) return table.merge(...) end ----@param itemDef Item.ItemDefinition ----@return Item +---@param itemDef Item.ItemDefinition +---@return Item function Item:new(itemDef) ---Adding default parameters itemDef = defMerge(itemDef, self.defaultDef, true) @@ -81,13 +86,13 @@ function Item:new(itemDef) registerFlatItem(luantiDef) end - ---@return string function instance:getVisual() return visual end instance.itemDef = itemDef instance.luantiDef = luantiDef + return instance end @@ -95,7 +100,7 @@ end ---default parameters that will be added to the item's parameters ---when an instance is received. ---@param defaultDef Item.ItemDefinition ----@return Item +---@return Item function Item:getExtended(defaultDef) ---@type Item local ChildClass = Mod:getClassExtended(self, { @@ -107,12 +112,13 @@ end ---Returns an instance of the `ItemFactory` class that can be used to mass-register identical items. ---@param defaultDef? Item.ItemDefinition ----@return ItemFactory +---@return ItemFactory function Item:getFactory(defaultDef) if defaultDef == nil then defaultDef = self.defaultDef end + ---@type ItemFactory local instance = Core.ItemFactory():new(self, defaultDef) return instance diff --git a/mods/CORE/Item/src/Item/Callbacks.lua b/mods/CORE/Item/src/Item/Callbacks.lua index 38184bf..3f9bda5 100644 --- a/mods/CORE/Item/src/Item/Callbacks.lua +++ b/mods/CORE/Item/src/Item/Callbacks.lua @@ -1,7 +1,7 @@ ---@class Item.Callbacks local Callbacks = {} --- TODO: Вписать вместо `table` более определенные классы: ItemStack, ObjectRef и т.п. +-- TODO: Разобраться с дубликатами аннотаций полей. Приоритетно брать аннотации из util/ide-helper ---Called when the 'place' key was pressed with the item in hand ---and pointing at a node. diff --git a/mods/CORE/Item/src/Item/Settings.lua b/mods/CORE/Item/src/Item/Settings.lua index 1ea5f3e..ef2b263 100644 --- a/mods/CORE/Item/src/Item/Settings.lua +++ b/mods/CORE/Item/src/Item/Settings.lua @@ -1,6 +1,8 @@ ---@class Item.Settings local Settings = {} +-- TODO: Разобраться с дубликатами аннотаций полей. Приоритетно брать аннотации из util/ide-helper + ---Technical name of the item. Must be unique and have the format `mod_name:item_name` ---@type string Settings.name = "" @@ -70,7 +72,6 @@ Settings.color = nil ---Maximum amount of items that can be in a single stack. ---The default can be changed by the setting `default_stack_max`. ----TODO: сделать другой стак по умолчанию? ---@type number? Settings.stack_max = nil diff --git a/mods/CORE/ItemFactory/src/ItemFactory.lua b/mods/CORE/ItemFactory/src/ItemFactory.lua index 6c7d7c8..56a4f53 100644 --- a/mods/CORE/ItemFactory/src/ItemFactory.lua +++ b/mods/CORE/ItemFactory/src/ItemFactory.lua @@ -1,11 +1,11 @@ ---@class ItemFactory ----@field defaultDef Item.ItemDefinition | Node.NodeDefinition ----@field itemClass Item | Node +---@field defaultDef Item.ItemDefinition|Node.NodeDefinition +---@field itemClass Item|Node local ItemFactory = {} ----@param itemClass Item | Node ----@param defaultDef Item.ItemDefinition | Node.NodeDefinition Parameters that all nodes registered with this ItemFactory must have. ----@return ItemFactory +---@param itemClass Item|Node +---@param defaultDef Item.ItemDefinition|Node.NodeDefinition Parameters that all nodes registered with this ItemFactory must have. +---@return ItemFactory function ItemFactory:new(itemClass, defaultDef) ---@type ItemFactory local instance = setmetatable({ @@ -22,7 +22,7 @@ local defMerge = function(...) return table.merge(...) end ----@param itemDefs Item.ItemDefinition[] | Node.NodeDefinition[] List of nodes with parameters unique to them. +---@param itemDefs Item.ItemDefinition[]|Node.NodeDefinition[] List of nodes with parameters unique to them. ---@param addModName boolean Whether to add the mod name to the settings.name. Default: `true` function ItemFactory:registerItems(itemDefs, addModName) if addModName == nil then @@ -50,7 +50,6 @@ local defMerge = function(...) return table.merge(...) end - ---@param shortNodeDefs table Table of the form `{ {name, title, description, tiles}, {name, title, description, tiles}, ...}` ---@param addModName boolean? Whether to add the mod name to the settings.name. Default: `true` function ItemFactory:registerNodesByShortDef(shortNodeDefs, addModName) @@ -70,6 +69,7 @@ function ItemFactory:registerNodesByShortDef(shortNodeDefs, addModName) tiles = shortNodeDef[4] } } + nodeDef = defMerge(nodeDef, self.defaultDef, true) if addModName then diff --git a/mods/CORE/MapGen/src/MapGen.lua b/mods/CORE/MapGen/src/MapGen.lua index e3966eb..dce7d8d 100644 --- a/mods/CORE/MapGen/src/MapGen.lua +++ b/mods/CORE/MapGen/src/MapGen.lua @@ -31,23 +31,24 @@ local Region = require("MapGen.Region") ---@field isRunning boolean A static field that guarantees that only one instance of the `MapGen` class will work. ---@field nodeIDs table local MapGen = { + layersByName = {}, + layersList = {}, multinoiseInitialized = false, - isRunning = false, + isRunning = false, } ---@param nodeIDs table ---@return MapGen function MapGen:new(nodeIDs) + ---@type MapGen local instance = setmetatable({ - layersByName = {}, - layersList = {}, - nodeIDs = nodeIDs, - --registeredRegions = {}, + nodeIDs = nodeIDs, }, {__index = self}) return instance end +---Determines which layer a node belongs to based on its height coordinate. ---@param yPos number ---@return MapGen.Layer? function MapGen:getLayerByHeight(yPos) @@ -66,6 +67,9 @@ function MapGen:getLayerByHeight(yPos) end end +---Mark the world area between two heights as a `MapGen.Layer`. +--- +---Note: layers must not overlap. ---@param name string ---@param minY number ---@param maxY number @@ -87,12 +91,15 @@ function MapGen:RegisterLayer(name, minY, maxY) end) end ----@param layerName string ----@param minPos table ----@param maxPos table ----@param multinoise table ----@param regionIs2D boolean? ----@param weightFactor number? +---Mark a region of the world as a cubic region by two opposite vertices. +--- +---Regions must be included in layers and may overlap each other. +---@param layerName string The name of the layer in which the new region will be included. +---@param minPos vector +---@param maxPos vector +---@param multinoise table Noise that will be assigned to the region and that will influence map generation +---@param regionIs2D boolean? If true, the transmitted Y coordinate will be overwritten by the layer boundaries. +---@param weightFactor number? The coefficient by which the reduction in the impact of regional noise on generation will be calculated. If 0, there will be no reduction. function MapGen:RegisterRegion(layerName, minPos, maxPos, multinoise, regionIs2D, weightFactor) ---@type MapGen.Layer local layer = self.layersByName[layerName] @@ -106,6 +113,8 @@ function MapGen:RegisterRegion(layerName, minPos, maxPos, multinoise, regionIs2D maxPos.y = layer.maxY end + --TODO: Добавить проверку, что регион не выходит за границы слоя или/и автоматически обрубать регион до слоя + if weightFactor == nil then weightFactor = 1 end @@ -131,9 +140,18 @@ function MapGen:initRegionsMultinoise() self.multinoiseInitialized = true end - ----@return number -local function calculateWeight(minPos, maxPos, x, z, weightFactor) +---Calculate the weight for noise based on +---the distance of the point from the center of the region. +--- +---If the `weightFactor` is `0`, then the region's +---weight is not calculated and is always equal to `1`. +---@param minPos vector +---@param maxPos vector +---@param x number +---@param z number +---@param weightFactor number +---@return number +local function calculateWeight2D(minPos, maxPos, x, z, weightFactor) if weightFactor == 0 then return 1 end @@ -187,7 +205,7 @@ local function generatorHandler(mapGenerator, data, index, x, y, z) local noise = region:getMultinoise().landscapeNoise -- The further a point is from the center of a region, the less noise affects it. - local weight = calculateWeight(region:getMinPos(), region:getMaxPos(), x, z, region.getWeightFactor()) + local weight = calculateWeight2D(region:getMinPos(), region:getMaxPos(), x, z, region.getWeightFactor()) noiseHeightValue = noiseHeightValue + ( noise:get_2d({x = x, y = z}) * weight ) end @@ -232,9 +250,12 @@ function MapGen:onMapGenerated(minPos, maxPos, blockseed) voxelManip:write_to_map() end +---Run world generation through this mapgen object +--- +---Note: only one instance of a `MapGen` class can be running. function MapGen:run() if MapGen.isRunning then - error('Only one instance of a `MapGen` class can be used.') + error('Only one instance of a `MapGen` class can be running.') end core.register_on_generated(function(...) diff --git a/mods/CORE/MapGen/src/MapGen/Layer.lua b/mods/CORE/MapGen/src/MapGen/Layer.lua index 2a9a745..720d433 100644 --- a/mods/CORE/MapGen/src/MapGen/Layer.lua +++ b/mods/CORE/MapGen/src/MapGen/Layer.lua @@ -2,7 +2,7 @@ ---@field name string ---@field minY number ---@field maxY number ----@field regionsList table +---@field regionsList table local Layer = { regionsList = {} } @@ -30,12 +30,14 @@ end ---@param xPos number ---@param yPos number ---@param zPos number ----@return table +---@return MapGen.Region[] function Layer:getRegionsByPos(xPos, yPos, zPos) - --- TODO: возможно здесь получится сделать более оптимизированный алгоритм - --- учитывая тот факт, что эта функция вызывается для каждой ноды в on_generated - --- и может быть даже не один раз - --- Можно подумать над тем, чтобы использовать сортированный список + -- TODO: возможно здесь получится сделать более оптимизированный алгоритм + -- учитывая тот факт, что эта функция вызывается для каждой ноды в on_generated + -- и может быть даже не один раз + -- Можно подумать над тем, чтобы использовать сортированный список + + ---@type MapGen.Region[] local regions = {} ---@param region MapGen.Region diff --git a/mods/CORE/MapGen/src/MapGen/Region.lua b/mods/CORE/MapGen/src/MapGen/Region.lua index 95a1328..c9b127d 100644 --- a/mods/CORE/MapGen/src/MapGen/Region.lua +++ b/mods/CORE/MapGen/src/MapGen/Region.lua @@ -1,8 +1,13 @@ --- TODO: replace `table` with `vector` for minPos and maxPos ---@class MapGen.Region +---@field getMinPos fun():vector +---@field getMaxPos fun():vector +---@field getMultinoiseParams fun():MapGen.Region.MultinoiseParams +---@field getMultinoise fun():MapGen.Region.Multinoise +---@field initMultinoise fun() +---@field getWeightFactor fun():number local Region = {} ----@param multinoiseParams MapGen.Region.MultinoiseParams -- ??? TODO: should be it's own class in EmmyLua +---@param multinoiseParams MapGen.Region.MultinoiseParams ---@return MapGen.Region.Multinoise local function multinoiseParamsToMultinoise(multinoiseParams) ---@type MapGen.Region.Multinoise @@ -15,37 +20,43 @@ local function multinoiseParamsToMultinoise(multinoiseParams) return multinoise end ----@param minPos table ----@param maxPos table +---@param minPos vector +---@param maxPos vector ---@param multinoiseParams MapGen.Region.MultinoiseParams ---@param weightFactor number ---@return MapGen.Region function Region:new(minPos, maxPos, multinoiseParams, weightFactor) + ---@type vector local _minPos = minPos + ---@type vector local _maxPos = maxPos + ---@type MapGen.Region.MultinoiseParams local _multinoiseParams = multinoiseParams if weightFactor < 0 then weightFactor = 1 end + ---@type MapGen.Region.Multinoise local _multinoise = {} + ---@type MapGen.Region local instance = setmetatable({}, {__index = self}) - ---@return {x:number, y:number, z:number} function instance:getMinPos() return _minPos end + + ---@return vector function instance:getMaxPos() return _maxPos end + function instance:getMultinoiseParams() return _multinoiseParams end - ---@return MapGen.Region.Multinoise function instance:getMultinoise() return _multinoise end diff --git a/mods/CORE/MapGen/src/MapGen/Region/MultinoiseParams.lua b/mods/CORE/MapGen/src/MapGen/Region/MultinoiseParams.lua index ba085d9..87042e5 100644 --- a/mods/CORE/MapGen/src/MapGen/Region/MultinoiseParams.lua +++ b/mods/CORE/MapGen/src/MapGen/Region/MultinoiseParams.lua @@ -1,9 +1,10 @@ ---For EmmyLua only + -- TODO: Когда в хелпер добавятся аннотации шумов, надо будет удалить этот класс и заменить его на хелперский ---@class MapGen.Region.NoiseParams ---@field offset number ---@field scale number ----@field spread vector -- TODO: describe vector class from Luanti (push Alek) +---@field spread vector ---@field seed number ---@field octaves number ---@field persistence number diff --git a/mods/CORE/Node/src/Node.lua b/mods/CORE/Node/src/Node.lua index 738c7cd..a066b46 100644 --- a/mods/CORE/Node/src/Node.lua +++ b/mods/CORE/Node/src/Node.lua @@ -6,7 +6,7 @@ local VisualEnum = Core.Item.require('Item.VisualEnum') local Node = Core.Item:getModClassExtended({}) ---@param nodeDef Node.NodeDefinition ----@return Node +---@return Node function Node:new(nodeDef) nodeDef.settings.visual = VisualEnum.ITEM_3D @@ -20,7 +20,7 @@ end ---default parameters that will be added to the node's parameters ---when an instance is received. ---@param defaultDef Node.NodeDefinition ----@return Node +---@return Node function Node:getExtended(defaultDef) ---@type Node local ChildClass = Mod:getClassExtended(self, { @@ -32,7 +32,7 @@ end ---Returns an instance of the `ItemFactory` class that can be used to mass-register identical items. ---@param defaultDef? Node.NodeDefinition ----@return ItemFactory +---@return ItemFactory function Node:getFactory(defaultDef) if defaultDef == nil then defaultDef = self.defaultDef diff --git a/mods/CORE/Node/src/Node/Callbacks.lua b/mods/CORE/Node/src/Node/Callbacks.lua index 00c4bd1..28068b3 100644 --- a/mods/CORE/Node/src/Node/Callbacks.lua +++ b/mods/CORE/Node/src/Node/Callbacks.lua @@ -1,6 +1,8 @@ ---@type Item.Callbacks local ItemCallbacks = Core.Item.require('Item.Callbacks') +-- TODO: Разобраться с дубликатами аннотаций полей. Приоритетно брать аннотации из util/ide-helper + ---@class Node.Callbacks : Item.Callbacks local Callbacks = Mod:getClassExtended(ItemCallbacks, {}) diff --git a/mods/CORE/Node/src/Node/Settings.lua b/mods/CORE/Node/src/Node/Settings.lua index 454e5ae..6f9f84d 100644 --- a/mods/CORE/Node/src/Node/Settings.lua +++ b/mods/CORE/Node/src/Node/Settings.lua @@ -1,6 +1,8 @@ ---@type Item.Settings local ItemSettings = Core.Item.require('Item.Settings') +-- TODO: Разобраться с дубликатами аннотаций полей. Приоритетно брать аннотации из util/ide-helper + ---@class Node.Settings : Item.Settings local Settings = Mod:getClassExtended(ItemSettings, {}) diff --git a/mods/CORE/TileSheet/src/TileSheet.lua b/mods/CORE/TileSheet/src/TileSheet.lua index 9a3f50e..a362aa3 100644 --- a/mods/CORE/TileSheet/src/TileSheet.lua +++ b/mods/CORE/TileSheet/src/TileSheet.lua @@ -1,20 +1,23 @@ ---@class TileSheet ---@field image string Name of texture ---@field width number Number of tiles in the table horizontally ----@field height number Number of tiles in the table vertically +---@field height number Number of tiles in the table vertically local TileSheet = {} ---@param image string Name of texture ---@param width number Number of tiles in the table horizontally ----@param height number Number of tiles in the table vertically +---@param height number Number of tiles in the table vertically ---@return TileSheet function TileSheet:new(image, width, height) + ---@type TileSheet local instance = setmetatable({ image = image, width = width, height = height, }, {__index = self}) + -- TODO возможно будет лучше сделать автоматическое определение высоты и ширины по разрешению текстуры + return instance end @@ -28,7 +31,7 @@ function TileSheet:getTextureName(x, y) return textureName end ----Aleas for `TileSheet:getTextureName`. +---Alias for `TileSheet:getTextureName`. ---@param x number ---@param y number ---@return string