From 32c01a088c7beb29c37695fd556839829289d504 Mon Sep 17 00:00:00 2001 From: DemiPixel Date: Thu, 10 Dec 2015 12:27:17 -0800 Subject: [PATCH] Improve contribute.md --- doc/CONTRIBUTE.md | 104 +++++++++++++++++----------------------------- 1 file changed, 39 insertions(+), 65 deletions(-) diff --git a/doc/CONTRIBUTE.md b/doc/CONTRIBUTE.md index df0847a..1f93ccf 100644 --- a/doc/CONTRIBUTE.md +++ b/doc/CONTRIBUTE.md @@ -5,93 +5,67 @@ Directory architecture : * app.js: specific settings and actually start the server -* index.js: contain the generic server implementation -* lib/: contain the classes and functions used in the plugins - * serverPlugins/: server plugins that do things general to the server, - properties and method are added to the server object in them - * playerPlugins/: player plugins that do things for each player, properties and method are added to the player object in them +* dist/: Contains "compiled" code (go to current directory in console and type `gulp` to generate this) +* src/: Source files for the project +* src/index.js: contain the generic server implementation +* src/lib: contain the classes and functions used in the plugins + * plugins/: All of the default plugins made to simulate vanilla + * worldGeneraions/: Contains default world generations, however plugins can use their own -Structure of a server plugin: +## Structure of a plugin ```js -module.exports=inject; -function inject(serv) -{ - // add methods and properties to serv +// Each of these are called an "inject" because you're injecting properties, events, methods, or data into the objects + +module.exports.server = function(serv) { // Create your server events here + serv.spawnPoint = ...; + serv.on('...', ...); } -``` -Structure of a player plugin : - -```js -module.exports=inject; - -function inject(serv,player) -{ - // add methods and properties to player - // you can use serv, but you shouldn't add things to it here +module.exports.entity = function(entity, serv) { // Called whenever an entity is created, do NOT do serv.on here + entity.health = 10; // Start with 10 health out of 20 + entity.on('...', ...); + // serv.on('...', ...); NOOOO } + +module.exports.player = function(player, serv) { // Player is a type of entity (entity inject is called first) with added properties and functions + player.setXp(100); // Example of a property player entities have but not other entities + player.on(',,,', ...); + // serv.on('...', .– don't even think about it +} + ``` ## Logs and event In order to keep logging independent from the rest of the server and to let people react in other ways than logging, -server and player events should be emitting and the logging should only take place in response to these events -in log.js of playerPlugins or serverPlugins. +logging uses methods and events from `log.js`. These include `serv.log(message)` and `serv.emit('error', err)`. ## Creating external plugins -Create a new repo, which will be published to npm when ready to be used. +Create a new repo, which will be published to npm when ready to be used. Create a file (probably `index.js`) in which you use a similar format as above (module.exports.xxxx). -Create a file in which you put an inject function like this : +In these inject functions you can use everything documented in the [api.md](api.md). -```js -module.exports=init; +Let's say you called your module fs-flying-horses and you published it to npm. -function init(flying-squid) { - return inject; -} +Now people can use install your plugin by simply typing: -function inject(serv) -{ - // add methods and properties to serv -} -``` +```npm install fs-flying-horses``` -In the init function, you can use anything flying-squid provide -(see [index.js](https://github.com/mhsjlw/flying-squid/blob/master/index.js#L11)). +### Testing your Plugin -In the inject function you can use everything documented in the [api.md](api.md) to add functionalities to the serv object. +For your convenience, you can put your plugin inside /src/plugins. An example might look like: +- src/plugins/ + - myPluginName/ + - index.js + - package.json + - node_modules + - ... + - myPluginName2.js (direct files are allowed but are impossible to publish, so it's best only to use them for testing) -Let's say you called your module flying-horses and you published it to npm. - -Now people can use your plugin that way : - -```js -var flyingSquid = require('flying-squid'); -var flyingHorses = require('flying-horses')(flyingSquid); -var serv = flyingSquid.createMCServer(/* your options there */); -// install the plugin -flyingHorses(serv); -``` - -As explained in the first part of this file, flying-squid has 2 kinds of plugins: server plugins, and player plugins. -We've explained until now how to create a server plugin and to use it with flying-squid. - -Within the same module, you can also create a player plugin. Here is the code you need to add to do that: - -```js -serv.on("newPlayer",function(player){ - injectPlayer(serv,player); -}); - -function injectPlayer(serv,player) -{ - // add methods and properties to player - // you can use serv, but you shouldn't add things to it here -} -``` +## Conclusion In this document, we explained how to create a simple plugin with just one file, but you can cut your code in several files by having several inject function and putting them in different files, just like flying-squid does for its internal plugins.