On this page
Overview
What is tickforge-global.yml?
tickforge-global.yml is the primary configuration file for TickForge. It controls server-wide performance tuning, gameplay tweaks, network protection, console formatting, MOTD, and tab list branding. This file is generated automatically on first launch inside the config/ directory.
Reload Without Restart
Most keys in this file can be reloaded at runtime using /tf reload. Keys marked with * in the tables below require a full server restart to take effect.
File Location
Where to find this file
The file lives inside the config/ directory that TickForge creates in your server root.
FILE PATH
<server-root>/config/tickforge-global.yml
Migrating from Paper?
If you previously used paper-global.yml, TickForge automatically migrates compatible keys on first launch. A backup of your original file is saved to config/legacy-backup/.
Performance
tickforge-performance
Controls entity processing, merge behavior, and server profile presets. These keys have the most direct impact on TPS and MSPT.
| Key | Type | Default | Description |
|---|---|---|---|
| server-profile | enum | CUSTOM |
Applies a predefined profile that auto-tunes the settings below. Options: CUSTOM, VANILLA_PLUS, BALANCED, AGGRESSIVE. |
| max-entity-ticks-per-world | int | -1 |
Maximum entities processed per tick per world. Lower values reduce lag spikes from entity-heavy areas. -1 for unlimited. |
| max-tile-entity-ticks-per-world | int | -1 |
Maximum tile entities (hoppers, furnaces, etc.) processed per tick per world. -1 for unlimited. |
| skip-inactive-entity-AI | boolean | false |
Skip AI ticks for entities that no player can see. Reduces CPU usage in loaded but unvisited chunks. |
| item-merge-radius | double | 0.5 |
Merge item entities within this radius (in blocks) to reduce entity count. Lower means less merging. |
| experience-merge-radius | double | 3.0 |
Merge experience orb entities within this radius (in blocks). |
| inactive-entity-AI-interval | int | 20 |
Interval in ticks between inactive entity AI updates. Higher saves CPU but makes mobs less responsive when first seen. Only applies when skip-inactive-entity-AI is true. |
YAML
tickforge-performance:
server-profile: CUSTOM
max-entity-ticks-per-world: -1
max-tile-entity-ticks-per-world: -1
skip-inactive-entity-AI: false
item-merge-radius: 0.5
experience-merge-radius: 3.0
inactive-entity-AI-interval: 20
Server Profile Presets
When a profile other than CUSTOM is selected, the values above are overridden automatically:
| Key | VANILLA_PLUS | BALANCED | AGGRESSIVE |
|---|---|---|---|
| max-entity-ticks-per-world | -1 |
300 |
200 |
| max-tile-entity-ticks-per-world | -1 |
256 |
128 |
| skip-inactive-entity-AI | false |
true |
true |
| item-merge-radius | 0.5 |
1.0 |
2.0 |
| experience-merge-radius | 3.0 |
3.5 |
4.0 |
| inactive-entity-AI-interval | 20 |
40 |
60 |
Profile Behavior
VANILLA_PLUS keeps vanilla behavior with light optimizations, ideal for small SMPs. BALANCED is a good default for most servers. AGGRESSIVE trades some vanilla accuracy for maximum performance on large servers. Set to CUSTOM to manually control every value.
Gameplay
tickforge-gameplay
Quality-of-life and gameplay tweaks for players and operators.
| Key | Type | Default | Description |
|---|---|---|---|
| coordinates-action-bar | boolean | false |
Show a coordinates display in the action bar. Players can toggle individually with /tf coords. |
| show-death-coordinates | boolean | true |
Show a death coordinates message to players when they respawn, telling them where they died. |
| max-entity-interaction-range | double | -1.0 |
Maximum distance in blocks a player can interact with entities. -1 uses the vanilla default (6.0 blocks). |
| max-block-place-range | double | -1.0 |
Allow players to place blocks beyond the normal range up to this distance. -1 uses the vanilla default (4.5 blocks). |
| auto-restart-tps-threshold | double | -1.0 |
Automatically restart the server when TPS drops below this threshold for more than 60 seconds. -1 to disable. |
| low-tps-warning-threshold | double | -1.0 |
Broadcast a warning to online players when TPS drops below this value. -1 to disable. |
YAML
tickforge-gameplay:
coordinates-action-bar: false
show-death-coordinates: true
max-entity-interaction-range: -1.0
max-block-place-range: -1.0
auto-restart-tps-threshold: -1.0
low-tps-warning-threshold: -1.0
Network
tickforge-network
Connection limits, logging, and packet protection settings.
| Key | Type | Default | Description |
|---|---|---|---|
| max-connections-per-ip | int | 0 |
Maximum concurrent connections allowed per IP address. Helps prevent simple bot attacks. 0 to disable. |
| max-latency-before-kick | int | -1 |
Kick players whose average latency exceeds this value (in ms) for more than 30 seconds. -1 to disable. |
| log-player-ips | boolean | true |
Log player IP addresses in the console. Disable for privacy compliance. |
| verbose-connection-logging | boolean | false |
Log connection and disconnection events with detailed info (protocol version, client brand, etc.). |
| max-packet-size | int | -1 |
Maximum packet size in bytes the server will accept before dropping the connection. -1 uses the default. |
YAML
tickforge-network:
max-connections-per-ip: 0
max-latency-before-kick: -1
log-player-ips: true
verbose-connection-logging: false
max-packet-size: -1
Console
tickforge-console
Controls the startup dashboard and console output formatting.
| Key | Type | Default | Description |
|---|---|---|---|
| startup-dashboard | boolean | true |
Show the startup summary dashboard after the server finishes loading. |
| system-tags | boolean | true |
Use color-coded system tags in console output (e.g. [Chunks], [Network], [Plugins]). |
| actionable-warnings | boolean | true |
Show actionable suggestions alongside warnings instead of raw technical output. |
YAML
tickforge-console:
startup-dashboard: true
system-tags: true
actionable-warnings: true
MOTD
tickforge-motd
Replaces the server.properties MOTD with a rich, rotatable server-list description powered by MiniMessage formatting.
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true |
Enable the TickForge MOTD framework. When disabled, the server.properties motd is used instead. |
| lines | list | see below | MOTD entries shown in the server list. Each entry supports up to 2 lines separated by \n. Supports MiniMessage formatting. |
| rotate | boolean | true |
When true, rotate through MOTD entries on each server ping. When false, always use the first entry. |
YAML
tickforge-motd:
enabled: true
lines:
- "<bold><gradient:#F97316:#FB923C>TickForge</gradient></bold> <gray>- Performance-tuned Minecraft</gray>\n<gray>Fast, clear, operator-friendly.</gray>"
rotate: true
Tab List
tickforge-tablist
Branded tab list header and footer with live placeholder support. Supports MiniMessage formatting.
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true |
Enable branded tab list header and footer for all players on join. |
| header | string | see below | Tab list header shown above the player list. Supports MiniMessage and placeholders. |
| footer | string | see below | Tab list footer shown below the player list. Supports MiniMessage and placeholders. |
| update-interval-seconds | int | 30 |
How often (in seconds) to refresh the header/footer. Set to 0 to only send on join. |
Available Placeholders
{server_name}, {player_count}, {max_players}, {tps}, {mspt}
YAML
tickforge-tablist:
enabled: true
header: "<bold><gradient:#F97316:#FB923C>TickForge</gradient></bold>"
footer: "<gray>Players: </gray><#FB923C>{player_count}</#FB923C><gray>/</gray><#FB923C>{max_players}</#FB923C> <dark_gray>|</dark_gray> <gray>TPS: </gray><#FB923C>{tps}</#FB923C>"
update-interval-seconds: 30
Reference
Full Default File
Below is the complete tickforge-global.yml as generated on first launch with the CUSTOM profile (all defaults).
Don't Copy-Paste Blindly
If you select a server profile other than CUSTOM, the performance values are overridden automatically. Only override keys you understand.
TICKFORGE-GLOBAL.YML (DEFAULTS)
Click to copy
# TickForge Global Configuration
tickforge-performance:
server-profile: CUSTOM
max-entity-ticks-per-world: -1
max-tile-entity-ticks-per-world: -1
skip-inactive-entity-AI: false
item-merge-radius: 0.5
experience-merge-radius: 3.0
inactive-entity-AI-interval: 20
tickforge-gameplay:
coordinates-action-bar: false
show-death-coordinates: true
max-entity-interaction-range: -1.0
max-block-place-range: -1.0
auto-restart-tps-threshold: -1.0
low-tps-warning-threshold: -1.0
tickforge-network:
max-connections-per-ip: 0
max-latency-before-kick: -1
log-player-ips: true
verbose-connection-logging: false
max-packet-size: -1
tickforge-console:
startup-dashboard: true
system-tags: true
actionable-warnings: true
tickforge-motd:
enabled: true
lines:
- "<bold><gradient:#F97316:#FB923C>TickForge</gradient></bold> <gray>- Performance-tuned Minecraft</gray>\n<gray>Fast, clear, operator-friendly.</gray>"
rotate: true
tickforge-tablist:
enabled: true
header: "<bold><gradient:#F97316:#FB923C>TickForge</gradient></bold>"
footer: "<gray>Players: </gray><#FB923C>{player_count}</#FB923C><gray>/</gray><#FB923C>{max_players}</#FB923C> <dark_gray>|</dark_gray> <gray>TPS: </gray><#FB923C>{tps}</#FB923C>"
update-interval-seconds: 30
Download
Download Default Config
Grab the full default tickforge-global.yml file to use as a starting point or reference.