Protection

Deprecated region engine with flags and region events. Use the official Region extension for new projects.

FreeDeprecatedv1.3World & building

RequiresTypeWriter0.9PacketEventsWorldEdit or FastAsyncWorldEditoptionalMythicMobsoptionalBlueMapoptionalPlaceholderAPIoptional

DownloadSource codeSupport

This extension is deprecated and no longer receives new features. Use Region (official TypeWriter extension) instead.

Overview

Deprecated

Protection is deprecated. It receives no new features, and v1.3 is the final compatibility release. New projects should use the official Region extension of TypeWriter, documented at docs.typewritermc.com. This page remains for servers that already run Protection.

Protection lets you define regions in the TypeWriter web panel and give them rules, called flags. A region is a cuboid or a polygon prism stored in an artifact, with a priority, owners, members, an optional parent region and a list of flags such as build, pvp or mob-spawning. When players act inside a region, the extension cancels or changes the action according to the flags.

Regions are also TypeWriter objects. You can start a sequence when a player enters or leaves a region, filter an audience by region, group players by region, read a fact that tells whether a player is inside, and show regions on a BlueMap map.

Features

• Cuboid and polygon regions — draw a region in game with a toolbar, or import a WorldEdit selection.
• World-wide regions — a global artifact covers whole worlds between two heights.
• Overlap and priority — regions can overlap; they are evaluated from the highest priority down.
• Parent regions — a child region inherits the flags, owners and members of its parent.
• Many flags — 99 flag keys covering building, combat, explosions, environment, movement and chat.
• Owners and members — these players are never restricted inside their region.
• Region events — enter and exit events, an audience filter, a group and a fact.
• Inspection tools — /typewriter protection inspect, info and flags show which flags apply where you stand.
• BlueMap markers — display a region on BlueMap with your own colours.
• PlaceholderAPI — read the regions around a player and their flag values.

Installation

1. Install PacketEvents, which TypeWriter already requires.
2. Optional: install WorldEdit or FastAsyncWorldEdit to import selections with /typewriter protection import-we.
3. Optional: install MythicMobs so the mob-spawning flag also applies to Mythic mobs, and BlueMap to show regions on the map.
4. Optional: PlaceholderAPI for the placeholders.
5. Put the Protection JAR in plugins/Typewriter/extensions/ and restart the server.

Getting started

Protect a spawn area against building and PvP:

1. In the TypeWriter web panel, open a manifest page and add a Protection Region Artifact. Leave artifactId as generated: it stores the shape of the region.
2. Add a Protection Region Definition and link the artifact in artifact. Set a priority (for example 10).
3. In flags, add a flag with the key build and a boolean value set to false. Add pvp the same way. A false boolean flag denies the action.
4. Publish the page.
5. In game, run /typewriter protection edit <definition>. A toolbar appears in your hotbar: the blaze rod adds a point at the block you look at, the redstone removes the last point, the compass switches between cuboid and polygon mode, the lime dye applies the selection and the barrier cancels. For a cuboid, add two opposite corners and apply.
6. Walk into the area and try to break a block. You can check what applies with /typewriter protection inspect.

Import a WorldEdit selection

Make a selection with WorldEdit, then run /typewriter protection import-we <definition>. Your selection is converted into points that you can then apply.

Owners and members

Owners and members of a region, and players with typewriter.protection.bypass, ignore every flag of that region. Test with a player who is not listed, and not an operator with the bypass permission.

How it works

A region only exists while its definition entry exists and is published. Its shape is stored in the artifact, and the definition holds everything else.

Overlap. Several regions can contain the same point. They are checked from the highest priority to the lowest. For boolean flags, one false flag is enough to deny the action: a region with build true does not cancel the denial of a lower priority region. Flags that change something (messages, actions, teleports) are applied by the first region that defines them.

Inheritance. A region with a parentRegion also evaluates the flags of its parents. Owners and members of the parents are added to the child. The child uses its own priority, or the parent one when its own is 0.

Region borders. Enter and exit are detected when a player moves to another block or teleports. A player who joins inside a region triggers the enter event on their first block of movement.

