# Dreamvisitor

[Dreamvisitor](https://github.com/stonley890/Dreamvisitor/wiki)<span style="white-space: pre-wrap;">, created by Bog specifically for Wings of Fire: The New World, has a variety of features. It serves as an all-in-one utility plugin and Discord bot.</span>

## <span style="white-space: pre-wrap;">Commands</span>

<table id="bkmrk-command-description--1"><colgroup><col></col><col></col></colgroup><thead><tr><td>Command</td><td>Description</td></tr></thead><tbody><tr><td>`<span class="editor-theme-code">/aradio <message>...</span>`

</td><td>🛡️ 📗 Send a message to all operators.

</td></tr><tr><td>`<span class="editor-theme-code">/discord</span>`

</td><td><span style="white-space: pre-wrap;">📗 Toggle whether messages from the Discord chat bridge appear in your chat. This can also be adjusted with </span>`<span class="editor-theme-code">/dvset</span>`.

</td></tr><tr><td>`<span class="editor-theme-code">/dreamvisitor manage <key> [value]</span>`

</td><td>🛡️ 📕 View or modify the Dreamvisitor configuration.

</td></tr><tr><td>`<span class="editor-theme-code">/dvset</span>`

</td><td>📗 Manage your Dreamvisitor settings.

</td></tr><tr><td>`<span class="editor-theme-code">/hub [entities]</span>`

</td><td>🛡️ 📗 Teleport yourself entities to the hub location. If you have an entity on a lead, the entity will teleport with you below the normal hub location.

</td></tr><tr><td>`<span class="editor-theme-code">/invswap</span>`

</td><td>🛡️ 📗 Swap between two different inventories.

</td></tr><tr><td>`<span class="editor-theme-code">/itembanlist</span>`

</td><td>🛡️ 📒 Open the item ban list inventory GUI.

</td></tr><tr><td>`<span class="editor-theme-code">/moonglobe remove <players></span>`

</td><td>🛡️ 📗 Remove moon globes from players.

</td></tr><tr><td>`<span class="editor-theme-code">/moonglobe create <players> <location> <max_distance></span>`

</td><td>🛡️ 📗 Give players moon globes.

</td></tr><tr><td>`<span class="editor-theme-code">/panic</span>`

</td><td>🛡️ 📕 Kick all players and sets the player limit override to 0.

</td></tr><tr><td>`<span class="editor-theme-code">/parcel cancel</span>`

</td><td>🛡️ 📗 Cancel your current parcel delivery.

</td></tr><tr><td>`<span class="editor-theme-code">/parcel locations add <position> <name> <weight> <home_tribe></span>`

</td><td><span style="white-space: pre-wrap;">🛡️ 📗 Add a delivery location. </span>`<span class="editor-theme-code">name</span>`<span style="white-space: pre-wrap;"> cannot contain spaces, but underscores will be replaced with spaces when displayed to players. </span>`<span class="editor-theme-code">weight</span>`<span style="white-space: pre-wrap;"> determines the likelihood of the location being chosen. At 0, it will never be chosen. At 4, it is quite likely to be chosen. </span>`<span class="editor-theme-code">home_tribe</span>`<span style="white-space: pre-wrap;"> determines only which names will appear on parcels to or from this location.</span>

</td></tr><tr><td>`<span class="editor-theme-code">/parcel locations remove <name></span>`

</td><td>🛡️ 📒 Remove a delivery location.

</td></tr><tr><td>`<span class="editor-theme-code">/parcel locations list</span>`

</td><td>🛡️ 📗 List all mail delivery locations.

</td></tr><tr><td>`<span class="editor-theme-code">/parcel delivery terminal <players></span>`

</td><td>🛡️ 📗 Give a player a parcel or allow players to deliver parcels to a location within 10 blocks.

</td></tr><tr><td>`<span class="editor-theme-code">/parcel delivery add <players> <start> <end></span>`

</td><td>🛡️ 📗 Create deliveries for players.

</td></tr><tr><td>`<span class="editor-theme-code">/parcel delivery remove <players></span>`

</td><td>🛡️ 📗 Cancel deliveries for players.

</td></tr><tr><td>`<span class="editor-theme-code">/parcel delivery list</span>`

</td><td>🛡️ 📗 List ongoing deliveries.

</td></tr><tr><td>`<span class="editor-theme-code">/pausebypass add <players></span>`

</td><td>🛡️ 📗 Allow players to chat even when chat is paused.

</td></tr><tr><td><span class="editor-theme-code">`/pausebypass remove <players>`</span>

</td><td>🛡️ 📗 Disallow players to chat when chat is paused.

</td></tr><tr><td><span class="editor-theme-code">`/pausebypass list`</span>

</td><td>🛡️ 📗 List players allowed to chat even when chat is paused.

</td></tr><tr><td>`<span class="editor-theme-code">/pausechat</span>`

</td><td>🛡️ 📕 Suppresses messages from players and the Discord chat bridge.

</td></tr><tr><td>`<span class="editor-theme-code">/playerlimit [new_limit]</span>`

</td><td>🛡️ 📕 Override the server player limit.

</td></tr><tr><td>`<span class="editor-theme-code">/radio <message>...</span>`

</td><td>🛡️ 📗 Send a message to all other players who can access the radio.

</td></tr><tr><td>`<span class="editor-theme-code">/sandbox <player> [on|off]</span>`

</td><td>🛡️ 📒 Manage players' access to Sandbox Mode.

</td></tr><tr><td>`<span class="editor-theme-code">/setback <players> [location] [rotation] [world]</span>`

</td><td>🛡️ 📗 Set a player's last EssentialsX location. If no world is specified, the current world is assumed. If no rotation is specified, none will be applied. If no location is specified, the execution position will be used.

</td></tr><tr><td>`<span class="editor-theme-code">/setmotd [new_motd]...</span>`

</td><td>🛡️ 📗 Change or reset the server MOTD.

</td></tr><tr><td>`<span class="editor-theme-code">/softwhitelist add <player></span>`

</td><td>🛡️ 📗 Add a player to the soft whitelist.

</td></tr><tr><td>`<span class="editor-theme-code">/softwhitelist remove <player></span>`

</td><td>🛡️ 📗 Remove a player from the soft whitelist.

</td></tr><tr><td>`<span class="editor-theme-code">/softwhitelist list</span>`

</td><td>🛡️ 📗 List all players on the soft whitelist.

</td></tr><tr><td>`<span class="editor-theme-code">/softwhitelist on</span>`

</td><td>🛡️ 📗 Enable the soft whitelist.

</td></tr><tr><td>`<span class="editor-theme-code">/softwhitelist off</span>`

</td><td>🛡️ 📗 Disable the soft whitelist.

</td></tr><tr><td>`<span class="editor-theme-code">/synctime [world]</span>`

</td><td>🛡️ 📗 Sync time across all worlds.

</td></tr><tr><td>`<span class="editor-theme-code">/tagradio <tag> <message></span>`

</td><td>🛡️ 📗 Send a message to all players with a given tag.

</td></tr><tr><td>`<span class="editor-theme-code">/togglepvp</span>`

</td><td>🛡️ 📗 Toggle whether PvP is enabled or disabled.

</td></tr><tr><td>`<span class="editor-theme-code">/tribeupdate <players></span>`

</td><td>🛡️ 📗 Update the permission groups of a player based on their tribe.

</td></tr><tr><td>`<span class="editor-theme-code">/velocity <entities> <vector> [replace]</span>`

</td><td>🛡️ 📗 Apply velocity to entities.

</td></tr><tr><td>`<span class="editor-theme-code">/unwax</span>`

</td><td>🛡️ 📗 Unwax the sign you are looking at.

</td></tr><tr><td>`<span class="editor-theme-code">/user <player></span>`

</td><td>🛡️ 📗 Get details of a player, online or offline.

</td></tr><tr><td>`<span class="editor-theme-code">/zoop</span>`

</td><td>🛡️ 📗 Sends a fake leave message to Discord and hides you from the list command.

</td></tr></tbody></table>

## Auto-Whitelist

The whitelist functionality is built to handle whitelisting players completely automatically.

When a user on Discord sends a username in the whitelist channel, Dreamvisitor will first check to see whether the player is marked as banned. If so, they will not be allowed to add players to the whitelist. Dreamvisitor will then check if the username is legal. Minecraft usernames are alphanumeric (including underscores). If the message is not alphanumeric, Dreamvisitor will take no action. This also occurs if the Mojang API cannot find the provided username.

If the username *is* valid, Dreamvisitor will first fetch the UUID of the username and add it to `accountLink.txt`, which tracks which Minecraft UUIDs are connected to which Discord Snowflake IDs. A new entry will be recorded every time, unless the UUID has already been registered. This means that a Discord account can be linked to multiple Minecraft accounts, but not the other way around.

Dreamvisitor will then check whether the account is already whitelisted. If they are not, they are added to the whitelist. Either way, the user will be directed to check the FAQ for the IP.

For both Discord whitelisting and web whitelisting, any new user added to the whitelist will be recorded in the guild's system logs channel.

## Item Banlist

`<span class="editor-theme-code">/itembanlist</span>`<span style="white-space: pre-wrap;"> will open a chest-like inventory. Items placed in this container will be saved in their place and players with matching items will have them automatically removed from non-operator player inventories. </span>**This removal is permanent.**<span style="white-space: pre-wrap;"> Be cautious of items you add. </span>**Items are only removed if the data is an exact match.**<span style="white-space: pre-wrap;"> If you put a potato into the blacklist GUI, potatoes that have been renamed or enchanted will not be removed.</span>

![](https://raw.githubusercontent.com/Stonley890/ItemVoid/main/ItemVoidDemoSmall.GIF)

A demonstration of the item blacklist.

## Soft Whitelist

<span style="white-space: pre-wrap;">The soft whitelist acts as a secondary whitelist that works much like Minecraft's built-in whitelist feature. This allows reducing the allowed players to a specified group while not modifying the main whitelist. Players with the </span>`<span class="editor-theme-code">dreamvisitor.nowhitelist</span>`<span style="white-space: pre-wrap;"> permission will always bypass the soft whitelist. </span>**Operators will always bypass the soft whitelist.**

The soft whitelist persists through restarts.

## Sandbox Mode

**Sandbox Mode**<span style="white-space: pre-wrap;"> is a feature that allows administrators to safely allow players to use Creative Mode. When a player is put into Sandbox Mode, their inventory is swapped, and they are put into Creative Mode with the following restrictions:</span>

- They cannot access containers.
- They cannot drop items.
- They cannot use spawn eggs.
- They cannot teleport.

<span style="white-space: pre-wrap;">A player with the </span>`<span class="editor-theme-code">dreamvisitor.sandbox</span>`<span style="white-space: pre-wrap;"> permission — usually an admin — must be online for Sandbox Mode to remain active. If all admins leave, all players in Sandbox Mode will have it removed, restoring their inventories. If players leave the game while in Sandbox Mode, they will remain in Sandbox Mode when they rejoin unless there are no admins. When a Sandboxed player joins, admins will be notified.</span>

[![demo.GIF](https://docs.woftnw.org/uploads/images/gallery/2025-02/demo.GIF)](https://docs.woftnw.org/uploads/images/gallery/2025-02/demo.GIF)

## Pause Chat

<span style="white-space: pre-wrap;">The </span>`<span class="editor-theme-code">/pausechat</span>`<span style="white-space: pre-wrap;"> command will stop all incoming chat messages from being broadcasted. It will also block messages from </span>`<span class="editor-theme-code">/me</span>`<span style="white-space: pre-wrap;"> and Discord pass-through. You can allow certain players to bypass this with </span>`<span class="editor-theme-code">/pausebypass</span>`<span style="white-space: pre-wrap;">. Players with the </span>`<span class="editor-theme-code">dreamvisitor.nopause</span>`<span style="white-space: pre-wrap;"> permission will always bypass chat pause. </span>**Operators will always bypass chat pause.**

Chat pause will persist through restarts.

## Moon Globes

<span style="white-space: pre-wrap;">Moon Globes can be created with the </span>`<span class="editor-theme-code">moonglobe</span>`<span style="white-space: pre-wrap;"> command.</span>

<span style="white-space: pre-wrap;">A player may only have one moon globe at a time. Each moon globe has an origin and a maximum distance. By default, the maximum distance is 256 blocks. If a moon globe (not the player) moves beyond that distance, it will be removed. It will also be removed if the player moves to a different dimension. It will </span>*not*<span style="white-space: pre-wrap;"> be removed if the player disconnects, though it will disappear until the player reconnects. Moon globes are not saved, so they will be deleted upon a server shutdown.</span>

## Mail System

Players can earn money by delivering mail. Players may interact with a mail terminal to receive a parcel. They will be assigned a location to deliver it to, and they must interact with the terminal at that location without teleportation to get a reward based on the distance.

<span style="white-space: pre-wrap;">When a player interacts with a terminal (a command block with the command </span>`<span class="editor-theme-code">/parcel terminal @p</span>`<span style="white-space: pre-wrap;">), Dreamvisitor will choose a random end location with each location weighted by an inherent, preset weight, and the distance from the start location, weighing closer locations higher than further ones. The distance weight can be multiplied using the </span>`<span class="editor-theme-code">mailDeliveryLocationSelectionDistanceWeightMultiplier</span>`<span style="white-space: pre-wrap;"> option in </span>`<span class="editor-theme-code">config.yml</span>`.

The player will be given an enchanted book that they must keep with them until they complete the delivery. The book will be addressed to a random name. There is a 45% chance that the name will be of the tribe associated with the start location, a 45% chance that the name will be of the tribe associated with the end location, and a 10% chance that the name will be of a random tribe. A random lore string will also be chosen from a preset pool. If the player does not have the parcel when they reach the destination location, they delivery will not be completed and they must re-obtain the parcel or cancel the delivery. If a player cancels their deliver while they still have the parcel, they will keep the parcel.

<span style="white-space: pre-wrap;">When a player completes a delivery, the parcel will be removed from them, and they will be given a reward based on the distance between the start and end location, multiplied by </span>`<span class="editor-theme-code">mailDistanceToRewardMultiplier</span>`<span style="white-space: pre-wrap;"> in </span>`<span class="editor-theme-code">config.yml</span>`.

## Command Scheduler

The Dreamvisitor Command Scheduler is a powerful system for automating server tasks at specific times or intervals. It supports running individual commands or sequences of commands with configurable delays between them.

#### Key Features

- Multiple schedule types: Run commands at intervals, daily at specific times, or using cron patterns
- Command sequences: Execute multiple commands in order from a single schedule
- Configurable delays: Add pauses between commands in a sequence
- User-friendly commands: Simple interface for managing schedules

### Getting Started

#### Prerequisites

The command scheduler is included in the Dreamvisitor plugin. Make sure you have the appropriate permission:

```
dreamvisitor.schedule
```

### Schedule Types

The scheduler supports three types of scheduling patterns:

#### Interval-based Schedules

Runs every X minutes.

**Example:**

```
/schedule interval backup 120 save-all
```

This runs the save-all command every 2 hours (120 minutes).

#### Daily Schedules

Runs once per day at a specific time.

**Example:**

```
/schedule daily restart 03:00:00 restart

```

This runs the restart command every day at 3:00 AM.

#### Cron-style Schedules

Uses cron patterns for more advanced scheduling.

**Example:**

```
/schedule cron resource-reset "0 0 * * 0" world reset resource

```

This reloads the resource world at midnight every Sunday.

##### Cron Pattern Format

The pattern follows the standard cron format: minute hour day-of-month month day-of-week

- minute: 0-59
- hour: 0-23
- day-of-month: 1-31
- month: 1-12
- day-of-week: 0-6 (Sunday to Saturday)

##### Special characters:

- \*: any value
- ,: value list separator
- -: range of values
- /: step values

##### Examples:

- 0 0 \* \* \*: Every day at midnight
- 0 \*/2 \* \* \*: Every 2 hours
- 0 0 \* \* 1-5: Every weekday at midnight
- \*/10 \* \* \* \*: Every 10 minutes

### Command Reference

#### Creating Schedules

- Interval Schedules
    
    ```
    /schedule interval <name> <minutes> <command>
    ```
- Daily Schedules
    
    ```
    /schedule daily <name> <time> <command>
    ```
    
    Time format must be HH:MM:SS (24-hour format)
- Cron Schedules
    
    ```
    /schedule cron <name> <pattern> <command>
    ```
    
    Pattern must follow cron format (see above)

#### Managing Schedules

- List All Schedules
    
    ```
    /schedule list
    ```
    
    Shows all schedules with their next run times
- Remove a Schedule
    
    ```
    /schedule remove <name>
    ```
    
    Deletes a schedule completely
- Run a Schedule Immediately
    
    ```
    /schedule run <name>
    ```
    
    Executes a schedule now

#### Managing Commands in a Schedule

- Add a Command
    
    ```
    /schedule add-command <name> <command>
    ```
    
    Adds a new command to an existing schedule
- Remove a Command
    
    ```
    /schedule remove-command <name> <index>
    ```
    
    Removes a command from a schedule by its index

<p class="callout info">Command indexes start at 1 (not 0).</p>

#### Managing Delays

- Add a Delay
    
    ```
    /schedule add-delay <name> <index> <seconds>
    ```
    
    Adds a delay before executing the specified command
- Remove a Delay
    
    ```
    /schedule remove-delay <name> <index>
    ```
    
    Removes a delay from the specified command

### Command Sequences

You can create sequences of commands that run in order by separating commands with semicolons (;).

**Example:**

```
/schedule daily server-restart 04:00:00 broadcast Server restart in 10 minutes!;broadcast Server restart in 1 minute!;broadcast Server restarting NOW!;restart
```

This will:

- Broadcast "Server restart in 10 minutes!"
- Broadcast "Server restart in 1 minute!"
- Broadcast "Server restarting NOW!"
- Restart the server

All at 4:00 AM each day.

You can also add commands to an existing schedule:

```
/schedule add-command server-restart broadcast The server is restarting for daily maintenance
```

### Delays Between Commands

For more precise control, you can add delays between specific commands in a sequence:

```
/schedule add-delay server-restart 1 540
/schedule add-delay server-restart 2 50
/schedule add-delay server-restart 3 10
```

This would modify our example to:

- Broadcast "Server restart in 10 minutes!"
- Wait 540 seconds (9 minutes)
- Broadcast "Server restart in 1 minute!"
- Wait 50 seconds
- Broadcast "Server restarting NOW!"
- Wait 10 seconds
- Restart the server

The delay is applied before the command at the specified index runs. Indexes start at 1 for the first command.

### Common Use Cases

#### Resource World Reset

Reset resource worlds automatically every Sunday at midnight:

```
/schedule cron resource-reset "0 0 * * 0" broadcast Resource world will reset in 5 minutes!;world reset resource
```

Add a longer delay:

```
/schedule add-delay resource-reset 2 300
```

#### Daily Backups

Create a daily backup schedule:

```
/schedule daily backup 02:00:00 broadcast Starting daily backup...;save-all;backup start
```

#### Server Restart

Schedule a restart when the server is quiet:

```
/schedule daily restart 04:00:00 restart
```

### Technical Reference

#### Storage Location

All schedules are saved in the schedules.yml file in the Dreamvisitor plugin folder.

#### Format of schedules.yml

The schedules.yml file uses a structured format to store all scheduled tasks. Here's the basic structure:

```yaml
schedules:
  schedule-name:
    type: [interval|daily|cron]
    # For interval schedules:
    interval-minutes: 120
    # For daily schedules:
    time: "04:00:00" # HH:MM:SS
    # For cron schedules:
    pattern: "0 0 * * 0" # minute hour day month weekday
    commands:
      - "command1"
      - "command2"
    delays:
      2: 30 # 30 second delay before command at index 2
    last-run: 1234567890 # Unix timestamp
```

Each schedule must have:

- A unique name identifier
- A type (interval, daily, or cron)
- Type-specific configuration (interval-minutes, time, or pattern)
- A list of commands to execute
- Optional delays between specific commands
- A last-run timestamp to track when it last executed

The CommandScheduler loads this configuration at startup and whenever schedules are modified through commands.

### Troubleshooting

#### Schedule Not Running

- Check if the schedule has been created with /schedule list
- Verify the server has permission to run the commands (check console for permission errors)
- For daily schedules, ensure time format is correct (HH:MM:SS)
- For cron schedules, validate the cron pattern is correct
- Check the server log for any errors related to the CommandScheduler
- Verify the system time on your server is accurate
- Check that schedules.yml hasn't been manually edited with invalid syntax

#### Commands in Sequence Not Running

- Check if there are syntax errors in any command
- Ensure delays aren't too long
- Verify command permissions
- Look for error messages in the console when the schedule runs
- Make sure commands that require a player don't use @p in a server context
- For commands with selectors, ensure they have the appropriate permissions

#### Invalid Cron Pattern

Common cron pattern mistakes:

- Not having exactly 5 parts
- Using values outside the valid ranges (e.g., minutes &gt; 59)
- Incorrect format for ranges or steps
- Missing required fields or using incorrect special characters

Use these valid pattern examples for reference:

- `0 4 * * *` - Every day at 4:00 AM
- `*/15 * * * *` - Every 15 minutes
- `0 0 * * 0` - Every Sunday at midnight
- `0 0,12 * * *` - Every day at midnight and noon