MCSkylines-Vehicles

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.

Vehicles provides persistent cars, bicycles/motorcycles, buses, boats, airplanes, helicopters, registration titles, garages, ownership, approved drivers, fuel, hull/tire damage, towing, impound, parking, and NPC transit. Custom definitions control each vehicle's capabilities.

Registration, garages, and storage

1. Staff place a sign with [garage] on line one and choose CAR, PLANE, HELICOPTER, or BOAT in its chat prompt, using the garage creation permission.
2. Craft or issue a genuine registration title, hold it at the matching garage, open the garage and redeem it. One database-backed title can register one vehicle; copies share the same redemption.
3. Select the stored registration in a matching garage to deploy it. Clearance, type, owner/driver and region limits still apply. Boats locate a water surface within five blocks with room for the full hull.
4. Return an empty stationary vehicle to a matching garage to store it. Staff have separate force-storage commands.

Chunk unload serializes deployed state and restores when its coverage loads. Full restart returns deployed registrations to garage storage. Plate, ownership, authorized drivers, fuel, hull, tire damage and lifetime wreck count persist. A complete vehicle is never carried/placed as an inventory item.

Ownership groups: create a shared fleet

Vehicles stores a group name and checks the effective Bukkit permission `group.<name>`. It does not create or manage LuckPerms groups. Merely naming a LuckPerms group is insufficient unless its members receive that permission.

1. As permission staff, create or choose a group, for example policefleet.
2. Give that group group.policefleet; assign users to it or make their existing rank inherit it.
3. Before transferring, ensure the current owner will retain access through that permission. Target the deployed vehicle (or occupy it) and run /vehicle transfer group:policefleet with vehicles.transfer.
4. Type CONFIRM in the transfer prompt. The owner changes to the group and existing approved-driver entries are cleared. cancel abandons the prompt.
5. Members with group.policefleet can access the group registration in garages and exercise group owner rights. Treat this permission as fleet management authority, including locks, driver lists and permitted further transfers.

Example permission-provider setup (LuckPerms commands; requires LuckPerms administration):

/lp creategroup policefleet
/lp group policefleet permission set group.policefleet true
/lp user Alex parent add policefleet
/vehicle transfer group:policefleet

To retain personal ownership while sharing only driving access, use /vehicle drivers add group:policefleet instead. Individual delegation uses /vehicle drivers add Alex. Removing a user's effective group permission removes group-derived access; removing an approved-driver entry removes that delegation. These checks differ from Lock's transitive LuckPerms sign-group checks.

Entry, locks, and driver authorization

Right-click the intended seat to enter. Owners and approved player/group drivers are checked independently of region entry and class permissions. Lock/unlock uses owner authority. Driver-list access does not transfer ownership. Sneak-right-click opens management while outside the driving action menu. Cuffed suspects must be seated by police; clicking them again removes them while retaining restraints. An officer exiting does not uncuff/eject every restrained passenger. Occupants cannot fire weapons.

Seat targeting follows the model's tilt and articulated cabin. controls.seat-click-padding adds a small margin on every side (default 0.12 blocks, allowed 0–0.3). Aim at the nearest intended seat from the front or rear; the vehicle's broad body box does not obstruct its seats. Blocks, unrelated entities and your entity interaction reach still limit entry. Ordinary clicks that miss all seats do nothing. Explicit sneak management, water refills and police custody clicks retain their behavior. The old controls.seat-click-radius setting no longer selects seats. Out-of-place click boxes and passenger carriers are retried while parked without moving the vehicle.

Native artwork defaults to three ticks of position smoothing. Ground-model rotation also uses that duration, including wheels, articulated trailers, lamps and flat tires. This smooths turns as well as forward movement. Existing configs with the two-tick value need rendering.position-smoothing-ticks: 3, followed by /vehicle reload; allowed values remain 1-5. Aircraft rotors/propellers retain their one-tick animation timing. Leave physics.ticks-per-update: 1. The road hull, upright slope clearance, steering, traction and seat geometry are unchanged. Test turns in buses, tractors and emergency vehicles, including heading wrap, steep slopes, diagonal parked seats and articulated sections on your actual server.

Native road vehicles use rendering.native-seat-movement: true by default, even when an existing config omits the key. Invisible seat carriers follow the position resolved by vehicle physics through native entity positioning. Occupied seats request a normal movement update every physics step, without teleporting riders. This seat synchronization experiment needs an in-game comparison; it retains three-tick artwork smoothing, seat offsets, click targeting, handling, collision hulls and slope/slab clearance. Aircraft, boats and external model adapters keep teleport transport. World changes, moves of eight blocks or more, unloaded destinations and unsupported server internals use teleport fallback. An unsupported bridge logs one warning and uses fallback until restart. To compare with the previous behavior, set rendering.native-seat-movement: false and run /vehicle reload; the switch also applies to existing occupied vehicles.

Each stock road tire is attached to its exported body section: front tires follow the front body's movement and articulated rear tires follow their trailer. This removes separate tire-position teleports that can drift or snap during the body's interpolation, especially at high speed. Flat rubber follows its spinning hub. Rejected attachments are retried while parked without advancing wheel phase or physics. Wheel spin, three-tick smoothing, tire damage/contact geometry and the upright road collision hull are unchanged. Check fast straight driving, turns, articulated rear wheels, flats, slopes and stop/start motion in-game.

