This repository has been archived on 2021-07-14. You can view files and clone it, but cannot push or open issues or pull requests.
scriptcraft/README.md

180 lines
7.6 KiB
Markdown
Raw Normal View History

2013-12-19 11:43:37 +01:00
# Let's begin...
2013-12-24 23:47:57 +01:00
I created ScriptCraft to make it easier for younger programmers to
2014-01-02 11:37:34 +01:00
create their own Minecraft Mods. Mods are written using the
Javascript programming language. Once the ScriptCraft mod is
2013-12-24 23:47:57 +01:00
installed, you can add your own new Mods by adding Javascript (.js)
files in a directory.
2013-12-19 11:43:37 +01:00
* If you're new to programming and want to start modding Minecraft, then [Start Here][ypgpm].
* If you've already used [Scratch][scr], have attended a few
[CoderDojo][cd] sessions, or have already dabbled with Javascript,
then [Start Here][cda].
2013-12-19 12:06:17 +01:00
* Watch some [demos][ytpl] of what you can do with ScriptCraft.
2014-01-02 11:44:26 +01:00
This is a simple mod in a file called greet.js in the scriptcraft/plugins directory...
2014-01-30 01:41:59 +01:00
```javascript
exports.greet = function( player ) {
player.sendMessage('Hello ' + player.name );
};
```
2014-01-02 11:44:26 +01:00
At the in-game prompt, type...
/js greet(self)
2014-01-30 01:41:59 +01:00
2014-01-02 11:44:26 +01:00
... to see the greeting. Anything you can do using CraftBukkit's API in Java, you can do using ScriptCraft in Javascript.
2013-12-19 12:06:17 +01:00
# Description
2013-12-19 11:43:37 +01:00
ScriptCraft is a plugin for Minecraft Servers which lets operators,
administrators and plug-in authors customize the game using
2013-01-25 00:46:28 +01:00
Javascript. ScriptCraft makes it easier to create your own mods. Mods
2014-01-02 11:37:34 +01:00
can be written in Javscript and can use the full [Bukkit API][bukkit]. The
2013-01-25 00:46:28 +01:00
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.
2013-12-24 23:47:57 +01:00
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 [cottage.js][cottage] file for an example
of how you can use the sample Drone plugin to create new buildings in
2013-01-25 00:46:28 +01:00
Minecraft.
2013-01-08 03:57:27 +01:00
2013-01-25 00:46:28 +01:00
[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
2014-01-02 11:37:34 +01:00
[bukkit]: http://dl.bukkit.org/
2013-01-08 03:57:27 +01:00
2014-01-15 00:25:00 +01:00
# Prerequisites
2013-01-25 00:46:28 +01:00
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]
2014-01-15 00:25:00 +01:00
# Installation
2013-01-25 00:46:28 +01:00
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.
2014-01-15 00:25:00 +01:00
# Post Install
2013-01-25 00:46:28 +01:00
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.
Launch CraftBukkit, 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 ...
/js up().box('35:15', 4, 9, 1)
... 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.
2013-12-24 23:47:57 +01:00
[ho]: blob/master/src/main/javascript/plugins/homes/homes.js
[ch]: blob/master/src/main/javascript/plugins/chat/color.js
[ar]: blob/master/src/main/javascript/plugins/arrows/arrows.js
[si]: blob/master/src/main/javascript/modules/signs/menu.js
2013-01-25 00:46:28 +01:00
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.
2014-01-15 00:25:00 +01:00
# Additional information
2013-01-25 00:46:28 +01:00
Because the Bukkit API is open, all of the Bukkit API is accessible
via javascript once the ScriptCraft plugin is loaded. There are a
couple of useful Java objects exposed via javascript in the Bukkit
ScriptCraft plugin...
2013-01-25 00:46:28 +01:00
2013-12-24 23:47:57 +01:00
* `__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() ).
* `server` - The top-level org.bukkit.Server object. See the [Bukkit API docs][bukapi] for reference.
2013-12-24 23:47:57 +01:00
* `self` - The player/command-block or server console operator who
invoked the `/js` command. Again, this is a good jumping off point for
2013-12-24 23:47:57 +01:00
diving into the Bukkit API.
2013-01-25 00:46:28 +01:00
[dl]: http://scriptcraftjs.org/download
2013-01-25 00:46:28 +01:00
[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/
2012-12-27 14:21:08 +01:00
2014-01-15 00:25:00 +01:00
# Contributing
If you would like to contribute source code and/or documentation changes please [read contributing.md][contrib]
2014-01-15 00:25:00 +01:00
## Status
[![Travis Build Status](https://api.travis-ci.org/walterhiggins/ScriptCraft.png)](http://travis-ci.org/walterhiggins/ScriptCraft)
# Configuration
2014-01-15 00:01:20 +01:00
ScriptCraft is a 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.
2014-01-15 00:25:00 +01:00
# Further Reading
2013-01-25 09:16:35 +01:00
ScriptCraft has [its own website][website] with further information.
2013-12-19 12:13:25 +01:00
* To get started using ScriptCraft to Learn Javascript, read [The Young Person's Guide to Programming in Minecraft][yp].
2013-02-09 21:31:36 +01:00
* The ScriptCraft [API documentation][api].
2013-12-19 12:13:25 +01:00
* To delve deeper into creating your own minecraft mod for use by others, read [Creating a complete Minecraft Mod in Javascript][mm].
2013-12-31 10:48:38 +01:00
* Take a look at some [examples][ex]
2013-01-25 09:16:35 +01:00
2013-01-02 11:28:40 +01:00
You can find more information about [ScriptCraft on my blog][blog].
[blog]: http://walterhiggins.net/blog/cat-index-scriptcraft.html
2013-01-05 00:56:30 +01:00
[buk]: https://github.com/walterhiggins/ScriptCraft/blob/master/bukkit.md
2013-12-19 12:10:08 +01:00
[yp]: docs/YoungPersonsGuideToProgrammingMinecraft.md
2013-12-31 10:48:38 +01:00
[mm]: docs/Anatomy-of-a-Plugin.md
[api]: https://github.com/walterhiggins/ScriptCraft/blob/master/docs/API-Reference.md
[website]: http://scriptcraftjs.org/
2013-12-19 12:10:08 +01:00
[ypgpm]: docs/YoungPersonsGuideToProgrammingMinecraft.md
2013-12-19 11:43:37 +01:00
[cd]: http://coderdojo.com/
[scr]: http://scratch.mit.edu/
[cda]: http://cdathenry.wordpress.com/category/modderdojo/
2013-12-19 12:06:17 +01:00
[ytpl]: http://www.youtube.com/watch?v=DDp20SKm43Y&list=PL4Tw0AgXQZH5BiFHqD2hXyXQi0-qFbGp_
2013-12-31 10:52:59 +01:00
[ex]: ../../tree/master/src/main/javascript/plugins/examples
[contrib]: contributing.md