Running the plugin for the first time will generate the default configuration file rsp.yml .

DOCUMENT UNDER CONSTRUCTION
For the old configuration page see: Configuration/old

rsp.yml

These sections desribe the options of the file rsp.yml, containing the basic configuration for the core plugin setup, including the "classic" features.

Basic Settings

The default configuration of RSP 0.12.0 can be seen here: http://dev.bukkit.org/paste/5426/
The section "generic-links" is unused, currently.

Accuracy and Performance

By default RSP is configured to allow for some inaccuracy (see below), in order to reach a better performance.

heuristic:
  lazy-dist: 5

heuristic.lazydist specifies the distance in blocks, that will force a re-checking of permdefs for a player. A higher lazy-dist will lead to less checking if a player is moving, at the cost of an inaccuracy of that many blocks. By default it is 5 to increase performance, if you need highest accuracy you can set it to 0, so that players will get re-checked if they move only one block.

player-cache:
  lifetime: 12345

player-cache.lifetime specifies a duration in milliseconds after which a player will be re-checked for permdefs, defaulting to roughly 12 seconds. If your server does not use any other permission manipulations you might set this to a very high value to avoid unnecessary re-checking. If you change permissions for a player, it might take this duration in milliseconds till the change is noticed by RSP. Setting this to a very low value is not recommended, due to this setting forcing a re-check of the regions etc. which will lead to a performance drop in average. After all you can use the stats settings to get stats about the processing time for RSP with different settings, RSP also allows for reloading the settings during runtime, so testing this should not be too difficult.

no-parking: false

With no-parking you can specify if player-data should be kept a while in order to save some time if players re-log after log-out. This can save some performance, because RSP might remove permission groups that are listed in "remove-exit" or "have-inside" for permdefs if a player logs out. If you have no-parking set to false, the player data will be kept and the removal will only be done on shutdown or if the player does not log in after roughly 5 minutes.

Permissions and Compatibility

permissions:
  save-at-all: false
  saving-period: 0
  save:
    on-check: false
    on-checkout: false
  use-worlds: true
  lower-case:
    players: true
    worlds: false

Permission settings allow to specify some compatibility options, The saving settings should not be used for the most permission plugins, for most plugins save automatically on permission manipulations, however bPermissions does have an option "auto-save" to disable always saving - if you have set that to false, you should enable the saving settings (save-at-all + interval). For using transient-groups it is not necessary to save at all.
The use-worlds flag states if permissions should be handled world-specific - this does affect adding and removing permission groups but not checking the permissions of a player. This might be relevant if using Vault, in case a linked plugin is incompatible with multiple world settings.
The lower-case section allows to specify if world and player names should be transformed to lower case for permission group checking and manipulation - this might be interesting when using Vault, because for some plugins Vault has to or is using special ways to implement group checking and manipulations, such that a correct case player name might not get recognized - then these settings might help to reach compatibility.

(Since 1.0.0-DEV-3) Transient permission support (permissions get added to the player independently of the plugin and only while the player is online, best use with have-inside):

transient-groups:
    SimVan:
    - simplyvanish.vanish.self
    - simplyvanish.reappear.self
    - customplg.flymode.use
    - -example.for.negation

You can add a section "transient-groups", in which you can list permissions under a group name. These will be used before the permission groups of your permission plugin, thus can be used to override those for testing, but also just to have permissions that don't get saved to disk.
Negate permissions in PEX style, like "-example.for.negation", above - however this is not well tested and i can not guarantee that this will really override other permissions of your other plugins, in fact i would guess it will not necessarily be the case.

load-plugins: []

The load-plugins list can be used to force RSP loading other plugins first, which might be useful, if those plugins are necessary for operating RSP or Vault or are using the RSP API, if the load order is not optimal for some reason. Should be rarely to never be necessary to use.

Stats and Error Logging

errors:
  log:
    min-delay: 10000
stats:
  use: true
  log: false
  show:
    range: false

The error section allows specifying a minimum delay in milliseconds (min-delay), which will prevent total spamming of the console in case of frequent error messages of the same kind, like the permissions plugin not being ready or similar.
The stats sections allows to set if RSP should take timings for its checking actions (use), if the timings should be logged to the console (roughly every 10 seconds if changes occur), and if to show minimum and maximum values (show.range). Maximum values can be pretty high due to permission manipulations leading to file-manipulations, which also could invite thread-switches, which then could lead to a hilariously high time in the milliseconds range. The av. time should be around or below 10000 nanoseconds for PlayerMove to ensure good performance, be sure to have many events, like n=200000 and above. Check ingame with /rsp stats.