Configuration

Messages and inspection. Add one Protection Settings entry to change how denied actions are shown: chat, action bar or boss bar, MiniMessage templates ({reason}, {reason_line}, {region}, {flag}), the refresh rate of the inspection mode (inspectRefreshTicks, at least 5 ticks) and the text of the command messages in messages. Without this entry, defaults are used. Only the first entry found is read.

BlueMap. In a region definition, turn on bluemapSettings.enabled to draw the region on BlueMap. You choose the marker set, the line and fill colours, the label ({name}, {id}, {priority}) and whether the marker is extruded or flat. Regions are synchronised when BlueMap starts and whenever a region changes.

Owners and members. owners and members hold player UUIDs. The commands addowner and addmember accept a player name and store the UUID when the player is known to the server.

Flags

Flags are added to the flags list of a region definition. Each flag has a key and a typed value. Most flags are booleans: a false value denies the action. The flag keys below are the ones used in the web panel and in commands.

Building and interaction

Flag	What a false value does
build	Cancels block break and place. Checked before block-break and block-place.
block-break, block-place	Cancels breaking or placing blocks.
use	Cancels right-clicks on doors, buttons, levers, gates, trapdoors, signs, chests, barrels, shulker boxes, furnaces, anvils, crafting and other stations, redstone components and similar blocks.
interact	Cancels every player interaction, including clicks in the air. Use with care.
chest-access	Cancels opening containers (chests, barrels, shulker boxes, hoppers, dispensers, droppers, furnaces, brewing stands).
sleep	Cancels using beds.
lighter	Cancels flint and steel and fire charges.
vehicle-place, vehicle-destroy	Cancels placing minecarts and boats, or a player destroying a vehicle.
entity-painting-destroy	Cancels a player breaking paintings and item frames.
crop-trampling	Cancels farmland being trampled.
pistons	Cancels pistons moving blocks into or out of the region.
item-pickup, item-drop	Cancels picking up or dropping items.

Combat and mobs

Flag	What a false value does
pvp	Cancels damage between players.
mob-damage	Cancels damage to a player caused by an entity that is not a player.
damage-animals	Cancels a player hitting animals.
tnt-damage, firework-damage	Cancels damage from TNT and explosive minecarts, or from fireworks.
mob-spawning	Cancels creature spawns, whatever the reason. It also applies to MythicMobs when MythicMobs is installed.
btcmob-spawning, btcmob-damage	Same for BTC Mobs creatures, when BTC Mobs is installed.
exp-drops	Mobs killed in the region drop no experience.
potion-splash	Cancels splash potions landing in the region.

Explosions and environment

Flag	What a false value does
creeper-explosion, tnt	Cancels creeper explosions, or TNT, TNT minecarts and respawn anchor explosions.
ghast-fireball	Cancels explosions of fireballs, wither skulls, dragon fireballs and wind charges.
fire-spread	Cancels fire spreading, burning blocks and ignition that is not lava or lightning.
lava-fire, lightning	Cancels ignition by lava, and lightning strikes and ignition.
lava-flow, water-flow	Cancels lava or water flowing into the region.
ice-melt, snow-melt	Cancels ice or snow melting.
ice-form, snow-fall	Cancels ice or snow forming.
frostwalker	Cancels frost walker ice.
leaf-decay, grass-growth, vine-growth	Cancels leaves decaying, grass, mycelium, paths and mushrooms spreading, and vines growing.
enderman-grief, ravager-grief	Cancels endermen and ravagers changing blocks.
chunk-unload	A true value keeps the chunks of the region force-loaded.

Movement

Flag	Value	Effect
entry, exit	boolean	A false value blocks entering or leaving the region. Blocked players get the deniedEntry message.
entry-deny-action, exit-deny-action	actions	TypeWriter actions run for the player when they enter or leave, and when an entry or exit is denied. Use the enter and exit event entries for ordinary logic.
ender-pearl	boolean	A false value cancels ender pearl teleports to the region.
fall-damage	boolean	A false value cancels fall damage.
fly	boolean	A false value turns flight off for players in the region.
walk-speed, fly-speed	number	Sets the walk or fly speed of players inside, between 0 and 1. Bukkit scale: 0.2 is the normal walk speed and 0.1 the normal fly speed. The default is restored outside.
glide	text	deny stops elytra gliding and flight toggling. allow and default do nothing.
join-location	position	Players who log in or respawn inside the region are moved to this position.

