If you find a bug, have a suggestion or want to talk, feel free to join my Discord server! 

VehiclesLib is a library that makes it easy to add vehicles to the game.

This library supports boats, cars, motorcycles, helicopters, airships, flying brooms... You name it. Only thing not supported yet are airplanes.

How to use VehiclesLib?

VehiclesLib supports three types of fuel: gas, steam and temporal. There's also a "none" fuel for vehicles that don't need any fuel.

Refueling a vehicle is simple:

• For gas, just right-click your vehicle with a bucket filled with a valid fuel (in vanilla, only Aqua Vitae can be used in a gas engine). You can pick the fuel back up by shift+right-clicking the vehicle with a bucket.
• For steam, fill it with water by right-clicking it with a water bucket, then add any combustible (wood, coal... With the exception of peat, which doesn't work right now) to it and wait for it to heat up.
• For temporal, just right-click the vehicle with a valid temporal fuel (in vanilla, that's temporal gears).

To drive your vehicle, simply use WASD, and for flying vehicles, space and control.

To pick up a vehicle, dismount it, hold CTRL and right-click it. Note that not all vehicles can be picked up! Also note that picking up a vehicle will lose its fuel.

However, being a library, VehiclesLib adds nothing by itself. You'll need to install a mod that uses it to actually get something out of it.

Here's a list of the mods that use VehiclesLib:

- Jonas Cycle Zero

For modders: how does it work?

VehiclesLib adds a relatively simple JSON API to create your vehicles, giving you full control over wheels, steering wheels, propellers and seats (up to 16 seats can be added to a single vehicle). A documentation is on its way, in the meantime feel free to check out the mods that use it for reference, or to ask me on discord (@moby_dick, or over on my discord server)

Here's an overview of the JSON attributes you'll have to add to your entity (the entity's class should be EntityVehicle, or another class inheriting from that).

The specified values are the default values (except for seats and animation parts, they're empty lists by default), if you don't want to change them, you don't have to add them to the file.

"Attributes": {
  "VehicleProps": {
    "canBePickedUp": true, # Whether the vehicle can be picked up with ctrl+right click
    "density": 100.0, # Any density higher than 1000 will make the vehicle sink in water, lower will make it float
    "SwimmingYOffset": 0.45, # The vertical offset at which the vehicle will float, if it floats
    "topSpeed": 1.0, # The vehicle's top speed, not really in blocks/second somehow but pretty close
    "acceleration": 1.0, # The vehicle's acceleration. Higher values means it will reach its top speed faster
    "swivelAngle": 0.0, # The game's swivel angle. Apparently it's pitching up and down when moving?
    "groundMultiplier": 1.0, # The ground speed multiplier
    "waterMultiplier": 0, # The water speed multiplier
    "turnSpeed": 45.0, # The vehicle's turning speed, in degrees per second I think
    "movingTurnOnly": false, # Whether the vehicle can only turn when moving forwards and backwards (think wheels)
    "canStepUp": true, # Whether the vehicle can step up blocks
    "stepHeight": 1.1, # How high the vehicle can step up
    "canReverse": true, # Whether the vehicle can drive in reverse
    "canBrake": true, # Whether the vehicle can brake by pressing space. Recommended false for flying vehicles
    "seats": [ # The array of all seats
      {
        "isControllable": true, # Whether the seat can control the vehicle
        "angleMode": 1, # The angle mode of the seat. See values below.
        "lockBodyYaw": true, # Whether the player's yaw will be locked. Good for oriented seats
        "offset": { # The offset of the seat
          "x": 0,
          "y": 0,
          "z": 0
        },
        "suggestedAnimation": "sneakidle", # The animation the player will play on the seat. See values below.
        "parentPart": "", # Not implemented
        "aimPart": "", # Not implemented
        "maxAimAngle": 0.0 # Not implemented
      }
    ],
    "wheels": [ # The list of wheel parts for animation. Will rotate around their Z axis
      {
        "partName": "", # The model part name of the wheel
        "strength": 1.0, # The rotation speed of the wheel
        "enabled": true # Set to false to disable the animation
      }
    ],
    "steer": [ # The list of steering parts. Same attributes as wheels. Will rotate around their Y axis

    ],
    "propellers": [ # The list of propeller parts. Same attributes as wheels, will rotate according to engine speed and not ground speed. Will rotate around their Z axis

    ],
    "engineProps": { # The engine properties
      "fuelType": "gas", # The type of fuel. Can be none, steam, gas or temporal
      "idleConsumption": 0.05, # The background fuel consumption when not running
      "consumptionRatio": 1.0, # How fast fuel will be used when running
      "tankCapacity": 3.0, # How much fuel it can store, in litres
      "alwaysIdle": false # Whether it will use the idle consumption even when no player is on it
    },
    "pushStrength": 1.0, # Not implemented
    "idleSound": "", # The sound file path of the idle sound
    "engineSound": "", # The sound file path of the driving sound
    "useGravity": true, # Whether the vehicle should use gravity
    "canFly": false, # Whether the vehicle can fly
    "climbSpeed": 0.0, # How fast flying vehicles will go up
    "fallSpeed": 0.0, # How fast flying vehicles will naturally go down when unattended
    "poweredFlightOnly": false # Whether the vehicle uses fuel to fly
  }
}

Possible values for the angle mode are: (note that these affect the player's ability to aim at blocks)
- 0 : unafffected
- 1 : pushyaw, turn the player with the vehicle but allow him to still change its yaw
- 2 : push, turn the player in all directions but allow him to change its angles
- 3 : fixateyaw, fixate the mounted entity yaw to the  mount
- 4 : fixate, fixate all entity angles to the mount

Possible values for the suggested animation are (exhaustive list in the assets/game/shapes/humanoid/player game file):
idle, walk, sneakidle, climbidle, sitflooridle, sitidle

What to expect in the future?

VehiclesLib, though stable and usable, is still pretty early in its development cycle. Here are a few planned features:

Short-ish term:
- Exhaust particles (let your vehicle spawn particles when it's used)
- In-world assembly (build vehicles in-world a bit like translocators, great for vehicles that aren't meant to be picked up)
- Reverse speed modifier (let your vehicle run slower backwards, will probably replace "canReverse" to some extent)
-  Add stamina drainage capacity (let your vehicle drain stamina when used, instead of burning fuel or on top of burning fuel)

Mid term:
- Animation control (let your vehicle play different seraph animations depending on its speed)
- New fuel: Fire fuel (for when only a combustible is needed, without water)
- New fuel: Special (similar to temporal, but with an extra string attribute for custom fuel types)
- New fuel: Food (burns calories)
- Airplane support with a different controlling format
- Add the ability for vehicles to be affected by wind (maybe only when airborne)

Long term:
- Add an isThrottle attribute or a throttle mode (for throttle vehicles, forward/backwards will control the speed at which the engine will run, instead of the speed of the vehicle, so you'll be able to start the motor and just let it run without touching anything)
- Add support for carts and trailers, possibly also for drawing Rusty Shells artillery
- Add the capacity to have mounted turrets, special behaviors (like tilling soil, breaking foliage, harvesting crops, cutting trees...) and others