Other Default Settings

create-portals: false
confine:
  enabled: false

For Confinement and World specific settings, see the section below.

generic-links:
  online: []
  ownership: []

Generic links are not yet available, later see the links section below.

Dynamic Permission Settings

To have permissions be manipulated dynamically on base of WorldGuard regions, you have to go through two steps:

• Define permission manipulations (permdefs), each stating who is affected and which groups to add or remove if a player enters or leaves a region.
• Link permdefs to WorldGuard regions (links), to tell RSP where permission manipulations are to be applied.

Defining Permission Manipulations (permdefs)

The "permdefs" section lets you define sets of manipulations for permission groups along with pre conditions for whom to apply those to.
Example:

permdefs:
  shopdef:
    ignore-perm: rsp.ignore.this
    have-inside:
      groups:
      - shopusergroup
  townFly:
    ignore-perm: rsp.ignore.this
    filter-perm: i.am.vip
    have-inside:
      groups:
      - flygroup
  XYZ:
    add-enter:
      groups:
      - ihavebeeninxyz

The ignore-perm is a permission which defines which players are not being affected by this permdef, whenever it may apply. Since RSP 1.7.3 you also have ignore-add-perm and ignore-remove-perm, which allows more flexibility with using priorities - since then the ignore-add-perm could be used without specifying ignore-perm nor ignore-remove-perm, to prevent a high-priority permdef staying because a player obtained the ignore-perm somehow.
The filter-perm is a permission which defines for which players the permdef can apply at all, players that don't have the permission will not get groups added.
Both fiter-perm and ignore-perm need not be specified, in such case it would apply to all players.
Further you define how the permdef is used with sections like "have-inside" or "add-enter", for each section you can set a list of groups (permission groups) which will be subject of adding or removing.
The possible uses are :

• add-enter
• remove-exit
  These groups also will be removed when a player is checked out, for instance on logout.
• have-inside
  This is the same as add-enter + remove-exit at the same time.
• add-exit
• remove-enter

The most common use should be "have-inside" to let players be part of a group while being inside of a certain region.
The permission groups have to be set according to your permission plugins configuration, and then contain the permissions for the specific purpose like "shopplugin.use" for the group shopusergroup or "flyplugin.use" for the group flygroup.

Be sure to use unique names for permdefs. Using some naming convention can help to not mix up group names and permdef names, if you call permission group permdef and region all like "shop" you will likely have more trouble on error recovery. Using names like shopusergroup, shopdef, shops can help to avoid trouble from the start.

Advanced permdefs (priorities)

permdefs:
  # ...
  noFly:
    priority: 1
    ignore-perm: rsp.ignore.this
    filter-perm: i.am.vip
    remove-enter:
      groups:
      - flygroup

You can assign priorities to permdefs, which can override other permdefs decisions and also transient permissions. Above is an example to take away the flygroup inside of an arena inside of the town region, for instance. This only takes away the flygroup.

If you use only transient permissions of RSP for flying you can also use priorities to override the flying permissions explicitely, to be able to use them in different groups. To give people permissions with RSP all over a world, you need to link permdefs to the __global__ region name,

permdefs:
  # ...
  vipfly:
    filter-perm: "i.am.vip"
    have-inside:
      groups:
      - vipfly
  nofly:
    priority: 10000
    have-inside:
      groups:
      - nofly
# ...
links:
  SomeWorld:
    __global__:
    - vipfly
    # (Say, vipfly is a gorup giving vips flying in that world, by use of filter-perm.)
    arena:
    - nofly  
transient-groups:
  # ...
  vipfly:
  - flyperm
  # (Just what is needed to be handled by RSP.)
  nofly:
  - -flyperm
  # (Negated flying permissions, priorities will put htis one through.)

Pitfall: Negating cross-plugin permission will likely not work. you might even not be able to rely on negation of permissions just using your permission plugin. For reliable negation of permissions in a dynamical context, you should use transient-groups inside of RSP, the filter-permission with the __global__ link can help to control who can have the permissions normally everywhere in a world.

Linking permdefs to WorldGuard Regions (links)

In the configuration section "links" you can tell RSP for which regions which permdefs should apply. The section generic-links is not yet available and has no effect.
Each world has its own section under links which then will have a list of names of permdefs for each region, example:

