Stargate/README

=============
 Description
=============
This is a port of the Stargate plugin from hMod by Dinnerbone.
Create gates that allow for instant-teleportation between large distances. Gates can be always-open, or triggered, they can be hidden, or accessible to everybody, they can share a network, or they can be split into clusters.
This port will import your existing locations.dat file from the hMod Stargate plugin!
iConomy support added back in, only costs are create, destroy and use.

=============
 Permissions
=============
stargate.use -- Allow use of all gates linking to any world in any network (Override ALL network/world permissions. Set to false to use network/world specific permissions)
  stargate.world -- Allow use of gates linking to any world
    stargate.world.{world} -- Allow use of gates with a destination in {world}. Set to false to disallow use.
  stargate.network -- Allow use of gates on all networks
    stargate.network.{network} -- Allow use of all gates in {network}. Set to false to disallow use.

stargate.option -- Allow use of all options
  stargate.option.hidden -- Allow use of 'H'idden
  stargate.option.alwayson -- Allow use of 'A'lways-On
  stargate.option.private -- Allow use of 'P'rivate
  stargate.option.free -- Allow use of 'F'ree
  stargate.option.backwards -- Allow use of 'B'ackwards
  stargate.option.show -- Allow use of 'S'how
  
stargate.create -- Allow creating gates on any network (Override all create permissions)
  stargate.create.personal -- Allow creating gates on network {playername}
  stargate.create.network -- Allow creating gates on any network
    stargate.create.network.{networkname} -- Allow creating gates on network {networkname}. Set to false to disallow creation on {networkname}

stargate.destroy -- Allow destruction gates on any network (Orderride all destroy permissions)
  stargate.destroy.personal -- Allow destruction of gates owned by user only
  stargate.destroy.network -- Allow destruction of gates on any network
    stargate.destroy.network.{networkname} -- Allow destruction of gates on network {networkname}. Set to false to disallow destruction of {networkname}

stargate.free -- Allow free use/creation/destruction of gates
  stargate.free.use -- Allow free use of Stargates
  stargate.free.create -- Allow free creation of Stargates
  stargate.free.destroy -- Allow free destruction of Stargates
  
stargate.admin -- Allow all admin features (Hidden/Private only so far)
  stargate.admin.private -- Allow use of Private gates not owned by user
  stargate.admin.hidden -- Allow access to Hidden gates not ownerd by user

=============
Default Permissions
=============
stargate.use -- Everyone
stargate.create -- Op
stargate.destroy -- Op
stargate.option -- Op
stargate.free -- Op
stargate.admin -- Op

=============
Instructions
=============
Building a gate:
    OO 
   O  O - These are Obsidian blocks. You need 10.
   O  O - Place a sign on either of these two blocks of Obsidian.
   O  O
    OO

Sign Layout:
 - Line 1: Gate Name (Max 12 characters)
 - Line 2: Destination Name [Optional] (Max 12 characters, used for fixed-gates only)
 - Line 3: Network name [Optional] (Max 12 characters)
 - Line 4: Options [Optional] :
 			'A' for always-on fixed gate
 			'H' for hidden networked gate
 			'P' for a private gate
 			'F' for a free gate
 			'B' is for a backwards facing gate (You will exit the back)
 			'S' is for showing an always-on gate in the network list

Options:
The options are the single letter, not the word. So to make a private hidden gate, your 4th line would be 'PH'.

Using a gate:
 - Right click the sign to choose a destination.
 - Right click the button to open up a portal.
 - Step through.

Fixed gates:
 - Fixed gates go to only one set destination.
 - Fixed gates can be linked to other fixed gates, or normal gates. A normal gate cannot open a portal to a fixed gate however.
 - To create a fixed gate, specify a destination on the second line of the stargate sign.
 - Set the 4th line of the stargate sign to "A" to enable an always-open fixed gate.

Gate networks:
 - Gates are all part of a network, by default this is "central".
 - You can specify (and create) your own network on the third line of the sign when making a new gate.
 - Gates on one network will not see gates on the second network, and vice versa.
 - Gates on different worlds, but in the same network, will see eachother.
 
Hidden Gates:
 - Hidden gates are like normal gates, but only show on the destination list of other gates under certain conditions.
 - A hidden gate is only visible to the creator of the gate, or somebody with the stargate.hidden permission.
 - Set the 4th line of the stargate sign to 'H' to make it a hidden gate.
 
iConomy Support:
 The latest version of Stargate has support for iConomy. Gate creation, destruction and use can all have different costs associated with them. You can also define per-gate layout costs. The default cost is assigned in the config.yml file, while the per-gate costs re defined in the .gate files. To define a certain cost to a gate just add these lines to your .gate file:
usecost=5
destroycost=5
createcost=5
toowner=true

==============
Custom Gate Layout
==============
You can create as many gate formats as you want, the gate layouts are stored in plugins/Stargate/gates/
The .gate file must be laid out a specific way, the first lines will be config information, and after a blank line you will lay out the gate format. Here is the default nether.gate file:

portal-open=90
portal-closed=0
X=49
-=49

 XX 
