arg/scriptcraft
Archived
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

documentation updates/fixes.

Browse source
This commit is contained in:
walterhiggins 2014-12-29 12:16:45 +00:00
parent 2ab333e999
commit f40b5ed232
2 changed files with 91 additions and 79 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
README.md
View file

@ -93,9 +93,9 @@ drone can do. If you're interested in customizing minecraft beyond
just creating new buildings, take a look at [./homes/homes.js][homes] for examples of how to create a just creating new buildings, take a look at [./homes/homes.js][homes] for examples of how to create a
javascript plugin for Minecraft. javascript plugin for Minecraft.
[ho]: blob/master/src/main/javascript/plugins/homes/homes.js [ho]: blob/master/src/main/js/plugins/homes/homes.js
[ar]: blob/master/src/main/javascript/plugins/arrows/arrows.js [ar]: blob/master/src/main/js/plugins/arrows.js
[si]: blob/master/src/main/javascript/modules/signs/menu.js [si]: blob/master/src/main/js/modules/signs/menu.js
A Javascript mod for minecraft is just a javascript source file (.js) A Javascript mod for minecraft is just a javascript source file (.js)
located in the craftbukkit/plugins/scriptcraft/plugins directory. All .js files in this located in the craftbukkit/plugins/scriptcraft/plugins directory. All .js files in this
@ -180,5 +180,5 @@ You can find more information about [ScriptCraft on my blog][blog].
[scr]: http://scratch.mit.edu/ [scr]: http://scratch.mit.edu/
[cda]: http://cdathenry.wordpress.com/category/modderdojo/ [cda]: http://cdathenry.wordpress.com/category/modderdojo/
[ytpl]: http://www.youtube.com/watch?v=DDp20SKm43Y&list=PL4Tw0AgXQZH5BiFHqD2hXyXQi0-qFbGp_ [ytpl]: http://www.youtube.com/watch?v=DDp20SKm43Y&list=PL4Tw0AgXQZH5BiFHqD2hXyXQi0-qFbGp_
[ex]: ../../tree/master/src/main/javascript/plugins/examples [ex]: ../../tree/master/src/main/js/plugins/examples
[contrib]: contributing.md [contrib]: contributing.md

162
docs/Anatomy-of-a-Plugin.md
View file

