#+TITLE: SilverMUD Design Document
* What Is The Main Goal Of SilverMUD?
The main goal of SilverMUD is to create a text-based role playing game system
that is setting-agnostic, where a game master can create new content through
interacting with a Scheme REPL. SilverMUD will tend to favor simple abstractions
for game concepts, in order to accomplish being more setting-agnostic and easy
to play over the internet.

* Concepts:
** Worlds
Worlds are a collection of regions and dungeons, tied to a [[*Settings][setting]]. 

*** Regions
Regions are a collection of areas bundled together. This lets them be unloaded
and loaded as a group, as well as providing a mechanism for dividing your areas
based on locales or otherwise.

**** Areas
Areas are actual locations a player can be in. They have a description, name,
and can hold [[*Players][players]] and [[*Objects][objects]].

***** Exits
Exits are connections to other [[*Areas][areas]] or [[*Rooms][rooms]], which could be in another [[*Region][region]]
or [[*Dungeons][dungeon]]. They may have a "challenge" to pass, in order to use them, or a
requirement to access them in the first place.

*** Dungeons
Dungeons are similar to a region, but differ in one crucial way; they are
instanced, allowing for a single player or party (or potentially multiple) to
enter a copy of the dungeon, allowing for setups similar to a MUD or MMO, or
easily reusable encounters. 

**** Rooms
Rooms are the dungeon equivalent to areas. They are separated purely to
strengthen the distinction between dungeons and regions; this may change to add
additional functionality 

***** Exits
Exits are connections to other [[*Areas][areas]] or [[*Rooms][rooms]], which could be in another [[*Region][region]]
or [[*Dungeons][dungeon]]. They may have a "challenge" to pass, in order to use them, or a
requirement to access them in the first place. The exit leading to or from a
[[*Dungeon][dungeon]] may create and destroy the instance of the dungeon.

** Objects
Objects are a representation of items that can be in areas, rooms, or player's
inventories. They have a name, description, and uses. Looking at an object
displays the name, description, and uses.  

*** Uses
Uses are Scheme functions pushed onto the event queue when a player activates
them through the use command.

Uses may additionally have a usage requirement, and a visibility requirement.

A usage requirement is a Scheme function that is passed a reference to the
player attempting to activate the use. It returns #t or #f, corresponding to the
activation being successful or a failure.

A visibility requirement is a Scheme function that is passed a reference to the 
player viewing the object. It returns #t or #f, corresponding to the use being
displayed to the player or hidden.

*** Properties
Objects may have additional properties that dictate how they can be interacted
with. Currently planned properties are:

- player-pick-up :: Defines whether a object can be moved to a player's inventory
  from an area or room.
- player-put-down :: Defines whether a object can be moved from a player's inventory
  to an area or room.
  
** Events
SilverMUD centers around a central events queue; a queue of Scheme programs,
which are spawned in response to most things which happen in the game and mutate
the global state. Events are constantly evaluated by a thread which has access
to the relevant data structures.

Player commands are parsed from the command format into events by the input
thread. 

** Players
Players will be designed more fully as gameplay aspects are implemented. They
currently are planned to have core statistics, skills (setting-specific
statistics), abilities, health points, ability points, and character points,
which are used to purchase core statistic points, skill points, and abilities.

** Abilities
Abilities are similar to [[*Uses][uses]], with the distinction of being tied to [[*Players][players]] and
not [[*Objects][objects]]. They have a name, description, usage cost, skill point cost, and
effect, and a usage requirement.

*** Usage Cost
The usage cost of an ability refers to the amount of ability energy it costs a
player to attempt to activate it using the /activate command.

*** Character Point Cost
The amount of character points it costs to "purchase" the skill, and add it to
the player's character.

*** Effect
Effects are Scheme functions pushed onto the event queue when a player activates
them through the /activate command.

*** Usage Requirement
Abilities may optionally have a usage requirement. A usage requirement is a
Scheme function that is passed a reference to the player attempting to activate
the ability. It returns #t or #f, corresponding to the activation being
successful or a failure. 

** Settings
Settings are a combination of definitions of items, custom rules, and other
miscellaneous things like common description strings and enemy types. It's
somewhat analogous to a sourcebook or rulebook for a traditional table-top RPG,
allowing the game to take on different forms and settings depending on which
ones are being used. These are loaded as Scheme files in a [[*Worlds][world.]]