Prison Chat Core

PrisonChat runs your server's chat. It formats every line by rank, with tags and colours players unlock, and lets players show off items, mention each other and send private messages. Filters catch spam, adverts and swearing, and staff get mute, clear and slow mode tools. Players change their own settings in one menu, /chat.

The short version

Upload the PrisonChat jar to your plugins folder next to PinnaPrison and restart the server. Then join as an operator and run:

/prisonchat status
/chat
/prisonchat test join play.example.net
/prisonchat games start math

1. /prisonchat status shows what PrisonChat hooked into (LuckPerms or permission groups, PlaceholderAPI, DiscordSRV), the storage type, and how many formats, tags, colours, filters and games loaded.
2. /chat opens the menu players use to pick a tag and colours, and to set mention alerts, private messages and ignored players.
3. /prisonchat test <message> runs a message through every filter the way a normal player would see it. This one should come back blocked by advert.
4. /prisonchat games start math starts a chat game straight away. Type the answer in chat to win the reward.

Send a normal chat message to see the format. As an operator you own every tag and colour, but your players own none until you give them permissions. See Tags and colours are unlocked by permission.

What you need

How a chat line is built

Each chat line comes from a format in formats.yml. PrisonChat uses the format with the highest priority whose groups include one of the player's groups. groups: ['*'] matches everyone, and an optional permission: must also be held.

formats:
  default:
    priority: 0
    groups: ['*']
    format: '&8[{rebirth}&8✦ {rank}&8] {prefix} {name}&8 {tag} » {message}'
    name: '&7{player}'
    name-click: 'suggest_command:/msg {player} '
    message-color: '&7'

To give a rank its own look, copy the default block, rename it (for example vip), raise its priority and list that rank's LuckPerms groups in groups. The comment block at the top of the file lists every token, such as {tag}, {prefix}, {rank}, {rebirth}, {name} and {message}. You can also use any PlaceholderAPI placeholder. name-hover sets the lines shown when someone hovers over a name, and name-click sets what clicking it does. {rank} and {rebirth} come from the text: placeholder at the top of rankcolors.yml and rebirthcolors.yml. Run /prisonchat debug <player> to see which groups, format, tag and colours a player ends up with.

Every chat-facing string in PrisonChat's files accepts & colour codes, &#RRGGBB hex and MiniMessage tags such as <gradient>, <hover> and <click>. What players type is never read as MiniMessage. They can only use the & codes their prisonchat.color permissions allow.

Tags and colours are unlocked by permission

Players start with no tags and no colours. Each tag in tags.yml needs prisonchat.tag.<id>, and each colour needs a node for its part. Give them out with your permissions plugin, for example:

/lp group default permission set prisonchat.tag.prisoner true
/lp group default permission set prisonchat.namecolor.gray true

Players can colour five parts of their chat line. Each part has its own palette file, command, menu and permission nodes:

.* in place of <id> unlocks every colour in that file, and prisonchat.tag.* unlocks every tag. A tag or colour with its own permission: line uses that node instead.

At the top of each palette file, enabled: false turns that part off, and default-color sets the colour used when a player hasn't picked one. Bold and italic are part of a colour, so "White Bold" is its own entry with decorations: ['bold'] and its own permission. The ids custom, use and gradient are reserved. Players with prisonchat.<part>color.custom can type their own hex colours, and prisonchat.<part>color.gradient lets them use several (up to chat-color.custom-max-colors in config.yml, 4 by default) as a gradient, stepped or rainbow style.

Filters and staff tools

Filters run in the order set in filters.yml. The first filter that blocks a message stops it, and filters that change a message (lower-casing caps, censoring a word) pass the changed text on. Each filter has a bypass permission, prisonchat.bypass.<id>. When notify-staff is on, staff with prisonchat.staff.filtered get an alert they can hover over to see the original message.

order: ['slowmode', 'cooldown', 'flood', 'similarity', 'caps', 'advert', 'rules']

advert:
  enabled: true
  action: block
  whitelist:
    - 'yourserver.net'
    - 'discord.gg/yourserver'
    - 'youtube.com'

Blocked words live under rules.list. Each rule has one or more regex lines and an action (replace, block or notify), and can run commands as the console. /prisonchat regex <word> --add swearing builds a pattern that catches common spellings like f.u.c.k and adds it to the swearing rule. Private messages go through the filters listed in private-messages.filters in config.yml.

