scriptcraft/contributing.md

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.