Merge branch 'walterhiggins:master' into master
11
.classpath
Normal file
|
@ -0,0 +1,11 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<classpath>
|
||||
<classpathentry kind="src" path="src/docs/java"/>
|
||||
<classpathentry kind="src" path="src/main/java/bukkit"/>
|
||||
<classpathentry kind="src" path="src/main/java/canary"/>
|
||||
<classpathentry kind="src" path="src/main/java/webserver"/>
|
||||
<classpathentry kind="lib" path="lib/bukkit-1.7.10-R0.1-SNAPSHOT.jar"/>
|
||||
<classpathentry kind="lib" path="lib/canarymod.jar"/>
|
||||
<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
|
||||
<classpathentry kind="output" path="target"/>
|
||||
</classpath>
|
22
.gitignore
vendored
|
@ -2,7 +2,29 @@ target
|
|||
*.class
|
||||
*.js~
|
||||
*.js#
|
||||
*.md#
|
||||
*.md~
|
||||
*.mdt~
|
||||
*.mdt#
|
||||
*.iml
|
||||
*.#*
|
||||
*.idea
|
||||
.DS_Store
|
||||
build.local.properties
|
||||
/src/main/javascript/lib/.#tabcomplete.js
|
||||
/src/main/javascript/plugins/.#example-1.js
|
||||
/nbproject/private/private.xml
|
||||
/nbproject/project.xml
|
||||
/src/docs/nbproject/private/
|
||||
/src/docs/build//#build.xml#
|
||||
/#build.xml#
|
||||
/src/docs/build/classes/generateApiDocs.js
|
||||
/src/docs/build/classes/generateTOC.js
|
||||
/src/docs/build/classes/hello.js
|
||||
/src/docs/build/classes/.netbeans_automatic_build
|
||||
/src/docs/build/classes/.netbeans_update_resources
|
||||
build
|
||||
nbproject
|
||||
/manifest.mf
|
||||
/platform.properties
|
||||
CopyLibs
|
17
.project
Normal file
|
@ -0,0 +1,17 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<projectDescription>
|
||||
<name>ScriptCraft</name>
|
||||
<comment></comment>
|
||||
<projects>
|
||||
</projects>
|
||||
<buildSpec>
|
||||
<buildCommand>
|
||||
<name>org.eclipse.jdt.core.javabuilder</name>
|
||||
<arguments>
|
||||
</arguments>
|
||||
</buildCommand>
|
||||
</buildSpec>
|
||||
<natures>
|
||||
<nature>org.eclipse.jdt.core.javanature</nature>
|
||||
</natures>
|
||||
</projectDescription>
|
5
.travis.yml
Normal file
|
@ -0,0 +1,5 @@
|
|||
language: java
|
||||
jdk:
|
||||
- oraclejdk8
|
||||
- oraclejdk7
|
||||
- openjdk7
|
331
README.md
|
@ -1,125 +1,266 @@
|
|||
ScriptCraft
|
||||
===========
|
||||
A Minecraft mod that lets you create mods using Javascript.
|
||||
# ScriptCraft - Modding Minecraft with Javascript
|
||||
|
||||
Description
|
||||
===========
|
||||
ScriptCraft is a plugin for Minecraft Servers which lets
|
||||
operators, administrators and plug-in authors customize the game using
|
||||
Javascript. ScriptCraft makes it easier to create your own mods. Mods
|
||||
can be written in Javscript and can use the full Bukkit API. The
|
||||
ScriptCraft mod also lets you enter javascript commands at the in-game
|
||||
prompt. To bring up the in-game prompt press the `/` key then type
|
||||
`js ` followed by any javascript statement. E.g. `/js 1+1` will print
|
||||
2.
|
||||
[![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/walterhiggins/ScriptCraft?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
||||
|
||||
ScriptCraft also includes many objects and functions to make building and modding easier using Javascript.
|
||||
ScriptCraft lets you write Minecraft Mods using Javascript - a
|
||||
programming language that's relatively easy to learn and use.
|
||||
ScriptCraft is a Minecraft Server plugin which means it must be used
|
||||
with a Minecraft server. Once you've downloaded and installed the
|
||||
Minecraft Server, then installed the ScriptCraft Plugin you can write
|
||||
your own Minecraft mods using Javascript.
|
||||
|
||||
* echo( message ) - displays a message on the player's screen. e.g. `/js echo( 1 + 3 )` or `/js echo ("Hello World")`
|
||||
* getMousePos() - A function which returns the current position of the cross-hairs (if a block is targeted)
|
||||
* getPlayerPos() - A function which returns the current position of the player.
|
||||
* putBlock( x, y, z, blockId, metaData ) - A function which lets you place a block anywhere (if no coordinates are given the block the player is currently looking at is replaced).
|
||||
* getBlock( x, y, z ) - returns the blockId and metadata at the given location (if no coordinates are given the cross-hair location is used)
|
||||
* putSign( String[] texts, x, y, z, blockId, metaData ) - A function which lets you place a sign.
|
||||
I created ScriptCraft to make it easier for younger programmers to
|
||||
create their own Minecraft Mods. Mods are written using the
|
||||
JavaScript programming language. Once the ScriptCraft mod is
|
||||
installed, you can add your own new Mods by adding JavaScript (.js)
|
||||
files in a directory.
|
||||
|
||||
The above primitives can be used to create buildings which would
|
||||
otherwise be time-consuming to create manually. It is highly
|
||||
recommended using the attached [drone][drone] javascript plugin which
|
||||
provides a fluent API for building. The Javascript `Drone` class
|
||||
provides a much richer API which can be used to construct
|
||||
buildings. See the attached [cottage.js][cottage] file for an example
|
||||
of you can use the sample Drone plugin to create new buildings in
|
||||
* If you're new to programming and want to start modding Minecraft, then [Start Here][yp].
|
||||
* If you've already used [Scratch][scr], have attended a few
|
||||
[CoderDojo][cd] sessions, or have already dabbled with JavaScript,
|
||||
then [Start Here][cda].
|
||||
* Watch some [demos][ytpl] of what you can do with ScriptCraft.
|
||||
|
||||
This is a simple mod in a file called greet.js in the scriptcraft/plugins directory:
|
||||
|
||||
```javascript
|
||||
function greet( player ) {
|
||||
echo( player, 'Hello ' + player.name );
|
||||
}
|
||||
exports.greet = greet;
|
||||
```
|
||||
|
||||
At the in-game prompt, type:
|
||||
|
||||
```javascript
|
||||
/js greet(self)
|
||||
```
|
||||
|
||||
Anything you can do using the Spigot or CanaryMod APIs in Java,
|
||||
you can do using ScriptCraft in JavaScript.
|
||||
|
||||
# Description
|
||||
|
||||
ScriptCraft is a plugin for Minecraft Servers which lets operators,
|
||||
administrators and plug-in authors customize the game using
|
||||
JavaScript. ScriptCraft makes it easier to create your own mods. Mods
|
||||
can be written in Javscript and can use the full [SpigotMC
|
||||
API][spigot] or [CanaryMod API][cm]. ScriptCraft works with all of the
|
||||
following Minecraft Server software:
|
||||
|
||||
* [SpigotMC][spigot] (Recommended)
|
||||
* [GlowStone][gs]
|
||||
* [CanaryMod][cm]
|
||||
|
||||
[spigot]: http://www.spigotmc.org/
|
||||
[gs]: http://www.glowstone.net/
|
||||
[cm]: http://canarymod.net/
|
||||
|
||||
I recommend using SpigotMC because both CanaryMod and CraftBukkit are
|
||||
no longer being actively developed. The ScriptCraft mod also lets you
|
||||
enter javascript commands at the in-game prompt. To bring up the
|
||||
in-game prompt press the `/` key then type `js ` followed by any
|
||||
javascript statement. For example: `/js 1 + 1` will print 2.
|
||||
|
||||
ScriptCraft also includes many objects and functions to make building
|
||||
and modding easier using JavaScript. The JavaScript `Drone` object
|
||||
bundled with ScriptCraft provides an easy way to build at-scale in
|
||||
Minecraft. See the attached [temple.js][temple] file for an example
|
||||
of how you can use the sample Drone plugin to create new buildings in
|
||||
Minecraft.
|
||||
|
||||
[drone]: https://github.com/walterhiggins/ScriptCraft/tree/master/src/main/javascript/drone/drone.js
|
||||
[cottage]: https://github.com/walterhiggins/ScriptCraft/tree/master/src/main/javascript//drone/cottage.js
|
||||
[cottage]: https://github.com/walterhiggins/ScriptCraft/tree/master/src/main/js/plugins/drone/contrib/cottage.js
|
||||
[temple]: https://github.com/walterhiggins/ScriptCraft/blob/master/src/main/js/plugins/drone/contrib/temple.js
|
||||
[bukkit]: http://dl.bukkit.org/
|
||||
|
||||
Prerequisites
|
||||
=============
|
||||
You will need to have Java version 6 or 7 installed on your
|
||||
machine. Check the version by typing `java -version` at a command
|
||||
prompt. You will need to [install Bukkit][ib] on your machine. Bukkit
|
||||
is a version of Minecraft (server) that makes it easy to install
|
||||
plugins and customize Minecraft. You can [download the CraftBukkit
|
||||
server here.][cbdl]
|
||||
# Prerequisites
|
||||
|
||||
Installation
|
||||
============
|
||||
If you don't want to compile from source, you can [download the
|
||||
compiled plugin here][dl] and copy it the craftbukkit's plugins
|
||||
directory.
|
||||
ScriptCraft is a Minecraft Server Mod which only works with Minecraft
|
||||
for Personal computers (Windows, Mac and Linux). It does not work with
|
||||
X-BOX, Playstation or WiiU versions of the game. You will need to have
|
||||
Java version 7 or later installed. Check the version by typing `java
|
||||
-version` at a command prompt.
|
||||
|
||||
Post Install
|
||||
============
|
||||
Once installed, a new js-plugins directory is automatically created in
|
||||
the same directory as the plugins folder. All files in the js-plugins
|
||||
directory will be automatically loaded when CraftBukkit starts. *Only
|
||||
players who are ops can use this plugin.* You can grant a player `op`
|
||||
privileges by typing 'op <username>' at the server console prompt or
|
||||
by adding the player's username to the ops.txt file in your
|
||||
craftbukkit directory.
|
||||
# Installation
|
||||
|
||||
Launch CraftBukkit, then launch the Minecraft client and create a new
|
||||
Before installing ScriptCraft you must first install SpigotMC which is
|
||||
a special version of Minecraft Server that makes it easy to customize
|
||||
the game.
|
||||
|
||||
## Installing and Running SpigotMC
|
||||
|
||||
Follow these steps to download and install SpigotMC.
|
||||
|
||||
1. Download Spigot's [BuildTools.jar][spigotdl]
|
||||
2. Save the BuildTools.jar file to a new directory called spigotmc.
|
||||
3. Open a terminal (Mac and Linux) or command prompt (windows) window and type `java -jar BuildTools.jar`. This will kick off a long series of commands to "build" SpigotMC.
|
||||
4. When the build is done, there will be a new file beginning with `spigot` and ending in `.jar` in the spigotmc directory. Run this file by typing `java -jar spigot-1.10.2.jar` (it might not be that exact name - you can list files in the directory by typing `dir` (Windows) or `ls` (Mac and Linux).
|
||||
5. The server will start up then shut down very shortly afterwards. You'll need to edit a file called `eula.txt` - change `eula=false` to `eula=true` and save the file.
|
||||
6. Run the `java -jar spigot-1.10.2.jar` command again - this time the server will start up. Shut it down by typing `stop` at the server prompt.
|
||||
|
||||
## Installing ScriptCraft
|
||||
|
||||
Follow these steps to download and install ScriptCraft.
|
||||
|
||||
1. Download the [scriptcraft.jar][dl] plugin and save it to the `plugins` directory and restart the server by typing `java -jar spigot-1.10.2.jar`.
|
||||
2. At the server prompt type `js 1 + 1` and hit enter. The result `2` should be displayed.
|
||||
|
||||
Congratulations - you've just installed your Custom Minecraft Server and are ready to begin writing your first mod!
|
||||
|
||||
# Post Install
|
||||
|
||||
Once installed, a new scriptcraft/plugins directory is automatically
|
||||
created. All files in the scriptcraft/plugins directory will be
|
||||
automatically loaded when the server starts. *Only players who are
|
||||
ops can use this plugin.* You can grant a player `op` privileges by
|
||||
typing 'op <username>' (replacing <username> with your own Minecraft
|
||||
user name) at the server console prompt or by adding the player's
|
||||
username to the ops.txt file in your server directory.
|
||||
|
||||
Launch the server, then launch the Minecraft client and create a new
|
||||
server connection. The IP address will be `localhost` . Once you've
|
||||
connected to your bukkit server and have entered the game, look at a
|
||||
ground-level block and type ...
|
||||
connected to your server and have entered the game, look at a
|
||||
ground-level block and type:
|
||||
|
||||
/js up().box('35:15', 4, 9, 1)
|
||||
/js up().box( blocks.wool.black, 4, 9, 1 )
|
||||
|
||||
... This will create a black monolith structure 4 blocks wide by 9
|
||||
… This will create a black monolith structure 4 blocks wide by 9
|
||||
blocks high by 1 block long. Take a look at the
|
||||
src/main/javascript/drone/drone.js file to see what ScriptCraft's
|
||||
drone can do. If you're interested in customizing minecraft beyond
|
||||
just creating new buildings, take a look at [./homes/homes.js][homes]
|
||||
and [./chat/color.js][chatcolor] for examples of how to create a
|
||||
javascript plugin for Minecraft.
|
||||
drone can do.
|
||||
|
||||
[ho]: blob/master/src/main/javascript/homes/homes.js
|
||||
[ch]: blob/master/src/main/javascript/chat/color.js
|
||||
[ar]: blob/master/src/main/javascript/arrows/arrows.js
|
||||
[si]: blob/master/src/main/javascript/signs/menu.js
|
||||
If you're interested in customizing minecraft beyond just creating new buildings, take a look at [the homes mod][homes] for an example of how to create a more fully-featured JavaScript plugin for Minecraft.
|
||||
|
||||
A Javascript mod for minecraft is just a javascript source file (.js)
|
||||
located in the craftbukkit/js-plugins directory. All .js files in this
|
||||
directory will be automatically loaded when the craftbukkit server
|
||||
starts. To get started writing your own mod, first take a look at some
|
||||
of the existing mods in the [homes][ho], [chat][ch], [arrows][ar] and
|
||||
[signs][si] directories. The chat/color.js mod is probably the
|
||||
simplest mod to get started with.
|
||||
## Your first mod - Howling blocks
|
||||
Listed below is a simple mod that will make blocks 'Howl' when they're broken.
|
||||
|
||||
Additional information
|
||||
======================
|
||||
Because the Bukkit API is open, all of the Bukkit API is accessible
|
||||
via javascript once the ScriptCraft plugin is loaded. For example, in
|
||||
addition to the functions provided in the MCP version of ScriptCraft,
|
||||
there are a couple of useful Java objects exposed via javascript in
|
||||
the Bukkit ScriptCraft plugin...
|
||||
``` javascript
|
||||
// copy and paste this code to a new file named 'scriptcraft/plugins/howling-blocks.js'
|
||||
var sounds = require('sounds');
|
||||
function howl(event){
|
||||
sounds.entityWolfHowl( event.block );
|
||||
}
|
||||
events.blockBreak( howl );
|
||||
```
|
||||
|
||||
* `__plugin` - the ScriptCraft Plugin itself. This is a useful starting point for accessing other Bukkit objects. The `__plugin` object is of type [org.bukkit.plugin.java.JavaPlugin][api] and all of its properties and methods are accessible. For example... `js __plugin.server.motd` returns the server's message of the day (javascript is more concise than the equivalent java code: __plugin.getServer().getMotd() ).
|
||||
* `self` - The player/command-block or server console operator who invoked the js command. Again, this is a good jumping off point for diving into the Bukkit API.
|
||||
* `server` - The top-level org.bukkit.Server object. See the [Bukkit API docs][bukapi] for reference.
|
||||
If you're using CanaryMod instead of SpigotMC you can [download the equivalent code](https://gist.github.com/walterhiggins/69cddd15160d803fb096).
|
||||
|
||||
[dl]: http://scriptcraftjs.org/download
|
||||
[api]: http://jd.bukkit.org/apidocs/org/bukkit/plugin/java/JavaPlugin.html
|
||||
[ib]: http://wiki.bukkit.org/Setting_up_a_server
|
||||
[cbdl]: http://dl.bukkit.org/downloads/craftbukkit/
|
||||
[bukapi]: http://jd.bukkit.org/apidocs/
|
||||
A JavaScript mod for minecraft is just a JavaScript source file (.js)
|
||||
located in the scriptcraft/plugins directory. All .js files in this
|
||||
directory will be automatically loaded when the server starts.
|
||||
|
||||
Further Reading
|
||||
===============
|
||||
To get started writing your own mod, take a look at some of the
|
||||
[examples][examples].
|
||||
|
||||
[homes]: src/main/js/plugins/homes/homes.js
|
||||
[examples]: src/main/js/plugins/examples/
|
||||
|
||||
# Additional information
|
||||
|
||||
Because the SpigotMC API is open, all of the SpigotMC API is accessible
|
||||
via javascript once the ScriptCraft plugin is loaded. There are a
|
||||
couple of useful Java objects exposed via javascript in the
|
||||
ScriptCraft plugin:
|
||||
|
||||
* `__plugin` – the ScriptCraft Plugin itself. This is a useful
|
||||
starting point for accessing other SpigotMC objects. The `__plugin`
|
||||
object is of type [org.bukkit.plugin.Plugin][api] and all
|
||||
of its properties and methods are accessible. For example: `js
|
||||
__plugin.name` returns the plugin's name
|
||||
(JavaScript is more concise than the equivalent Java code:
|
||||
`__plugin.getName()` ).
|
||||
|
||||
* `server` – The top-level org.bukkit.Server object. See the [SpigotMC API docs][spigotapi] for reference.
|
||||
|
||||
* `self` – The player/command-block or server console operator who
|
||||
invoked the `/js` command. Again, this is a good jumping off point for
|
||||
diving into the SpigotMC API.
|
||||
|
||||
[dl]: http://scriptcraftjs.org/download/latest
|
||||
[api]: https://hub.spigotmc.org/javadocs/spigot/
|
||||
[ic]: http://canarymod.net/releases
|
||||
[spigotdl]: https://hub.spigotmc.org/jenkins/job/BuildTools/lastSuccessfulBuild/artifact/target/BuildTools.jar
|
||||
[cmapi]: https://ci.visualillusionsent.net/job/CanaryLib/javadoc/
|
||||
[spigotapi]: https://hub.spigotmc.org/javadocs/spigot/
|
||||
|
||||
# Contributing
|
||||
|
||||
If you would like to contribute source code and/or documentation changes please [read contributing.md][contrib]
|
||||
|
||||
## Status
|
||||
|
||||
[![Travis Build Status](https://api.travis-ci.org/walterhiggins/ScriptCraft.png)](http://travis-ci.org/walterhiggins/ScriptCraft)
|
||||
|
||||
# Bukkit Configuration
|
||||
## (You can ignore this if using CanaryMod)
|
||||
|
||||
ScriptCraft works with Bukkit Plugin and uses the Bukkit Configuration
|
||||
API. On first loading, ScriptCraft will create a config.yml file in
|
||||
the plugins/scriptcraft/ directory. This file looks like this:
|
||||
|
||||
extract-js:
|
||||
plugins: true
|
||||
modules: true
|
||||
lib: true
|
||||
|
||||
This file allows scriptcraft admins to turn on or off re-unzipping of the `modules`,
|
||||
`plugins` and `lib` folders when deploying a new version of
|
||||
ScriptCraft. It's strongly recommended that the `lib` directory always
|
||||
be set to true to get the latest core ScriptCraft code . The modules
|
||||
and plugins directories are optional and not part of ScriptCraft core.
|
||||
|
||||
# Further Reading
|
||||
|
||||
ScriptCraft has [its own website][website] with further information.
|
||||
|
||||
* To get started using ScriptCraft to Learn Javascript I recommend [reading this][yp].
|
||||
* To get started using ScriptCraft to Learn JavaScript, read [The Young Person's Guide to Programming in Minecraft][yp].
|
||||
* The ScriptCraft [API documentation][api].
|
||||
* To delve deeper into creating your own minecraft mod, I recommend [reading this][mm].
|
||||
* To delve deeper into creating your own minecraft mod for use by others, read [Creating a complete Minecraft Mod in JavaScript][mm].
|
||||
* Take a look at some [examples][ex].
|
||||
* Buy the Official ScriptCraft Book [A Beginner's Guide to Writing Minecraft Plugins in Javascript][book].
|
||||
|
||||
<a href="http://www.amazon.co.uk/gp/product/0133930149/ref=as_li_tl?ie=UTF8&camp=1634&creative=6738&creativeASIN=0133930149&linkCode=as2&tag=walthigg-21&linkId=P3LLGB3WTATW57AZ"><img border="0" src="http://ws-eu.amazon-adsystem.com/widgets/q?_encoding=UTF8&ASIN=0133930149&Format=_SL250_&ID=AsinImage&MarketPlace=GB&ServiceVersion=20070822&WS=1&tag=walthigg-21" ></a><img src="http://ir-uk.amazon-adsystem.com/e/ir?t=walthigg-21&l=as2&o=2&a=0133930149" width="1" height="1" border="0" alt="" style="border:none !important; margin:0px !important;" />
|
||||
|
||||
You can find more information about [ScriptCraft on my blog][blog].
|
||||
|
||||
[blog]: http://walterhiggins.net/blog/cat-index-scriptcraft.html
|
||||
[buk]: https://github.com/walterhiggins/ScriptCraft/blob/master/bukkit.md
|
||||
[yp]: http://walterhiggins.net/blog/YoungPersonProgrammingMinecraft
|
||||
[mm]: http://walterhiggins.net/blog/ScriptCraft-1-Month-later
|
||||
[api]: https://github.com/walterhiggins/ScriptCraft/blob/master/docs/api.md
|
||||
[website]: http://scriptcraftjs.org/
|
||||
# Additional Resources
|
||||
|
||||
CoderDojo Athenry have some [excellent tutorials][cda] for younger
|
||||
programmers who have used [Scratch][scr] and are interested in Modding
|
||||
Minecraft using JavaScript. In particular, they have an excellent
|
||||
[Scratch - to - JavaScript][sj] tutorial which explains Scratch
|
||||
programs and how to do the same thing in JavaScript.
|
||||
|
||||
I highly recommend the series of [tutorials provided by CoderDojo Athenry][cda].
|
||||
|
||||
Developer Chris Cacciatore has created some interesting tools using ScriptCraft:
|
||||
|
||||
* [A wolf-bot][wb]
|
||||
* [L-Systems (Large-scale fractal structures in Minecraft)][ls]
|
||||
|
||||
# Docker
|
||||
|
||||
To launch a container with SpigotMC and ScriptCraft you can just do
|
||||
|
||||
docker run -p 25565:25565 -it tclavier/scriptcraft
|
||||
|
||||
You can find all files used to build this container in github project: [docker-scriptcraft](https://github.com/tclavier/docker-scriptcraft)
|
||||
|
||||
|
||||
[wb]: https://github.com/cacciatc/wolfbot
|
||||
[ls]: https://github.com/cacciatc/scriptcraft-lsystems
|
||||
|
||||
[blog]: http://walterhiggins.net/blog/cat-index-scriptcraft.html
|
||||
[yp]: docs/YoungPersonsGuideToProgrammingMinecraft.md
|
||||
[mm]: docs/Anatomy-of-a-Plugin.md
|
||||
[api]: docs/API-Reference.md
|
||||
[website]: http://scriptcraftjs.org/
|
||||
[cd]: http://coderdojo.com/
|
||||
[scr]: http://scratch.mit.edu/
|
||||
[cda]: http://cdathenry.wordpress.com/category/modderdojo/
|
||||
[ytpl]: http://www.youtube.com/watch?v=DDp20SKm43Y&list=PL4Tw0AgXQZH5BiFHqD2hXyXQi0-qFbGp_
|
||||
[ex]: src/main/js/plugins/examples
|
||||
[contrib]: contributing.md
|
||||
[sj]: http://cdathenry.wordpress.com/2013/10/12/modderdojo-week-2-moving-from-scratch-to-javascript/
|
||||
[book]: http://www.peachpit.com/store/beginners-guide-to-writing-minecraft-plugins-in-javascript-9780133930146
|
||||
|
|
|
@ -1 +1 @@
|
|||
bukkit-version=1.4.7
|
||||
scriptcraft-version=3.2.1
|
||||
|
|
280
build.xml
|
@ -1,11 +1,42 @@
|
|||
<project name="scriptcraft" default="package" basedir=".">
|
||||
<property file="build.properties"/>
|
||||
<description>Builds the scriptcraft.jar file - a plugin for bukkit
|
||||
</description>
|
||||
<property name="src" location="src/main/java"/>
|
||||
<description>Builds the scriptcraft.jar file - a plugin for bukkit</description>
|
||||
<!-- ScriptCraft works with:
|
||||
* CanaryMod
|
||||
* Bukkit
|
||||
* Glowstone (which is bukkit-compatible)
|
||||
* Spigot (which is bukkit-compatible)
|
||||
-->
|
||||
<property name="src.canary" location="src/main/java/canary"/>
|
||||
<property name="src.bukkit" location="src/main/java/bukkit"/>
|
||||
|
||||
<!-- compiles against these libraries -->
|
||||
<property name="lib.canary" location="lib/canarymod-1.8.0.jar"/>
|
||||
<property name="lib.bukkit" location="lib/spigot-1.11.2.jar"/>
|
||||
|
||||
<property name="build" location="target/classes"/>
|
||||
<property name="dist" location="target/" />
|
||||
<property name="minecraft.dir" location="${dist}/minecraft" />
|
||||
<property name="js-plugins-dir" value="scriptcraft"/>
|
||||
<property name="http.agent" value="'Walter'" />
|
||||
|
||||
<macrodef name="jscript">
|
||||
<attribute name="src"/>
|
||||
<attribute name="out"/>
|
||||
<attribute name="err"/>
|
||||
<element name="js-args" implicit="yes" optional="true"/>
|
||||
<sequential>
|
||||
<java classname="jscript" failonerror="true" fork="true" output="@{out}" error="@{err}">
|
||||
<classpath>
|
||||
<pathelement path="${build}"/>
|
||||
<pathelement path="${lib.canary}"/>
|
||||
<pathelement path="${lib.bukkit}"/>
|
||||
</classpath>
|
||||
<arg value="@{src}"/>
|
||||
<js-args/>
|
||||
</java>
|
||||
</sequential>
|
||||
</macrodef>
|
||||
|
||||
<target name="init">
|
||||
<property file="build.local.properties"/>
|
||||
|
@ -16,101 +47,216 @@
|
|||
</tstamp>
|
||||
<mkdir dir="${build}"/>
|
||||
|
||||
<available file="${minecraft.dir}" property="minecraft.present"/>
|
||||
<available file="${lib.canary}" property="canary.present"/>
|
||||
<available file="${dist}/js/modules/underscore.js" property="underscore.present"/>
|
||||
</target>
|
||||
|
||||
<target name="server-setup" depends="init" description="Downloads the latest bukkit dev jar"
|
||||
unless="minecraft.present">
|
||||
<mkdir dir="${minecraft.dir}" />
|
||||
<target name="test" depends="package" description="Perform unit tests">
|
||||
|
||||
<echo>Retrieving CraftBukkit artifact info
|
||||
</echo>
|
||||
<get src="http://dl.bukkit.org/api/1.0/downloads/projects/CraftBukkit?_accept=application/xml"
|
||||
dest="${minecraft.dir}/bukkit.xml" />
|
||||
|
||||
<xslt in="${minecraft.dir}/bukkit.xml"
|
||||
out="${minecraft.dir}/ant.properties.xml"
|
||||
style="build/bukkit-to-url.xsl"/>
|
||||
<xmlproperty file="${minecraft.dir}/ant.properties.xml" keeproot="true"/>
|
||||
|
||||
<echo>Retrieving CraftBukkit jar
|
||||
</echo>
|
||||
<get src="${bukkit.url}"
|
||||
dest="${minecraft.dir}/craftbukkit.jar"
|
||||
verbose="true"/>
|
||||
|
||||
<echo>Creating default ops.txt for your user
|
||||
</echo>
|
||||
<echo message="${op.name}" file="${minecraft.dir}/ops.txt" />
|
||||
|
||||
</target>
|
||||
|
||||
|
||||
<target name="run" depends="server-setup, package, update-live-cb" description="Starts Bukkit with ScriptCraft">
|
||||
<echo>Starting Bukkit with ScriptCraft
|
||||
</echo>
|
||||
<java jar="${minecraft.dir}/craftbukkit.jar"
|
||||
maxmemory="1024m"
|
||||
fork="true"
|
||||
dir="${minecraft.dir}"
|
||||
/>
|
||||
<target name="compile-plugins" depends="init" description="compile canary plugin source">
|
||||
<javac includeantruntime="false"
|
||||
source="1.6"
|
||||
target="1.6"
|
||||
destdir="${build}"
|
||||
debug="true">
|
||||
<src path="${src.canary}"/>
|
||||
<src path="${src.bukkit}"/>
|
||||
<classpath>
|
||||
<pathelement path="${lib.canary}" />
|
||||
<pathelement path="${lib.bukkit}" />
|
||||
</classpath>
|
||||
</javac>
|
||||
</target>
|
||||
|
||||
<target name="gendocs" depends="construct-ypgpm, construct-api-ref" description="Generate API documentation">
|
||||
</target>
|
||||
|
||||
<target name="compile-docs" depends="init">
|
||||
<javac includeantruntime="false" srcdir="src/docs/java" destdir="${build}">
|
||||
<classpath>
|
||||
<pathelement path="${lib.canary}"/>
|
||||
</classpath>
|
||||
</javac>
|
||||
</target>
|
||||
|
||||
<target name="generate-api-ref-entries" depends="copy-js,compile-docs,init">
|
||||
|
||||
<jscript src="src/docs/js/generateApiDocs.js"
|
||||
out="${dist}/apiref.md"
|
||||
err="${dist}/gen-api-error.log">
|
||||
<arg value="${dist}/js"/>
|
||||
</jscript>
|
||||
|
||||
<jscript src="src/docs/js/generateItemsDoc.js"
|
||||
out="${dist}/items.md"
|
||||
err="${dist}/gen-items-error.log" />
|
||||
|
||||
<jscript src="src/docs/js/generateEntitiesDoc.js"
|
||||
out="${dist}/entities.md"
|
||||
err="${dist}/gen-entities-error.log" />
|
||||
|
||||
<concat destfile="${dist}/apiref-con.md">
|
||||
<fileset file="${dist}/apiref.md" />
|
||||
<fileset file="${dist}/items.md" />
|
||||
<fileset file="${dist}/entities.md" />
|
||||
</concat>
|
||||
|
||||
</target>
|
||||
|
||||
|
||||
<target name="gen-events-helper-canary" depends="compile-docs,init">
|
||||
<mkdir dir="${dist}/js/lib"/>
|
||||
<jscript src="src/docs/js/generateEventsHelper.js"
|
||||
out="${dist}/js/lib/events-helper-canary.js"
|
||||
err="${dist}/gen-events-canary-error.log">
|
||||
<arg value="CanaryMod"/>
|
||||
<arg value="${lib.canary}"/>
|
||||
<arg value="blockDestroy"/>
|
||||
<arg value="net.canarymod.hook.player.BlockDestroyHook"/>
|
||||
</jscript>
|
||||
</target>
|
||||
|
||||
<target name="gen-events-helper-bukkit" depends="compile-docs,init">
|
||||
<mkdir dir="${dist}/js/lib"/>
|
||||
<jscript src="src/docs/js/generateEventsHelper.js"
|
||||
out="${dist}/js/lib/events-helper-bukkit.js"
|
||||
err="${dist}/gen-events-bukkit-error.log">
|
||||
<arg value="SpigotMC"/>
|
||||
<arg value="${lib.bukkit}"/>
|
||||
<arg value="blockBreak"/>
|
||||
<arg value="org.bukkit.event.block.BlockBreakEvent"/>
|
||||
</jscript>
|
||||
</target>
|
||||
|
||||
<target name="construct-api-ref" depends="gen-toc-apiref,init">
|
||||
|
||||
<concat destfile="docs/API-Reference.md">
|
||||
<header filtering="no" trimleading="yes"><!--
|
||||
IMPORTANT NOTE FOR CONTRIBUTORS
|
||||
-------------------------------
|
||||
Contributors: This file is generated from comments in javascript source files src/main/js/*
|
||||
If you would like to make changes, change the comments in the src/main/js/* files instead.
|
||||
-->
|
||||
# ScriptCraft API Reference
|
||||
|
||||
Walter Higgins
|
||||
|
||||
[walter.higgins@gmail.com][email]
|
||||
|
||||
[email]: mailto:walter.higgins@gmail.com?subject=ScriptCraft_API_Reference
|
||||
|
||||
</header>
|
||||
<fileset file="${dist}/toc-apiref.md" />
|
||||
<fileset file="${dist}/apiref-con.md" />
|
||||
</concat>
|
||||
</target>
|
||||
|
||||
<target name="compile" depends="init, server-setup" description="compile bukkit plugin source">
|
||||
<javac includeantruntime="false" srcdir="${src}" destdir="${build}" classpath="${minecraft.dir}/craftbukkit.jar" />
|
||||
</target>
|
||||
|
||||
<target name="gendocs" depends="init" description="Generate API documentation">
|
||||
<javac includeantruntime="false" srcdir="src/docs/java"/>
|
||||
<java classname="jscript" failonerror="true" fork="true" output="docs/api.md">
|
||||
<classpath>
|
||||
<pathelement path="src/docs/java"/>
|
||||
</classpath>
|
||||
<arg value="src/docs/javascript/generateApiDocs.js"/>
|
||||
<arg value="src/main/javascript"/>
|
||||
</java>
|
||||
<target name="gen-toc-apiref" depends="compile-docs,generate-api-ref-entries, init" description="Generate Table of Contents for API Reference">
|
||||
<jscript src="src/docs/js/generateTOC.js"
|
||||
out="${dist}/toc-apiref.md"
|
||||
err="${dist}/gen-toc-error.log">
|
||||
<arg value="${dist}/apiref-con.md"/>
|
||||
</jscript>
|
||||
</target>
|
||||
|
||||
<target name="coffeescript_setup" depends="init" description="Gets latest coffeescript compiler">
|
||||
<echo>Retrieving Coffeescript compiler
|
||||
</echo>
|
||||
<mkdir dir="${build}/coffeescript/core" />
|
||||
<get src="https://raw.github.com/jashkenas/coffee-script/master/extras/coffee-script.js"
|
||||
dest="${build}/coffeescript/core/_coffeescript.js"/>
|
||||
<target name="gen-toc-ypgpm" depends="compile-docs,init" description="Generate Table of Contents for Young Programmers Guide">
|
||||
<jscript src="src/docs/js/generateTOC.js"
|
||||
out="${dist}/toc-ypgpm.md"
|
||||
err="${dist}/gen-ypgpm-error.log">
|
||||
<arg value="src/docs/templates/ypgpm.md"/>
|
||||
</jscript>
|
||||
</target>
|
||||
|
||||
<target name="zip_js" depends="coffeescript_setup">
|
||||
<zip destfile="${build}/js-plugins.zip">
|
||||
<zipfileset dir="./src/main/javascript" />
|
||||
<zipfileset dir="${build}/coffeescript" />
|
||||
<!-- Piece together the Young persons' guide from template and generated table of contents -->
|
||||
<target name="construct-ypgpm" depends="gen-toc-ypgpm,init">
|
||||
<concat destfile="docs/YoungPersonsGuideToProgrammingMinecraft.md">
|
||||
<header filtering="no" trimleading="yes"><!--
|
||||
IMPORTANT NOTE FOR CONTRIBUTORS
|
||||
-------------------------------
|
||||
Contributors: This file is generated from source file src/docs/templates/ypgpm.md
|
||||
If you would like to make changes, change file src/docs/templates/ypgpm.md instead
|
||||
-->
|
||||
# The Young Person's Guide to Programming in Minecraft
|
||||
</header>
|
||||
<fileset file="${dist}/toc-ypgpm.md" />
|
||||
<fileset file="src/docs/templates/ypgpm.md" />
|
||||
</concat>
|
||||
</target>
|
||||
|
||||
<target name="zip_js" depends="zip_lib, zip_modules, zip_plugins">
|
||||
</target>
|
||||
|
||||
<target name="copy-js" depends="gen-events-helper-bukkit,gen-events-helper-canary,init">
|
||||
<copy todir="${dist}/js">
|
||||
<fileset dir="src/main/js"/>
|
||||
</copy>
|
||||
</target>
|
||||
|
||||
<target name="zip_lib" depends="copy-js">
|
||||
<delete file="${build}/lib.zip"/>
|
||||
<zip destfile="${build}/lib.zip"
|
||||
basedir="${dist}/js"
|
||||
excludes="modules/**, plugins/**,">
|
||||
</zip>
|
||||
</target>
|
||||
|
||||
<target name="package" depends="gendocs,zip_js,compile"
|
||||
description="generate the distribution" >
|
||||
<target name="get_underscore" depends="copy-js" unless="underscore.present">
|
||||
<!-- download underscore -->
|
||||
<get src="http://underscorejs.org/underscore.js"
|
||||
verbose="true"
|
||||
dest="${dist}/js/modules/underscore.js"/>
|
||||
</target>
|
||||
|
||||
<target name="zip_modules" depends="copy-js, get_underscore">
|
||||
<delete file="${build}/modules.zip"/>
|
||||
<zip destfile="${build}/modules.zip"
|
||||
basedir="${dist}/js"
|
||||
excludes="lib/**, plugins/**,">
|
||||
</zip>
|
||||
</target>
|
||||
|
||||
<target name="zip_plugins" depends="copy-js">
|
||||
<delete file="${build}/plugins.zip"/>
|
||||
<zip destfile="${build}/plugins.zip"
|
||||
basedir="${dist}/js"
|
||||
excludes="lib/**, modules/**">
|
||||
</zip>
|
||||
</target>
|
||||
|
||||
<target name="package" depends="gendocs,zip_js,compile-plugins" description="generate the distribution" >
|
||||
<!-- ensure plugin.yml is always copied -->
|
||||
<delete file="${build}/plugin.yml" />
|
||||
<copy file="src/main/resources/plugin.yml" todir="${build}"/>
|
||||
<replace file="${build}/plugin.yml" value="${bukkit-version}-${DSTAMP}">
|
||||
<replacetoken>[[version]]
|
||||
</replacetoken>
|
||||
<delete file="${build}/Canary.inf" />
|
||||
<copy todir="${build}">
|
||||
<fileset dir="src/main/resources"/>
|
||||
</copy>
|
||||
<replace file="${build}/plugin.yml" value="${scriptcraft-version}-${DSTAMP}">
|
||||
<replacetoken>[[version]]</replacetoken>
|
||||
</replace>
|
||||
<replace file="${build}/Canary.inf" value="${scriptcraft-version}-${DSTAMP}">
|
||||
<replacetoken>[[version]]</replacetoken>
|
||||
</replace>
|
||||
|
||||
<!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file -->
|
||||
<mkdir dir="${dist}/${DSTAMP}" />
|
||||
<jar jarfile="${dist}/${DSTAMP}/ScriptCraft.jar" basedir="${build}"/>
|
||||
|
||||
<jar jarfile="${dist}/${DSTAMP}/scriptcraft.jar" basedir="${build}"/>
|
||||
<copy file="${dist}/${DSTAMP}/scriptcraft.jar" tofile="${dist}/scriptcraft.jar"/>
|
||||
</target>
|
||||
|
||||
<target name="clean" description="clean up" >
|
||||
<delete dir="${dist}"/>
|
||||
</target>
|
||||
|
||||
<target name="update-live-cb" depends="package" description="Copy the built plugin to the live craftbukkit folder for testing.">
|
||||
<target name="update-live-cb" depends="package" description="Copy the built plugin to the live folder for testing.">
|
||||
<mkdir dir="${minecraft.dir}/plugins" />
|
||||
<delete>
|
||||
<fileset dir="${minecraft.dir}/plugins/" includes="scriptcraft*.*"/>
|
||||
</delete>
|
||||
<mkdir dir="${minecraft.dir}/plugins" />
|
||||
<copy file="${dist}/${DSTAMP}/ScriptCraft.jar" todir="${minecraft.dir}/plugins"/>
|
||||
<copy file="${dist}/${DSTAMP}/scriptcraft.jar" todir="${minecraft.dir}/plugins"/>
|
||||
</target>
|
||||
</project>
|
||||
|
|
|
@ -1,13 +0,0 @@
|
|||
<xsl:stylesheet
|
||||
version="1.0"
|
||||
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
|
||||
|
||||
<xsl:template match="list-item[name='Development Build']">
|
||||
<bukkit>
|
||||
<url><xsl:text>http://dl.bukkit.org</xsl:text><xsl:value-of select="latest_artifact/file/url" /></url>
|
||||
</bukkit>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="text()" />
|
||||
|
||||
</xsl:stylesheet>
|
119
contributing.md
Normal file
|
@ -0,0 +1,119 @@
|
|||
# Status
|
||||
|
||||
[![Travis Build Status](https://api.travis-ci.org/walterhiggins/ScriptCraft.png)](http://travis-ci.org/walterhiggins/ScriptCraft)
|
||||
|
||||
# Notes for Contributors
|
||||
|
||||
This project uses a Maven-like directory structure...
|
||||
|
||||
src +
|
||||
main +
|
||||
java +
|
||||
net +
|
||||
walterhiggins +
|
||||
scriptcraft +
|
||||
ScriptCraftPlugin.java
|
||||
|
||||
js +
|
||||
lib +
|
||||
(core javascript code goes here. Modules in this directory
|
||||
should not be 'require'd by plugin or module authors)
|
||||
modules +
|
||||
(this is where module authors should put modules for
|
||||
use by others)
|
||||
plugins +
|
||||
(this is where plugins - scriptcraft extensions for use by
|
||||
operators and players should go)
|
||||
resources +
|
||||
plugin.yml
|
||||
docs +
|
||||
templates +
|
||||
(documentation templates go here. If you want to make
|
||||
changes to the young persons guide should be made to ypgpm.md)
|
||||
ypgpm.md
|
||||
javascript +
|
||||
(javascript source used to build the API reference and
|
||||
table of contents for the API reference and Programming Guide
|
||||
is located here)
|
||||
docs +
|
||||
(the following files should not be edited directly because they are constructed
|
||||
during the build process - yeah I know they strictly shouldn't be under source control but
|
||||
it's nice to have the markdown docs on github for reading by non-contributors)
|
||||
|
||||
API-Reference.md
|
||||
Young-Persons-Guide.md
|
||||
|
||||
(this project is build using Ant, type `ant` at the command line to build.)
|
||||
|
||||
build.xml
|
||||
build.properties
|
||||
|
||||
## Core javascript modules
|
||||
|
||||
ScriptCraft's deployed core consists of a single Java source file (the
|
||||
Bukkit Plugin) and a tiny set of javascript source files located in
|
||||
the src/main/javascript/lib directory. All other javascript files are
|
||||
optional modules and plugins. `scriptcraft.js` is the first file
|
||||
loaded by the Java plugin. scriptcraft.js in turn loads the require.js
|
||||
file which initializes the commonJS `require()` function and all other
|
||||
files in the lib directory are then loaded. Finally all of the modules
|
||||
in the plugins directory are automatically loaded and any exports are
|
||||
automatically exported to the global namespace. For example a file
|
||||
called `greet.js` located in the plugins folder...
|
||||
|
||||
// plugins/greet.js contents
|
||||
|
||||
exports.greet = function(sender){
|
||||
sender.sendMessage('hello')
|
||||
}
|
||||
|
||||
... will be loaded at startup and the `greet` function will be
|
||||
global. Anyone with operator privileges can type `/js greet(self)` at
|
||||
the in-game command prompt to execute the function.
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
See <https://github.com/rwaldron/idiomatic.js> for a recommended
|
||||
approach to writing javascript code for ScriptCraft. ScriptCraft is
|
||||
aimed at younger programmers so readability is important - moreso than
|
||||
cleverness. If submitting new code for inclusion in ScriptCraft please
|
||||
ensure it is documented using the guidelines below...
|
||||
|
||||
## Documentation contributions
|
||||
|
||||
The Young persons guide to programming source file is located at
|
||||
/src/docs/templates/ypgpm.md . *Do not make changes to
|
||||
/docs/YoungPersonsGuide.md*
|
||||
|
||||
The API Reference is generated by the build from markdown comments
|
||||
embedded in the javascript source. If you would like comments for
|
||||
contributed code to be included in the API reference then enclose your
|
||||
comment as follows:
|
||||
|
||||
* Start the comment block with a `/**********` (a forward-slash
|
||||
followed by 10 or more asterisk characters). *The start block must
|
||||
be at the start of the line*.
|
||||
|
||||
* End the comment block with a `***/` (3 asterisk followed by a
|
||||
forward slash) at the start of a new line.
|
||||
|
||||
This is an example of a comment which will be included in the API reference...
|
||||
|
||||
/*********************
|
||||
## foo() function
|
||||
|
||||
The foo() function performs foo-type operatations on all bars.
|
||||
|
||||
### Parameters
|
||||
|
||||
* name : Name of the foo
|
||||
* count: Number of foos to perform
|
||||
|
||||
### Returns
|
||||
foo() returns a list of foos that were changed.
|
||||
|
||||
***/
|
||||
|
||||
Top level comments for a module should be a H2 heading `##`. Please
|
||||
don't use a H1 heading ( `#` ) as this is used for the top-level API
|
||||
document title.
|
7458
docs/API-Reference.md
Normal file
175
docs/Anatomy-of-a-Plugin.md
Normal file
|
@ -0,0 +1,175 @@
|
|||
# Anatomy of a ScriptCraft Plugin
|
||||
|
||||
Anything you can do using a Java-based plugin, you can do it
|
||||
faster and easier in JavaScript with the ScriptCraft plugin. To
|
||||
demonstrate this, I've recreated a commonly-used mod (homes) in
|
||||
javascript. The [homes][homes] JavaScript plugin lets players set their current
|
||||
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
|
||||
demonstrates a couple of new features in ScriptCraft …
|
||||
|
||||
* Persistence
|
||||
* 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
|
||||
… First persistence. Persistence is the ability to retain state
|
||||
after the server has shutdown and started up again. You can create a
|
||||
JavaScript object which will be saved at shutdown and reloaded at
|
||||
startup by using the built-in `persist()` function.
|
||||
|
||||
```javascript
|
||||
// file: scriptcraft/plugins/my-first-plugin.js
|
||||
var prefs = persist('myprefs', {});
|
||||
...
|
||||
prefs.color = 'black';
|
||||
```
|
||||
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
|
||||
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
|
||||
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
|
||||
ensures that when a player chats, the text will be displayed in their
|
||||
chosen color …
|
||||
|
||||
```javascript
|
||||
var colors = ['black', 'blue', 'darkgreen', 'darkaqua', 'darkred',
|
||||
'purple', 'gold', 'gray', 'darkgray', 'indigo',
|
||||
'brightgreen', 'aqua', 'red', 'pink',
|
||||
'yellow', 'white'];
|
||||
var colorCodes = {};
|
||||
var COLOR_CHAR = '\u00a7';
|
||||
for (var i =0;i < colors.length;i++)
|
||||
colorCodes[colors[i]] = i.toString(16);
|
||||
|
||||
var addColor = function( evt ) {
|
||||
var player = evt.player;
|
||||
var playerChatColor = store.players[ player.name ];
|
||||
if ( playerChatColor ) {
|
||||
evt.message = COLOR_CHAR + colorCodes[ playerChatColor ] + evt.message;
|
||||
}
|
||||
};
|
||||
|
||||
if (__plugin.bukkit) {
|
||||
events.asyncPlayerChat(addColor);
|
||||
} else if (__plugin.canary) {
|
||||
events.chat(addColor);
|
||||
};
|
||||
```
|
||||
|
||||
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
|
||||
messages.
|
||||
|
||||
## Adding new Player Commands
|
||||
The other command in ScriptCraft is the `/jsp` command – this lets
|
||||
operators expose plugins for use by regular players. To be clear, `/jsp`
|
||||
does not do any JavaScript evaluation, it just accepts parameters which
|
||||
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
|
||||
know – actually set their text color of choice – only operators can do
|
||||
this for a player using the `js chat.setColor(...)` JavaScript
|
||||
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
|
||||
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
|
||||
new `command()` function like so …
|
||||
|
||||
```javascript
|
||||
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);
|
||||
```
|
||||
|
||||
… The above code adds a new *subcommand* to the `/jsp` command and
|
||||
also specifies autocomplete options (the last parameter – `colors`) for
|
||||
that command when the player presses the `TAB` key. Now the player
|
||||
themselves can change their chosen chat color like so …
|
||||
|
||||
/jsp chat_color yellow
|
||||
|
||||
… 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
|
||||
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
|
||||
code is just a couple of lines of code but is a fully working plugin …
|
||||
|
||||
```javascript
|
||||
var store = persist('chat-colors', {players: {}});
|
||||
exports.chat = {
|
||||
setColor: function(player,chatColor) {
|
||||
store.players[player.name] = chatColor;
|
||||
}
|
||||
}
|
||||
var colors = ['black', 'blue', 'darkgreen', 'darkaqua', 'darkred',
|
||||
'purple', 'gold', 'gray', 'darkgray', 'indigo',
|
||||
'brightgreen', 'aqua', 'red', 'pink',
|
||||
'yellow', 'white'];
|
||||
var colorCodes = {};
|
||||
var COLOR_CHAR = '\u00a7';
|
||||
for (var i =0;i < colors.length;i++)
|
||||
colorCodes[colors[i]] = i.toString(16);
|
||||
|
||||
var addColor = function( evt ) {
|
||||
var player = evt.player;
|
||||
var playerChatColor = store.players[ player.name ];
|
||||
if ( playerChatColor ) {
|
||||
evt.message = COLOR_CHAR + colorCodes[ playerChatColor ] + evt.message;
|
||||
}
|
||||
};
|
||||
|
||||
if (__plugin.bukkit) {
|
||||
events.asyncPlayerChat(addColor);
|
||||
} else if (__plugin.canary) {
|
||||
events.chat(addColor);
|
||||
};
|
||||
|
||||
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]
|
||||
|
||||
… this is what I would call a minimum viable plugin and it
|
||||
demonstrates some of the new features of ScriptCraft – persistence
|
||||
(automatic), event handling, and exposing new functionality to players
|
||||
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
|
||||
their needs.
|
||||
|
||||
[1]: img/scriptcraft-chat-color.png
|
||||
|
46
docs/Frequently-Asked-Questions.md
Normal file
|
@ -0,0 +1,46 @@
|
|||
## Using Other Plugins from ScriptCraft
|
||||
The following question gets asked a lot so I'm going to try to answer it here:
|
||||
|
||||
> How to use other bukkit plugins API?
|
||||
> Like PermissionEX API.
|
||||
> I can check permission group by java code:
|
||||
> ru.tehkode.permissions.bukkit.PermissionsEx.getUser(player).inGroup("moderator");
|
||||
> But I can't run this code in JavaScript.
|
||||
> -- [Bukkit forum question][1]
|
||||
|
||||
[1]: http://dev.bukkit.org/bukkit-plugins/scriptcraft/?page=2#c48
|
||||
|
||||
The above question refers to using ScriptCraft for CraftBukkit so I'll answer that first:
|
||||
|
||||
You can get the permissionsEx (or any other Bukkit plugin) like this...
|
||||
```javascript
|
||||
var pex = server.pluginManager.getPlugin('PermissionsEx');
|
||||
if (pex.getUser(player).inGroup('moderator') ) {
|
||||
...
|
||||
}
|
||||
```
|
||||
Generally if you want to use another plugin's API, then get the plugin object by name and then call its methods. In the above example the `pex` variable refers to the aforementioned `PermissionsEx` Plugin. Once you have that reference you can call any of the plugin's methods just as you would in Java. The tricky part is getting the reference and that's where `server.pluginManager.getPlugin()` comes in.
|
||||
|
||||
To get a reference to and work with another plugin's API using ScriptCraft for CanaryMod the same principle applies. Say you've installed ScriptCraft and the dConomy plugin:
|
||||
|
||||
```javascript
|
||||
var Canary = Packages.net.canarymod.Canary;
|
||||
var pluginMgr = Canary.pluginManager();
|
||||
var dConomy = pluginMgr.getPlugin('dConomy');
|
||||
var dConomyServer = dConomy.modServer;
|
||||
// from here on in you can access all of the dConomyServer object's calls
|
||||
// e.g. dConomyServer.newTransaction()
|
||||
```
|
||||
|
||||
The only difference between CanaryMod and Bukkit is how you get the plugin reference. In Bukkit it's:
|
||||
|
||||
```javascript
|
||||
var otherPlugin = server.pluginManager.getPlugin('PLUGIN_NAME_GOES_HERE');
|
||||
```
|
||||
|
||||
whereas in CanaryMod it's:
|
||||
|
||||
```javascript
|
||||
var Canary = Packages.net.canarymod.Canary;
|
||||
var otherPlugin = Canary.pluginManager().getPlugin('PLUGIN_NAME_GOES_HERE');
|
||||
```
|
126
docs/Using-Java-APIs-In-Javascript.md
Normal file
|
@ -0,0 +1,126 @@
|
|||
# Using Java APIs in Javascript
|
||||
|
||||
ScriptCraft uses the Javascript Engine bundled with Java 6 and later
|
||||
versions. This means that all of the core Java classes can be used
|
||||
from within ScriptCraft. In addition, all of the Bukkit API can be
|
||||
used from Javascript too. There are some things to consider when using
|
||||
Java classes in Javascript...
|
||||
|
||||
## Using Java Beans
|
||||
|
||||
The Javascript Engine bundled with Java comes with a handy notation
|
||||
for accessing and modifying Java Beans. A Java Bean is any Java class
|
||||
which uses a `get{Property}()` method to retrieve an object's property
|
||||
and a `set{Property}()` method to set the object's property. One
|
||||
example of a Java Bean in the [Bukkit API][bukapi] is the
|
||||
[org.bukkit.entity.Player][bukpl] Class which has many methods which
|
||||
conform to the JavaBean specification.
|
||||
|
||||
For example the [Player.getWalkSpeed()][bukplws] can be used to get a
|
||||
player's walking speed. In Java you would have to write code like this
|
||||
to obtain the walking speed...
|
||||
|
||||
float walkingSpeed = player.getWalkSpeed();
|
||||
|
||||
... however, in Javascript you can access the walking-speed property
|
||||
using the more succinct...
|
||||
|
||||
var walkingspeed = player.walkSpeed;
|
||||
|
||||
... or if you prefer to use Java-style access...
|
||||
|
||||
var walkingspeed = player.getWalkSpeed();
|
||||
|
||||
... I personally prefer to use the simpler `player.walkSpeed` because
|
||||
it is easier to read. The important thing to remember when using the
|
||||
Bukkit (or any Java API) from Javascript is that for any Java Bean, a
|
||||
property called `propertyName` will have a getter called
|
||||
`getPropertyName()` and a setter called `setPropertyName()`. From this
|
||||
rule you can infer what any Bukkit class properties are. For example,
|
||||
the [Bukkit Player][bukpl] object has the following methods...
|
||||
|
||||
* float getWalkSpeed()
|
||||
* void setWalkSpeed(float speed)
|
||||
|
||||
... so from this you can infer that every Player object has a
|
||||
`walkSpeed` property which can be read and changed. For example you
|
||||
can triple your own walking speed (from the default 0.2) at the
|
||||
in-game prompt using the following command...
|
||||
|
||||
/js self.walkSpeed = self.walkSpeed * 3;
|
||||
|
||||
... If we were limited to using Java's notation we would have had to
|
||||
write `/js self.setWalkSpeed( self.getWalkSpeed() * 3 )` . Since
|
||||
almost every class in the Bukkit API is also a JavaBean you can access
|
||||
properties of properties and so on. For example, to get the name of
|
||||
the world in which a player is located...
|
||||
|
||||
/js self.location.world.name
|
||||
|
||||
... is more concise than `/js self.getLocation().getWorld().getName()`.
|
||||
If you're new to Java and the [Bukkit API][bukapi] is the first time
|
||||
you've browsed Java documentation, you may be wondering where the
|
||||
`location` property came from - the `location` property is "inherited"
|
||||
from one of the Player class's super-classes (it's ancestors). You'll see the
|
||||
`getLocation()` method listed under a section titled **Methods
|
||||
inherited from interface org.bukkit.entity.Entity** in the
|
||||
[Player][bukpl] javadoc page.
|
||||
|
||||
## Using java.lang package classes
|
||||
|
||||
In Java the following code will print out the `user.dir` and
|
||||
`user.timezone` properties...
|
||||
|
||||
System.out.println( System.getProperty( "user.dir" ) );
|
||||
System.out.println( System.getProperty( "user.timezone" ) );
|
||||
|
||||
... In Java, any classes in the `java.lang` package don't need to be
|
||||
prefixed with the package so the `java.lang.System` class can simply
|
||||
be written as `System`. However, in Javascript classes in the
|
||||
`java.lang` package need to be fully qualified so you need to write...
|
||||
|
||||
println( java.lang.System.getProperty( "user.dir" ) );
|
||||
println( java.lang.System.getProperty( "user.timezone" ) );
|
||||
|
||||
... the `println()` function is one of the default functions provided
|
||||
by the JS Engine in Java so there is no need to add the class name
|
||||
prefix, but for other System class methods you need to explicitly
|
||||
include the package name e.g. `java.lang.`. If you are using the
|
||||
System class in a number of statements you can save yourself some
|
||||
typing by declaring a System variable and using that instead of the
|
||||
fully-qualified package and class name...
|
||||
|
||||
var System = java.lang.System;
|
||||
println( System.getProperty( "user.dir" ) );
|
||||
println( System.getProperty( "user.timezone" ) );
|
||||
|
||||
The JS Engine provides an `importPackage()` function which can be used
|
||||
to import packages. This also saves you having to type full package
|
||||
names before classes. For example...
|
||||
|
||||
importPackage(java.util);
|
||||
var hMap = new HashMap();
|
||||
hMap.put('name','Walter');
|
||||
|
||||
... makes all of the classes in the Java Library's `java.util` package
|
||||
available for use without having to use the `java.util`
|
||||
prefix. However, importing the `java.lang` package is not recommended
|
||||
as some of the java.lang classes (e.g. String, Object) conflict with
|
||||
Javascript Object types.
|
||||
|
||||
## Summary
|
||||
|
||||
When writing modules or plugins in ScriptCraft, you can access and
|
||||
change JavaBean properties using a simple .{propertyName} notation
|
||||
instead of using the Java .get{PropertyName}() and .set{PropertyName()
|
||||
methods. This results in more concise code. This simpler notation is
|
||||
provided by the Javascript Engine embedded in Java 6 and later
|
||||
versions. Javascript does not have access to private members, the
|
||||
.{propertyName} notation is automagically converted to the appropriate
|
||||
.get{PropertyName}() or .set{PropertyName}() method by Java.
|
||||
|
||||
[bukapi]: http://jd.bukkit.org/beta/apidocs/
|
||||
[bukpl]: http://jd.bukkit.org/beta/apidocs/org/bukkit/entity/Player.html
|
||||
[bukplws]: http://jd.bukkit.org/beta/apidocs/org/bukkit/entity/Player.html#getWalkSpeed()
|
||||
[buksrv]: http://jd.bukkit.org/beta/apidocs/org/bukkit/Server.html
|
||||
|
1466
docs/api.md
BIN
docs/img/castleex1.png
Normal file
After Width: | Height: | Size: 387 KiB |
BIN
docs/img/chessboardex1.png
Normal file
After Width: | Height: | Size: 113 KiB |
BIN
docs/img/cottageex1.png
Normal file
After Width: | Height: | Size: 116 KiB |
BIN
docs/img/cottageroadex1.png
Normal file
After Width: | Height: | Size: 159 KiB |
BIN
docs/img/cowclicker.png
Normal file
After Width: | Height: | Size: 98 KiB |
BIN
docs/img/dancefloorex1.png
Normal file
After Width: | Height: | Size: 163 KiB |
BIN
docs/img/fortex1.png
Normal file
After Width: | Height: | Size: 207 KiB |
BIN
docs/img/lcdclockex1.png
Normal file
After Width: | Height: | Size: 165 KiB |
BIN
docs/img/mazeex1.png
Normal file
After Width: | Height: | Size: 324 KiB |
BIN
docs/img/scriptcraft-chat-color.png
Normal file
After Width: | Height: | Size: 98 KiB |
BIN
docs/img/templeex1.png
Normal file
After Width: | Height: | Size: 306 KiB |
1
lib/.gitignore
vendored
Normal file
|
@ -0,0 +1 @@
|
|||
/canarymod.jar
|
BIN
lib/canarymod-1.8.0.jar
Normal file
BIN
lib/spigot-1.11.2.jar
Normal file
21
license.txt
Normal file
|
@ -0,0 +1,21 @@
|
|||
The MIT License (MIT)
|
||||
|
||||
Copyright (c) 2016 Walter Higgins
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
|
@ -1,43 +0,0 @@
|
|||
package net.minecraft.src;
|
||||
/**
|
||||
* This mod lets you load and run javascript to build structures which
|
||||
* would otherwise be tedious. Build road networks, rows of houses,
|
||||
* factories and sky-scrapers. ScriptCraft takes building to a whole
|
||||
* new level by making it easy to create javascript scripts that do
|
||||
* the building for you. The following code creates a simple cottage
|
||||
* at the crosshair location or the player's current location...
|
||||
*
|
||||
* load("./drone.js");
|
||||
* var drone = new Drone().chkpt('cornerstone');
|
||||
* drone.box0(48,7,2,6) // 4 walls
|
||||
* .right(3).door() // a door front-center
|
||||
* .left(2).box(102) // windows left and right of door
|
||||
* .right(4).box(102) //
|
||||
* .move('cornerstone').up(2).prism0(53,7,6); // a gable roof
|
||||
*
|
||||
*/
|
||||
|
||||
public class CommandScript extends CommandBase
|
||||
{
|
||||
ScriptCraftEvaluator evaluator = null;
|
||||
|
||||
public String getCommandName() { return "js"; }
|
||||
|
||||
public int getRequiredPermissionLevel() { return 0; }
|
||||
|
||||
public void processCommand(ICommandSender par1ICommandSender, String[] args)
|
||||
{
|
||||
if (this.evaluator == null)
|
||||
this.evaluator = new ScriptCraftEvaluator(new ScriptCraftMCP(this));
|
||||
|
||||
// Collect the arguments into a single string.
|
||||
String s = "";
|
||||
for (int i=0; i < args.length; i++) {
|
||||
s += args[i] + " ";
|
||||
}
|
||||
// Now evaluate the string we've colected.
|
||||
this.evaluator.eval(s,par1ICommandSender);
|
||||
|
||||
return;
|
||||
}
|
||||
}
|
|
@ -1,12 +0,0 @@
|
|||
package net.minecraft.src;
|
||||
|
||||
public interface IScriptCraft
|
||||
{
|
||||
public double[] getPlayerPos();
|
||||
public double[] getMousePos();
|
||||
public void putSign(String[] texts,int x, int y, int z, int block, int meta);
|
||||
public void putBlock(int x, int y, int z, int blockId, int meta);
|
||||
public String getBlock(int x, int y, int z);
|
||||
public void notifyAdministrators(String message);
|
||||
public void setInvoker(Object invoker);
|
||||
}
|
|
@ -1,265 +0,0 @@
|
|||
package net.minecraft.src;
|
||||
|
||||
import org.mozilla.javascript.*;
|
||||
import java.util.List;
|
||||
import java.io.*;
|
||||
import javax.swing.JFileChooser;
|
||||
|
||||
public class ScriptCraftEvaluator
|
||||
{
|
||||
protected static IScriptCraft sc = null;
|
||||
protected Context ctx = null;
|
||||
protected Scriptable scope = null;
|
||||
|
||||
public static class MCScope extends ImporterTopLevel{
|
||||
public MCScope(Context ctx){
|
||||
super(ctx);
|
||||
}
|
||||
}
|
||||
public ScriptCraftEvaluator(IScriptCraft scImpl)
|
||||
{
|
||||
ScriptCraftEvaluator.sc = scImpl;
|
||||
this.ctx = Context.enter();
|
||||
ScriptableObject importer = new ScriptCraftEvaluator.MCScope(ctx);
|
||||
this.scope = this.ctx.initStandardObjects(importer);
|
||||
//
|
||||
// for mcp debug only
|
||||
//ctx.evaluateString(scope,"importPackage(net.minecraft.src)","<cmd>",1,null);
|
||||
//
|
||||
String[] names = {
|
||||
"print"
|
||||
,"load"
|
||||
,"help"
|
||||
,"getPlayerPos"
|
||||
,"getMousePos"
|
||||
,"putBlock"
|
||||
,"getBlock"
|
||||
,"putSign"
|
||||
};
|
||||
importer.defineFunctionProperties(names,
|
||||
ScriptCraftEvaluator.class,
|
||||
ScriptableObject.DONTENUM);
|
||||
}
|
||||
/**
|
||||
* So clients can add their own properties ...
|
||||
*
|
||||
* evaluator.getScope().defineProperty("jsVarName",javaObject);
|
||||
*/
|
||||
public ScriptableObject getScope()
|
||||
{
|
||||
return (ScriptableObject)this.scope;
|
||||
}
|
||||
|
||||
public Object eval(String javascript, Object invoker)
|
||||
{
|
||||
ScriptCraftEvaluator.sc.setInvoker(invoker);
|
||||
ScriptCraftEvaluator.sc.notifyAdministrators("js> " + javascript);
|
||||
Object result = null;
|
||||
try
|
||||
{
|
||||
result = ctx.evaluateString(this.scope, javascript, "<cmd>", 1, null);
|
||||
}
|
||||
catch(Exception e)
|
||||
{
|
||||
e.printStackTrace(System.err);
|
||||
ScriptCraftEvaluator.sc.notifyAdministrators("Exception: " + e.getMessage());
|
||||
}
|
||||
if (result != null)
|
||||
{
|
||||
ScriptCraftEvaluator.sc.notifyAdministrators(Context.toString(result));
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Load a javascript source file and evaluate its contents.
|
||||
*/
|
||||
public static Object load(Context cx, Scriptable thisObj, Object[] args, Function funObj)
|
||||
{
|
||||
Object result = null;
|
||||
|
||||
File scriptFile = null;
|
||||
String filename = null;
|
||||
|
||||
if (args.length == 0)
|
||||
{
|
||||
JFileChooser fc = new javax.swing.JFileChooser();
|
||||
int rc = fc.showOpenDialog(null);
|
||||
if (rc ==JFileChooser.APPROVE_OPTION){
|
||||
scriptFile = fc.getSelectedFile();
|
||||
}else{
|
||||
return result;
|
||||
}
|
||||
}else{
|
||||
scriptFile = new File((String)args[0]);
|
||||
}
|
||||
|
||||
FileReader in = null;
|
||||
try {
|
||||
in = new FileReader(scriptFile);
|
||||
}
|
||||
catch (FileNotFoundException ex)
|
||||
{
|
||||
ex.printStackTrace(System.err);
|
||||
ScriptCraftEvaluator.sc.notifyAdministrators( "Error - File not found " + args[0]);
|
||||
Context.reportError("Couldn't open file \"" + scriptFile + "\".");
|
||||
return null;
|
||||
}
|
||||
filename = scriptFile.getAbsolutePath();
|
||||
System.out.println("ScripCraftEvaluator: filename=" + filename);
|
||||
File parentFile = scriptFile.getParentFile();
|
||||
String filedir = null;
|
||||
if (parentFile !=null){
|
||||
filedir = parentFile.getAbsolutePath();
|
||||
}
|
||||
//
|
||||
// setup the special script-context-only variables
|
||||
//
|
||||