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