Sentry

Sentry

Author	aufdemrand, jrbudda
Version	0.7.6 8/8/2012
Citizens build	2.0 dev build #275
Other dependencies	Vault, and a permissions system
Download	Link
Description: Sentries are NPCs that can attack monsters, players, and groups automatically. They can be killed and configured with stats such as strength and armor. Sentries can use melee weapons or ranged projectiles.

Updates

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

~~known bug: cannot target individual hostile monster types, will fix soon~~
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.

Up next: Warning targeted Players.

How to Use

Installation

Ensure Citizens2 and Vault are installed
Download file. See top of page
Place Sentry.jar in your Plugins folder.
Start Server

Commands

Sentries are useful for guarding areas from intruders. Giving a Citizens NPC the Sentry trait will also make it killable.

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

Alternatively you may use /sentry # [command] to send a sentry command to a specified sentry without selecting it. # is the Sentry's npc id.

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

Creation

To create a sentry, use:

/npc create 'NPC Name'

then

/trait sentry

To place your sentry use:

/npc path

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:

/npc equip

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

/npc tphere

And then call

/sentry spawn

Targets

Sentries are on the constant lookout for targets. Targets can be monsters, passive mobs, players, or player groups.

Sentries look at all the possible targets they can see in range, and select the closest one.

A target cannot be seen if it is out of line-of-sight or if it is too dark for the Sentry's Night Vision.

Melee Sentries will chase targets until the target is dead or has gotten out of range.

Ranged Sentries do not follow targets, but will stay on their spot/path and fire at the target until it is dead or out of projectile range.

Note that detection range is not the same as projectile range. Projectiles have a fixed range depending on their type. Archers, for example, have a range of about 25 blocks on flat ground. Elevated sentries can hit targets farther away. Sentries that throw things have shorter range.

To add a target:

/sentry target add [target]

[target] can be entity:Name, entity:monster, entity:player, group:Name, or player:Name

entity:monster is a shortcut to make the Sentry attack all hostile mobs.

entity:player is a shortcut to make the Sentry attack all players.

player:SentryName can be used to attack another Sentry.

Example: /sentry target add player:Notch or /sentry target add entity:creeper

To remove a target:

/sentry target remove [target]

To view the target list:

/sentry target list

To clear the target list:

/sentry target clear

Guarding

Sentries can be set as Lookouts or Bodyguards. Lookouts guard a location or path, 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 itsself.

If a bodyguard is set for Friendly Fire it can accidentally hit and be hit by it's guard target.

To set a Sentry as a bodyguard for a target NPC or Player:

/sentry guard [Name]

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

To set the Sentry back to the default Lookout mode:

/sentry guard

Stats

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

To set a stat use:

/sentry [stat] [value]

Example: /sentry armor 5

To view the current value of a stat and get help:

/sentry [stat]

Example: /sentry range

To view all the Sentry's stats, as well as current target, status, and guard target, use:

/sentry info

Stat	Default Value	Value Range	Notes
HEALTH	20	1-20	The number of hit points the Sentry has. Normal players have 20.
ARMOR	0	0-10	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.
STRENGTH	1	0-10	This is the damage the sentry does with each hit, regardless of weapon (or object) held.
RANGE	10	1-100	This is the detection range for the Sentry. High values may affect server performance.
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).
HEALRATE	0.0	0.0-300.0	This is the number of seconds between heals of 1 point. The minimum internal rate is 0.5 (twice a second). Set to 0 to turn off healing.
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.
RESPAWN	10	-1-300	When the sentry dies, this is the number of seconds after which it will respawn. If this value is set to -1 the Sentry will not respawn and be permanently destroyed.

Options

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

/sentry [option]

Example: /sentry invincible

To view all the Sentry's stats, options, current target, status, and guard target, use:

/sentry info

Option	Default Value	Notes
DROPS	False	If this is True the Sentry will drop his equipment on death.
INVINCIBLE	False	If this is True the Sentry will not take any damage, be knocked back, or show a 'hurt' flash.
RETAILIATE	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.
CRITICALS	True	If this is true the Sentry will take critical hits and misses. If False, the normal damage is always applied.
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 FRIENDLYFIRE and 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

A Sentry should be equipped with a weapon to make it look right, but any hand held item can be used.

Sentries equipped with a Bow, Blaze Rod, Egg, or Snowball become RANGED sentries. and will fire projectiles at the target:

Archers have a range of about 50 blocks on flat ground, more when elevated.

Bombadiers have a range of about half that of Archers.

Pyromancers have.. pretty much an unlimited range, be very careful with pyromancers.

All armor and weapons are cosmetic from a combat standpoint. The amount of damage the Sentry gives and takes is determined by its STRENGTH and ARMOR.

Dealing Damage

The damage dealt by a Sentry when attacking a target is equal to the sentry's STRENGTH.

Typically players have 20 health. By default a Sentry has 1 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 RETALIATE, it will target any living entity that attacks it, ignoring any current target.

If the Sentry is set to INVINCIBLE, it takes NO damage or knockback at all!

If the Sentry has 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 ARMOR 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 DROP ITEMS on death, when it dies it drops its equipment like a normal monster. Watch out for farmers!

After a delay (default is 10 seconds) the Sentry will respawn.

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

Bodyguards will respawn near their guard target.

Advanced Usage

Sentry and Denizen

In Citizens 2 a single NPC can be multiple character types at the same time. This can lead to very powerful player interactions. Denizen, especially can create great gameplay. Here are 2 examples.