Road step-up checks follow the vehicle's heading through a turn. This lets an articulated bus's rear swing onto a climbable half slab without treating its clear starting position as already blocked. Long vehicles also include corner travel when choosing collision-check intervals. Supporting ground and headroom are still required for the whole front and rear hull. Walls, low ceilings, unloaded terrain and rises above physics.step-height-blocks remain blocked. Hull sizes, upright road clearance, tire attachments, wheel spin, three-tick smoothing, steering and traction are unchanged. Check rear half-slab turns in both directions, forward and reverse, together with full-block obstacles and low ceilings in-game.

Install the current combined Suite JAR and matching complete resource pack, preserving module folders, registrations and custom configuration. NPC routes use driving recordings; legacy waypoint files need to be recorded again. See NPC bus routes below.

Ground and boat driving

W accelerates, S brakes then reverses, A/D steer gradually, Jump holds the horn. Start/stop the engine with /vehicle on and /vehicle off from the driver seat. Sneak exits. F toggles cruise while moving forward at least 1 m/s with power and fuel. Braking, collision, driver/engine/fuel loss, towing, or punctured tires cancels cruise; boats also cancel out of water. A stranded boat has no land propulsion.

Ground driver seating escrows the original hotbar and installs a nine-slot action menu. Select a slot and right-click. Passenger inventories and air/sea controls keep their normal mappings. Step out before inventory or vehicle management operations; menu items cannot be moved/dropped/placed and pickups are blocked during the session.

Unsupported actions show Barrier. Clicking an active siren switches it off; selecting another changes mode. Emergency lights override utility lights and utility lights resume afterward. Sirens and lights are separate. Hotbar emergency actions accept vehicles.emergency, vehicles.police or justice.police; the legacy siren command checks vehicles.emergency or vehicles.police. Region siren restrictions still apply.

The saved hotbar is restored on exit, quit, death/recovery and shutdown using persistent serialized backup tags. Armor, offhand and storage beyond the nine hotbar slots are not replaced. Do not remove session/backup tags during recovery.

Road steps, slabs, and collision damage

Ground CAR vehicles follow supported road rises progressively during a movement update. Each individual rise is limited by the definition’s physics.step-height-blocks; several climbable half-slab treads can be crossed in one faster movement instead of treating their combined rise as a single wall. The path is checked in small, bounded increments for both wheel support and full-hull headroom.

A real wall, low ceiling, unsupported airborne approach or step above the configured limit still blocks movement and retains ordinary collision/damage rules. Use a sufficiently wide, supported road and verify the entire vehicle’s clearance. This does not change boat or aircraft movement, or exempt genuine high-speed impacts from damage. Test your actual road geometry and speeds on the updated server.

Airplanes: takeoff, flight, and landing

W raises throttle at 30 percentage points/second; S lowers it at 40. The selection holds when released, banking or changing flaps. Jump pitches up and Sneak pitches down; the selected attitude holds until changed. A/D bank and steer on the runway. Sneak exits only landed/nearly stopped. Engines without fuel/power provide no thrust.

F cycles Retracted → Takeoff → Retracted → Landing → Retracted. Takeoff flaps add moderate lift/drag and landing flaps add more; they do not hold speed/throttle. Rotation needs sufficient configured airspeed (about 1.2 times stall speed). Banking reduces vertical lift. High angle of attack adds drag and progressively loses lift: lower the nose to recover airspeed.

For landing, reduce throttle, use landing flaps, approach shallowly with level wings and gently flare. Safe stock touchdown accepts downward speed at most 6 m/s, bank at most 12 degrees, and pitch from 18 degrees nose-up to 10 degrees nose-down. Hold S on the runway to lower throttle and brake. Hard, banked arrivals and obstacles still cause damage. Clear the entire hull, including wings and tail. Flaps reset after a fresh spawn; displayed altitude is world Y, not height above terrain.

Helicopters and aircraft terrain

Helicopters use W/S for forward/back pitch, A/D bank/turn, Jump ascent and Sneak descent. Sneak exits only landed. Releasing forward input preserves momentum before coasting down. Cruise holds horizontal forward speed where supported. Police helicopter IR belongs to Justice; see its sensor guide.

Aircraft prepare terrain up to 48 blocks ahead and retain only needed airframe chunks. If terrain is unavailable, motion pauses while retaining velocity, throttle and attitude, then resumes when ready. Parking empty with the engine off, storage, unloading and shutdown release tickets. NPC buses share reference-counted tickets. Ordinary Utilities/Industry virtual machines do not use this aircraft behavior.

Fuel, hull damage, wrecks, and repair

Use the vehicle GUI with accepted genuine fuel in hand. Definitions specify capacity, consumption and fuel provider. Hull damage comes from physical collisions and real projectile paths, with region protection. Walls/living entities intercept weapon shots; tasers do not damage hull as bullets. The configurable damage.weapon-damage-multiplier defaults to 0.2 times weapon base damage, adjusted by impact resistance. Crash damage grows with impact speed squared beyond its threshold.

Wrecks cannot drive. Diagnose through an authorized mechanic GUI, supply its exact configured part, and use Repair. Hull repair percentages are bounded to 25% per configured part. Wreck limits and submersion/permanent-loss policies are configurable; a lost registration is distinct from a repairable wreck.

Tire punctures and replacement

Accumulating bullet damage

Bullets test actual wheel positions; hitting the body does not damage a hidden far-side tire. Every real WeaponMechanics projectile adds damage to the wheel it hits, including independent shotgun pellets. Each contribution is the weapon’s nonnegative Damage.Base_Damage, capped by damage.tire-projectile-damage-cap (configurable; default 5). This calculation is independent of hull damage multipliers and armor. A tire punctures when its accumulated damage reaches damage.tire-durability (configurable; default 12); its total cannot exceed that threshold.

