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

Merge pull request #234 from carlrobert/patch-14

Browse source 
Linked to homes and added chat_color intro
This commit is contained in:
Walter Higgins 2015-04-16 21:26:14 +01:00
commit e1e78587f4
1 changed files with 33 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -1,20 +1,24 @@
# Anatomy of a ScriptCraft Plugin # Anatomy of a ScriptCraft Plugin
Anything you can do using a java-based plugin, you can do it Anything you can do using a Java-based plugin, you can do it
faster and easier in Javascript with the ScriptCraft plugin. To faster and easier in JavaScript with the ScriptCraft plugin. To
demonstrate this, I've recreated a commonly-used mod (homes) in demonstrate this, I've recreated a commonly-used mod (homes) in
javascript. The `homes` javascript plugin lets players set their current javascript. The [homes][homes] JavaScript plugin lets players set their current
location as home and return to that location using in-game commands. location as home and return to that location using in-game commands.
They can also visit other players' homes. It's a simple plugin that They can also visit other players' homes. It's a simple plugin that
demonstrates a couple of new features in ScriptCraft ... demonstrates a couple of new features in ScriptCraft …
* Persistence * Persistence
* Adding Player (non-operator) commands * Adding Player (non-operator) commands
[homes]: src/main/js/plugins/homes/homes.js
Here, I walk you through another useful plugin which lets players modify the color of the in-game chat.
## Persistence ## Persistence
... First persistence. Persistence is the ability to retain state … First persistence. Persistence is the ability to retain state
after the server has shutdown and started up again. You can create a after the server has shutdown and started up again. You can create a
Javascript object which will be saved at shutdown and reloaded at JavaScript object which will be saved at shutdown and reloaded at
startup by using the built-in `persist()` function. startup by using the built-in `persist()` function.
```javascript ```javascript
@ -28,7 +32,7 @@ In the example above, a new empty object is created and stored in a file called
The data is persisted in JSON form so it's even somewhat 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 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 new plugin called "chat" that will let players change the default
color of their messages in the in-game chat window... color of their messages in the in-game chat window …
```javascript ```javascript
var store = persist('chat-colors', {players: {}}); var store = persist('chat-colors', {players: {}});
@ -43,8 +47,8 @@ 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
change when chatting with other players, but the above code will ensure change when chatting with other players, but the above code will ensure
the player's color setting is at least saved. The following code just 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 …
```javascript ```javascript
var colors = ['black', 'blue', 'darkgreen', 'darkaqua', 'darkred', var colors = ['black', 'blue', 'darkgreen', 'darkaqua', 'darkred',
@ -69,18 +73,18 @@ handler which intercepts and inserts color codes into player's text
messages. messages.
## Adding new Player Commands ## 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
are then passed on to the appropriate javascript plugin. So far in this are then passed on to the appropriate JavaScript plugin. So far in this
example plugin we haven't provided any way for regular players to - you example plugin we haven't provided any way for regular players to – you
know - actually set their text color of choice - only operators can do know – actually set their text color of choice – only operators can do
this for a player using the `js chat.setColor(...)` javascript this for a player using the `js chat.setColor(...)` JavaScript
expression. Let's be clear - giving your players access to the whole API expression. Let's be clear – giving your players access to the whole API
via javascript isn't a good idea. So how do you safely let players via JavaScript isn't a good idea. So how do you safely let players
choose their text color? If you've written a javascript function and 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 …
```javascript ```javascript
function chat_color( params, sender ){ function chat_color( params, sender ){
@ -95,18 +99,18 @@ function chat_color( params, sender ){
command(chat_color, 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
that command when the player presses the `TAB` key. Now the player that command when the player presses the `TAB` key. Now the player
themselves can change their chosen chat color like so... themselves can change their chosen chat color like so …
/jsp chat_color yellow /jsp chat_color yellow
... What I've done here is create a new plugin which lets players choose … What I've done here is create a new plugin which lets players choose
a chat color and saves that preference when the server shuts down and a chat color and saves that preference when the server shuts down and
starts up. I've also added a new `jsp` sub-command - `chat_color` that 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 …
```javascript ```javascript
var store = persist('chat-colors', {players: {}}); var store = persist('chat-colors', {players: {}});
@ -144,10 +148,10 @@ command(chat_color, colors);
![Chat Color plugin][1] ![Chat Color plugin][1]
... this is what I would call a minimum viable plugin and it … this is what I would call a minimum viable plugin and it
demonstrates some of the new features of ScriptCraft - persistence demonstrates some of the new features of ScriptCraft – persistence
(automatic) , event handling, and exposing new functionality to players (automatic), event handling, and exposing new functionality to players
using the `/jsp` command. I hope this will give potential MineCraft using the `/jsp` command. I hope this will give potential Minecraft
modders a feel for just how easy it can be to change the game to suit modders a feel for just how easy it can be to change the game to suit
their needs. their needs.