MCSkylines-Utilities

Configuration defaults: Values shown for operator-configurable settings are the bundled defaults, and can be changed in the module’s configuration or definitions. The server’s active settings take precedence, so costs, speeds, ranges, durations, chances, effects, recipes, limits and enabled features may differ. Command examples illustrate syntax; fixed mechanics and validation bounds are not configuration defaults.

Utilities supplies player-funded power/water, property meters, batteries, reservoirs, virtual fluids, machine access and electrical lamps. Industry registers production content in the same system. It is a configurable prototype; there is no free NPC supply or automatic treasury billing.

First grid and machine

1. Register the property in Property. The landlord owns its machines; tenancy/membership alone is insufficient.
2. Use /utilities types and /utilities blueprint meter to inspect the actual configured footprint. Build it, look at its controller and commission a unique meter ID.
3. Infrastructure staff create a named grid, then look at the meter and connect it.
4. Zoning staff stand in the intended machinery property and run /utilities industrial on. All non-meter machines need approval; registered street lamps may serve ordinary plots.
5. Build/commission a generator using its blueprint, deposit accepted fuel and verify its output. Add batteries for generated-energy reserves and waterworks/reservoirs for powered water supply.
6. Build/commission production/storage types and grant per-machine operators. Deposit inputs and explicitly start one recipe batch.

Example (using actual type IDs from your configured types list): /utilities commission meter workshop_meter, /utilities grid city, /utilities connect city. Do not use the administrative blueprint builder for ordinary player production: it places blocks directly and requires admin authority.

Implemented rules

• One meter per registered Property plot. The Property API's landlord/owner UUID owns the machines. Tenants are not automatically owners; grant them operator access if desired.
• Owners can add individual operators to each machine. Operators can use dashboards, deposit/withdraw resources, start/cancel batches, pause/resume machines, and create fluid links when authorized at both endpoints. They cannot manage operators or decommission machines.
• Owner changes revoke the old operator list and remove fluid links touching the affected machines. Access is checked again on every action, including already-open GUIs. Physical WorldGuard build rules still govern commissioning.
• Infrastructure staff connect property meters to named grids. Appliances and machinery inherit that meter's connection. Electrical lamp registration also requires the grid-connection permission.
• Grids contain no free supply and no NPC fallback. Generators consume player-delivered fuel. Batteries store only actual generated energy. Waterworks consume electricity and require the configured water-containing structure.
• All production machines, extraction machines, tanks, gas vessels, generators, batteries, and water facilities run virtually while their chunks are unloaded. Fluid transfers also work with both endpoints unloaded. There are no chunk tickets, forced chunks, or chunk-load requests in these plugins.
• Commissioning still requires one complete, physically loaded validation. Thereafter, loaded portions are rechecked without loading missing portions. Known damage pauses the machine; repairing a known-invalid machine requires a complete physical validation once. An entirely unloaded, previously validated machine continues from its saved record.
• Staff approve machinery plots with /utilities industrial on. All device types except property meters require an approved plot to commission and operate. Revocation pauses existing machines and routes without deleting stock. Meters and street lamps can serve ordinary properties.
• Production runs only in manually started finite batches. Inputs are reserved, progress pauses if power, authorization, valid structure, or output capacity is unavailable, and cancellation returns inputs. Nothing automatically starts the next batch.
• One simulation step is scheduled per 20 server ticks. Unloaded machines advance normally while the server runs; there is no elapsed-time catch-up after server downtime, slow computation, or a discarded stale calculation.
• Registered lamps draw their normal electrical demand even while unloaded. Their physical block states are updated only when already loaded. The plugin does not keep mobs, hoppers, redstone, or other vanilla systems ticking in remote areas.

Permissions

For an infrastructure department using LuckPerms, for example:

/lp group infrastructure permission set utilities.grid.connect true
/lp group infrastructure permission set utilities.grid.manage true

Grant utilities.plots.manage to the role responsible for industrial zoning. None of these department permissions grants access to machine stock. The owner manages per-machine access while looking at its controller:

/utilities access add PlayerName
/utilities access list
/utilities access remove PlayerName

