updating docs for module release
This commit is contained in:
walterhiggins
parent
60de2ec28a
commit
82f1928628
48
README.md
48
README.md
|
|
@ -1,6 +1,11 @@
|
|||
# Let's begin...
|
||||
|
||||
I created ScriptCraft to make it easier for younger programmers to create their own Minecraft Mods. ScriptCraft makes it easier for new programmers to create Minecraft mods. Mods are written using the Javascript programming language and once the ScriptCraft mod is installed, you can add your own new Mods by adding Javascript (.js) files in a directory.
|
||||
I created ScriptCraft to make it easier for younger programmers to
|
||||
create their own Minecraft Mods. ScriptCraft makes it easier for new
|
||||
programmers to create Minecraft mods. Mods are written using the
|
||||
Javascript programming language and once the ScriptCraft mod is
|
||||
installed, you can add your own new Mods by adding Javascript (.js)
|
||||
files in a directory.
|
||||
|
||||
* 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].
|
||||
|
|
@ -17,22 +22,11 @@ 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.
|
||||
|
||||
ScriptCraft also includes many objects and functions to make building and modding easier 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.
|
||||
|
||||
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
|
||||
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
|
||||
Minecraft.
|
||||
|
||||
[drone]: https://github.com/walterhiggins/ScriptCraft/tree/master/src/main/javascript/drone/drone.js
|
||||
|
|
@ -78,10 +72,10 @@ 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.
|
||||
|
||||
[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
|
||||
[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
|
||||
|
||||
A Javascript mod for minecraft is just a javascript source file (.js)
|
||||
located in the craftbukkit/js-plugins directory. All .js files in this
|
||||
|
|
@ -99,8 +93,16 @@ 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...
|
||||
|
||||
* `__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.
|
||||
* `__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.
|
||||
|
||||
[dl]: http://scriptcraftjs.org/download
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
|
|
@ -439,18 +439,18 @@ object can do, let's use that knowledge to create a Minecraft Mod!
|
|||
|
||||
Once you've installed Notepad++, Launch it, create a new file and type the following...
|
||||
|
||||
function greet(){
|
||||
exports.greet = function(){
|
||||
echo("Hi " + self.name);
|
||||
}
|
||||
|
||||
... then save the file in a new directory
|
||||
`craftbukkit/js-plugins/{your_name}` (replace {your_name} with your
|
||||
`craftbukkit/scriptcraft/plugins/{your_name}` (replace {your_name} with your
|
||||
own name) and call the file `greet.js` (be sure to change the file-type
|
||||
option to '*.* All Files' when saving or NotePad++ will add a '.txt'
|
||||
extension to the filename. Now switch back to the Minecraft game and
|
||||
type...
|
||||
|
||||
/reload
|
||||
/js refresh()
|
||||
|
||||
... to reload all of the server plugins. Your mod has just been
|
||||
loaded. Try it out by typing this command...
|
||||
|
|
@ -465,8 +465,30 @@ loaded. Try it out by typing this command...
|
|||
minecraft username. Congratulations - You've just written your very
|
||||
first Minecraft Mod! With ScriptCraft installed, writing Minecraft
|
||||
Mods is as simple as writing a new javascript function and saving it
|
||||
in a file in the js-plugins directory. This function will now be
|
||||
avaible every time you launch minecraft.
|
||||
in a file in the craftbukkit/scriptcraft/plugins directory. This
|
||||
function will now be avaible every time you launch minecraft. This is
|
||||
a deliberately trivial minecraft mod but the principles are the same
|
||||
when creating more complex mods.
|
||||
|
||||
The `exports` variable is a special variable you can use in your mod
|
||||
to provide functions, objects and variables for others to use. If you
|
||||
want to provide something for other programmers to use, you should
|
||||
"export" it using the special `exports` variable. The syntax is
|
||||
straightforward and you can use the same `exports` variable to export
|
||||
one or more functions, objects or variables. For example...
|
||||
|
||||
#### thrower.js
|
||||
|
||||
exports.egg = function(){
|
||||
self.throwEgg();
|
||||
}
|
||||
exports.snowball = function(){
|
||||
self.throwSnowball();
|
||||
}
|
||||
|
||||
... is a plugin which provides 2 javascript functions called `egg()`
|
||||
and `snowball()` which can be invoked from the in-game prompt like
|
||||
this `/js egg()` or `/js snowball()`.
|
||||
|
||||
### Parameters
|
||||
If you want to change the `greet()` function so that it displays a
|
||||
|
|
@ -479,11 +501,11 @@ differently each time it is called.
|
|||
|
||||
Change the `greet()` function so that it looks like this...
|
||||
|
||||
function greet( greeting ) {
|
||||
exports.greet = function ( greeting ) {
|
||||
echo( greeting + self.name );
|
||||
}
|
||||
|
||||
... Save your greet.js file and issue the /reload command in
|
||||
... Save your greet.js file and issue the `/js refresh()` command in
|
||||
minecraft. Now enter the following command in Minecraft...
|
||||
|
||||
greet("Hello ");
|
||||
|
|
@ -672,7 +694,7 @@ function. Open the `hi.js` file you created earlier (using NotePad++ ,
|
|||
TextWrangler or your editor of choice) and add the following code at
|
||||
the bottom of the file...
|
||||
|
||||
function hiAll(){
|
||||
exports.hiAll = function (){
|
||||
var players = server.onlinePlayers;
|
||||
for (var i = 0; i < players.length; i++) {
|
||||
var player = players[i];
|
||||
|
|
@ -760,6 +782,7 @@ utils.foreach() function...
|
|||
/*
|
||||
give every player the ability to fly.
|
||||
*/
|
||||
var utils = require('utils');
|
||||
utils.foreach( server.onlinePlayers,
|
||||
function (player) {
|
||||
player.setAllowFlight(true);
|
||||
|
|
@ -771,6 +794,7 @@ utils.foreach() function...
|
|||
/*
|
||||
Play a Cat's Meow sound for each player.
|
||||
*/
|
||||
var utils = require('utils');
|
||||
utils.foreach( server.onlinePlayers,
|
||||
function (player) {
|
||||
player.playSound(player.location,
|
||||
|
|
@ -811,26 +835,26 @@ pointing at the block, type the following into the in-game prompt...
|
|||
... A skyscraper with just a single floor isn't much of a skyscraper
|
||||
so the next step is to repeat this over and over. This is where `for`
|
||||
loops come in. Open your favorite text editor and create a new file in
|
||||
your js-plugins/{your-name} directory called `myskyscraper.js`, then
|
||||
your scriptcraft/plugins/{your-name} directory, name the file `myskyscraper.js`, then
|
||||
type the following...
|
||||
|
||||
function skyscraper(floors)
|
||||
exports.myskyscraper = function(floors)
|
||||
{
|
||||
floors = floors || 10; // default number of floors is 10
|
||||
this.chkpt('skyscraper'); // saves the drone position so it can return there later
|
||||
this.chkpt('myskyscraper'); // saves the drone position so it can return there later
|
||||
for (var i = 0; i < floors; i++)
|
||||
{
|
||||
this.box(blocks.iron,20,1,20).up().box0(blocks.glass_pane,20,3,20).up(3);
|
||||
}
|
||||
return this.move('skyscraper'); // return to where we started
|
||||
return this.move('myskyscraper'); // return to where we started
|
||||
};
|
||||
|
||||
load("../drone/drone.js");
|
||||
Drone.extend('skyscraper',skyscraper);
|
||||
Drone.extend('myskyscraper',myskyscraper);
|
||||
|
||||
... so this takes a little explaining. First I create a new function
|
||||
called skyscraper that will take a single parameter `floors` so that
|
||||
when you eventually call the `skyscraper()` function you can tell it
|
||||
called myskyscraper that will take a single parameter `floors` so that
|
||||
when you eventually call the `myskyscraper()` function you can tell it
|
||||
how many floors you want built. The first statement in the function
|
||||
`floors = floors || 10;` just sets floors to 10 if no parameter is
|
||||
supplied. The next statement `this.chkpt('myskyscraper')` just saves
|
||||
|
|
@ -845,7 +869,7 @@ so that now it can build skyscrapers among other things. Once you've
|
|||
typed in the above code and saved the file, type `reload` in your
|
||||
in-game prompt, then type ...
|
||||
|
||||
/js skyscraper(2);
|
||||
/js myskyscraper(2);
|
||||
|
||||
... A two-story skyscraper should appear. If you're feeling
|
||||
adventurous, try a 10 story skyscraper! Or a 20 story skyscraper!
|
||||
|
|
@ -904,7 +928,7 @@ whatever follows it.
|
|||
What if you want to display a message in both cases - whether you're
|
||||
flying or not? This is where the `if - else` construct comes in handy.
|
||||
Open your favorite editor and type the following code into a new file
|
||||
in your js-plugins directory...
|
||||
in your scriptcraft/plugins directory...
|
||||
|
||||
function flightStatus()
|
||||
{
|
||||
|
|
@ -935,7 +959,7 @@ minecraft, I recommend reading the accompanying [ScriptCraft API
|
|||
reference][api] which covers all of the ScriptCraft functions, objects
|
||||
and methods. I also recommend reading the source code to some of the
|
||||
existing scriptcraft add-ons, the *chat* module (
|
||||
`js-plugins/chat/chat.js` ) is a good place to start, followed by
|
||||
`scriptcraft/plugins/chat/color.js` ) is a good place to start, followed by
|
||||
[Anatomy of a ScriptCraft Plug-in][ap]. The online [Craftbukkit API
|
||||
Reference][cbapi] provides lots of valuable information about the
|
||||
different objects and methods available for use by ScriptCraft.
|
||||
|
|
|
|||
|
|
@ -86,8 +86,12 @@ var store = [];
|
|||
find(new File(dir),store,/\/[a-zA-Z0-9_\-]+\.js$/);
|
||||
|
||||
store.sort(sorter([
|
||||
/_scriptcraft\.js$/,
|
||||
/core/,
|
||||
/scriptcraft\.js$/,
|
||||
/require\.js$/,
|
||||
/plugin\.js$/,
|
||||
/events\.js$/,
|
||||
/lib/,
|
||||
/modules/,
|
||||
/drone\.js/,
|
||||
/drone/
|
||||
]));
|
||||
|
|
|
|||
|
|
@ -1,8 +1,6 @@
|
|||
/*************************************************************************
|
||||
## Require - Node.js-style module loading in ScriptCraft
|
||||
|
||||
#### (Experimental as of 2013-12-21)
|
||||
|
||||
Node.js is a server-side javascript environment with an excellent
|
||||
module loading system based on CommonJS. Modules in Node.js are really
|
||||
simple. Each module is in its own javascript file and all variables
|
||||
|
|
@ -11,6 +9,8 @@ There is a very concise explanation of CommonJS modules at...
|
|||
|
||||
[http://wiki.commonjs.org/wiki/Modules/1.1.1.][cjsmodules]
|
||||
|
||||
Node.js also has good documentation on [Modules][njsmod].
|
||||
|
||||
If you want to export a variable or function you use the module.export
|
||||
property.
|
||||
|
||||
|
|
@ -48,7 +48,6 @@ support node modules. Node.js and Rhino are two very different
|
|||
Javascript environments. ScriptCraft uses Rhino Javascript, not
|
||||
Node.js.
|
||||
|
||||
Right now, the base directory is for relative modules is 'js-plugins'.
|
||||
Modules can be loaded using relative or absolute paths. Per the CommonJS
|
||||
module specification, the '.js' suffix is optional.
|
||||
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ subdirectories will be ...
|
|||
|
||||
... The `plugins`, `modules` and `lib` directories each serve a different purpose.
|
||||
|
||||
### The `plugins` directory
|
||||
### The plugins directory
|
||||
|
||||
At server startup the ScriptCraft Java plugin is loaded and begins
|
||||
automatically loading and executing all of the modules (javascript
|
||||
|
|
@ -93,7 +93,7 @@ javascript modules in the `js-plugins` directory, then put them in the
|
|||
* Automatically loaded and run at server startup.
|
||||
* Anything exported by modules becomes a global variable.
|
||||
|
||||
### The `modules` directory
|
||||
### The modules directory
|
||||
|
||||
The module directory is where you should place your modules if you
|
||||
don't want to export globally. In javascript, it's considered best
|
||||
|
|
@ -108,7 +108,7 @@ between modules in the `plugins` directory and modules in the
|
|||
automatically loaded and exported in to the global namespace at server
|
||||
startup, modules in the `modules` directory are not.
|
||||
|
||||
### The `lib` directory
|
||||
### The lib directory
|
||||
|
||||
Modules in the `lib` directory are for use by ScriptCraft and some
|
||||
core functions for use by module and plugin developers are also
|
||||
|
|
@ -128,7 +128,7 @@ As of December 24 2013, the `scriptcraft/plugins` directory has the following su
|
|||
* alias - The alias plugin/module
|
||||
* home - The home module - for setting homes and visiting other homes.
|
||||
|
||||
## Free Variables
|
||||
## Core Module: functions
|
||||
|
||||
ScripCraft provides some functions which can be used by all plugins/modules...
|
||||
|
||||
|
|
|
|||
|
|
@ -44,9 +44,8 @@ Only ops users can run the classroom.allowScripting() function - this is so that
|
|||
don't try to bar themselves and each other from scripting.
|
||||
|
||||
***/
|
||||
var _canScript = false;
|
||||
|
||||
exports.classroom = {
|
||||
var _store = {enableScripting: false};
|
||||
var classroom = plugin("classroom", {
|
||||
allowScripting: function (/* boolean: true or false */ canScript) {
|
||||
/*
|
||||
only operators should be allowed run this function
|
||||
|
|
@ -67,12 +66,16 @@ exports.classroom = {
|
|||
});
|
||||
});
|
||||
}
|
||||
_canScript = canScript;
|
||||
}
|
||||
};
|
||||
_store.enableScripting = canScript;
|
||||
},
|
||||
store: _store
|
||||
}, true);
|
||||
|
||||
exports.classroom = classroom;
|
||||
|
||||
events.on('player.PlayerLoginEvent', function(listener, event) {
|
||||
var player = event.player;
|
||||
if (classroom.canScript){
|
||||
if (classroom.store.enableScripting){
|
||||
player.addAttachment(__plugin, "scriptcraft.*", true);
|
||||
}
|
||||
}, "HIGHEST");
|
||||
|
|
|
|||
Reference in New Issue