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

updating docs for module release

Browse source
This commit is contained in:
walterhiggins 2013-12-24 22:47:57 +00:00
parent 60de2ec28a
commit 82f1928628
7 changed files with 887 additions and 760 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
README.md
View file

@ -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

1501
docs/API-Reference.md
View file

File diff suppressed because it is too large Load diff

60
docs/YoungPersonsGuideToProgrammingMinecraft.md
View file

@ -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.

8
src/docs/javascript/generateApiDocs.js
View file

@ -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/
]));

5
src/main/javascript/lib/require.js
View file

@ -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.

8
src/main/javascript/lib/scriptcraft.js
View file

@ -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...

17
src/main/javascript/plugins/classroom/classroom.js
View file

@ -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");