4.5 KiB
Status
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.