Skip to content
This repository was archived by the owner on Apr 27, 2019. It is now read-only.

Commit 3b63b78

Browse files
ddevaultddevault
committed
Fix up readme
This changes markdown style to be more consistent with the usual markdown style. Also, importantly, this changes the plugin license requirements to require an OSI-approved license instead of WTFPL. WTFPL is basically public domain, and doesn't work in a number of countries. You can't really use it for serious projects.
1 parent 4148575 commit 3b63b78

1 file changed

Lines changed: 159 additions & 67 deletions

File tree

‎README.md‎

Lines changed: 159 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
StarryPy
2-
========
1+
# StarryPy
32

43
StarryPy is Twisted-based plugin-driven Starbound server wrapper. It is currently in beta.
54

6-
# Features
5+
## Features
6+
77
With the built-in plugins (which are removable):
88
* User management. Kicking, banning, whois, player listing. Multiple user levels.
99
* Message of the day
@@ -14,123 +14,215 @@ With the built-in plugins (which are removable):
1414
* Join/quit announcements.
1515
* And more.
1616

17-
# Installation
17+
## Installation
18+
19+
StarryPy runs on Python 2.7. It has been tested with Python 2.7.6, 2.7.5, 2.7.2,
20+
and PyPy.
21+
22+
This requires Python and pip to install, and on *nix systems the python
23+
development headers (python-dev in apt, python-devel in yum.) After installing
24+
those, simply run `pip install -r requirements.txt` in the root directory of
25+
StarryPy. This will install all of the components needed for use. I recommend
26+
running it in a virtualenv.
1827

19-
StarryPy runs on Python 2.7. It has been tested with Python 2.7.6, 2.7.5, 2.7.2, and PyPy.
28+
Create a configuration file using the config.json.example. The most important
29+
things to note are owner\_uuid, which should be set to a character's UUID that
30+
you possess and have never shared; server\_address and server\_port, which
31+
should be set to the proxied server. StarryPy will default to port 21025 for
32+
normal clients to connect to. Select a good random port, or set it to 21024 and
33+
firewall it off from the outside.
2034

21-
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.
35+
## Run it
2236

23-
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.
37+
After making sure the Starbound server is running, use your terminal (cmd or
38+
powershell on windows) and `cd` to the directory you installed StarryPy into.
39+
Enter `python server.py` to start the proxy.
2440

25-
# Run it
26-
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.
41+
## Built-in plugins
2742

28-
# Built-in plugins
29-
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 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.
43+
StarryPy is nearly entirely plugin driven (our plugin manager is a plugin!), so
44+
there are quite a few built-in plugins. The truly important plugins are in the
45+
`core\_plugins` folder. If you remove any of those, it's likely that most other
46+
plugins will break. We'll break them down by core plugin and normal plugin
47+
classes. If you are looking for the commands, feel free to skip the core plugins
48+
section.
3049

31-
## Core Plugins
50+
### Core Plugins
3251

33-
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.
52+
Core plugins are plugins that have no dependencies and are intended to be
53+
accessed by other plugins. If your plugin doesn't meet those criteria, it is
54+
recommended to put it in the normal plugins folder.
3455

35-
### Player Manager
56+
#### Player Manager
3657

37-
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.
58+
The player manager is perhaps the most essential plugin of them all. It keeps
59+
track of each player that logs in, tracks their position, and manages
60+
kicks/bans. It is composed of the actual database manager, using SQLAlchemy on
61+
an SQLite3 backend by default.
3862

39-
### Command Plugin
63+
#### Command Plugin
4064

41-
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.
65+
This is a core plugin that works in conjunction with the plugin class
66+
SimpleCommandPlugin. SimpleCommandPlugins automatically register their commands
67+
with the instantiated command plugin and when a chat packet is sent it is
68+
automatically parsed. If it matches one of these commands, it sends it off to
69+
that function for processing. If it doesn't match any of the commands, it sends
70+
it on its merry way to the actual starbound server for processing.
4271

43-
## Plugins
72+
### Plugins
4473

45-
### Admin Commands
46-
The admin commands plugin implements player management from in game. It is a SimpleCommandPlugin that provides the following commands:
74+
#### Admin Commands
75+
76+
The admin commands plugin implements player management from in game. It is a
77+
SimpleCommandPlugin that provides the following commands:
4778