Player state, chat and commands

Flag	Value	Effect
hunger	boolean	A false value stops hunger loss.
heal-amount, heal-min-health, heal-max-health	number	Heals players in the region by heal-amount health points every second, between the minimum and maximum health. Healing pauses for 5 seconds after any damage.
item-durability	boolean	A true value stops tools, weapons and armor losing durability.
send-chat, receive-chat	boolean	A false value blocks messages sent from, or received inside, the region.
chat-prefix, chat-suffix	text	Adds text before or after chat messages sent from the region.
blocked-cmds, allowed-cmds	list	Command names (without the slash) that are blocked, or that are always allowed. * blocks every command. allowed-cmds wins.
worldedit	boolean	A true value blocks WorldEdit commands for players in the region.

Not enforced by this extension

The following flags can be added to a region but nothing in Protection acts on them: passthrough, teleport, godmode, nether-portals, entry-min-level, entry-max-level, permit-completely, mobtrap-use, blocked-effects, heal-delay, biome (the biome is not changed), and the RPG flags mana-regen, mana-drain, double-drop, grappling-hook, fishing, alchemy, enchanting-override, elytra-auto-switch, ground-item-glow, pistol, corruption, auction, backpack, wardrobe, profession, experience, gathering and resin.

keep-inventory, keep-exp and invincible have no effect for regular players either: they only act for owners, members and players with the bypass permission.

Commands

All commands are sub-commands of /typewriter (alias /tw), for example /typewriter protection list. They can only be used by players and need typewriter.protection. Commands marked admin need typewriter.protection.admin.

Command	Description
/typewriter protection list	List loaded regions, highest priority first.
/typewriter protection edit <definition>	Start drawing the region in game with the hotbar toolbar. For a global artifact, it applies the artifact values immediately.
/typewriter protection apply	Save the current selection.
/typewriter protection cancel	Cancel the current selection.
/typewriter protection remove <1-16>	Remove one point of the current selection.
/typewriter protection import-we <definition>	Import your WorldEdit selection as the points of the region.
/typewriter protection info <region>	Show the shape, priority, owners, members and flags of a region.
/typewriter protection flags <region>	Show which flags are effective, inherited, overridden or blocked by inheritance.
/typewriter protection inspect	Toggle a live view of the regions and flags where you stand, in the action bar and boss bars.
/typewriter protection teleport <region>	Teleport to the centre of a region (or the world spawn for a global region).
/typewriter protection wand	Gives a stick named Protection Wand. In this release, nothing reacts to it.
/typewriter protection setflag <region> <flag> <value> (admin)	Change a flag in memory.
/typewriter protection clearflag <region> <flag> (admin)	Clear a flag in memory.
/typewriter protection addowner|removeowner|addmember|removemember <region> <player> (admin)	Change owners or members in memory.
/typewriter protection delete <region> (admin)	Remove a region from memory.
/typewriter protection reload (admin)	Reload regions from the published entries.
/typewriter protection migrate-from-worldguard (admin)	Experimental import of the cuboid bounds of WorldGuard regions. See the page on artifact identity and migration.

In-memory commands

setflag, clearflag, addowner, removeowner, addmember, removemember and delete do not write to your entries. They change the loaded copy, and the changes are lost on reload or restart. Most flags are enforced from the region definition entry, so a setflag does not change how build, pvp or most other flags behave. Edit flags in the web panel and publish.

Permissions

Permission	Grants
typewriter.protection	The /typewriter protection commands that are not admin only.
typewriter.protection.admin	The admin commands: flags, owners, members, delete, reload and WorldGuard migration.
typewriter.protection.bypass	Ignore every flag, in every region.

Placeholders

PlaceholderAPI placeholders use the form %typewriter_regions:<path>%. They read the regions at the player position, sorted by priority; primary is the first one.

