docs

git-svn-id: http://svn.net-core.org/repos/t-engine4@15 51575b47-30f0-44d4-a5cc-537603b46e54

game/engine/Entity.lua

+--- 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 betetr to use specific engine.Grid, engine.Actor or engine.Object
+-- classes. Most modules will want to subclass those anyway to add new comportments
 module(..., package.seeall, class.make)
 
 local next_uid = 1
@@ -5,6 +9,10 @@ local next_uid = 1
 -- Setup the uids repository as a weak value table, when the entities are no more used anywhere else they disappear from there too
 setmetatable(__uids, {__mode="v"})
 
+--- Initialize an entity
+-- Any subclass MUST call this constructor
+-- @param t a table defining the basic properties of the entity
+-- @usage Entity.new{display='#', color_r=255, color_g=255, color_b=255}
 function _M:init(t)
 	t = t or {}
 	self.uid = next_uid
@@ -31,12 +39,19 @@ function _M:cloned()
 	next_uid = next_uid + 1
 end
 
+--- 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
 function _M:check(prop, ...)
 	if type(self[prop]) == "function" then return self[prop](self, ...)
 	else return self[prop]
 	end
 end
 
+--- Loads a list of entities from a definition file
+-- @param ... the files to load from
+-- @usage MyEntityClass:loadList("/data/my_entities_def.lua")
 function _M:loadList(...)
 	local res = {}
 

game/engine/Game.lua

 require "engine.class"
+
+--- Represent a game
+-- A module should subclass it and initialize anything it needs to play inside
 module(..., package.seeall, class.make)
 
+--- Constructor
+-- Sets up the default keyhandler.
+-- Also requests the display size and stores it in "w" and "h" properties
 function _M:init(keyhandler)
 	self.key = keyhandler
 	self.level = nil
 	self.w, self.h = core.display.size()
 end
 
+--- Starts the game
+-- Modules should reimplement it to do whatever their game needs
 function _M:run()
 end
 
+--- Sets the current level
+-- @param level an engine.Level (or subclass) object
 function _M:setLevel(level)
 	self.level = level
 end
 
+--- Tells the game engine to play this game
 function _M:setCurrent()
 	core.game.set_current_game(self)
 	_M.current = self
 end
 
+--- Displays the screen
+-- Called by the engine core to redraw the screen every frame
 function _M:display()
 	if self.level and self.level.map then
 		local s = self.level.map:display()
@@ -26,7 +39,6 @@ function _M:display()
 	end
 end
 
--- This is the "main game loop", do something here
+--- This is the "main game loop", do something here
 function _M:tick()
-
 end

game/engine/GameEnergyBased.lua

 require "engine.class"
 require "engine.Game"
+
+--- 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
 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 recieves 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, energy_per_tick
 	engine.Game.init(self, keyhandler)
 end
 
+--- Gives energy and act if needed
 function _M:tick()
 	engine.Game.tick(self)
 

game/engine/GameTurnBased.lua

 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/>
+-- 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
 module(..., package.seeall, class.inherit(engine.GameEnergyBased))
 
+--- See engine.GameEnergyBased
 function _M:init(keyhandler, energy_to_act, energy_per_tick)
 	self.paused = false
 	engine.GameEnergyBased.init(self, keyhandler, energy_to_act, energy_per_tick)

game/engine/Key.lua

 require "engine.class"
+
+--- Basic keypress handler
+-- The engine calls receiveKey when a key is pressed
 module(..., package.seeall, class.make)
 
 function _M:init()
 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?
+-- @param unicode the unicode representation of the key, if possible
 function _M:receiveKey(sym, ctrl, shift, alt, meta, unicode)
 	print(sym, ctrl, shift, alt, meta, unicode)
 end
 
+--- Setups as the current game keyhandler
 function _M:setCurrent()
 	core.key.set_current_handler(self)
 	_M.current = self

game/engine/KeyCommand.lua

 require "engine.class"
 require "engine.Key"
+
+--- Receieves keypresses and acts upon them
 module(..., package.seeall, class.inherit(engine.Key))
 
 function _M:init()
@@ -24,6 +26,10 @@ function _M:receiveKey(sym, ctrl, shift, alt, meta, unicode)
 	end
 end
 
+--- Adds a key/command combinaison
+-- @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
 function _M:addCommand(sym, mods, fct)
 	if type(sym) == "string" then sym = self[sym] end
 	if not sym then return end
@@ -37,6 +43,19 @@ function _M:addCommand(sym, mods, fct)
 	end
 end
 
+--- Adds many key/command at once
+-- @usage self.key:addCommands{<br/>
+--   _LEFT = function()<br/>
+--     print("left")<br/>
+--   end,<br/>
+--   _RIGHT = function()<br/>
+--     print("right")<br/>
+--   end,<br/>
+--   {{"x","ctrl"}] = function()<br/>
+--     print("control+x")<br/>
+--   end,<br/>
+-- }
+
 function _M:addCommands(t)
 	for k, e in pairs(t) do
 		if type(k) == "string" then

game/engine/Level.lua

 require "engine.class"
 module(..., package.seeall, class.make)
 
-function _M:init(map)
+function _M:init(level, map)
+	self.level = level
 	self.map = map
 	self.entities = {}
 end

game/engine/Map.lua

@@ -11,10 +11,15 @@ ACTOR = 20
 displayOrder = { ACTOR, OBJECT, TERRAIN }
 rememberDisplayOrder = { TERRAIN }
 
-function _M:init(w, h, tile_w, tile_h)
+-- Static
+function _M:setViewPort(w, h, tile_w, tile_h)
+	self.viewport = {width=w, height=h}
 	self.tiles = Tiles.new(tile_w, tile_h)