Spread and obstructions still matter. WorldGuard vehicle-damage protection applies and tasers do not damage tires. Justice road spikes test each wheel’s swept contact and puncture immediately; they do not need to accumulate bullet damage. Both partial damage and flats persist per wheel through garage storage and restart. Repeatedly shooting an already-flat tire does not generate another puncture sound or a fresh flat.

Driving with flat tires

Front flats weaken steering more, rear flats reduce grip more, and uneven damage pulls toward the damaged side. Any flat cancels cruise. Added rolling drag and smooth bounded drift make even balanced flats unstable while moving; there are no random position jumps or instantaneous steering jolts.

The speed and acceleration factors decrease with the square of the remaining inflated fraction. With any flats, an additional absolute speed ceiling is 1 + 11 × (1 - flat fraction)² m/s. These are ceilings, not guaranteed travel speeds: the vehicle’s own speed limit, grip, engine, fuel and terrain can make it slower.

Each tire changes independently to its flat visual. An authorized mechanic holds one iron ingot and selects Repair on an empty stationary vehicle. Tire repair resets all flats and partial tire damage, including damage on wheels that have not punctured yet. Ordinary hull-part repair remains separate.

Towing and recovery trucks

With vehicles.tow, use an authorized configured recovery truck with sufficient capacity, parked ahead of an empty stationary road target facing the same direction. Target it and use /vehicle tow or /vehicle tow <plate>. The explicit plate handler searches nearby active vehicles within 20 blocks; the hitch-to-nose attachment check uses configurable towing.attach-range in impound.yml (default 12 blocks). Do not rely on the older 32-block advice.

The target follows visibly with its engine disabled, and obstacles stop the truck. The towing speed cap is configurable through towing.maximum-speed-mps in impound.yml: 12 m/s is the bundled default, not a fixed limit. For example, setting it to 20.0 gives a 20 m/s towing cap; the truck’s own performance, terrain and other speed restrictions can still make it slower. Targets cannot be boarded, stored, deleted, refuelled, repaired, transferred, or have access/controls changed while attached. Use /vehicle unhook on either vehicle to detach. Unloading/removing either or wrecking the truck disconnects the transient coupling.

Impound, fees, forfeiture, and city titles

1. Flag any chosen WorldGuard region impound-lot allow. This is a custom flag, not a required region name.
2. Bring the target's complete collision footprint into the lot and unhook it.
3. An officer with vehicles.impound.seize sneak-right-clicks the target, chooses Impound this vehicle, and confirms its plate. Selecting the truck selects the truck.
4. Original owners are notified; drivers are cleared and the registration is held under impound ownership.
5. Use a configured impound Citizens NPC or /vehicle impound to collect. Group members need group.<original-group> and group collection enabled. Collection requires vehicles.impound.collect.

Configurable fees.towing and fees.daily-storage in impound.yml default to $200 and $30 respectively. With those defaults, a started 24-hour storage period costs $230 immediately and $260 after 24 hours; changed fees change those totals. Fees are captured on impound. The confirmation names the exact amount/payment source. Wallet pays unless a debit card is held; a held card must be valid, owned and funded, with no cash fallback. Proceeds enter the treasury. Release returns the registration to its original garage ownership, not the NPC location.

After fourteen unpaid days the city owns the vehicle. Authorized staff issue /vehicle impound title <vehicle-uuid>; its holder right-clicks and confirms to claim the existing registration. reprint reissues the same outstanding serial, so duplicate papers cannot duplicate a car. Pending ambiguous payments recover using their original operation keys and block conflicting release/forfeiture; retain Economy and Vehicles journals together.

Parking meters and manual enforcement

WorldGuard coverage and setup

A meter’s physical location and its covered parking area are separate. Staff first define the intended bay as an ordinary existing WorldGuard cuboid or polygon region, including the correct vertical bounds. Stand where the meter should appear and use /parking admin create <id> <region>. For an existing meter use /parking admin region <id> <region>; space is an alias with the same required region argument. There is no radius argument.

The region must exist in the meter’s world, cannot be __global__, and can be assigned to only one meter. Occupancy tests the vehicle origin’s block position inside the live region geometry, including Y; it does not require the complete hull to fit inside. Editing the WorldGuard bounds changes coverage. A missing or deleted region provides no radius fallback and accepts no occupancy/payment. Rebind that meter to a valid region. Removing a meter does not delete the WorldGuard region.

Players right-click a meter or use /parking <meter-id>, choose the actual parked plate and duration, then confirm. Explicit payment is /parking <meter-id> <plate> <hours>, with integer hours from one to the configured maximum. The payer must be within six blocks of the meter and the vehicle stationary inside its region. The configurable meter defaults are $10/hour and at most 24 hours; a meter’s active parking.yml settings determine its actual price and limit. Renewals extend that plate’s time up to the maximum; a different car cannot inherit it. parking.yml stores meter positions, named region IDs, price and maximum hours.

Wallet charges enter Economy’s treasury through a recoverable operation key. Paid status belongs to that plate. Pending ambiguous payments stay fenced until recovery; staff can use /parking admin retry <id> after resolving the database/Economy issue. Technology MDT lists occupied unpaid/expired regions and rechecks their current plates when selected. Vacant meters and pending payments are excluded. Citations and towing remain manual.

Upgrading older radius-based meters

On loading a legacy meter with space.x/y/z/radius, Vehicles saves parking-radius-backup-<millis>.yml and creates a pass-through WorldGuard cuboid around the old bounding square, extending two blocks above/below the old center. Its name starts mcskylines_parking_<meter-id>, using _2 and further suffixes for unrelated name collisions. The region is persisted before the configuration is rebound; an interrupted retry reuses the same matching pass-through bounds. A failure preserves the existing configuration and payment/session records.

