From 2bda4febb94c4e40775eb9b13d84907383ca90e4 Mon Sep 17 00:00:00 2001 From: mrkubax10 Date: Wed, 22 Mar 2023 18:52:21 +0100 Subject: [PATCH] Document api functions --- api.lua | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/api.lua b/api.lua index 61de155..0bb21f1 100644 --- a/api.lua +++ b/api.lua @@ -36,6 +36,9 @@ industrialtest.api.addPowerStorage=function(meta,capacity,flow,ioConfig) meta:set_int("industrialtest.powerAmount",0) meta:set_string("industrialtest.ioConfig",ioConfig) end +-- \brief Checks if metadata contains power storage +-- \param meta MetaDataRef which should be checked +-- \returns true if metadata contains power storage, false otherwise industrialtest.api.hasPowerStorage=function(meta) local values={"industrialtest.powerCapacity","industrialtest.powerFlow","industrialtest.powerAmount","industrialtest.ioConfig"} for _,value in ipairs(values) do @@ -45,12 +48,19 @@ industrialtest.api.hasPowerStorage=function(meta) end return true end +-- \brief Updates itemstack description to show current power storage information, additionally updates item wear bar. +-- Function doesn't check if itemstack contains power storage so you should be sure that it does before calling this function +-- \param itemstack ItemStack which should be updated +-- \returns nil industrialtest.api.updateItemPowerText=function(itemstack) local meta=itemstack:get_meta() local def=minetest.registered_tools[itemstack:get_name()] meta:set_string("description",S("@1\n@2 / @3 EU",def.description,meta:get_int("industrialtest.powerAmount"),meta:get_int("industrialtest.powerCapacity"))) itemstack:set_wear(65535-meta:get_int("industrialtest.powerAmount")/meta:get_int("industrialtest.powerCapacity")*65534) end +-- \brief Adds power storage to item depending on it's definition +-- \param itemstack ItemStack to which item storage should be added +-- \returns true if power storage was successfully added, false otherwise industrialtest.api.preparePowerStorageItem=function(itemstack) local meta=itemstack:get_meta() local def=minetest.registered_tools[itemstack:get_name()] @@ -61,6 +71,9 @@ industrialtest.api.preparePowerStorageItem=function(itemstack) industrialtest.api.updateItemPowerText(itemstack) return true end +-- \brief Sets uses metadata value depending on item's definition +-- \param itemstack ItemStack which should be altered +-- \returns true if value was successfully added, false otherwise industrialtest.api.prepareToolItem=function(itemstack) local def=minetest.registered_tools[itemstack:get_name()] if not def or not def._industrialtest_tool or not def.tool_capabilities or not def.tool_capabilities.uses then @@ -70,6 +83,9 @@ industrialtest.api.prepareToolItem=function(itemstack) meta:set_int("industrialtest.uses",def.tool_capabilities.uses) return true end +-- \brief Adds wear to item after it's use +-- \param itemstack ItemStack to which wear should be added +-- \returns nil industrialtest.api.afterToolUse=function(itemstack) local meta=itemstack:get_meta() local def=minetest.registered_tools[itemstack:get_name()] @@ -92,9 +108,16 @@ industrialtest.api.afterToolUse=function(itemstack) meta:set_int("industrialtest.uses",uses) itemstack:set_wear(65535-uses/def.tool_capabilities.uses*65535) end +-- \brief Checks if power storage is fully charged +-- \param meta MetaDataRef which should be checked +-- \returns true if power storage is fully charged, false otherwise industrialtest.api.isFullyCharged=function(meta) return meta:get_int("industrialtest.powerAmount")>=meta:get_int("industrialtest.powerCapacity") end +-- \brief Adds power to power storage. Function doesn't check if meta contains power storage so you must be sure that it does. +-- \param meta MetaDataRef to which power should be added +-- \param amount Amount of power to add +-- \returns How much of power was actually added industrialtest.api.addPower=function(meta,amount) local powerAmount=meta:get_int("industrialtest.powerAmount") local powerCapacity=meta:get_int("industrialtest.powerCapacity") @@ -103,6 +126,10 @@ industrialtest.api.addPower=function(meta,amount) meta:set_int("industrialtest.powerAmount",powerAmount) return powerAmount-prevPowerAmount end +-- \brief Adds power to itemstack. Function checks if itemstack has power storage. +-- \param itemstack ItemStack to which add power +-- \param amount How much power to add +-- \returns Amount of power added industrialtest.api.addPowerToItem=function(itemstack,amount) local meta=itemstack:get_meta() if not industrialtest.api.hasPowerStorage(meta) then @@ -112,6 +139,10 @@ industrialtest.api.addPowerToItem=function(itemstack,amount) industrialtest.api.updateItemPowerText(itemstack) return added end +-- \brief Adds power to destination metadata while subtracting it from source metadata +-- \Param srcMeta MetaDataRef from which take power +-- \param destMeta MetaDataRef to which add power +-- \returns How much of power was actually transferred industrialtest.api.transferPower=function(srcMeta,destMeta,amount) local currentFlow=math.min(srcMeta:get_int("industrialtest.powerAmount"),amount) if currentFlow==0 then @@ -121,6 +152,10 @@ industrialtest.api.transferPower=function(srcMeta,destMeta,amount) srcMeta:set_int("industrialtest.powerAmount",srcMeta:get_int("industrialtest.powerAmount")-actualFlow) return actualFlow end +-- \brief Adds power to destination itemstack while subtracting it from source metadata +-- \param srcMeta MetaDataRef from which take power +-- \param itemstack ItemStack to which add power +-- \returns How much of power was actually transferred industrialtest.api.transferPowerToItem=function(srcMeta,itemstack,amount) local currentFlow=math.min(srcMeta:get_int("industrialtest.powerAmount"),amount) if currentFlow==0 then @@ -130,6 +165,10 @@ industrialtest.api.transferPowerToItem=function(srcMeta,itemstack,amount) srcMeta:set_int("industrialtest.powerAmount",srcMeta:get_int("industrialtest.powerAmount")-actualFlow) return actualFlow end +-- \brief Transfers power from source node to all neighbouring nodes +-- \param pos Vector with position of source node +-- \returns two values: true if any neighbouring node has room for more power, false otherwise +-- true if any power was transferred, false otherwise industrialtest.api.powerFlow=function(pos) local meta=minetest.get_meta(pos) if not industrialtest.api.hasPowerStorage(meta) then @@ -189,6 +228,9 @@ industrialtest.api.powerFlow=function(pos) end return roomAvailable,transferred end +-- \brief Starts node timer of neighbouring nodes with center node +-- \param pos Vector with position of center node +-- \returns nil industrialtest.api.triggerNeighbours=function(pos) local neighbourPositions={ vector.offset(pos,-1,0,0), @@ -206,9 +248,15 @@ industrialtest.api.triggerNeighbours=function(pos) end end end +-- \brief Returns opposite side of provided one +-- \param side Side number. See industrialtest.api.addPowerStorage for order +-- \returns Opposite side industrialtest.api.getOppositeSide=function(side) return (side%2==0 and side-1 or side+1) end +-- \brief Returns connections of node with power storage +-- \param pos Vector with position of node with power storage +-- \returns Table with side numbers industrialtest.api.getConnections=function(pos) local result={} local neighbourPositions={ @@ -229,21 +277,42 @@ industrialtest.api.getConnections=function(pos) end return result end +-- \brief Changes node's power IO config. Function doesn't check if meta actually contains power storage. +-- \param meta MetaDataRef of node which power IO config should be changed +-- \param side Side number. See industrialtest.api.addPowerStorage to check order. +-- \param mode Side mode. See industrialtest.api.addPowerStorage for possible values. +-- \returns nil industrialtest.api.changeIoConfig=function(meta,side,mode) local ioConfig=meta:get_string("industrialtest.ioConfig") ioConfig=string.sub(ioConfig,1,side-1)..mode..string.sub(ioConfig,side+1) meta:set_string("industrialtest.ioConfig",ioConfig) end +-- \brief Checks if provided side is power input +-- \param meta MetaDataRef of node +-- \param side Side number. See industrialtest.api.addPowerStorage to check order. +-- \returns true if provided side is power input, false otherwise industrialtest.api.isPowerInput=function(meta,side) local ioConfig=meta:get_string("industrialtest.ioConfig") local mode=string.sub(ioConfig,side,side) return (mode=="i" or mode=="a") end +-- \brief Checks if provided side is power output +-- \param meta MetaDataRef of node +-- \param side Side number. See industrialtest.api.addPowerStorage to check order. +-- \returns true if provided side is power output, false otherwise industrialtest.api.isPowerOutput=function(meta,side) local ioConfig=meta:get_string("industrialtest.ioConfig") local mode=string.sub(ioConfig,side,side) return (mode=="o" or mode=="a") end +-- \brief Registers dust of certain resource +-- \param name Technical name of resource +-- \param displayName Display name of resource +-- \param resources List of tables with following keys: , , [count(1)] +-- <> - required, [] - optional, () - default value +-- \param color HTML color of dust +-- \param registerMaceratorRecipe If true macerator recipe for dust will be registered +-- \returns nil industrialtest.api.registerResourceDust=function(name,displayName,resources,color,registerMaceratorRecipe) minetest.register_craftitem("industrialtest:"..name.."_dust",{ description=S(displayName.." Dust"), @@ -259,6 +328,9 @@ industrialtest.api.registerResourceDust=function(name,displayName,resources,colo end end end +-- \brief Registers macerator recipe +-- \param config Table with keys: , , [time(2)] +-- \returns nil industrialtest.api.registerMaceratorRecipe=function(config) local definition={ output=config.output or "", @@ -267,9 +339,15 @@ industrialtest.api.registerMaceratorRecipe=function(config) } industrialtest.api.maceratorRecipes[definition.recipe]=definition end +-- \brief Returns macerator recipe result +-- \param recipe String ID of resulting conten +-- \returns Table with following keys: output, recipe, time industrialtest.api.getMaceratorRecipeResult=function(recipe) return industrialtest.api.maceratorRecipes[recipe] end +-- \brief Registers compressor recipe +-- \param config Table with following keys: , , [time(2)], [count(1)] +-- \returns nil industrialtest.api.registerCompressorRecipe=function(config) local definition={ output=config.output or "", @@ -279,6 +357,9 @@ industrialtest.api.registerCompressorRecipe=function(config) } industrialtest.api.compressorRecipes[definition.recipe]=definition end +-- \brief Returns macerator recipe result +-- \param recipe String ID of resulting conten +-- \returns Table with following keys: output, recipe, time industrialtest.api.getCompressorRecipeResult=function(recipe) return industrialtest.api.compressorRecipes[recipe] end