Names resolve from online/cached players, without a blocking profile lookup; UUIDs are also accepted. Lists persist across restart. There are no automatic trust grants to the owner's previous delegates on a sale.

Controls

Right-click a commissioned structure near its controller to open its dashboard. Only the controller needs to be loaded for local GUI access. Sneak-right-click with a supported resource to deposit the main-hand stack. One portable fluid container holds 100 liters by default; its name and lore show the resource and quantity. Containers are tagged inventory items, not flowing Minecraft liquid blocks. Older tagged containers remain recognized after the display-text upgrade.

The vanilla GUI provides a colored nine-segment fill gauge, exact contents/capacity, percentage full, reserved ingredients, energy, progress, and status. It has paginated Contents, Recipes, and Connections tabs:

• Contents: left-click withdraws one item/container, right-click withdraws eight, and shift-left requests up to 64, subject to inventory space. Quantities smaller than one portable container remain stored.
• Network ports: choose Both, Input, Output, or Disabled. Modes control logical fluid routes; battery modes control charging/discharging. Manual deposits and withdrawals remain available.
• Auto-eject: turn off to retain fluid or energy reserves. The device can still receive input. Water held behind closed output controls is excluded from municipal supply.
• Contents lock: choose a permitted fluid for a tank, including while it is empty. Shift-click clears the lock. A different resource cannot replace existing contents without emptying them first.
• Connections: left-click enables/pauses a route; right-click increases its rate; shift-left decreases it; shift-right removes it. Rate edits require operator access at both endpoints. Displayed rates are configured maximums, not measured flow.
• Recipes: left-click starts exactly one batch. Separate buttons pause operation, deposit held resources, and cancel a batch.

These are Mekanism-inspired controls implemented with ordinary inventory slots and tooltips. They do not require a client mod/resource pack and do not add display entities. Port modes apply to logical endpoints rather than six physical faces; there are no animated fluid meshes or custom mod screens.

Both /utilities and /industry reach the shared command interface. Their reload subcommands refresh their respective message files:

/utilities help
/utilities types
/utilities blueprint <type>
/utilities commission <type> <unique-id>
/utilities open
/utilities deposit
/utilities withdraw <resource> [item-count]
/utilities start <recipe>
/utilities pause
/utilities resume
/utilities cancel
/utilities remove
/utilities link <source-id> <destination-id> <fluid> <liters-per-second>
/utilities links
/utilities unlink <link-id>
/utilities grid <name>
/utilities connect <grid-name>
/utilities disconnect
/utilities lamp add
/utilities lamp remove
/utilities industrial on
/utilities industrial off
/utilities survey
/utilities status
/utilities reload

connect and disconnect operate on the meter being looked at. industrial approves/revokes the property the staff member is standing in. link requires matching grids/worlds and operator access to both endpoints. A tank holds only one fluid/gas resource at a time; empty it to change contents. Transfer rates are bounded per link. Named IDs contain lowercase letters, digits, underscores, or hyphens and start with a letter.

Virtual operation and performance

An industrial designation is a persisted permission for machinery, not a chunk loader. The plugins never request or retain chunks. Normal players, spawn rules, or other plugins may still load areas; these plugins do not alter those rules. Bounds on registered machines, links, lamps, surveyed fields, and operators remain configurable. Every registered machine has a finite simulation cost even while unloaded, so zoning does not replace these limits.

The production, transfer, and power calculations run on one background worker using detached snapshots of the logical state. Only one calculation can be in flight. The main thread validates its revision and endpoint availability before applying any resource changes. Player actions, ownership changes, connections, and relevant chunk changes invalidate stale results. There is no growing work backlog and no concurrent mutation of Bukkit inventories.

YAML encoding, backup copying, and atomic state-file replacement run on a separate writer. The main thread captures snapshots, checks a bounded number of already-loaded multiblock portions, applies resource results, changes loaded physical blocks, and services GUIs. Those world/inventory operations cannot safely be run asynchronously through Bukkit. Fully unloaded structures skip physical block reads. Lamp block updates are queued with a per-tick limit; GUIs refresh only while open. No per-pipe-block fluid simulation, fluid entities, per-machine Bukkit repeating tasks, or world-wide block scans are used.