Review each migrated cuboid in WorldGuard: a square is not the old circular radius, and the vertical bounds are now significant. Adjust it or rebind to your intended existing region. Meter IDs, paid sessions and payment journals retain their identities; there is no money or session migration. Keep the configuration backup and database together when restoring an installation.

NPC bus routes

Recorded NPC routes use the normal vehicle physics, collision, audio and display systems. Traffic clearance and vehicle crashes compare the occupied, oriented hull sections, including the articulated rear. Empty corners of a long diagonal vehicle’s enclosing rectangle do not stop nearby vehicles. Actual hull contact still collides, and road hulls retain their level pose for slope/slab clearance. Racked bicycles are stored registrations with display-only cargo, outside the collision system. Keep physics.ticks-per-update: 1 and rendering.position-smoothing-ticks: 3. Existing format-2 recordings remain usable; service settings default to free boarding with one bus.

Operators need vehicles.bus.admin. Use a road vehicle with passenger seats, such as a city or articulated bus:

1. Sit in its driver seat at the intended starting position. Turn the engine on, stop, and unhook any tow connection.
2. Run /bus record start <route-id> [route name], for example /bus record start downtown Downtown Loop. The starting driver-seat position automatically becomes a seven-second boarding stop on every lap. Drive the actual road normally, including its turns and slopes; operate turn signals and hazards as you want the NPC to use them.
3. At each bus stop, bring the bus to a stop and run /bus record stop <stop-id> [stop name], for example /bus record stop station Central Station. The stop saves the driver seat where you are sitting, including the bus heading; line that seat up with the intended stop. Continue driving when ready. Stop IDs must be unique within the route.
4. Return the bus's reference position within one block of its starting position, stop, and face within 15 degrees of the original direction. Run `/bus record finish`. Passing near the start never ends the recording automatically. A driven loop is required; the automatic starting stop counts as the first stop.
5. Wait for the saved confirmation, then store your recording vehicle or drive it clear of the starting area. The NPC bus spawns only when its entire hull has room.

/bus record status reports the sample count. /bus record cancel discards the draft without replacing a saved route. Leaving the driver seat, dying, disconnecting or changing worlds cancels an unfinished recording. Starting a replacement recording pauses that route's NPC bus; its previous recording remains saved until the replacement succeeds.

The server records actual bus position, heading, pitch/roll, velocity, steering, driving inputs and signal selection (left, right, hazards or off) at each physics update—normally every 50 milliseconds. Replay uses those controls with the normal road acceleration, steering, grip, gravity, slab climbing, hull collision, tires and engine/horn/heavy-vehicle sounds. Replay corrects small horizontal drift every tick through the normal collision pipeline. Steering follows route progress and adjusts for slower replay speed, avoiding a held turn sample when braking delays the bus. Route progress measures horizontal travel with a separate vertical guard allowing one configured step height plus 0.1 blocks (at least 0.25 blocks). This lets adjacent slab treads settle at different ticks without holding an old sample; crossings on another level cannot advance the route. Forward lookahead probes the live hull elevation with the normal sweep and step-up checks. A replay brake cannot engage reverse unless the current or next recorded sample contains reverse motion. Its bounded horizontal corrections cannot override gravity, road height or slab climbing. The dense 50-millisecond samples preserve driving inputs; reducing their number is not a remedy for terrain stalls. It pauses for obstructions and resumes after clearance; it cannot find a detour around a changed road. Braking may carry the bus past a few samples, so replay rejoins only samples actually passed in its immediate recorded corridor, without skipping a stop. Signals follow route progress, so a traffic pause holds the current selection and resumes its recorded sequence. Blinking uses the normal lamp clock, rather than replaying individual flashes. Changes made during trimmed stationary time are not timed events: the marked stop keeps its selection and departure uses the selection captured when movement resumes. Older recordings have no signal data and default to off; rerecord to capture your original signal use. Use the same vehicle definition and physics settings used to record the route, and rerecord after changing handling or terrain.

The automatic start is named <route name> Start, with ID start (or start_2, etc. if that ID is already used). If the first sample is already a marked stop, it is reused instead of adding a second pause. Existing format-2 routes gain the start automatically on load. Initial typing/idle time is trimmed while retaining the departure input that produces the first moving sample.

Stationary samples immediately before and after each marked stop are trimmed and replaced with a fixed seven-second pause. Unmarked pauses remain part of the recording. The final approach blends the small closing gap over up to four recorded seconds without moving marked stops. Before boarding, replay aligns the driver seat horizontally within 0.05 blocks and the bus heading within 0.1 degrees, at no more than 0.1 m/s. Near-stop parking and live closing corrections are limited to 0.02 blocks and 0.15 degrees per tick and pass through normal collision checks. Terrain and suspension still determine seat height. The same bus entities and articulated trailer state continue through samples and laps; the route cursor never respawns the model at a point.

By default, one transient NPC-driven vehicle runs per saved route; positive headways can assign multiple buses. It participates in vehicle collision and normal movement/audio updates and retains the chunks needed by its full hull. Service buses have their own lifecycle and do not create owned registrations or debit fuel/durability storage. Riders need vehicles.bus.ride, granted by default. /bus list shows saved routes and stops. Aim at a passenger seat and right-click during a boarding pause or terminus wait. Clicking the body without aiming at a seat does not board, and the driver seat is reserved. Sneak-right-click never boards; sneak dismounts only while boarding is open. Stop positions use the driver seat, so the front bumper naturally extends ahead of the stop. Navigation receives that same driver-seat position through BusTransitApi; driving samples retain their normal hull reference coordinates.