X..X
-..-
X*.X
 XX 

portal-open/closed are used to define the material in the gate when it is open or closed. 
"X" and "-" are used to define block "types" for the layout (Any single-character can be used, such as "#").
In the gate format, you can see we use "X" to show where obsidian must be, "-" where the controls (Button/sign) are.
You will also notice a "*" in the gate layout, this is the "exit point" of the gate, the block at which the player will teleport in front of.
As of version 0.5.5 you can supply block data in the format
X=35:15
Which would only allow black wool. If no data is supplied any version of a block will work (Any color of wool for example)
 
==============
Configuration
==============
default-gate-network - The default gate network
portal-folder - The folder your portal databases are saved in
gate-folder - The folder containing your .gate files
destroyexplosion - Whether to destroy a stargate with explosions, or stop an explosion if it contains a gates controls.
useiconomy - Whether or not to use iConomy
createcost - The cost to create a stargate
destroycost - The cost to destroy a stargate (Can be negative for a "refund"
usecost - The cost to use a stargate
chargefreedestination - Enable to allow free travel from any gate to a free gate
freegatesgreen - Enable to make gates that won't cost the player money show up as green
toowner - Whether the money from gate-use goes to the owner or nobody
maxgates - If non-zero, will define the maximum amount of gates allowed on any network.

debug - Whether to show massive debug output
permdebug - Whether to show massive permission debug output

=======================
 Message Customization
=======================
As of 0.6.5 it is possible to customize all of the messages Stargate displays, including the [Stargate] prefix. You can find the strings in plugins/Stargate/lang/en.txt. 
If a string is removed, or left blank, it will not be shown when the user does the action associated with it.
There are three special cases when it comes to messages, these are:
ecoDeduct=Spent %cost%
ecoRefund=Redunded %cost%
ecoObtain=Obtained %cost$ from Stargate %portal%

As you can see, these three strings have variables in them. These variables are fairly self-explanatory.
The full list of strings is as follows:
prefix=[Stargate] 
teleportMsg=Teleported
destroyMsg=Gate Destroyed
invalidMsg=Invalid Destination
blockMsg=Destination Blocked
denyMsg=Access Denied
destEmpty=Destination List Empty

ecoDeduct=Deducted %cost%
ecoRefund=Redunded %cost%
ecoObtain=Obtained %cost$ from Stargate %portal%
ecoInFunds=Insufficient Funds

createMsg=Gate Created
createNetDeny=You do not have access to that network
createPersonal=Creating gate on personal network
createNameLength=Name too short or too long.
createExists=A gate by that name already exists
createFull=This network is full
createWorldDeny=You do not have access to that world
createConflict=Gate conflicts with existing gate


=============
  Changes
=============
[Version 0.6.5]
 - Moved printed message config to a seperate file
 - Added permdebug option
 - Hopefully fix path issues some people were having
 - Fixed iConomy creation cost
 - Added 'S'how option for Always-On gates
[Version 0.6.4]
 - Fixed iConomy handling
[Version 0.6.3]
 - Fixed (Not Connected) showing on inter-world gate loading
 - Added the ability to negate Network/World permissions (Use, Create and Destroy)
 - Fixed Lockette compatibility
 - More stringent verification checks
[Version 0.6.2]
 - Fixed an issue with private gates
 - Added default permissions
[Version 0.6.1]
 - Stop destruction of open gates on startup
[Version 0.6.0]
 - Completely re-wrote Permission handling (REREAD/REDO YOUR PERMISSIONS!!!!!!!!)
 - Added custom Stargate events (See Stargate-DHD code for use)
 - Fixed portal event cancellation
 - Umm... Lots of other small things.
[Version 0.5.5]
 - Added 'B'ackwards option
 - Fixed opening of gates with a fixed gate as a destination
 - Added block metadata support to gates
[Version 0.5.1]
 - Take into account world/network restrictions for Vehicles
 - Properly teleport empty vehicles between worlds
 - Properly teleport StoreageMinecarts between worlds
 - Take into account vehicle type when teleporting
[Version 0.5.0]
 - Updated the teleport method
 - Remove always-open gates from lists
 - Hopefully stop Stargate and Nether interference
[Version 0.4.9]
 - Left-click to scroll signs up
 - Show "(Not Connected)" on fixed-gates with a non-existant destination
 - Added "maxgates" option
 - Removed debug message
 - Started work on disabling damage for lava gates, too much work to finish with the current implementation of EntityDamageByBlock
[Version 0.4.8]
 - Added chargefreedestination option
 - Added freegatesgreen option
[Version 0.4.7]
 - Added debug option
 - Fixed gates will now show in the list of gates they link to.
 - iConomy no longer touched if not enabled in config
[Version 0.4.6]
 - Fixed a bug in iConomy handling.
[Version 0.4.5]
 - Owner of gate now isn't charged for use if target is owner
 - Updated for iConomy 5.x
 - Fixed random iConomy bugs
[Version 0.4.4]
 - Added a check for stargate.network.*/stargate.world.* on gate creation
 - Check for stargate.world.*/stargate.network.* on gate entrance
 - Warp player outside of gate on access denied
[Version 0.4.3]
 - Made some errors more user-friendly
 - Properly take into account portal-closed material
[Version 0.4.2]
 - Gates can't be created on existing gate blocks
[Version 0.4.1]
 - Sign option permissions
 - Per-gate iconomy target
 - /sg reload command
 - Other misc fixes
[Version 0.4.0]
 - Carts with no player can now go through gates.
 - You can set gates to send their cost to their owner.
 - Per-gate layout option for "toOwner".
 - Cleaned up the iConomy code a bit, messages should only be shown on actual deduction now.
 - Created separate 'stargate.free.{use/create/destroy}' permissions.
[Version 0.3.5]
 - Added 'stargate.world.*' permissions
 - Added 'stargate.network.*' permissions
 - Added 'networkfilter' config option
 - Added 'worldfilter' config option
[Version 0.3.4]
 - Added 'stargate.free' permission
 - Added iConomy cost into .gate files
[Version 0.3.3]
 - Moved sign update into a schedule event, should fix signs
[Version 0.3.2]
 - Updated to latest RB
 - Implemented proper vehicle handling
 - Added iConomy to vehicle handling
 - Can now set cost to go to creator on use
[Version 0.3.1]
 - Changed version numbering.
 - Changed how plugins are hooked into.
[Version 0.30]
 - Fixed a bug in iConomy checking.
[Version 0.29]
 - Added iConomy support. Currently only works with iConomy 4.4 until Niji fixes 4.5
 - Thanks @Jonbas for the base iConomy implementation
[Version 0.28]
 - Fixed an issue with removing stargates during load
[Version 0.27]
 - Fixed portal count on load
[Version 0.26]
 - Added stargate.create.personal for personal stargate networks
 - Fixed a bug with destroying stargates by removing sign/button
[Version 0.25]
 - Fixed a bug with worlds in subfolders
 - Fixed gates being destroyed with explosions
 - Added stargate.destroy.owner
[Version 0.24]
 - Fixed a loading bug in which invalid gates caused file truncation
[Version 0.23]
 - Added a check to make sure "nethergate.gate" exists, otherwise create it
[Version 0.22]
 - Fixed multi-world stargates causing an NPE
[Version 0.21]
 - Code cleanup
 - Added a few more errors when a gate can't be loaded
 - Hopefully fixed path issue on some Linux installs
[Version 0.20]
 - Fixed the bug SIGN_CHANGE exception when using plugins such as Lockette
[Version 0.19]
 - Set button facing on new gates, fixes weirdass button glitch
 - Beginning of very buggy multi-world support
[Version 0.18]
 - Small permissions handling update.
[Version 0.17]
 - Core GM support removed, depends on FakePermissions if you use GM.
[Version 0.16]
 - Fixed Permissions, will work with GroupManager, Permissions 2.0, or Permissions 2.1
 - Left-clicking to activate a stargate works again
[Version 0.15]
 - Built against b424jnks -- As such nothing lower is supported at the moment.
 - Moved gate destruction code to onBlockBreak since onBlockDamage no longer handles breaking blocks.
 - Removed long constructor.
[Version 0.14]
 - Fixed infinite loop in fixed gates.
 - Fixed gate destination will not open when dialed into.
[Version 0.13]
 - Fixed gates no longer show in destination list.
[Version 0.12]
 - Implemented fixed destination block using * in .gate file. This is the recommended method of doing an exit point for custom gates, as the automatic method doesn't work in a lot of cases.
 - Split networks up in memory, can now use same name in different networks. As a result, fixed gates must now specify a network.
 - Added the ability to have a private gate, which only you can activate. Use the 'P' option to create.
 - Fixed but not AlwaysOn gates now open the destination gate.
 - Fixed gates now show their network. Existing fixed gates are added to the default network (Sorry! It had to be done)
[Version 0.11]
 - Fuuuu- Some code got undid and broke everything. Fixed.
[Version 0.10]
 - Hopefully fixed the "No position found" bug.
 - If dest > origin, any blocks past origin.size will drop you at dest[0]
 - Switched to scheduler instead of our own thread for closing gates and deactivating signs
 - No longer depend on Permissions, use it as an option. isOp() used as defaults.
[Version 0.09]
 - Gates can now be any shape 
[Version 0.08]
 - Gates can now consist of any material.
 - You can left or right click the button to open a gate
 - Gates are now initialized on sign placement, not more right clicking!
[Version 0.07]
 - Fixed where the default gate is saved to.
[Version 0.06]
 - Forgot to make gates load from new location, oops
[Version 0.05]
 - Moved Stargate files into the plugins/Stargate/ folder
 - Added migration code so old gates/portals are ported to new folder structure
 - Create default config.yml if it doesn't exist
 - Fixed removing a gate, it is now completely removed
[Version 0.04]
 - Updated to multi-world Bukkit
[Version 0.03]
 - Changed package to net.TheDgtl.*
 - Everything now uses Blox instead of Block objects
 - Started on vehicle code, but it's still buggy