/utilities status reports the last background calculation time, stale-result count, approved plots, and zero chunk tickets. It does not measure the whole plugin's main-thread cost; profile the live server at your intended scale before raising limits. Snapshot capture, ownership checks, and result application still occur on the main thread.

Configuration and persistence

Messages and MiniMessage

Utilities creates plugins/MCSkylines-Utilities/messages.yml. It owns command replies, input errors, help, simulation statuses, dashboard titles, button names/lore, units, and default portable-resource item presentation. Industry creates its own messages.yml for its console and reload replies; Industry machinery uses the shared Utilities catalog.

All these templates support MiniMessage, including gradients and hex colors. Placeholders such as <machine>, <resource>, <amount>, and <prefix> appear in the bundled examples. Player names, identifiers, and other substituted strings are inserted as literal components; they cannot inject MiniMessage click events or formatting. Administratively configured markup is trusted.

/utilities reload requires utilities.reload (included in utilities.admin). /industry reload requires industry.reload (operators by default). Both work from console, refresh messages only, and retain the previous catalog when YAML or template types are invalid. Missing keys fall back to bundled defaults without overwriting customized files. Reopen a dashboard after changing its title; button text refreshes at the configured interval. Already-issued custom items keep their previous appearance but remain valid by resource identity.

Content presentation

Resources, machines, and recipes accept a MiniMessage display-name in their owning plugin's config.yml. Resources also accept an optional lore list and gauge-material. Omit lore to use item-lore from Utilities messages; set lore: [] to hide it. Resource lore supports <resource>, <amount>, and <unit>. Vanilla resource items retain their native item metadata; their configured display names are used in the dashboard.

resources:
    water:
        material: HONEY_BOTTLE
        unit: 100
        vanilla: false
        fluid: true
        display-name: '<aqua>City Water</aqua>'
        gauge-material: BLUE_STAINED_GLASS_PANE
        lore:
            - '<gray>Contents: <resource>'
            - '<blue><amount> <unit> per sealed container'

Runtime controls

interaction.target-range (default 6 blocks) controls command targeting, while interaction.controller-range (10 blocks) controls local machine access. performance.structure-audit-ticks defaults to 2, performance.save-interval-ticks to 200, and performance.dashboard-refresh-ticks to 20. Lighting budgets, registry limits, and geology settings remain configurable. Invalid numeric ranges, fractional integer values, malformed YAML, non-text lore, and non-boolean flags reject startup rather than silently substituting another gameplay policy.

The simulation step stays fixed at 20 server ticks so configured per-second power, quantities, and durations keep their meaning. Audit, save, and GUI refresh intervals do not change production speed. Increasing the save interval increases the amount of progress exposed to an unclean shutdown.

Machines, footprints, resource forms, storage sizes, generator output, fuel energy, recipes, durations, input/output quantities, and electrical consumption are data-driven. Blocks are relative x y z MATERIAL entries from the controller, with fixed world axes. AIR entries reserve required interior space. Default copper structures are waxed to prevent ordinary oxidation from disabling a plant.

Restart after editing definitions. The prototype intentionally does not hot-reload an in-flight factory. Active batches retain their original recipe snapshot so a configuration edit cannot silently change reserved ingredients. Removing an occupied machine definition or shrinking capacity below its contents/escrow fails startup without overwriting state. Cancel and empty machines before making incompatible changes. Keep geology field size stable once players start extracting resources.

State is saved every 10 seconds and on a clean stop to state.yml, with the previous snapshot in state.yml.bak. On a save failure the simulation and player mutations pause. Do not edit the state file while running.

This is an isolated-test-server release: snapshots are not a transaction shared with Minecraft's player-inventory files. An abrupt process/host crash can roll these files back to different moments. Crash-consistent item delivery needs further work before this should run an established economy. Normal batch cancellation, transfers, and clean restart persistence are covered by automated tests.

Integrations and remaining scope