Recordings persist in plugins/MCSkylines-Vehicles/bus-routes.yml with format-version: 2. New marked frames also save stop-seat-x, stop-seat-y and stop-seat-z. Existing format-2 recordings remain compatible: their driver-seat anchors are derived from the saved stop pose and current vehicle definition, without shifting the driven path or requiring rerecording. Saving uses an atomic replacement; a failed save leaves the previous file intact. Old waypoint routes are disabled and must be driven and recorded again. The old file is left untouched until the first successful recording save, which preserves a bus-routes-waypoints-backup-<timestamp>.yml copy. The old point commands and 55-block spacing rule no longer apply; waypoint coordinates cannot reconstruct steering, braking or road physics.

/bus route remove <route-id> removes a saved recording. /bus reload reads the file again, cancels drafts and recreates NPC buses, dismounting riders. Replacement recordings, route removal, reload and shutdown remove service buses safely; ordinary samples, stops and completed laps keep the same live bus. Make administrative changes with no riders aboard. Test your recorded route in game, especially the bridge, tight articulated turns, stops, road obstructions and several consecutive laps.

Passengers can board and leave during the seven-second stop dwell and while a fully stopped bus waits at its starting terminus for its headway slot. Voluntary dismounts are blocked enroute. Holding sneak shows the exit warning once; release and press again for another warning; death, disconnect and authorized staff/service cleanup can still remove a rider. Players within seven blocks of the hull see the nearest bus's boarding boss bar. Its final seven seconds drain one seventh per second; longer terminus waits show the actual remaining wait plus dwell. Departed remains visible for three seconds, then hides while enroute. Arriving appears in the final three recorded seconds before a stop; traffic and obstructions can delay the actual arrival.

Live BlueMap bus locations

When BlueMap is installed, the public Live buses map layer shows active NPC buses at their actual vehicle positions. Hover over a bus marker for its route ID/name, next stop and Boarding or Enroute status. Vehicles updates markers every 20 server ticks (one second at 20 TPS); BlueMap's browser refresh settings also affect how quickly changes appear. Each mapped world receives its own buses. Removed or out-of-service buses disappear from the layer, and route/module/BlueMap reloads clean up old markers.

The integration is optional and automatic; no new configuration or command is needed. Install a BlueMap version compatible with API 2.7.7. Map updates read detached positions and do not steer or move buses. BusTransitApi.liveBuses() supplies immutable numeric snapshots of active service buses; call it on the server's main thread before handing the snapshot to another thread.

Bus bicycle racks

City, articulated and prison buses have a front rack. Right-click its handle while stopped to fold or deploy an empty rack; a loaded rack stays deployed. Boarding automatically takes the nearest available bicycle that you own, or a group bicycle you can manage, within 10 blocks of the bus hull. It must be unoccupied, untowed and serviceable. The two visible slots face opposite directions. Additional riders' bicycles are safely stored aboard without another visible model; when a visible slot empties, the next carried bicycle becomes visible.

Getting off returns the same registration, ownership, fuel, durability and tire state to a clear, supported spot on the right side of the bus, preferring a raised sidewalk. Obstacles, other vehicles and spawn protections are checked. If there is no clear allowed space, the bicycle remains safe in normal vehicle storage. Death, disconnect, bus removal and restart cannot strand a separate rack-only registration or create a duplicate bicycle. A carried bicycle cannot also be spawned from a garage. Rack artwork and carried bicycles share the bus's display interpolation and ambient lighting, including night and tunnels. Looking toward the bumper from the side, above or below does not hide an attachment because its origin is at the bus's center. The rack does not extend the driving collision hull. The matching client pack keeps solid bus panels and floors opaque while preserving clear windows.

Pedal bicycle handling and repairs

Road and mountain bicycles use pedals: they have no ignition switch or fuel requirement. A serviceable bicycle can be ridden immediately; a wreck still requires repair. Riders keep their normal inventory instead of the car control hotbar, and bicycles have no cruise control, headlights, brake/reverse lamps, turn signals or damage smoke. Jump rings the bell. These rules also apply to renamed definitions using the native road/mountain bicycle model; motorcycles retain their engine and car controls.

Road bicycles default to 6.5 m/s, 1.4 m/s² acceleration and 0.025 crash-damage factor; mountain bicycles default to 5.5 m/s, 1.6 m/s² and 0.020. A one-time definition upgrade replaces only the old bundled values and preserves custom handling and sound keys. config-version: 2 marks that upgrade. Previously damaged bicycles' car-only repair requirements are converted on load. Bicycles use bike-chain, bike-brake-cable and bike-wheel from parts.yml; cars do not select those parts. Operators can supply genuine parts through /skylines give vehicles:part/<part-id>, then sell them through ordinary shops. Wheel puncture replacement still uses the existing iron-ingot mechanic.

The approved mcskylines:vehicle.bicycle.ride sound is quiet, spatial and movement-only. The client pack needs both assets/mcskylines/sounds/vehicle/bicycle_ride.ogg and bicycle_bell.ogg, plus the base vehicle.bicycle.* and all 64 audio.bicycle.<channel>.ride / .bell entries in assets/mcskylines/sounds.json. The complete Oraxen installer/client ZIP includes these; copying only models does not install the audio. Each eight-second loop retains its starting pitch until renewal, then adjusts to speed; stopping cuts only that bicycle's owned sound. The jump/horn control rings mcskylines:vehicle.bicycle.bell at pitch 1. A tap keeps the full tail; holding repeats every 40 ticks. Custom non-stock per-definition engine/horn event keys retain their existing playback path. Install the matching complete client pack for the slimmer bicycle artwork, rack items and audio. Pedal bicycles never start wreck fires; other vehicles use Fire's configurable 20% default chance.