/staffchat switches a staff member's chat to staff only. Anyone with prisonchat.staffchat can also start a message with # to send just that line to staff. Change or blank the staff-chat.shortcut in config.yml if that gets in the way. To send staff chat to Discord, set staff-chat.discordsrv-channel to a DiscordSRV channel name. /mutechat and /slowmode only last until the next restart. moderation.default-slowmode in config.yml sets the slow mode the server starts with.

Chat games and extras

Every 600 seconds, if at least 2 players are online, games.yml starts a random chat game: typist, unscramble, math or trivia. The first player to type the answer wins and the game's rewards run. A reward line starting [console], [player], [message] or [broadcast] runs a command or sends text. Any other line is a PinnaPrison action, such as the bundled give-eco tokens 25k. Use {player} in a line for the winner's name.

The rest works out of the box, but a few parts are worth a look before you open:

• Announcements. announcements.yml broadcasts one message every 300 seconds. The bundled ones link to https://discord.gg/yourserver and run /buy and /vote, so change them to match your server.
• Emojis and links. emojis.yml swaps typed text such as :heart: or [discord]. [discord] and [store] point at placeholder addresses. [bal], [tokens], [rank] and [gang] need prisonchat.placeholder.balance, .tokens, .rank and .gang.
• Showcase and mentions. Players type [item], [inv] or [enderchest] to show them in chat, and @name to mention someone. Shown inventories stay clickable for showcase.snapshot-seconds (300). Mention alerts are set under mentions in config.yml, and each player can switch alerts off in /chat.
• Join and quit messages. join-quit in config.yml sets one pair per group and a first-join welcome. prisonchat.silentjoin hides them for a player.
• Mine finds. mine-finds in config.yml sends a player a message when they mine a listed block by hand (a beacon or gilded blackstone by default). Players switch it off in /chat.

Commands

Player commands:

In the colour commands, custom asks you to type hex colours in chat, hex sets them directly, and mode cycles gradient, stepped and rainbow. custom and hex need prisonchat.<part>color.custom. mode, and using more than one colour, need prisonchat.<part>color.gradient.

Staff and admin commands:

A trailing -s on /mutechat, /clearchat or /slowmode skips the broadcast to players. On /prisonchat reload, regex, games or announce it skips your confirmation message.

Permissions

Files

Every file starts with a comment block explaining its keys. PrisonChat creates its files once and never overwrites them. /prisonchat reload applies changes to all of them, except the storage section, chat.listener-priority and placeholders.tags-expansion, which need a restart. If a file has a YAML error, the console says so, the reload reply names it, and PrisonChat runs on the built-in copy of that file until you fix it and reload.

The menus are PinnaPrison GUI files. PrisonChat installs them into plugins/PinnaPrison/guis/prisonchat/ on first start and never overwrites them, so delete a file and restart to get the default back. Menu changes reload with /pinna reload, not /prisonchat reload.

Placeholders

PlaceholderAPI placeholders need PlaceholderAPI. The PinnaPrison variables work wherever PinnaPrison fills in its own variables.

If another plugin already uses the tags identifier, set placeholders.tags-expansion: false in config.yml and restart. %prisonchat_tag%, %prisonchat_tag_raw% and %prisonchat_tag_id% still work.

Troubleshooting

Filters, slow mode and mute chat don't affect you. Operators hold every bypass permission. Test with a non-op account, or run /prisonchat test <message>, which ignores your bypasses.

Players can't pick any tag or colour. They need prisonchat.tag.<id> and prisonchat.<part>color.<id> nodes. Nobody but operators has them by default. See Tags and colours are unlocked by permission.

The chat line shows %pinnaprison_...% text, or the rank and rebirth numbers are wrong. Install PlaceholderAPI and restart. The default format and the rank and rebirth numbers rely on it. /prisonchat status shows PlaceholderAPI: true once it's hooked.

/msg, /r, /tags or /ignore run another plugin's version. Another plugin, often Essentials, registered the same command. /prisonchat:msg always reaches PrisonChat. Remove the command from the other plugin, or point it at PrisonChat in the server's commands.yml:

aliases:
  msg:
  - prisonchat:msg $1-

Menu changes don't show up. Run /pinna reload. Menus belong to PinnaPrison, so /prisonchat reload doesn't touch them.

PrisonChat disables itself on start. Check the console. Could not open the chat database (mysql) means the details under storage.mysql in config.yml are wrong or the database can't be reached. Fix them and restart. If the error is about downloading libraries, the server couldn't reach the internet on first start. Allow outbound access once and restart.