@ -11,26 +11,33 @@ demonstrates a couple of new features in ScriptCraft ...
* Persistence * Persistence
* Adding Player (non-operator) commands * Adding Player (non-operator) commands
... First persistence. Persistence is the ability to retain state after ## Persistence
the server has shutdown and started up again. Persistence is something ... First persistence. Persistence is the ability to retain state
you get for free if you create your javsacript plugin using the new after the server has shutdown and started up again. You can create a
`plugin()` function provided with ScriptCraft - just keep any data you Javascript object which will be saved at shutdown and reloaded at
want to save in a property called `store` and that data will be written startup by using the built-in `persist()` function.
and read at shutdown and startup. The data is persisted in JSON form so
it's even somewhat human-readable. Declaring a new plugin is easy, you
give your plugin a name, specify an interface/object and whether the
plugin should be persistent. For this I'm going to create a new plugin
called "chat" that will let players change the default color of their messages
in the in-game chat window...
var _store = {players: {}}; ```javascript
exports.chat = plugin('chat', { // file: scriptcraft/plugins/my-first-plugin.js
setColor: function(player,chatColor) { var prefs = persist('myprefs', {});
_store.players[player.name] = chatColor; ...
}, prefs.color = 'black';
store: _store ```
}, true); In the example above, a new empty object is created and stored in a file called `myprefs-store.json`. The empty object is returned (if data is not already present in that file or the file does not exist) and any changes to the object's contents are written to the file when the server is shutdown.
The data is persisted in JSON form so it's even somewhat
human-readable. Declaring a new plugin is easy. I'm going to create a
new plugin called "chat" that will let players change the default
color of their messages in the in-game chat window...
```javascript
var store = persist('chat-colors', {players: {}});
exports.chat = {
setColor: function(player,chatColor) {
store.players[player.name] = chatColor;
}
}
```
The above code doesn't do a whole lot other than let operators set a The above code doesn't do a whole lot other than let operators set a
player's color choice ( `/js chat.setColor(self, 'green')` ). A little player's color choice ( `/js chat.setColor(self, 'green')` ). A little
bit more code has to be added so that the player's text color will bit more code has to be added so that the player's text color will
@ -39,25 +46,29 @@ the player's color setting is at least saved. The following code just
ensures that when a player chats , the text will be displayed in their ensures that when a player chats , the text will be displayed in their
chosen color... chosen color...
var colors = ['black', 'blue', 'darkgreen', 'darkaqua', 'darkred', ```javascript
'purple', 'gold', 'gray', 'darkgray', 'indigo', var colors = ['black', 'blue', 'darkgreen', 'darkaqua', 'darkred',
'brightgreen', 'aqua', 'red', 'pink', 'purple', 'gold', 'gray', 'darkgray', 'indigo',
'yellow', 'white']; 'brightgreen', 'aqua', 'red', 'pink',
var colorCodes = {}; 'yellow', 'white'];
for (var i =0;i < colors.length;i++) colorCodes[colors[i]] = i.toString(16); var colorCodes = {};
for (var i =0;i < colors.length;i++)
events.asyncPlayerChat( function( evt ) { colorCodes[colors[i]] = i.toString(16);
var player = evt.player;
var playerChatColor = _store.players[ player.name ]; events.asyncPlayerChat( function( evt ) {
if ( playerChatColor ) { var player = evt.player;
evt.message = '&sect;' + colorCodes[ playerChatColor ] + evt.message; var playerChatColor = _store.players[ player.name ];
} if ( playerChatColor ) {
}); evt.message = '&sect;' + colorCodes[ playerChatColor ] + evt.message;
}
});
```
The next step is to declare a lookup table of colors / names and add an event The next step is to declare a lookup table of colors / names and add an event
handler which intercepts and inserts color codes into player's text handler which intercepts and inserts color codes into player's text
messages. messages.
## Adding new Player Commands
The other command in ScriptCraft is the `/jsp` command - this lets The other command in ScriptCraft is the `/jsp` command - this lets
operators expose plugins for use by regular players. To be clear, `/jsp` operators expose plugins for use by regular players. To be clear, `/jsp`
does not do any javascript evaluation, it just accepts parameters which does not do any javascript evaluation, it just accepts parameters which
@ -71,15 +82,18 @@ choose their text color? If you've written a javascript function and
want players to be able to use that function, you expose it using the want players to be able to use that function, you expose it using the
new `command()` function like so... new `command()` function like so...
command( 'chat_color', function( params, sender ) { ```javascript
var color = params[0]; function chat_color( params, sender ){
if (colorCodes[color]){ var color = params[0];
chat.setColor(sender,color); if (colorCodes[color]){
}else{ chat.setColor(sender,color);
sender.sendMessage(color + ' is not a valid color'); }else{
sender.sendMessage('valid colors: ' + colors.join(', ')); echo(sender, color + ' is not a valid color');
} echo(sender, 'valid colors: ' + colors.join(', '));
},colors); }
}
command(chat_color, colors);
```
... The above code adds a new *subcommand* to the `/jsp` command and ... The above code adds a new *subcommand* to the `/jsp` command and
also specifies autocomplete options (the last parameter - `colors`) for also specifies autocomplete options (the last parameter - `colors`) for
@ -94,41 +108,39 @@ starts up. I've also added a new `jsp` sub-command - `chat_color` that
players use to change their chat color setting. The full plugin source players use to change their chat color setting. The full plugin source
code is just a couple of lines of code but is a fully working plugin... code is just a couple of lines of code but is a fully working plugin...
// declare a new javascript plugin ```javascript
var _store = { players: {} } ; // private variable var store = persist('chat-colors', {players: {}});
exports.chat = plugin('chat', { exports.chat = {
setColor: function(player, color){ setColor: function(player,chatColor) {
_store.players[player.name] = color; store.players[player.name] = chatColor;
}, }
store: _store }
},true); var colors = ['black', 'blue', 'darkgreen', 'darkaqua', 'darkred',
'purple', 'gold', 'gray', 'darkgray', 'indigo',
var colors = ['black', 'blue', 'darkgreen', 'darkaqua', 'darkred', 'brightgreen', 'aqua', 'red', 'pink',
'purple', 'gold', 'gray', 'darkgray', 'indigo', 'yellow', 'white'];
'brightgreen', 'aqua', 'red', 'pink', var colorCodes = {};
'yellow', 'white']; for (var i =0;i < colors.length;i++)
var colorCodes = {}; colorCodes[colors[i]] = i.toString(16);
for ( var i =0; i < colors.length; i++ ) {
colorCodes[ colors[i] ] = i.toString(16);
}
events.asyncPlayerChat( function( evt ) {
var player = evt.player;
var playerChatColor = _store.players[player.name];
if ( playerChatColor ) {
evt.message = '&sect;' + colorCodes[playerChatColor] + evt.message;
}
});
command( 'chat_color', function( params, sender ) {
var color = params[0];
if ( colorCodes[ color ] ) {
chat.setColor( sender, color );
}else{
sender.sendMessage( color + ' is not a valid color' );
sender.sendMessage( colors.join(',') );
}
}, colors );
events.asyncPlayerChat( function( evt ) {
var player = evt.player;
var playerChatColor = _store.players[ player.name ];
if ( playerChatColor ) {
evt.message = '&sect;' + colorCodes[ playerChatColor ] + evt.message;
}
});
function chat_color( params, sender ){
var color = params[0];
if (colorCodes[color]){
chat.setColor(sender,color);
}else{
echo(sender, color + ' is not a valid color');
echo(sender, 'valid colors: ' + colors.join(', '));
}
}
command(chat_color, colors);
```
![Chat Color plugin][1] ![Chat Color plugin][1]