• Core registers the resources under industry:<resource> for /skylines give testing.
• Fire's existing HydrantWaterProvider reports whether the hydrant property's grid has water. This initial bridge gates availability; the current Fire refill API does not debit measured water. Metered hydrant withdrawal is a follow-up integration.
• UtilitiesApi.consumeWater(location, liters) is provided for later brewing and other water consumers. Narcotics brewing has not been changed.
• This version controls registered redstone lamps. Universal vanilla-light conversion, custom lamp models, tanker vehicles, pressure physics, billing, pollution, and a complete downstream crafting economy are not implemented.
• Generic tanks and gas vessels currently use the same quantity-based storage rules. Materials, sizes, and appearance differ; they do not simulate pressure.
• Utility generation is continuous while enabled, consuming fuel even if surplus power cannot be stored. Waterworks stop when full. Batteries have per-step charge/discharge limits.

Build: gradlew.bat :Utilities:build :Industry:build. The automated suite covers finite batches, conservation, fuel/battery limits, blocked outputs, finite deposits, snapshots, persistence, migration, virtual operation, port/lock controls, gauges, configuration parsing, and owner/operator transitions. A source architecture test rejects chunk-loading/ticket API calls. Actual Paper GUIs, lighting, and unloaded-world behavior require the in-game acceptance pass.

Commodity appearance

The complete matching resource pack supplies native held models for water, steel, crude oil, diesel, naphtha, refinery gas, residue and polymer resin. Utilities assigns those models to the stock tagged commodities shared with Industry. Vanilla coal, iron and carbon keep their vanilla appearance. Reissue older items if needed; visual-only items do not carry resource metadata. Operator-defined commodity IDs retain their configured appearance. This changes items, not machine multiblocks.

Nitrogen, hydrogen, anhydrous ammonia and fertilizer also have textured 3D held models. All 17 bundled Utilities and Industry machine types have distinct dashboard status icons: the meter, coal generator, battery, waterworks, reservoir, tank, gas vessel, cold room, oil well, refinery, industrial furnace, polymer reactor, diesel generator, air separator, electrolyzer, ammonia reactor and fertilizer mixer. The fertilizer chain uses different silhouettes as well as colours. Operator-defined machine types retain the ordinary status material when no shipped icon exists.

These are menu icons for commissioned multiblocks. Build the actual structures from the live blueprints; the icons do not replace their blocks, footprints or validation. Preview them in the machine icon gallery. Editable Blockbench sources and regeneration instructions are maintained with the Agriculture artwork.

Machine faults and recovery

If commissioning fails, check controller target, complete loaded footprint including required AIR, property control, approval, unique ID and meter-before-machinery order. If a batch pauses, inspect power, resource reservations, output capacity, structure damage, grid/ACL and plot approval. Cancel returns reserved inputs rather than duplicating outputs. Empty stock, energy/fuel credit and active batch before owner-authorized decommissioning.

Ordinary server downtime does not create catch-up production. Unloaded validated logical machines continue only while the server runs, without ticking vanilla hoppers/redstone/mobs. Ownership changes revoke delegates and fluid links; reopen a dashboard and reauthorize new operators.

Bundled machine directory

Use the live blueprint for every coordinate and orientation; required AIR and WATER cells are part of validation. Capacities and power below are bundled abstract simulation units and can be changed by operators. All machines retain the owner/operator, zoning and same-grid requirements above.

Industry registers additional types, resources and finite recipes; see the Industry directory. A machine’s capacity does not create stock. Deposit genuine resources or produce them through a valid batch. The default portable water container carries 100 liters; a displayed commodity model alone does not confer resource identity.

Industrial containers

Custom industrial resources, including water containers and petroleum products, have no vanilla consumption action. They cannot be drunk or eaten, and attempts do not spend the supply. Ordinary vanilla items retain their normal use; machines and resource-transfer interactions remain available.

Refrigeration and cold rooms

Commission cold_room on an approved property using the existing meter, grid and operator rules. Its footprint is 0 0 0 PACKED_ICE, 1 0 0 IRON_BLOCK, and 0 0 1 IRON_BLOCK. It consumes 40 EU per simulation second while enabled, structurally valid and supplied. Successful steps add persisted cooling seconds through the revision-checked simulation; insufficient power adds none. This works with unloaded chunks and creates no chunk tickets. Agriculture recognizes storage within four blocks on each axis on the same property and slows spoilage to 25% of the ambient rate for actual powered intervals. Commission before stocking/opening the chest. Ice alone is not a refrigerator. Remove food before decommissioning to retain unsettled cooling credit. Integrations use opaque storage-location tokens, cumulative cooling time and genuine commodity-unit inspection.

