Update README

Author: ddevault

README.md

@@ -1,6 +1,7 @@
 # StarryPy
 
-StarryPy is Twisted-based plugin-driven Starbound server wrapper. It is currently in beta.
+StarryPy is Twisted-based plugin-driven Starbound server wrapper. It is currently
+in beta.
 
 ## Features
 
@@ -19,81 +20,141 @@ With the built-in plugins (which are removable):
 StarryPy runs on Python 2.7. It has been tested with Python 2.7.6, 2.7.5, 2.7.2,
 and PyPy.
 
-This requires Python and pip to install, and on *nix systems the python
-development headers (python-dev in apt, python-devel in yum.) After installing
-those, simply run `pip install -r requirements.txt` in the root directory of
-StarryPy. This will install all of the components needed for use. I recommend
-running it in a virtualenv.
+Below I provide installation instructions for Linux and Windows. Please note that
+Windows setup is more complex and in general seems to be buggier. I develop for
+Linux primarily, so you may consider the windows instructions unsupported; though
+they did work for me in a VM.
 
-Create a configuration file using the config.json.example. The most important
-things to note are owner\_uuid, which should be set to a character's UUID that
-you possess and have never shared; server\_address and server\_port, which
-should be set to the proxied server. StarryPy will default to port 21025 for
-normal clients to connect to. Select a good random port, or set it to 21024 and
-firewall it off from the outside.
+### Linux
+
+(CentOS instructions coming in the near future.) On Debian, the installation is
+decidedly simple, but it will require sudo access if you do not have python 2.7
+installed.
+
+First, let's make sure that all the prerequisites are installed:
+
+`sudo apt-get install python2.7 python-dev python-pip git`
+
+After installing the prerequisites, clone the repo in the directory of your choice
+using git:
+
+`git clone https://github.com/CarrotsAreMediocre/StarryPy`
+
+### Windows 
+
+As a reminder, though this worked for me I cannot guarantee it will fork for you.
+I offer no particular support for running StarryPy on windows as it has become a
+huge time sink that has dragged me away from development proper. If, however, you
+run into actual bugs with the server in Windows, please do let me know.
+
+#### Download Python
+
+We'll be using ActiveState python for ease of use. This way you don't have to
+monkey around with your paths. Just download it from
+[here](http://www.activestate.com/activepython/downloads). ***Make sure you grab
+the 32-bit 2.7 version and not the python 3 version; the server will not run on
+Python 3, nor will it work with the 64-bit version on Windows due to licensing
+requirements.***
+
+#### Download StarryPy from GitHub. 
+
+I personally recommend using git, but a zip file will suffice. Please note that if
+you choose not to use git (not too hard to figure out), future upgrades are far
+more likely to break everything.
+
+If not using git, click the Download zip file on the right side of the page. 
+
+Move the StarryPy-master folder somewhere convenient. You can rename it to
+whatever you like.
+
+#### Install requirements. 
+
+For this step, you'll need to get inside the StarryPy folder in the command
+prompt. For Vista or greater, which hopefully you are all running, you can simply
+open up the folder, make sure you don't have any files selected, and then hold
+down shift and right click in the empty space of the folder. There will be an
+option to 'Open Command Window Here' or something along those lines.
+
+If you can't find that window, run the command 'cmd'. Then, use 'cd
+directory_name' to get to the right place. If you go too high, use 'cd..' to go
+down a level.
+
+Once you're in the StarryPy folder, run 'pypm install -r requirements.txt' to
+install all of the dependencies. It will give you an error about enum34; don't
+worry about it, we'll take care of that next.
+
+After all the components are done installing, run 'pypm install pip'. Wait for
+that to finish installing, and then run 'pip install enum34'.
+
+Finally, once that's done, we can move onto configuration.
+
+## Configuration
+
+There are two areas of configuration that we are concerned with. The first is the
+StarryPy configuration, and the second is Starbound configuration.
+
+For StarryPy, you will have to create a configuration file. Copy
+config.json.example to config.json in the config/ folder, and edit the following
+variables:
+
+* upstream_port: This is the port that Starbound will be running on. I recommend
+  21026. It **must** match the port in your starbound.config file.
+* upstream_hostname: Change this if you are hosting the wrapper on a different
+  computer than your server.
+* bind_port: This should be 21025 normally; it is the port that StarryPy listens
+  on.
+* passthrough: **Make sure this is false.** It is an emergency off switch for
+  StarryPy.
+
+Finally, find starbound.config and change `gameport` to be exactly the same as
+`upstream_port` in config.json.
 
 ## Run it
 
-After making sure the Starbound server is running, use your terminal (cmd or
+**After making sure the Starbound server is running**, use your terminal (cmd or
 powershell on windows) and `cd` to the directory you installed StarryPy into.
 Enter `python server.py` to start the proxy.
 
 ## Built-in plugins
 
 StarryPy is nearly entirely plugin driven (our plugin manager is a plugin!), so
 there are quite a few built-in plugins. The truly important plugins are in the
-`core\_plugins` folder. If you remove any of those, it's likely that most other
+core\_plugins folder. If you remove any of those, it's likely that most other
 plugins will break. We'll break them down by core plugin and normal plugin
-classes. If you are looking for the commands, feel free to skip the core plugins
-section.
+classes. 
+
+If you are looking for commands, they have been removed from the listing due to
+the constant flux and the time required for documentation. For a list of commands
+that you can access from your current user level, use /help. For help with a
+specific command, use /help command_name.
 
 ### Core Plugins
 
-Core plugins are plugins that have no dependencies and are intended to be
-accessed by other plugins. If your plugin doesn't meet those criteria, it is
-recommended to put it in the normal plugins folder.
+Core plugins are plugins that have no dependencies and are intended to be accessed
+by other plugins. If your plugin doesn't meet those criteria, it is recommended to
+put it in the normal plugins folder.
 
 #### Player Manager
 
 The player manager is perhaps the most essential plugin of them all. It keeps
-track of each player that logs in, tracks their position, and manages
-kicks/bans. It is composed of the actual database manager, using SQLAlchemy on
-an SQLite3 backend by default.
+track of each player that logs in, tracks their position, and manages kicks/bans.
+It is composed of the actual database manager, using SQLAlchemy on an SQLite3
+backend by default.
 
 #### Command Plugin
 
 This is a core plugin that works in conjunction with the plugin class
 SimpleCommandPlugin. SimpleCommandPlugins automatically register their commands
 with the instantiated command plugin and when a chat packet is sent it is
-automatically parsed. If it matches one of these commands, it sends it off to
-that function for processing. If it doesn't match any of the commands, it sends
-it on its merry way to the actual starbound server for processing.
+automatically parsed. If it matches one of these commands, it sends it off to that
+function for processing. If it doesn't match any of the commands, it sends it on
+its merry way to the actual starbound server for processing.
 
 ### Plugins
 
 #### Admin Commands
 
-The admin commands plugin implements player management from in game. It is a
-SimpleCommandPlugin that provides the following commands:
-
-* **/who**: Displays all users currently logged into the server. `Access: Everyone`
-* **/planet**: Displays all users on your current planet. `Access: Everyone`
-* **/whois**: Displays user information. Includes player UUID, IP address,
-  username, access level, and current planet. `Access: Admin`
-* **/promote**: Promotes/demotes a user to a given access level. You can only
-  promote if you are a moderator or above, and then only to a user of lesser rank
-  than yourself. `Access: Moderator`
-* **/kick**: Kicks a user by username. If the name has spaces, enclose it in
-  quotes. `Access: Moderator`
-* **/ban**: Bans an IP address. Best fetched with /whois. It does not support
-  usernames. `Access: Admin`
-* **/bans**: Lists all active IP bans. `Access: Admin`
-* **/unban**: Unbans an IP address. `Access: Admin`
-* **/mute**: Mutes a player. `Access: Moderator`
-* **/unmute**: Unmutes a player. `Access: Moderator`
-* **/give\_item**: Gives an item to a player. Syntax is /give\_item player
-  (enclosed in quotes if it has spaces) itemname count. The default limit for
-  number of items to give to a player is 1000. `Access: Admin`
+The admin commands plugin implements player management from in game.
 
 #### Admin Messenger
 
@@ -106,8 +167,8 @@ This plugin simply announces whenever a player joins or quits the server.
 
 #### Bouncer
 
-This plugin prevents non-registered users from building or destroying anything.
-It is disabled by default. 
+This plugin prevents non-registered users from building or destroying anything. It
+is disabled by default. 
 
 #### Colored names
 
@@ -116,10 +177,7 @@ are set in config.json.
 
 #### MOTD    
 
-This plugin sends a Message of the Day on login. The MOTD is located in motd.txt
-in the plugin folder. It provides the following command:
-
-* **/set\_motd**: Sets the MOTD to the following text. `Access: Moderator`
+This plugin sends a Message of the Day on login. 
 
 #### New Player Greeter
 
@@ -129,35 +187,18 @@ starter\_items.txt). Default items are 200 `coalore` and 5 `alienburger`s.
 
 #### Planet Protection
 
-This plugin protects specified planets against modification in any way.
-Currently if a planet is protected only Admins may modify it. This plugin
-provides the following commands:
-
-* **/protect**: Protects the planet you are currently on. `Access: Admin`
-* **/unprotect**: Unprotects the planet you are currently on. `Access: Admin`
+This plugin protects specified planets against modification in any way. Currently
+if a planet is protected only registered users may modify it. 
 
 #### Plugin Manager
 
 This plugin provides a method of enabling/disabling plugins. I know it's silly
-that it's a plugin, you don't have to tell me. It provides the following
-commands:
-
-* **/list\_plugins**: Sends you a list of all loaded plugins. `Access: Admin`
-* **/disable\_plugin**: Disables a plugin by name. `Access: Admin`
-* **/enable\_plugin**: Enables a plugin by name. `Access: Admin`
-* **/help**: This command provides a list of commands if called by itself, and
-  the help string for a command if given a name. Example syntax: /help
-  enable\_plugin. `Access: Everyone`
+that it's a plugin, you don't have to tell me.
 
 #### Warpy
 
 This plugin provides various methods for warping players and ships around.
 
-* **/warp**: Warps you to another player's ship. `Access: Admin`
-* **/move\_ship**: Moves your ship to the location of another player, or
-  coordinates in the form of `alpha 514180 -82519336 -23964461 4` `Access: Admin`
-* **/move\_other\_ship**: Same as above, but another player's ship. `Access: Admin`
-
 #### More plugins
 
 Even more plugins can be found over at
@@ -168,13 +209,12 @@ Even more plugins can be found over at
 There are several built-in plugins that you can derive inspiration from. The
 plugin API is decidedly simple, and simply responds to packet events. There is a
 convenience plugin class called SimpleCommandPlugin which responds to user
-commands in chat. Currently there is no easy way to *modify* packets, however
-they can be dropped or allowed to send by any plugin intercepting that packet
-type.
+commands in chat. Currently there is no easy way to *modify* packets, however they
+can be dropped or allowed to send by any plugin intercepting that packet type.
 
 All plugins must ultimately derive from `BasePlugin`. Do not override the
-`__init__` method unless you absolutely know that you need to. All setup
-functions should be done in `activate()`
+`__init__` method unless you absolutely know that you need to. All setup functions
+should be done in `activate()`
 
 There will be more to come in the near future, for now please examine the base
 plugin classes.
@@ -186,11 +226,29 @@ StarryPy proper must be licensed under an open-source license. We suggest the
 MIT or BSD licenses. If this isn't acceptable to you, we will only be able to
 provide a link.
 
+## Troubleshooting
+
+### None of the commands are working
+
+You are likely in passthrough mode or connecting to the vanilla server. Check
+config.json and ensure that passthrough is false.
+
+If you are running StarryPy on the same computer you're playing it from, it is
+likely it is using the gameport in starbound.config to connect to. To avoid this,
+use localhost:21025 in the hostname field in Starbound. Other computers will be
+able to connect fine.
+
+### Something else?
+
+If you're having another issue, check the Issues tab over on the side. If you find
+that your issue isn't there, please create a new issue with a copy of your
+debug.log (if applicable.)
+
 ## Planned features
 
 We haven't been able to pack in everything we've wanted to in this version. We
-love contributions, so please feel free to write whatever plugins/improve the
-core however you can.
+love contributions, so please feel free to write whatever plugins/improve the core
+however you can.
 
 We have quite a roadmap, here are some of the highlights you can expect in the
 next major version, and in the development branch before that if you're feeling
@@ -203,20 +261,19 @@ brave:
   going to prison on the inevitable murder charge.
 * Lotteries. Because what is life without a little risk?
 * Creature spawning. Want to spawn a couple dozen bone dragons? So do we!
-* Projectile blacklist. This should be coming very soon.
 * Internationalization. Translate plugins and core messages with ease to your
   preferred language.
 * Role based access control Thought the mod/admin/owner distinction is useful,
   having individual roles is our plan for the future.
 * Client filtering based on modded items. Though asset digests aren't supported
-  right now, we want to do some minor filtering to keep out the riff-raff (if
-  you as an admin want to.)
+  right now, we want to do some minor filtering to keep out the riff-raff (if you
+  as an admin want to.)
 * Plugin dependency overhaul. Really only interesting to developers, but it will
   allow for complex dependency resolution.
 
-There are many more planned features, minor and major. If you have a feature
-you'd just love to have that we haven't covered here, put in a feature request
-on the issues page.
+There are many more planned features, minor and major. If you have a feature you'd
+just love to have that we haven't covered here, put in a feature request on the
+issues page.
 
 ## Contributing