evennia/contrib/battle_for_evennia/README

Battle for Evennia
------------------

Evennia contrib - Griatch 2012 (WORK IN PROGRESS)

This is the beginnings of what will be a tutorial for building a
simple yet still reasonably playable and not-quite-bog-standard
starting game in Evennia. The tutorial text itself will eventually be
found from the Dev blog and from the wiki.


Ideas & Initial Brainstorm
---------------------------

This is to be a hack&slash game. Characters fight mobiles and each
other for random loot and better weapons. The highscore is based on
most accumulated gold. They can sell loot to NPC merchants for gold,
and also buy stuff others sold there (spending gold). Characters get
better in the skills they use (no levels). They automatically collect
loot when they kill things, and they cannot drop it (but they can give
it away and, most importantly sell it). Death sends the player back to
a starting position, but gives all but their weakest gear to their
nemesis (they keep all their gold though).

Inventory of code we need:
- Loot/Equipment lists of Weapons, Armour, Potions and Spells - maybe partly randomly generated.
- Way to spawn in-game objects based on the loot lists
- Character creation module (choose skills, attributes, assigns starting gear)
- 3 Attributes, about 10 skills (some magic?)
- Experience -> skill increase code
- Skill success code - same between PCs as between NPC and PC
- Combat code (twitch-based? Turn-based? Turn based seems easier to balance. Same for NPC vs PC and PC vs PC)
- Mobile code (same for NPCs and enemies)
- 'Give' mechanism (should require consent by receiver)
- No quests, for simplicity. Use gold as a highscore.
- Death respawn mechanism


Elaboration based on Brainstorm
-------------------------------

 * Loot/Equipment lists and spawn - These could be global-level
   dictionaries in a module. Each dictionary gives info such as name,
   description and typeclass. Attributes could be set or
   randomized. The loot-spawner (probably a handler tied to a dead
   mob, treasure chest etc) would use utils.variable_from_module to
   extract a random item-template.

 * Characters have 3 attributes: Wile, Strength and Agility. At
   creation, they distribute points between them. Wile is used for
   bartering with merchants, and using Magic. Strength determines
   hand-weapon damage and how heavy armour can be worn. Agility
   determines ability to dodge, initiative and using lighter weapons.
   Health is based on an average of all three attributes (i.e. all
   chars start with the same health).

 * Skills are as follows (may change):
     - Long blades (str) ability to hit with swords and also axes.
     - Blunt (str) usage of blunt weapons like clubs. Good on armoured foes.
     - Spears (agi) usage of spears and hillebards. Bonus on first attack, minus on initiative.
     - Daggers (agi) usage of daggers and short blades. Bonus on initiative, bad on armour
     - Unarmoured (agi) usage of your fists and feet. Very fast. Bad on armour.
     - Dodge (agi) avoiding blows by swift footwork
     - Feint (agi) faign attacks to keep the enemy guessing
     - Shield (str) absorbing hits with a shielf
     - Platemail (str) utilizing heavy armour
     - Chainmail (max(str, agi)) utilizing medium armour
     - Leather (agi) utilizing light armour
     - Barter (wil) barter with merchants for a good price
     - Magic (wil) use of single-use magical scrolls to achieve various effects
     - Potions (wil) making the best of potions with various effects
     - Heal (wil) fixing yourself (or a friend) up between combat. Also judge opponent's wounds.

 * Experience simply rises upon kills and is distributed between the
   skills used in the battle (so we need to log this). After N amount of
   XP in a skill, that skill automatically goes up one
   point. Increasing skills at least N points in 3+ different skills
   of a certain type (str, agi, wil) will increase the most trained
   Attribute by one point.

 * Skill success is a comparison between the value of a random.gauss
   centered around the attacker's skill value vs the result of a
   random.gauss centered on the defender's skill. Certain
   weapons/defense combinations might be especially effective against
   one another (or not). The difference is the base damage, then
   adjusted by weapon and armour. In the case of bartering, skill
   challenge is between barter skill of both sides; difference
   influences the discount/higher price offered for selling/buying.

 * Attacking another player or NPC will start a combat queue.
   Combat happens in turns. Each turn each player may enter two actions,
   picking among the following:
     - attack
     - parry (with weapon)
     - shield
     - feint
     - dodge
     - flee <direction>
     - block (anti-flee)
     - switch <weapon>
   Emoting is free in each round, but movement is forbidden unless one
   tries to flee (agi challenge, or cancelled by block action).  All
   combattants involved in a fight submits their actions, then combat
   is resolved simultaneously by the code. Order of the two actions
   matter, so for example if both attack, neither is trying to parry,
   but may hit each other simultaneously. If both parry, shield or
   dodge, it means both are dancing about each other. If one feints
   and the other parries or dodges, they will have a disadvantage on
   the next defensive movement. A successful parry will give the
   parried attacker a disadvantage on their next attack. And so on.
   Another player may "join the queue" at any time by attacking one of
   the combatting PCs. They get to insert their actions together with
   the rest on the next round.  A round should probably have a timeout
   to avoid a Character clogging the queue.

 * Mobiles will use "a global ticker system" where they
   subscribe. They act the same way as PCs in combat, except with a
   semi- random selection of actions they take (they will probably be
   more predictable than PCs). Adding aggressive and passive mobiles
   should be straightforward, as well as un-killable ones (merchants).

 * The inventory of a defeated enemy is automatically transferred to
   the winner's inventory. If there are many alternative pieces of
   equipment, they get to keep the weakest one, otherwise it's all
   transferred. There are no limits to carrying except the fear of
   losing gear. This should hopefully prevent hoarding of good items.
   One can give item(s) to another player - that player must then
   conceed to receiving it (use Y/N module in contrib.menusystem).
   There is no way of dropping items on the ground; one must either
   give them away or sell them for gold to a merchant.

 * Gold is used for buying items from merchants, but is also the
   highscore. Whereas sell prices are fixed, buy prices are not fixed
   but is based on a percentage of the gold carried, adjusted by the
   barter skill (this should defeat inflation quite effectively). Items
   sold to merchants are made available for other players to buy.

 * Death means loosing inventory (except weakest item, as mentioned),
   but no loss of gold. Otherwise death is cheap - one respawns at a
   random starting position (probably needing special-aliased rooms to
   use for this - maybe with one-way exits).