The matching Agriculture client pack supplies distinct icons for the cold-room dashboard and the nitrogen, hydrogen, anhydrous-ammonia and fertilizer commodities. These icons do not change commissioned multiblock structures. Farming outside registered property is permitted according to Agriculture's land rules; Utilities water grids and refrigerator coverage still require their normal registered property and commissioning.

Machinery audio

The matching complete client pack supplies commissioned-machine sounds. Generation, pumping, cooling and processing are audible only after a productive simulation step is accepted on the server thread, including the final productive batch tick. Rejected calculations never start sounds. Fuel/power/input loss, full outputs, paused or removed machines and unhealthy state end activity; a 25-tick lease prevents a stalled worker from leaving audio running. Playback additionally requires the entire structure's chunks to be loaded, even for background-capable machines.

Batteries sound only during positive charge/discharge. Reservoirs, tanks and gas vessels sound on actual linked transfers, successful manual deposits/withdrawals or direct water draws. Idle storage and input delivery to an idle processor stay silent. Meters make one click after a successful manual enabled-state change.

Utilities config.yml owns sounds.enabled and sounds.types.<type> for both Utilities and Industry machines. Each entry provides enabled, sound, volume, range (blocks) and loop-ticks. Electrolyzer and fertilizer mixer use 80 ticks (four seconds); other industrial loops use 160 (eight seconds), all at pitch 1. Zero denotes a one-shot. Custom loop sound keys require .voice0 through .voice7 pack aliases. The first upgrade adds missing sound settings without replacing an existing operator section. Restart to apply audio settings; message reload does not reload them. Core's machinery-audio.enabled is the global switch and maximum-loops-per-listener defaults to three (allowed 1–8).

Farm and industrial loops share this listener budget, with a maximum of two per sound type, driver priority and nearby-selection hysteresis. Distinct listener/source slots keep a stop command from silencing another same-type machine. Moving out of range, world/chunk unload and shutdown stop the corresponding voices. Audio is transient, does not change resource accounting and never loads chunks or persists playback.

Reading command syntax

Configuration defaults: Values shown for operator-configurable settings are the bundled defaults, and can be changed in the module’s configuration or definitions. The server’s active settings take precedence, so costs, speeds, ranges, durations, chances, effects, recipes, limits and enabled features may differ. Command examples illustrate syntax; fixed mechanics and validation bounds are not configuration defaults.

<argument> is required; [argument] is optional. Replace the placeholder, including its brackets, with your value. Choices separated by a vertical bar mean choose one. ... accepts the remaining words. Do not type quotation marks around multiword names unless the command specifically requires them. A bare command has no required arguments. Examples use sample players/IDs: substitute entries from your server and use Tab for configured IDs.

player means a username; operational actions usually require that player online. amount and price are currency values such as 25.00, unless the row specifies items, levels, or units. reason, memo, message, name, and statement accept text where supported. duration uses the module's duration format (for example 10m, 2h, or 7d); it is not a bare number of minutes unless stated. id is the exact identifier displayed by that system, not its friendly name. Permissions and ownership/state/location checks both apply.

Shared machine commands

Both /utilities and /industry route to this interface. All gameplay commands require utilities.use and an in-game player; targeted stock/batch actions also require owner/operator ACL. Staff grid/zoning permissions do not grant stock access. Industry reload refreshes Industry messages; Utilities reload refreshes shared messages, not machine footprints/recipes.

IDs use lowercase letters/digits/underscore/hyphen and begin with a letter. Type, resource and recipe IDs come from config/types/resources/dashboard. Links use the listed generated ID. Example: /utilities link oil_storage refinery_input crude_oil 100. Fluid defaults use 100-liter portable containers, so withdraw water 2 requests two containers rather than two liters.

Root commands and aliases

These are the registered command entry points. The subcommand tables above describe their complete operations. Alias names use the same arguments as their root.