4879
* **/who**: Displays all users currently logged into the server. `Access: Everyone`
4980
* **/planet**: Displays all users on your current planet. `Access: Everyone`
50-
* **/whois**: Displays user information. Includes player UUID, IP address, username, access level, and current planet. `Access: Admin`
51-
* **/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`
52-
* **/kick**: Kicks a user by username. If the name has spaces, enclose it in quotes. `Access: Moderator`
53-
* **/ban**: Bans an IP address. Best fetched with /whois. It does not support usernames. `Access: Admin`
81+
* **/whois**: Displays user information. Includes player UUID, IP address,
82+
username, access level, and current planet. `Access: Admin`
83+
* **/promote**: Promotes/demotes a user to a given access level. You can only
84+
promote if you are a moderator or above, and then only to a user of lesser rank
85+
than yourself. `Access: Moderator`
86+
* **/kick**: Kicks a user by username. If the name has spaces, enclose it in
87+
quotes. `Access: Moderator`
88+
* **/ban**: Bans an IP address. Best fetched with /whois. It does not support
89+
usernames. `Access: Admin`
5490
* **/bans**: Lists all active IP bans. `Access: Admin`
5591
* **/unban**: Unbans an IP address. `Access: Admin`
5692
* **/mute**: Mutes a player. `Access: Moderator`
5793
* **/unmute**: Unmutes a player. `Access: Moderator`
58-
* **/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`
94+
* **/give\_item**: Gives an item to a player. Syntax is /give\_item player
95+
(enclosed in quotes if it has spaces) itemname count. The default limit for
96+
number of items to give to a player is 1000. `Access: Admin`
97+
98+
#### Admin Messenger
5999

60-
### Admin Messenger
61-
This command forwards a message to all active moderators or greater. Any command prefixed with ## will be sent to moderators+ only. `Access: Everyone`
100+
This command forwards a message to all active moderators or greater. Any command
101+
prefixed with ## will be sent to moderators+ only. `Access: Everyone`
102+
103+
#### Announcer
62104

63-
### Announcer
64105
This plugin simply announces whenever a player joins or quits the server.
65106

66-
### Bouncer
67-
This plugin prevents non-registered users from building or destroying anything. It is disabled by default.
107+
#### Bouncer
108+
109+
This plugin prevents non-registered users from building or destroying anything.
110+
It is disabled by default.
111+
112+
#### Colored names
113+
114+
This plugin displays color codes for each username depending on rank. The colors
115+
are set in config.json.
68116

69-
### Colored names
70-
This plugin displays color codes for each username depending on rank. The colors are set in config.json.
117+
#### MOTD
71118

72-
### MOTD
73-
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:
119+
This plugin sends a Message of the Day on login. The MOTD is located in motd.txt
120+
in the plugin folder. It provides the following command:
74121

75122
* **/set\_motd**: Sets the MOTD to the following text. `Access: Moderator`
76123

77-
### New Player Greeter
124+
#### New Player Greeter
78125

79-
Greets first-time players on the server. Gives them a greeting (located in new\_player\_message.txt) and gives them a pack of starter items (located in starter\_items.txt). Default items are 200 `coalore` and 5 `alienburger`s.
126+
Greets first-time players on the server. Gives them a greeting (located in
127+
new\_player\_message.txt) and gives them a pack of starter items (located in
128+
starter\_items.txt). Default items are 200 `coalore` and 5 `alienburger`s.
80129

81-
### Planet Protection
82-
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:
130+
#### Planet Protection
131+
132+
This plugin protects specified planets against modification in any way.
133+
Currently if a planet is protected only Admins may modify it. This plugin
134+
provides the following commands:
83135

84136
* **/protect**: Protects the planet you are currently on. `Access: Admin`
85137
* **/unprotect**: Unprotects the planet you are currently on. `Access: Admin`
86138

87-
### Plugin Manager
88-
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:
139+
#### Plugin Manager
140+
141+
This plugin provides a method of enabling/disabling plugins. I know it's silly
142+
that it's a plugin, you don't have to tell me. It provides the following
143+
commands:
89144

90145
* **/list\_plugins**: Sends you a list of all loaded plugins. `Access: Admin`
91146
* **/disable\_plugin**: Disables a plugin by name. `Access: Admin`
92147
* **/enable\_plugin**: Enables a plugin by name. `Access: Admin`
93-
* **/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`
148+
* **/help**: This command provides a list of commands if called by itself, and
149+
the help string for a command if given a name. Example syntax: /help
150+
enable\_plugin. `Access: Everyone`
151+
152+
#### Warpy
94153

95-
### Warpy
96154
This plugin provides various methods for warping players and ships around.
97155

98156
* **/warp**: Warps you to another player's ship. `Access: Admin`
99-
* **/move\_ship**: Moves your ship to the location of another player, or coordinates in the form of `alpha 514180 -82519336 -23964461 4` `Access: Admin`
157+
* **/move\_ship**: Moves your ship to the location of another player, or
158+
coordinates in the form of `alpha 514180 -82519336 -23964461 4` `Access: Admin`
100159
* **/move\_other\_ship**: Same as above, but another player's ship. `Access: Admin`
101160

102-
### More plugins
103-
Even more plugins can be found over at [our plugin list](https://github.com/MrMarvin/StarryPy_plugins).
161+
#### More plugins
162+
163+
Even more plugins can be found over at
164+
[our plugin list](https://github.com/MrMarvin/StarryPy_plugins).
165+
166+
## Plugin development
104167

105-
# Plugin development
168+
There are several built-in plugins that you can derive inspiration from. The
169+
plugin API is decidedly simple, and simply responds to packet events. There is a
170+
convenience plugin class called SimpleCommandPlugin which responds to user
171+
commands in chat. Currently there is no easy way to *modify* packets, however
172+
they can be dropped or allowed to send by any plugin intercepting that packet
173+
type.
106174

107-
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.
175+
All plugins must ultimately derive from `BasePlugin`. Do not override the
176+
`__init__` method unless you absolutely know that you need to. All setup
177+
functions should be done in `activate()`
108178

109-
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()`
179+
There will be more to come in the near future, for now please examine the base
180+
plugin classes.
110181

