From bd400593b32870ed3d0837e0a4a23061ebebc215 Mon Sep 17 00:00:00 2001
From: xelivous <mail@xelivo.us>
Date: Tue, 31 Mar 2015 19:06:26 -0500
Subject: [PATCH] Add documentation comments to various lua engine classes
---
game/engines/default/engine/Actor.lua | 116 +++++--
.../default/engine/ActorsSeenDisplay.lua | 17 ++
game/engines/default/engine/Astar.lua | 45 ++-
game/engines/default/engine/Autolevel.lua | 10 +-
game/engines/default/engine/BSP.lua | 11 +-
game/engines/default/engine/Birther.lua | 55 +++-
game/engines/default/engine/Calendar.lua | 36 ++-
.../default/engine/CharacterBallSave.lua | 16 +-
.../default/engine/CharacterVaultSave.lua | 11 +
game/engines/default/engine/Chat.lua | 18 +-
game/engines/default/engine/DamageType.lua | 31 +-
game/engines/default/engine/DebugConsole.lua | 36 ++-
game/engines/default/engine/Dialog.lua | 76 ++++-
game/engines/default/engine/DirectPath.lua | 8 +-
game/engines/default/engine/Emote.lua | 10 +
game/engines/default/engine/Entity.lua | 171 ++++++++---
game/engines/default/engine/Faction.lua | 49 +--
game/engines/default/engine/FlyingText.lua | 21 ++
game/engines/default/engine/FontPackage.lua | 30 +-
game/engines/default/engine/Game.lua | 104 +++++--
.../default/engine/GameEnergyBased.lua | 16 +-
game/engines/default/engine/GameTurnBased.lua | 13 +-
game/engines/default/engine/Generator.lua | 38 +++
game/engines/default/engine/Grid.lua | 2 +
game/engines/default/engine/Heightmap.lua | 10 +-
game/engines/default/engine/HighScores.lua | 34 ++-
.../engines/default/engine/HotkeysDisplay.lua | 27 +-
.../default/engine/HotkeysIconsDisplay.lua | 29 +-
game/engines/default/engine/Key.lua | 288 +++++++++++++++++-
game/engines/default/engine/KeyBind.lua | 11 +-
game/engines/default/engine/KeyCommand.lua | 2 +
game/engines/default/engine/Level.lua | 4 +-
game/engines/default/engine/LogDisplay.lua | 1 +
game/engines/default/engine/LogFlasher.lua | 1 +
game/engines/default/engine/Map.lua | 7 +-
game/engines/default/engine/MapEffect.lua | 1 +
game/engines/default/engine/Module.lua | 3 +
game/engines/default/engine/Mouse.lua | 16 +-
game/engines/default/engine/NameGenerator.lua | 45 +--
.../engines/default/engine/NameGenerator2.lua | 2 +
game/engines/default/engine/Object.lua | 10 +-
game/engines/default/engine/Particles.lua | 1 +
game/engines/default/engine/PlayerProfile.lua | 8 +-
game/engines/default/engine/Projectile.lua | 3 +-
game/engines/default/engine/Quadratic.lua | 1 +
game/engines/default/engine/Quest.lua | 10 +-
game/engines/default/engine/Savefile.lua | 138 ++++++++-
game/engines/default/engine/SavefilePipe.lua | 1 +
game/engines/default/engine/Shader.lua | 1 +
game/engines/default/engine/Store.lua | 4 +
game/engines/default/engine/Target.lua | 6 +-
game/engines/default/engine/Tiles.lua | 1 +
game/engines/default/engine/Tooltip.lua | 2 +
game/engines/default/engine/Trap.lua | 1 +
game/engines/default/engine/UserChat.lua | 1 +
game/engines/default/engine/World.lua | 1 +
game/engines/default/engine/Zone.lua | 14 +-
game/engines/default/engine/ai/simple.lua | 3 +-
.../default/engine/ai/special_movements.lua | 3 +-
game/engines/default/engine/ai/talented.lua | 3 +-
game/engines/default/engine/class.lua | 10 +-
game/engines/default/engine/colors.lua | 44 +++
.../default/engine/dialogs/Achievement.lua | 4 +
.../default/engine/dialogs/AudioOptions.lua | 2 +
game/engines/default/engine/dialogs/Chat.lua | 2 +
.../default/engine/dialogs/ChatChannels.lua | 2 +
.../default/engine/dialogs/ChatFilter.lua | 2 +
.../default/engine/dialogs/ChatIgnores.lua | 2 +
.../engine/dialogs/DisplayResolution.lua | 2 +
.../default/engine/dialogs/Downloader.lua | 1 +
.../default/engine/dialogs/GameMenu.lua | 2 +
.../default/engine/dialogs/GetQuantity.lua | 2 +
.../default/engine/dialogs/GetText.lua | 2 +
.../default/engine/dialogs/KeyBinder.lua | 2 +
.../engine/dialogs/ShowAchievements.lua | 4 +
.../default/engine/dialogs/ShowEquipInven.lua | 2 +
.../default/engine/dialogs/ShowEquipment.lua | 2 +
.../default/engine/dialogs/ShowErrorStack.lua | 2 +
.../default/engine/dialogs/ShowInventory.lua | 2 +
.../default/engine/dialogs/ShowLog.lua | 2 +
.../engine/dialogs/ShowPickupFloor.lua | 2 +
.../default/engine/dialogs/ShowQuests.lua | 2 +
.../default/engine/dialogs/ShowStore.lua | 2 +
.../default/engine/dialogs/ShowText.lua | 2 +
.../default/engine/dialogs/SteamOptions.lua | 2 +
.../default/engine/dialogs/Talkbox.lua | 2 +
.../default/engine/dialogs/UseTalents.lua | 2 +
.../default/engine/dialogs/UserInfo.lua | 2 +
.../default/engine/dialogs/VideoOptions.lua | 2 +
.../default/engine/dialogs/ViewHighScores.lua | 2 +
.../engine/generator/actor/OnSpots.lua | 2 +
.../default/engine/generator/actor/Random.lua | 2 +
.../default/engine/generator/map/Building.lua | 2 +
.../default/engine/generator/map/Cavern.lua | 2 +
.../engine/generator/map/CavernousTunnel.lua | 2 +
.../default/engine/generator/map/Empty.lua | 2 +
.../default/engine/generator/map/Filled.lua | 2 +
.../default/engine/generator/map/Forest.lua | 2 +
.../default/engine/generator/map/GOL.lua | 2 +
.../engine/generator/map/Heightmap.lua | 2 +
.../default/engine/generator/map/Maze.lua | 2 +
.../default/engine/generator/map/Octopus.lua | 2 +
.../default/engine/generator/map/Roomer.lua | 2 +
.../default/engine/generator/map/Rooms.lua | 1 +
.../engine/generator/map/RoomsLoader.lua | 1 +
.../default/engine/generator/map/Static.lua | 2 +
.../default/engine/generator/map/TileSet.lua | 2 +
.../default/engine/generator/map/Town.lua | 2 +
.../engine/generator/object/OnSpots.lua | 2 +
.../engine/generator/object/Random.lua | 2 +
.../default/engine/generator/trap/Random.lua | 2 +
game/engines/default/engine/init.lua | 4 +-
.../default/engine/interface/ActorAI.lua | 4 +-
.../default/engine/interface/ActorFOV.lua | 1 +
.../engine/interface/ActorInventory.lua | 111 ++++---
.../default/engine/interface/ActorLevel.lua | 4 +-
.../default/engine/interface/ActorLife.lua | 15 +-
.../default/engine/interface/ActorProject.lua | 29 +-
.../default/engine/interface/ActorQuest.lua | 1 +
.../engine/interface/ActorResource.lua | 1 +
.../default/engine/interface/ActorStats.lua | 1 +
.../default/engine/interface/ActorTalents.lua | 47 ++-
.../interface/ActorTemporaryEffects.lua | 13 +-
.../default/engine/interface/BloodyDeath.lua | 1 +
.../engine/interface/ControlCursorSupport.lua | 1 +
.../default/engine/interface/GameMusic.lua | 1 +
.../default/engine/interface/GameSound.lua | 1 +
.../engine/interface/GameTargeting.lua | 1 +
.../engine/interface/ObjectActivable.lua | 1 +
.../engine/interface/ObjectIdentify.lua | 1 +
.../engine/interface/PlayerDumpJSON.lua | 1 +
.../engine/interface/PlayerExplore.lua | 10 +-
.../engine/interface/PlayerHotkeys.lua | 1 +
.../default/engine/interface/PlayerMouse.lua | 8 +
.../default/engine/interface/PlayerRest.lua | 15 +-
.../default/engine/interface/PlayerRun.lua | 22 +-
.../default/engine/interface/PlayerSlide.lua | 1 +
.../engine/interface/WorldAchievements.lua | 1 +
game/engines/default/engine/resolvers.lua | 2 +
game/engines/default/engine/ui/ActorFrame.lua | 2 +
game/engines/default/engine/ui/Base.lua | 1 +
game/engines/default/engine/ui/Button.lua | 1 +
.../engines/default/engine/ui/ButtonImage.lua | 3 +-
game/engines/default/engine/ui/Checkbox.lua | 3 +-
game/engines/default/engine/ui/Dialog.lua | 3 +-
game/engines/default/engine/ui/Dropdown.lua | 1 +
game/engines/default/engine/ui/Empty.lua | 1 +
game/engines/default/engine/ui/EquipDoll.lua | 2 +
.../default/engine/ui/EquipDollFrame.lua | 2 +
game/engines/default/engine/ui/Focusable.lua | 1 +
.../default/engine/ui/GenericContainer.lua | 3 +-
game/engines/default/engine/ui/Gestures.lua | 1 +
game/engines/default/engine/ui/Image.lua | 1 +
game/engines/default/engine/ui/ImageList.lua | 1 +
game/engines/default/engine/ui/Inventory.lua | 1 +
game/engines/default/engine/ui/List.lua | 1 +
.../engines/default/engine/ui/ListColumns.lua | 1 +
game/engines/default/engine/ui/Numberbox.lua | 3 +-
game/engines/default/engine/ui/Separator.lua | 3 +-
game/engines/default/engine/ui/Slider.lua | 1 +
game/engines/default/engine/ui/SubDialog.lua | 1 +
.../engines/default/engine/ui/SurfaceZone.lua | 3 +-
game/engines/default/engine/ui/Tab.lua | 3 +-
game/engines/default/engine/ui/Tabs.lua | 1 +
game/engines/default/engine/ui/Textbox.lua | 1 +
game/engines/default/engine/ui/Textzone.lua | 3 +-
.../default/engine/ui/TextzoneList.lua | 3 +-
game/engines/default/engine/ui/TreeList.lua | 3 +-
.../engines/default/engine/ui/UIContainer.lua | 3 +-
game/engines/default/engine/ui/UIGroup.lua | 3 +-
.../default/engine/ui/VariableList.lua | 3 +-
game/engines/default/engine/ui/Waitbar.lua | 1 +
game/engines/default/engine/ui/Waiter.lua | 3 +-
game/engines/default/engine/ui/WebView.lua | 1 +
game/engines/default/engine/utils.lua | 14 +-
game/engines/default/engine/version.lua | 38 ++-
game/engines/default/engine/webcore.lua | 2 +
177 files changed, 1827 insertions(+), 380 deletions(-)
diff --git a/game/engines/default/engine/Actor.lua b/game/engines/default/engine/Actor.lua
index a7e1664f33..40b06fc0cb 100644
--- a/game/engines/default/engine/Actor.lua
+++ b/game/engines/default/engine/Actor.lua
@@ -22,14 +22,22 @@ local Entity = require "engine.Entity"
local Map = require "engine.Map"
local Faction = require "engine.Faction"
+--- Base Actor class used by NPCs, Players, Enemies, etc
+-- @classmod engine.Actor
module(..., package.seeall, class.inherit(Entity))
+--- Display actor when seen
_M.display_on_seen = true
+--- Remember actor after seeing it
_M.display_on_remember = false
+--- Display actor when it hasn't yet been seen
_M.display_on_unknown = false
-- Allow actors to act as object carriers, if the interface is loaded
_M.__allow_carrier = true
+--- Instantiates an actor
+-- @param[type=table] t default values for actor
+-- @param[type=table] no_default override the default values for entities
function _M:init(t, no_default)
t = t or {}
@@ -46,22 +54,25 @@ function _M:init(t, no_default)
end
--- Called when it is time to act
+-- @return true if alive
function _M:act()
if self.dead then return false end
return true
end
--- Gets the actor target
--- Does nothing, AI redefines it so should a "Player" class
+-- Does nothing, AI redefines it, so should a "Player" class
function _M:getTarget()
end
--- Sets the actor target
--- Does nothing, AI redefines it so should a "Player" class
+-- Does nothing, AI redefines it, so should a "Player" class
function _M:setTarget(target)
end
--- Setup minimap color for this entity
-- You may overload this method to customize your minimap
+-- @param mo
+-- @param[type=Map] map
function _M:setupMinimapInfo(mo, map)
if map.actor_player and not map.actor_player:canSee(self) then return end
local r = map.actor_player and map.actor_player:reactionToward(self) or -100
@@ -72,6 +83,7 @@ function _M:setupMinimapInfo(mo, map)
end
--- Set the current emote
+-- @param[type=Emote] e
function _M:setEmote(e)
-- Remove previous
if self.__emote then
@@ -176,10 +188,9 @@ end
--- Moves an actor on the map
-- *WARNING*: changing x and y properties manually is *WRONG* and will blow up in your face. Use this method. Always.
--- @param map the map to move onto
--- @param x coord of the destination
--- @param y coord of the destination
--- @param force if true do not check for the presence of an other entity. *Use wisely*
+-- @int x coord of the destination
+-- @int y coord of the destination
+-- @param[type=boolean] force if true do not check for the presence of an other entity. *Use wisely*
-- @return true if a move was *ATTEMPTED*. This means the actor will probably want to use energy
function _M:move(x, y, force)
if not x or not y then return end
@@ -221,7 +232,10 @@ function _M:move(x, y, force)
return true
end
---- Moves into the given direction (calls actor:move() internally)
+--- Moves into the given direction (calls `Actor:move`() internally)
+-- @number dir direction to move
+-- @number force amount to move
+-- @return true if we attempted to move
function _M:moveDir(dir, force)
local dx, dy = util.dirToCoord(dir, self.x, self.y)
if dir ~= 5 then self.doPlayerSlide = config.settings.player_slide end
@@ -247,7 +261,10 @@ function _M:moveDir(dir, force)
end
--- Can the actor go there
--- @param terrain_only if true checks only the terrain, otherwise checks all entities
+-- @int x x coordinate
+-- @int y y coordinate
+-- @param[type=?boolean] terrain_only if true checks only the terrain, otherwise checks all entities
+-- @return true if it can
function _M:canMove(x, y, terrain_only)
if not game.level.map:isBound(x, y) then return false end
if terrain_only then
@@ -258,6 +275,7 @@ function _M:canMove(x, y, terrain_only)
end
--- Remove the actor from the level, marking it as dead but not using the death functions
+-- @param src not used by default, but should be the event source
function _M:disappear(src)
if game.level and game.level:hasEntity(self) then game.level:removeEntity(self) end
self.dead = true
@@ -265,16 +283,16 @@ function _M:disappear(src)
end
--- Get the "path string" for this actor
--- See Map:addPathString() for more info
+-- See `Map:addPathString`() for more info
function _M:getPathString()
return ""
end
--- Teleports randomly to a passable grid
--- @param x the coord of the teleportation
--- @param y the coord of the teleportation
--- @param dist the radius of the random effect, if set to 0 it is a precise teleport
--- @param min_dist the minimum radius of of the effect, will never teleport closer. Defaults to 0 if not set
+-- @int x the coord of the teleportation
+-- @int y the coord of the teleportation
+-- @number dist the radius of the random effect, if set to 0 it is a precise teleport
+-- @number min_dist the minimum radius of of the effect, will never teleport closer. Defaults to 0 if not set
-- @return true if the teleport worked
function _M:teleportRandom(x, y, dist, min_dist)
local poss = {}
@@ -299,6 +317,11 @@ function _M:teleportRandom(x, y, dist, min_dist)
end
--- Knock back the actor
+-- @int srcx source x
+-- @int srcy source y
+-- @number dist distance to push
+-- @param[type=?boolean] recursive is it recursive?
+-- @param[type=?boolean] on_terrain
function _M:knockback(srcx, srcy, dist, recursive, on_terrain)
print("[KNOCKBACK] from", srcx, srcx, "over", dist)
@@ -353,6 +376,10 @@ function _M:knockback(srcx, srcy, dist, recursive, on_terrain)
end
--- Pull the actor
+-- @int srcx source x
+-- @int srcy source y
+-- @number dist distance to pull
+-- @param[type=boolean] recursive is it recursive?
function _M:pull(srcx, srcy, dist, recursive)
print("[PULL] from", self.x, self.x, "towards", srcx, srcy, "over", dist)
@@ -395,6 +422,8 @@ function _M:pull(srcx, srcy, dist, recursive)
end
end
+--- Remove this actor from specified map
+-- @param[type=Map] map
function _M:deleteFromMap(map)
if self.x and self.y and map then
map:remove(self.x, self.y, engine.Map.ACTOR, self)
@@ -403,13 +432,16 @@ function _M:deleteFromMap(map)
end
end
---- Do we have enough energy
+--- Do we have enough energy?
+-- @number val
+-- @return true if we have enough
function _M:enoughEnergy(val)
val = val or game.energy_to_act
return self.energy.value >= val
end
--- Use some energy
+-- @number val how much energy to use
function _M:useEnergy(val)
val = val or game.energy_to_act
self.energy.value = self.energy.value - val
@@ -419,7 +451,8 @@ function _M:useEnergy(val)
end
--- What is our reaction toward the target
--- See Faction:factionReaction()
+-- @see Faction.factionReaction
+-- @param[type=Actor] target the target to check against
function _M:reactionToward(target)
return Faction:factionReaction(self.faction, target.faction)
end
@@ -427,15 +460,25 @@ end
--- Can the actor see the target actor
-- This does not check LOS or such, only the actual ability to see it.<br/>
-- By default this returns true, but a module can override it to check for telepathy, invisibility, stealth, ...
--- @param actor the target actor to check
--- @param def the default
--- @param def_pct the default percent chance
--- @return true or false and a number from 0 to 100 representing the "chance" to be seen
+-- @param[type=Actor] actor the target actor to check
+-- @number def the default
+-- @number def_pct the default percent chance
+-- @return[1] true
+-- @return[1] a number from 0 to 100 representing the "chance" to be seen
+-- @return[2] false
+-- @return[2] a number from 0 to 100 representing the "chance" to be seen
function _M:canSee(actor, def, def_pct)
return true, 100
end
--- Create a line to target based on field of vision
+-- @int tx terrain x
+-- @int ty terrain y
+-- @param[type=?boolean|func|string] extra_block function that returns a boolean, or string that checks all entities to see if line of sight is blocked
+-- @param[type=?boolean] block boolean of whether or not it's blocked by default
+-- @int[opt=self.x] sx actor's x
+-- @int[opt=self.y] sy actor's y
+-- @return fov line from `core.fov.line`
function _M:lineFOV(tx, ty, extra_block, block, sx, sy)
sx = sx or self.x
sy = sy or self.y
@@ -466,13 +509,18 @@ function _M:lineFOV(tx, ty, extra_block, block, sx, sy)
end
--- Does the actor have LOS to the target
--- @param x the spot we test for LOS
--- @param y the spot we test for LOS
--- @param what the property to check for, defaults to block_sight
--- @param range the maximum range to see, defaults to self.sight
--- @param source_x the spot to test from (defaults to self.x)
--- @param source_y the spot to test from (defaults to self.y)
--- @return has_los, last_x, last_y
+-- @int x the spot we test for LOS
+-- @int y the spot we test for LOS
+-- @param[opt=block_sight] what the property to check for
+-- @int[opt=self.sight] range the maximum range to see
+-- @int[opt=self.x] source_x the spot to test from
+-- @int[opt=self.y] source_y the spot to test from
+-- @return[1] true
+-- @return[1] last_x
+-- @return[1] last_y
+-- @return[2] false
+-- @return[2] last_x
+-- @return[2] last_y
function _M:hasLOS(x, y, what, range, source_x, source_y)
source_x = source_x or self.x
source_y = source_y or self.y
@@ -502,9 +550,10 @@ function _M:hasLOS(x, y, what, range, source_x, source_y)
end
--- Are we within a certain distance of the target
--- @param x the spot we test for nearness
--- @param y the spot we test for nearness
--- @param radius how close we should be (defaults to 1)
+-- @int x the spot we test for nearness
+-- @int y the spot we test for nearness
+-- @number radius how close we should be (defaults to 1)
+-- @return true if near
function _M:isNear(x, y, radius)
radius = radius or 1
if core.fov.distance(self.x, self.y, x, y) > radius then return false end
@@ -513,11 +562,20 @@ end
--- Return the kind of the entity
+-- @return "actor"
function _M:getEntityKind()
return "actor"
end
+--- he/she formatting
+-- @return string.he_she(self)
function _M:he_she() return string.he_she(self) end
+--- his/her formatting
+-- @return string.his_her(self)
function _M:his_her() return string.his_her(self) end
+--- him/her formatting
+-- @return string.him_her(self)
function _M:him_her() return string.him_her(self) end
+--- he/she/self formatting
+-- @return string.his_her_self(self)
function _M:his_her_self() return string.his_her_self(self) end
diff --git a/game/engines/default/engine/ActorsSeenDisplay.lua b/game/engines/default/engine/ActorsSeenDisplay.lua
index 129a6e224d..7b88ec7673 100644
--- a/game/engines/default/engine/ActorsSeenDisplay.lua
+++ b/game/engines/default/engine/ActorsSeenDisplay.lua
@@ -19,8 +19,19 @@
require "engine.class"
+--- A display of the actors currently seen by the specified actor
+-- @classmod engine.ActorsSeenDisplay
module(..., package.seeall, class.make)
+--- Init
+-- @param[type=Actor] actor
+-- @int x x coordinate on screen
+-- @int y y coordinate on screen
+-- @int w width of window
+-- @int h height of window
+-- @param[opt=black] bgcolor background color of window
+-- @string[opt="/data/font/DroidSansMono.ttf"] fontname
+-- @int[opt=10] fontsize
function _M:init(actor, x, y, w, h, bgcolor, fontname, fontsize)
self.actor = actor
if type(bgcolor) ~= "string" then
@@ -36,6 +47,10 @@ function _M:init(actor, x, y, w, h, bgcolor, fontname, fontsize)
end
--- Resize the display area
+-- @int x new x position
+-- @int y new y position
+-- @int w new width
+-- @int h new height
function _M:resize(x, y, w, h)
self.display_x, self.display_y = math.floor(x), math.floor(y)
self.w, self.h = math.floor(w), math.floor(h)
@@ -58,6 +73,7 @@ function _M:resize(x, y, w, h)
end
--- Sets the display into nb columns
+-- @int nb number of columns
function _M:setColumns(nb)
self.nb_cols = nb
end
@@ -101,6 +117,7 @@ function _M:display()
return self.surface
end
+--- Draws the actor to the display
function _M:toScreen()
self:display()
self.texture:toScreenFull(self.display_x, self.display_y, self.w, self.h, self.texture_w, self.texture_h)
diff --git a/game/engines/default/engine/Astar.lua b/game/engines/default/engine/Astar.lua
index 944047c4e0..3f938105ca 100644
--- a/game/engines/default/engine/Astar.lua
+++ b/game/engines/default/engine/Astar.lua
@@ -21,9 +21,12 @@ require "engine.class"
local Map = require "engine.Map"
--- Pathfinding using A*
+-- @classmod engine.Astar
module(..., package.seeall, class.make)
--- Initializes Astar for a map and an actor
+-- @param[type=Map] map
+-- @param[type=Actor] actor
function _M:init(map, actor)
self.map = map
self.actor = actor
@@ -31,6 +34,12 @@ function _M:init(map, actor)
end
--- The default heuristic for A*, tries to come close to the straight path
+-- @int sx
+-- @int sy
+-- @int cx
+-- @int cy
+-- @int tx
+-- @int ty
function _M:heuristicCloserPath(sx, sy, cx, cy, tx, ty)
local h
if util.isHex() then
@@ -48,19 +57,36 @@ function _M:heuristicCloserPath(sx, sy, cx, cy, tx, ty)
return h + 0.01*math.abs(dx1*dy2 - dx2*dy1)
end
---- The a simple heuristic for A*, using distance
+--- A simple heuristic for A*, using distance
+-- @int sx
+-- @int sy
+-- @int cx
+-- @int cy
+-- @int tx
+-- @int ty
function _M:heuristicDistance(sx, sy, cx, cy, tx, ty)
return core.fov.distance(cx, cy, tx, ty)
end
+--- Converts x & y into a single value
+-- @see toDouble
+-- @int x
+-- @int y
function _M:toSingle(x, y)
return x + y * self.map.w
end
+
+--- Converts a single value back into x & y
+-- @see toSingle
+-- @int c
function _M:toDouble(c)
local y = math.floor(c / self.map.w)
return c - y * self.map.w, y
end
+--- Create Path
+-- @param came_from
+-- @param cur
function _M:createPath(came_from, cur)
if not came_from[cur] then return end
local rpath, path = {}, {}
@@ -74,13 +100,16 @@ function _M:createPath(came_from, cur)
end
--- Compute path from sx/sy to tx/ty
--- @param sx the start coord
--- @param sy the start coord
--- @param tx the end coord
--- @param ty the end coord
--- @param use_has_seen if true the astar wont consider non-has_seen grids
--- @param add_check a function that checks each x/y coordinate and returns true if the coord is valid
--- @return either nil if no path or a list of nodes in the form { {x=...,y=...}, {x=...,y=...}, ..., {x=tx,y=ty}}
+-- @int sx x of the start coord
+-- @int sy y of the start coord
+-- @int tx x of the end coord
+-- @int ty y of the end coord
+-- @param[type=boolean] use_has_seen if true the astar wont consider non-has_seen grids
+-- @func[opt=`heuristicCloserPath`] heuristic The heuristic to use
+-- @func[opt=true] add_check a function that checks each x/y coordinate and returns true if the coord is valid
+-- @param[type=?boolean] forbid_diagonals if they can't move diagonally
+-- @return[1] nil if no path is found
+-- @return[2] list of nodes in the form { {x=...,y=...}, {x=...,y=...}, ..., {x=tx,y=ty}}
function _M:calc(sx, sy, tx, ty, use_has_seen, heuristic, add_check, forbid_diagonals)
local heur = heuristic or self.heuristicCloserPath
local w, h = self.map.w, self.map.h
diff --git a/game/engines/default/engine/Autolevel.lua b/game/engines/default/engine/Autolevel.lua
index d3f5ef6100..943021e446 100644
--- a/game/engines/default/engine/Autolevel.lua
+++ b/game/engines/default/engine/Autolevel.lua
@@ -19,19 +19,25 @@
require "engine.class"
---- Handles autoleveling schemes
--- Probably used mainly for NPCS, although it could also be used for player allies
+--- Handles autoleveling schemes
+-- Used mainly for NPCS, although it could also be used for player allies
-- or players themselves for lazy players/modules
+-- @classmod engine.Autolevel
module(..., package.seeall, class.make)
_M.schemes = {}
+--- Register Scheme for use with actors
+-- @param[type=table] t your scheme definition
+-- @usage registerScheme({ name = "warrior", levelup = function(self) self:learnStats{ self.STAT_STR, self.STAT_STR, self.STAT_DEX } end})
function _M:registerScheme(t)
assert(t.name, "no autolevel name")
assert(t.levelup, "no autolevel levelup function")
_M.schemes[t.name] = t
end
+--- Triggers the autolevel function defined with registerScheme for the specified actor
+-- @param[type=Actor] actor
function _M:autoLevel(actor)
if not actor.autolevel then return end
assert(_M.schemes[actor.autolevel], "no autoleveling scheme "..actor.autolevel)
diff --git a/game/engines/default/engine/BSP.lua b/game/engines/default/engine/BSP.lua
index bdb77569f4..cf91eff2cf 100644
--- a/game/engines/default/engine/BSP.lua
+++ b/game/engines/default/engine/BSP.lua
@@ -19,10 +19,17 @@
require "engine.class"
---- Abstract binary space partitioning
+--- Abstract binary space partitioning
-- Can be used to generator levels and so on
+-- @classmod engine.BSP
module(..., package.seeall, class.make)
+--- Init
+-- @int w
+-- @int h
+-- @int min_w
+-- @int min_h
+-- @int[opt=8] max_depth
function _M:init(w, h, min_w, min_h, max_depth)
self.max_depth = max_depth or 8
self.min_w, self.min_h = min_w, min_h
@@ -33,6 +40,8 @@ function _M:init(w, h, min_w, min_h, max_depth)
print("[BSP] ", w, h)
end
+--- Partition
+-- @param[type=?table] store BSP table, Default: {x=0, y=0, rx=0, ry=0, w=w, h=h, nodes={}, id=0, depth=0}
function _M:partition(store)
store = store or self.bsp
diff --git a/game/engines/default/engine/Birther.lua b/game/engines/default/engine/Birther.lua
index e7bc817450..0f971fc90f 100644
--- a/game/engines/default/engine/Birther.lua
+++ b/game/engines/default/engine/Birther.lua
@@ -24,14 +24,23 @@ local Button = require "engine.ui.Button"
local Textzone = require "engine.ui.Textzone"
local Separator = require "engine.ui.Separator"
+--- Allows you to create characters using a GUI
+-- @classmod engine.Birther
module(..., package.seeall, class.inherit(Dialog))
+--- Where descriptors are stored
+-- @static
_M.birth_descriptor_def = {}
+--- If a descriptor is automatic it gets stored here
+-- @static
_M.birth_auto = {}
+--- Names for the steps
+-- @static
_M.step_names = {}
---- Defines birth descriptors
--- Static!
+--- Defines birth descriptors from specified lua file
+-- @static
+-- @string file the lua file containing the descriptor
function _M:loadDefinition(file)
local f, err = util.loadfilemods(file, setmetatable({
ActorTalents = require("engine.interface.ActorTalents"),
@@ -47,7 +56,9 @@ function _M:loadDefinition(file)
end
--- Defines one birth descriptor
--- Static!
+-- @{birth_descriptor.lua|Example Birth Descriptor}
+-- @static
+-- @param[type=table] t the birth descriptor
function _M:newBirthDescriptor(t)
assert(t.name, "no birth name")
assert(t.type, "no birth type")
@@ -67,14 +78,23 @@ function _M:newBirthDescriptor(t)
end
--- Get one birth descriptor
--- Static!
+-- @static
+-- @string type type of descriptor
+-- @string name the name of the descriptor
function _M:getBirthDescriptor(type, name)
if not self.birth_descriptor_def[type] then return nil end
return self.birth_descriptor_def[type][name]
end
---- Instanciates a birther for the given actor
+--- Instantiates a birther for the given actor
+-- @string title dialog title
+-- @param[type=Actor] actor the actor we're birthing
+-- @param[type=table] order the order to display birth descriptors in, referenced by names
+-- @func[opt] at_end function to call when finished birthing
+-- @param[type=?boolean] quickbirth do we `quickBirth`??
+-- @int[opt=600] w width of dialog
+-- @int[opt=400] h height of dialog
function _M:init(title, actor, order, at_end, quickbirth, w, h)
self.quickbirth = quickbirth
self.actor = actor
@@ -143,6 +163,7 @@ Mouse: #00FF00#Left click#FFFFFF# to accept; #00FF00#right click#FFFFFF# to go b
}
end
+--- Automatically called after using @{engine.Game.registerDialog} for this class
function _M:on_register()
self:next()
self:select(self.list[self.c_list.sel])
@@ -165,6 +186,8 @@ function _M:on_register()
end
end
+--- Quickly birth the actor using predefined settings.
+--
function _M:quickBirth()
if not self.do_quickbirth then return end
-- Abort quickbirth if stage not found
@@ -184,6 +207,9 @@ function _M:quickBirth()
self.do_quickbirth = false
end
+--- Populates the dialog with all of the choices for the specified type
+--
+-- @string type birth descriptor type
function _M:selectType(type)
local default = 1
self.list = {}
@@ -219,6 +245,9 @@ function _M:selectType(type)
self.c_list:onSelect()
end
+--- Used internally to transform indices into letters for column selection
+--
+-- @int letter
function _M:makeKey(letter)
if letter >= 26 then
return string.char(string.byte('A') + letter - 26)
@@ -227,6 +256,8 @@ function _M:makeKey(letter)
end
end
+--- Called after `selectType` to actually put the generated descriptor values into the list
+--
function _M:updateList()
self.list.chars = {}
for i, item in ipairs(self.list) do
@@ -239,6 +270,8 @@ function _M:updateList()
self.c_list:generate()
end
+--- Returns to the previous birth descriptor specified in order
+--
function _M:prev()
if self.cur_order == 1 then
if #self.list == 1 and self.birth_auto[self.current_type] ~= false then self:next() end
@@ -257,6 +290,9 @@ function _M:prev()
end
end
+--- Stores the value of the current selected birth descriptor,
+-- then proceeds to the next birth descriptor specified in order
+--
function _M:next()
self.changed = true
if self.list then
@@ -298,19 +334,26 @@ function _M:next()
end
end
+--- Randomly selects an option for the current birth descriptor,
+-- then goes to the next one in the order automatically
+--
function _M:randomSelect()
self.sel = rng.range(1, #self.list)
game.log("Randomly selected %s.", self.list[self.sel].name)
self:next()
end
+--- Used by the list that stores birth descriptors, selects the correct item
+--
+-- @param item
function _M:select(item)
if item and self.uis and self.uis[2] then
self.uis[2].ui = item.zone
end
end
---- Apply all birth options to the actor
+--- Tries to apply all birth options to the actor. Should only be called once, at the end of creation
+--
function _M:apply()
self.actor.descriptor = {}
local stats, inc_stats = {}, {}
diff --git a/game/engines/default/engine/Calendar.lua b/game/engines/default/engine/Calendar.lua
index 227b78339e..5ad9dbe75b 100644
--- a/game/engines/default/engine/Calendar.lua
+++ b/game/engines/default/engine/Calendar.lua
@@ -19,20 +19,30 @@
require "engine.class"
---- Defines factions
+--- Defines calendars for factions
+-- @classmod engine.Calendar
module(..., package.seeall, class.make)
+--- Default: 10
seconds_per_turn = 10
+--- Default: 6 turns = 60 / `seconds_per_turn`
MINUTE = 60 / seconds_per_turn
+--- Default: 360 turns = `MINUTE` * 60
HOUR = MINUTE * 60
+--- Default: 8640 turns = `HOUR` * 24
DAY = HOUR * 24
+--- Default: 3153600 turns = `DAY` * 365
YEAR = DAY * 365
+--- Default: 2160 turns = `HOUR` * 6
DAY_START = HOUR * 6
--- Create a calendar
-- @param definition the file to load that returns a table containing calendar months
-- @param datestring a string to format the date when requested, in the format "%s %s %s %d %d", standing for, day, month, year, hour, minute
+-- @param start_year the year the calendar starts at
+-- @param start_day defaults to 1
+-- @param start_hour defaults to 8
function _M:init(definition, datestring, start_year, start_day, start_hour)
local data = dofile(definition)
self.calendar = {}
@@ -50,12 +60,20 @@ function _M:init(definition, datestring, start_year, start_day, start_hour)
self.start_hour = start_hour or 8
end
+--- Gets a formatted timedate string
+-- @int turn
+-- @string dstr a datestring
+-- @return a formatted date string
function _M:getTimeDate(turn, dstr)
local doy, year = self:getDayOfYear(turn)
local hour, min = self:getTimeOfDay(turn)
return (dstr or self.datestring):format(tostring(self:getDayOfMonth(doy)):ordinal(), self:getMonthName(doy), tostring(year):ordinal(), hour, min)
end
+--- Get what day of the year it is based on turn
+-- @int turn
+-- @return day_of_year
+-- @return year
function _M:getDayOfYear(turn)
local d, y
turn = turn + self.start_hour * self.HOUR
@@ -65,6 +83,10 @@ function _M:getDayOfYear(turn)
return d, self.start_year + y
end
+--- Current time based on turn
+-- @int turn
+-- @return hour
+-- @return min
function _M:getTimeOfDay(turn)
local hour, min
turn = turn + self.start_hour * self.HOUR
@@ -74,6 +96,9 @@ function _M:getTimeOfDay(turn)
return hour, min
end
+--- Gets month number based on day of year
+-- @int dayofyear use `getDayOfYear`
+-- @return integer between {1, numMonths}
function _M:getMonthNum(dayofyear)
local i = #self.calendar
@@ -85,16 +110,25 @@ function _M:getMonthNum(dayofyear)
return i
end
+--- Returns the name of the month using the day
+-- @int dayofyear use `getDayOfYear`
+-- @return month.name
function _M:getMonthName(dayofyear)
local month = self:getMonthNum(dayofyear)
return self.calendar[month].name
end
+--- Day of the month using day of year
+-- @int dayofyear getDayOfYear
+-- @return integer between {1, numDaysInMonth}
function _M:getDayOfMonth(dayofyear)
local month = self:getMonthNum(dayofyear)
return dayofyear - self.calendar[month].days + 1 + self.calendar[month].offset
end
+--- How long the month is using day of year
+-- @int dayofyear getDayOfYear
+-- @return month.length
function _M:getMonthLength(dayofyear)
local month = self:getMonthNum(dayofyear)
return self.calendar[month].length
diff --git a/game/engines/default/engine/CharacterBallSave.lua b/game/engines/default/engine/CharacterBallSave.lua
index 4e214f6103..dea8ee2d8e 100644
--- a/game/engines/default/engine/CharacterBallSave.lua
+++ b/game/engines/default/engine/CharacterBallSave.lua
@@ -20,9 +20,13 @@
require "engine.class"
local Savefile = require "engine.Savefile"
---- Handles a local characters vault saves
+--- Handles a local characters charball saves
+-- @classmod engine.CharacterBallSave
module(..., package.seeall, class.inherit(Savefile))
+--- init
+-- @param[type=Savefile] savefile
+-- @thread coroutine
function _M:init(savefile, coroutine)
Savefile.init(self, savefile, coroutine)
@@ -34,16 +38,24 @@ function _M:init(savefile, coroutine)
end
--- Get a savename for an entity
+-- @param[type=Entity] e
+-- @return a formatted string
+-- "{e.uuid}-{version_major}.{version_minor}.{version_patch}.charball"
function _M:nameSaveEntity(e)
e.__version = game.__mod_info.version
return ("%s-%d.%d.%d.charball"):format(e.__te4_uuid, game.__mod_info.version[1], game.__mod_info.version[2], game.__mod_info.version[3])
end
---- Get a savename for an entity
+--- Get a specific savename for an entity
+-- @string name
+-- @return name.charball
function _M:nameLoadEntity(name)
return name..".charball"
end
--- Save an entity
+-- @see engine.Savefile.saveEntity
+-- @param[type=Entity] e
+-- @param[type=boolean] no_dialog Show a dialog that we're saving?
function _M:saveEntity(e, no_dialog)
Savefile.saveEntity(self, e, no_dialog)
end
diff --git a/game/engines/default/engine/CharacterVaultSave.lua b/game/engines/default/engine/CharacterVaultSave.lua
index c178b47b54..7b2208caa5 100644
--- a/game/engines/default/engine/CharacterVaultSave.lua
+++ b/game/engines/default/engine/CharacterVaultSave.lua
@@ -21,8 +21,12 @@ require "engine.class"
local Savefile = require "engine.Savefile"
--- Handles a local characters vault saves
+-- @classmod engine.CharacterVaultSave
module(..., package.seeall, class.inherit(Savefile))
+--- Init
+-- @string savefile name of savefile
+-- @thread coroutine
function _M:init(savefile, coroutine)
Savefile.init(self, savefile, coroutine)
@@ -34,16 +38,23 @@ function _M:init(savefile, coroutine)
end
--- Get a savename for an entity
+-- @param[type=Entity] e
+-- @return "character.teac"
function _M:nameSaveEntity(e)
e.__version = game.__mod_info.version
return "character.teac"
end
--- Get a savename for an entity
+-- @string name not used
+-- @return "character.teac"
function _M:nameLoadEntity(name)
return "character.teac"
end
--- Save an entity
+-- @see engine.Savefile.saveEntity
+-- @param[type=Entity] e
+-- @param[type=boolean] no_dialog Show a popup dialog that we're currently saving?
function _M:saveEntity(e, no_dialog)
Savefile.saveEntity(self, e, no_dialog)
diff --git a/game/engines/default/engine/Chat.lua b/game/engines/default/engine/Chat.lua
index d7b9576dcf..fab69ebdfe 100644
--- a/game/engines/default/engine/Chat.lua
+++ b/game/engines/default/engine/Chat.lua
@@ -22,8 +22,14 @@ require "engine.dialogs.Chat"
local slt2 = require "slt2"
--- Handle chats between the player and NPCs
+-- @classmod engine.Chat
module(..., package.seeall, class.make)
+--- Init
+-- @string name used to load a chat file
+-- @param[type=Actor] npc the NPC that the player is talking to
+-- @param[type=Actor] player the player
+-- @param[type=table] data
function _M:init(name, npc, player, data)
self.quick_replies = 0
self.chats = {}
@@ -45,6 +51,9 @@ function _M:init(name, npc, player, data)
self:triggerHook{"Chat:load", data=data}
end
+--- Get chat file
+-- Also has support for chat files in addons
+-- @string file /data*/chats/{file}.lua
function _M:getChatFile(file)
local _, _, addon, rfile = file:find("^([^+]+)%+(.+)$")
if addon and rfile then
@@ -54,6 +63,8 @@ function _M:getChatFile(file)
end
--- Switch the NPC talking
+-- @param[type=Actor] npc
+-- @return NPC we switched from
function _M:switchNPC(npc)
local old = self.npc
self.npc = npc
@@ -61,6 +72,7 @@ function _M:switchNPC(npc)
end
--- Adds a chat to the list of possible chats
+-- @param[type=table] c
function _M:addChat(c)
self:triggerHook{"Chat:add", c=c}
@@ -81,7 +93,8 @@ function _M:addChat(c)
end
--- Invokes a chat
--- @param id the id of the first chat to run, if nil it will use the default one
+-- @string[opt=self.default_id] id the id of the first chat to run
+-- @return `engine.dialog.Chat`
function _M:invoke(id)
if self.npc.onChat then self.npc:onChat() end
if self.player.onChat then self.player:onChat() end
@@ -92,6 +105,8 @@ function _M:invoke(id)
end
--- Gets the chat with the given id
+-- @string id the id of the chat
+-- @return `Chat`
function _M:get(id)
local c = self.chats[id]
if c and c.template then
@@ -102,6 +117,7 @@ function _M:get(id)
end
--- Replace some keywords in the given text
+-- @string text @playername@, @npcname@, @playerdescriptor.(.-)@
function _M:replace(text)
text = text:gsub("@playername@", self.player.name):gsub("@npcname@", self.npc.name)
text = text:gsub("@playerdescriptor.(.-)@", function(what) return self.player.descriptor["fake_"..what] or self.player.descriptor[what] end)
diff --git a/game/engines/default/engine/DamageType.lua b/game/engines/default/engine/DamageType.lua
index 5e20865a22..097234cf2b 100644
--- a/game/engines/default/engine/DamageType.lua
+++ b/game/engines/default/engine/DamageType.lua
@@ -19,18 +19,26 @@
require "engine.class"
---- Handles actors stats
+--- Defines damage types used by actors
+-- @classmod engine.DamageType
module(..., package.seeall, class.make)
_M.dam_def = {}
--- Default damage projector
+--- Default damage projector
+-- needs to be overridden, as the default functionality just prints to the console
+-- @param[type=Actor] src what is projecting
+-- @int x x coordinate
+-- @int y y coordinate
+-- @param type type of damage
+-- @int dam amount of damage
function _M.defaultProject(src, x, y, type, dam)
print("implement a projector!")
end
--- Defines new damage type
--- Static!
+-- @static
+-- @string file loads a definition from a lua file
function _M:loadDefinition(file)
local f, err = loadfile(file)
if not f and err then error(err) end
@@ -44,7 +52,8 @@ function _M:loadDefinition(file)
end
--- Defines one ability type(group)
--- Static!
+-- @static
+-- @param[type=table] t
function _M:newDamageType(t)
assert(t.name, "no ability type name")
assert(t.type, "no ability type type")
@@ -66,19 +75,33 @@ function _M:newDamageType(t)
self[t.type] = t.type
end
+--- Fetches the damage type by the string id
+-- throws an assert
+-- @string id
+-- @return damage type
function _M:get(id)
assert(_M.dam_def[id], "damage type "..tostring(id).." used but undefined")
return _M.dam_def[id]
end
+--- Checks if our damage type exists
+-- @string id
+-- @return[1] nil
+-- @return[2] damage type
function _M:exists(id)
return _M.dam_def[id]
end
+--- Allows an actor to project for another actor
+-- @param[type=Actor] src
+-- @param[type=Actor] v
function _M:projectingFor(src, v)
src.__projecting_for = v
end
+--- Who is this actor projecting for?
+-- @param[type=Actor] src
+-- @return `Actor`
function _M:getProjectingFor(src)
return src.__projecting_for
end
diff --git a/game/engines/default/engine/DebugConsole.lua b/game/engines/default/engine/DebugConsole.lua
index 12d170a99b..01ae24d39d 100644
--- a/game/engines/default/engine/DebugConsole.lua
+++ b/game/engines/default/engine/DebugConsole.lua
@@ -20,10 +20,15 @@
require "engine.class"
require "engine.Dialog"
+--- Debug Console
+-- @classmod engine.DebugConsole
+-- @inherit engine.Dialog
module(..., package.seeall, class.inherit(engine.Dialog))
-- Globals to all instances of the console
+--- Current scroll offset
offset = 0
+--- History of debug console defaults to help text for easy usage
history = {
[[<<<<<------------------------------------------------------------------------------------->>>>>]],
[[< Welcome to the T-Engine Lua Console >]],
@@ -46,12 +51,27 @@ history = {
[[< Page Down :=: Scrolls down 75% of the history >]],
[[<<<<<------------------------------------------------------------------------------------->>>>>]],
}
+--- String representation of current line
line = ""
+--- Integer Position in current line
line_pos = 0
+--- Integer command selection
com_sel = 0
+--- Registered commands
commands = {}
local find_base
+--- Parses a string for autocompletion
+-- @local
+-- @string remaining the string to parse, also used for recursion
+-- @return[1] nil
+-- @return[1] error object
+-- @return[2] nil
+-- @return[2] "%s does not exist."
+-- @return[3] nil
+-- @return[3] "%s is not a valid path"
+-- @return[4] head
+-- @return[4] tail
find_base = function(remaining)
-- Check if we are in a string by counting quotation marks
local _, nsinglequote = remaining:gsub("\'", "")
@@ -105,6 +125,7 @@ find_base = function(remaining)
end
end
+--- Init the debug console
function _M:init()
self.cursor = "|"
self.blink_period = 20
@@ -282,6 +303,7 @@ function _M:init()
}
end
+--- Display function
function _M:display()
-- Blinking cursor
self.blink = self.blink - 1
@@ -293,6 +315,9 @@ function _M:display()
engine.Dialog.display(self)
end
+--- @param s screen
+-- @param w width
+-- @param h height
function _M:drawDialog(s, w, h)
local buffer = (self.ih % self.font_h) / 2
local i, dh = #_M.history - _M.offset, self.ih - buffer - self.font:lineSkip()
@@ -311,7 +336,7 @@ function _M:drawDialog(s, w, h)
end
--- Scroll the zone
--- @param i number representing how many lines to scroll
+-- @int i number representing how many lines to scroll
function _M:scrollUp(i)
_M.offset = _M.offset + i
if _M.offset > #_M.history - 1 then _M.offset = #_M.history - 1 end
@@ -319,7 +344,7 @@ function _M:scrollUp(i)
self.changed = true
end
---- Autocomplete the current line
+--- Autocomplete the current line
-- Will handle either tables (eg. mod.cla -> mod.class) or paths (eg. "/mod/cla" -> "/mod/class/")
function _M:autoComplete()
local base, to_complete = find_base(_M.line:sub(1, _M.line_pos))
@@ -419,7 +444,8 @@ function _M:autoComplete()
end
--- Prints comments for a function
--- @param function
+-- @func func only works on a function obviously
+-- @param[type=boolean] verbose give extra junk
function _M:functionHelp(func, verbose)
if type(func) ~= "function" then return nil, "Can only give help on functions." end
local info = debug.getinfo(func)
@@ -457,8 +483,8 @@ function _M:functionHelp(func, verbose)
end
--- Add a list of strings to the history with multiple columns
--- @param strings Array of strings to add to the history
--- @param offset Number of spaces to add on the left-hand side
+-- @param[type=table] strings Array of strings to add to the history
+-- @int offset Number of spaces to add on the left-hand side
function _M:historyColumns(strings, offset)
local offset_str = string.rep(" ", offset and offset or 0)
local ox, oy = self.font:size(offset_str)
diff --git a/game/engines/default/engine/Dialog.lua b/game/engines/default/engine/Dialog.lua
index 1ee0cff4cb..6b2a886949 100644
--- a/game/engines/default/engine/Dialog.lua
+++ b/game/engines/default/engine/Dialog.lua
@@ -22,11 +22,16 @@ require "engine.Tiles"
require "engine.KeyBind"
--- Handles dialog windows
+-- @classmod engine.Dialog
module(..., package.seeall, class.make)
tiles = engine.Tiles.new(16, 16)
--- Requests a simple, press any key, dialog
+-- @string title Display title
+-- @string text the text
+-- @func[opt] fct the function to call on dialog close
+-- @param[type=?boolean] no_leave set this to true to disable closing of the dialog
function _M:simplePopup(title, text, fct, no_leave)
local font = core.display.newFont("/data/font/DroidSans.ttf", 14)
local w, h = font:size(text)
@@ -47,6 +52,11 @@ function _M:simplePopup(title, text, fct, no_leave)
end
--- Requests a simple, press any key, dialog
+-- @string title Display title
+-- @string text the text
+-- @int w width
+-- @func[opt] fct the function to call on dialog close
+-- @param[type=?boolean] no_leave set this to true to disable closing of the dialog
function _M:simpleLongPopup(title, text, w, fct, no_leave)
local font = core.display.newFont("/data/font/DroidSans.ttf", 14)
local list = text:splitLines(w - 10, font)
@@ -73,6 +83,11 @@ function _M:simpleLongPopup(title, text, w, fct, no_leave)
end
--- Requests a simple yes-no dialog
+-- @string title Display title
+-- @string text the text
+-- @func[opt] fct the function to call on dialog close
+-- @string[opt="Yes"] yes_text Text for "yes" button
+-- @string[opt="No"] no_text Text for "no" button
function _M:yesnoPopup(title, text, fct, yes_text, no_text)
local font = core.display.newFont("/data/font/DroidSans.ttf", 14)
local w, h = font:size(text)
@@ -108,6 +123,12 @@ function _M:yesnoPopup(title, text, fct, yes_text, no_text)
end
--- Requests a long yes-no dialog
+-- @string title Display title
+-- @string text the text
+-- @int w width
+-- @func[opt] fct the function to call on dialog close
+-- @string[opt="Yes"] yes_text Text for "yes" button
+-- @string[opt="No"] no_text Text for "no" button
function _M:yesnoLongPopup(title, text, w, fct, yes_text, no_text)
local font = core.display.newFont("/data/font/DroidSans.ttf", 14)
local list = text:splitLines(w - 10, font)
@@ -149,6 +170,14 @@ function _M:yesnoLongPopup(title, text, w, fct, yes_text, no_text)
end
--- Create a Dialog
+-- @string title Display title
+-- @int w width
+-- @int h height
+-- @int x absolute x coordinate
+-- @int y absolute y coordinate
+-- @int[opt] alpha transparency
+-- @param[opt] font defaults to Droid Sans 14pt
+-- @param[opt] showup how long it takes to show up?
function _M:init(title, w, h, x, y, alpha, font, showup)
self.title = title
self.controls = { }
@@ -167,6 +196,12 @@ function _M:init(title, w, h, x, y, alpha, font, showup)
end
end
+--- Resize
+-- @int w width
+-- @int h height
+-- @int x absolute x coordinate
+-- @int y absolute y coordinate
+-- @int[opt] alpha defaults to 220
function _M:resize(w, h, x, y, alpha)
self.w, self.h = math.floor(w), math.floor(h)
self.display_x = math.floor(x or (game.w - self.w) / 2)
@@ -179,6 +214,7 @@ function _M:resize(w, h, x, y, alpha)
self.changed = true
end
+--- Renders the dialog
function _M:display()
if not self.changed then return self.surface end
@@ -215,6 +251,10 @@ function _M:display()
return self.surface
end
+--- texture to screen
+-- @int x absolute x coordinate
+-- @int y absolute y coordinate
+-- @int nb_keyframes number of keyframes
function _M:toScreen(x, y, nb_keyframes)
-- Draw with only the texture
if self.__showup then
@@ -239,16 +279,23 @@ function _M:toScreen(x, y, nb_keyframes)
end
end
-
+--- Draw the dialog
+-- @param s screen
function _M:drawDialog(s)
end
+--- register keybind and command
+-- @param[type=KeyCommand] t
+-- @param[type=KeyBind] b
function _M:keyCommands(t, b)
self.key = engine.KeyBind.new()
if t then self.key:addCommands(t) end
if b then self.key:addBinds(b) end
end
+--- create a mouse zone
+-- @param[type=boolean] t t.norestrict = true, then allow mouse to move out of zone
+-- @param[type=boolean] no_new true = don't create a new mouse
function _M:mouseZones(t, no_new)
-- Offset the x and y with the window position and window title
if not t.norestrict then
@@ -264,22 +311,49 @@ function _M:mouseZones(t, no_new)
self.mouse:registerZones(t)
end
+--- Called when dialog is unloading
function _M:unload()
end
+--- Called when dialog is cleaning up
function _M:cleanup()
end
+--- Draw a horizontal border
+-- @param s screen
+-- @int x absolute x coordinate
+-- @int y absolute y coordinate
+-- @int w width
function _M:drawWBorder(s, x, y, w)
for i = x, x + w do
s:merge(tiles:get(nil, 0,0,0, 0,0,0, "border_8.png"), i, y)
end
end
+--- Draw a vertical border
+-- @param s screen
+-- @int x absolute x coordinate
+-- @int y absolute y coordinate
+-- @int h height
function _M:drawHBorder(s, x, y, h)
for i = y, y + h do
s:merge(tiles:get(nil, 0,0,0, 0,0,0, "border_4.png"), x, i)
end
end
+--- draw a selection list
+-- @param s screen
+-- @int x absolute x coordinate
+-- @int y absolute y coordinate
+-- @int hskip height padding
+-- @param[type=table] list the list to draw
+-- @int[opt=nil] sel the selected item
+-- @param[type=?opt|tab|string|func] prop property to display for items (can be table/function/string), Default: toString(item)
+-- @int[opt=1] scroll how far down the list are we
+-- @int[opt=99999] max max number of entries
+-- @param[type=?table] color color of items, defaults to colors.WHITE
+-- @param[type=?table] selcolor color of selected item, defaults to colors.CYAN
+-- @int[opt] max_size max length of displayed strings
+-- @int[opt] cutoff_size max width
+-- @param[type=?boolean] scrollbar display a scrollbar?
function _M:drawSelectionList(s, x, y, hskip, list, sel, prop, scroll, max, color, selcolor, max_size, cutoff_size, scrollbar)
selcolor = selcolor or {0,255,255}
color = color or {255,255,255}
diff --git a/game/engines/default/engine/DirectPath.lua b/game/engines/default/engine/DirectPath.lua
index e673d4fe64..f05b3f346d 100644
--- a/game/engines/default/engine/DirectPath.lua
+++ b/game/engines/default/engine/DirectPath.lua
@@ -21,9 +21,12 @@ require "engine.class"
local Map = require "engine.Map"
--- Computes a direct line path from start to end
+-- @classmod engine.DirectPath
module(..., package.seeall, class.make)
--- Initializes DirectPath for a map and an actor
+-- @param[type=Map] map
+-- @param[type=Actor] actor
function _M:init(map, actor)
self.map = map
self.actor = actor
@@ -34,8 +37,9 @@ end
-- @param sy the start coord
-- @param tx the end coord
-- @param ty the end coord
--- @param use_has_seen if true the astar wont consider non-has_seen grids
--- @return either nil if no path or a list of nodes in the form { {x=...,y=...}, {x=...,y=...}, ..., {x=tx,y=ty}}
+-- @param[opt] use_has_seen if true the astar wont consider non-has_seen grids
+-- @return[1] nil if no path
+-- @return[2] a list of nodes in the form { {x=...,y=...}, {x=...,y=...}, ..., {x=tx,y=ty}}
function _M:calc(sx, sy, tx, ty, use_has_seen)
local path = {}
local l = line.new(sx, sy, tx, ty)
diff --git a/game/engines/default/engine/Emote.lua b/game/engines/default/engine/Emote.lua
index 2df4ce3970..878109c103 100644
--- a/game/engines/default/engine/Emote.lua
+++ b/game/engines/default/engine/Emote.lua
@@ -20,6 +20,8 @@
require "engine.class"
local Base = require "engine.ui.Base"
+--- Emotes for actors
+-- @classmod engine.Emote
module(..., package.seeall, class.inherit(Base))
frame_ox1 = -15
@@ -27,6 +29,9 @@ frame_ox2 = 15
frame_oy1 = -15
frame_oy2 = 15
+--- @string text
+-- @int[opt=60] dur
+-- @param[opt=colors.Black] color
function _M:init(text, dur, color)
self.text = text
self.dur = dur or 60
@@ -35,20 +40,24 @@ function _M:init(text, dur, color)
Base.init(self, {font = {"/data/font/DroidSans-Bold.ttf", 16}})
end
+--- on loaded
function _M:loaded()
Base.init(self, {font = {"/data/font/DroidSans-Bold.ttf", 16}})
end
--- Serialization
+-- @return if we successfully saved or not
function _M:save()
return class.save(self, {x=true, y=true, text=true, dur=true, color=true}, true)
end
+--- Update emote
function _M:update()
self.dur = self.dur - 1
if self.dur < 0 then return true end
end
+--- Generate emote
function _M:generate()
-- Draw UI
local w, h = self.font:size(self.text)
@@ -62,6 +71,7 @@ function _M:generate()
self.frame = self:makeFrame("ui/emote/", self.w, self.h)
end
+--- Display emote
function _M:display(x, y)
local a = 1
if self.dur < 10 then
diff --git a/game/engines/default/engine/Entity.lua b/game/engines/default/engine/Entity.lua
index 19cb1b8994..77f99126c2 100644
--- a/game/engines/default/engine/Entity.lua
+++ b/game/engines/default/engine/Entity.lua
@@ -17,31 +17,39 @@
-- Nicolas Casalini "DarkGod"
-- darkgod@te4.org
---- A game entity
--- An entity is anything that goes on a map, terrain features, objects, monsters, player, ...
--- Usually there is no need to use it directly, and it is better to use specific engine.Grid, engine.Actor or engine.Object
--- classes. Most modules will want to subclass those anyway to add new comportments
local Shader = require "engine.Shader"
local Particles = require "engine.Particles"
+--- An entity is anything that goes on a map, terrain features, objects, monsters, player, ...
+-- Usually there is no need to use it directly, and it is better to use specific engine.Grid, engine.Actor or engine.Object
+-- classes. Most modules will want to subclass those anyway to add new comportments
+-- @classmod engine.Entity
module(..., package.seeall, class.make)
local next_uid = 1
local entities_load_functions = {}
+
_M.__mo_final_repo = {}
+--- Fields we shouldn't save
_M._no_save_fields = { _shader = true }
-_M.__position_aware = false -- Subclasses can change it to know where they are on the map
+ --- Subclasses can change it to know where they are on the map
+_M.__position_aware = false
--- Setup the uids & MO repository as a weak value table, when the entities are no more used anywhere else they disappear from there too
+-- Setup the uids & Map object repository as a weak value table, when the entities are no more used anywhere else they disappear from there too
setmetatable(__uids, {__mode="v"})
setmetatable(_M.__mo_final_repo, {__mode="k"})
---- Invalidates the whole MO repository
+--- Invalidates the whole Map Object repository
+-- @static
function _M:invalidateAllMO()
setmetatable(_M.__mo_final_repo, {__mode="k"})
end
+--- recursive copy
+-- @param[type=table] dst the destination table
+-- @param[type=table] src the source table
+-- @param[type=boolean] deep copy ALL the things
local function copy_recurs(dst, src, deep)
for k, e in pairs(src) do
if type(e) == "table" and (e.__ATOMIC or e.__CLASSNAME) then
@@ -59,6 +67,9 @@ local function copy_recurs(dst, src, deep)
end
end
+--- Import base into entity
+-- @param[type=table] t
+-- @param[type=table] base
local function importBase(t, base)
local temp = table.clone(base, true, {uid=true, define_as = true})
if base.onEntityMerge then base:onEntityMerge(temp) end
@@ -69,7 +80,10 @@ local function importBase(t, base)
end
--- Create a new entity with a base
--- STATIC
+-- calls `importBase`
+-- @static
+-- @param[type=table] t
+-- @param[type=table] base
function _M:fromBase(t, base)
if not base then base = t.base end
assert(base, "no base given to Entity.fromBase")
@@ -79,7 +93,8 @@ end
--- Initialize an entity
-- Any subclass MUST call this constructor
--- @param t a table defining the basic properties of the entity
+-- @param[type=table] t a table defining the basic properties of the entity
+-- @param[type=boolean] no_default alternate settings that override the defaults
-- @usage Entity.new{display='#', color_r=255, color_g=255, color_b=255}
function _M:init(t, no_default)
t = t or {}
@@ -159,6 +174,8 @@ function _M:init(t, no_default)
end
--- If we are cloned we need a new uid
+-- flags entity as changed
+-- @param src source of event, not used by default
function _M:cloned(src)
self.uid = next_uid
__uids[self.uid] = self
@@ -168,6 +185,9 @@ function _M:cloned(src)
end
--- If we are replaced we need a new uid
+-- flags entity as changed
+-- @param[type=boolean] isdone
+-- @param new
function _M:replacedWith(isdone, new)
if not isdone then __uids[self.uid] = nil
else
@@ -179,8 +199,10 @@ function _M:replacedWith(isdone, new)
end
_M.__autoload = {}
+--- Do we delay the load for this entity or not
_M.loadNoDelay = true
--- If we are loaded we need a new uid
+-- flags entity as changed
function _M:loaded()
local ouid = self.uid
if __uids[self.uid] and __uids[self.uid] == self.uid then __uids[self.uid] = nil end
@@ -198,6 +220,7 @@ end
--- Change the entity's uid
-- <strong>*WARNING*</strong>: ONLY DO THIS IF YOU KNOW WHAT YOU ARE DOING!. YOU DO NOT !
+-- @param newuid the new uid
function _M:changeUid(newuid)
if __uids[self.uid] and __uids[self.uid] == self.uid then __uids[self.uid] = nil end
self.uid = newuid
@@ -211,10 +234,13 @@ end
--- Setup minimap color for this entity
-- You may overload this method to customize your minimap
+-- @param mo
+-- @param[type=Map] map
function _M:setupMinimapInfo(mo, map)
end
--- Adds a particles emitter following the entity
+-- @param[type=Particles] ps
function _M:addParticles(ps)
self.__particles[ps] = true
if self.x and self.y and game.level and game.level.map then
@@ -226,6 +252,12 @@ function _M:addParticles(ps)
end
--- Adds a particles emitter following the entity and duplicate it for the back
+-- calls `addParticles`() twice internally
+-- @param[type=table] def
+-- @param[type=?table] args
+-- @string[opt] shader
+-- @return back `Particles`
+-- @return front `Particles`
function _M:addParticles3D(def, args, shader)
local args1, args2 = table.clone(args or {}), table.clone(args or {})
args1.noup = 2
@@ -247,6 +279,7 @@ function _M:addParticles3D(def, args, shader)
end
--- Removes a particles emitter following the entity
+-- @param[type=Particles] ps
function _M:removeParticles(ps)
if not ps then return end
self.__particles[ps] = nil
@@ -259,6 +292,7 @@ function _M:removeParticles(ps)
end
--- Get the particle emitters of this entity
+-- @param[type=string|bool] back "all" is a valid value
function _M:getParticlesList(back)
local ps = {}
for e, _ in pairs(self.__particles) do
@@ -317,6 +351,12 @@ end
-- Do not touch unless you *KNOW* what you are doing.<br/>
-- You do *NOT* need this, this is used by the engine.Map class automatically.<br/>
-- *DO NOT TOUCH!!!*
+-- @param[type=Tiles] tiles
+-- @int idx
+-- @return[1] nil
+-- @return[2] self._mo
+-- @return[2] self.z
+-- @return[2] last_mo
function _M:makeMapObject(tiles, idx)
if idx > 1 and not tiles.use_images then return nil end
if idx > 1 then
@@ -452,16 +492,26 @@ function _M:makeMapObject(tiles, idx)
return self._mo, self.z, last_mo
end
---- Allows to alter the generated map objects
+--- Allows to alter the generated map objects
-- Does nothing by default
+-- @param[type=Tiles] tiles
+-- @param mo Map Object
+-- @param z
+-- @param last_mo last Map Object
+-- @return mo
+-- @return z
+-- @return last_mo
function _M:alterMakeMapObject(tiles, mo, z, last_mo)
return mo, z, last_mo
end
---- Get all "map objects" representing this entity
--- Do not touch unless you *KNOW* what you are doing.<br/>
--- You do *NOT* need this, this is used by the engine.Map class automatically.<br/>
+--- Get all "map objects" representing this entity
+-- Do not touch unless you *KNOW* what you are doing.
+-- You do *NOT* need this, this is used by the engine.Map class automatically.
-- *DO NOT TOUCH!!!*
+-- @param[type=Tiles] tiles
+-- @param mos map objects
+-- @int z recursive index
function _M:getMapObjects(tiles, mos, z)
local tgt = self
if self.replace_display then tgt = self.replace_display end
@@ -484,6 +534,8 @@ function _M:getMapObjects(tiles, mos, z)
self:defineDisplayCallback()
end
+--- Remove all Map objects for this entity
+-- @param[type=boolean] no_invalidate don't invalidate the map object
function _M:removeAllMOs(no_invalidate)
if self._mo and not no_invalidate then self._mo:invalidate() end
self._mo = nil
@@ -499,13 +551,13 @@ function _M:removeAllMOs(no_invalidate)
end
--- Setup movement animation for the entity
--- The entity is supposed to posses a correctly set x and y pair of fields - set to the current (new) position
+-- The entity is supposed to possess a correctly set x and y pair of fields - set to the current (new) position
-- @param oldx the coords from where the animation will seem to come from
-- @param oldy the coords from where the animation will seem to come from
-- @param speed the number of frames the animation lasts (frames are normalized to 30/sec no matter the actual FPS)
-- @param blur apply a motion blur effect of this number of frames
-- @param twitch_dir defaults to 8, the direction to do movement twitch
--- @param twitch_dir defaults to 0, the amplitude of movement twitch
+-- @param twitch defaults to 0, the amplitude of movement twitch
function _M:setMoveAnim(oldx, oldy, speed, blur, twitch_dir, twitch)
if not self._mo then return end
self._mo:setMoveAnim(oldx, oldy, self.x, self.y, speed, blur, twitch_dir, twitch)
@@ -537,6 +589,7 @@ function _M:resetMoveAnim()
end
--- Sets the flip state of MO and associated MOs
+-- @param v passed to the map object's flipX()
function _M:MOflipX(v)
if not self._mo then return end
self._mo:flipX(v)
@@ -551,6 +604,7 @@ function _M:MOflipX(v)
end
--- Sets the flip state of MO and associated MOs
+-- @param v passed to the map object's flipY()
function _M:MOflipY(v)
if not self._mo then return end
self._mo:flipY(v)
@@ -565,10 +619,12 @@ function _M:MOflipY(v)
end
--- Get the entity image as an sdl surface and texture for the given tiles and size
--- @param tiles a Tiles instance that will handle the tiles (usually pass it the current Map.tiles)
+-- @param[type=Tiles] tiles a Tiles instance that will handle the tiles (usually pass it the current Map.tiles)
-- @param w the width
-- @param h the height
--- @return the sdl surface and the texture
+-- @return[1] nil if no texture
+-- @return[2] the sdl surface
+-- @return[2] the texture
function _M:getEntityFinalSurface(tiles, w, h)
local id = w.."x"..h
if _M.__mo_final_repo[self] and _M.__mo_final_repo[self][id] then return _M.__mo_final_repo[self][id].surface, _M.__mo_final_repo[self][id].tex end
@@ -590,10 +646,11 @@ function _M:getEntityFinalSurface(tiles, w, h)
end
--- Get the entity image as an sdl texture for the given tiles and size
--- @param tiles a Tiles instance that will handle the tiles (usually pass it the current Map.tiles)
+-- @param[type=Tiles] tiles a Tiles instance that will handle the tiles (usually pass it the current Map.tiles)
-- @param w the width
-- @param h the height
--- @return the sdl texture
+-- @return[1] nil if no texture
+-- @return[2] the texture
function _M:getEntityFinalTexture(tiles, w, h)
local id = w.."x"..h
if _M.__mo_final_repo[self] and _M.__mo_final_repo[self][id] then return _M.__mo_final_repo[self][id].tex end
@@ -616,6 +673,7 @@ function _M:getEntityFinalTexture(tiles, w, h)
end
--- Get a string that will display in text the texture of this entity
+-- @string[opt] tstr
function _M:getDisplayString(tstr)
if tstr then
if core.display.FBOActive() or true then
@@ -633,12 +691,14 @@ function _M:getDisplayString(tstr)
end
--- Displays an entity somewhere on screen, outside the map
--- @param tiles a Tiles instance that will handle the tiles (usually pass it the current Map.tiles, it will if this is null)
--- @param x where to display
--- @param y where to display
--- @param w the width
--- @param h the height
--- @param a the alpha setting, defaults to 1
+-- @param[type=Tiles] tiles a Tiles instance that will handle the tiles (usually pass it the current Map.tiles, it will if this is null)
+-- @int x where to display
+-- @int y where to display
+-- @int w the width
+-- @int h the height
+-- @param[type=?number] a the alpha setting
+-- @param allow_cb
+-- @param allow_shader
function _M:toScreen(tiles, x, y, w, h, a, allow_cb, allow_shader)
local Map = require "engine.Map"
tiles = tiles or Map.tiles
@@ -652,10 +712,14 @@ function _M:toScreen(tiles, x, y, w, h, a, allow_cb, allow_shader)
core.map.mapObjectsToScreen(x, y, w, h, a, allow_cb, allow_shader, unpack(list))
end
---- Resolves an entity
--- This is called when generating the final clones of an entity for use in a level.
--- This can be used to make random enchants on objects, random properties on actors, ...
+--- Resolves an entity
+-- This is called when generating the final clones of an entity for use in a level.
+-- This can be used to make random enchants on objects, random properties on actors, ...
-- by default this only looks for properties with a table value containing a __resolver field
+-- @param[type=?table] t table defaults to self
+-- @param[type=?boolean] last resolve last
+-- @param[type=?boolean] on_entity
+-- @param[type=?table] key_chain stores keys, defaults to {}
function _M:resolve(t, last, on_entity, key_chain)
t = t or self
key_chain = key_chain or {}
@@ -699,6 +763,7 @@ function _M:resolve(t, last, on_entity, key_chain)
end
--- Print all resolvers registered
+-- @param[type=?table] t defaults to self
function _M:printResolvers(t)
for k, e in pairs(t or self) do
if type(e) == "table" and e.__resolver then
@@ -737,26 +802,28 @@ function _M:removed()
end
end
---- Check for an entity's property
+--- Check for an entity's property
-- If not a function it returns it directly, otherwise it calls the function
-- with the extra parameters
-- @param prop the property name to check
+-- @param[opt] ... the functions arguments
function _M:check(prop, ...)
if type(self[prop]) == "function" then return self[prop](self, ...)
else return self[prop]
end
end
+--- temporary values storage
_M.temporary_values_conf = {}
--- Computes a "temporary" value into a property
--- Example: You want to give an actor a boost to life_regen, but you do not want it to be permanent<br/>
+-- Example: You want to give an actor a boost to life_regen, but you do not want it to be permanent
-- You cannot simply increase life_regen, so you use this method which will increase it AND
-- store the increase. it will return an "increase id" that can be passed to removeTemporaryValue()
-- to remove the effect.
--- @param prop the property to affect. This can be either a string or a table of strings, the latter allowing nested properties to be modified.
--- @param v the value to add. This should either be a number or a table of properties and numbers.
--- @param noupdate if true the actual property is not changed and needs to be changed by the caller
+-- @param[opt=tab|string] prop the property to affect. This can be either a string or a table of strings, the latter allowing nested properties to be modified.
+-- @param[opt=number|tab] v the value to add. This should either be a number or a table of properties and numbers.
+-- @param[type=boolean] noupdate if true the actual property is not changed and needs to be changed by the caller
-- @return an id that can be passed to removeTemporaryValue() to delete this value
function _M:addTemporaryValue(prop, v, noupdate)
if not self.compute_vals then self.compute_vals = {n=0} end
@@ -856,9 +923,9 @@ function _M:addTemporaryValue(prop, v, noupdate)
end
--- Removes a temporary value, see addTemporaryValue()
--- @param prop the property to affect
--- @param id the id of the increase to delete
--- @param noupdate if true the actual property is not changed and needs to be changed by the caller
+-- @param[opt=tab|string] prop the property to affect
+-- @int id the id of the increase to delete
+-- @param[type=boolean] noupdate if true the actual property is not changed and needs to be changed by the caller
function _M:removeTemporaryValue(prop, id, noupdate)
local oldval = self.compute_vals[id]
-- print("removeTempVal", prop, oldval, " :=: ", id)
@@ -960,10 +1027,15 @@ function _M:removeTemporaryValue(prop, id, noupdate)
end
end
---- Helper function to add temporary values and not have to remove them manualy
+--- Helper function to add temporary values
+-- @param[type=table] t
+-- @param k
+-- @param v
function _M:tableTemporaryValue(t, k, v)
t[#t+1] = {k, self:addTemporaryValue(k, v)}
end
+--- Helper function to remove temporary values
+-- @param[type=table] t
function _M:tableTemporaryValuesRemove(t)
for i = 1, #t do
self:removeTemporaryValue(t[i][1], t[i][2])
@@ -985,7 +1057,9 @@ end
-- @param to the temp value added to changed_attr which we are ending on
-- @param result_attr the result we are measuring the difference in
-- @param ... arguments to pass to result_attr if it is a function
--- @return the difference, the from result, the to result
+-- @return the difference
+-- @return the from result
+-- @return the to result
function _M:getAttrChange(changed_attr, from, to, result_attr, ...)
local temp = self:addTemporaryValue(changed_attr, from)
local from_result = util.getval(self[result_attr], self, ...)
@@ -1002,9 +1076,11 @@ end
-- The attributes are just actor properties, but this ensures they are numbers and not booleans
-- thus making them compatible with temporary values system
-- @param prop the property to use
--- @param v the value to add, if nil this the function return
--- @param fix forces the value to v, do not add
--- @return nil if v was specified. If not then it returns the current value if it exists and is not 0 otherwise returns nil
+-- @param[opt] v the value to add, if nil the function returns
+-- @param[opt] fix forces the value to v, does not add
+-- @return nil if v was specified
+-- @return nil if property doesn't exist
+-- @return If v isn't specified then it returns the current value if it exists and isn't 0
function _M:attr(prop, v, fix)
if v then
if fix then self[prop] = v
@@ -1020,11 +1096,11 @@ function _M:attr(prop, v, fix)
end
--- Loads a list of entities from a definition file
--- @param file the file to load from
--- @param no_default if true then no default values will be assigned
--- @param res the table to load into, defaults to a new one
--- @param mod an optional function to which will be passed each entity as they are created. Can be used to adjust some values on the fly
--- @param loaded an optional table of already loaded files
+-- @string file the file to load from
+-- @param[type=?boolean] no_default if true then no default values will be assigned
+-- @param[type=?table] res the table to load into, defaults to a new one
+-- @func[opt] mod a function to which will be passed each entity as they are created. Can be used to adjust some values on the fly
+-- @param[type=?table] loaded a table of already loaded files
-- @usage MyEntityClass:loadList("/data/my_entities_def.lua")
function _M:loadList(file, no_default, res, mod, loaded)
local Zone = require "engine.Zone"
@@ -1110,11 +1186,14 @@ function _M:loadList(file, no_default, res, mod, loaded)
end
--- Return the kind of the entity
+-- @return "entity"
function _M:getEntityKind()
return "entity"
end
--- Putting this here to avoid errors, not sure if appropriate
+-- @string type_str
+-- @return false
function _M:checkClassification(type_str)
return false
end
diff --git a/game/engines/default/engine/Faction.lua b/game/engines/default/engine/Faction.lua
index 8b3b343b77..5bc331d54f 100644
--- a/game/engines/default/engine/Faction.lua
+++ b/game/engines/default/engine/Faction.lua
@@ -19,18 +19,20 @@
require "engine.class"
---- Defines factions
+--- Factions for actors
+-- Defines 2 factions by default: "Players", "Enemies"
+-- @classmod engine.Faction
module(..., package.seeall, class.make)
_M.factions = {}
---- Adds a new faction.
--- Static method, and can be called during load.lua.
--- @param t the table describing the faction.
--- @param t.name the name of the added faction, REQUIRED.
--- @param t.short_name the internally referenced name, defaults to lowercase t.name with "-" for spaces.
--- @param t.reaction table of initial reactions to other factions, where keys are short_names.
--- @return t.short_name see above.
+--- Adds a new faction
+-- @static
+-- @param[type=table] t the table describing the faction.
+-- @string t.name the name of the added faction
+-- @string[opt] t.short_name the internally referenced name, defaults to lowercase t.name with "-" for spaces.
+-- @param[type=?table] t.reaction table of initial reactions to other factions, where keys are short_names.
+-- @return t.short_name see above
function _M:add(t)
assert(t.name, "no faction name")
t.short_name = t.short_name or t.name:lower():gsub(" ", "-")
@@ -48,11 +50,11 @@ function _M:add(t)
end
--- Sets the initial reaction.
--- Static method, and can be called during load.lua.
--- @param f1 the source faction short_name.
--- @param f2 the target faction short_name.
--- @param reaction a numerical value representing the reaction, 0 is neutral, <0 is aggressive, >0 is friendly.
--- @param mutual if true the same status will be set for f2 toward f1.
+-- @static
+-- @string f1 the source faction short_name.
+-- @string f2 the target faction short_name.
+-- @number reaction a numerical value representing the reaction, 0 is neutral, <0 is aggressive, >0 is friendly.
+-- @param[type=boolean] mutual if true the same status will be set for f2 toward f1.
function _M:setInitialReaction(f1, f2, reaction, mutual)
-- print("[FACTION] initial", f1, f2, reaction, mutual)
-- Faction always like itself
@@ -65,17 +67,20 @@ function _M:setInitialReaction(f1, f2, reaction, mutual)
end
end
---- Returns the faction definition
+--- Gets the faction definition
+-- @static
+-- @param id
+-- @return `Faction`
function _M:get(id)
return self.factions[id]
end
---- Returns the status of faction f1 toward f2
--- @param f1 the source faction short_name.
--- @param f2 the target faction short_name.
+--- Gets the status of faction f1 toward f2
+-- @string f1 the source faction short_name
+-- @string f2 the target faction short_name
-- @return reaction a numerical value representing the reaction, 0 is neutral, <0 is aggressive, >0 is friendly.
function _M:factionReaction(f1, f2)
- -- Faction always like itself
+ -- Factions always like itself
if f1 == f2 then return 100 end
if game.factions and game.factions[f1] and game.factions[f1][f2] then return game.factions[f1][f2] end
if not self.factions[f1] then return 0 end
@@ -85,10 +90,10 @@ end
--- Sets the status of faction f1 toward f2.
-- This should only be used after the game has loaded (not in load.lua).
-- These changes will be saved to the savefile.
--- @param f1 the source faction short_name.
--- @param f2 the target faction short_name.
--- @param reaction a numerical value representing the reaction, 0 is neutral, <0 is aggressive, >0 is friendly.
--- @param mutual if true the same status will be set for f2 toward f1.
+-- @string f1 the source faction short_name.
+-- @string f2 the target faction short_name.
+-- @number reaction a value representing the reaction, 0 is neutral, <0 is aggressive, >0 is friendly.
+-- @param[type=boolean] mutual if true the same status will be set for f2 toward f1.
function _M:setFactionReaction(f1, f2, reaction, mutual)
reaction = util.bound(reaction, -100, 100)
print("[FACTION]", f1, f2, reaction, mutual)
diff --git a/game/engines/default/engine/FlyingText.lua b/game/engines/default/engine/FlyingText.lua
index c7fa8e084b..8fd5407221 100644
--- a/game/engines/default/engine/FlyingText.lua
+++ b/game/engines/default/engine/FlyingText.lua
@@ -19,8 +19,15 @@
require "engine.class"
+--- Flying Text
+-- @classmod engine.FlyingText
module(..., package.seeall, class.make)
+--- Init
+-- @string[opt="DroidSans"] fontname
+-- @int[opt=12] fontsize
+-- @string[opt="DroidSans-Bold"] bigfontname
+-- @int[opt=14] bigfontsize
function _M:init(fontname, fontsize, bigfontname, bigfontsize)
self.font = core.display.newFont(fontname or "/data/font/DroidSans.ttf", fontsize or 12)
self.bigfont = core.display.newFont(bigfontname or "/data/font/DroidSans-Bold.ttf", bigfontsize or 14)
@@ -28,10 +35,21 @@ function _M:init(fontname, fontsize, bigfontname, bigfontsize)
self.flyers = {}
end
+--- @param[type=boolean] v enable the shadowssss
function _M:enableShadow(v)
self.shadow = v
end
+--- Add a new flying text
+-- @int x x position
+-- @int y y position
+-- @int[opt=10] duration
+-- @param[type=?number] xvel horizontal velocity
+-- @param[type=?number] yvel vertical velocity
+-- @string str what the text says
+-- @param[type=?table] color color of the text, defaults to colors.White
+-- @param[type=?boolean] bigfont use the big font?
+-- @return `FlyingText`
function _M:add(x, y, duration, xvel, yvel, str, color, bigfont)
if not x or not y or not str then return end
color = color or {255,255,255}
@@ -54,10 +72,13 @@ function _M:add(x, y, duration, xvel, yvel, str, color, bigfont)
return f
end
+--- Removes all FlyingText
function _M:empty()
self.flyers = {}
end
+--- Display loop function
+-- @int nb_keyframes
function _M:display(nb_keyframes)
if not next(self.flyers) then return end
diff --git a/game/engines/default/engine/FontPackage.lua b/game/engines/default/engine/FontPackage.lua
index 5129ef6599..78a2891b0c 100644
--- a/game/engines/default/engine/FontPackage.lua
+++ b/game/engines/default/engine/FontPackage.lua
@@ -19,12 +19,16 @@
require "engine.class"
---- Configure sets of fonts
+--- Define and load fonts
+-- @classmod engine.FontPackage
module(..., package.seeall, class.make)
+--- All of the packages
local packages = {}
--- Loads lore
+-- @string file
+-- @param env
function _M:loadDefinition(file, env)
local f, err = loadfile(file)
if not f and err then error(err) end
@@ -35,17 +39,27 @@ function _M:loadDefinition(file, env)
f()
end
+--- Default font style, "normal"
local cur_size = "normal"
+--- @string size "normal", "bold", etc
function _M:setDefaultSize(size)
cur_size = size
end
+--- Default font id, "default"
local cur_id = "default"
+--- Set default font to use
+-- @string id if it can't find it, then the font will be "basic"
function _M:setDefaultId(id)
if not packages[id] then id = "basic" end
cur_id = id
end
+--- Resolves a font
+-- @string name
+-- @string orname
+-- @return font object
+-- @return size
function _M:resolveFont(name, orname)
local font = packages[cur_id]
local size = cur_size
@@ -55,11 +69,20 @@ function _M:resolveFont(name, orname)
return font[name], size
end
+--- Fetches the actual font by calling `resolveFont`() internally
+-- @string name
+-- @string orname
+-- @return font
+-- @return size
function _M:getFont(name, orname)
local font, size = self:resolveFont(name, orname)
return font.font, font[size]
end
+--- Get by name.
+-- @bug orname is used but not defined
+-- @string name
+-- @param[type=?boolean] force make a font bold no matter what
function _M:get(name, force)
local font, size = self:resolveFont(name, orname)
local f = core.display.newFont(font.font, font[size], font.bold or force)
@@ -67,6 +90,7 @@ function _M:get(name, force)
return f
end
+--- List all fonts
function _M:list()
local list = {}
for _, f in pairs(packages) do list[#list+1] = f end
@@ -74,6 +98,10 @@ function _M:list()
return list
end
+--- Initialize font package
+-- @param[type=table] t
+-- @string t.id package id
+-- @string t.default default font
function _M:init(t)
assert(t.id, "no font package id")
assert(t.default, "no font package default")
diff --git a/game/engines/default/engine/Game.lua b/game/engines/default/engine/Game.lua
index daec090997..42cf47ffa3 100644
--- a/game/engines/default/engine/Game.lua
+++ b/game/engines/default/engine/Game.lua
@@ -23,13 +23,14 @@ require "engine.DebugConsole"
local tween = require "tween"
local Shader = require "engine.Shader"
---- Represent a game
+--- Represents a game
-- A module should subclass it and initialize anything it needs to play inside
+-- @classmod engine.Game
module(..., package.seeall, class.make)
---- Constructor
--- Sets up the default keyhandler.
+--- Sets up the default keyhandler
-- Also requests the display size and stores it in "w" and "h" properties
+-- @param[type=Key] keyhandler the default keyhandler for this game
function _M:init(keyhandler)
self.key = keyhandler
self.level = nil
@@ -48,7 +49,9 @@ function _M:init(keyhandler)
self:defaultMouseCursor()
end
+--- Log a message
function _M:log() end
+--- Log something that was seen
function _M:logSeen() end
--- Default mouse cursor
@@ -61,6 +64,11 @@ function _M:defaultMouseCursor()
end
end
+--- Sets the mouse cursor
+-- @string mouse image for mouse
+-- @string[opt] mouse_down image for mouse click
+-- @number offsetx
+-- @number offsety
function _M:setMouseCursor(mouse, mouse_down, offsetx, offsety)
if type(mouse) == "string" then mouse = core.display.loadImage(mouse) end
if type(mouse_down) == "string" then mouse_down = core.display.loadImage(mouse_down) end
@@ -74,6 +82,7 @@ function _M:setMouseCursor(mouse, mouse_down, offsetx, offsety)
end
end
+--- Called whenever the cursor needs updating
function _M:updateMouseCursor()
if self.__cursor then
if config.settings.mouse_cursor then
@@ -84,6 +93,7 @@ function _M:updateMouseCursor()
end
end
+--- Called when the game is loaded
function _M:loaded()
self.w, self.h, self.fullscreen = core.display.size()
self.dialogs = {}
@@ -97,6 +107,8 @@ function _M:loaded()
end
--- Defines the default fields to be saved by the savefile code
+-- @param[type=table] t additional definitions to save
+-- @return table of definitions
function _M:defaultSavedFields(t)
local def = {
w=true, h=true, zone=true, player=true, level=true, entities=true,
@@ -112,12 +124,13 @@ function _M:defaultSavedFields(t)
end
--- Sets the player name
+-- @string name
function _M:setPlayerName(name)
self.save_name = name
self.player_name = name
end
---- Do not touch
+--- Do not touch!!
function _M:prerun()
if self.__persistent_hooks then for _, h in ipairs(self.__persistent_hooks) do
self:bindHook(h.hook, h.fct)
@@ -129,13 +142,14 @@ end
function _M:run()
end
---- Checks if the current character is "tainted" by cheating
+--- Checks if the current character is "tainted" by cheating
+-- @return false by default
function _M:isTainted()
return false
end
--- Sets the current level
--- @param level an engine.Level (or subclass) object
+-- @param level a `Level` (or subclass) object
function _M:setLevel(level)
self.level = level
end
@@ -186,13 +200,15 @@ function _M:display(nb_keyframes)
end
--- Register a timer
--- The callback function will be called in the given number of seconds
+-- @int seconds will be called in the given number of seconds
+-- @func cb the callback function
function _M:registerTimer(seconds, cb)
self._timers_cb = self._timers_cb or {}
self._timers_cb[cb] = seconds * 30
end
--- Called when the game is focused/unfocused
+-- @param[type=boolean] focus are we focused?
function _M:idling(focus)
self.has_os_focus = focus
-- print("Game got focus/unfocus", focus)
@@ -209,7 +225,8 @@ function _M:handleEvents()
end
--- Receives a profile event
--- Usualy this just transfers it to the PlayerProfile class but you can overload it to handle special stuff
+-- Usually this just transfers it to the PlayerProfile class but you can overload it to handle special stuff
+-- @param evt the event
function _M:handleProfileEvent(evt)
return profile:handleEvent(evt)
end
@@ -218,24 +235,28 @@ end
-- Reimplement it in your module, this can just return nil if you dont want/need
-- the engine adjusting stuff to the player or if you have many players or whatever
-- @param main if true the game should try to return the "main" player, if any
+-- @return nil by default
function _M:getPlayer(main)
return nil
end
--- Returns current "campaign" name
--- Defaults to "default"
+-- @return "default" by default
function _M:getCampaign()
return "default"
end
--- Says if this savefile is usable or not
-- Reimplement it in your module, returning false when the player is dead
+-- @return true by default
function _M:isLoadable()
return true
end
--- Gets/increment the savefile version
--- @param token if "new" this will create a new allowed save token and return it. Otherwise this checks the token against the allowed ones and returns true if it is allowed
+-- @param[opt] token if "new" this will create a new allowed save token and return it. Otherwise this checks the token against the allowed ones and returns true if it is allowed
+-- @return uuid
+-- @return true
function _M:saveVersion(token)
if token == "new" then
token = util.uuid()
@@ -282,7 +303,7 @@ function _M:tick()
end
--- Run all registered tick end functions
--- Usualy jsut let the engine call it
+-- Usually just let the engine call it
function _M:onTickEndExecute()
if self.on_tick_end and #self.on_tick_end > 0 then
local fs = self.on_tick_end
@@ -293,6 +314,8 @@ function _M:onTickEndExecute()
end
--- Register things to do on tick end
+-- @func f function to do on tick end
+-- @string name callback to reference the function
function _M:onTickEnd(f, name)
self.on_tick_end = self.on_tick_end or {}
@@ -306,7 +329,9 @@ function _M:onTickEnd(f, name)
end
--- Called when a zone leaves a level
--- Going from "old_lev" to "lev", leaving level "level"
+-- @param level the level we're leaving
+-- @param lev the new level
+-- @param old_lev the old level (probably same value as level)
function _M:leaveLevel(level, lev, old_lev)
end
@@ -320,12 +345,14 @@ function _M:onExit()
core.game.exit_engine()
end
---- Sets up a text flyers
+--- Sets up a `FlyingText` for general use
+-- @param[type=FlyingText] fl
function _M:setFlyingText(fl)
self.flyers = fl
end
--- Registers a dialog to display
+-- @param[type=Dialog] d
function _M:registerDialog(d)
table.insert(self.dialogs, d)
self.dialogs[d] = #self.dialogs
@@ -336,9 +363,9 @@ function _M:registerDialog(d)
if self.onRegisterDialog then self:onRegisterDialog(d) end
end
---- Registers a dialog to display somewher in the stack
--- @param d the dialog
--- @param pos the stack position (1=top, 2=second, ...)
+--- Registers a dialog to display somewhere in the stack
+-- @param[type=Dialog] d
+-- @int pos the stack position (1=top, 2=second, ...)
function _M:registerDialogAt(d, pos)
if pos == 1 then return self:registerDialog(d) end
table.insert(self.dialogs, #self.dialogs - (pos - 2), d)
@@ -351,7 +378,9 @@ function _M:registerDialogAt(d, pos)
if self.onRegisterDialog then self:onRegisterDialog(d) end
end
---- Replaces a dialog to display with an other
+--- Replaces a dialog to display with another
+-- @param[type=Dialog] src old dialog
+-- @param[type=Dialog] dest new dialog
function _M:replaceDialog(src, dest)
local id = src.__stack_id
@@ -372,6 +401,7 @@ function _M:replaceDialog(src, dest)
end
--- Undisplay a dialog, removing its own keyhandler if needed
+-- @param[type=Dialog] d
function _M:unregisterDialog(d)
if not self.dialogs[d] then return end
table.remove(self.dialogs, self.dialogs[d])
@@ -389,17 +419,20 @@ function _M:unregisterDialog(d)
end
--- Do we have a specific dialog
+-- @param[type=Dialog] d
function _M:hasDialog(d)
return self.dialogs[d] and true or false
end
---- Do we have a dialog running
+--- Do we have a dialog(s) running
+-- @int[opt=0] nb how many dialogs minimum
function _M:hasDialogUp(nb)
nb = nb or 0
return #self.dialogs > nb
end
--- The C core gives us command line arguments
+-- @param[type=table] args filled in by the C core
function _M:commandLineArgs(args)
for i, a in ipairs(args) do
print("Command line: ", a)
@@ -407,6 +440,7 @@ function _M:commandLineArgs(args)
end
--- Called by savefile code to describe the current game
+-- @return table
function _M:getSaveDescription()
return {
name = "player",
@@ -415,6 +449,8 @@ function _M:getSaveDescription()
end
--- Save a settings file
+-- @string file
+-- @param data
function _M:saveSettings(file, data)
core.game.resetLocale()
local restore = fs.getWritePath()
@@ -442,6 +478,9 @@ available_resolutions =
-- ["1200x1024 Fullscreen"] = {1200, 1024, true},
-- ["1600x1200 Fullscreen"] = {1600, 1200, true},
}
+--- Get the available display modes for the monitor from the core
+-- @function list
+-- @local
local list = core.display.getModesList()
for _, m in ipairs(list) do
local ms = m.w.."x"..m.h.." Fullscreen"
@@ -451,6 +490,8 @@ for _, m in ipairs(list) do
end
--- Change screen resolution
+-- @string res should be in format like "800x600 Windowed"
+-- @param[type=boolean] force try to force the resolution if it can't find it
function _M:setResolution(res, force)
local r = available_resolutions[res]
if force and not r then
@@ -561,11 +602,17 @@ function _M:onResolutionChange()
end
--- Checks if we must reload to change resolution
+-- @int w width
+-- @int h height
+-- @int ow original width
+-- @int oh original height
function _M:checkResolutionChange(w, h, ow, oh)
return false
end
--- Called when the game window is moved around
+-- @int x x coordinate
+-- @int y y coordinate
function _M:onWindowMoved(x, y)
config.settings.window.pos = config.settings.window.pos or {}
config.settings.window.pos.x = x
@@ -577,12 +624,12 @@ function _M:onWindowMoved(x, y)
end
--- Update any registered video options dialogs with the latest changes.
+--
+-- Note: If the title of the video options dialog changes, this
+-- functionality will break.
function _M:updateVideoDialogs()
-- Update the video settings dialogs if any are registered.
-- We don't know which dialog (if any) is VideoOptions, so iterate through.
- --
- -- Note: If the title of the video options dialog changes, this
- -- functionality will break.
for i, v in ipairs(self.dialogs) do
if v.title == "Video Options" then
v.c_list:drawTree()
@@ -592,6 +639,7 @@ end
--- Sets the gamma of the window
-- By default it uses SDL gamma settings, but it can also use a fullscreen shader if available
+-- @param gamma
function _M:setGamma(gamma)
if self.support_shader_gamma and self.full_fbo_shader then
-- Tell the shader which gamma to use
@@ -615,18 +663,22 @@ end
--- Add a coroutine to the pool
-- Coroutines registered will be run each game tick
+-- @param id the id
+-- @thread co the coroutine
function _M:registerCoroutine(id, co)
print("[COROUTINE] registering", id, co)
self.__coroutines[id] = co
end
--- Get the coroutine corresponding to the id
+-- @param id the id
function _M:getCoroutine(id)
return self.__coroutines[id]
end
--- Ask a registered coroutine to cancel
-- The coroutine must accept a "cancel" action
+-- @param id the id
function _M:cancelCoroutine(id)
local co = self.__coroutines[id]
if not co then return end
@@ -643,7 +695,8 @@ function _M:cancelCoroutine(id)
end
--- Take a screenshot of the game
--- @param for_savefile The screenshot will be used for savefile display
+-- @param[type=boolean] for_savefile The screenshot will be used for savefile display
+-- @return screenshot
function _M:takeScreenshot(for_savefile)
if for_savefile then
self.suppressDialogs = true
@@ -657,8 +710,7 @@ function _M:takeScreenshot(for_savefile)
end
end
---- Take a screenshot of the game
--- @param for_savefile The screenshot will be used for savefile display
+--- Take a screenshot of the game and saves it to the screenshots folder
function _M:saveScreenshot()
local s = self:takeScreenshot()
if not s then return end
@@ -682,6 +734,8 @@ end
--- Register a hook that will be saved in the savefile
-- Obviously only run it once per hook per save
+-- @string hook the hook to run on
+-- @func fct the function to run
function _M:registerPersistentHook(hook, fct)
self.__persistent_hooks = self.__persistent_hooks or {}
table.insert(self.__persistent_hooks, {hook=hook, fct=fct})
@@ -689,6 +743,8 @@ function _M:registerPersistentHook(hook, fct)
end
-- get a text-compatible texture for a game entity (overload in module)
+-- @param[type=Entity] en
+-- @return ""
function _M:getGenericTextTiles(en)
return ""
end
diff --git a/game/engines/default/engine/GameEnergyBased.lua b/game/engines/default/engine/GameEnergyBased.lua
index af99487d9d..9e49bcbaa5 100644
--- a/game/engines/default/engine/GameEnergyBased.lua
+++ b/game/engines/default/engine/GameEnergyBased.lua
@@ -20,15 +20,16 @@
require "engine.class"
require "engine.Game"
---- A game type that gives each entities energy
+--- A game type that gives each entities energy
-- When an entity reaches an energy level it is allowed to act (it calls the entity"s "act" method)
-- @inherit engine.Game
+-- @classmod engine.GameEnergyBased
module(..., package.seeall, class.inherit(engine.Game))
--- Setup the game
--- @param keyhandler the default keyhandler for this game
--- @energy_to_act how much energy does an entity need to act
--- @energy_per_tick how much energy does an entity receives per game tick. This is multiplied by the entity energy.mod property
+-- @param[type=Key] keyhandler the default keyhandler for this game
+-- @number energy_to_act how much energy does an entity need to act
+-- @number energy_per_tick how much energy does an entity receives per game tick. This is multiplied by the entity energy.mod property
function _M:init(keyhandler, energy_to_act, energy_per_tick)
self.energy_to_act, self.energy_per_tick = energy_to_act or 1000, energy_per_tick or 100
engine.Game.init(self, keyhandler)
@@ -38,6 +39,7 @@ function _M:init(keyhandler, energy_to_act, energy_per_tick)
self:loaded()
end
+--- The function called after the game has loaded
function _M:loaded()
engine.Game.loaded(self)
@@ -53,7 +55,7 @@ function _M:loaded()
setmetatable(self.entities, {__mode="v"})
end
---- Gives energy and act if needed
+--- Give energy and act if needed
function _M:tick()
engine.Game.tick(self)
@@ -89,6 +91,7 @@ function _M:tick()
end
--- Run tick on a level
+-- @param[type=Level] level
function _M:tickLevel(level)
local i, e = 1, nil
local arr = level.e_array
@@ -145,6 +148,7 @@ end
-- This differs from Level:addEntity in that it's not specific to actors and the entities are not bound to
-- the current level. Also they are stored in a *WEAK* table, so this wont hold them from garbage
-- collecting if they are not
+-- @param[type=Entity] e
function _M:addEntity(e)
if not e.canAct or not e:canAct() then return end
if self.entities[e.uid] and self.entities[e.uid] ~= e then error("Entity "..e.uid.." already present in the game and not the same") end
@@ -152,6 +156,7 @@ function _M:addEntity(e)
end
--- Removes an entity from the game
+-- @param[type=Entity] e
function _M:removeEntity(e)
if not e.canAct or not e:canAct() then return end
if not self.entities[e.uid] then error("Entity "..e.uid.." not present in the game") end
@@ -159,6 +164,7 @@ function _M:removeEntity(e)
end
--- Does the game have this entity ?
+-- @param[type=Entity] e
function _M:hasEntity(e)
return self.entities[e.uid]
end
diff --git a/game/engines/default/engine/GameTurnBased.lua b/game/engines/default/engine/GameTurnBased.lua
index 1f3213d3e9..143b5dff61 100644
--- a/game/engines/default/engine/GameTurnBased.lua
+++ b/game/engines/default/engine/GameTurnBased.lua
@@ -20,21 +20,26 @@
require "engine.class"
require "engine.GameEnergyBased"
---- Defines a turn based game
--- If this class is not used the game is realtime.
--- This game type pauses the ticking as long as its paused property is true.<br/>
+--- Defines a turn based game.
+-- If this class is not used the game is realtime.
+-- This game type pauses the ticking as long as its paused property is true.
-- To use it make your player "act" method set the game property paused to true and when an action is made to false
-- @inherit engine.GameEnergyBased
+-- @classmod engine.GameTurnBased
module(..., package.seeall, class.inherit(engine.GameEnergyBased))
can_pause = true
---- See engine.GameEnergyBased
+--- @see engine.GameEnergyBased
+-- @param[type=Key] keyhandler
+-- @number energy_to_act
+-- @number energy_per_tick
function _M:init(keyhandler, energy_to_act, energy_per_tick)
self.paused = false
engine.GameEnergyBased.init(self, keyhandler, energy_to_act, energy_per_tick)
end
+--- main game loop
function _M:tick()
if self.paused then
-- Auto unpause if the player has no energy to act
diff --git a/game/engines/default/engine/Generator.lua b/game/engines/default/engine/Generator.lua
index aaa08cd582..435fdec78d 100644
--- a/game/engines/default/engine/Generator.lua
+++ b/game/engines/default/engine/Generator.lua
@@ -18,8 +18,16 @@
-- darkgod@te4.org
require "engine.class"
+
+--- Genric generator
+-- @classmod engine.Generator
module(..., package.seeall, class.make)
+--- Init
+-- @param[type=Zone] zone
+-- @param[type=Map] map
+-- @param[type=Level] level
+-- @param[type=table] spots
function _M:init(zone, map, level, spots)
self.zone = zone
self.map = map
@@ -38,9 +46,16 @@ function _M:init(zone, map, level, spots)
end
end
+--- Override this in your generator
function _M:generate()
end
+--- Resolve
+-- @param[type=string|table|function] c a function or table to resolve
+-- @param[type=table] list list to resolve
+-- @param[type=boolean] force force the value of c to be used
+-- @return[1] nil
+-- @return[2] res
function _M:resolve(c, list, force)
local res = force and c or self.data[c]
if type(res) == "function" then
@@ -61,6 +76,11 @@ function _M:resolve(c, list, force)
return res
end
+--- Add entity to a room of a map
+-- @param i
+-- @param j
+-- @param type
+-- @param e
function _M:roomMapAddEntity(i, j, type, e)
self.map.room_map[i] = self.map.room_map[i] or {}
self.map.room_map[i][j] = self.map.room_map[i][j] or {}
@@ -70,33 +90,49 @@ function _M:roomMapAddEntity(i, j, type, e)
e:added() -- we do it here to make sure uniques are uniques
end
+--- Class Gridlist
local Gridlist = class.make{}
+--- Create a new gridlist
+-- @return Gridlist
function _M:makeGridList()
return Gridlist.new()
end
+--- Gridlist initializer
function Gridlist:init()
self.list = {}
end
+--- Add a new entry to gridlist
+-- @number x x coordinate
+-- @number y y coordinate
+-- @param data
function Gridlist:add(x, y, data)
if data == nil then data = true end
if not self.list[x] then self.list[x] = {} end
self.list[x][y] = data
end
+--- Remove entry from gridlist
+-- @number x x coordinate
+-- @number y y coordinate
function Gridlist:remove(x, y)
if not self.list[x] then return end
self.list[x][y] = nil
if not next(self.list[x]) then self.list[x] = nil end
end
+--- Check if gridlist has anything at specified coordinates
+-- @number x x coordinate
+-- @number y y coordinate
function Gridlist:has(x, y)
if not self.list[x] then return end
return self.list[x][y]
end
+--- Turn the gridlist into an easily parsed table
+-- @return {{x, y, data}, ...}
function Gridlist:toList()
local list = {}
for x, yy in pairs(self.list) do for y, data in pairs(yy) do
@@ -105,6 +141,8 @@ function Gridlist:toList()
return list
end
+--- How many items does our gridlist have??
+-- @return number
function Gridlist:count()
local nb = 0
for x, yy in pairs(self.list) do for y, data in pairs(yy) do
diff --git a/game/engines/default/engine/Grid.lua b/game/engines/default/engine/Grid.lua
index 7f485d7bdb..c1fb30ce4a 100644
--- a/game/engines/default/engine/Grid.lua
+++ b/game/engines/default/engine/Grid.lua
@@ -20,6 +20,8 @@
require "engine.class"
local Entity = require "engine.Entity"
+--- Grid
+-- @classmod engine.Grid
module(..., package.seeall, class.inherit(Entity))
-- When used on the map, do not draw alpha channel
diff --git a/game/engines/default/engine/Heightmap.lua b/game/engines/default/engine/Heightmap.lua
index 4421d4284d..f3754a9e6f 100644
--- a/game/engines/default/engine/Heightmap.lua
+++ b/game/engines/default/engine/Heightmap.lua
@@ -19,14 +19,19 @@
require "engine.class"
---- Heightmap fractal generator
+--- Heightmap fractal generator
-- This can be used to create rooms, levels, world maps, whatever
+-- @classmod engine.Heightmap
module(..., package.seeall, class.make)
_M.max = 100000
_M.min = 0
--- Creates the fractal generator for the specified heightmap size
+-- @number w width
+-- @number h height
+-- @number[opt=1.2] roughness how rough
+-- @param[type=?table] start
function _M:init(w, h, roughness, start)
self.w = w
self.h = h
@@ -46,6 +51,7 @@ function _M:init(w, h, roughness, start)
end
--- Actually creates the heightmap
+-- @return table
function _M:generate()
local rects = {}
@@ -94,6 +100,8 @@ function _M:generate()
return self.hmap
end
+--- heightmap as symbols
+-- @string[opt="abcdefghijklmnopqrstwxyzABCDEFGHIJKLMNOPQRSTWXYZ"] symbs
function _M:displayDebug(symbs)
symbs = symbs or "abcdefghijklmnopqrstwxyzABCDEFGHIJKLMNOPQRSTWXYZ"
print("Displaying heightmap", self.w, self.h)
diff --git a/game/engines/default/engine/HighScores.lua b/game/engines/default/engine/HighScores.lua
index 456f204bb0..b36e2ca04c 100644
--- a/game/engines/default/engine/HighScores.lua
+++ b/game/engines/default/engine/HighScores.lua
@@ -20,39 +20,47 @@
require "engine.class"
local Map = require "engine.Map"
---- Define high score table support
----
---- This will eventually actually generate a GUI table and handle
---- filtering etc but for now it just generates a text string which
---- represents the list of high scores.
-
+--- Define high score table support
+-- This will eventually actually generate a GUI table and handle
+-- filtering etc but for now it just generates a text string which
+-- represents the list of high scores.
+-- @classmod engine.HighScores
module(..., package.seeall, class.make)
---- to call these you need to have profile.mod pointing at the right module
---- that's normally automatic? But the code which runs from the 'boot'
---- module sets it up carefully
+--- to call these you need to have profile.mod pointing at the right module
+-- that's normally automatic? But the code which runs from the 'boot' module sets it up carefully
--- register a highscore against a campaign
+--- register a highscore against a campaign
+-- @param[type=World] world the world
+-- @param[type=table] details
function registerScore(world,details)
details.type = "dead"
profile:saveModuleProfile("scores", details)
end
--- scores of living players are stored against their name
+--- scores of living players are stored against their name
+--- register a highscore against a campaign
+-- @param[type=World] world the world
+-- @string name name of the character
+-- @param[type=table] details
function noteLivingScore(world,name,details)
details.type = "alive"
profile:saveModuleProfile("scores", details)
end
--- and should be removed when the char dies
+--- and should be removed when the char dies
+-- @param[type=World] world the world
+-- @string name
function clearLivingScore(world,name)
-- don't know how to write this
-- don't know how to remove from the profile
end
-
+--- Format the highscore table as a string
+-- @param[type=World] world the world
+-- @param[type=table] formatters
function createHighScoreTable(world,formatters)
local highscores = ""
print ("createHighScoreTable called with world : ",world)
diff --git a/game/engines/default/engine/HotkeysDisplay.lua b/game/engines/default/engine/HotkeysDisplay.lua
index 7fdc227cf5..e2ecbbdc75 100644
--- a/game/engines/default/engine/HotkeysDisplay.lua
+++ b/game/engines/default/engine/HotkeysDisplay.lua
@@ -19,8 +19,19 @@
require "engine.class"
+--- Hotkeys Display
+-- @classmod engine.HotkeysDisplay
module(..., package.seeall, class.make)
+--- Init
+-- @param[type=Actor] actor
+-- @number x x coordinate
+-- @number y y coordinate
+-- @number w width
+-- @number h height
+-- @param[type=table] bgcolor background color
+-- @string[opt="DroidSansMono"] fontname
+-- @number[opt=10] fontsize
function _M:init(actor, x, y, w, h, bgcolor, fontname, fontsize)
self.actor = actor
if type(bgcolor) ~= "string" then
@@ -44,11 +55,16 @@ function _M:setColumns(nb)
self.nb_cols = nb
end
+--- Enable our shadows??
function _M:enableShadow(v)
self.shadow = v
end
--- Resize the display area
+-- @number x x coordinate
+-- @number y y coordinate
+-- @number w width
+-- @number h height
function _M:resize(x, y, w, h)
self.display_x, self.display_y = math.floor(x), math.floor(y)
self.w, self.h = math.floor(w), math.floor(h)
@@ -70,7 +86,7 @@ end
local page_to_hotkey = {"", "SECOND_", "THIRD_", "FOURTH_", "FIFTH_"}
--- Displays the hotkeys, keybinds & cooldowns
+--- Displays the hotkeys, keybinds & cooldowns
function _M:display()
local a = self.actor
if not a or not a.changed then return self.surface end
@@ -151,6 +167,7 @@ function _M:display()
end
end
+--- To screen function override
function _M:toScreen()
self:display()
if self.bg_texture then self.bg_texture:toScreenFull(self.display_x, self.display_y, self.w, self.h, self.bg_texture_w, self.bg_texture_h) end
@@ -162,8 +179,14 @@ function _M:toScreen()
end
end
---- Call when a mouse event arrives in this zone
+--- Call when a mouse event arrives in this zone
-- This is optional, only if you need mouse support
+-- @string button
+-- @number mx mouse x
+-- @number my mouse y
+-- @param[type=boolean] click did they click
+-- @param[type=function] on_over callback for hover
+-- @param[type=function] on_click callback for click
function _M:onMouse(button, mx, my, click, on_over, on_click)
local a = self.actor
diff --git a/game/engines/default/engine/HotkeysIconsDisplay.lua b/game/engines/default/engine/HotkeysIconsDisplay.lua
index a27ad07149..fa13a5fba9 100644
--- a/game/engines/default/engine/HotkeysIconsDisplay.lua
+++ b/game/engines/default/engine/HotkeysIconsDisplay.lua
@@ -23,8 +23,21 @@ local Entity = require "engine.Entity"
local Tiles = require "engine.Tiles"
local UI = require "engine.ui.Base"
+--- Display of hotkeys with icons
+-- @classmod engine.HotkeysIconsDisplay
module(..., package.seeall, class.make)
+--- Init
+-- @param[type=Actor] actor
+-- @number x x coordinate
+-- @number y y coordinate
+-- @number w width
+-- @number h height
+-- @param[type=table] bgcolor background color
+-- @string[opt="DroidSansMono"] fontname
+-- @number[opt=10] fontsize
+-- @number icon_w icon width
+-- @number icon_h icon height
function _M:init(actor, x, y, w, h, bgcolor, fontname, fontsize, icon_w, icon_h)
self.actor = actor
if type(bgcolor) ~= "string" then
@@ -61,11 +74,18 @@ end
function _M:setColumns(nb)
end
+--- Enable our shadows
function _M:enableShadow(v)
self.shadow = v
end
--- Resize the display area
+-- @number x x coordinate
+-- @number y y coordinate
+-- @number w width
+-- @number h height
+-- @number iw icon width
+-- @number ih icon height
function _M:resize(x, y, w, h, iw, ih)
self.display_x, self.display_y = math.floor(x), math.floor(y)
self.w, self.h = math.floor(w), math.floor(h)
@@ -260,6 +280,7 @@ function _M:display()
end end
end
+--- Our toScreen override
function _M:toScreen()
self:display()
local shader = Shader.default.textoutline and Shader.default.textoutline.shad
@@ -303,8 +324,14 @@ function _M:toScreen()
end
end
---- Call when a mouse event arrives in this zone
+--- Call when a mouse event arrives in this zone
-- This is optional, only if you need mouse support
+-- @string button
+-- @number mx mouse x
+-- @number my mouse y
+-- @param[type=boolean] click did they click
+-- @param[type=function] on_over callback for hover
+-- @param[type=function] on_click callback for click
function _M:onMouse(button, mx, my, click, on_over, on_click)
local orient = self.orient or "down"
mx, my = mx - self.display_x, my - self.display_y
diff --git a/game/engines/default/engine/Key.lua b/game/engines/default/engine/Key.lua
index 15c42e3376..7781b55463 100644
--- a/game/engines/default/engine/Key.lua
+++ b/game/engines/default/engine/Key.lua
@@ -21,302 +21,568 @@ require "engine.class"
--- Basic keypress handler
-- The engine calls receiveKey when a key is pressed
+-- @classmod engine.Key
module(..., package.seeall, class.make)
+--- Init
function _M:init()
self.status = {}
end
--- Called when a key is pressed
--- @param sym a number representing the key, see all the _FOO fields
--- @param ctrl is the control key pressed?
--- @param shift is the shit key pressed?
--- @param alt is the alt key pressed?
--- @param meta is the meta key pressed?
+-- @number sym a number representing the key, see all the _FOO fields
+-- @param[type=boolean] ctrl is the control key pressed?
+-- @param[type=boolean] shift is the shit key pressed?
+-- @param[type=boolean] alt is the alt key pressed?
+-- @param[type=boolean] meta is the meta key pressed?
-- @param unicode the unicode representation of the key, if possible
--- @param isup true if the key was released, false if pressed
--- @param key the unicode representation of the key pressed (without accounting for modifiers)
+-- @param[type=boolean] isup true if the key was released, false if pressed
+-- @string key the unicode representation of the key pressed (without accounting for modifiers)
function _M:receiveKey(sym, ctrl, shift, alt, meta, unicode, isup, key)
self:handleStatus(sym, ctrl, shift, alt, meta, unicode, isup)
end
--- Called when a key is pressed, gives raw codes
+-- @param[type=boolean] isup false if pressed, true if released
+-- @number scancode
+-- @number sym a number representing the key, see all the _FOO fields
+-- @param unicode the unicode representation of the key, if possible
+-- @param[type=boolean] ctrl is the control key pressed?
+-- @param[type=boolean] shift is the shit key pressed?
+-- @param[type=boolean] alt is the alt key pressed?
+-- @param[type=boolean] meta is the meta key pressed?
function _M:receiveKeyRaw(isup, scancode, sym, unicode, ctrl, shift, alt, meta)
end
--- Called when a gamepad key is pressed
-- @param button the id
--- @param isup false if pressed true if released
+-- @param[type=boolean] isup false if pressed, true if released
function _M:receiveJoyButton(button, isup)
-- print("==joy button", button, isup)
end
--- Maintain the self.status table, which can be used to know if a key is currently pressed
+-- @number sym a number representing the key, see all the _FOO fields
+-- @param[type=boolean] ctrl is the control key pressed?
+-- @param[type=boolean] shift is the shit key pressed?
+-- @param[type=boolean] alt is the alt key pressed?
+-- @param[type=boolean] meta is the meta key pressed?
+-- @param unicode the unicode representation of the key, if possible
+-- @param[type=boolean] isup false if pressed, true if released
function _M:handleStatus(sym, ctrl, shift, alt, meta, unicode, isup)
self.status[sym] = not isup
end
---- Setups as the current game keyhandler
+--- Setup as the current game keyhandler
function _M:setCurrent()
core.key.set_current_handler(self)
-- if game then game.key = self end
_M.current = self
end
+-- This regex takes the fields below, and adds doc comments for all of them
+-- You'll need to remove the comments below before you use the regex though
+-- Regex: /(_*[\S]*)\s*=\s*(-?[\d]*)/g
+-- Subst: --- @field $1 $2 \n$1 = $2
+-- A lazy solution to remove the comments would be to use the following:
+-- Regex: /(?:(_*[\S]*)\s*(=)\s*(-?[\d]*))|(--- @field\s+_+[\S]*\s+-?[\d]*)/g
+-- Subst: $1 $2 $3
+
+--- @field _UNKNOWN 0
_UNKNOWN = 0
+--- @field _a 4
_a = 4
+--- @field _b 5
_b = 5
+--- @field _c 6
_c = 6
+--- @field _d 7
_d = 7
+--- @field _e 8
_e = 8
+--- @field _f 9
_f = 9
+--- @field _g 10
_g = 10
+--- @field _h 11
_h = 11
+--- @field _i 12
_i = 12
+--- @field _j 13
_j = 13
+--- @field _k 14
_k = 14
+--- @field _l 15
_l = 15
+--- @field _m 16
_m = 16
+--- @field _n 17
_n = 17
+--- @field _o 18
_o = 18
+--- @field _p 19
_p = 19
+--- @field _q 20
_q = 20
+--- @field _r 21
_r = 21
+--- @field _s 22
_s = 22
+--- @field _t 23
_t = 23
+--- @field _u 24
_u = 24
+--- @field _v 25
_v = 25
+--- @field _w 26
_w = 26
+--- @field _x 27
_x = 27
+--- @field _y 28
_y = 28
+--- @field _z 29
_z = 29
+--- @field _1 30
_1 = 30
+--- @field _2 31
_2 = 31
+--- @field _3 32
_3 = 32
+--- @field _4 33
_4 = 33
+--- @field _5 34
_5 = 34
+--- @field _6 35
_6 = 35
+--- @field _7 36
_7 = 36
+--- @field _8 37
_8 = 37
+--- @field _9 38
_9 = 38
+--- @field _0 39
_0 = 39
+--- @field _RETURN 40
_RETURN = 40
+--- @field _ESCAPE 41
_ESCAPE = 41
+--- @field _BACKSPACE 42
_BACKSPACE = 42
+--- @field _TAB 43
_TAB = 43
+--- @field _SPACE 44
_SPACE = 44
+--- @field _MINUS 45
_MINUS = 45
+--- @field _EQUALS 46
_EQUALS = 46
+--- @field _LEFTBRACKET 47
_LEFTBRACKET = 47
+--- @field _RIGHTBRACKET 48
_RIGHTBRACKET = 48
+--- @field _BACKSLASH 49
_BACKSLASH = 49
+--- @field _NONUSHASH 50
_NONUSHASH = 50
+--- @field _SEMICOLON 51
_SEMICOLON = 51
+--- @field _APOSTROPHE 52
_APOSTROPHE = 52
+--- @field _GRAVE 53
_GRAVE = 53
+--- @field _COMMA 54
_COMMA = 54
+--- @field _PERIOD 55
_PERIOD = 55
+--- @field _SLASH 56
_SLASH = 56
+--- @field _CAPSLOCK 57
_CAPSLOCK = 57
+--- @field _F1 58
_F1 = 58
+--- @field _F2 59
_F2 = 59
+--- @field _F3 60
_F3 = 60
+--- @field _F4 61
_F4 = 61
+--- @field _F5 62
_F5 = 62
+--- @field _F6 63
_F6 = 63
+--- @field _F7 64
_F7 = 64
+--- @field _F8 65
_F8 = 65
+--- @field _F9 66
_F9 = 66
+--- @field _F10 67
_F10 = 67
+--- @field _F11 68
_F11 = 68
+--- @field _F12 69
_F12 = 69
+--- @field _PRINTSCREEN 70
_PRINTSCREEN = 70
+--- @field _SCROLLLOCK 71
_SCROLLLOCK = 71
+--- @field _PAUSE 72
_PAUSE = 72
+--- @field _INSERT 73
_INSERT = 73
+--- @field _HOME 74
_HOME = 74
+--- @field _PAGEUP 75
_PAGEUP = 75
+--- @field _DELETE 76
_DELETE = 76
+--- @field _END 77
_END = 77
+--- @field _PAGEDOWN 78
_PAGEDOWN = 78
+--- @field _RIGHT 79
_RIGHT = 79
+--- @field _LEFT 80
_LEFT = 80
+--- @field _DOWN 81
_DOWN = 81
+--- @field _UP 82
_UP = 82
+--- @field _NUMLOCKCLEAR 83
_NUMLOCKCLEAR = 83
+--- @field _KP_DIVIDE 84
_KP_DIVIDE = 84
+--- @field _KP_MULTIPLY 85
_KP_MULTIPLY = 85
+--- @field _KP_MINUS 86
_KP_MINUS = 86
+--- @field _KP_PLUS 87
_KP_PLUS = 87
+--- @field _KP_ENTER 88
_KP_ENTER = 88
+--- @field _KP_1 89
_KP_1 = 89
+--- @field _KP_2 90
_KP_2 = 90
+--- @field _KP_3 91
_KP_3 = 91
+--- @field _KP_4 92
_KP_4 = 92
+--- @field _KP_5 93
_KP_5 = 93
+--- @field _KP_6 94
_KP_6 = 94
+--- @field _KP_7 95
_KP_7 = 95
+--- @field _KP_8 96
_KP_8 = 96
+--- @field _KP_9 97
_KP_9 = 97
+--- @field _KP_0 98
_KP_0 = 98
+--- @field _KP_PERIOD 99
_KP_PERIOD = 99
+--- @field _NONUSBACKSLASH 100
_NONUSBACKSLASH = 100
+--- @field _APPLICATION 101
_APPLICATION = 101
+--- @field _POWER 102
_POWER = 102
+--- @field _KP_EQUALS 103
_KP_EQUALS = 103
+--- @field _F13 104
_F13 = 104
+--- @field _F14 105
_F14 = 105
+--- @field _F15 106
_F15 = 106
+--- @field _F16 107
_F16 = 107
+--- @field _F17 108
_F17 = 108
+--- @field _F18 109
_F18 = 109
+--- @field _F19 110
_F19 = 110
+--- @field _F20 111
_F20 = 111
+--- @field _F21 112
_F21 = 112
+--- @field _F22 113
_F22 = 113
+--- @field _F23 114
_F23 = 114
+--- @field _F24 115
_F24 = 115
+--- @field _EXECUTE 116
_EXECUTE = 116
+--- @field _HELP 117
_HELP = 117
+--- @field _MENU 118
_MENU = 118
+--- @field _SELECT 119
_SELECT = 119
+--- @field _STOP 120
_STOP = 120
+--- @field _AGAIN 121
_AGAIN = 121
+--- @field _UNDO 122
_UNDO = 122
+--- @field _CUT 123
_CUT = 123
+--- @field _COPY 124
_COPY = 124
+--- @field _PASTE 125
_PASTE = 125
+--- @field _FIND 126
_FIND = 126
+--- @field _MUTE 127
_MUTE = 127
+--- @field _VOLUMEUP 128
_VOLUMEUP = 128
+--- @field _VOLUMEDOWN 129
_VOLUMEDOWN = 129
+--- @field _KP_COMMA 133
_KP_COMMA = 133
+--- @field _KP_EQUALSAS400 134
_KP_EQUALSAS400 = 134
+--- @field _INTERNATIONAL1 135
_INTERNATIONAL1 = 135
+--- @field _INTERNATIONAL2 136
_INTERNATIONAL2 = 136
+--- @field _INTERNATIONAL3 137
_INTERNATIONAL3 = 137
+--- @field _INTERNATIONAL4 138
_INTERNATIONAL4 = 138
+--- @field _INTERNATIONAL5 139
_INTERNATIONAL5 = 139
+--- @field _INTERNATIONAL6 140
_INTERNATIONAL6 = 140
+--- @field _INTERNATIONAL7 141
_INTERNATIONAL7 = 141
+--- @field _INTERNATIONAL8 142
_INTERNATIONAL8 = 142
+--- @field _INTERNATIONAL9 143
_INTERNATIONAL9 = 143
+--- @field _LANG1 144
_LANG1 = 144
+--- @field _LANG2 145
_LANG2 = 145
+--- @field _LANG3 146
_LANG3 = 146
+--- @field _LANG4 147
_LANG4 = 147
+--- @field _LANG5 148
_LANG5 = 148
+--- @field _LANG6 149
_LANG6 = 149
+--- @field _LANG7 150
_LANG7 = 150
+--- @field _LANG8 151
_LANG8 = 151
+--- @field _LANG9 152
_LANG9 = 152
+--- @field _ALTERASE 153
_ALTERASE = 153
+--- @field _SYSREQ 154
_SYSREQ = 154
+--- @field _CANCEL 155
_CANCEL = 155
+--- @field _CLEAR 156
_CLEAR = 156
+--- @field _PRIOR 157
_PRIOR = 157
+--- @field _RETURN2 158
_RETURN2 = 158
+--- @field _SEPARATOR 159
_SEPARATOR = 159
+--- @field _OUT 160
_OUT = 160
+--- @field _OPER 161
_OPER = 161
+--- @field _CLEARAGAIN 162
_CLEARAGAIN = 162
+--- @field _CRSEL 163
_CRSEL = 163
+--- @field _EXSEL 164
_EXSEL = 164
+--- @field _KP_00 176
_KP_00 = 176
+--- @field _KP_000 177
_KP_000 = 177
+--- @field _THOUSANDSSEPARATOR 178
_THOUSANDSSEPARATOR = 178
+--- @field _DECIMALSEPARATOR 179
_DECIMALSEPARATOR = 179
+--- @field _CURRENCYUNIT 180
_CURRENCYUNIT = 180
+--- @field _CURRENCYSUBUNIT 181
_CURRENCYSUBUNIT = 181
+--- @field _KP_LEFTPAREN 182
_KP_LEFTPAREN = 182
+--- @field _KP_RIGHTPAREN 183
_KP_RIGHTPAREN = 183
+--- @field _KP_LEFTBRACE 184
_KP_LEFTBRACE = 184
+--- @field _KP_RIGHTBRACE 185
_KP_RIGHTBRACE = 185
+--- @field _KP_TAB 186
_KP_TAB = 186
+--- @field _KP_BACKSPACE 187
_KP_BACKSPACE = 187
+--- @field _KP_A 188
_KP_A = 188
+--- @field _KP_B 189
_KP_B = 189
+--- @field _KP_C 190
_KP_C = 190
+--- @field _KP_D 191
_KP_D = 191
+--- @field _KP_E 192
_KP_E = 192
+--- @field _KP_F 193
_KP_F = 193
+--- @field _KP_XOR 194
_KP_XOR = 194
+--- @field _KP_POWER 195
_KP_POWER = 195
+--- @field _KP_PERCENT 196
_KP_PERCENT = 196
+--- @field _KP_LESS 197
_KP_LESS = 197
+--- @field _KP_GREATER 198
_KP_GREATER = 198
+--- @field _KP_AMPERSAND 199
_KP_AMPERSAND = 199
+--- @field _KP_DBLAMPERSAND 200
_KP_DBLAMPERSAND = 200
+--- @field _KP_VERTICALBAR 201
_KP_VERTICALBAR = 201
+--- @field _KP_DBLVERTICALBAR 202
_KP_DBLVERTICALBAR = 202
+--- @field _KP_COLON 203
_KP_COLON = 203
+--- @field _KP_HASH 204
_KP_HASH = 204
+--- @field _KP_SPACE 205
_KP_SPACE = 205
+--- @field _KP_AT 206
_KP_AT = 206
+--- @field _KP_EXCLAM 207
_KP_EXCLAM = 207
+--- @field _KP_MEMSTORE 208
_KP_MEMSTORE = 208
+--- @field _KP_MEMRECALL 209
_KP_MEMRECALL = 209
+--- @field _KP_MEMCLEAR 210
_KP_MEMCLEAR = 210
+--- @field _KP_MEMADD 211
_KP_MEMADD = 211
+--- @field _KP_MEMSUBTRACT 212
_KP_MEMSUBTRACT = 212
+--- @field _KP_MEMMULTIPLY 213
_KP_MEMMULTIPLY = 213
+--- @field _KP_MEMDIVIDE 214
_KP_MEMDIVIDE = 214
+--- @field _KP_PLUSMINUS 215
_KP_PLUSMINUS = 215
+--- @field _KP_CLEAR 216
_KP_CLEAR = 216
+--- @field _KP_CLEARENTRY 217
_KP_CLEARENTRY = 217
+--- @field _KP_BINARY 218
_KP_BINARY = 218
+--- @field _KP_OCTAL 219
_KP_OCTAL = 219
+--- @field _KP_DECIMAL 220
_KP_DECIMAL = 220
+--- @field _KP_HEXADECIMAL 221
_KP_HEXADECIMAL = 221
+--- @field _LCTRL 224
_LCTRL = 224
+--- @field _LSHIFT 225
_LSHIFT = 225
+--- @field _LALT 226
_LALT = 226
+--- @field _LGUI 227
_LGUI = 227
+--- @field _RCTRL 228
_RCTRL = 228
+--- @field _RSHIFT 229
_RSHIFT = 229
+--- @field _RALT 230
_RALT = 230
+--- @field _RGUI 231
_RGUI = 231
+--- @field _MODE 257
_MODE = 257
+--- @field _AUDIONEXT 258
_AUDIONEXT = 258
+--- @field _AUDIOPREV 259
_AUDIOPREV = 259
+--- @field _AUDIOSTOP 260
_AUDIOSTOP = 260
+--- @field _AUDIOPLAY 261
_AUDIOPLAY = 261
+--- @field _AUDIOMUTE 262
_AUDIOMUTE = 262
+--- @field _MEDIASELECT 263
_MEDIASELECT = 263
+--- @field _WWW 264
_WWW = 264
+--- @field _MAIL 265
_MAIL = 265
+--- @field _CALCULATOR 266
_CALCULATOR = 266
+--- @field _COMPUTER 267
_COMPUTER = 267
+--- @field _AC_SEARCH 268
_AC_SEARCH = 268
+--- @field _AC_HOME 269
_AC_HOME = 269
+--- @field _AC_BACK 270
_AC_BACK = 270
+--- @field _AC_FORWARD 271
_AC_FORWARD = 271
+--- @field _AC_STOP 272
_AC_STOP = 272
+--- @field _AC_REFRESH 273
_AC_REFRESH = 273
+--- @field _AC_BOOKMARKS 274
_AC_BOOKMARKS = 274
+--- @field _BRIGHTNESSDOWN 275
_BRIGHTNESSDOWN = 275
+--- @field _BRIGHTNESSUP 276
_BRIGHTNESSUP = 276
+--- @field _DISPLAYSWITCH 277
_DISPLAYSWITCH = 277
+--- @field _KBDILLUMTOGGLE 278
_KBDILLUMTOGGLE = 278
+--- @field _KBDILLUMDOWN 279
_KBDILLUMDOWN = 279
+--- @field _KBDILLUMUP 280
_KBDILLUMUP = 280
+--- @field _EJECT 281
_EJECT = 281
+--- @field _SLEEP 282
_SLEEP = 282
-__DEFAULT = -10000
-__TEXTINPUT = -10001
+--- @field __DEFAULT -10000
+__DEFAULT = -10000
+--- @field __TEXTINPUT -10001
+__TEXTINPUT = -10001
-- Reverse sym calc
_M.sym_to_name = {}
diff --git a/game/engines/default/engine/KeyBind.lua b/game/engines/default/engine/KeyBind.lua
index 16c18b1ec6..9dcd574a1a 100644
--- a/game/engines/default/engine/KeyBind.lua
+++ b/game/engines/default/engine/KeyBind.lua
@@ -22,6 +22,7 @@ require "engine.class"
require "engine.KeyCommand"
--- Handles key binds to "virtual" actions
+-- @classmod engine.KeyBind
module(..., package.seeall, class.inherit(engine.KeyCommand))
_M.binds_def = {}
@@ -41,7 +42,7 @@ end
--- Loads a list of keybind definitions
-- Keybind definitions are in /data/keybinds/. Modules can define new ones.
--- @param a string representing the keybind, separated by commas. I.e: "move,hotkeys,actions,inventory"
+-- @param str a string representing the keybind, separated by commas. I.e: "move,hotkeys,actions,inventory"
function _M:load(str)
local defs = str:split(",")
for i, def in ipairs(defs) do
@@ -264,17 +265,15 @@ function _M:triggerVirtual(virtual)
end
--- Adds a key/command combination
--- @param sym the key to handle
--- @param mods a table with the mod keys needed, i.e: {"ctrl", "alt"}
+-- @param virtual the key to handle
-- @param fct the function to call when the key is pressed
function _M:addBind(virtual, fct)
self.virtuals[virtual] = fct
end
--- Adds a key/command combination
--- @param sym the key to handle
--- @param mods a table with the mod keys needed, i.e: {"ctrl", "alt"}
--- @param fct the function to call when the key is pressed
+-- @param t {virtual: fct}
+-- @see KeyBind.addBind
function _M:addBinds(t)
local later = {}
for virtual, fct in pairs(t) do
diff --git a/game/engines/default/engine/KeyCommand.lua b/game/engines/default/engine/KeyCommand.lua
index c1cd05fa87..3ec415ab76 100644
--- a/game/engines/default/engine/KeyCommand.lua
+++ b/game/engines/default/engine/KeyCommand.lua
@@ -22,6 +22,7 @@ require "engine.class"
require "engine.Key"
--- Receives keypresses and acts upon them
+-- @classmod engine.KeyCommand
module(..., package.seeall, class.inherit(engine.Key))
function _M:init()
@@ -101,6 +102,7 @@ end
-- @param sym the key to handle
-- @param mods a table with the mod keys needed, i.e: {"ctrl", "alt"}
-- @param fct the function to call when the key is pressed
+-- @param anymod allow any modifier
function _M:addCommand(sym, mods, fct, anymod)
if type(sym) == "string" then sym = self[sym] end
if not sym then return end
diff --git a/game/engines/default/engine/Level.lua b/game/engines/default/engine/Level.lua
index ff074edfab..c74c47fe74 100644
--- a/game/engines/default/engine/Level.lua
+++ b/game/engines/default/engine/Level.lua
@@ -21,6 +21,7 @@ require "engine.class"
local Map = require "engine.Map"
--- Define a level
+-- @classmod engine.Level
module(..., package.seeall, class.make)
-- Keep a list of currently existing maps
@@ -198,7 +199,8 @@ end
-- Decaying means we look on the map for the given type of entities and if we are allowed to we delete them
-- @param what what Map feature to decay (ACTOR, OBJECT, ...)
-- @param check either a boolean or a function, if true the given entity will be decayed
--- @return the number of decayed entities and the total number of such entities remaining
+-- @return the number of decayed entities
+-- @return the total number of such entities remaining
function _M:decay(what, check)
local total, nb = 0, 0
for i = 0, self.map.w - 1 do for j = 0, self.map.h - 1 do
diff --git a/game/engines/default/engine/LogDisplay.lua b/game/engines/default/engine/LogDisplay.lua
index b4723f7184..00bf664f95 100644
--- a/game/engines/default/engine/LogDisplay.lua
+++ b/game/engines/default/engine/LogDisplay.lua
@@ -24,6 +24,7 @@ local Mouse = require "engine.Mouse"
local Slider = require "engine.ui.Slider"
--- Module that handles message history in a mouse wheel scrollable zone
+-- @classmod engine.LogDisplay
module(..., package.seeall, class.inherit(engine.ui.Base))
--- Creates the log zone
diff --git a/game/engines/default/engine/LogFlasher.lua b/game/engines/default/engine/LogFlasher.lua
index b13140c5bd..d6874f2e3e 100644
--- a/game/engines/default/engine/LogFlasher.lua
+++ b/game/engines/default/engine/LogFlasher.lua
@@ -20,6 +20,7 @@
require "engine.class"
--- Module that handles a single message line, with pausing and flashing
+-- @classmod engine.LogFlasher
module(..., package.seeall, class.make)
GOOD = 1
diff --git a/game/engines/default/engine/Map.lua b/game/engines/default/engine/Map.lua
index cc40cbd6cd..c30741ff6b 100644
--- a/game/engines/default/engine/Map.lua
+++ b/game/engines/default/engine/Map.lua
@@ -25,6 +25,7 @@ local Faction = require "engine.Faction"
local DamageType = require "engine.DamageType"
--- Represents a level map, handles display and various low level map work
+-- @classmod engine.Map
module(..., package.seeall, class.make)
-- Keep a list of currently existing maps
@@ -94,6 +95,7 @@ viewport_padding_8 = 0
-- @param tile_h height of a single tile
-- @param fontname font parameters, can be nil
-- @param fontsize font parameters, can be nil
+-- @param allow_backcolor allow backcolor
function _M:setViewPort(x, y, w, h, tile_w, tile_h, fontname, fontsize, allow_backcolor)
local otw, oth = self.tile_w, self.tile_h
local ovw, ovh = self.viewport and self.viewport.width, self.viewport and self.viewport.height
@@ -598,8 +600,9 @@ end
--- Displays the map on screen
-- @param x the coord where to start drawing, if null it uses self.display_x
-- @param y the coord where to start drawing, if null it uses self.display_y
--- @param nb_keyframes the number of keyframes elapsed since last draw
+-- @param nb_keyframe the number of keyframes elapsed since last draw
-- @param always_show tell the map code to force display unseed entities as remembered (used for smooth FOV shading)
+-- @param prevfbo previous vertiex buffer object used in last display
function _M:display(x, y, nb_keyframe, always_show, prevfbo)
nb_keyframes = nb_keyframes or 1
local ox, oy = rawget(self, "display_x"), rawget(self, "display_y")
@@ -1047,8 +1050,10 @@ end
-- @param y the epicenter coords
-- @param duration the number of turns to persist
-- @param damtype the DamageType to apply
+-- @param dam the amount of damage
-- @param radius the radius of the effect
-- @param dir the numpad direction of the effect, 5 for a ball effect
+-- @param angle the angle of the effect
-- @param overlay either a simple display entity to draw upon the map or a Particle class
-- @param update_fct optional function that will be called each time the effect is updated with the effect itself as parameter. Use it to change radius, move around ....
-- @param selffire percent chance to damage the source actor (default 100)
diff --git a/game/engines/default/engine/MapEffect.lua b/game/engines/default/engine/MapEffect.lua
index 5309a890cd..af899d9312 100644
--- a/game/engines/default/engine/MapEffect.lua
+++ b/game/engines/default/engine/MapEffect.lua
@@ -21,6 +21,7 @@ require "engine.class"
local Entity = require "engine.Entity"
--- Describes a trap
+-- @classmod engine.MapEffect
module(..., package.seeall, class.inherit(Entity))
_M.display_on_seen = true
diff --git a/game/engines/default/engine/Module.lua b/game/engines/default/engine/Module.lua
index 2f1f041827..bf6330bac4 100644
--- a/game/engines/default/engine/Module.lua
+++ b/game/engines/default/engine/Module.lua
@@ -25,6 +25,7 @@ local FontPackage = require "engine.FontPackage"
require "engine.PlayerProfile"
--- Handles dialog windows
+-- @classmod engine.Module
module(..., package.seeall, class.make)
--- Create a version string for the module version
@@ -819,6 +820,8 @@ end
-- @param mod the module definition as given by Module:loadDefinition()
-- @param name the savefile name
-- @param new_game true if the game must be created (aka new character)
+-- @param no_reboot
+-- @param extra_module_info
function _M:instanciate(mod, name, new_game, no_reboot, extra_module_info)
if not no_reboot then
local eng_v = nil
diff --git a/game/engines/default/engine/Mouse.lua b/game/engines/default/engine/Mouse.lua
index 3fc29252be..668ee55595 100644
--- a/game/engines/default/engine/Mouse.lua
+++ b/game/engines/default/engine/Mouse.lua
@@ -21,6 +21,7 @@ require "engine.class"
--- Basic mousepress handler
-- The engine calls receiveMouse when a mouse is clicked
+-- @classmod engine.Mouse
module(..., package.seeall, class.make)
function _M:init()
@@ -40,6 +41,7 @@ end
-- @param y coordinate of the click
-- @param isup true if the key was released, false if pressed
-- @param force_name if not nil only the zone with this name may trigger
+-- @param extra
function _M:receiveMouse(button, x, y, isup, force_name, extra)
self.last_pos = { x = x, y = y }
self.status[button] = not isup
@@ -203,29 +205,29 @@ end
-- @param y coordinate of the click (normalized to 0->1)
-- @param dx delta coordinate of the click (normalized to 0->1)
-- @param dy delta coordinate of the click (normalized to 0->1)
+-- @param pressure
-- @param isup true if the key was released, false if pressed
function _M:receiveTouch(fingerId, x, y, dx, dy, pressure, isup)
-- print("=touch", fingerId, x, y, dx, dy, pressure, isup)
end
---- Called when a touch event is received
+--- Called when a touch motion event is received
-- @param fingerId id of the finger info
-- @param x coordinate of the click (normalized to 0->1)
-- @param y coordinate of the click (normalized to 0->1)
-- @param dx delta coordinate of the click (normalized to 0->1)
-- @param dy delta coordinate of the click (normalized to 0->1)
--- @param isup true if the key was released, false if pressed
+-- @param pressure
function _M:receiveTouchMotion(fingerId, x, y, dx, dy, pressure)
-- print("=touch motion", fingerId, x, y, dx, dy, pressure)
end
---- Called when a touch event is received
--- @param fingerId id of the finger info
+--- Called when a touch gesture event is received
+-- @param nb_fingers number of fingers
-- @param x coordinate of the click (normalized to 0->1)
-- @param y coordinate of the click (normalized to 0->1)
--- @param dx delta coordinate of the click (normalized to 0->1)
--- @param dy delta coordinate of the click (normalized to 0->1)
--- @param isup true if the key was released, false if pressed
+-- @param d_rot delta rotation
+-- @param d_pinch delta pinch
function _M:receiveTouchGesture(nb_fingers, x, y, d_rot, d_pinch)
-- print("=touch gesture", nb_fingers, x, y, d_rot, d_pinch)
end
diff --git a/game/engines/default/engine/NameGenerator.lua b/game/engines/default/engine/NameGenerator.lua
index f0c93aa0f4..d332afa7ac 100644
--- a/game/engines/default/engine/NameGenerator.lua
+++ b/game/engines/default/engine/NameGenerator.lua
@@ -20,31 +20,34 @@
require "engine.class"
local lpeg = require "lpeg"
+--- Creates a random name generator with a set of rules
+--
+-- @usage The lang_def parameter is a table that must look like this:
+-- {
+-- phonemesVocals = "a, e, i, o, u, y",
+-- phonemesConsonants = "b, c, ch, ck, cz, d, dh, f, g, gh, h, j, k, kh, l, m, n, p, ph, q, r, rh, s, sh, t, th, ts, tz, v, w, x, z, zh",
+-- syllablesStart = "Aer, Al, Am, An, Ar, Arm, Arth, B, Bal, Bar, Be, Bel, Ber, Bok, Bor, Bran, Breg, Bren, Brod, Cam, Chal, Cham, Ch, Cuth, Dag, Daim, Dair, Del, Dr, Dur, Duv, Ear, Elen, Er, Erel, Erem, Fal, Ful, Gal, G, Get, Gil, Gor, Grin, Gun, H, Hal, Han, Har, Hath, Hett, Hur, Iss, Khel, K, Kor, Lel, Lor, M, Mal, Man, Mard, N, Ol, Radh, Rag, Relg, Rh, Run, Sam, Tarr, T, Tor, Tul, Tur, Ul, Ulf, Unr, Ur, Urth, Yar, Z, Zan, Zer",
+-- syllablesMiddle = "de, do, dra, du, duna, ga, go, hara, kaltho, la, latha, le, ma, nari, ra, re, rego, ro, rodda, romi, rui, sa, to, ya, zila",
+-- syllablesEnd = "bar, bers, blek, chak, chik, dan, dar, das, dig, dil, din, dir, dor, dur, fang, fast, gar, gas, gen, gorn, grim, gund, had, hek, hell, hir, hor, kan, kath, khad, kor, lach, lar, ldil, ldir, leg, len, lin, mas, mnir, ndil, ndur, neg, nik, ntir, rab, rach, rain, rak, ran, rand, rath, rek, rig, rim, rin, rion, sin, sta, stir, sus, tar, thad, thel, tir, von, vor, yon, zor",
+-- rules = "$s$v$35m$10m$e",
+-- }
+--
+-- The rules field defines how names are generated. Any special character found inside (starting with a $, with an optional number and a character) will be replaced by a random word from one of the lists.<br>
+-- $P = syllablesPre<br>
+-- $s = syllablesStart<br>
+-- $m = syllablesMiddle<br>
+-- $e = syllablesEnd<br>
+-- $p = syllablesPost<br>
+-- $v = phonemesVocals<br>
+-- $c = phonemesConsonants<br>
+-- If a number is give it is a percent chance for this part to exist.
+-- @classmod engine.NameGenerator
module(..., package.seeall, class.make)
local number = lpeg.R"09" ^ 0
local rule_pattern = "$" * lpeg.C(number) * lpeg.C(lpeg.S"smePpvc?")
---- Creates a random name generator with a set of rules
--- The lang_def parameter is a table that must look like this:<br/>
--- {<br/>
--- phonemesVocals = "a, e, i, o, u, y",<br/>
--- phonemesConsonants = "b, c, ch, ck, cz, d, dh, f, g, gh, h, j, k, kh, l, m, n, p, ph, q, r, rh, s, sh, t, th, ts, tz, v, w, x, z, zh",<br/>
--- syllablesStart = "Aer, Al, Am, An, Ar, Arm, Arth, B, Bal, Bar, Be, Bel, Ber, Bok, Bor, Bran, Breg, Bren, Brod, Cam, Chal, Cham, Ch, Cuth, Dag, Daim, Dair, Del, Dr, Dur, Duv, Ear, Elen, Er, Erel, Erem, Fal, Ful, Gal, G, Get, Gil, Gor, Grin, Gun, H, Hal, Han, Har, Hath, Hett, Hur, Iss, Khel, K, Kor, Lel, Lor, M, Mal, Man, Mard, N, Ol, Radh, Rag, Relg, Rh, Run, Sam, Tarr, T, Tor, Tul, Tur, Ul, Ulf, Unr, Ur, Urth, Yar, Z, Zan, Zer",<br/>
--- syllablesMiddle = "de, do, dra, du, duna, ga, go, hara, kaltho, la, latha, le, ma, nari, ra, re, rego, ro, rodda, romi, rui, sa, to, ya, zila",<br/>
--- syllablesEnd = "bar, bers, blek, chak, chik, dan, dar, das, dig, dil, din, dir, dor, dur, fang, fast, gar, gas, gen, gorn, grim, gund, had, hek, hell, hir, hor, kan, kath, khad, kor, lach, lar, ldil, ldir, leg, len, lin, mas, mnir, ndil, ndur, neg, nik, ntir, rab, rach, rain, rak, ran, rand, rath, rek, rig, rim, rin, rion, sin, sta, stir, sus, tar, thad, thel, tir, von, vor, yon, zor",<br/>
--- rules = "$s$v$35m$10m$e",<br/>
--- }<br/>
--- The rules field defines how names are generated. Any special character found inside (starting with a $, with an optional number and a character) will be
--- replaced by a random word from one of the lists.<br/>
--- $P = syllablesPre<br/>
--- $s = syllablesStart<br/>
--- $m = syllablesMiddle<br/>
--- $e = syllablesEnd<br/>
--- $p = syllablesPost<br/>
--- $v = phonemesVocals<br/>
--- $c = phonemesConsonants<br/>
--- If a number is give it is a percent chance for this part to exist
+-- init
function _M:init(lang_def)
local def = {}
if lang_def.phonemesVocals then def.v = lang_def.phonemesVocals:split(", ") end
@@ -59,7 +62,7 @@ function _M:init(lang_def)
end
--- Generates a name
--- @param if not nil this is a generation rule to use instead of a random one
+-- @param rule if not nil this is a generation rule to use instead of a random one
function _M:generate(rule)
while not rule do
rule = rng.table(self.lang_def.rules)
diff --git a/game/engines/default/engine/NameGenerator2.lua b/game/engines/default/engine/NameGenerator2.lua
index f824c63efa..857fd23f5c 100644
--- a/game/engines/default/engine/NameGenerator2.lua
+++ b/game/engines/default/engine/NameGenerator2.lua
@@ -20,6 +20,8 @@
require "engine.class"
local lpeg = require "lpeg"
+--- Alternate Name Generator
+-- @classmod engine.NameGenerator2
module(..., package.seeall, class.make)
--- Creates a random name generator using a pregenerated grammar
diff --git a/game/engines/default/engine/Object.lua b/game/engines/default/engine/Object.lua
index 711e865260..ca92d506ca 100644
--- a/game/engines/default/engine/Object.lua
+++ b/game/engines/default/engine/Object.lua
@@ -21,6 +21,8 @@ require "engine.class"
local Map = require "engine.Map"
local Entity = require "engine.Entity"
+--- Object
+-- @classmod engine.Object
module(..., package.seeall, class.inherit(Entity))
_M.display_on_seen = true
@@ -133,7 +135,9 @@ end
-- @param o = object to stack onto self
-- @param force boolean to stack unstackable objects
-- @param num = maximum number of stacked objects to move
--- @return true if stacking worked or false if not, and boolean if all of the stack was moved
+-- @return[1] false if stacking failed
+-- @return[2] true if stacking worked
+-- @return[2] boolean if all of the stack was moved
function _M:stack(o, force, num)
local last = true
num = num or math.huge
@@ -172,8 +176,8 @@ function _M:unstack(num)
return o, last
end
---- Applies a function to all items of the stack
--- stops after fct(so, i) returns true
+--- Applies a function to all items of the stack
+-- stops after fct(so, i) returns true
function _M:forAllStack(fct)
if fct(self) then return end
if not self.stacked then return end
diff --git a/game/engines/default/engine/Particles.lua b/game/engines/default/engine/Particles.lua
index dab6825d13..8808b320f6 100644
--- a/game/engines/default/engine/Particles.lua
+++ b/game/engines/default/engine/Particles.lua
@@ -21,6 +21,7 @@ require "engine.class"
--- Handles a particles system
-- Used by engine.Map
+-- @classmod engine.Particles
module(..., package.seeall, class.make)
local __particles_gl = {}
diff --git a/game/engines/default/engine/PlayerProfile.lua b/game/engines/default/engine/PlayerProfile.lua
index 3d0a186611..773610561e 100644
--- a/game/engines/default/engine/PlayerProfile.lua
+++ b/game/engines/default/engine/PlayerProfile.lua
@@ -25,6 +25,10 @@ local Dialog = require "engine.ui.Dialog"
local UserChat = require "engine.UserChat"
require "Json2"
+--- Handles the player profile, possibly online
+-- @classmod engine.PlayerProfile
+module(..., package.seeall, class.make)
+
------------------------------------------------------------
-- some simple serialization stuff
------------------------------------------------------------
@@ -68,9 +72,6 @@ end
------------------------------------------------------------
---- Handles the player profile, possibly online
-module(..., package.seeall, class.make)
-
function _M:init()
self.chat = UserChat.new()
self.dlc_files = {classes={}, files={}}
@@ -822,6 +823,7 @@ function _M:setSaveID(module, uuid, savename, md5)
print("[ONLINE PROFILE] saved character md5", uuid, savename, md5)
end
+--- check if our save is valid
function _M:checkSaveID(module, uuid, savename, md5)
if not self.auth or not self.hash_valid or not md5 then return function() return false end end
core.profile.pushOrder(table.serialize{o="CheckSaveMD5",
diff --git a/game/engines/default/engine/Projectile.lua b/game/engines/default/engine/Projectile.lua
index fa6c0b9166..187c9cf0e0 100644
--- a/game/engines/default/engine/Projectile.lua
+++ b/game/engines/default/engine/Projectile.lua
@@ -22,6 +22,8 @@ local Entity = require "engine.Entity"
local Particles = require "engine.Particles"
local Map = require "engine.Map"
+--- Projectile
+-- @classmod engine.Projectile
module(..., package.seeall, class.inherit(Entity))
_M.display_on_seen = true
@@ -72,7 +74,6 @@ end
--- Moves a projectile on the map
-- *WARNING*: changing x and y properties manually is *WRONG* and will blow up in your face. Use this method. Always.
--- @param map the map to move onto
-- @param x coord of the destination
-- @param y coord of the destination
-- @param force if true do not check for the presence of an other entity. *Use wisely*
diff --git a/game/engines/default/engine/Quadratic.lua b/game/engines/default/engine/Quadratic.lua
index 68f1e20e8f..802c343ff5 100644
--- a/game/engines/default/engine/Quadratic.lua
+++ b/game/engines/default/engine/Quadratic.lua
@@ -21,6 +21,7 @@ require "engine.class"
--- Handles a 3D "quadratic" object
-- It's mostly undeed, it simply allows quadratic to be serialized
+-- @classmod engine.Quadratic
module(..., package.seeall, class.make)
--- Make a particle emitter
diff --git a/game/engines/default/engine/Quest.lua b/game/engines/default/engine/Quest.lua
index 2355339b8e..12bc9eda15 100644
--- a/game/engines/default/engine/Quest.lua
+++ b/game/engines/default/engine/Quest.lua
@@ -20,6 +20,7 @@
require "engine.class"
--- Handle quests
+-- @classmod engine.Quest
module(..., package.seeall, class.make)
PENDING = 0
@@ -45,7 +46,8 @@ end
--- Checks if the quest (or sub-objective) is complete
-- @param sub a subobjective id or nil for the whole quest
--- @return true or false
+-- @return[1] false if objective still incomplete
+-- @return[2] true if objective completed
function _M:isCompleted(sub)
if sub then
if self.objectives[sub] and self.objectives[sub] == COMPLETED then return true else return false end
@@ -54,7 +56,8 @@ function _M:isCompleted(sub)
end
--- Checks if the quest is ended (DONE or FAILED)
--- @return true or false
+-- @return[1] false if quest didn't end
+-- @return[2] true if quest ended
function _M:isEnded()
if self.status == DONE or self.status == FAILED then return true else return false end
end
@@ -71,6 +74,8 @@ end
--- Sets the quests status or sub-objective status
-- @param status one of the possible quest status (PENDING, COMPLETED, DONE, FAILED)
+-- @param[opt] sub sub-objective
+-- @param who who did this??
function _M:setStatus(status, sub, who)
if sub then
if self.objectives[sub] and self.objectives[sub] == status then return false end
@@ -87,6 +92,7 @@ end
--- Checks the quests status or sub-objective status
-- @param status one of the possible quest status (PENDING, COMPLETED, DONE, FAILED)
+-- @param[opt] sub sub-objective
function _M:isStatus(status, sub)
if sub then
if self.objectives[sub] and self.objectives[sub] == status then return true end
diff --git a/game/engines/default/engine/Savefile.lua b/game/engines/default/engine/Savefile.lua
index b999009692..93845c90b9 100644
--- a/game/engines/default/engine/Savefile.lua
+++ b/game/engines/default/engine/Savefile.lua
@@ -20,14 +20,17 @@
require "engine.class"
local Dialog = require "engine.ui.Dialog"
---- Savefile code
--- T-Engine4 savefiles are direct serialization of in game objects<br/>
--- Basically the engine is told to save your Game instance and then it will
--- recursively save all that it contains: level, map, entities, your own objects, ...<br/>
--- The savefile structure is a zip file that contains one file per object to be saved. Unzip one, it is quite obvious<br/>
--- A simple object (that does not do anything too fancy in its constructor) will save/load without anything
--- to code, it's magic!<br/>
--- For more complex objects, look at the methods save() and loaded() in objects that have them
+--[[-- Savefile code
+T-Engine4 savefiles are direct serialization of in game objects
+
+Basically the engine is told to save your Game instance and then it will recursively save all that it contains: level, map, entities, your own objects, ...
+
+The savefile structure is a zip file that contains one file per object to be saved. Unzip one, it is quite obvious
+
+A simple object (that does not do anything too fancy in its constructor) will save/load without anything to code, it's magic!
+For more complex objects, look at the methods save() and loaded() in objects that have them
+]]
+--- @classmod engine.Savefile
module(..., package.seeall, class.make)
_M.current_save = false
@@ -52,13 +55,24 @@ function _M:init(savefile, coroutine)
_M.current_save = self
end
+--- The save file that is currently open
+-- @static
+-- @return current save
function _M:getCurrent()
return _M.current_save
end
+
+--- Set this save file as the current one
+-- @static
+-- @param[type=table] save
+-- @return current save
function _M:setCurrent(save)
_M.current_save = save
end
+--- Do we md5 the specified type when saving?
+-- @static
+-- @string type
function _M:setSaveMD5Type(type)
self.md5_types[type] = true
end
@@ -74,6 +88,7 @@ function _M:close()
end
--- Delete the savefile, if needed
+-- Also deletes from steam cloud if it's available
function _M:delete()
for i, f in ipairs(fs.list(self.save_dir)) do
fs.delete(self.save_dir..f)
@@ -91,6 +106,7 @@ function _M:delete()
end
end
+--- add to process
function _M:addToProcess(o)
if not self.tables[o] then
table.insert(self.process, o)
@@ -98,11 +114,17 @@ function _M:addToProcess(o)
end
end
+--- Add a delayed load for object
+-- @param o
function _M:addDelayLoad(o)
-- print("add delayed", _M, "::", self, #self.delayLoad, o)
table.insert(self.delayLoad, 1, o)
end
+--- Get the filename of the object
+-- @param o
+-- @return[1] "main"
+-- @return[2] o.__CLASSNAME.."-"..tostring(o):sub(8)
function _M:getFileName(o)
if o == self.current_save_main then
return "main"
@@ -111,6 +133,10 @@ function _M:getFileName(o)
end
end
+--- Save the object to specified zip
+-- @param obj current_save_main
+-- @param zip
+-- @return int of how many processed
function _M:saveObject(obj, zip)
local processed = 0
self.current_save_zip = zip
@@ -131,15 +157,20 @@ function _M:saveObject(obj, zip)
end
--- Get a savename for a world
+-- @param[type=World] world unused
+-- @return "world.teaw"
function _M:nameSaveWorld(world)
return "world.teaw"
end
--- Get a savename for a world
+-- @return "world.teaw"
function _M:nameLoadWorld()
return "world.teaw"
end
--- Save the given world
+-- @param[type=World] world the world to save
+-- @param[type=boolean] no_dialog show a popup when saving?
function _M:saveWorld(world, no_dialog)
collectgarbage("collect")
@@ -163,6 +194,7 @@ function _M:saveWorld(world, no_dialog)
end
--- Save the given birth descriptors, used for quick start
+-- @param[type=table] descriptor {key, value}
function _M:saveQuickBirth(descriptor)
collectgarbage("collect")
@@ -174,6 +206,8 @@ function _M:saveQuickBirth(descriptor)
end
--- Load the given birth descriptors, used for quick start
+-- @return[1] nil
+-- @return[2] table
function _M:loadQuickBirth()
collectgarbage("collect")
@@ -191,6 +225,7 @@ function _M:loadQuickBirth()
end
--- Saves the screenshot of a game
+-- @param screenshot the screenshot to write to
function _M:saveScreenshot(screenshot)
if not screenshot then return end
fs.mkdir(self.save_dir)
@@ -201,15 +236,20 @@ function _M:saveScreenshot(screenshot)
end
--- Get a savename for a game
+-- @param[type=Game] game
+-- @return "game.teag"
function _M:nameSaveGame(game)
return "game.teag"
end
--- Get a savename for a game
+-- @return "game.teag"
function _M:nameLoadGame()
return "game.teag"
end
--- Save the given game
+-- @param[type=Game] game
+-- @param[type=boolean] no_dialog Show a popup when saving?
function _M:saveGame(game, no_dialog)
collectgarbage("collect")
@@ -277,15 +317,22 @@ function _M:saveGame(game, no_dialog)
end
--- Get a savename for a zone
+-- @param[type=Zone] zone
+-- @return "zone-%s.teaz"
function _M:nameSaveZone(zone)
return ("zone-%s.teaz"):format(zone.short_name)
end
--- Get a savename for a zone
+-- @param[type=Zone] zone
+-- @return "zone-%s.teaz"
function _M:nameLoadZone(zone)
+
return ("zone-%s.teaz"):format(zone)
end
--- Save a zone
+-- @param[type=Zone] zone
+-- @param[type=?boolean] no_dialog Show a popup when saving?
function _M:saveZone(zone, no_dialog)
fs.mkdir(self.save_dir)
@@ -307,15 +354,22 @@ function _M:saveZone(zone, no_dialog)
end
--- Get a savename for a level
+-- @param[type=Level] level
+-- @return "level-%s-%d.teal"
function _M:nameSaveLevel(level)
return ("level-%s-%d.teal"):format(level.data.short_name, level.level)
end
--- Get a savename for a level
+-- @param[type=Zone] zone
+-- @param[type=Level] level
+-- @return "level-%s-%d.teal"
function _M:nameLoadLevel(zone, level)
return ("level-%s-%d.teal"):format(zone, level)
end
--- Save a level
+-- @param[type=Level] level
+-- @param[type=?boolean] no_dialog Show a popup when saving?
function _M:saveLevel(level, no_dialog)
fs.mkdir(self.save_dir)
@@ -337,15 +391,19 @@ function _M:saveLevel(level, no_dialog)
end
--- Get a savename for an entity
+-- @return "entity-%s.teae"
function _M:nameSaveEntity(e)
return ("entity-%s.teae"):format(e.name:gsub("[^a-zA-Z0-9_-.]", "_"):lower())
end
--- Get a savename for an entity
+-- @return "entity-%s.teae"
function _M:nameLoadEntity(name)
return ("entity-%s.teae"):format(name:gsub("[^a-zA-Z0-9_-.]", "_"):lower())
end
--- Save an entity
+-- @param[type=Entity] e
+-- @param[type=?boolean] no_dialog Show a popup when saving?
function _M:saveEntity(e, no_dialog)
fs.mkdir(self.save_dir)
@@ -366,6 +424,10 @@ function _M:saveEntity(e, no_dialog)
if not no_dialog then popup:done() end
end
+--- Ensure compatability between saves
+-- @param o object
+-- @param base base object
+-- @param allow_object allow the object to save (called recursively)
local function resolveSelf(o, base, allow_object)
-- we check both to ensure compatibility with old saves; including world.teaw which is vital to not make everything explode
if (o.__ATOMIC or o.__CLASSNAME) and not allow_object then return end
@@ -381,6 +443,10 @@ local function resolveSelf(o, base, allow_object)
for i, k in ipairs(change) do o[k] = base end
end
+--- Actually load an object
+-- @param load
+-- @return[1] nil
+-- @return[2] o
function _M:loadReal(load)
if self.loaded[load] then return self.loaded[load] end
local f = fs.open(self.load_dir..load, "r")
@@ -403,7 +469,10 @@ function _M:loadReal(load)
return o
end
---- Loads a world
+--- Loads a `World`
+-- @return[1] nil
+-- @return[1] "no savefile"
+-- @return[2] `World`
function _M:loadWorld()
if util.steamCanCloud() then core.steam.readFile(self.save_dir..self:nameLoadWorld()) end
local path = fs.getRealPath(self.save_dir..self:nameLoadWorld())
@@ -434,7 +503,10 @@ function _M:loadWorld()
return loadedWorld
end
---- Loads a world
+--- Gets the filesize of a `World` savefile
+-- @return[1] nil
+-- @return[1] "no savefile"
+-- @return[2] size
function _M:loadWorldSize()
if util.steamCanCloud() then core.steam.readFile(self.save_dir..self:nameLoadWorld()) end
local path = fs.getRealPath(self.save_dir..self:nameLoadWorld())
@@ -453,7 +525,12 @@ function _M:loadWorldSize()
return nb
end
---- Loads a game
+--- Loads a `Game`
+-- delay_fct is all of the delayLoad functionality for the save file
+-- @return[1] nil
+-- @return[1] "no savefile"
+-- @return[2] `Game`
+-- @return[2] delay_fct
function _M:loadGame()
if util.steamCanCloud() then core.steam.readFile(self.save_dir..self:nameLoadGame()) end
local path = fs.getRealPath(self.save_dir..self:nameLoadGame())
@@ -487,7 +564,10 @@ function _M:loadGame()
end
---- Loads a game
+--- Gets the filesize of the `Game` savefile
+-- @return[1] nil
+-- @return[1] "no savefile"
+-- @return[2] size
function _M:loadGameSize()
if util.steamCanCloud() then core.steam.readFile(self.save_dir..self:nameLoadGame()) end
local path = fs.getRealPath(self.save_dir..self:nameLoadGame())
@@ -506,7 +586,11 @@ function _M:loadGameSize()
return nb
end
---- Loads a zone
+--- Loads a `Zone`
+-- executes all delayLoad automatically
+-- @param[type=table] zone
+-- @return[1] false
+-- @return[2] `Zone`
function _M:loadZone(zone)
if util.steamCanCloud() then core.steam.readFile(self.save_dir..self:nameLoadZone(zone)) end
local path = fs.getRealPath(self.save_dir..self:nameLoadZone(zone))
@@ -545,7 +629,12 @@ function _M:loadZone(zone)
return loadedZone
end
---- Loads a level
+--- Loads a `Level`
+-- all delayLoad executes automatically
+-- @param[type=table] zone
+-- @param[type=table] level
+-- @return[1] false
+-- @return[2] `Level`
function _M:loadLevel(zone, level)
if util.steamCanCloud() then core.steam.readFile(self.save_dir..self:nameLoadLevel(zone, level)) end
local path = fs.getRealPath(self.save_dir..self:nameLoadLevel(zone, level))
@@ -583,6 +672,10 @@ function _M:loadLevel(zone, level)
end
--- Loads an entity
+-- automatically executes delayLoad
+-- @string name
+-- @return[1] false
+-- @return[2] `Entity`
function _M:loadEntity(name)
if util.steamCanCloud() then core.steam.readFile(self.save_dir..self:nameLoadEntity(name)) end
local path = fs.getRealPath(self.save_dir..self:nameLoadEntity(name))
@@ -620,6 +713,9 @@ function _M:loadEntity(name)
end
--- Checks validity of a kind
+-- @string type "Entity" | "World" | "Level" | "Zone"
+-- @param object the object to check
+-- @return true if valid
function _M:checkValidity(type, object)
local path = fs.getRealPath(self.save_dir..self['nameSave'..type:lower():capitalize()](self, object))
if not path or path == "" then
@@ -637,11 +733,16 @@ function _M:checkValidity(type, object)
end
--- Checks for existence
+-- @return true if exists
function _M:check()
if util.steamCanCloud() then core.steam.readFile(self.save_dir..self:nameLoadGame()) end
return fs.exists(self.save_dir..self:nameLoadGame())
end
+--- Upload type as md5
+-- @see setSaveMD5Type
+-- @string type savefile type
+-- @string f filename
function _M:md5Upload(type, f)
if not self.md5_types[type] then return end
local p = game:getPlayer(true)
@@ -663,6 +764,14 @@ function _M:md5Upload(type, f)
profile:setSaveID(game.__mod_info.short_name, uuid, f, m)
end
+--- Check if md5 is correct
+-- @see setSaveMD5Type
+-- @see PlayerProfile:checkSaveID
+-- @string type savefile type
+-- @string f filename
+-- @param[opt=`Game`] loadgame game we're loading, defaults to static Game
+-- @return[1] fct() return false end
+-- @return[2] fct() return true end
function _M:md5Check(type, f, loadgame)
if not self.md5_types[type] then return function() return true end end
@@ -686,6 +795,7 @@ function _M:md5Check(type, f, loadgame)
return profile:checkSaveID(game.__mod_info.short_name, uuid, f, m)
end
+--- Called when our md5 is bad
function _M:badMD5Load()
if game.onBadMD5Load then game:onBadMD5Load() end
game.bad_md5_loaded = true
diff --git a/game/engines/default/engine/SavefilePipe.lua b/game/engines/default/engine/SavefilePipe.lua
index c0b783cb73..e9b8d7061f 100644
--- a/game/engines/default/engine/SavefilePipe.lua
+++ b/game/engines/default/engine/SavefilePipe.lua
@@ -24,6 +24,7 @@ local Dialog = require "engine.ui.Dialog"
-- Creates a savefile pipe, savefiles requests can be pushed into it, it will execute them
-- in order and, as much as possible, as a background process, thus not preventing the game from running.<br/>
-- There can only be one pipe! DO NOT TRY TO MAKE MORE
+-- @classmod engine.SavefilePipe
module(..., package.seeall, class.make)
_M.current = nil
diff --git a/game/engines/default/engine/Shader.lua b/game/engines/default/engine/Shader.lua
index 22c09d95ff..6e5ca5a44c 100644
--- a/game/engines/default/engine/Shader.lua
+++ b/game/engines/default/engine/Shader.lua
@@ -21,6 +21,7 @@ require "engine.class"
--- Handles a particles system
-- Used by engine.Map
+-- @classmod engine.Shader
module(..., package.seeall, class.make)
_M.verts = {}
diff --git a/game/engines/default/engine/Store.lua b/game/engines/default/engine/Store.lua
index dcec3128cd..ecb5f680ab 100644
--- a/game/engines/default/engine/Store.lua
+++ b/game/engines/default/engine/Store.lua
@@ -24,6 +24,8 @@ local Inventory = require "engine.interface.ActorInventory"
local ShowStore = require_first("mod.dialogs.ShowStore", "engine.dialogs.ShowStore")
local GetQuantity = require "engine.dialogs.GetQuantity"
+--- Store
+-- @classmod engine.Store
module(..., package.seeall, class.inherit(Entity, Inventory))
function _M:init(t, no_default)
@@ -56,6 +58,7 @@ end
--- Fill the store with goods
-- @param level the level to generate for (instance of type engine.Level)
-- @param zone the zone to generate for
+-- @param force_nb[opt] make it generate a specific number of items
function _M:loadup(level, zone, force_nb)
local s = self.store
if not s then error("Store without a store field") end
@@ -115,6 +118,7 @@ end
--- Actor interacts with the store
-- @param who the actor who interacts
+-- @param[opt] name display name of the store
function _M:interact(who, name)
local store, inven = self:getInven("INVEN"), who:getInven("INVEN")
local d; d = ShowStore.new("Store: "..(name or self.name), store, inven, self.store.store_filter, self.store.actor_filter, function(what, o, item)
diff --git a/game/engines/default/engine/Target.lua b/game/engines/default/engine/Target.lua
index 47e52fd4e5..a4c98955e6 100644
--- a/game/engines/default/engine/Target.lua
+++ b/game/engines/default/engine/Target.lua
@@ -22,6 +22,7 @@ local Map = require "engine.Map"
local Shader = require "engine.Shader"
--- handles targetting
+-- @classmod engine.Target
module(..., package.seeall, class.make)
_M.defaults = {}
@@ -510,7 +511,6 @@ _M.types_def = {
bolt = function(dest, src) dest.stop_block = true end,
beam = function(dest, scr) dest.line = true end,}
--- @return t The target table used by ActorProject, Projectile, GameTargeting, etc.
-- @param t Target table used to generate the
-- @param t.type The engine-defined type, populates other more complex variables (see below)
-- Hit: simple project in LOS<br/>
@@ -530,6 +530,10 @@ _M.types_def = {
-- @param t.pass_terrain Boolean that allows the target to pass through terrain to remembered tiles on the other side.
-- @param t.block_path(typ, lx, ly) Function called on each tile to determine if the targeting is blocked. Automatically set when using t.typ, but the user can provide their own if they know what they are doing. It should return three arguments: block, hit, hit_radius
-- @param t.block_radius(typ, lx, ly) Function called on each tile when projecting the radius to determine if the radius projection is blocked. Automatically set when using t.typ, but the user can provide their own if they know what they are doing.
+-- @return[1] t The target table used by ActorProject
+-- @return[2] `Projectile`
+-- @return[3] `GameTargeting`
+-- @return[4] etc
function _M:getType(t)
if not t then return {} end
diff --git a/game/engines/default/engine/Tiles.lua b/game/engines/default/engine/Tiles.lua
index 81bd143cc0..f36b70ff8a 100644
--- a/game/engines/default/engine/Tiles.lua
+++ b/game/engines/default/engine/Tiles.lua
@@ -21,6 +21,7 @@ require "engine.class"
--- Handles tiles
-- Used by engine.Map to reduce processing needed. Module authors wont use it directly mostly.
+-- @classmod engine.Tiles
module(..., package.seeall, class.make)
prefix = "/data/gfx/"
diff --git a/game/engines/default/engine/Tooltip.lua b/game/engines/default/engine/Tooltip.lua
index fb821f7162..0d6fa93bc8 100644
--- a/game/engines/default/engine/Tooltip.lua
+++ b/game/engines/default/engine/Tooltip.lua
@@ -24,6 +24,7 @@ local UIContainer = require "engine.ui.UIContainer"
local Map = require "engine.Map"
--- A generic tooltip
+-- @classmod engine.Tooltip
module(..., package.seeall, class.inherit(Base))
tooltip_bound_x1 = function() return 0 end
@@ -263,6 +264,7 @@ end
-- @param my the screen coordinate to display at, if nil it will be computed from tmy
-- @param text a text to display, if nil it will interrogate the map under the mouse using the "tooltip" property
-- @param force forces tooltip to refresh
+-- @param nb_keyframes number of keyframes
function _M:displayAtMap(tmx, tmy, mx, my, text, force, nb_keyframes)
if not mx then
mx, my = game.level.map:getTileToScreen(tmx, tmy)
diff --git a/game/engines/default/engine/Trap.lua b/game/engines/default/engine/Trap.lua
index 725c0a6417..d0440a8627 100644
--- a/game/engines/default/engine/Trap.lua
+++ b/game/engines/default/engine/Trap.lua
@@ -22,6 +22,7 @@ local Entity = require "engine.Entity"
local Map = require "engine.Map"
--- Describes a trap
+-- @classmod engine.Trap
module(..., package.seeall, class.inherit(Entity))
_M.display_on_seen = true
diff --git a/game/engines/default/engine/UserChat.lua b/game/engines/default/engine/UserChat.lua
index b0b3fe9b5b..d955a3cf8b 100644
--- a/game/engines/default/engine/UserChat.lua
+++ b/game/engines/default/engine/UserChat.lua
@@ -26,6 +26,7 @@ local Slider = require "engine.ui.Slider"
local Base = require "engine.ui.Base"
--- Module that handles multiplayer chats
+-- @classmod engine.UserChat
module(..., package.seeall, class.inherit(Base))
local channel_colors = {
diff --git a/game/engines/default/engine/World.lua b/game/engines/default/engine/World.lua
index be82399eef..dda074bde0 100644
--- a/game/engines/default/engine/World.lua
+++ b/game/engines/default/engine/World.lua
@@ -20,6 +20,7 @@
require "engine.class"
--- Represents a game world, that is persistent across characters
+-- @classmod engine.World
module(..., package.seeall, class.make)
--- Initializes the world
diff --git a/game/engines/default/engine/Zone.lua b/game/engines/default/engine/Zone.lua
index 0349795956..c0bd2d4b43 100644
--- a/game/engines/default/engine/Zone.lua
+++ b/game/engines/default/engine/Zone.lua
@@ -26,6 +26,7 @@ local forceprint = print
local print = function() end
--- Defines a zone: a set of levels, with depth, npcs, objects, level generator, ...
+-- @classmod engine.Zone
module(..., package.seeall, class.make)
_no_save_fields = {temp_memory_levels=true, _tmp_data=true}
@@ -96,6 +97,7 @@ end
--- Loads a zone definition
-- @param short_name the short name of the zone to load, if should correspond to a directory in your module data/zones/short_name/ with a zone.lua, npcs.lua, grids.lua and objects.lua files inside
+-- @param dynamic
function _M:init(short_name, dynamic)
__zone_store[self] = true
@@ -355,7 +357,8 @@ end
-- @param filter a filter table
-- @param force_level if not nil forces the current level for resolvers to this one
-- @param prob_filter if true a new probability list based on this filter will be generated, ensuring to find objects better but at a slightly slower cost (maybe)
--- @return the fully resolved entity, ready to be used on a level. Or nil if a filter was given an nothing found
+-- @return[1] nil if a filter was given an nothing found
+-- @return[2] the fully resolved entity, ready to be used on a level
function _M:makeEntity(level, type, filter, force_level, prob_filter)
resolvers.current_level = self.base_level + level.level - 1
if force_level then resolvers.current_level = force_level end
@@ -418,7 +421,8 @@ function _M:makeEntity(level, type, filter, force_level, prob_filter)
end
--- Find a given entity and resolve it
--- @return the fully resolved entity, ready to be used on a level. Or nil if a filter was given an nothing found
+-- @return[1] nil if a filter was given an nothing found
+-- @return[2] the fully resolved entity, ready to be used on a level
function _M:makeEntityByName(level, type, name, force_unique)
resolvers.current_level = self.base_level + level.level - 1
@@ -682,6 +686,7 @@ end
-- @param typ the type of entity, one of "actor", "object", "trap" or "terrain"
-- @param x the coordinates where to add it. This CAN be null in which case it wont be added to the map
-- @param y the coordinates where to add it. This CAN be null in which case it wont be added to the map
+-- @param no_added have we added it
function _M:addEntity(level, e, typ, x, y, no_added)
if typ == "actor" then
-- We are additing it, this means there is no old position
@@ -815,8 +820,11 @@ function _M:leaveLevel(no_close, lev, old_lev)
end
--- Asks the zone to generate a level of level "lev"
+-- @param game which `Game`?
-- @param lev the level (from 1 to zone.max_level)
--- @return a Level object
+-- @param old_lev where are we leaving
+-- @param no_close pass to `leaveLevel`
+-- @return a `Level` object
function _M:getLevel(game, lev, old_lev, no_close)
self:leaveLevel(no_close, lev, old_lev)
diff --git a/game/engines/default/engine/ai/simple.lua b/game/engines/default/engine/ai/simple.lua
index 3a07b92270..abc65b553a 100644
--- a/game/engines/default/engine/ai/simple.lua
+++ b/game/engines/default/engine/ai/simple.lua
@@ -17,8 +17,9 @@
-- Nicolas Casalini "DarkGod"
-- darkgod@te4.org
--- Defines a simple AI building blocks
+--- Defines a simple AI building blocks
-- Target nearest and move/attack it
+-- @classmod engine.ai.simple
local Astar = require "engine.Astar"
newAI("move_simple", function(self)
diff --git a/game/engines/default/engine/ai/special_movements.lua b/game/engines/default/engine/ai/special_movements.lua
index 8bed3710e4..cd97d81256 100644
--- a/game/engines/default/engine/ai/special_movements.lua
+++ b/game/engines/default/engine/ai/special_movements.lua
@@ -17,7 +17,8 @@
-- Nicolas Casalini "DarkGod"
-- darkgod@te4.org
--- Defines some special movement AIs
+--- Defines some special movement AIs
+-- @classmod engine.ai.special_movements
-- Ghoul AI: move, pause, move pause, ...
newAI("move_ghoul", function(self)
diff --git a/game/engines/default/engine/ai/talented.lua b/game/engines/default/engine/ai/talented.lua
index a33859920e..390d9524fa 100644
--- a/game/engines/default/engine/ai/talented.lua
+++ b/game/engines/default/engine/ai/talented.lua
@@ -17,7 +17,8 @@
-- Nicolas Casalini "DarkGod"
-- darkgod@te4.org
--- Defines AIs that can use talents, either smartly or "dumbly"
+--- Defines AIs that can use talents, either smartly or "dumbly"
+-- @classmod engine.ai.talented
-- Randomly use talents
newAI("dumb_talented", function(self)
diff --git a/game/engines/default/engine/class.lua b/game/engines/default/engine/class.lua
index c7e9afefa8..cfe215daf1 100644
--- a/game/engines/default/engine/class.lua
+++ b/game/engines/default/engine/class.lua
@@ -17,11 +17,15 @@
-- Nicolas Casalini "DarkGod"
-- darkgod@te4.org
+--- Base class used by pretty much everything
+-- @classmod engine.class
module("class", package.seeall)
local base = _G
local run_inherited = {}
+--- Search
+-- @local
local function search(k, plist)
for i=1, #plist do
local v = plist[i][k] -- try `i'-th superclass
@@ -29,7 +33,9 @@ local function search(k, plist)
end
end
-
+--- Calls init() for module and sets up some variables
+-- @param[type=table] c class
+-- @return class
function make(c)
setmetatable(c, {__index=_M})
c.new = function(...)
@@ -49,6 +55,8 @@ function make(c)
end
local skip_key = {init=true, _NAME=true, _M=true, _PACKAGE=true, new=true, _BASES=true, castAs=true}
+--- Inherit
+-- @return function(c)
function inherit(...)
local bases = {...}
return function(c)
diff --git a/game/engines/default/engine/colors.lua b/game/engines/default/engine/colors.lua
index 80e8f74c0f..6c64fbda54 100644
--- a/game/engines/default/engine/colors.lua
+++ b/game/engines/default/engine/colors.lua
@@ -17,33 +17,77 @@
-- Nicolas Casalini "DarkGod"
-- darkgod@te4.org
+--- Implements string->Color functionality, and allows the definition of colors
+-- Defines numerous colors by default
+-- @script engine.colors
+
colors = {}
colors_simple = {}
+--- Define Color
+-- @string name
+-- @int r foreground red
+-- @int g foreground green
+-- @int b foreground blue
+-- @int br background red
+-- @int bg background green
+-- @int bb background blue
function defineColor(name, r, g, b, br, bg, bb)
colors[name] = {r=r, g=g, b=b, br=br, bg=bg, bb=bb}
colors_simple[name] = {r, g, b}
end
+--- color -> foreground table
+-- @param[type=table] c color
+-- @return {r, g, b}
function colors.simple(c) return {c.r, c.g, c.b} end
+--- Does: color{r,g,b} / 255
+-- @param[type=table] c color
+-- @number[opt=1] a transparency
function colors.simple1(c, a) return {c.r/255, c.g/255, c.b/255, a or 1} end
+--- color -> foreground arguments
+-- @param[type=table] c
+-- @return r
+-- @return g
+-- @return b
function colors.unpack(c) return c.r, c.g, c.b end
+--- hex -> color
+-- @usage colors.hex1("FFBBCC")
+-- @string hex RRGGBB format hex string, 00->FF
+-- @return {r, g, b}
function colors.hex1(hex)
local r, g, b = tonumber("0x"..hex:sub(1, 2)), tonumber("0x"..hex:sub(3, 4)), tonumber("0x"..hex:sub(5, 6))
return {r / 255, g / 255, b / 255}
end
+--- hex -> color
+-- @usage colors.hex1unpack("FFBBCC")
+-- @string hex RRGGBB format hex string, 00->FF
+-- @return r
+-- @return g
+-- @return b
function colors.hex1unpack(hex)
return tonumber("0x"..hex:sub(1, 2)) / 255, tonumber("0x"..hex:sub(3, 4)) / 255, tonumber("0x"..hex:sub(5, 6)) / 255
end
+--- hex -> color with alpha
+-- @usage colors.hex1alpha("FFBBCC88")
+-- @string hex RRGGBB format hex string, 00->FF
+-- @return {r, g, b, a}
function colors.hex1alpha(hex)
local r, g, b, a = tonumber("0x"..hex:sub(1, 2)), tonumber("0x"..hex:sub(3, 4)), tonumber("0x"..hex:sub(5, 6)), tonumber("0x"..hex:sub(7, 8))
return {r / 255, g / 255, b / 255, a / 255}
end
+--- hex -> color with alpha
+-- @usage colors.hex1alpha("FFBBCC88")
+-- @string hex RRGGBB format hex string, 00->FF
+-- @return r
+-- @return g
+-- @return b
+-- @return a
function colors.hex1alphaunpack(hex)
return tonumber("0x"..hex:sub(1, 2)) / 255, tonumber("0x"..hex:sub(3, 4)) / 255, tonumber("0x"..hex:sub(5, 6)) / 255, tonumber("0x"..hex:sub(7, 8)) / 255
end
diff --git a/game/engines/default/engine/dialogs/Achievement.lua b/game/engines/default/engine/dialogs/Achievement.lua
index 679bed7ba0..92679e373f 100644
--- a/game/engines/default/engine/dialogs/Achievement.lua
+++ b/game/engines/default/engine/dialogs/Achievement.lua
@@ -23,6 +23,10 @@ local Dialog = require "engine.ui.Dialog"
local Image = require "engine.ui.Image"
local Textzone = require "engine.ui.Textzone"
+--- A sub dialog for defining an achievement
+--
+-- See also: @{ShowAchievements}
+-- @classmod engine.dialogs.Achievement
module(..., package.seeall, class.inherit(Dialog))
function _M:init(title, a)
diff --git a/game/engines/default/engine/dialogs/AudioOptions.lua b/game/engines/default/engine/dialogs/AudioOptions.lua
index 128c019efe..9907a1bae0 100644
--- a/game/engines/default/engine/dialogs/AudioOptions.lua
+++ b/game/engines/default/engine/dialogs/AudioOptions.lua
@@ -24,6 +24,8 @@ local Checkbox = require "engine.ui.Checkbox"
local Numberbox = require "engine.ui.Numberbox"
local Separator = require "engine.ui.Separator"
+--- Shows audio options
+-- @classmod engine.dialogs.AudioOptions
module(..., package.seeall, class.inherit(Dialog))
function _M:init()
diff --git a/game/engines/default/engine/dialogs/Chat.lua b/game/engines/default/engine/dialogs/Chat.lua
index 3b8addb02f..829c7372b0 100644
--- a/game/engines/default/engine/dialogs/Chat.lua
+++ b/game/engines/default/engine/dialogs/Chat.lua
@@ -24,6 +24,8 @@ local Textzone = require "engine.ui.Textzone"
local Separator = require "engine.ui.Separator"
local ActorFrame = require "engine.ui.ActorFrame"
+--- Controls chat between players and npcs
+-- @classmod engine.dialogs.Chat
module(..., package.seeall, class.inherit(Dialog))
show_portraits = false
diff --git a/game/engines/default/engine/dialogs/ChatChannels.lua b/game/engines/default/engine/dialogs/ChatChannels.lua
index 05de469c12..bbd0b33b5b 100644
--- a/game/engines/default/engine/dialogs/ChatChannels.lua
+++ b/game/engines/default/engine/dialogs/ChatChannels.lua
@@ -22,6 +22,8 @@ local Dialog = require "engine.ui.Dialog"
local Checkbox = require "engine.ui.Checkbox"
local Textzone = require "engine.ui.Textzone"
+--- Player to player chat
+-- @classmod engine.dialogs.ChatChannels
module(..., package.seeall, class.inherit(Dialog))
function _M:init(chat)
diff --git a/game/engines/default/engine/dialogs/ChatFilter.lua b/game/engines/default/engine/dialogs/ChatFilter.lua
index 40639b0306..e0720f8575 100644
--- a/game/engines/default/engine/dialogs/ChatFilter.lua
+++ b/game/engines/default/engine/dialogs/ChatFilter.lua
@@ -22,6 +22,8 @@ local Dialog = require "engine.ui.Dialog"
local Checkbox = require "engine.ui.Checkbox"
local Textzone = require "engine.ui.Textzone"
+--- Chat filters
+-- @classmod engine.dialogs.ChatFilter
module(..., package.seeall, class.inherit(Dialog))
function _M:init(adds)
diff --git a/game/engines/default/engine/dialogs/ChatIgnores.lua b/game/engines/default/engine/dialogs/ChatIgnores.lua
index 66cb254a4d..a1ee08bf68 100644
--- a/game/engines/default/engine/dialogs/ChatIgnores.lua
+++ b/game/engines/default/engine/dialogs/ChatIgnores.lua
@@ -22,6 +22,8 @@ local Dialog = require "engine.ui.Dialog"
local List = require "engine.ui.List"
local Textzone = require "engine.ui.Textzone"
+--- Chat Ignores
+-- @classmod engine.dialogs.ChatIgnores
module(..., package.seeall, class.inherit(Dialog))
function _M:init()
diff --git a/game/engines/default/engine/dialogs/DisplayResolution.lua b/game/engines/default/engine/dialogs/DisplayResolution.lua
index 35383ebdbf..2a8bcb8e95 100644
--- a/game/engines/default/engine/dialogs/DisplayResolution.lua
+++ b/game/engines/default/engine/dialogs/DisplayResolution.lua
@@ -22,6 +22,8 @@ local Dialog = require "engine.ui.Dialog"
local List = require "engine.ui.List"
local Checkbox = require "engine.ui.Checkbox"
+--- Controls what resoultion the window is set to
+-- @classmod engine.dialogs.DisplayResolution
module(..., package.seeall, class.inherit(Dialog))
function _M:init(on_change)
diff --git a/game/engines/default/engine/dialogs/Downloader.lua b/game/engines/default/engine/dialogs/Downloader.lua
index 8faeaa9cd1..3abc2c7c20 100644
--- a/game/engines/default/engine/dialogs/Downloader.lua
+++ b/game/engines/default/engine/dialogs/Downloader.lua
@@ -22,6 +22,7 @@ local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
--- A web browser
+-- @classmod engine.dialogs.Downloader
module(..., package.seeall, class.inherit(Base, Focusable))
function _M:init(t)
diff --git a/game/engines/default/engine/dialogs/GameMenu.lua b/game/engines/default/engine/dialogs/GameMenu.lua
index 5df20e649c..62cbe2ae0b 100644
--- a/game/engines/default/engine/dialogs/GameMenu.lua
+++ b/game/engines/default/engine/dialogs/GameMenu.lua
@@ -21,6 +21,8 @@ require "engine.class"
local Dialog = require "engine.ui.Dialog"
local List = require "engine.ui.List"
+--- Main game menu
+-- @classmod engine.dialogs.GameMenu
module(..., package.seeall, class.inherit(Dialog))
function _M:init(actions)
diff --git a/game/engines/default/engine/dialogs/GetQuantity.lua b/game/engines/default/engine/dialogs/GetQuantity.lua
index 51644a359a..2456a9a34e 100644
--- a/game/engines/default/engine/dialogs/GetQuantity.lua
+++ b/game/engines/default/engine/dialogs/GetQuantity.lua
@@ -23,6 +23,8 @@ local Dialog = require "engine.ui.Dialog"
local Button = require "engine.ui.Button"
local Numberbox = require "engine.ui.Numberbox"
+--- Generic popup for getting quantity
+-- @classmod engine.dialogs.GetQuantity
module(..., package.seeall, class.inherit(Dialog))
function _M:init(title, prompt, default, max, action, min)
diff --git a/game/engines/default/engine/dialogs/GetText.lua b/game/engines/default/engine/dialogs/GetText.lua
index 2b1b4ceeb0..7d19dd8300 100644
--- a/game/engines/default/engine/dialogs/GetText.lua
+++ b/game/engines/default/engine/dialogs/GetText.lua
@@ -23,6 +23,8 @@ local Dialog = require "engine.ui.Dialog"
local Button = require "engine.ui.Button"
local Textbox = require "engine.ui.Textbox"
+--- Generic popup for getting text
+-- @classmod engine.dialogs.GetText
module(..., package.seeall, class.inherit(Dialog))
function _M:init(title, text, min, max, action, cancel, absolute)
diff --git a/game/engines/default/engine/dialogs/KeyBinder.lua b/game/engines/default/engine/dialogs/KeyBinder.lua
index 963f999f31..c6fccaa9c2 100644
--- a/game/engines/default/engine/dialogs/KeyBinder.lua
+++ b/game/engines/default/engine/dialogs/KeyBinder.lua
@@ -26,6 +26,8 @@ local KeyBind = require "engine.KeyBind"
local Gestures = require "engine.ui.Gestures"
local GetText = require "engine.dialogs.GetText"
+--- Bind your keys!
+-- @classmod engine.dialogs.KeyBinder
module(..., package.seeall, class.inherit(Dialog))
function _M:init(key_source, force_all, gesture_source)
diff --git a/game/engines/default/engine/dialogs/ShowAchievements.lua b/game/engines/default/engine/dialogs/ShowAchievements.lua
index 408c5990aa..53ab0c2a7f 100644
--- a/game/engines/default/engine/dialogs/ShowAchievements.lua
+++ b/game/engines/default/engine/dialogs/ShowAchievements.lua
@@ -26,6 +26,10 @@ local Separator = require "engine.ui.Separator"
local Image = require "engine.ui.Image"
local Checkbox = require "engine.ui.Checkbox"
+--- Dialog for showing achievements
+--
+-- See also: @{Achievement}
+-- @classmod engine.dialogs.ShowAchievements
module(..., package.seeall, class.inherit(Dialog))
function _M:init(title, player)
diff --git a/game/engines/default/engine/dialogs/ShowEquipInven.lua b/game/engines/default/engine/dialogs/ShowEquipInven.lua
index 5dfa0076e7..e067c101de 100644
--- a/game/engines/default/engine/dialogs/ShowEquipInven.lua
+++ b/game/engines/default/engine/dialogs/ShowEquipInven.lua
@@ -24,6 +24,8 @@ local Textzone = require "engine.ui.Textzone"
local TextzoneList = require "engine.ui.TextzoneList"
local Separator = require "engine.ui.Separator"
+--- Show Equip Iventory
+-- @classmod engine.dialogs.ShowEquipInven
module(..., package.seeall, class.inherit(Dialog))
function _M:init(title, actor, filter, action, on_select)
diff --git a/game/engines/default/engine/dialogs/ShowEquipment.lua b/game/engines/default/engine/dialogs/ShowEquipment.lua
index 60b5bc3116..4d3e74ebb7 100644
--- a/game/engines/default/engine/dialogs/ShowEquipment.lua
+++ b/game/engines/default/engine/dialogs/ShowEquipment.lua
@@ -24,6 +24,8 @@ local Textzone = require "engine.ui.Textzone"
local TextzoneList = require "engine.ui.TextzoneList"
local Separator = require "engine.ui.Separator"
+--- Show Equipment
+-- @classmod engine.dialogs.ShowEquipment
module(..., package.seeall, class.inherit(Dialog))
function _M:init(title, actor, filter, action)
diff --git a/game/engines/default/engine/dialogs/ShowErrorStack.lua b/game/engines/default/engine/dialogs/ShowErrorStack.lua
index 554fbe9594..e17fad7ded 100644
--- a/game/engines/default/engine/dialogs/ShowErrorStack.lua
+++ b/game/engines/default/engine/dialogs/ShowErrorStack.lua
@@ -23,6 +23,8 @@ local Button = require "engine.ui.Button"
local Textzone = require "engine.ui.Textzone"
local Textbox = require "engine.ui.Textbox"
+--- Show Error Stack
+-- @classmod engine.dialogs.ShowErrorStack
module(..., package.seeall, class.inherit(Dialog))
function _M:init(errs)
diff --git a/game/engines/default/engine/dialogs/ShowInventory.lua b/game/engines/default/engine/dialogs/ShowInventory.lua
index 5246f3f9b1..9106ab529d 100644
--- a/game/engines/default/engine/dialogs/ShowInventory.lua
+++ b/game/engines/default/engine/dialogs/ShowInventory.lua
@@ -24,6 +24,8 @@ local Textzone = require "engine.ui.Textzone"
local TextzoneList = require "engine.ui.TextzoneList"
local Separator = require "engine.ui.Separator"
+--- Show Inventory
+-- @classmod engine.dialogs.ShowInventory
module(..., package.seeall, class.inherit(Dialog))
function _M:init(title, inven, filter, action, actor)
diff --git a/game/engines/default/engine/dialogs/ShowLog.lua b/game/engines/default/engine/dialogs/ShowLog.lua
index 4a361bbe08..b3ff1b3063 100644
--- a/game/engines/default/engine/dialogs/ShowLog.lua
+++ b/game/engines/default/engine/dialogs/ShowLog.lua
@@ -21,6 +21,8 @@ require "engine.class"
local Dialog = require "engine.ui.Dialog"
local Slider = require "engine.ui.Slider"
+--- Show Log
+-- @classmod engine.dialogs.ShowLog
module(..., package.seeall, class.inherit(Dialog))
function _M:init(title, shadow, log)
diff --git a/game/engines/default/engine/dialogs/ShowPickupFloor.lua b/game/engines/default/engine/dialogs/ShowPickupFloor.lua
index cb2f007b8f..a6df327483 100644
--- a/game/engines/default/engine/dialogs/ShowPickupFloor.lua
+++ b/game/engines/default/engine/dialogs/ShowPickupFloor.lua
@@ -25,6 +25,8 @@ local Textzone = require "engine.ui.Textzone"
local TextzoneList = require "engine.ui.TextzoneList"
local Separator = require "engine.ui.Separator"
+--- ShowPickupFloor
+-- @classmod engine.dialogs.ShowPickupFloor
module(..., package.seeall, class.inherit(Dialog))
function _M:init(title, x, y, filter, action, takeall, actor)
diff --git a/game/engines/default/engine/dialogs/ShowQuests.lua b/game/engines/default/engine/dialogs/ShowQuests.lua
index 29694ba1ec..ae590ff1aa 100644
--- a/game/engines/default/engine/dialogs/ShowQuests.lua
+++ b/game/engines/default/engine/dialogs/ShowQuests.lua
@@ -23,6 +23,8 @@ local ListColumns = require "engine.ui.ListColumns"
local TextzoneList = require "engine.ui.TextzoneList"
local Separator = require "engine.ui.Separator"
+--- Show Quests
+-- @classmod engine.dialogs.ShowQuests
module(..., package.seeall, class.inherit(Dialog))
function _M:init(actor)
diff --git a/game/engines/default/engine/dialogs/ShowStore.lua b/game/engines/default/engine/dialogs/ShowStore.lua
index 3bea550fd9..5b8503d567 100644
--- a/game/engines/default/engine/dialogs/ShowStore.lua
+++ b/game/engines/default/engine/dialogs/ShowStore.lua
@@ -24,6 +24,8 @@ local Textzone = require "engine.ui.Textzone"
local TextzoneList = require "engine.ui.TextzoneList"
local Separator = require "engine.ui.Separator"
+--- Show Store
+-- @classmod engine.dialogs.ShowStore
module(..., package.seeall, class.inherit(Dialog))
function _M:init(title, store_inven, actor_inven, store_filter, actor_filter, action, desc, descprice, allow_sell, allow_buy, on_select)
diff --git a/game/engines/default/engine/dialogs/ShowText.lua b/game/engines/default/engine/dialogs/ShowText.lua
index 58554c7097..03d4d15b35 100644
--- a/game/engines/default/engine/dialogs/ShowText.lua
+++ b/game/engines/default/engine/dialogs/ShowText.lua
@@ -21,6 +21,8 @@ require "engine.class"
local Dialog = require "engine.ui.Dialog"
local Textzone = require "engine.ui.Textzone"
+--- Show Text
+-- @classmod engine.dialogs.ShowText
module(..., package.seeall, class.inherit(Dialog))
function _M:init(title, file, replace, w, h, on_exit, accept_key)
diff --git a/game/engines/default/engine/dialogs/SteamOptions.lua b/game/engines/default/engine/dialogs/SteamOptions.lua
index e94f3bd93c..069ca769f5 100644
--- a/game/engines/default/engine/dialogs/SteamOptions.lua
+++ b/game/engines/default/engine/dialogs/SteamOptions.lua
@@ -24,6 +24,8 @@ local Textzone = require "engine.ui.Textzone"
local Separator = require "engine.ui.Separator"
local GetQuantity = require "engine.dialogs.GetQuantity"
+--- Steam Options
+-- @classmod engine.dialogs.SteamOptions
module(..., package.seeall, class.inherit(Dialog))
function _M:init()
diff --git a/game/engines/default/engine/dialogs/Talkbox.lua b/game/engines/default/engine/dialogs/Talkbox.lua
index 98f7748de8..07866a3d66 100644
--- a/game/engines/default/engine/dialogs/Talkbox.lua
+++ b/game/engines/default/engine/dialogs/Talkbox.lua
@@ -25,6 +25,8 @@ local Textbox = require "engine.ui.Textbox"
local Dropdown = require "engine.ui.Dropdown"
local Textzone = require "engine.ui.Textzone"
+--- player to player chatbox
+-- @classmod engine.dialogs.Talkbox
module(..., package.seeall, class.inherit(Dialog))
function _M:init(chat, on_end, only_friends)
diff --git a/game/engines/default/engine/dialogs/UseTalents.lua b/game/engines/default/engine/dialogs/UseTalents.lua
index 2eb32f86a0..92e415cc58 100644
--- a/game/engines/default/engine/dialogs/UseTalents.lua
+++ b/game/engines/default/engine/dialogs/UseTalents.lua
@@ -24,6 +24,8 @@ local Textzone = require "engine.ui.Textzone"
local TextzoneList = require "engine.ui.TextzoneList"
local Separator = require "engine.ui.Separator"
+--- Use Talents
+-- @classmod engine.dialogs.UseTalents
module(..., package.seeall, class.inherit(Dialog))
function _M:init(actor)
diff --git a/game/engines/default/engine/dialogs/UserInfo.lua b/game/engines/default/engine/dialogs/UserInfo.lua
index a8dd4b1208..612e204f17 100644
--- a/game/engines/default/engine/dialogs/UserInfo.lua
+++ b/game/engines/default/engine/dialogs/UserInfo.lua
@@ -22,6 +22,8 @@ local Dialog = require "engine.ui.Dialog"
local Button = require "engine.ui.Button"
local Textzone = require "engine.ui.Textzone"
+--- User Info for player to player chatbox
+-- @classmod engine.dialogs.UserInfo
module(..., package.seeall, class.inherit(Dialog))
function _M:init(data)
diff --git a/game/engines/default/engine/dialogs/VideoOptions.lua b/game/engines/default/engine/dialogs/VideoOptions.lua
index 1fa9d886ee..52c8a3afbc 100644
--- a/game/engines/default/engine/dialogs/VideoOptions.lua
+++ b/game/engines/default/engine/dialogs/VideoOptions.lua
@@ -24,6 +24,8 @@ local Textzone = require "engine.ui.Textzone"
local Separator = require "engine.ui.Separator"
local GetQuantity = require "engine.dialogs.GetQuantity"
+--- Video Options
+-- @classmod engine.dialogs.VideoOptions
module(..., package.seeall, class.inherit(Dialog))
function _M:init()
diff --git a/game/engines/default/engine/dialogs/ViewHighScores.lua b/game/engines/default/engine/dialogs/ViewHighScores.lua
index 27a6d77c5a..d65b2cd013 100644
--- a/game/engines/default/engine/dialogs/ViewHighScores.lua
+++ b/game/engines/default/engine/dialogs/ViewHighScores.lua
@@ -22,6 +22,8 @@ local Dialog = require "engine.ui.Dialog"
local Textzone = require "engine.ui.Textzone"
local HighScores = require "engine.HighScores"
+--- View Highscores
+-- @classmod engine.dialogs.ViewHighScores
module(..., package.seeall, class.inherit(Dialog))
function _M:init()
diff --git a/game/engines/default/engine/generator/actor/OnSpots.lua b/game/engines/default/engine/generator/actor/OnSpots.lua
index e605016588..30cec0ef62 100644
--- a/game/engines/default/engine/generator/actor/OnSpots.lua
+++ b/game/engines/default/engine/generator/actor/OnSpots.lua
@@ -20,6 +20,8 @@
require "engine.class"
local Map = require "engine.Map"
local Random = require "engine.generator.actor.Random"
+
+--- @classmod engine.generator.actor.OnSpots
module(..., package.seeall, class.inherit(Random))
function _M:init(zone, map, level, spots)
diff --git a/game/engines/default/engine/generator/actor/Random.lua b/game/engines/default/engine/generator/actor/Random.lua
index 72fc6d890c..0dcf3ae4d7 100644
--- a/game/engines/default/engine/generator/actor/Random.lua
+++ b/game/engines/default/engine/generator/actor/Random.lua
@@ -20,6 +20,8 @@
require "engine.class"
local Map = require "engine.Map"
require "engine.Generator"
+
+--- @classmod engine.generator.actor.Random
module(..., package.seeall, class.inherit(engine.Generator))
function _M:init(zone, map, level, spots)
diff --git a/game/engines/default/engine/generator/map/Building.lua b/game/engines/default/engine/generator/map/Building.lua
index 678e8cf65b..07c091da2e 100644
--- a/game/engines/default/engine/generator/map/Building.lua
+++ b/game/engines/default/engine/generator/map/Building.lua
@@ -22,6 +22,8 @@ local Map = require "engine.Map"
local BSP = require "engine.BSP"
require "engine.Generator"
local RoomsLoader = require "engine.generator.map.RoomsLoader"
+
+--- @classmod engine.generator.map.Building
module(..., package.seeall, class.inherit(engine.Generator, RoomsLoader))
function _M:init(zone, map, level, data)
diff --git a/game/engines/default/engine/generator/map/Cavern.lua b/game/engines/default/engine/generator/map/Cavern.lua
index aae12f75fa..bc2257e124 100644
--- a/game/engines/default/engine/generator/map/Cavern.lua
+++ b/game/engines/default/engine/generator/map/Cavern.lua
@@ -20,6 +20,8 @@
require "engine.class"
local Map = require "engine.Map"
require "engine.Generator"
+
+--- @classmod engine.generator.map.Cavern
module(..., package.seeall, class.inherit(engine.Generator))
function _M:init(zone, map, level, data)
diff --git a/game/engines/default/engine/generator/map/CavernousTunnel.lua b/game/engines/default/engine/generator/map/CavernousTunnel.lua
index 3f72d3694c..a2267dbca7 100644
--- a/game/engines/default/engine/generator/map/CavernousTunnel.lua
+++ b/game/engines/default/engine/generator/map/CavernousTunnel.lua
@@ -20,6 +20,8 @@
require "engine.class"
local Map = require "engine.Map"
require "engine.Generator"
+
+--- @classmod engine.generator.map.CavernousTunnel
module(..., package.seeall, class.inherit(engine.Generator))
function _M:init(zone, map, level, data)
diff --git a/game/engines/default/engine/generator/map/Empty.lua b/game/engines/default/engine/generator/map/Empty.lua
index be143a471c..9dce1fec1e 100644
--- a/game/engines/default/engine/generator/map/Empty.lua
+++ b/game/engines/default/engine/generator/map/Empty.lua
@@ -20,6 +20,8 @@
require "engine.class"
local Map = require "engine.Map"
require "engine.Generator"
+
+--- @classmod engine.generator.map.Empty
module(..., package.seeall, class.inherit(engine.Generator))
function _M:init(zone, map, level, data)
diff --git a/game/engines/default/engine/generator/map/Filled.lua b/game/engines/default/engine/generator/map/Filled.lua
index de0d43db1d..87f98f3772 100644
--- a/game/engines/default/engine/generator/map/Filled.lua
+++ b/game/engines/default/engine/generator/map/Filled.lua
@@ -20,6 +20,8 @@
require "engine.class"
local Map = require "engine.Map"
require "engine.Generator"
+
+--- @classmod engine.generator.map.Filled
module(..., package.seeall, class.inherit(engine.Generator))
function _M:init(zone, map, level, data)
diff --git a/game/engines/default/engine/generator/map/Forest.lua b/game/engines/default/engine/generator/map/Forest.lua
index f61cb11577..ccf16d1d75 100644
--- a/game/engines/default/engine/generator/map/Forest.lua
+++ b/game/engines/default/engine/generator/map/Forest.lua
@@ -23,6 +23,8 @@ require "engine.Generator"
local RoomsLoader = require "engine.generator.map.RoomsLoader"
local Astar = require"engine.Astar"
local DirectPath = require"engine.DirectPath"
+
+--- @classmod engine.generator.map.Forest
module(..., package.seeall, class.inherit(engine.Generator, RoomsLoader))
function _M:init(zone, map, level, data)
diff --git a/game/engines/default/engine/generator/map/GOL.lua b/game/engines/default/engine/generator/map/GOL.lua
index e98db0a98d..02f612d2f7 100644
--- a/game/engines/default/engine/generator/map/GOL.lua
+++ b/game/engines/default/engine/generator/map/GOL.lua
@@ -20,6 +20,8 @@
require "engine.class"
local Map = require "engine.Map"
require "engine.Generator"
+
+--- @classmod engine.generator.map.GOL
module(..., package.seeall, class.inherit(engine.Generator))
function _M:init(zone, map, level, data)
diff --git a/game/engines/default/engine/generator/map/Heightmap.lua b/game/engines/default/engine/generator/map/Heightmap.lua
index 4269aa509c..f511651654 100644
--- a/game/engines/default/engine/generator/map/Heightmap.lua
+++ b/game/engines/default/engine/generator/map/Heightmap.lua
@@ -21,6 +21,8 @@ require "engine.class"
local Map = require "engine.Map"
local Heightmap = require "engine.Heightmap"
require "engine.Generator"
+
+--- @classmod engine.generator.map.Heightmap
module(..., package.seeall, class.inherit(engine.Generator))
function _M:init(zone, map, level, data)
diff --git a/game/engines/default/engine/generator/map/Maze.lua b/game/engines/default/engine/generator/map/Maze.lua
index d45f576467..14d59a87e6 100644
--- a/game/engines/default/engine/generator/map/Maze.lua
+++ b/game/engines/default/engine/generator/map/Maze.lua
@@ -20,6 +20,8 @@
require "engine.class"
local Map = require "engine.Map"
require "engine.Generator"
+
+--- @classmod engine.generator.map.Maze
module(..., package.seeall, class.inherit(engine.Generator))
function _M:init(zone, map, grid_list, data)
diff --git a/game/engines/default/engine/generator/map/Octopus.lua b/game/engines/default/engine/generator/map/Octopus.lua
index 545472bc0d..ba77c062d8 100644
--- a/game/engines/default/engine/generator/map/Octopus.lua
+++ b/game/engines/default/engine/generator/map/Octopus.lua
@@ -20,6 +20,8 @@
require "engine.class"
local Map = require "engine.Map"
require "engine.generator.map.Roomer"
+
+--- @classmod engine.generator.map.Octopus
module(..., package.seeall, class.inherit(engine.generator.map.Roomer))
function _M:init(zone, map, level, data)
diff --git a/game/engines/default/engine/generator/map/Roomer.lua b/game/engines/default/engine/generator/map/Roomer.lua
index d0e2d9ce5a..9a258f3aaf 100644
--- a/game/engines/default/engine/generator/map/Roomer.lua
+++ b/game/engines/default/engine/generator/map/Roomer.lua
@@ -21,6 +21,8 @@ require "engine.class"
local Map = require "engine.Map"
require "engine.Generator"
local RoomsLoader = require "engine.generator.map.RoomsLoader"
+
+--- @classmod engine.generator.map.Roomer
module(..., package.seeall, class.inherit(engine.Generator, RoomsLoader))
function _M:init(zone, map, level, data)
diff --git a/game/engines/default/engine/generator/map/Rooms.lua b/game/engines/default/engine/generator/map/Rooms.lua
index ca26df7dfc..9fc4b7ece1 100644
--- a/game/engines/default/engine/generator/map/Rooms.lua
+++ b/game/engines/default/engine/generator/map/Rooms.lua
@@ -22,6 +22,7 @@ local Map = require "engine.Map"
require "engine.Generator"
--- Generator that makes a map
+-- @classmod engine.generator.map.Rooms
module(..., package.seeall, class.inherit(engine.Generator))
function _M:init(zone, map, level, data)
diff --git a/game/engines/default/engine/generator/map/RoomsLoader.lua b/game/engines/default/engine/generator/map/RoomsLoader.lua
index f5282013dc..092fd572a8 100644
--- a/game/engines/default/engine/generator/map/RoomsLoader.lua
+++ b/game/engines/default/engine/generator/map/RoomsLoader.lua
@@ -21,6 +21,7 @@ require "engine.class"
local Map = require "engine.Map"
--- Generator interface that can use rooms
+-- @classmod engine.generator.map.RoomsLoader
module(..., package.seeall, class.make)
function _M:init(data)
diff --git a/game/engines/default/engine/generator/map/Static.lua b/game/engines/default/engine/generator/map/Static.lua
index 99ca023a8d..c7fae705af 100644
--- a/game/engines/default/engine/generator/map/Static.lua
+++ b/game/engines/default/engine/generator/map/Static.lua
@@ -22,6 +22,8 @@ local Map = require "engine.Map"
local lom = require "lxp.lom"
local mime = require "mime"
require "engine.Generator"
+
+--- @classmod engine.generator.map.Static
module(..., package.seeall, class.inherit(engine.Generator))
auto_handle_spot_offsets = true
diff --git a/game/engines/default/engine/generator/map/TileSet.lua b/game/engines/default/engine/generator/map/TileSet.lua
index 893bfe164d..1115d16a95 100644
--- a/game/engines/default/engine/generator/map/TileSet.lua
+++ b/game/engines/default/engine/generator/map/TileSet.lua
@@ -20,6 +20,8 @@
require "engine.class"
local Map = require "engine.Map"
require "engine.Generator"
+
+--- @classmod engine.generator.map.TileSet
module(..., package.seeall, class.inherit(engine.Generator))
-- Deactivate too many prints
diff --git a/game/engines/default/engine/generator/map/Town.lua b/game/engines/default/engine/generator/map/Town.lua
index b0ac078330..4bd01da550 100644
--- a/game/engines/default/engine/generator/map/Town.lua
+++ b/game/engines/default/engine/generator/map/Town.lua
@@ -22,6 +22,8 @@ local Map = require "engine.Map"
local BSP = require "engine.BSP"
require "engine.Generator"
local RoomsLoader = require "engine.generator.map.RoomsLoader"
+
+--- @classmod engine.generator.map.Town
module(..., package.seeall, class.inherit(engine.Generator, RoomsLoader))
function _M:init(zone, map, level, data)
diff --git a/game/engines/default/engine/generator/object/OnSpots.lua b/game/engines/default/engine/generator/object/OnSpots.lua
index 66d1cbb49f..9d1a46e12b 100644
--- a/game/engines/default/engine/generator/object/OnSpots.lua
+++ b/game/engines/default/engine/generator/object/OnSpots.lua
@@ -20,6 +20,8 @@
require "engine.class"
local Map = require "engine.Map"
local Random = require "engine.generator.object.Random"
+
+--- @classmod engine.generator.object.OnSpots
module(..., package.seeall, class.inherit(Random))
function _M:init(zone, map, level, spots)
diff --git a/game/engines/default/engine/generator/object/Random.lua b/game/engines/default/engine/generator/object/Random.lua
index b2b8d669bb..953a4616c6 100644
--- a/game/engines/default/engine/generator/object/Random.lua
+++ b/game/engines/default/engine/generator/object/Random.lua
@@ -20,6 +20,8 @@
require "engine.class"
local Map = require "engine.Map"
require "engine.Generator"
+
+--- @classmod engine.generator.object.Random
module(..., package.seeall, class.inherit(engine.Generator))
function _M:init(zone, map, level)
diff --git a/game/engines/default/engine/generator/trap/Random.lua b/game/engines/default/engine/generator/trap/Random.lua
index 303ef9f367..572f7da53e 100644
--- a/game/engines/default/engine/generator/trap/Random.lua
+++ b/game/engines/default/engine/generator/trap/Random.lua
@@ -20,6 +20,8 @@
require "engine.class"
local Map = require "engine.Map"
require "engine.Generator"
+
+--- @classmod engine.generator.trap.Random
module(..., package.seeall, class.inherit(engine.Generator))
function _M:init(zone, map, level)
diff --git a/game/engines/default/engine/init.lua b/game/engines/default/engine/init.lua
index 47c6a69ee3..3be23f1a25 100644
--- a/game/engines/default/engine/init.lua
+++ b/game/engines/default/engine/init.lua
@@ -17,6 +17,8 @@
-- Nicolas Casalini "DarkGod"
-- darkgod@te4.org
+--- @script init.lua
+
-- load some utility functions
dofile("/engine/utils.lua")
dofile("/engine/colors.lua")
@@ -125,7 +127,7 @@ end
fs.umount(engine.homepath)
--- Staem cloud saves, disabled until the user chooses otherwise
+-- Steam cloud saves, disabled until the user chooses otherwise
if core.steam and not config.settings.steam_cloud_choose then
print("[STEAM] Disabling cloud saves until the user elects to use them")
core.steam.cloudEnable(false)
diff --git a/game/engines/default/engine/interface/ActorAI.lua b/game/engines/default/engine/interface/ActorAI.lua
index 00be78ea14..46b2499b1c 100644
--- a/game/engines/default/engine/interface/ActorAI.lua
+++ b/game/engines/default/engine/interface/ActorAI.lua
@@ -22,6 +22,7 @@ require "engine.Actor"
local Map = require "engine.Map"
--- Handles actors artificial intelligence (or dumbness ... ;)
+-- @classmod engine.generator.interface.ActorAI
module(..., package.seeall, class.make)
_M.ai_def = {}
@@ -158,7 +159,8 @@ _M.AI_LOCATION_GUESS_ERROR = 3 -- Start position guess errors at ~3 grids
-- This will usually return the exact coords, but if the target is only partially visible (or not at all)
-- it will return estimates, to throw the AI a bit off (up to 10 tiles error)
-- @param target the target we are tracking
--- @return x, y coords to move/cast to
+-- @return x coord to move/cast to
+-- @return y coord to move/cast to
function _M:aiSeeTargetPos(target)
if not target then return self.x, self.y end
local tx, ty = target.x, target.y
diff --git a/game/engines/default/engine/interface/ActorFOV.lua b/game/engines/default/engine/interface/ActorFOV.lua
index 4f80154467..edd203c2f5 100644
--- a/game/engines/default/engine/interface/ActorFOV.lua
+++ b/game/engines/default/engine/interface/ActorFOV.lua
@@ -23,6 +23,7 @@ local Map = require "engine.Map"
--- Handles actors field of view
-- When an actor moves it computes a field of view and stores it in self.fov<br/>
-- When an other actor moves it can update the fov of seen actors
+-- @classmod engine.generator.interface.ActorFOV
module(..., package.seeall, class.make)
_M.__do_distance_map = false
diff --git a/game/engines/default/engine/interface/ActorInventory.lua b/game/engines/default/engine/interface/ActorInventory.lua
index 3c3bfa1e60..cbef4838bb 100644
--- a/game/engines/default/engine/interface/ActorInventory.lua
+++ b/game/engines/default/engine/interface/ActorInventory.lua
@@ -25,6 +25,7 @@ local ShowEquipInven = require_first("mod.dialogs.ShowEquipInven", "engine.dialo
local ShowPickupFloor = require_first("mod.dialogs.ShowPickupFloor", "engine.dialogs.ShowPickupFloor")
--- Handles actors stats
+-- @classmod engine.generator.interface.ActorInventory
module(..., package.seeall, class.make)
_M.inven_def = {}
@@ -115,12 +116,15 @@ function _M:invenStackLimit(id)
end
--- Adds an object to an inventory
+-- checks o:on_preaddobject(self, inven) (must return true to add to inventory)
-- @param inven_id = inventory id to add to
-- @param o = object to add
-- @param no_unstack = boolean to prevent unstacking the object to be added
-- @param force_item to add to the set position instead of to the end
--- @return false if the object could not be added or true, inventory index it was moved to, remaining stack if any or false
--- checks o:on_preaddobject(self, inven) (must return true to add to inventory)
+-- @return[1] false if the object could not be added
+-- @return[2] true
+-- @return[2] inventory index it was moved to
+-- @return[2] remaining stack if any or false
function _M:addObject(inven_id, o, no_unstack, force_item)
local inven = self:getInven(inven_id)
local slot
@@ -178,7 +182,9 @@ end
-- @param inven = inventory or inventory id to search
-- @param o = object to look for
-- @param by_reference set true to match by exact (memory) reference, otherwise matches by o.name
--- @return nil or the inventory slot, stack position if stacked
+-- @return[1] nil
+-- @return[2] the inventory slot
+-- @return[2] stack position if stacked
function _M:itemPosition(inven, o, by_reference)
inven = self:getInven(inven)
local found, pos = nil, nil
@@ -193,14 +199,16 @@ function _M:itemPosition(inven, o, by_reference)
return nil
end
---- Pick up an object from the floor
--- @param i = object position on map at self.x, self.y
--- @param vocal = boolean to post messages to log
--- @param no_sort = boolen to suppress automatic sorting of inventory
--- puts picked up objects in self.INVEN_INVEN
--- @return the object picked up (or stack added to), num picked up or true if o:on_prepickup(i) returns true (not "skip") or nil
--- checks obj:on_prepickup(self, i) (must return true to pickup)
--- checks obj:on_pickup(self, num) and self:on_pickup_object(obj, num) functions after pickup (includes stacks)
+--- Pick up an object from the floor
+-- checks obj:on_prepickup(self, i) (must return true to pickup)
+-- checks obj:on_pickup(self, num) and self:on_pickup_object(obj, num) functions after pickup (includes stacks)
+-- @param i object position on map at self.x, self.y
+-- @param[type=boolean] vocal to post messages to log
+-- @param[type=boolean] no_sort suppress automatic sorting of inventory. puts picked up objects in self.INVEN_INVEN
+-- @return[1] nil
+-- @return[2] true if o:on_prepickup(i) returns true (not "skip")
+-- @return[3] the object picked up (or stack added to)
+-- @return[3] num picked up
function _M:pickupFloor(i, vocal, no_sort)
local inven = self:getInven(self.INVEN_INVEN)
if not inven then return end
@@ -243,11 +251,13 @@ function _M:pickupFloor(i, vocal, no_sort)
end
--- Removes an object from inventory
--- @param inven the inventory to remove from
+-- checks obj:on_preremoveobject(self, inven) (return true to not remove)
+-- @param inven_id the inventory to remove from
-- @param item inven slot of the item to remove
--- @param no_unstack = num items to remove into a new stack (set true to remove the original stack unchanged)
--- @return the object removed or nil if no item existed and a boolean saying if there is no more objects
--- checks obj:on_preremoveobject(self, inven) (return true to not remove)
+-- @param no_unstack num items to remove into a new stack (set true to remove the original stack unchanged)
+-- @return[1] nil if no item existed
+-- @return[1] a boolean saying if there is no more objects
+-- @return[2] the object removed
function _M:removeObject(inven_id, item, no_unstack)
local inven = self:getInven(inven_id)
@@ -308,11 +318,12 @@ function _M:onDropObject(o)
end
--- Drop an object on the floor
+-- checks item:on_drop(self) (return true to not drop)
-- @param inven the inventory to drop from
-- @param item the item id to drop
+-- @param vocal do we show a log message on dropping?
-- @param all set to remove part (if number) or all (if true) a stack
-- @return the object removed or nil if no item existed
--- checks obj:on_drop(self) (return true to not drop)
function _M:dropFloor(inven, item, vocal, all)
local o = self:getInven(inven)[item]
if not o then
@@ -335,9 +346,10 @@ function _M:dropFloor(inven, item, vocal, all)
end
--- Show combined equipment/inventory dialog
--- @param inven the inventory (from self:getInven())
+-- @param title title of the dialog
-- @param filter nil or a function that filters the objects to list
-- @param action a function called when an object is selected
+-- @param on_select the function to be called on selecting the item
function _M:showEquipInven(title, filter, action, on_select)
local d = ShowEquipInven.new(title, self, filter, action, on_select)
game:registerDialog(d)
@@ -345,6 +357,7 @@ function _M:showEquipInven(title, filter, action, on_select)
end
--- Show inventory dialog
+-- @param title title of the dialog
-- @param inven the inventory (from self:getInven())
-- @param filter nil or a function that filters the objects to list
-- @param action a function called when an object is selected
@@ -356,6 +369,7 @@ function _M:showInventory(title, inven, filter, action)
end
--- Show equipment dialog
+-- @param title title of the dialog
-- @param filter nil or a function that filters the objects to list
-- @param action a function called when an object is selected
function _M:showEquipment(title, filter, action)
@@ -365,6 +379,7 @@ function _M:showEquipment(title, filter, action)
end
--- Show floor pickup dialog
+-- @param title title of the dialog
-- @param filter nil or a function that filters the objects to list
-- @param action a function called when an object is selected
function _M:showPickupFloor(title, filter, action)
@@ -374,9 +389,9 @@ function _M:showPickupFloor(title, filter, action)
end
--- Can we wear this item?
--- @param o = object to wear
--- @param try_slot = inventory slot to wear (override)
--- checks self:canWearObjectCustom(o, try_slot) (return true to make unwearable)
+-- checks self:canWearObjectCustom(o, try_slot) (return true to make unwearable)
+-- @param o object to wear
+-- @param try_slot inventory slot to wear (override)
function _M:canWearObject(o, try_slot)
local req = rawget(o, "require")
@@ -438,7 +453,7 @@ end
--- Checks if the given item should respect its slot_forbid value
-- @param o the item to check
--- @param in_inven the inventory id in which the item is worn or tries to be worn
+-- @param in_inven_id the inventory id in which the item is worn or tries to be worn
function _M:slotForbidCheck(o, in_inven_id)
return true
end
@@ -449,13 +464,17 @@ function _M:getObjectOffslot(o)
end
--- Wear/wield an item
--- @param o = object to be worn
--- @param replace = boolean allow first object in wearable inventory to be removed to make space if needed
--- @vocal = boolean to post messages to game.logSeen(self, ....)
--- @force_inven = try to equip into this inventory only
--- @force_item = attempt to equip/replace into that slot
--- returns true or replaced object if succeeded or false if not, remaining stack of o if any
--- checks o:on_canwear(self, inven) (return true to prevent wearing)
+-- checks o:on_canwear(self, inven) (return true to prevent wearing)
+-- @param o object to be worn
+-- @param[type=boolean] replace allow first object in wearable inventory to be removed to make space if needed
+-- @param[type=boolean] vocal to post messages to game.logSeen(self, ....)
+-- @param[type=boolean] force_inven try to equip into this inventory only
+-- @param[type=boolean] force_item attempt to equip/replace into that slot
+-- @return[1] false
+-- @return[2] true
+-- @return[2] remaining stack of o if any
+-- @return[3] replaced object if succeeded
+-- @return[3] remaining stack of o if any
function _M:wearObject(o, replace, vocal, force_inven, force_item)
-- keep it cause stack might change later
local o_name = o:getName{do_color=true}
@@ -610,8 +629,10 @@ end
--- Finds an object by name in an inventory
-- @param inven the inventory to look into
-- @param name the name to look for
--- @param getname the parameters to pass to getName(), if nil the default is {no_count=true, force_id=true}
--- @return object, position or nil if not found
+-- @param[type=?table] getname the parameters to pass to getName(), if nil the default is {no_count=true, force_id=true}
+-- @return[1] nil if not found
+-- @return[2] object
+-- @return[2] position
function _M:findInInventory(inven, name, getname)
getname = getname or {no_count=true, force_id=true}
for item, o in ipairs(inven) do
@@ -622,7 +643,10 @@ end
--- Finds an object by name in all the actor's inventories
-- @param name the name to look for
-- @param getname the parameters to pass to getName(), if nil the default is {no_count=true, force_id=true}
--- @return object, position, inven_id or nil if not found
+-- @return[1] nil if not found
+-- @return[2] object
+-- @return[2] position
+-- @return[2] inven_id
function _M:findInAllInventories(name, getname)
for inven_id, inven in pairs(self.inven) do
local o, item = self:findInInventory(inven, name, getname)
@@ -634,7 +658,9 @@ end
-- @param inven the inventory to look into
-- @param prop the property to look for
-- @param value the value to look for, can be a function
--- @return object, position or nil if not found
+-- @return[1] nil if not found
+-- @return[2] object
+-- @return[2] position
function _M:findInInventoryBy(inven, prop, value)
if type(value) == "function" then
for item, o in ipairs(inven) do
@@ -650,7 +676,10 @@ end
--- Finds an object by property in all the actor's inventories
-- @param prop the property to look for
-- @param value the value to look for, can be a function
--- @return object, position, inven_id or nil if not found
+-- @return[1] nil if not found
+-- @return[2] object
+-- @return[2] position
+-- @return[2] inven_id
function _M:findInAllInventoriesBy(prop, value)
for inven_id, inven in pairs(self.inven) do
local o, item = self:findInInventoryBy(inven, prop, value)
@@ -661,7 +690,9 @@ end
--- Finds an object by reference in an inventory
-- @param inven the inventory to look into
-- @param so the object(reference) to look for
--- @return object, position or nil if not found
+-- @return[1] nil if not found
+-- @return[2] object
+-- @return[2] position
function _M:findInInventoryByObject(inven, so)
for item, o in ipairs(inven) do
if o == so then return o, item end
@@ -669,9 +700,11 @@ function _M:findInInventoryByObject(inven, so)
end
--- Finds an object by reference in all the actor's inventories
--- @param inven the inventory to look into
-- @param so the object(reference) to look for
--- @return object, position, inven_id or nil if not found
+-- @return[1] nil if not found
+-- @return[2] object
+-- @return[2] position
+-- @return[2] inven_id
function _M:findInAllInventoriesByObject(so)
for inven_id, inven in pairs(self.inven) do
local o, item = self:findInInventoryByObject(inven, so)
@@ -681,7 +714,7 @@ end
--- Applies fct over all items
-- @param inven the inventory to look into
--- @param fct the function to be called. It will receive three parameters: inven, item, object
+-- @func fct the function to be called. It will receive three parameters: inven, item, object
function _M:inventoryApply(inven, fct)
for item, o in ipairs(inven) do
fct(inven, item, o)
@@ -689,8 +722,7 @@ function _M:inventoryApply(inven, fct)
end
--- Applies fct over all items in all inventories
--- @param inven the inventory to look into
--- @param fct the function to be called. It will receive three parameters: inven, item, object
+-- @func fct the function to be called. It will receive three parameters: inven, item, object
function _M:inventoryApplyAll(fct)
for inven_id, inven in pairs(self.inven) do
self:inventoryApply(inven, fct)
@@ -698,6 +730,7 @@ function _M:inventoryApplyAll(fct)
end
--- Empties given inventory and marks items inside as never generated
+-- @param inven the inventory to empty
function _M:forgetInven(inven)
inven = self:getInven(inven)
if not inven then return end
diff --git a/game/engines/default/engine/interface/ActorLevel.lua b/game/engines/default/engine/interface/ActorLevel.lua
index 0a1a7d181d..ff3dc25d08 100644
--- a/game/engines/default/engine/interface/ActorLevel.lua
+++ b/game/engines/default/engine/interface/ActorLevel.lua
@@ -22,6 +22,7 @@ require "engine.class"
--- Interface to add leveling capabilities to actors
-- Defines the exp property, which is the current experience, level which is the current level and exp_worth which is a multiplier
-- to the monster level default exp
+-- @classmod engine.generator.interface.ActorLevel
module(..., package.seeall, class.make)
_M.actors_max_level = false
@@ -79,7 +80,8 @@ end
--- Get the exp needed for the given level
-- @param level the level to check exp for
--- @return the exp needed, or nil if this level is not achievable
+-- @return[1] nil if this level is not achievable
+-- @return[2] the exp needed
function _M:getExpChart(level)
if type(self.exp_chart) == "table" then
return self.exp_chart[level] * self.exp_mod
diff --git a/game/engines/default/engine/interface/ActorLife.lua b/game/engines/default/engine/interface/ActorLife.lua
index 0c24806d2a..85de07f209 100644
--- a/game/engines/default/engine/interface/ActorLife.lua
+++ b/game/engines/default/engine/interface/ActorLife.lua
@@ -23,6 +23,7 @@ local Target = require "engine.Target"
local DamageType = require "engine.DamageType"
--- Handles actors life and death
+-- @classmod engine.generator.interface.ActorLife
module(..., package.seeall, class.make)
function _M:init(t)
@@ -59,10 +60,14 @@ function _M:heal(value, src)
return value
end
---- Remove some HP from an actor
--- If HP is reduced to 0 then remove from the level and call the die method.<br/>
+--- Remove some HP from an actor
+-- If HP is reduced to 0 then remove from the level and call the die method.
-- When an actor dies its dead property is set to true, to wait until garbage collection deletes it
--- @return true/false if the actor died and the actual damage done
+-- @param value how much damage
+-- @param src attacker
+-- @string death_note message for death
+-- @return true/false if the actor died
+-- @return the actual damage done
function _M:takeHit(value, src, death_note)
if self.onTakeHit then value = self:onTakeHit(value, src) end
self.life = self.life - value
@@ -76,6 +81,8 @@ function _M:takeHit(value, src, death_note)
end
--- Called when died
+-- @param src attacker
+-- @string death_note message for death
function _M:die(src, death_note)
if game.level:hasEntity(self) then game.level:removeEntity(self) end
self.dead = true
@@ -89,6 +96,8 @@ end
--- Actor is being attacked!
-- Module authors should rewrite it to handle combat, dialog, ...
-- @param target the actor attacking us
+-- @param x placeholder
+-- @param y placeholder
function _M:attack(target, x, y)
game.logSeen(target, "%s attacks %s.", self.name:capitalize(), target.name:capitalize())
target:takeHit(10, self)
diff --git a/game/engines/default/engine/interface/ActorProject.lua b/game/engines/default/engine/interface/ActorProject.lua
index 4308ad6818..82cff500e0 100644
--- a/game/engines/default/engine/interface/ActorProject.lua
+++ b/game/engines/default/engine/interface/ActorProject.lua
@@ -23,6 +23,7 @@ local Target = require "engine.Target"
local DamageType = require "engine.DamageType"
--- Handles actors projecting damage to zones/targets
+-- @classmod engine.generator.interface.ActorProject
module(..., package.seeall, class.make)
_M.projectile_class = "engine.Projectile"
@@ -228,16 +229,20 @@ function _M:project(t, x, y, damtype, dam, particles)
return grids, stop_x, stop_y
end
---- Can we project to this grid ?
--- This function can be used for either just the boolean, or to tell you where the projection stops.
+--- Can we project to this grid?
+-- This function can be used for either just the boolean, or to tell you where the projection stops.
-- Two sets of coordinates will be returned, one for where the projection stops (stop_x, stop_y) and
-- one for where any radius effect should start from (radius_x, radius_y). The distinction is made
-- because a projection should hit the wall, but explosions should start one tile back to avoid
-- "leaking" through a one tile thick wall.
--- @param t a type table describing the attack, passed to engine.Target:getType() for interpretation
--- @param x target coords
--- @param y target coords
--- @return can_project, stop_x, stop_y, radius_x, radius_y.
+-- @param[type=table] t a type table describing the attack, passed to engine.Target:getType() for interpretation
+-- @number x target coords
+-- @number y target coords
+-- @return can_project
+-- @return stop_x
+-- @return stop_y
+-- @return radius_x
+-- @return radius_y
function _M:canProject(t, x, y)
if not x or not y then return end
local typ = Target:getType(t)
@@ -335,16 +340,17 @@ function _M:projectile(t, x, y, damtype, dam, particles)
return proj
end
+--- Do move
-- @param typ a target type table
-- @param tgtx the target's x-coordinate
-- @param tgty the target's y-coordinate
-- @param x the projectile's x-coordinate
--- @param y the projectile's x-coordinate
--- @param srcx the sources's x-coordinate
--- @param srcx the source's x-coordinate
+-- @param y the projectile's y-coordinate
+-- @param srcx the sourcs's x-coordinate
+-- @param srcy the source's y-coordinate
-- @return lx x-coordinate the projectile travels to next
-- @return ly y-coordinate the projectile travels to next
--- @return act should we call projectDoAct (usually only for beam)
+-- @return act should we call `projectDoAct`() (usually only for beam)
-- @return stop is this the last (blocking) tile?
function _M:projectDoMove(typ, tgtx, tgty, x, y, srcx, srcy)
local lx, ly, blocked_corner_x, blocked_corner_y = typ.line_function:step()
@@ -381,7 +387,7 @@ function _M:projectDoMove(typ, tgtx, tgty, x, y, srcx, srcy)
return lx, ly, false, false
end
-
+--- projectDoAct
function _M:projectDoAct(typ, tg, damtype, dam, particles, px, py, tmp)
-- Now project on each grid, one type
-- Call the projected method of the target grid if possible
@@ -403,6 +409,7 @@ function _M:projectDoAct(typ, tg, damtype, dam, particles, px, py, tmp)
end
end
+--- projectDoStop
function _M:projectDoStop(typ, tg, damtype, dam, particles, lx, ly, tmp, rx, ry, projectile)
local grids = {}
local function addGrid(x, y)
diff --git a/game/engines/default/engine/interface/ActorQuest.lua b/game/engines/default/engine/interface/ActorQuest.lua
index e6aafe95e2..e81b18af50 100644
--- a/game/engines/default/engine/interface/ActorQuest.lua
+++ b/game/engines/default/engine/interface/ActorQuest.lua
@@ -20,6 +20,7 @@
require "engine.class"
--- Handles actors quests
+-- @classmod engine.generator.interface.ActorQuest
module(..., package.seeall, class.make)
_M.quest_class = "engine.Quest"
diff --git a/game/engines/default/engine/interface/ActorResource.lua b/game/engines/default/engine/interface/ActorResource.lua
index 8690416a3e..04046cdf31 100644
--- a/game/engines/default/engine/interface/ActorResource.lua
+++ b/game/engines/default/engine/interface/ActorResource.lua
@@ -20,6 +20,7 @@
require "engine.class"
--- Handles actors life and death
+-- @classmod engine.generator.interface.ActorResource
module(..., package.seeall, class.make)
_M.resources_def = {}
diff --git a/game/engines/default/engine/interface/ActorStats.lua b/game/engines/default/engine/interface/ActorStats.lua
index b1c0b2297d..15404a22bf 100644
--- a/game/engines/default/engine/interface/ActorStats.lua
+++ b/game/engines/default/engine/interface/ActorStats.lua
@@ -20,6 +20,7 @@
require "engine.class"
--- Handles actors stats
+-- @classmod engine.generator.interface.ActorStats
module(..., package.seeall, class.make)
_M.stats_def = {}
diff --git a/game/engines/default/engine/interface/ActorTalents.lua b/game/engines/default/engine/interface/ActorTalents.lua
index 97d24a619f..a80cf4a9ef 100644
--- a/game/engines/default/engine/interface/ActorTalents.lua
+++ b/game/engines/default/engine/interface/ActorTalents.lua
@@ -20,6 +20,7 @@
require "engine.class"
--- Handles actors stats
+-- @classmod engine.generator.interface.ActorTalents
module(..., package.seeall, class.make)
_M.talents_def = {}
@@ -291,21 +292,24 @@ function _M:useTalentMessage(ab)
return str
end
---- Called before an talent is used
+--- Called before a talent is used
-- Redefine as needed
--- @param ab the talent (not the id, the table)
--- @param silent no messages will be outputted
--- @param fake no actions are taken, only checks
--- @return true to continue, false to stop
+-- @param[type=table] talent the talent (not the id, the table)
+-- @param[type=boolean] silent no messages will be outputted
+-- @param[type=boolean] fake no actions are taken, only checks
+-- @return[1] true to continue
+-- @return[2] false to stop
function _M:preUseTalent(talent, silent, fake)
return true
end
---- Called before an talent is used
+--- Called before a talent is used
-- Redefine as needed
--- @param ab the talent (not the id, the table)
+-- @param[type=table] talent the talent (not the id, the table)
-- @param ret the return of the talent action
--- @return true to continue, false to stop
+-- @param[type=boolean] silent no messages will be outputted
+-- @return[1] true to continue
+-- @return[2] false to stop
function _M:postUseTalent(talent, ret, silent)
return true
end
@@ -317,8 +321,8 @@ function _M:onTalentLuaError(ab, err)
return
end
---- Force a talent to activate without using energy or such
--- "def" can have a field "ignore_energy" to not consume energy; other parameters can be passed and handled by an overload of this method.
+--- Force a talent to activate without using energy or such
+-- "def" can have a field "ignore_energy" to not consume energy; other parameters can be passed and handled by an overload of this method.
-- Object activation interface calls this method with an "ignore_ressources" parameter
function _M:forceUseTalent(t, def)
local oldpause = game.paused
@@ -358,7 +362,9 @@ end
-- @param t_id the id of the talent to learn
-- @param force if true do not check canLearnTalent
-- @param nb the amount to increase the raw talent level by, default 1
--- @return true if the talent was learnt, nil and an error message otherwise
+-- @return[1] nil if failed
+-- @return[1] an error message
+-- @return[2] true if the talent was learned
function _M:learnTalent(t_id, force, nb)
-- print("[TALENT]", self.name, self.uid, "learning", t_id, force, nb)
local t = _M.talents_def[t_id]
@@ -441,7 +447,9 @@ end
--- Actor forgets a talent completly
-- @param t_id the id of the talent to learn
--- @return true if the talent was unlearnt, nil and an error message otherwise
+-- @return[1] nil if failed
+-- @return[1] an error message
+-- @return[2] true if the talent was unlearned
function _M:unlearnTalentFull(t_id)
local lvl = self:getTalentLevelRaw(t_id)
if lvl > 0 then self:unlearnTalent(t_id, lvl) end
@@ -449,6 +457,7 @@ end
--- Actor forgets a talent
-- @param t_id the id of the talent to learn
+-- @param nb
-- @return true if the talent was unlearnt, nil and an error message otherwise
function _M:unlearnTalent(t_id, nb)
if not self:knowTalent(t_id) then return false, "talent not known" end
@@ -539,6 +548,7 @@ end
--- Checks the talent if learnable
-- @param t the talent to check
-- @param offset the level offset to check, defaults to 1
+-- @param ignore_special ignore requirement of special
function _M:canLearnTalent(t, offset, ignore_special)
-- Check prerequisites
if rawget(t, "require") then
@@ -740,8 +750,11 @@ function _M:getTalentTypeFrom(id)
end
--- Actor learns a talent type
--- @param t_id the id of the talent to learn
--- @return true if the talent was learnt, nil and an error message otherwise
+-- @param tt the id of the talent to learn
+-- @param v value
+-- @return[1] nil if failed
+-- @return[1] an error message
+-- @return[2] true if the talent was learned
function _M:learnTalentType(tt, v)
if v == nil then v = true end
if self.talents_types[tt] then return end
@@ -752,8 +765,10 @@ function _M:learnTalentType(tt, v)
end
--- Actor forgets a talent type
--- @param t_id the id of the talent to learn
--- @return true if the talent was unlearnt, nil and an error message otherwise
+-- @param tt the id of the talent to unlearn
+-- @return[1] nil if failed
+-- @return[1] an error message
+-- @return[2] true if the talent was unlearned
function _M:unlearnTalentType(tt)
self.talents_types[tt] = false
self.changed = true
diff --git a/game/engines/default/engine/interface/ActorTemporaryEffects.lua b/game/engines/default/engine/interface/ActorTemporaryEffects.lua
index b70807f9b7..59741e447b 100644
--- a/game/engines/default/engine/interface/ActorTemporaryEffects.lua
+++ b/game/engines/default/engine/interface/ActorTemporaryEffects.lua
@@ -20,12 +20,13 @@
require "engine.class"
--- Handles actors temporary effects (temporary boost of a stat, ...)
+-- @classmod engine.generator.interface.ActorTemporaryEffects
module(..., package.seeall, class.make)
_M.tempeffect_def = {}
--- Defines actor temporary effects
--- Static!
+-- @static
function _M:loadDefinition(file, env)
local f, err = util.loadfilemods(file, setmetatable(env or {
DamageType = require "engine.DamageType",
@@ -38,7 +39,7 @@ function _M:loadDefinition(file, env)
end
--- Defines one effect
--- Static!
+-- @static
function _M:newEffect(t)
assert(t.name, "no effect name")
assert(t.desc, "no effect desc")
@@ -56,7 +57,7 @@ function _M:newEffect(t)
self["EFF_"..t.name] = "EFF_"..t.name
end
-
+--- init
function _M:init(t)
self.tmp = self.tmp or {}
end
@@ -161,7 +162,8 @@ end
--- Check timed effect
-- @param eff_id the effect to check for
--- @return either nil or the parameters table for the effect
+-- @return[1] nil
+-- @return[2] the parameters table for the effect
function _M:hasEffect(eff_id)
return self.tmp[eff_id]
end
@@ -215,7 +217,8 @@ end
--- Copy an effect ensuring temporary values are managed properly
-- @param eff_id the effect to copy
--- @return either nil or the parameters table for the effect
+-- @return[1] nil
+-- @return[2] the parameters table for the effect
function _M:copyEffect(eff_id)
if not self then return nil end
local param = table.clone( self:hasEffect(eff_id) )
diff --git a/game/engines/default/engine/interface/BloodyDeath.lua b/game/engines/default/engine/interface/BloodyDeath.lua
index 770df07c94..0e3d7ce34b 100644
--- a/game/engines/default/engine/interface/BloodyDeath.lua
+++ b/game/engines/default/engine/interface/BloodyDeath.lua
@@ -21,6 +21,7 @@ require "engine.class"
--- Interface to add a bloodyDeath() method to actors
-- When this method is called, the floor or walls around the late actor is covered in blood
+-- @classmod engine.generator.interface.BloodyDeath
module(..., package.seeall, class.make)
--- Makes the bloody death happen
diff --git a/game/engines/default/engine/interface/ControlCursorSupport.lua b/game/engines/default/engine/interface/ControlCursorSupport.lua
index e90c8474c8..6faa66001c 100644
--- a/game/engines/default/engine/interface/ControlCursorSupport.lua
+++ b/game/engines/default/engine/interface/ControlCursorSupport.lua
@@ -26,6 +26,7 @@ tiles = engine.Tiles.new(16, 16)
--- Handles control Cursor
-- This should work for anything that has a surface and x,y,w,h,font properties.
+-- @classmod engine.generator.interface.ControlCursorSupport
module(..., package.seeall, class.make)
function _M:startCursor()
diff --git a/game/engines/default/engine/interface/GameMusic.lua b/game/engines/default/engine/interface/GameMusic.lua
index 5bed92cb79..6885a49bb1 100644
--- a/game/engines/default/engine/interface/GameMusic.lua
+++ b/game/engines/default/engine/interface/GameMusic.lua
@@ -20,6 +20,7 @@
require "engine.class"
--- Handles music in the game
+-- @classmod engine.generator.interface.GameMusic
module(..., package.seeall, class.make)
--- Initializes musics
diff --git a/game/engines/default/engine/interface/GameSound.lua b/game/engines/default/engine/interface/GameSound.lua
index 47818fc7b9..3c4ae68eea 100644
--- a/game/engines/default/engine/interface/GameSound.lua
+++ b/game/engines/default/engine/interface/GameSound.lua
@@ -20,6 +20,7 @@
require "engine.class"
--- Handles sounds in the game
+-- @classmod engine.generator.interface.GameSound
module(..., package.seeall, class.make)
--- Initializes
diff --git a/game/engines/default/engine/interface/GameTargeting.lua b/game/engines/default/engine/interface/GameTargeting.lua
index 394f4a577c..782fe9d477 100644
--- a/game/engines/default/engine/interface/GameTargeting.lua
+++ b/game/engines/default/engine/interface/GameTargeting.lua
@@ -24,6 +24,7 @@ local Map = require "engine.Map"
local Target = require "engine.Target"
--- Handles default targeting interface & display
+-- @classmod engine.generator.interface.GameTargeting
module(..., package.seeall, class.make)
--- Initializes targeting
diff --git a/game/engines/default/engine/interface/ObjectActivable.lua b/game/engines/default/engine/interface/ObjectActivable.lua
index 54caa3bb0c..063edd36ef 100644
--- a/game/engines/default/engine/interface/ObjectActivable.lua
+++ b/game/engines/default/engine/interface/ObjectActivable.lua
@@ -21,6 +21,7 @@ require "engine.class"
--- Handles activable objects, much more simple than actor's resource
-- It can define simple activations, complex ones that use power and it can also activate talent (ActorTalents interface must also be used on the Object class in this case)
+-- @classmod engine.generator.interface.ObjectActivatable
module(..., package.seeall, class.make)
function _M:init(t)
diff --git a/game/engines/default/engine/interface/ObjectIdentify.lua b/game/engines/default/engine/interface/ObjectIdentify.lua
index 9885ce52dd..9374e6e7aa 100644
--- a/game/engines/default/engine/interface/ObjectIdentify.lua
+++ b/game/engines/default/engine/interface/ObjectIdentify.lua
@@ -20,6 +20,7 @@
require "engine.class"
--- Handles unidentified objects, and their identification
+-- @classmod engine.generator.interface.ObjectIdentify
module(..., package.seeall, class.make)
function _M:init(t)
diff --git a/game/engines/default/engine/interface/PlayerDumpJSON.lua b/game/engines/default/engine/interface/PlayerDumpJSON.lua
index 1bfdf4ae58..06c6207211 100644
--- a/game/engines/default/engine/interface/PlayerDumpJSON.lua
+++ b/game/engines/default/engine/interface/PlayerDumpJSON.lua
@@ -22,6 +22,7 @@ require "Json2"
--- Handles player json "char dump"
-- This is used for auto uploads to te4.org, could be for other stuff too
+-- @classmod engine.generator.interface.PlayerDumpJSON
module(..., package.seeall, class.make)
allow_late_uuid = false
diff --git a/game/engines/default/engine/interface/PlayerExplore.lua b/game/engines/default/engine/interface/PlayerExplore.lua
index 9eddab4b45..8c491636ad 100644
--- a/game/engines/default/engine/interface/PlayerExplore.lua
+++ b/game/engines/default/engine/interface/PlayerExplore.lua
@@ -17,15 +17,15 @@
-- Nicolas Casalini "DarkGod"
-- darkgod@te4.org
---- This file implements a simple auto-explore whereby a single command can explore unseen tiles and objects.
--- To see how a module can make auto-explore more robust, see "game/modules/tome/class/interface/PlayerExplore.lua"
---
--- Note that the floodfill algorithm in this file assumes that the movement costs for all grids are equal
-
require "engine.class"
local Map = require "engine.Map"
local Dialog = require "engine.ui.Dialog"
+--- This file implements a simple auto-explore whereby a single command can explore unseen tiles and objects.
+-- To see how a module can make auto-explore more robust, see "game/modules/tome/class/interface/PlayerExplore.lua"
+--
+-- Note that the floodfill algorithm in this file assumes that the movement costs for all grids are equal
+-- @classmod engine.generator.interface.PlayerExplore
module(..., package.seeall, class.make)
local function toSingle(x, y)
diff --git a/game/engines/default/engine/interface/PlayerHotkeys.lua b/game/engines/default/engine/interface/PlayerHotkeys.lua
index 0e38e640d6..6b6124b7ab 100644
--- a/game/engines/default/engine/interface/PlayerHotkeys.lua
+++ b/game/engines/default/engine/interface/PlayerHotkeys.lua
@@ -23,6 +23,7 @@ local Dialog = require "engine.ui.Dialog"
--- Handles player hotkey interface
-- This provides methods to bind and manage hotkeys as well as using them<br/>
-- This interface is designed to work with the engine.HotkeysDisplay class to display current hotkeys to the player
+-- @classmod engine.generator.interface.PlayerHotkeys
module(..., package.seeall, class.make)
_M.quickhotkeys = {}
diff --git a/game/engines/default/engine/interface/PlayerMouse.lua b/game/engines/default/engine/interface/PlayerMouse.lua
index 9f1f991bc2..ee3fc1bac0 100644
--- a/game/engines/default/engine/interface/PlayerMouse.lua
+++ b/game/engines/default/engine/interface/PlayerMouse.lua
@@ -24,6 +24,7 @@ local Map = require "engine.Map"
--- Handles player default mouse actions
-- Defines some methods to help use the mouse in an uniform way in all modules
+-- @classmod engine.generator.interface.PlayerMouse
module(..., package.seeall, class.make)
--- Runs to the clicked mouse spot
@@ -34,6 +35,7 @@ module(..., package.seeall, class.make)
-- @param tmy the coords clicked
-- @param spotHostiles a function taking only the player as a parameter that must return true if hostiles are in sight
-- @param astar_check nil or a function to check each tile on the astar path for passability
+-- @param force_move force movement even if mouse_move is disabled
function _M:mouseMove(tmx, tmy, spotHostiles, astar_check, force_move)
if not self.x or not self.y or not tmx or not tmy then return end
tmx = util.bound(tmx, 0, game.level.map.w - 1)
@@ -124,6 +126,12 @@ end
--
-- @param key the Key object to which to pass the event if not treated, this should be your game default key handler probably
-- @param allow_move true if this will allow player movement (you should use it to check that you are not in targetting mode)
+-- @param button the mouse button that was pressed
+-- @param mx absolute x
+-- @param my absolute y
+-- @param xrel relative x
+-- @param yrel relative y
+-- @param event click event
function _M:mouseHandleDefault(key, allow_move, button, mx, my, xrel, yrel, event)
if not game.level then return end
local tmx, tmy = game.level.map:getMouseTile(mx, my)
diff --git a/game/engines/default/engine/interface/PlayerRest.lua b/game/engines/default/engine/interface/PlayerRest.lua
index 26f8e73e33..276e29e04c 100644
--- a/game/engines/default/engine/interface/PlayerRest.lua
+++ b/game/engines/default/engine/interface/PlayerRest.lua
@@ -21,6 +21,7 @@ require "engine.class"
local Dialog = require "engine.ui.Dialog"
--- Handles player resting
+-- @classmod engine.generator.interface.PlayerRest
module(..., package.seeall, class.make)
--- Initializes resting
@@ -64,11 +65,10 @@ function _M:onRestStop()
end
--- Rest a turn
--- For a turn based game you want in you player's act() something like that:<br/>
--- <pre>
--- if not self:restStep() then game.paused = true end
--- </pre>
--- @return true if we can continue to rest, false otherwise
+-- For a turn based game you want in you player's act() something like the usage example
+-- @usage if not self:restStep() then game.paused = true end
+-- @return[1] true if we can continue to rest
+-- @return[2] false if we can't continue
function _M:restStep()
if not self.resting then return false end
@@ -84,9 +84,10 @@ function _M:restStep()
end
end
---- Can we continue resting ?
+--- Can we continue resting?
-- Rewrite this method to check for mana, life, whatever. By default we always return false so resting will never work
--- @return true if we can continue to rest, false otherwise
+-- @return[1] true if we can continue to rest
+-- @return[2] false if we can't continue
function _M:restCheck()
return false, "player:restCheck() method not defined"
end
diff --git a/game/engines/default/engine/interface/PlayerRun.lua b/game/engines/default/engine/interface/PlayerRun.lua
index c1c769ab50..505e5f9f13 100644
--- a/game/engines/default/engine/interface/PlayerRun.lua
+++ b/game/engines/default/engine/interface/PlayerRun.lua
@@ -22,6 +22,7 @@ local Dialog = require "engine.ui.Dialog"
--- Handles player running
-- This should work for running inside tunnel, alongside walls, in open spaces.<br/>
+-- @classmod engine.generator.interface.PlayerRun
module(..., package.seeall, class.make)
local function checkDir(a, dir, dist)
@@ -106,13 +107,11 @@ function _M:runFollow(path)
end
--- Run a turn
--- For a turn based game you want in you player's act() something like that:<br/>
--- <pre>
--- if not self:runStep() then game.paused = true end
--- </pre><br/>
--- This will move the actor using the :move() method, this SHOULD have been redefined by the module
--- to use energy, otherwise running will be free.
--- @return true if we can continue to run, false otherwise
+-- This will move the actor using the :move() method, this SHOULD have been redefined by the module to use energy, otherwise running will be free.
+-- For a turn based game you want in you player's act() something like the usage example
+-- @usage if not self:runStep() then game.paused = true end
+-- @return[1] true if we can continue to run
+-- @return[2] false if we can't continue
function _M:runStep()
if not self.running then return false end
@@ -238,11 +237,12 @@ function _M:runStep()
end
end
---- Can we continue running ?
--- Rewrite this method to hostiles, interesting terrain, whatever.
--- This method should be called by its submethod, it tries to detect changes in the terrain.<br/>
+--- Can we continue running?
+-- Rewrite this method to hostiles, interesting terrain, whatever.
+-- This method should be called by its submethod, it tries to detect changes in the terrain.
-- It will also try to follow tunnels when they simply change direction.
--- @return true if we can continue to run, false otherwise
+-- @return[1] true if we can continue to run
+-- @return[2] false if we can't continue
function _M:runCheck()
if not self.running.path then
local dir_is_cardinal = self.running.dir == 2 or self.running.dir == 4 or self.running.dir == 6 or self.running.dir == 8
diff --git a/game/engines/default/engine/interface/PlayerSlide.lua b/game/engines/default/engine/interface/PlayerSlide.lua
index 18e4799d28..2edc4de415 100644
--- a/game/engines/default/engine/interface/PlayerSlide.lua
+++ b/game/engines/default/engine/interface/PlayerSlide.lua
@@ -22,6 +22,7 @@ local Map = require "engine.Map"
--- Makes the player "slide" along walls when possible
-- Simply call x, y = self:tryPlayerSlide(x, y, force) in your player's move() method
+-- @classmod engine.generator.interface.PlayerSlide
module(..., package.seeall, class.make)
function _M:tryPlayerSlide(x, y, force)
diff --git a/game/engines/default/engine/interface/WorldAchievements.lua b/game/engines/default/engine/interface/WorldAchievements.lua
index e406492667..8c6e10b25f 100644
--- a/game/engines/default/engine/interface/WorldAchievements.lua
+++ b/game/engines/default/engine/interface/WorldAchievements.lua
@@ -22,6 +22,7 @@ local Dialog = require "engine.ui.Dialog"
local Achievement = require "engine.dialogs.Achievement"
--- Handles achievements in a world
+-- @classmod engine.generator.interface.WorldAchievements
module(..., package.seeall, class.make)
_M.achiev_defs = {}
diff --git a/game/engines/default/engine/resolvers.lua b/game/engines/default/engine/resolvers.lua
index 01b1c9c9ce..8f17f5ad8e 100644
--- a/game/engines/default/engine/resolvers.lua
+++ b/game/engines/default/engine/resolvers.lua
@@ -17,6 +17,8 @@
-- Nicolas Casalini "DarkGod"
-- darkgod@te4.org
+--- @script engine.resolvers
+
resolvers = {}
resolvers.calc = {}
diff --git a/game/engines/default/engine/ui/ActorFrame.lua b/game/engines/default/engine/ui/ActorFrame.lua
index 7008b9fea3..4a32a174df 100644
--- a/game/engines/default/engine/ui/ActorFrame.lua
+++ b/game/engines/default/engine/ui/ActorFrame.lua
@@ -21,6 +21,8 @@ require "engine.class"
local Base = require "engine.ui.Base"
local Tiles = require "engine.Tiles"
+
+--- @classmod engine.ui.ActorFrame
module(..., package.seeall, class.inherit(Base))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/Base.lua b/game/engines/default/engine/ui/Base.lua
index 5b7f50d1c9..409070939e 100644
--- a/game/engines/default/engine/ui/Base.lua
+++ b/game/engines/default/engine/ui/Base.lua
@@ -22,6 +22,7 @@ local KeyBind = require "engine.KeyBind"
local Mouse = require "engine.Mouse"
--- A generic UI element
+-- @classmod engine.ui.base
module(..., package.seeall, class.make)
local gfx_prefix = "/data/gfx/"
diff --git a/game/engines/default/engine/ui/Button.lua b/game/engines/default/engine/ui/Button.lua
index a2a66debb8..1b67d1d16e 100644
--- a/game/engines/default/engine/ui/Button.lua
+++ b/game/engines/default/engine/ui/Button.lua
@@ -22,6 +22,7 @@ local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
--- A generic UI button
+-- @classmod engine.ui.Button
module(..., package.seeall, class.inherit(Base, Focusable))
frame_ox1 = -5
diff --git a/game/engines/default/engine/ui/ButtonImage.lua b/game/engines/default/engine/ui/ButtonImage.lua
index 953f72f405..5d061f4d8f 100644
--- a/game/engines/default/engine/ui/ButtonImage.lua
+++ b/game/engines/default/engine/ui/ButtonImage.lua
@@ -22,7 +22,8 @@ local Tiles = require "engine.Tiles"
local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
---- A generic UI button
+--- A generic UI button image
+-- @classmod engine.ui.ButtonImage
module(..., package.seeall, class.inherit(Base, Focusable))
frame_ox1 = -5
diff --git a/game/engines/default/engine/ui/Checkbox.lua b/game/engines/default/engine/ui/Checkbox.lua
index 434aba1e5d..d638b32dc0 100644
--- a/game/engines/default/engine/ui/Checkbox.lua
+++ b/game/engines/default/engine/ui/Checkbox.lua
@@ -21,7 +21,8 @@ require "engine.class"
local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
---- A generic UI textbox
+--- A generic UI checkbox
+-- @classmod engine.ui.Checkbox
module(..., package.seeall, class.inherit(Base, Focusable))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/Dialog.lua b/game/engines/default/engine/ui/Dialog.lua
index d8104e1914..9aa8f08b7e 100644
--- a/game/engines/default/engine/ui/Dialog.lua
+++ b/game/engines/default/engine/ui/Dialog.lua
@@ -22,7 +22,8 @@ local KeyBind = require "engine.KeyBind"
local Base = require "engine.ui.Base"
local Particles = require "engine.Particles"
---- A generic UI button
+--- A generic UI Dialog
+-- @classmod engine.ui.Dialog
module(..., package.seeall, class.inherit(Base))
--- Requests a simple waiter dialog
diff --git a/game/engines/default/engine/ui/Dropdown.lua b/game/engines/default/engine/ui/Dropdown.lua
index ea22c6768d..fd377f9a9d 100644
--- a/game/engines/default/engine/ui/Dropdown.lua
+++ b/game/engines/default/engine/ui/Dropdown.lua
@@ -24,6 +24,7 @@ local List = require "engine.ui.List"
local Dialog = require "engine.ui.Dialog"
--- A generic UI list dropdown box
+-- @classmod engine.ui.Dropdown
module(..., package.seeall, class.inherit(Base, Focusable))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/Empty.lua b/game/engines/default/engine/ui/Empty.lua
index e61cd465d8..705dc00969 100644
--- a/game/engines/default/engine/ui/Empty.lua
+++ b/game/engines/default/engine/ui/Empty.lua
@@ -22,6 +22,7 @@ local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
--- An empty space
+-- @classmod engine.ui.Empty
module(..., package.seeall, class.inherit(Base))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/EquipDoll.lua b/game/engines/default/engine/ui/EquipDoll.lua
index b67c571d45..084b0c835a 100644
--- a/game/engines/default/engine/ui/EquipDoll.lua
+++ b/game/engines/default/engine/ui/EquipDoll.lua
@@ -23,6 +23,8 @@ local Focusable = require "engine.ui.Focusable"
local EquipDollFrame = require "engine.ui.EquipDollFrame"
local UIGroup = require "engine.ui.UIGroup"
+--- Equipment doll preview
+-- @classmod engine.ui.EquipDoll
module(..., package.seeall, class.inherit(Base, Focusable, UIGroup))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/EquipDollFrame.lua b/game/engines/default/engine/ui/EquipDollFrame.lua
index 4c6a9c8feb..22578ffb0d 100644
--- a/game/engines/default/engine/ui/EquipDollFrame.lua
+++ b/game/engines/default/engine/ui/EquipDollFrame.lua
@@ -21,6 +21,8 @@ require "engine.class"
local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
+--- Equipment Doll preview frame
+-- @classmod engine.ui.EquipDollFrame
module(..., package.seeall, class.inherit(Base, Focusable))
_M.font = core.display.newFont("/data/font/DroidSans.ttf", 10)
diff --git a/game/engines/default/engine/ui/Focusable.lua b/game/engines/default/engine/ui/Focusable.lua
index f012f79122..badb441eec 100644
--- a/game/engines/default/engine/ui/Focusable.lua
+++ b/game/engines/default/engine/ui/Focusable.lua
@@ -20,6 +20,7 @@
require "engine.class"
--- Make a UI element clickable
+-- @classmod engine.ui.Focusable
module(..., package.seeall, class.make)
can_focus = true
diff --git a/game/engines/default/engine/ui/GenericContainer.lua b/game/engines/default/engine/ui/GenericContainer.lua
index ad469650f5..9083fddddc 100644
--- a/game/engines/default/engine/ui/GenericContainer.lua
+++ b/game/engines/default/engine/ui/GenericContainer.lua
@@ -21,7 +21,8 @@ require "engine.class"
local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
---- An empty space
+--- An empty space that contains other elements
+-- @classmod engine.ui.GenericContainer
module(..., package.seeall, class.inherit(Base, Focusable))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/Gestures.lua b/game/engines/default/engine/ui/Gestures.lua
index fd816cadc4..d496c8e705 100644
--- a/game/engines/default/engine/ui/Gestures.lua
+++ b/game/engines/default/engine/ui/Gestures.lua
@@ -20,6 +20,7 @@
require "engine.class"
local KeyBind = require "engine.KeyBind"
+--- @classmod engine.ui.Gestures
module(..., package.seeall, class.make)
function _M:init(text, key_source, force_all)
diff --git a/game/engines/default/engine/ui/Image.lua b/game/engines/default/engine/ui/Image.lua
index 15ed63260b..9a0afc7969 100644
--- a/game/engines/default/engine/ui/Image.lua
+++ b/game/engines/default/engine/ui/Image.lua
@@ -22,6 +22,7 @@ local Tiles = require "engine.Tiles"
local Base = require "engine.ui.Base"
--- A generic UI image
+-- @classmod engine.ui.Image
module(..., package.seeall, class.inherit(Base))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/ImageList.lua b/game/engines/default/engine/ui/ImageList.lua
index 818f385cd8..92432b1631 100644
--- a/game/engines/default/engine/ui/ImageList.lua
+++ b/game/engines/default/engine/ui/ImageList.lua
@@ -24,6 +24,7 @@ local Slider = require "engine.ui.Slider"
local Focusable = require "engine.ui.Focusable"
--- A generic UI image list
+-- @classmod engine.ui.ImageList
module(..., package.seeall, class.inherit(Base, Focusable))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/Inventory.lua b/game/engines/default/engine/ui/Inventory.lua
index 62b05a2b52..e27a421348 100644
--- a/game/engines/default/engine/ui/Inventory.lua
+++ b/game/engines/default/engine/ui/Inventory.lua
@@ -26,6 +26,7 @@ local KeyBind = require "engine.KeyBind"
local UIGroup = require "engine.ui.UIGroup"
--- A generic inventory, with possible tabs
+-- @classmod engine.ui.Inventory
module(..., package.seeall, class.inherit(Base, Focusable, UIGroup))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/List.lua b/game/engines/default/engine/ui/List.lua
index 54869e26aa..04d71b856c 100644
--- a/game/engines/default/engine/ui/List.lua
+++ b/game/engines/default/engine/ui/List.lua
@@ -23,6 +23,7 @@ local Focusable = require "engine.ui.Focusable"
local Slider = require "engine.ui.Slider"
--- A generic UI list
+-- @classmod engine.ui.List
module(..., package.seeall, class.inherit(Base, Focusable))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/ListColumns.lua b/game/engines/default/engine/ui/ListColumns.lua
index 0f6beacee7..aec0592446 100644
--- a/game/engines/default/engine/ui/ListColumns.lua
+++ b/game/engines/default/engine/ui/ListColumns.lua
@@ -23,6 +23,7 @@ local Focusable = require "engine.ui.Focusable"
local Slider = require "engine.ui.Slider"
--- A generic UI multi columns list
+-- @classmod engine.ui.ListColumns
module(..., package.seeall, class.inherit(Base, Focusable))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/Numberbox.lua b/game/engines/default/engine/ui/Numberbox.lua
index 51861c1b21..55c59e861e 100644
--- a/game/engines/default/engine/ui/Numberbox.lua
+++ b/game/engines/default/engine/ui/Numberbox.lua
@@ -20,7 +20,8 @@
require "engine.class"
local Textbox = require "engine.ui.Textbox"
---- A generic UI textbox
+--- A generic UI number textbox
+--- @classmod engine.ui.Numberbox
module(..., package.seeall, class.inherit(Textbox))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/Separator.lua b/game/engines/default/engine/ui/Separator.lua
index becb7a40d6..195abdc522 100644
--- a/game/engines/default/engine/ui/Separator.lua
+++ b/game/engines/default/engine/ui/Separator.lua
@@ -20,7 +20,8 @@
require "engine.class"
local Base = require "engine.ui.Base"
---- A generic UI button
+--- A generic UI separator
+-- @classmod engine.ui.Separator
module(..., package.seeall, class.inherit(Base))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/Slider.lua b/game/engines/default/engine/ui/Slider.lua
index fc5aae49df..f750e4d8e5 100644
--- a/game/engines/default/engine/ui/Slider.lua
+++ b/game/engines/default/engine/ui/Slider.lua
@@ -21,6 +21,7 @@ require "engine.class"
local Base = require "engine.ui.Base"
--- A generic UI slider, usualy used by other UI elements
+-- @classmod engine.ui.Slider
module(..., package.seeall, class.inherit(Base))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/SubDialog.lua b/game/engines/default/engine/ui/SubDialog.lua
index e9468beb5a..9ba33d8d8c 100644
--- a/game/engines/default/engine/ui/SubDialog.lua
+++ b/game/engines/default/engine/ui/SubDialog.lua
@@ -23,6 +23,7 @@ local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
--- A generic UI button
+-- @classmod engine.ui.SubDialog
module(..., package.seeall, class.inherit(Base, Focusable))
title_shadow = true
diff --git a/game/engines/default/engine/ui/SurfaceZone.lua b/game/engines/default/engine/ui/SurfaceZone.lua
index e86f2cc90d..80bebe9fa0 100644
--- a/game/engines/default/engine/ui/SurfaceZone.lua
+++ b/game/engines/default/engine/ui/SurfaceZone.lua
@@ -21,7 +21,8 @@ require "engine.class"
local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
---- A generic UI list
+--- A generic UI surface zone
+-- @classmod engine.ui.SurfaceZone
module(..., package.seeall, class.inherit(Base, Focusable))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/Tab.lua b/game/engines/default/engine/ui/Tab.lua
index 3621198b46..dd3aad9e27 100644
--- a/game/engines/default/engine/ui/Tab.lua
+++ b/game/engines/default/engine/ui/Tab.lua
@@ -21,7 +21,8 @@ require "engine.class"
local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
---- A generic UI textbox
+--- A generic UI tab
+-- @classmod engine.ui.Tab
module(..., package.seeall, class.inherit(Base, Focusable))
frame_ox1 = -5
diff --git a/game/engines/default/engine/ui/Tabs.lua b/game/engines/default/engine/ui/Tabs.lua
index fa6b6c451d..1dfb675dfd 100644
--- a/game/engines/default/engine/ui/Tabs.lua
+++ b/game/engines/default/engine/ui/Tabs.lua
@@ -25,6 +25,7 @@ local Separator = require "engine.ui.Separator"
local UIGroup = require "engine.ui.UIGroup"
--- A tab container
+-- @classmod engine.ui.Tabs
module(..., package.seeall, class.inherit(Base, Focusable, UIGroup))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/Textbox.lua b/game/engines/default/engine/ui/Textbox.lua
index e6aeecc49f..a99e93bcca 100644
--- a/game/engines/default/engine/ui/Textbox.lua
+++ b/game/engines/default/engine/ui/Textbox.lua
@@ -22,6 +22,7 @@ local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
--- A generic UI textbox
+-- @classmod engine.ui.Textbox
module(..., package.seeall, class.inherit(Base, Focusable))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/Textzone.lua b/game/engines/default/engine/ui/Textzone.lua
index 1eea8d4e74..17481421c5 100644
--- a/game/engines/default/engine/ui/Textzone.lua
+++ b/game/engines/default/engine/ui/Textzone.lua
@@ -22,7 +22,8 @@ local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
local Slider = require "engine.ui.Slider"
---- A generic UI list
+--- A generic UI text zone
+-- @classmod engine.ui.Textzone
module(..., package.seeall, class.inherit(Base, Focusable))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/TextzoneList.lua b/game/engines/default/engine/ui/TextzoneList.lua
index efd488bd0c..51e52e7c95 100644
--- a/game/engines/default/engine/ui/TextzoneList.lua
+++ b/game/engines/default/engine/ui/TextzoneList.lua
@@ -23,7 +23,8 @@ local Focusable = require "engine.ui.Focusable"
local Slider = require "engine.ui.Slider"
local Separator = require "engine.ui.Separator"
---- A generic UI list
+--- A generic UI textzone list
+-- @classmod engine.ui.TextzoneList
module(..., package.seeall, class.inherit(Base, Focusable))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/TreeList.lua b/game/engines/default/engine/ui/TreeList.lua
index 42f5c1e2a1..4f5a2fb4f3 100644
--- a/game/engines/default/engine/ui/TreeList.lua
+++ b/game/engines/default/engine/ui/TreeList.lua
@@ -22,7 +22,8 @@ local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
local Slider = require "engine.ui.Slider"
---- A generic UI list
+--- A generic UI tree list
+-- @classmod engine.ui.TreeList
module(..., package.seeall, class.inherit(Base, Focusable))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/UIContainer.lua b/game/engines/default/engine/ui/UIContainer.lua
index 5475b36ce4..3967f01cdf 100644
--- a/game/engines/default/engine/ui/UIContainer.lua
+++ b/game/engines/default/engine/ui/UIContainer.lua
@@ -22,7 +22,8 @@ local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
local Slider = require "engine.ui.Slider"
---- A generic UI list
+--- A generic UI Container
+-- @classmod engine.ui.UIContainer
module(..., package.seeall, class.inherit(Base, Focusable))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/UIGroup.lua b/game/engines/default/engine/ui/UIGroup.lua
index 0c47a16153..e1e3a0d3a6 100644
--- a/game/engines/default/engine/ui/UIGroup.lua
+++ b/game/engines/default/engine/ui/UIGroup.lua
@@ -19,7 +19,8 @@
require "engine.class"
---- Make a UI element clickable
+--- A generic UI group
+-- @classmod engine.ui.UIGroup
module(..., package.seeall, class.make)
function _M:setInnerFocus(id)
diff --git a/game/engines/default/engine/ui/VariableList.lua b/game/engines/default/engine/ui/VariableList.lua
index 612bb6b161..edd43d681e 100644
--- a/game/engines/default/engine/ui/VariableList.lua
+++ b/game/engines/default/engine/ui/VariableList.lua
@@ -22,7 +22,8 @@ local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
local Slider = require "engine.ui.Slider"
---- A generic UI list
+--- A generic UI variable list
+-- @classmod engine.ui.VariableList
module(..., package.seeall, class.inherit(Base, Focusable))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/Waitbar.lua b/game/engines/default/engine/ui/Waitbar.lua
index 3759e9afdf..7d09a71bd3 100644
--- a/game/engines/default/engine/ui/Waitbar.lua
+++ b/game/engines/default/engine/ui/Waitbar.lua
@@ -21,6 +21,7 @@ require "engine.class"
local Base = require "engine.ui.Base"
--- A generic waiter bar
+-- @classmod engine.ui.WaitBar
module(..., package.seeall, class.inherit(Base))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/Waiter.lua b/game/engines/default/engine/ui/Waiter.lua
index 8b495e2734..789b4f8ea9 100644
--- a/game/engines/default/engine/ui/Waiter.lua
+++ b/game/engines/default/engine/ui/Waiter.lua
@@ -20,7 +20,8 @@
require "engine.class"
local Base = require "engine.ui.Base"
---- A generic waiter bar
+--- A generic waiter
+-- @classmod engine.ui.Waiter
module(..., package.seeall, class.inherit(Base))
function _M:init(t)
diff --git a/game/engines/default/engine/ui/WebView.lua b/game/engines/default/engine/ui/WebView.lua
index 69017503e4..36f6b5d34e 100644
--- a/game/engines/default/engine/ui/WebView.lua
+++ b/game/engines/default/engine/ui/WebView.lua
@@ -22,6 +22,7 @@ local Base = require "engine.ui.Base"
local Focusable = require "engine.ui.Focusable"
--- A web browser
+-- @classmod engine.ui.Webview
module(..., package.seeall, class.inherit(Base, Focusable))
function _M:init(t)
diff --git a/game/engines/default/engine/utils.lua b/game/engines/default/engine/utils.lua
index 3c4be1d86e..ec23843b80 100644
--- a/game/engines/default/engine/utils.lua
+++ b/game/engines/default/engine/utils.lua
@@ -17,6 +17,9 @@
-- Nicolas Casalini "DarkGod"
-- darkgod@te4.org
+--- Utility functionality used by a lot of the base classes
+-- @script engine.utils
+
local lpeg = require "lpeg"
function math.decimals(v, nb)
@@ -2075,7 +2078,7 @@ function core.fov.set_permissiveness(val)
end
--- Sets the FoV vision size of the source actor (if applicable to the chosen FoV algorithm).
--- @param should be any number between 0.0 and 1.0 (smallest to largest). Default is 1.
+-- @param val should be any number between 0.0 and 1.0 (smallest to largest). Default is 1.
-- val = 1.0 will result in symmetric vision and targeting (i.e., I can see you if and only if you can see me)
-- for applicable fov algorithms ("large_ass").
function core.fov.set_actor_vision_size(val)
@@ -2105,7 +2108,7 @@ function core.fov.set_algorithm(val)
end
--- Sets the vision shape or distance metric for field of vision, talent ranges, AoEs, etc.
--- @param should be a string: circle, circle_round (same as circle), circle_floor, circle_ceil, circle_plus1, octagon, diamond, square.
+-- @param val should be a string: circle, circle_round (same as circle), circle_floor, circle_ceil, circle_plus1, octagon, diamond, square.
-- See "src/fov/fov.h" to see how each shape calculates distance and height.
-- "circle_round" is aesthetically pleasing, "octagon" is a traditional roguelike FoV shape, and "circle_plus1" is similar to both "circle_round" and "octagon"
-- Default is "circle_round"
@@ -2307,16 +2310,16 @@ function util.removeForceSafeBoot()
if restore then fs.setWritePath(restore) end
end
--- Alias os.exit to our own exit method for cleanliness
+--- Alias os.exit to our own exit method for cleanliness
os.crash = os.exit
os.exit = core.game.exit_engine
--- Ultra weird, this is used by the C serialization code because I'm too dumb to make lua_dump() work on windows ...
+--- Ultra weird, this is used by the C serialization code because I'm too dumb to make lua_dump() work on windows ...
function __dump_fct(f)
return string.format("%q", string.dump(f))
end
--- Tries to load a lua module from a list, returns the first available
+--- Tries to load a lua module from a list, returns the first available
function require_first(...)
local list = {...}
for i = 1, #list do
@@ -2329,6 +2332,7 @@ function require_first(...)
return nil
end
+--- Is steamcloud available?
function util.steamCanCloud()
if core.steam and core.steam.isCloudEnabled(true) and core.steam.isCloudEnabled(false) and not savefile_pipe.disable_cloud_saves then return true end
end
diff --git a/game/engines/default/engine/version.lua b/game/engines/default/engine/version.lua
index 9968eac7e1..264cdbe3c7 100644
--- a/game/engines/default/engine/version.lua
+++ b/game/engines/default/engine/version.lua
@@ -17,11 +17,21 @@
-- Nicolas Casalini "DarkGod"
-- darkgod@te4.org
--- Engine Version
+--- In the format {1,4,0,"te4",17}
+-- Where values are {major, minor, patch, engine_name, c_core}
+-- @script engine.version
+
engine.version = {1,4,0,"te4",17}
engine.require_c_core = engine.version[5]
engine.version_id = ("%s-%d_%d.%d.%d"):format(engine.version[4], engine.require_c_core, engine.version[1], engine.version[2], engine.version[3])
+--- Check which version the engine is
+-- @param[type=table] v version table
+-- @return[1] "newer" if our version is newer
+-- @return[2] "lower" if our version is older
+-- @return[3] "same" if our versions are identical
+-- @return[4] "different engine" if it's an entirely different engine
+-- @return[5] "bad C core" if our c core is incorrect
function engine.version_check(v)
local ev = engine.version
if v[5] ~= core.game.VERSION then return "bad C core" end
@@ -33,10 +43,18 @@ function engine.version_check(v)
return "lower"
end
+--- Formatted engine string
+-- @param[type=table] v
+-- @return "te4.v[1].[v2].v[3]"
function engine.version_string(v)
return ("%s-%d.%d.%d"):format(v[4] or "te4", v[1], v[2], v[3])
end
+--- Takes a version string and turns it into a table
+-- @string[opt] s
+-- @return[1] {1, 0, 0} if s is absent
+-- @return[2] {x, y, z} if in format "x.y.z"
+-- @return[3] {x, y, z, name=str} if in format "x.y.z.str"
function engine.version_from_string(s)
local v = {1, 0, 0}
if not s then return v end
@@ -47,6 +65,12 @@ function engine.version_from_string(s)
return v
end
+--- Compare two engine tables
+-- @param[type=table] v the version we want to know about
+-- @param[type=table] ev the version to compare to
+-- @return[1] "newer" if our version is newer
+-- @return[2] "lower" if our version is older
+-- @return[3] "same" if our versions are identical
function engine.version_compare(v, ev)
if v[1] > ev[1] then return "newer" end
if v[1] == ev[1] and v[2] > ev[2] then return "newer" end
@@ -55,6 +79,14 @@ function engine.version_compare(v, ev)
return "lower"
end
+--- Compare two engine tables
+-- @param[type=table] v the version we want to know about
+-- @param[type=table] ev the version to compare to
+-- @return true if nearly the same
+-- @usage version_nearly_same({1.2.3}, {1.2.2}) = true
+-- version_nearly_same({1.3.0}, {1.1.5}) = true
+-- version_nearly_same({1.1.0}, {1.2.0}) = false
+-- version_nearly_same({0.9.2}, {1.2.2}) = false
function engine.version_nearly_same(v, ev)
if v[1] == ev[1] then
if v[2] == ev[2] and v[3] >= ev[3] then return true
@@ -64,6 +96,10 @@ function engine.version_nearly_same(v, ev)
return false
end
+--- Check if the two versions are identical
+-- @param[type=table] v version1
+-- @param[type=table] ev version2
+-- @return true if same
function engine.version_patch_same(v, ev)
if v[1] ~= ev[1] then return false end
if v[2] ~= ev[2] then return false end
diff --git a/game/engines/default/engine/webcore.lua b/game/engines/default/engine/webcore.lua
index a204b67190..7a28a7bc31 100644
--- a/game/engines/default/engine/webcore.lua
+++ b/game/engines/default/engine/webcore.lua
@@ -17,6 +17,8 @@
-- Nicolas Casalini "DarkGod"
-- darkgod@te4.org
+--- @classmod engine.webcore
+
if not core.webview then return end
local class = require "class"
--
GitLab