Driver skins, fares and route headways

Use /bus route info <route-id> to see service settings. Operators can run:

/bus route fare downtown 2.50
/bus route headway downtown 60
/bus route skin downtown PlayerSkinName

/bus route fare 2.50 also works while riding that route, or when only one route exists. The same shortcut works for headway and skin. Set fare to 0 for free boarding. Set headway to 0 for one bus. Positive headways are seconds between scheduled starts: enough buses are assigned to cover the recorded loop plus all seven-second stops, and the cycle is rounded up to a whole number of headways. For example, a 201-second loop with a 60-second headway uses four buses and a 240-second cycle. Early buses wait at the start for their next slot. Ordinary laps keep the same bus and passengers. Shorter headways cannot force a bus to spawn through an occupied starting hull; start clearance and real traffic may delay service. The validation bound is 32 assigned buses per route.

With Citizens installed, the driver is a temporary human NPC seated in the driver seat. skin is a Java Minecraft username. A signed custom skin can instead use the optional texture and signature pair below. The human driver is excluded from player controls, rider fare prompts and passenger ejection. Before a Citizens despawn or skin replacement, the driver is detached while still alive. Its current entity is checked and remounted each physics step without rebuilding the bus; a removed player is never deliberately dismounted again during cleanup. Without Citizens, service uses the existing villager driver and logs that human skins need Citizens. Drivers are removed with their service bus and do not create persistent Citizens NPCs.

Paid boarding seats the rider, then opens Fare - COST, with a green Pay and red Evade button. The initial choice has 10 seconds; closing or ignoring it counts as evasion when that time expires. Pay immediately uses the wallet if no debit card is carried. With a card in inventory, Pay opens a Wallet / Debit card choice with its own 10-second deadline. No source choice defaults to wallet, including if the menu is closed or the rider leaves. A card must be the rider's signed active card; its checking account and bank reserves settle the fare. Revenue goes to government treasury as BUS_FARE. Nothing is withdrawn before Pay is accepted. Changing seats on the same ride does not create another fare. Accepted amounts and sources stay fixed for duplicate clicks and retries. Free routes skip the prompt and create no zero-value transfer. Finish an accepted or uncertain prior fare before boarding another paid bus; changing buses cannot replace its payment deadline or retry key.

Choosing Evade, ignoring the prompt, or leaving with an unanswered fare counts as evasion. By default the driver has a 10% chance to report each evasion once to carbon:dispatch. Reports contain the rider, route, coordinates and world; Carbon channel hearing permissions apply. When Carbon or the channel is unavailable, recipients with vehicles.bus.dispatch or vehicles.police receive the report and the console records it. A report does not automatically fine, restrain or add a wanted case. Submitted or uncertain payments are not reported as evasion while Economy checks their outcome.

Add service settings under the route, alongside name, world, vehicle and frames; retain every recorded frame:

format-version: 2
routes:
  downtown:
    name: Downtown Loop
    world: world
    vehicle: articulated-bus
    service:
      fare: '2.50'
      headway-seconds: 60
      stuck-seconds: 30
      driver:
        name: Bus Driver
        skin: Steve
        # Optional custom signed skin; provide both values together:
        # texture: '<base64 texture>'
        # signature: '<base64 signature>'
      fare-evasion-report-chance: 0.10
      dispatch-channel: carbon:dispatch
    # Keep the existing frames list here.

The snippet shows a paid example; omitted service settings default to fare 0, headway 0, stuck timeout 30, driver name Bus Driver, skin Steve, report chance 0.10 and channel carbon:dispatch. Edit plugins/MCSkylines-Vehicles/bus-routes.yml and run /bus reload, or use the commands to save atomically. Fare changes apply to future boardings and preserve accepted fare amounts. Changing headway or skin restarts that route's service and dismounts its riders; reload restarts all routes. Replacement recordings retain their existing service settings.

If a bus makes no route progress for the configured stuck timeout, it dismounts riders, removes its driver/model and releases its chunk tickets. Its replacement waits for that bus's next scheduled cycle at the starting stop, advancing to the next future cycle if several were missed. Other buses keep their slots. A blocked starting area postpones spawning safely; missed runs are discarded rather than bunched together. Seven-second boarding pauses and scheduled waits do not count as stuck time. Timetables start fresh after server restart or route reload; they are not wall-clock schedules saved across restarts. An out-of-service warning includes the route sample, live and target coordinates, driver readiness and the specific obstruction: a terrain/unloaded-chunk sweep, another vehicle’s definition/UUID/location, or a clear probe with no route progress. Recovery emits that diagnostic once when the bus leaves service.

Lights, horns, sirens, and audio

Native ground models display emissive signals, utility/emergency overlays, brake lights based on braking and reverse lights based on actual reverse motion. Left/right always refer to the driver's perspective; from the front they appear on opposite screen sides. The current complete pack mirrors signal placement across body/trailer sections and uses dedicated bus strips below the projectors. Emergency red and blue alternate rather than remaining solid.

