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)
|
|
|
|
|
2014-01-13 22:56:21 +01:00
|
|
|
# Notes for Contributors
|
|
|
|
|
|
|
|
This project uses a Maven-like directory structure...
|
|
|
|
|
|
|
|
src +
|
|
|
|
main +
|
|
|
|
java +
|
|
|
|
net +
|
|
|
|
walterhiggins +
|
|
|
|
scriptcraft +
|
|
|
|
ScriptCraftPlugin.java
|
|
|
|
|
2014-01-30 01:03:07 +01:00
|
|
|
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)
|
2014-01-13 22:56:21 +01:00
|
|
|
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.
|
|
|
|
|
2014-01-30 01:03:07 +01:00
|
|
|
## 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...
|
|
|
|
|
2014-01-13 22:56:21 +01:00
|
|
|
## 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.
|