Criminal System

A few Sentry-Denizens can be used to create a town criminal systems.

Let's say you have an adventure server with a town called Hillside, populated by shopkeepers, guards, blacksmiths, etc.

Create a number of Sentry-Denizens to act as your town's police force. Set each Sentry to target a GROUP called Hillside_Enemy.

Now create a Denizen script to handle player aggression. Let's use a 3-strike system. This same script will execute for all NPCs to which it is assigned, and the player's step will be the same for each, so we can use 1 script with multiple steps, one for each strike. Here's an example:

Hillside Aggression Script and Assignments

---- assignments.yml ----

Denizens:                         
  'Town Guard':                        
    Interact Scripts:        
      (other assignments)           
    - 10 ^Hillside_Aggression

  'Shopkeeper Bob':                        
    Interact Scripts:      
      (other assignments)                     
    - 10 ^Hillside_Aggression

  'Mayor Steve':                        
    Interact Scripts:   
      (other assignments)                        
    - 10 ^Hillside_Aggression

---- script.yml ----
'Hillside_Aggression':
  Type: Trigger
  Requirements:
    Mode: All
    List:
      - -GROUP Hillside_Enemy
  Steps:
    1:
      Damage Trigger:
        Script:
        - CHAT "Hey, watch it or I'm calling the guards!"
        - ZAP
    2:
      Damage Trigger:
        Script:
        - CHAT "Stop it, troublemaker, or else!"
        - ZAP
    3:
      Damage Trigger:
        Script:
        - CHAT "HELP! HELP! I'm being attacked!"
        - EXECUTE ASSERVER 'permissions player addgroup <PLAYER> Hillside_Enemy'
        - NARRATE 'You are now an enemy of Hillside.'  
        - ZAP 1

You can see we've assigned the script "Hillside_Aggression" to all NPCs named Town Guard, Shopkeeper Bob, or Mayor Steve.

If a player attacks any of these NPCs, they will receive a warning message and move on to the next step, if they get to step 3, they get put in the Sentry hostile group Hillside_Enemy.

Bonus: If the shopkeeper and mayor are set as Sentries too, they will defend themselves! (turn retaliate off, so they don't attack immediately)

The final step resets the script to step 1, but will not run so long as the player is a member of Hillside_Enemy.

This is just a basic example and can be expanded in any number of ways, using the commands in Denizen you could:

- forgive the player after a period of time (remove the player from the hillside_enemy group)

- Create a quest for the player to earn forgiveness.

- Create hostility in other towns if harassment of Hillside continues.

- etc etc etc.

Hire-able Bodyguards

So you're getting your butt kicked on your adventure server, wouldn't it be nice to spend some of that hard-earned emerald on a dude who will watch your back for you? Now you can!

Let's see how we can use Denizen to make hire-able bodyguards.

Mercenary Leader Script and Assignment

---- assignments.yml ----

Denizens:                         
  'Mercenary Leader':                        
    Interact Scripts:          
    - 10 'Hire a Guard'
    Texts: 
      No Requirements Met: "Come back when you have some money and we'll talk."

---- script.yml ----

'Hire a Guard':
  Type: Trigger
  Requirements:
    Mode: All
    List:
      - MONEY 500
  Steps:
    1:
      Click Trigger:
        Script:
        - CHAT "You look like you could use some help out there. $500 will get you one of my boys."
        - HINT
      Chat Trigger:
       '1'
          Trigger: /Yes/, I am weak and need protecting.
          Script:
          - CHAT "Okay then, nice doin' business with ya"
          - TAKE MONEY QTY:500
          - EXECUTE ASNPC "npc create '<PLAYER>s Bodyguard'"
          - EXECUTE ASNPC "trait sentry"
          - ^EXECUTE ASNPC "sentry guard <PLAYER>"
          - ^EXECUTE ASNPC "sentry strength 2"
          - ^EXECUTE ASNPC "sentry respawn -1"  #Note this means when the bodyguard dies, he's gone for good.
       '2'
          Trigger: /No/, I can handle myself!
          Script:
            - CHAT "Not my fault if you wind up dead, kid."

Here we have a single NPC named 'Mercenary Leader'. Locate him somewhere convenient. Depending your server's permission system you may need to pretend Mercenary Leader is player and grant him access to to /npc and /sentry commands. (need to test)

In this simple example we've given him one script with the requirement the Player has 500 economy money. We also gave him a default text telling the player to come back when he has more. You could expand on this with another script, but it's good enough for now.

If the player has the moolah, when he right clicks, the Merc will ask him if he wants a bodyguard. If the player answers yes. the NPC will use server commands to create a Sentry and assign it to the Player. In this example the Sentry's RESPAWN is set to -1 meaning if the bodyguard dies, its dead for good and the player needs to buy another one.

That's all there is too it. You could expand on this in many ways:

Higher prices for bodyguards with better stats.
Limit player to one guard at a time.
Give ranged or melee guards.
Make the bodyguard a Denizen as well and respond to player commands.

Known caveats and upcoming features

Using /citizens reload may break your sentries or waypoints.

Sentries may get lost or fall through the world.

Suggestions

Suggestions are, of course, always welcome! Visit us in #citizens on EsperNet.

Quick Navigation
Usage	Installation · Frequently Asked Questions · Commands · Editors · Characters · API ·
Configuration	Configuration · Text Syntax · Permissions · Waypoints · Data Storage