Doc edits

README.mkd

@@ -2,12 +2,12 @@
 
 # ranvier
 
-Node.js based MUD engine
+## Node.js-based MUD engine
 
 See the [staging](https://github.com/shawncplus/ranviermud/tree/staging) branch for the latest features.
 
-Ranvier is _not_ a websocket MUD. It does not have a web client. It is a plain ol' fashioned telnet MUD. Any client you
-use to connect to the MUD you played 15 years ago will work with Ranvier.
+Ranvier is _not_ a WebSocket MUD. It does not have a web client. It is a plain ol' fashioned telnet MUD. Any client you
+can use to connect to the MUD you played 15 years ago will work with Ranvier.
 
 ## Documentation
 
@@ -16,25 +16,25 @@ Ranvier prides itself on having thorough documentation which is available on our
 
 ## Slack
 
-We have a slack channel you can use to ask questions, suggest features, or just keep up to date with the project: [https://ranviermud.slack.com](https://ranviermud.slack.com)
+We have a Slack channel you can use to ask questions, suggest features, or just keep up to date with the project: [https://ranviermud.slack.com](https://ranviermud.slack.com)
 
 [Get an invite](https://ranviermud.signup.team/)
 
 ## Features
 
 * Robust bundle system: Nearly every aspect of the game can be modified without changing the core and allows for easy
   packaging and sharing of commands/areas/items/npcs/channels/behaviors
-* Scripting support: It's in Javascript! No need for a shitty DSL. The codebase is javascript, the scripting is javascript.
+* Scripting support: It's in JavaScript! No need for a shitty DSL. The codebase is JavaScript, the scripting is JavaScript.
 * Scripting is event-based. Put a listener in the script attached to your mob and it'll automagically happen when the
   event is emitted. Adding new events is easy as `npc.emit('eventName')` See documentation on Node.js event emitters for more detail
 * Pfile saving in JSON, easy to parse for external usage
 * Rooms, items, and NPCs are easily described in YAML. No weird bullshit ~~~~ and byte-specific parsing that requires a
   GUI editor to build (though we do have a GUI editor in the works!)
-* Did I mention it's in blasting javascript? No compiling, no C, no cygwin, no 15 year old spaghetti code
+* Did I mention it's in blasting JavaScript? No compiling, no C, no cygwin, no 15 year old spaghetti code
 
 ### Built-in Bundles
 
-The default bundles come together to make a basic Diku style MUD with the following features:
+The default bundles come together to make a basic Diku-style MUD with the following features:
 
 * Classes
 * Leveling
@@ -69,6 +69,6 @@ The default admin user/pass is `admin`/`ranviermud`
 
 ## Play it
 
-To try out what Ranvier looks like out of the box as a player telnet or point your favorite client to
-mud.ranviermud.com on port 4000. The server is updated from the github `staging` branch, reset, and restarted every
+To try out what Ranvier looks like out of the box, as a player, `telnet` or point your favorite client to
+mud.ranviermud.com on port 4000. The server is updated from the Github `staging` branch, reset, and restarted every
 hour.

docs/api.md

@@ -2,13 +2,13 @@ There is an in-progress Web interface for viewing information about the MUD and
 Currently, the following routes are supported:
 
 ```
-GET: 
+GET:
   /api/items
   /api/npcs
   /api/players
   /api/rooms
   /api/help
 ```
 
-Right now, you can whitelist IPs by adding them to a key called `webWhitelist` in ranvier.json.  By default only the
+Right now, you can whitelist IPs by adding them to a key called `webWhitelist` in ranvier.json.  By default, only the
 local host IP is whitelisted.

docs/extending/areas/index.md

@@ -25,7 +25,7 @@ ranvier-areas/
 
 ## The Manifest
 
-The manifest right now is incredibly simple and only requires one setting: `title`
+The manifest right now is incredibly simple and only requires one setting: `title`.
 
 Example Manifest
 
@@ -37,11 +37,11 @@ info:
 ```
 
 `respawnInterval` _`number`_
-:    Number of seconds between respawn ticks. See the [Room](rooms.md) section for respawn details
+:    Number of seconds between respawn ticks. See the [Room](rooms.md) section for details on handling respawn. Defaults to 60.
 
 ## Entity References
 
-Very often you'll see strings like `limbo:1`. These are entity references and can refer to Items, NPCs, Rooms, and Quests. The type of entity the reference points to is inferred from its usage (e.g., `foobar:1` in an `items` list would point to an Item.) Let's take a look at an example NPC definition
+You'll often see strings like `limbo:1`. These are entity references and can refer to Items, NPCs, Rooms, and Quests. The type of entity the reference points to is inferred from its context (e.g., `foobar:1` in an `items` list would point to an Item.) Let's take a look at an example NPC definition:
 
 Assuming both of these definitions live in `bundles/awesome-bundle/areas/foobar/`
 
@@ -58,6 +58,6 @@ and an accompanying item definition
   name: "Sword of Awesomeness"
 ```
 
-In the definition of Joe Schmoe `foobar:1` in the `items` property says "Find item with the ID `1` in the area `foobar`". Entity ids are only unique within the same entity type of the same area. So Joe Schmoe's entity reference would _also_ be `foobar:1`
+In the definition of Joe Schmoe, the value`foobar:1` in the `items` property's array means "Find item with the ID `1` in the area `foobar`". Entity ids are only unique within the same entity type of the same area. So Joe Schmoe's entity reference would _also_ be `foobar:1`, but would refer to an NPC.
 
-This type will be described in the subsequent docs as `EntityReference`
+This string will be described in the subsequent docs as `EntityReference`.

docs/extending/areas/items.md

@@ -4,7 +4,7 @@ In Ranvier all items for an area are defined in a single file within the area fo
 
 ## Example File
 
-`bundles/ranvier-areas/areas/limbo/npcs.yml`
+`bundles/ranvier-areas/areas/limbo/items.yml`
 ``` yaml
 - id: 1
   name: "Rusty Shiv"
@@ -43,17 +43,17 @@ In Ranvier all items for an area are defined in a single file within the area fo
 :    ***required*** Item id unique among the items of the current area
 
 `type` _`ItemType`_ `(OBJECT)`
-:    See `src/ItemType.js`. Natively doesn't not change _functionality_, simply a helper for you to use in scripts to
+:    See `src/ItemType.js`. Natively, does not change _functionality_, simply a helpful flag for you to use in scripts to
 detect the item type
 
 `name` _`string`_
-:    ***required*** String seen in the player's inventory, equipment list
+:    ***required*** String seen while in the player's inventory or equipment list, or in a container
 
 `roomDesc` _`string`_
 :    ***required*** String displayed when the item is seen on the ground in a room
 
 `keywords` _`string`_
-:    ***required*** Keywords that the player can use to target this item, does not need to be unique
+:    ***required*** Keywords that the player can use to target this item; keywords do not need to be unique on a per-item basis
 
 `description` _`string`_
 :    String displayed when the player looks directly at the item
@@ -62,16 +62,16 @@ detect the item type
 :    Name of custom script to attach to this item (See [Scripting](scripting.md))
 
 `behaviors` _`Object<string,Object>`_
-:    List of behaviors to attach to this item. Key is the behavior name, the value is the configuration for that
-behavior. For boolean (on/off) behaviors, `true` suffices for the config. (See [Scripting](scripting.md) for creating behaviors)
+:    List of behaviors to attach to this item. The key is the behavior name, the value is the configuration object for that
+behavior. For boolean (on/off) behaviors, `true` suffices for the config. (See [Scripting](scripting.md) for more on creating behaviors)
 
 `slot` _`string`_
-:    If the item can be equipped `slot` identifies the wear location of the item. This can be an arbitrary string but
-you probably want to limit to a standard list of locations
+:    If the item can be equipped, `slot` identifies the `wear` location of the item. This can be an arbitrary string but
+you probably want to limit equipment to a standard list of locations
 
 `attributes` _`object`_
 :    Arbitrary list of attributes to attach to this object. There are no constraints on this so you are free to assign
-basically anything here that you want to look for inside commands/scripts/etc.
+basically anything here that you want to look for inside commands/scripts/etc. Accessible in scripts via the `item.attributes` property
 
 `items` _`array<EntityReference>`_
-:    List of Entity References identifying which items should be loaded into this item's inventory
+:    For containers. A list of Entity References identifying which items should be loaded into this item's inventory

docs/extending/areas/npcs.md

@@ -1,4 +1,4 @@
-In Ranvier all npcs for an area are defined in a single file within the area folder: `npcs.yml`
+In Ranvier all NPCs for an area are defined in a single file within the area folder: `npcs.yml`
 
 [TOC]
 
@@ -34,7 +34,7 @@ In Ranvier all npcs for an area are defined in a single file within the area fol
         "limbo:4": 50
 ```
 
-Here we have two npcs. The rat can enter combat, has a custom script, a default inventory, hands out a quest and has
+Here we have two NPCs. The rat can enter combat, has a custom script, a default inventory, hands out a quest and has
 some extra attributes. The old man is the most basic NPC you can have.
 
 ## Definition Fields
@@ -44,27 +44,26 @@ some extra attributes. The old man is the most basic NPC you can have.
 ----
 
 `id` _`number`_
-:    ***required*** NPC id unique among the npcs of the current area
+:    ***required*** NPC id, unique among the NPCs of the current area
 
 `name` _`string`_
-:    ***required*** String displayed the player sees the npc in the room
+:    ***required*** String displayed when the player sees the NPC in the room
 
 `keywords` _`string`_
-:    ***required*** Keywords that the player can use to target this npc, does not need to be unique
+:    ***required*** Keywords that the player can use to target this NPC, keywords do not need to be unique
 
 `description` _`string`_
-:    ***required*** String displayed when the player looks directly at the npc
+:    ***required*** String displayed when the player looks directly at the NPC
 
 `script` _`string`_
-:    Name of custom script to attach to this npc (See [Scripting](scripting.md))
+:    Name of custom script to attach to this NPC (See [Scripting](scripting.md))
 
 `behaviors` _`Object<string,Object>`_
-:    List of behaviors to attach to this npc. Key is the behavior name, the value is the configuration for that
+:    List of behaviors to attach to this NPC. The key is the behavior name, the value is the configuration object for that
 behavior. For boolean (on/off) behaviors, `true` suffices for the config. (See [Scripting](scripting.md) for creating behaviors)
 
 `attributes` _`object`_
-:    Arbitrary list of attributes to attach to this NPC. There are no constraints on this so you are free to assign
-basically anything here that you want to look for inside commands/scripts/etc.
+:    Arbitrary list of attributes to attach to this NPC. Unlike items, these attributes will be turned into an AttributesMap (see `src/Attributes` and `src/Character`, so these are not arbitrary.
 
 `items` _`array<EntityReference>`_
 :    List of Entity References representing the NPC's default inventory