diff --git a/docs/API-Reference.md b/docs/API-Reference.md index 3316238..64fcc07 100644 --- a/docs/API-Reference.md +++ b/docs/API-Reference.md @@ -435,9 +435,12 @@ Walter Higgins * [The slash() function](#the-slash-function) * [Sounds Module](#sounds-module) * [Usage (Bukkit) :](#usage-bukkit-) - * [Teleport Module](#teleport-module) + * [Spawn Module](#spawn-module) * [Parameters](#parameters) * [Example](#example-2) + * [Teleport Module](#teleport-module) + * [Parameters](#parameters-1) + * [Example](#example-3) * [Utilities Module](#utilities-module) * [utils.player() function](#utilsplayer-function) * [utils.world( worldName ) function](#utilsworld-worldname--function) @@ -492,7 +495,7 @@ Walter Higgins * [Administration options](#administration-options) * [NumberGuess mini-game:](#numberguess-mini-game) * [Description](#description-1) - * [Example](#example-3) + * [Example](#example-4) * [Cow Clicker Mini-Game](#cow-clicker-mini-game) * [How to Play](#how-to-play) * [Rules](#rules) @@ -5289,6 +5292,31 @@ In addition, a play function is provided for each possible sound using the follo sounds.villagerNo(); // plays VILLAGER_NO sound for all players online. These methods are provided for convenience to help beginners explore sounds using TAB completion. +## Spawn Module + +Provides a single function to 'spawn' an entity at a given location. + +### Parameters + + * entityType - The type of entity to spawn. This can be a string (see entities module for reference) or a framework-specific object type (see https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html). A list of [all possible entities][ents] functions (equivalent to the EntityType enum). + + * location - where the entity should be spawned. + +[ents]: #entities-module + +### Example + +Using the entities module as a helper, spawn a new polar bear at the world's default spawn location: + +```javascript +var entities = require('entities'), + spawn = require('spawn'); +... +var spawnLocation = world.spawnLocation; +spawn(entities.polar_bear(), spawnLocation); +``` + +This module is in turn used by the Drone's `spawn()` method and the `jsp spawn` command. String class extensions ----------------------- The following chat-formatting methods are added to the javascript String class.. @@ -7303,7 +7331,14 @@ The following functions are provided: ## Entities module -The Entities module provides a suite of functions - one for each possible entity type. +The Entities module provides a suite of functions - one for each possible entity type. +It acts as a helper or enumerated module to assist in use with the `spawn` module and command. +This module is useful for TAB-completion at the in-game prompt. + +When each function is called with no parameters, it will return the appropriate EntityType object. +For example `entities.polar_bear()` will return an `EntityType.POLAR_BEAR` object. + +When each function is called with a single parameter - an entity - the entity's type will be compared and return true or false. ### Usage diff --git a/src/docs/js/generateEntitiesDoc.js b/src/docs/js/generateEntitiesDoc.js index 5679d2e..f24e368 100644 --- a/src/docs/js/generateEntitiesDoc.js +++ b/src/docs/js/generateEntitiesDoc.js @@ -6,7 +6,14 @@ var out = java.lang.System.out, var content = [ '', '## Entities module', - 'The Entities module provides a suite of functions - one for each possible entity type.', + 'The Entities module provides a suite of functions - one for each possible entity type. ', + 'It acts as a helper or enumerated module to assist in use with the `spawn` module and command. ', + 'This module is useful for TAB-completion at the in-game prompt. ', + '', + 'When each function is called with no parameters, it will return the appropriate EntityType object. ', + 'For example `entities.polar_bear()` will return an `EntityType.POLAR_BEAR` object. ', + '', + 'When each function is called with a single parameter - an entity - the entity\'s type will be compared and return true or false. ', '', '### Usage', '', diff --git a/src/main/js/modules/spawn.js b/src/main/js/modules/spawn.js index 088f437..471d9d5 100644 --- a/src/main/js/modules/spawn.js +++ b/src/main/js/modules/spawn.js @@ -1,16 +1,39 @@ /*global require, module, __plugin, Packages*/ 'use strict'; var entities = require('entities'); +/************************************************************************ +## Spawn Module +Provides a single function to 'spawn' an entity at a given location. + +### Parameters + + * entityType - The type of entity to spawn. This can be a string (see entities module for reference) or a framework-specific object type (see https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html). A list of [all possible entities][ents] functions (equivalent to the EntityType enum). + + * location - where the entity should be spawned. + +[ents]: #entities-module + +### Example + +Using the entities module as a helper, spawn a new polar bear at the world's default spawn location: + +```javascript +var entities = require('entities'), + spawn = require('spawn'); +... +var spawnLocation = world.spawnLocation; +spawn(entities.polar_bear(), spawnLocation); +``` + +This module is in turn used by the Drone's `spawn()` method and the `jsp spawn` command. +***/ module.exports = function(entityType, location){ var entityTypeFn; if (typeof entityType === 'string'){ entityTypeFn = entities[entityType.toLowerCase()]; entityType = entityTypeFn(); } - if (typeof entityType === 'function'){ - entityType = entityType(); - } var world = location.world; if (__plugin.bukkit){ world.spawnEntity( location, entityType);