> For the complete documentation index, see [llms.txt](https://docs.cozycrafters.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cozycrafters.net/plugin-docs/cozytowns.md).

# CozyTowns

## CozyTowns

### What It Does

CozyTowns adds player towns on top of GriefPrevention claims.

Players can create towns, invite members, link claims, manage town identity, use private town chat, form alliances, visit public towns, run contracts, and share town vaults. Staff can manage towns through admin commands, adjust town XP and levels, inspect town status, and monitor private town and ally chat with spy mode.

### Main Features

<table><thead><tr><th width="165.8046875">Feature</th><th>Description</th></tr></thead><tbody><tr><td>Town creation and membership</td><td>Players can create towns, invite members, accept or deny invites, leave towns, kick members, transfer ownership, and disband towns.</td></tr><tr><td>Claim linking</td><td>Towns can link and unlink GriefPrevention claims. CozyTowns does not replace GriefPrevention claim ownership.</td></tr><tr><td>Town menus</td><td><code>/town</code> opens the main town menu for players.</td></tr><tr><td>Town identity</td><td>Towns can use names, tags, colors, banners, mottos, motto history, and cosmetic roles.</td></tr><tr><td>Town chat</td><td><code>/townchat</code> and <code>/tc</code> send private messages to online town members.</td></tr><tr><td>Ally chat</td><td><code>/allychat</code> sends private messages to town members and allied towns.</td></tr><tr><td>Recruitment</td><td>Towns can use invite-only, open/request, closed, and hidden recruitment states.</td></tr><tr><td>Join requests</td><td>Players can request to join towns, and town leaders can review requests.</td></tr><tr><td>Town profiles</td><td><code>/town profile [town]</code> and player <code>/town info [town]</code> open public town profile menus.</td></tr><tr><td>Ratings</td><td>Players can rate towns from profile menus when ratings are enabled.</td></tr><tr><td>Alliances</td><td>Town mayors can propose, accept, deny, view, and break alliances.</td></tr><tr><td>Visits</td><td>Players can visit public towns, and towns can view recent visitor logs.</td></tr><tr><td>Vaults</td><td>Towns can open shared vaults, rename vaults, and view vault logs.</td></tr><tr><td>Contracts</td><td>Towns can view and manage generated town contracts/jobs.</td></tr><tr><td>Bulletins</td><td>Towns can post, list, pin, unpin, and remove bulletin board posts.</td></tr><tr><td>Progression</td><td>Towns gain XP, levels, caps, and perks.</td></tr><tr><td>Admin tools</td><td>Admins can reload configs, inspect towns, adjust XP/levels, reset progression, manage recruitment, manage bulletins, check contracts, and use spy mode.</td></tr></tbody></table>

### Basic Admin Workflow

1. Install the required dependencies: Vault and GriefPrevention.
2. Install an economy provider for Vault if paid actions are enabled.
3. Optionally install PlaceholderAPI and PlayerPoints if you use those integrations.
4. Start the server once so CozyTowns can create its files.
5. Review `config.yml`, `messages.yml`, and `contracts.yml`.
6. Give players the standard player permissions.
7. Give staff `cozytowns.admin` only if they should use admin commands or staff spy.
8. Use `/town reload` after supported config, message, or contract changes.

### Notes

* The primary player command is `/town`; `/t` is its alias.
* `/towns` opens the public town finder when enabled.
* Preferred admin commands are `/townadmin` and `/townsadmin`.
* `/towns admin ...` remains accepted as a compatibility path.
* `/townchat`, `/tc`, and `/allychat` can be used with a message or with no message to toggle private chat mode.
* Private chat modes are in memory and clear on reload, restart, or player quit.
* `/townadmin spy` is in memory and clears on reload, restart, or player quit.
* The source confirms hard dependencies on Vault and GriefPrevention.
* The source confirms optional soft dependencies on PlayerPoints and PlaceholderAPI.
* The current source does not declare a wildcard permission such as `cozytowns.*`.

### Common Use Cases

<table><thead><tr><th width="208.15625">Use Case</th><th>Command</th></tr></thead><tbody><tr><td>Open the town menu</td><td><code>/town</code></td></tr><tr><td>Create a town</td><td><code>/town create &#x3C;name></code></td></tr><tr><td>Invite a player</td><td><code>/town invite &#x3C;player></code></td></tr><tr><td>Open town chat</td><td><code>/townchat [message]</code> or <code>/tc [message]</code></td></tr><tr><td>Open ally chat</td><td><code>/allychat [message]</code></td></tr><tr><td>Browse towns</td><td><code>/towns</code> or <code>/town finder</code></td></tr><tr><td>View a town profile</td><td><code>/town profile [town]</code></td></tr><tr><td>Visit a public town</td><td><code>/town visit &#x3C;town></code></td></tr><tr><td>Open town contracts</td><td><code>/town contracts</code></td></tr><tr><td>Open a town vault</td><td><code>/town vault [number]</code></td></tr><tr><td>Reload CozyTowns files</td><td><code>/town reload</code></td></tr><tr><td>Toggle staff chat spy</td><td><code>/townadmin spy</code></td></tr><tr><td>Add XP to a player's town</td><td><code>/townadmin addxp_player &#x3C;player> &#x3C;amount> [silent]</code></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cozycrafters.net/plugin-docs/cozytowns.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.