Entities GUI

The Entities GUI allows controlling what entities are saved and also allows modifying entity track distances.

Entities GUI image

Entity names and groups

Entities are named based off of the internal savegame ID. This may not seem too familiar, but they generally match with the actual names*.

Entities are further grouped into 3 major categories: "Hostile", "Passive", and "Other". Hostile entities are all monsters, passive is all animals (excluding squid), and other is anything else.

^{*Exceptions: SmallFireball is a fire charge shot from a dispenser; Fireball is a ghast fireball. LavaSlime is actually a magma cube. And VillagerGolem is an Iron Golem.}

"Special" entities

Certain entities have special properties. These entities are usually one type of entity being used for a non-standard purpose, for example invisible invulnerable flying armor stands with a custom name being used to generate holograms.

These entities are put into the same Entity List GUI with the other entities, and can be separately identified. When an entity is about to be removed, various potential conditions are checked and the entity will be judged based on the special type as needed.

Type selection is achieved using the api, with implementations of ISpecialEntityHandler. There is 1 implementation already built-in, for enabling/disabling Holograms. You can see the code for it in HologramHandler.java.

Enabling/disabling entities

The main purpose of this GUI is to enable or disable entities. You can do this in two ways: either selecting the button next to the entity, which toggles it from being enabled or disabled; or you can toggle an entire group. Toggling a group still saves your settings for each individual entity, and you can re-enable the group and have your old values still there.

What are track distances?

When a player walks too far from an entity, it will visually disappear. However, this is separate from the entity despawning - the entity will reappear if you get closer to it, so it never was actually removed. But, when the entity is hidden from view, it is actually also removed from the client*. What World Downloader does is save an entity when it is unsent, so that it's still present in the downloaded copy of the world.

But, how does one distinguish from a entity getting unsent and an entity actually being killed by a player? You wouldn't want all of the creepers you killed to come back in the downloaded copy, nor would you want TNT to be respawned after it has exploded. The answer is relatively simple - if the entity is over a specific distance from the player, it must have been unsent rather than killed.

Those distances vary by entities - farm animals are unsent before players, and similar. Fortunately, most of this data is easy to get (already stored in the client version), so the default values are easy to get. Just check the distance for the entity, and save or allow death as needed.

"But," you might ask, "why do I need to see these numbers? Why can I edit them?"

Well, it's actually not that simple. Some custom servers (namely, spigot servers) change these ranges. While this doesn't reduce lag for the server (it still keeps track of all of the entities), it helps improve client framerates. The default values used under spigot are much shorter than the vanilla ones, but still fairly simple (split into passive, hostile, and ... groups). Now, World Downloader can guess whether the given server is spigot or not**. And when it is spigot, the default spigot track distances work, which are correct most of the time. But for the servers that do change track distances, incorrect ranges result in no entities being saved.

There are two solutions to this. The best solution is to have custom servers send this data (some do using the plugin channels system), but not all servers will do this. So, the second solution is to allow manually changing these values.

^{*Technically, these are separate processes. If you move up vertically, an entity will stop rendering but will not be unsent. Only horizontal movement is considered for the unsending of entities. **The server's brand is sent to the client in the MC|BRAND plugin channel packet. Most servers do send this packet, and all spigot servers include spigot in the brand.}

Using track distances

There are two* options for ranges: Default and User. The "Track distance" button choses between them.

To manually set ranges, you must set the mode to "User". Then, the sliders will become enabled. You can manually drag the sliders or select "Range presets" to chose from some of the defaults.

^{*In some cases, 3 - server is also an option. However, server is only present on servers that send the ranges, and default uses server when posible, so it's still efectively 2. I may want to change default this so that it's less silly...}

Range presets

Entity range presets GUI image

The range presets sub-gui allows reseting your user ranges to one of several built-in range options. There are 3 options: vanilla minecraft's ranges (for vanilla servers and some Bukkit servers), the default spigot ranges (for spigot servers), and server ranges (for the servers that send range information). The last option is only available on some servers.