Rough plan for order of implementation
--------------------------------------

1) Conflict resolution system - work out how basic challenges should work, what format ingoing Skills
   should have and how generic bonuses from attributes and equipment affect things. Make a generic
   API for it. Try to list all supported plus/minues equipment may offer.
2) Using skills - create XP and automatic skill improvement code
3) Define new Character typeclass that stores skills/attributes in a way that the conflict
   system understands. Chars should also have the ability to "wear" things, so some
   sort of slot system is needed. Gold needs to be stored in a separate variable.
4) Create "sell/buy" command stump, for testing the Skill resolution code with fixed on-character values.
5) Create Combat queue code for turn-taking combat. Reiterate so that it works with the generic form of
   Skills and conflict resolution.
6) Create all included skills and their associated commands.
7) Test commands manually with two PC characters in the Combat queue and in other challenge situations.
8) Create loot-creation mechanism based on equipment lists, for spawning semi-random items and gear.
9) Create Death-respawn mechanism, including loss of equipment and transfer of same to the winner.
10) Create NPC/mobile object runner Script. Use a copy of Character typeclass for mobiles, except some
    automation hooks and AI states. Tie loot creation to the death of NPCs.
11) Test PC vs NPC combat and other challenges.
12) Create merchants as interactive, immortal NPCs with the "barter" skill.
13) Create Character creation module, for assigning attributes/skills when first starting.
    Add appropriate commands to ooccmdset.
14) Add "give" command to command set. Remove unused commands like "drop" (or make it admin-only). Possibly
    expand "look" command to allow to look across exits into the next room. Also add "highscore" command for
    viewing game statistics.
15) <starting building of game world>