View source for Sentry

{{Trait
| PICTURE      = Sentry.png
| AUTHOR      = aufdemrand, jrbudda
| NAME         = Sentry
| VERSION    = 0.9.0 8/31/2012
| CITIZENSBUILD  = 2.0 dev build #299
| DEVSTATUS    = InDev
| DEPENDS     =  None required, Vault and a permissions plugin suggested.
| DOWNLOADLINK  = https://github.com/downloads/jrbudda/Sentry/Sentry%200.9.0.zip
| DESCRIPTION  = Citizens NPCs that attack monsters and can be killed.
}}

'''Sentry''' is a Citizens 2.0 [[Characters|character trait]] that gives NPCs the ability to:
* Attack monsters, players, and groups automatically. 
* Kill, and be killed by, players, monsters, and the environment.
* Guard locations, paths, players, or other NPCs.
* Use ranged or melee weapons.
* Be configured with stats such as strength, armor, speed, and night vision.
* [[Sentry/Sentry and Denizen|Work with Denizen]] to create NPCs that run scripts upon death.

== Updates ==

{{scrollbox|
'''v. 0.9.0 beta''' 8/31/2012
* For the first time in 100 years, the venerated Order of the Stormcallers has descended from their monastery on the top of Mt. Creeperhorn. They have come to join their brethren in SentryCorps and share a century's worth of arcane secrets to push back the tide of evil sweeping the land!
** Wielding potent scrolls and ancient tomes the Stormcallers bring forth lightning to smite their foes!
** The Stormcallers have taught the Pyromancer brigade to focus their chi and summon more powerful Fire!
** The SentryCorp Ice Magi have learned to infuse their balls of ice with freezing power!


'''v. 0.8.9 beta''' 8/28/2012
*Fix target, ignore, guard, warning and greeting commands to properly handle spaces.
*Change damage event priority: All sentries should deal and receive damage independent of any PVP protection plugins, since they are not, by definition, players.

'''v. 0.8.8.2 beta''' 8/27/2012
*Removed upper limit on {{sentrystat|respawn}}.
*Removed upper limit on {{sentrystat|healrate}} to allow faster healing. Heal rate is still the number of seconds between heals of 1hp but all values between 0.0 and 1.0 are now valid. So a heal rate of 0.5 is 2hp per second. A healrate of 0.1 is 10hp per second. a healrate of 0.01 is 100hp per second. 
*Fixed error if vault not installed.
*Made Vault registration delayed for compatibility with slow perms systems.

'''v. 0.8.8.1 beta''' 8/23/2012
* Sentries take less knockback based on armor. Also honor the .5 second invulnerable period after hits that other Minecraft entities enjoy. This should make fighting them much more difficult and rewarding.
* Removed the upper limit on {{sentrystat|health}}, {{sentrystat|strength}}, and {{sentrystat|armor}}. This is for compatibility with other plugins. Vanilla craftbukkit users should still use 1-20 for health, and 0-10 for strength and armor.

'''v. 0.8.8 beta''' 8/21/2012
* Due to pending litigation, all Citizens SentryCorps personnel have been sent to Public Relations training. APPARENTLY some people were upset that Sentries were attacking people with no warning.
::Added commands warningrange, warning, greeting
::See [[#Warn/Greet]]
*Fixed sentries giving up on retaliation targets after a few seconds.
*Other bugfixes.

'''v. 0.8.7.1 beta''' 8/20/2012
* Fix group ignores. 
* Added valid target: entity:all 

'''v. 0.8.7 beta''' 8/20/2012
* Added command: ignore
* Added target entity:owner

'''v. 0.8.6 beta''' 8/20/2012
* Added Target Reassessment
::When Sentries have an active target, every few seconds they will glance over their shoulders at other possible targets and switch if one has gotten closer. Stab me in the back once, shame on you, stab me in the back twice, shame on me.
* Added Denizen Command: LIVE

'''v. 0.8.5.1 beta''' 8/19/2012
* Minor fixes to perms, info, debugging info.

'''v. 0.8.5 beta''' 8/17/2012
* Support for Factions. Use FACTION:FactionTag to target memebers of that faction.
* Added Towny Nation support. Use NATION:NationName to target memebers of that Towny Nation.

'''v. 0.8.4.1 beta''' 8/16/2012
* Last-second heals will no longer allow a sentry to jump back into the fray after death, naked.
* Sentries forget their target on death, shouldn't smack people nearby on respawn anymore.

'''v. 0.8.4 beta''' 8/15/2012
*<del> {{color|red|white| KNOWN ISSUE: Sentries with a single waypoint can cause VERY bad lag, either remove the single waypoint or make 2 waypoints until we can correct the issue.}}</del>
:::{{color|green|white|Corrected in Citizens2 build #288}}
*<del> {{color|red|white| KNOWN ISSUE: Human-type NPCs cannot path up stairs or half-blocks}}</del>
:::{{color|green|white|Corrected in Citizens2 build #291}}
* If a Sentry NPC is owned by 'server' anyone with the 'citizens.admin' permission can run sentry commands on it. (if they also have the required Sentry [[Sentry/Permissions|permissions)]]


'''v. 0.8.3 beta''' 8/15/2012
* Fix for group checking with some perms plugins.
* Default pathfinding range much larger.

'''v. 0.8.2 beta''' 8/15/2012
* Sentries will now take most forms of environmental damage:
::Armor will be applied against damage from Cacti and TNT.
::Sentries do not drown or take fall damage (yet)
::Sentries that die from the environment will still run [[Sentry/Sentry_and_Denizen#Scripted_Death|Scripted Death]] scripts if at least one player directly damaged them.


'''v. 0.8.1 beta''' 8/14/2012
* Changed arrow-cleanup method. Should work better.
* Small group permissions compatibility fix.

'''v. 0.8.0 beta''' 8/13/2012
* Built in [http://dev.bukkit.org/server-mods/towny-advanced/ Towny] support. (Thanks '''TerraNetworkOrg'''!)
:::Sentry does not require Towny, but if you use it you can add a "TOWN:TownName" target to your sentries and they will target players from that town.
* Added in a hack to periodically remove bugged arrows when no players are around. Hopefully this is temporary.

'''v. 0.7.9.2 beta''' 8/12/2012
* Fix Sentries not checking GROUP targets.
* Checks for world groups first then global groups if no world groups found. Should be compatible with more perms systems.
* Sentries will forget their attackers if they heal back to full health. (This only applies to [[Sentry/Sentry_and_Denizen#Scripted_Death|Scripted Deaths]])

'''v. 0.7.9.1 beta''' 8/12/2012
* Fix for doppelgangers on /citizens reload
* Sentries set to not drop equipment also don't drop EXP.

'''v. 0.7.9 beta''' 8/11/2012
* Added animations to projectile shot and healing. Added sound effect to blocked hits.
* Workaround for Ranged Sentries not pathing after respawn.

'''v. 0.7.8.1 beta''' 8/11/2012
* Fix for denizen change. Fixed 2 NPEs.

'''v. 0.7.8 beta''' 8/10/2012
* Full permissions system for each command in /sentry. See [[Sentry/Permissions|Permissions]]

'''v. 0.7.7.1 beta''' 8/10/2012
* Integration with [[Denizen]]. Now you can trigger scripts on a Sentry's death. Long, drawn-out, guilt-ridden death speeches are go. see [[Sentry/Sentry and Denizen|Sentry and Denizen]] for more info.
* Minor bugfixes.

'''v. 0.7.6 beta''' 8/8/2012
* Added command: healrate
* Sentries can now heal back health over time.

'''v. 0.7.5 beta''' 8/7/2012
* Added command: spawn
* All /sentry commands may now be run from the console.
* Sentry damage is now independent of the weapon equipped. Damage is now equal to the sentry's Strength. The default for new Sentries is 1. If you already have Sentries created be sure to set the Strength, the old default was 0.
* Lots of bugfixes to speed, pathing, guarding, damage, arrow physics.

'''v. 0.7.4.5 beta''' 8/7/2012
* Bugfixes all over.
* Bodyguards will no longer take damage from other bodyguards guarding the same target. (unless friendly fire is on... and if FF and Retaliate are both on.. they will attack and kill each other (merc's have a temper.))
* Bodyguards are more persistent. If you get separated from your guard move within its Range and it should start following you again. '''Remember where you parked your bodyguard!
* Known bugs: Sentries sometimes take multiple hits.. note sure if Sentry or Core C2 problem. Bodyguards may lose their target.
* TO DO: keep bodyguards from trying to stand on top of you and each other.

'''v. 0.7.4 beta''' 8/6/2012
* <del>{{color|red|white|known bug: cannot target individual hostile monster types, will fix soon}}</del>
* Added commands: respawn, guard, nightvision, friendlyfire.
* Archers have gone back to basic training and can now shoot moving targets with deadly accuracy.
* Arrows now a move little faster, archers have more range.
* Sentries can be set to not see targets in dark conditions. Sneaking makes players harder to see. Thief missions Go!
* Sentries can be set as bodyguards. (note this is not currently persistent and may have bugs)


'''v. 0.7.3 beta''' 8/4/2012
* Added command: attackrate
* Pyromancer sentries no longer shoot themselves in the face.
* Tweaked the projectile physics and firing system.
* Respawn fix and other bugfixes.

'''v. 0.7.2 beta''' 8/4/2012
* Removed ignore-cone, All Sentries now use Line-Of-Sight to select targets.
* Archers no longer stare at the spot of the last enemy.
* Code re-arrange.

'''v. 0.7.2 beta''' 8/4/2012
* Added commands: range
* Sentries ignore a cone of space directly below them. This is to stop archers from shooting at their feet.
* Fixed sentries being unable to target some mobs such as ghasts.
* Archers with targets out of range no longer drop arrows at their feet.

'''v. 0.7.1 beta''' 8/3/2012
* Added commands: info, armor, strength
* All combat (ranged, player-npc, npc-npc, mob-npc) goes through the same calculations for armor, strength, and critical hits.
* Sentry no longer creates a folder or config.yml. All options are stored within the Citizens saves.yml.
* More bugfixes and cleanup.

'''v. 0.7.0 beta''' 8/2/2012
* MC 1.3.1 Compatible
* Added commands: invincible, retaliate, drops, criticals
* Added ability to shoot bows and projectiles.
* Sentries respond to damage from arrows.
* Lots of bugfixes and minor updates.

'''v. 0.5.6 beta'''
* Now working with the new builds of C2.

'''v. 0.5.5 beta'''
* Fixed bugs.

'''v. 0.5 beta'''
* Added the ability to specify targets.
* Added the ability to set the Health and Speed of a Sentry.
* 'Stuck' Sentries now respawn after a while.
* Fixed the death handling.
* Fixed Sentries remembering their guard location on a restart.

'''v. 0.3 beta'''
* Added ability to kill the NPCs. Swords kill faster. Built-in chance of criticals, etc.
* Fixed targeting code, should be more efficient now.
* Implemented respawning sequence.

}}

==How to Use==
===Installation===
* Ensure Citizens2 and Vault are installed
* Download file. [[#top|See top of page]]
* Place Sentry.jar in your Plugins folder.
* Start Server


===Permissions===

See [[Sentry/Permissions|Sentry Permissions]]

===Commands===

All /sentry commands normally require a selected NPC. use /npc select # to do this.

'''Alternatively you may use {{color|blue|white|<code >/sentry # [command]  </code>}} to send a sentry command to a specified sentry without 
selecting it. # is the Sentry's npc id.

Example: <code>/sentry 3 add target entity:monster </code> will add the monsters target to sentry with npcID 3.

====Creation====
To create a sentry, use:

:'''<code>/npc create 'NPC Name' 
:'''/trait sentry 
</code> 

:or
:'''<code>/npc create 'NPC Name'  --trait sentry </code>


To place your sentry use:

:'''<code>/npc path</code>

And use the [[Waypoints]] editor to give your Sentry a place to stand, or a path to walk.


To equip you Sentry with weapons and armor use:

:'''<code>/npc equip</code>

And right click with the desired weapon or armor. See the [[#Combat]] section for a discussion of weapons and armor

If you would like the Sentry to respawn in a different place from where it was created. Move it using 

:'''<code>/npc tphere</code>

And then call

:'''<code>/sentry spawn</code>

====Targets====

Sentries have 2 lists: '''Targets''' and '''Ignores'''. These lists contain entities. Entities can be monsters, passive mobs, players, or player groups. Sentries look at all the possible entities they can see in their {{sentrystat|range}}, If it NOT on the '''Ignores''' list and IS on the '''Targets''' list, the Sentry will attack it. An entity cannot be seen if it is out of line-of-sight or if it is too dark for the Sentry's {{sentrystat|nightvision}}

*Melee Sentries will chase targets until the target is dead, has gotten out of {{sentrystat|range}}, or another valid target has gotten closer.
*Ranged Sentries do not follow targets, but will stay on their spot/path and fire at the target until it is dead, out of ''projectile''* range, or another valid target has gotten closer.

::<nowiki>*</nowiki>Note that projectile range is not the same as {{sentrystat|range}} (detection range). Projectiles have a fixed range depending on their type. Archers, for example, have a range of about 50 blocks on flat ground. Elevated sentries can hit targets farther away. Sentries that throw things have shorter range.

To add a target: 
:'''<code>/sentry target add {{color|red|white|[entity]}}</code>

To add an ignore: 
:'''<code>/sentry ignore add {{color|red|white|[entity]}}</code>

'''<code>{{color|red|white|[entity]}}</code>''' can be any of the following:
{| class="wikitable" style="text-align: left; width: 75%"
|entity:all|| All living things. (adding this to the Ignore list is the same as leaving the Target list empty.)
|-
|entity:owner|| The Sentry's npc Owner.
|-
|entity:Name || any [[Types|mob types]] with the name Name
|-
|entity:monster || All hostile mobs
|-
|entity:player|| All players and NPCS.
|-
|player:Name|| The player or NPC with the name Name
|-
|group:Name|| All members of permissions group Name. Sentries can be added to permission groups.
|-
|town:Name|| All members of [http://dev.bukkit.org/server-mods/towny-advanced/ Towny] town Name
|-
|nation:Name|| All members of [http://dev.bukkit.org/server-mods/towny-advanced/ Towny] nation Name
|-
|faction:Name|| All members of [http://dev.bukkit.org/server-mods/factions/ Factions] factiontag Name
|}

Examples: 
This will make the Sentry attack all players except those in the Admin group
<pre>
/sentry target add entity:player 
/sentry ignore add group:Admin
</pre>

This will make the Sentry attack anything that moves.. except sheep and the player named Bob Johnson.
<pre>
/sentry target add entity:all
/sentry ignore add entity:sheep
/sentry ignore add player:Bob Johnson
</pre>

To remove a target:
:'''<code>/sentry target remove [target]</code>

To remove a ignore:
:'''<code>/sentry ignore remove [entity]</code>


To view the target list:
:'''<code>/sentry target list</code>

To clear the ignore list:
:'''<code>/sentry ignore clear</code>

=====Warn/Greet=====
Sentries can optionally warn or greet Players that come nearby, letting the Player know if the Sentry is hostile or friendly. This is off by default. To turn it on set the {{sentrystat|WARNINGRANGE}} higher than 0. This is the number of blocks beyond the {{sentrystat|RANGE}} that the Sentry will look for Players to warn/greet. For example if the {{sentrystat|RANGE}} is 10 and the {{sentrystat|WARNINGRANGE}} is 5, Players 10-15 blocks away will be alerted to the Sentry's hostility.

The warning and greeting message can be customized for each Sentry. 

To set the warning message:
:'''<code>/sentry warning 'New Warning Message'></code>

To set the greetingmessage:
:'''<code>/sentry warning 'New Greeting Message'></code>

*<PLAYER> and <NPC> can be used in the message as a placeholder for the Player's name or Sentry's name.
*Setting either message to '' will disable that message.

====Guarding====
Sentries can be set as Lookouts or Bodyguards. Lookouts guard a location or path  (set with '''<code>/npc path</code>'''), Bodyguards follow around an assigned living target (player or NPC).

If a bodyguard is set to Retaliate, it will attack anything that attacks the assigned guard target or itself.

If a bodyguard is set for Friendly Fire it can accidentally damage and be damaged by its guard target.

To set a Sentry as a bodyguard for a target NPC or Player:
:'''<code>/sentry guard [Name] </code>

Note: The target must be within the Sentry's Range when the target is set.

To set the Sentry back to the default Lookout mode:
:'''<code>/sentry guard</code>

and use  '''<code>/npc path</code>''' to set waypoints.

====Stats====
Stats are Sentry settings that take a value and affect its performance.

To set a stat use:
:'''<code>/sentry [stat] [value]'''      
:Example: /sentry armor 5 </code>

To view the current value of a stat and get help:
:'''<code>/sentry [stat]'''        
:Example: /sentry range </code>

To view all the Sentry's stats, as well as current target, status, and guard target, use:
:'''<code>/sentry info </code>

{| class="wikitable" style="text-align: left; width: 100%"
|-
!  Stat ||  Default Value || Value Range || Notes
|-
| {{sentrystat|health}}|| 20 || 1-2000000 || The number of hit points the Sentry has. Normal players have 20.
|-
| {{sentrystat|armor}}|| 0 || 0-2000000 || This value is subtracted from all incoming damage. An armor of 10 makes the Sentry very hard to hurt. Armor items equipped on the Sentry have no effect on combat.
|-
| {{sentrystat|strength}}|| 1 || 0-2000000 || This is the damage the sentry does with each hit, regardless of weapon (or object) held.
|-
| {{sentrystat|range}}|| 10 || 1-100 || This is the '''detection''' range for the Sentry. High values may affect server performance. This is not the same as the projectile range, which is dictated by projectile type and the Sentry's elevation relative to the target.
|-
| {{sentrystat|speed}}|| 1.0 || 0.0-1.5 || This is the speed at which a sentry will move while pursuing a target. To set the normal path speed use /npc speed.
|-
| {{sentrystat|attackrate}}|| 2.0 || 0.0-30.0 || This is the number of seconds between projectile shots and has no effect if the Sentry uses a melee weapon. The minimum internal rate is 0.5 (twice a second).
|-
| {{sentrystat|healrate}}|| 0.0 || 0.0-300.0 || This is the number of seconds between heals of 1 point, values less than 1.0 are acceptable. Set to 0 to turn off healing.
|-
| {{sentrystat|nightvision}}|| 16 || 0-16 ||  This is how well the Sentry can see potential targets in the dark. A value of 16 means the sentry can see perfectly all the time. A value of 12 means a target is invisible below light level 4 (16-12) . A value of 6 means a target is invisible below light level 10 (16-6), etc. If the target is a Player and that player is sneaking, its effective light light level is cut in half, making it harder for the sentry to detect.
|-
| {{sentrystat|respawn}}|| 10 || -1-2000000|| When the sentry dies, this is the number of seconds after which it will respawn. Set to 0 to prevent normal respawn. Set to -1 and the Sentry will not respawn and be '''permanently''' destroyed on death.
|-
| {{sentrystat|warningrange}}|| 0 || 0-50|| The number of blocks beyond {{sentrystat|range}} the Sentry will look for Players to warn or greet. Set to 0 to disable warn/greet.
|-
|}

====Options====
Options are sentry settings that can be toggled on and off and affect its behavior.

:'''<code>/sentry [option]'''      
:Example: /sentry invincible </code>

To view all the Sentry's stats, options, current target, status, and guard target, use:
:'''<code>/sentry info </code>

{| class="wikitable" style="text-align: left; width: 100%"
|-
!  Option||  Default Value || Notes
|-
| {{sentrystat|drops}}|| False ||  If this is True the Sentry will drop his equipment and some EXP on death. 
|-
| {{sentrystat|invincible}}|| False  || If this is True the Sentry will not take any damage, be knocked back, or show a 'hurt' flash.
|-
| {{sentrystat|retaliate}}|| True ||  If this is True, the Sentry will attack to any living thing that attacks it. If the Sentry is acting as a bodyguard, it will also attack any living thing that attacks its guard target. 
|-
| {{sentrystat|criticals}}|| True || If this is true the Sentry will take critical hits and misses. If False, the normal damage is always applied.
|-
| {{sentrystat|friendlyfire}}|| False || If this is True the sentry can be damaged by and cause damage to any living thing. If this is False, the Sentry will not damage or receive damage from its guard target or any other Sentries guarding that target. Using {{sentrystat|friendlyfire}} and {{sentrystat|retaliate}} at the same time is highly not recommended, although hilarious.
|-
|}

===Combat===

Sentries can engage in rewarding combat with players, monsters, and even each other!

=====Equipment=====
*All armor is cosmetic from a combat standpoint, {{sentrystat|armor}} determines the damage reduction from attacks.
*The item a Sentry holds in its hand determines its attack type, but the amount of damage the Sentry does is determined by its {{sentrystat|strength}} 

The following items are usable by Sentrys
{| class="wikitable" style="text-align: left; width: 100%"
|-
!  Item || Type || Notes
|-
| BOW || Archer|| The 14th Archer Brigade ("Hawkeyes") of SentryCorps wield long bows and razor arrows. They can hit a chicken square in the nuggets from 50 meters on flat ground.
|-
| REDSTONE_TORCH || Pyromancer || The lowest power memebers of the 27th Pyromancer Brigade shoot small, non-inciendary fireballs from their wands.
|-
| TORCH || Pyromancer||  The elite of the Flaming 27th, these wizards shoot fireballs that set the land on fire.
|-
| BLAZE_ROD || Pyromancer|| Spoken of in only hushed whispers, this little-known squad of the 27th has learned to fire large, explosive fireballs. Life spawn is usually very short for these crazed pryomancers.
|-
| SNOWBALL || Ice Magi || The frosty brethren of the 88th Ice Magi Brigade ("Snowmen") throw snowballs which slow enemies on contract. Snowballs have a range of about 25 blocks on flat groud.
|-
| EGG || Bombadiers || The 3rd Brigade of Ovarian Bombardiers gets few recruits. Perhaps its the giant chicken suits they have to wear. Eggs have a range of about 25 blocks on flat ground.
|-
| POTION || Witch Doctor|| When not drunk on their own noxious brews, the 9th Witch Doctor Brigade can turn the tide of battle with a single potion. Potions have a range of about 25 blocks on flat ground. The Sentry will throw a splash version of whatever potion type it is equipped with.
|-
| PAPER|| Stormcaller|| The magic incantation written on their scrolls allows members of the 99th Stormcallers to strike targets with bolts of electricity. 
|-
| BOOK|| Stormcaller|| The elite of the 99th can call forth powerful lightning from the sky to smite multiple foes, using tomes of untold power. This lightning's damage is atmospheric and not affected by the Sentry's strength.
|-
|}

=====Dealing Damage=====

The damage dealt by a Sentry when attacking a target is equal to the sentry's {{sentrystat|strength}}.

Typically players have 20 health. By default a Sentry has 1 {{sentrystat|strength}} and therefore does 1 damage.

=====Receiving Damage=====

Sentries can receive damage from any source, just like a monster. If the Sentry is set to {{sentrystat|retaliate}}, it will target any living entity that attacks it, ignoring any current target.

If the Sentry is set to {{sentrystat|invincible}}, it takes NO damage or knockback at all!

If the Sentry has {{sentrystat|criticals}} turned on, any incoming damage is randomized resulting in a normal hit, a miss, or one of several degrees of critical hit. If the attacker is a player, a message is shown based on the type of hit. 

If the Sentry has {{sentrystat|armor}} > 0 the damage will be reduced by the amount of armor. If the damage is reduced to nothing, the attack results in a block. Blocked hits cause no damage but DO cause knockback!

=====Death=====

If the Sentry's health drops to 0. It dies.

If the Sentry is set to {{sentrystat|drops}} on death, when it dies it drops its equipment like a normal monster. Watch out for farmers!

After the {{sentrystat|respawn}} delay (default is 10 seconds) the Sentry will respawn. If the{{sentrystat|respawn}} is set to 0, the Sentry must be re spawned manually.

Lookouts will respawn at their spawn location, by default this is where they were created.

Bodyguards will respawn near their guard target.

===Advanced Usage===
For combining Sentry and Denizen for truly powerful interactions see [[Sentry/Sentry and Denizen|Sentry And Denizen]]

==Known caveats and upcoming features==

Using commands on a Sentry NPC while it is dead may cause errors. (/npc spawn is safe)

Using /citizens reload may break your sentries or waypoints.

Sentries may get lost or fall through the world.

Mob-type NPCs have some oddities since mc 1.3.1

==Suggestions==
Suggestions are, of course, always welcome! 
*Visit us in #citizens on [http://webchat.esper.net/?channels=citizens EsperNet].
*Bugs and suggestions can also be posted [[https://github.com/jrbudda/Sentry/issues Here]]

[[Category:Characters]]

{{NavBox}}