New Server Commands
These commands are new to Hack/Mine as of version 0.6 (now available as a development build.) Smart name matching has been added as well, so players can be searched for via the first few letters of their name, both case and 1337 insensitively.
If chunkX and chunkZ aren't specified, the player's current chunk is assumed. Dimensions may be -1, 0, 1, or 10 for the Nether, the surface, the End, and the mystery dimension respectively. The surface is assumed when not specified.
Chunk coordinates can be calculated from block coordinates if they're divided by 16 and floored (e.g. block coords of (26, -113) are inside chunk (1, -8)). Your current position in block coords can be found by opening the debug menu with F3 and taking "x" and "z" (your height being "y").
Useful tip: F9 will toggle a "Chunk Grid" on your radar when at maximum zoom. Good for fast chunk flaggin'.
|spawn||Teleports the player to spawn (if enabled in server.properties)|
|who [player]||Gives the name, class, race, level, and op status of the specified player (or yourself if the player isn't specified).|
|flags [<chunkX> <chunkZ> [dim]]||Spits out all flags on the chunk (pvp enabling/disabling, block protection, mob/animal spawning)|
|roll | rand | random [die size]||Spits out a random number in chat from 1 - <die size> (100 if none is given).|
|get <property>||Tells you what the current value for a property in server.properties or areaCache.properties is. Property lookup is case-insensitive.|
|set <property> <value>||If possible, updates the value of the property in server.properties or areaCache.properties and applies it to the game immediately. Not all properties can be set for security or stability reasons (like ip-address or generate-structures) Property lookup is case-insensitive.|
|reward <player> (<amount> <cur> | mobdrop <mult>)||Gives some currency to the player. If "mobdrop" is specified, it gives them a typical amount of gold from a monster of the player's level, times <mult>. Otherwise, it gives the player <amount> of <cur>, where <cur> is p, g, s, c, platinum, plat, gold, silver, or copper.|
|penalize <player> (<amount> <cur> | mobdrop <mult>)||Removes currency from the player (will report amount actually removed if they have less).|
|setspawn [<x> <z>]||Sets the spawn point to the given block coordinates (uses your current position if not specified)|
|<flag> [<chunkX> <chunkZ> [dim]]||<flag> may be protect-blocks, unprotect-blocks, prohibit-pvp, allow-pvp, default-pvp, no-mobs, spawn-mobs, no-animals, spawn-animals. Block protection prevents blocks from being dug, placed, or explodinated by non-ops, whereas prohibit-pvp and allow-pvp override the server's default pvp settings for that chunk. Explosions on the border of a protected chunk will not effect blocks inside it. Using unprotect-blocks and default-pvp will clear their respective effects. The mob/animal commands prevent or reinstate spawning for that creature type (though they can still wander into the chunk or spawn from mob spawners.)|
|clear-all <flag>||Removes the flag from all chunks; <flag> may be protect-blocks, prohibit-pvp, allow-pvp, pvp, no-mobs, no-animals, flags. When entered, the console will ask you to confirm the command by reinputting it within 20 seconds.|
|resize-ac [newsize]||Resizes the area cache (to the minSize in areaCache.properties if not specified). If shrinking, an area size higher than the number of players is recommended.|
|reset-ac [newsize]||Entirely cleans the area cache and resizes it (to the minSize in areaCache.properties if not specified). May fix lag if the server's acting up. Again, if shrinking, an area size higher than the number of players is recommended.|
Flagged chunk data is saved to "flaggedChunks.txt" and can be edited while the server is off for quick flagging. Possible flags are protect-blocks, allow-pvp, prohibit-pvp, no-mobs, and no-animals.
The Area/Chunk Cache
"areaCache.properties" contains advanced settings for Hack/Mine's area cache, and fine-tuning them may improve performance and stability for your H/M server. The in game "get" and "set" commands available to Ops are the best way to perform quick experimentation, and additionally disallow you from setting your values to anything ridiculous. Also, Frizzil needs people to mess with it in hopes of finding better numbers (if you screw it up or aren't sure about your changes, just delete the file and H/M will generate a new one for you.) Fine-tuning is really only necessary if your server is at 20+ people. However, the larger your server is, the more significant fine-tuning your area cache will become. You'll want to enable "verboseLogging" when experimenting and disable it otherwise, to avoid console clutter. If you find settings that work, post them along with your system and server specs on the discussion page!
Things to consider when tuning, from most to least important: How fast is my file I/O? What's the speed on my CPU? How much RAM do I have?
Basically, the area cache is a place in memory where Areas are stored for quick access. A "cache miss" is when a request is made for an area that isn't in the cache, resulting in it being loaded from disk and into the cache-- you're trying to minimize these as much as possible, since file I/O is VERY expensive (unless you've got SSD like a boss!) Obviously, areas must be loaded at least once, but the trick is storing areas that will likely be used again and removing those that won't to make room. More recently referenced areas are kept, whereas less recently referenced ones are removed. A larger cache helps, but results in slower "victim selection" (selection of an area to remove on a cache miss), and at extreme sizes results in general lag and high RAM consumption.
Each tick, the ratio of cache entries that have been recently used is calculated and stored in "pctUsage." The exponential average of this number is stored in "avgPctUsage." I.e. avgPctUsage is set to avgPctUsage * w + (1-w) * pctUsage each tick, where w is "avgPctUsagePastWeight" This gives several important numbers for you to tweak-- avgPctUsageMax and pctUsageMax, which "grow" the cache when exceeded by their respective variables, and "avgPctMissPastWeight", which is "how significant are past values?" and effectively smooths out avgPctMiss as it approaches 1.00 (at 20 ticks/second, slight variations of this number from the default make dramatic differences.) You'll probably want this number to start around .99, making extremely marginal changes until you get a "memory" of usage that feels right. If your past weight is too low, your cache will be too sensitive to fluctuations and cause too many cache resizings, causing negligible to extreme lag (depending on how large your cache is and how badly you undershot it). If your past weight is too high, your cache will be too resilient to fluctuations, resulting in "area thrashing" if the need for areas exceeds the size of the cache, causing needed areas to be saved and loaded with each tick (This will cause massive lag and may also crash your server.) pctUsageMax generally prevents this if avgPctUsageMax doesn't catch it. Finally, you have avgPctUsageMin, which "shrinks" the cache when it can support that low of a usage when shrinking (iow, when avgPctUsage < avgPctUsageMin/growthFactor) Basically, fine tune these numbers to get the perfect amount of responsiveness to cache usage, only growing and shrinking when necessary to accurately support the needs of players.
When the cache "grows" or "shrinks", it takes a moment to copy it's data into a new, larger or smaller location in memory, respectively. "growthFactor" determines how much larger or smaller this location should be than the last location. Larger values result in less copying and hence lag, but more poorly associate the right cache size with your needs. E.g. a factor of 2 makes for little copying but potentially twice the resources consumed than needed if you just barely trigger a growth. Values closer to 1 may result in good matching of resources, but will result in excessive copying and more lag in response to quickly increasing needs, especially at larger cache sizes.
For you fellow computer science geeks, the area cache uses an aging page replacement algorithm (except not pages), using a 64-bit "age" for each cache entry, shifting once every tick (about 20 times a second) further reading. The "growthFactor" tradeoffs are directly associated with that of a dynamic array's.
|minSize||64||The size to initialize the area cache at. Not bad to set it higher if you have a large server, to avoid the lag of resizing. Each player will need at least one area at any time, but players also frequently inhabit the same area, resulting in overlap.|
|verboseLogging||false||If set to true, will spit info out to the console every twenty ticks and whenever there's a cache resizing. Extremely useful during testing, extremely annoying otherwise.|
|avgPctUsageMax||.90||Triggers a "grow" when exceeded by "avgPctUsage." The percentage leftover (1-avgPctUsageMax) could be thought of your safety buffer; the larger it is, the less likely you'll have "area thrashing" before the avgPctUsage reflects the actual demand for areas.|
|pctUsageMax||.999||Triggers a "grow" when exceeded by "pctUsage." The percentage leftover (1-pctUsageMax) could be thought of as another safety buffer; the larger it is, the less likely you'll have an area unnecessarily reload before the tick is done and the pctUsage can be calculated. pctUsageMax is generally a safety net, and should be set to a very high value you're certain reflects an increased need for areas.|
|avgPctUsageMin||.70||Triggers a "shrink" when "avgPctUsage" < avgPctUsageMin/growthFactor. The difference between avgPctUsageMax and avgPctUsageMin could be thought of as another safety buffer; the larger it is, the less likely you'll have "twitchy" resizings as usage fluctuates (imagine min and max were the same, and the avgPctUsage were fluctuating around that number)|
|growthFactor||2.0||The relative amount to increase or decrease the cache's resources by when a "grow" or "shrink" occurs. E.g. 2.0 would double the existing cache size with each growth and halve it with each shrink.|
|avgPctUsagePastWeight||0.999||The weight to give to the past "avgPctUsage" when calculating the exponential average. Should be between .85 and 1.0. Basically, it determines the "quality" of avgPctUsage, smoothing it out with prior miss ratios. Too low and your cache will be too sensitive to fluctuations, causing excessive resizing and potentially crashing your server if bad enough-- too high and your cache is too resilient to immediate usage needs, growing only when it's too late and thus causing lag of Biblical proportions, also potentially crashing your server.|
|emergencyResetSize||131072||An upper bound on your cache size that, once exceeded, forces the area cache to entirely reset (like the "/reset-ac" command.) Basically, set it to an amount you know will never be exceeded, like 50 times the maximum players on your server (since a player isn't liable to need more areas than can appear on their radar, 50 areas per player is an incredibly generous estimate you can be 99.999% certain is the result of erroneous growth.)|
Remember to test this stuff out! If you're testing with a large player base, gradually make changes and see how they go so you don't piss everyone off. Take notes even-- save old "areaCache.properties" and write notes at the bottom of it, so you can go back to good settings once you've found them. Finally, good settings on one machine aren't necessarily good another, especially if the system specs are drastically different (SSD vs Harddisk, low-end CPU vs monster CPUs, etc)
And most importantly, enjoy speeding up your server and improving its stability!