Placeholder	Returns
%typewriter_regions:count%	How many regions contain the player.
%typewriter_regions:list%, %typewriter_regions:list_names%	The ids, or the names, of those regions, separated by commas.
%typewriter_regions:stack%	Priority and name of each region, separated by |.
%typewriter_regions:has:<id1>,<id2>%	true if the player is in one of the listed regions.
%typewriter_regions:primary%	The name of the highest priority region. Add :id, :name, :priority, :overlap_count, :parent, :parent_name, :owner_count, :member_count, :is_global, :depth or :path for other fields.
%typewriter_regions:active:<n>%	The same fields for the n-th region of the stack, starting at 1, for example %typewriter_regions:active:2:id%.
%typewriter_regions:flag:<flag>%	The value of a flag in the primary region. Add :state, :source or :source_name for where it comes from.
%typewriter_regions:by_id:<region>:<field>%	A field of a given region, for example %typewriter_regions:by_id:spawn:priority%.
%typewriter_regions:exists:<region>%	true if the region exists.
%typewriter_regions:nearest%	The region whose minimum corner is nearest to the player. The same fields are available.
%typewriter_regions:can_build%, %typewriter_regions:can_interact%	false when the first region, by priority, that sets build (or interact) has it set to false, otherwise true.

Migrating to Region

Protection will not receive new features, so plan to move to the official Region extension of TypeWriter, documented at docs.typewritermc.com. This page does not describe Region: follow its own documentation.

Protection contains no tool to convert its regions to Region. The general approach is:

1. List your regions with /typewriter protection list and note, for each one, its shape, priority, parent, owners and members, and flags (/typewriter protection info <region>).
2. Recreate each region in the new extension and map each flag to the equivalent setting there. Some Protection flags are not enforced (see above), so you may not need them.
3. Test on a copy of your server, with players who are not owners, members or bypass holders.
4. Remove the Protection entries and the JAR once the new regions behave as expected. Keep a backup of your TypeWriter pages and assets first.

Entries

9 entries, generated from the extension source.

Events2

• On Enter Protection RegionWhen a player enters a protection region
• On Exit Protection RegionWhen a player exits a protection region

Facts1

• In Protection Region FactIf the player is in a protection region

Audiences1

• Protection Region AudienceFilter players based on if they are in a protection region

Groups1

• Protection Region GroupAll players grouped by protection regions

Artifacts2

• Global Protection Region ArtifactPersistent data for a world-wide protection region
• Protection Region ArtifactPersistent data for a TypeWriter-managed protection region

Manifests2

• Protection SettingsConfiguration for protection tooling
• Region DefinitionProtection region definition

Troubleshooting

A flag does nothing. Check the flag in Flags: some keys are not enforced. Also check that the region is saved and published, that the player is not an owner, a member or a holder of typewriter.protection.bypass, and that the value is a boolean set to false for denying flags.

The region exists but players are not inside it. The shape comes from the artifact. A definition without an artifact, or an artifact where you never applied a selection, covers nothing. Run /typewriter protection edit <definition> and apply a selection, then check with /typewriter protection info <region>. All points must be in the same world, and a cuboid needs 2 points, a polygon 3.

The selection toolbar does not appear. edit needs a published region definition linked to an artifact. If the message says the definition is not linked to any artifact, link one. For a global artifact there is no toolbar: set worlds, minY and maxY on the artifact.

/typewriter protection import-we says no selection or no adapter. WorldEdit or FastAsyncWorldEdit must be installed and you must have made a selection in the world you are standing in.

A setflag change disappears. The command only changes memory. Put the flag in the region definition and publish.

A WorldGuard migration did not create regions. The migration does not create region definitions, flags, owners or members: it only handles the cuboid bounds of each region, and it reads the regions of WorldGuard through the first loaded world. Create the definitions in the web panel.

Players are not teleported or blocked by entry. The check happens when a player moves to another block or teleports. Entering by a plugin that moves the player without a movement or teleport event is not seen.

Related extensions

• MythicMobs — mob-spawning also applies to Mythic mobs.