-	self.w, self.h = math.floor(w / tile_w), math.floor(h / tile_h)
 	self.tile_w, self.tile_h = tile_w, tile_h
+end
+
+function _M:init(w, h)
+	self.w, self.h = w, h
 	self.map = {}
 	self.lites = {}
 	self.seens = {}
@@ -32,7 +37,7 @@ function _M:init(w, h, tile_w, tile_h)
 	setmetatable(self.seens, {__call = mapbool})
 	setmetatable(self.remembers, {__call = mapbool})
 
-	self.surface = core.display.newSurface(w, h)
+	self.surface = core.display.newSurface(self.viewport.width, self.viewport.height)
 	self.fov = core.fov.new(_M.opaque, _M.apply, self)
 	self.fov_lite = core.fov.new(_M.opaque, _M.applyLite, self)
 	self.changed = true

game/engine/Zone.lua

+require "engine.class"
+
+--- Defines a zone: a set of levels, with depth, nps, objects, level generator, ...
 module(..., package.seeall, class.make)
 
+--- Setup classes to use for level generation
 -- Static method
--- Setup classes to use for entities
+-- @param t table that contains the name of the classes to use
+-- @usage Required fields:
+-- npc_class (default engine.Actor)
+-- grid_class (default engine.Grid)
+-- object_class (default engine.Object)
 function _M:setup(t)
-	self.npc_class = require(t.npc_class)
-	self.grid_class = require(t.grid_class)
-	self.object_class = require(t.object_class)
+	self.map_class = require(t.map_class or "engine.Map")
+	self.level_class = require(t.level_class or "engine.Level")
+	self.npc_class = require(t.npc_class or "engine.Actor")
+	self.grid_class = require(t.grid_class or "engine.Grid")
+	self.object_class = require(t.object_class or "engine.Object")
 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
 function _M:init(short_name)
 	self.short_name = short_name
 	self:load()
+	assert(self.max_level, "no zone max level")
 	self.levels = self.levels or {}
 	self.npc_list = self.npc_class:loadList("/data/zones/"..self.short_name.."/npcs.lua")
 	self.grid_list = self.grid_class:loadList("/data/zones/"..self.short_name.."/grids.lua")
@@ -21,5 +34,34 @@ function _M:load()
 	local f, err = loadfile("/data/zones/"..self.short_name.."/zone.lua")
 	if err then error(err) end
 	local data = f()
+	for k, e in pairs(data) do self[k] = e end
+end
+
+function _M:getLevelData(lev)
+	if not self.levels[lev] then return self end
+
+	local res = {}
+	for k, e in pairs(self) do res[k] = e end
+	for k, e in pairs(self.levels[lev]) do res[k] = e end
+	return res
+end
+
+--- Asks the zone to generate a level of level "lev"
+-- @param lev the level (from 1 to zone.max_level)
+-- @return a Level object
+function _M:getLevel(lev)
+	local level_data = self:getLevelData(lev)
+
+	local map = self.map_class.new(level_data.width, level_data.height)
+	map:liteAll(0, 0, map.w, map.h)
+	map:rememberAll(0, 0, map.w, map.h)
+
+	local floor = self.grid_list.GRASS
+	local wall = self.grid_list.TREE
+
+	local generator = require(level_data.generator.class).new(map, {0.4, 0.6}, floor, wall)
+	generator:generate()
 
+	local level = self.level_class.new(lev, map)
+	return level
 end

game/engine/generator/BST.lua

@@ -22,8 +22,8 @@ function _M:split(x, y, w, h)
 		split = rng.range(h * self.splitzone[1], h * self.splitzone[2])
 		x1, y1, w1, h1 = x, y, w, split
 		x2, y2, w2, h2 = x, y + split, w, h - split
-		print(x1, y1, w1, h1)
-		print(x2, y2, w2, h2)
+--		print(x1, y1, w1, h1)
+--		print(x2, y2, w2, h2)
 	end
 	return {x1, y1, w1, h1}, {x2, y2, w2, h2}
 end

game/modules/tome/class/Game.lua

@@ -22,6 +22,8 @@ function _M:run()
 	self:setupCommands()
 
 	Zone:setup{npc_class="mod.class.NPC", grid_class="engine.Grid", object_class="engine.Entity"}
+	Map:setViewPort(self.w, math.floor(self.h * 0.80), 16, 16)
+
 	self.zone = Zone.new("ancient_ruins")
 
 	self.tooltip = engine.Tooltip.new(nil, nil, {255,255,255}, {30,30,30})
@@ -29,17 +31,7 @@ function _M:run()
 	self.log = engine.LogDisplay.new(self.w * 0.5, self.h * 0.20, nil, nil, nil, {255,255,255}, {30,30,30})
 	self.log("Welcome to #00FF00#Tales of Middle Earth!")
 
-	local map = Map.new(self.w, math.floor(self.h * 0.80), 16, 16)
-	map:liteAll(0, 0, map.w, map.h)
-	map:rememberAll(0, 0, map.w, map.h)
-
-	local floor = self.zone.grid_list.GRASS
-	local wall = self.zone.grid_list.TREE
-
-	local generator = BST.new(map, {0.4, 0.6}, floor, wall)
-	generator:generate()
-
-	local level = Level.new(map)
+	local level = self.zone:getLevel(1)
 	self:setLevel(level)
 
 	self.player = Player.new{name="player", image='player.png', display='@', color_r=230, color_g=230, color_b=230}

game/modules/tome/data/zones/ancient_ruins/zone.lua

 return {
+	name = "ancient ruins",
+	max_level = 5,
+	width = 50, height = 30,
+	generator =  { class= "engine.generator.BST", }
 }

make_doc.sh

+#!/bin/sh
+cd game
+luadoc --nofiles -d ../doc `find engine -name '*lua'`
+cd ..
+