Police equipment uses modern thin clear/white off lenses with colored illumination only when active and compact motorcycle fixtures. Unmarked sedans and undercover SUVs have discreet grille, rear, and upper-windshield visor modules. Marked sedans, SUVs, and vans have mirror modules and strips below the side doors. Each side assembly contains both colors so alternation is visible from either side. Red and blue alternate every five server ticks (a quarter-second at 20 TPS); review images may show both phases together to illustrate placement. Slot 5 utility lights reuse the supported fixtures in amber and default on for ground police equipment as well as configured service/tow vehicles; explicit features.utility-lights: false remains respected and installed definitions are not rewritten. Emergency lighting suppresses utility lighting temporarily, which resumes when emergency lights switch off. The matching plugin and complete client pack are required; restart after installing Java changes.

Custom model providers use visible particle fallbacks. Headlights project temporary level-14 road light up to configurable headlights.range-blocks in config.yml (default 18 blocks, fixed validation bounds 1–48), stop at solids, preserve placed blocks/water, and clean up through a recovery journal.

Native lamp overlays share the parent body or trailer display’s interpolated anchor, so enabling or blinking a lamp does not start a separate position animation ahead of the vehicle.

Ground vehicle bodies, wheels, trailers and lamps carry their full-precision heading in a shared display transformation, with ground display entity yaw held at zero. This avoids coarse passenger rotation that could partly bury lamps at particular headings. Wheel-pivot translations and trailer tilt use the same orientation; dark mounted lamps retain the parent transform without restarting movement interpolation.

The matching models correct buried side repeaters, motorcycle reverse lamps intersecting rear wheels, and a tractor headlamp intersecting its grille. Marked-sedan grille strobes retain matching neutral/on bounds; separate head/fog lamps, plate and trim keep their white surfaces. Push bars and metallic lens dividers remain physical obstructions and can cover neutral and active lens faces equally. Test headlights, amber utility and emergency lights at several headings both parked and driving. Source and geometry checks do not replace live Minecraft acceptance or frame-time measurement.

Amber utility lights alternate driver-left and driver-right in opposite five-tick phases, matching the cadence of emergency alternation (a quarter-second per phase at 20 TPS). Updated native models use utility_left and utility_right hooks. Emergency red/amber-left share one cached display slot, and emergency blue/amber-right share the other, keeping the same two slots instead of adding a second utility pair. Legacy custom utility hooks remain supported as a single blinking group; custom packs need the split hooks for side-to-side alternation. Emergency lights still override utility illumination, which resumes when emergency mode ends. Install both the matching plugin and complete client pack, restart for Java changes, and have players download the new pack. Approved sounds are unchanged.

Lamp overlays are created when first needed; hidden overlays are not repeatedly moved, and emissive brightness does not fight ambient refresh. Headlight world scans occur at most every four server ticks. Recovery-file writes use one serial background snapshot; world updates happen on the server thread only after the prior/new location union is saved. Slow disk can delay beams without blocking vehicle movement or accumulating stale work. Shutdown waits for pending recovery before saving final state. Live client measurement is still needed to certify frame times and perceived smoothness.

Engines, horns, heavy reversing/air-system effects, bicycles' chain/bell, signal clicks and tire punctures require the matching pack. Jump holds the horn for cars/boats, but is a flight input for aircraft. Only the ground driver hears signal clicks. Newly committed punctures play one nearby thump/hiss; already-flat hits and repairs are silent.

Police Wail/Yelp/Phaser have separately stopped leased sound channels; mode changes stop the old voice. Known police Yelp/Phaser renew every forty ticks, city Wail every 94 and fire Wail every 214. Blank mode keys mute configured audio. Heavy stationary engine shutdown or driver exit plays guarded air-brake feedback; stopping while seated does not. Sustained hard braking requires eight consecutive braking ticks, speed, deceleration, driver and tire support; start speed defaults to 3 m/s and every phase stops below 0.5 m/s. Configure sound keys/timing and thresholds in definitions; global signal/puncture keys can be blank to mute them.

Resource-pack installation and missing textures

Installing matching lighting models and plugin

Back up your plugin data and Oraxen pack sources, stop the server, and replace the combined JAR with MCSkylines-1.0.29.jar. Preserve module folders, registrations and custom definitions. This runtime update requires a restart.

If the current 1.0.13 complete asset pack is already installed, merge MC-Skylines-Vehicle-Lighting-Update-2026-10-08.zip into the server’s plugins folder. Its Oraxen/pack/assets/... prefix places the replacements at plugins/Oraxen/pack/assets/...; merge existing folders, preserving custom additions. The small update replaces model JSON only. Older asset baselines should use the matching complete Oraxen installer or complete client ZIP instead of this incremental update. Approved audio is unchanged.

Start the server, run /oraxen reload pack as an Oraxen operator (no extra arguments), and have players reconnect and download the regenerated pack. Verify stationary and moving lamps at different headings, automatic main-hand radar on foot, front/rear moving radar in an eligible police vehicle, and the actual slab roads used by players. A plugin reload cannot replace Java code or regenerate the client’s old pack.

Diagnosing magenta or black textures

Magenta/black police lenses or control/tire surfaces indicate a missing texture or an unresolved atlas reference. The corrected pack uses mcskylines:item/vehicle_lighting/<name> and mcskylines:item/control_palette/<name>. These keys resolve to assets/mcskylines/textures/item/vehicle_lighting/<name>.png and assets/mcskylines/textures/item/control_palette/<name>.png. Preserve the mcskylines namespace and the item subfolder when merging; moving PNGs without updating their model references does not repair the pack.

For the texture repair to the Suite 1.0.12 / Vehicles 1.9.3 pack:

