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/contributing.md

120 lines
4.5 KiB
Markdown

# Status
[![Travis Build Status](https://api.travis-ci.org/walterhiggins/ScriptCraft.png)](http://travis-ci.org/walterhiggins/ScriptCraft)
# 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.