111-
There will be more to come in the near future, for now please examine the base plugin classes.
182+
Please consider letting us know of your plugin(s) so it can be listed at
183+
[our plugin list](https://github.com/MrMarvin/StarryPy_plugins). Pull requests
184+
are much appreciated! Please note that any plugins that we integrate into
185+
StarryPy proper must be licensed under an OSI-approved open-source license,
186+
for simplicity's sake. We suggest the MIT or BSD licenses. If this isn't
187+
acceptable to you, we will only be able to provide a link.
112188

113-
Please consider letting us know of your plugin(s) so it can be listed at [our plugin list](https://github.com/MrMarvin/StarryPy_plugins). Pull requests are much appreciated! Please note that any plugins that we integrate into StarryPy proper must be licensed under WTFPL for simplicity's sake. If this isn't acceptable to you, we will only be able to provide a link.
189+
## Planned features
114190

115-
# Planned features
116-
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.
191+
We haven't been able to pack in everything we've wanted to in this version. We
192+
love contributions, so please feel free to write whatever plugins/improve the
193+
core however you can.
117194

118-
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 brave:
195+
We have quite a roadmap, here are some of the highlights you can expect in the
196+
next major version, and in the development branch before that if you're feeling
197+
brave:
119198

120-
* Spawn networks. Free transportation between admin-designated planets, so your new players can get a leg up in the world.
121-
* Loot rolling. So a rare item dropped and you don't think it's fair your friend got it? Soon you'll be able to get good items without ending friendships and going to prison on the inevitable murder charge.
199+
* Spawn networks. Free transportation between admin-designated planets, so your
200+
new players can get a leg up in the world.
201+
* Loot rolling. So a rare item dropped and you don't think it's fair your friend
202+
got it? Soon you'll be able to get good items without ending friendships and
203+
going to prison on the inevitable murder charge.
122204
* Lotteries. Because what is life without a little risk?
123205
* Creature spawning. Want to spawn a couple dozen bone dragons? So do we!
124206
* Projectile blacklist. This should be coming very soon.
125-
* Internationalization. Translate plugins and core messages with ease to your preferred language.
126-
* Role based access control Thought the mod/admin/owner distinction is useful, having individual roles is our plan for the future.
127-
* 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.)
128-
* Plugin dependency overhaul. Really only interesting to developers, but it will allow for complex dependency resolution.
129-
130-
131-
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.
132-
133-
# Contributing
134-
We're absolutely happy to accept pull requests. There is a freenode channel called ##starbound-dev that we discuss our development on primarily.
135-
136-
Other than that, please report any bugs you find with the appropriate section of the debug.log file that is generated.
207+
* Internationalization. Translate plugins and core messages with ease to your
208+
preferred language.
209+
* Role based access control Thought the mod/admin/owner distinction is useful,
210+
having individual roles is our plan for the future.
211+
* Client filtering based on modded items. Though asset digests aren't supported
212+
right now, we want to do some minor filtering to keep out the riff-raff (if
213+
you as an admin want to.)
214+
* Plugin dependency overhaul. Really only interesting to developers, but it will
215+
allow for complex dependency resolution.
216+
217+
There are many more planned features, minor and major. If you have a feature
218+
you'd just love to have that we haven't covered here, put in a feature request
219+
on the issues page.
220+
221+
## Contributing
222+
223+
We're absolutely happy to accept pull requests. There is a freenode channel
224+
called [##starbound-dev](http://webchat.freenode.net/?channels=##starbound-dev)
225+
that we discuss our development on primarily.
226+
227+
Other than that, please report any bugs you find with the appropriate section of
228+
the debug.log file that is generated.

0 commit comments

Comments
 (0)