1. Back up the current Oraxen pack sources and custom additions.
2. Apply the matching model-and-texture hotfix together. Its Oraxen/pack/assets/... prefix is relative to the server's plugins folder: extract there so files land in plugins/Oraxen/pack/assets/mcskylines/.... If merging manually, copy the patch's assets contents into plugins/Oraxen/pack/assets; avoid a second nested Oraxen or assets folder.
3. Preserve the rest of the complete curated pack, including approved audio. This hotfix replaces model texture references and adds the matching PNGs; it needs neither a new JAR nor replacement sounds.
4. Run the Oraxen operator command /oraxen reload pack (no additional arguments) to regenerate and redistribute the client pack. /vehicle reload does not rebuild resource-pack textures.
5. Reconnect, accept and download the refreshed pack, then check police lamps both off and on, amber utility lights, hotbar icons and flat tires. Ensure the server is distributing the newly generated pack, rather than an older hosted ZIP or cached download.

The corrected complete pack also includes this repair. Retained legacy PNG paths are compatibility copies; models use the atlas-visible textures/item paths above. A texture-only hotfix does not require resetting vehicle definitions, registrations or player inventories.

Definition files and integrations

config.yml owns database, limits, garages, hijacking, protections, sounds and physics workload. vehicles/*.yml owns class, dimensions, seats, model provider, fuel, durability, handling and capabilities. recipes.yml accepts shaped/shapeless and cooking/stonecutting recipes with exact custom ingredients; parts.yml owns repair pools. Staff edit through /vehicle admin and reload definitions/messages/recipes with /vehicle reload. Java changes require restart; retain custom files and database.

Bundled vehicle definitions are installed on first setup. Deleting a definition from an existing installation does not regenerate it on restart. Restore a missing definition from the matching distribution's defaults without deleting the main config.yml or database. Definition IDs identify saved registrations; changing the filename does not change ownership. Stop the server before renaming a definition, and rename rather than copy it: two files with the same ID are rejected. Normal bicycle filenames are supported; a filename suffix is not required. Definitions use config-version: 1, except the stock road and mountain bicycle definitions, which also accept revision 2 for their one-time handling/audio upgrade. Other configuration files still require revision 1.

WorldGuard flags independently govern vehicles-entry, vehicles-spawn, vehicles-damage, vehicles-hijack, vehicles-horn, vehicles-siren, and impound-lot. Configure Oraxen/ModelEngine IDs and use native fallbacks as supported. SQLite or MySQL stores authoritative registrations; APIs expose snapshots, custody, parking and transit.

Moving-radar capability

VehiclesApi.movingRadarEquipment(vehicleId) reports moving-radar eligibility separately from general police equipment. Its API default is false. Vehicles enables it only for a loaded police-equipped CAR whose definition ID and model ID do not contain motorcycle (case-insensitive), so renaming a stock motorcycle definition does not enable its radar. Eligible police ground drivers toggle moving radar with /radar; main-hand handheld radar operates automatically on foot. Police motorcycles retain their other emergency equipment. Justice checks this capability both when enabling radar and at HUD updates; custom API implementations must explicitly provide it.

VehiclesApi.movingRadarTarget(observerVehicleId, range) returns the fastest eligible front/rear ground-vehicle contact, its direction label and absolute speed. It takes the observing vehicle UUID; its default implementation returns empty. Its fixed horizontal half-angle is 30 degrees and it rechecks equipment, range and line of sight. This is separate from radarTarget(playerId, range), which takes a player UUID and supplies the handheld’s aimed nearest hull. Implementations must preserve that distinction; general police equipment alone does not imply moving-radar support. Both target queries must be called on the server’s main thread.

Hijacking

Use the genuine configured hijack kit on an eligible target. Remain within the configured distance throughout its channel; cancellation consumes the kit. Owner and police alerts follow configured messages, including queued owner notifications. Success changes ownership rather than granting a temporary driver slot. Region hijacking rules and disabled/impounded/towed states still apply. See config.yml for duration, probabilities, distance and limits before balancing theft.

Criminal captives and unconscious passengers

Passenger handling now asks Justice's canHandleRestrained(actor, target) main-thread API. Police may handle restrained suspects, and the captor may handle their own ziptied captive. Other criminals cannot take over police custody or someone else's ties. Normal right-click places/removes an eligible captive in a nearby passenger seat; sneak-right-click on a ziptied person leaves the gesture for Justice's criminal search menu. Health suspends unconscious floor anchoring within the nested Justice transport scope and while seated, so unconscious restrained passengers remain in the car. Removal retains restraints and restores their unconscious pose at the exit rather than a former escort location.

Vehicle logout detaches the passenger carrier before saving player data, clears transient ejection state and releases the seat for the next entry. Reconnecting does not restore an obsolete vehicle attachment.

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.

Vehicle commands

Unless specified, these target your occupied vehicle or the vehicle you look at within the configured range. Commands are player-only except admin storeall, which also accepts console. Aliases /car, /plane, /helicopter, /boat use the same syntax.

definition is a vehicle filename ID, such as commuter-sedan; owner is a username; vehicle-uuid is the full registration UUID suggested by title Tab completion; plate is the displayed license plate. Example: /vehicle admin grant commuter-sedan Alex.

Bus commands

Example: /bus route create downtown Downtown Loop; /bus stop add downtown hospital Hospital. Route IDs and stop IDs are stable identifiers, not arbitrary coordinate values.

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.

Parking commands

Example: define WorldGuard region main_street_bay, then stand at the meter and use /parking admin create main_street_1 main_street_bay. To rebind use /parking admin region main_street_1 replacement_bay. A user can pay with /parking main_street_1 ABC123 2 only when stationary plate ABC123 is inside the bound region, including its height, and the payer is nearby.