links:
  world:
    town:
    - townFly
    - townEco
    shops:
    - shopdef
    shops2:
    - shopdef
  world_nether:
    shops:
    - shopdef
  SomeOtherWorld:
    TownOfXYZ:
    - XYZ

Here are links for three worlds: world, world_nether and SomeOtherWorld.
For each region that should change some permissions a list of permdef names has to be given, so that RSP knows where to apply the permdefs.
Be sure to use correct case for the permdfef, world and region names!
Be sure to never duplicate sections (i.e. two times world: ... or two times links: ...)
There are some generic region names (reserved):

• __global__
  Applies to the whole world in general.
• __owner__
  Applies to region owners only (RSP 1.3.0).
• __member__
  Applies to region members only (RSP 1.3.0).
• __region__
  Applies to players that are on a region in general (RSP 1.3.0).

World Specific and Confinement Settings

To limit your maps you can use confinement settings.
On top level of the configuration you can set default settings, in the section "worlds" you can define world-specifiic confinement settings which will override the defaults.

Examples for confinement and world specific settings:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

confine:
    enabled: true
    center:
        x: 0
        z: 0
    radius: 2500
    circular: true
    message: 'World border reached !'
    resetto:
        recent: true

worlds:
    infinite_world:
        confine:
            enabled: false
        heuristic:
            lazy-dist: 10000

On "ground level" of the configuration file you can define confinement settings and lazy-dist which will be treated as default settings for all worlds, unless specific settings are given there.
Here The default confinement is set to circular with a radius of 2500 blocks to each direction (height is not checked).
The message need not be set, same as the resetto.recent setting (see below).
For world specific settings you have the section "worlds", which here stats that some world should not use confinement and have a very big lazy dist, which makes sense if there are no region specific permissions for that world.

Setting circular to false leads to more "minecraft-natural" feeling of the world border, due to being able to walk next to it, which is difficult with a circular border.

Standard confinement vilolation behavior:

• If the resetto.recent setting is set to true, RSP will attempt to teleport the player to the last "valid" position, which is "acurate" within lazy-dist. Actually this should never be a cross-world position, but i am not 100% sure, so if the behavior given below is ok, the most safe setting will be set this to false, to avoid strange effects, that might occur with presence of other plugins, potentially. I had no problems with this yet, but if so, this setting allows to force in-world teleport at the cost of reset-accuracy.
• If no "valid" position is stored (either due to simply not being present, or because resetto.recent is set to false), then the player will be teleported "somewhere" inside of the confinement, to the highest block that is just inside of the confinement:
  • circular: Along the line from the player to the center.
  • rectangular( circular=false): Orthogonally towards center both for x and z independently.
• If an action leading to an invalid position can be canceled, such will be attempted.

Edge case: portals

create-portals: false

The entry create-portals only takes effect, if you use confinement settings. It has a more or less distant abuse potential (see below) for it creates portals to check if a player may move there, and might not respect things like WorldGuard regions for that. Thus it is set to false by default. The effect of create-portals being set to false is that the standard confinement violation treatment will be applied, instead of just denying the portal use, which might lead to teleport the player "somewhere" next to inside of the confinement or to the last valid position. If it is set to true, it might help avoiding teleporting to another world unnecessarily. [Subject to removal]

players.yml

With the players.yml file, you can define per-player default groups, which get added to the player globally.
Currently there is no ingame commands nor java API for efficient use, thus this feature has to be regarded as "experimental", but it allows for having admin-like permissions for selected players, for the case that you don't want to use another permission plugin. Group setup is very basic and only allows to specify transient-groups entries with priority (@priority, see below), there is also no permissions subscriptions done, so the compatibility with some advanced features of Bukkit is probably not given. This system might get extended further for more easy setup and more rich features.

Basic example (rsp.yml)

Priorities are stated with appending @priority (see below). You can address players by name, but the file will change it to the UUID once the player joins, the name will then be added as an extra entry to the section for easier manual editing.

Notch:
  groups:
  # Simple reference:
  - Notchian
  # Group added with priority 100:
  - NoFly@100
  # Undefined strange thing (probably forget about this one):
  - -Mojang@-2500000000
  # (In theory you can take away a group, e.g. to "repair" a complicated
  # setup, by preventing to add the group below that priority,
  # not sure this works at all, as it has not yet been tested.)