> For the complete documentation index, see [llms.txt](https://mavenverse.gitbook.io/mavenverse-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mavenverse.gitbook.io/mavenverse-docs/freecarts/overview-and-installation.md).

# Overview & Installation

FreeCarts is an advanced transportation and vehicle management system for Minecraft servers. It transforms vanilla minecarts into steerable vehicles with custom physics, progressive upgrades, fuel networks, virtual garages, and autonomous autopilot navigation.

## System Requirements

| Component       | Minimum Requirement                   | Notes                                                               |
| --------------- | ------------------------------------- | ------------------------------------------------------------------- |
| Server Software | Paper, Purpur, or Spigot 1.17 - 26.3+ | Paper or Purpur strongly recommended                                |
| Java Runtime    | Java 17 or higher                     | Matches modern Minecraft server standards                           |
| PacketEvents    | Version 2.11.2 or higher              | Required for client-side WASD input and packet display entities     |
| Economy Engine  | Vault + Economy Provider              | Optional; required for fuel and upgrade transactions                |
| Custom Entities | MythicMobs                            | Optional; custom hostile mob detection and evasion during autopilot |
| Cross-Play      | GeyserMC & Floodgate                  | Optional; full Bedrock support with automatic fallbacks             |

## Installation Steps

1. Stop your server.
2. Download the latest `Freecarts-Spigot.jar` release.
3. Ensure `packetevents-spigot.jar` and `Vault.jar` are present in your `plugins/` directory.
4. Place `Freecarts-Spigot.jar` into your `plugins/` directory.
5. Start the server to generate default configurations and directory trees.

## Directory Structure

```
plugins/FreeCarts/
├── config.yml              # Core vehicle physics, fuel, economy, and database settings
├── autopilot.yml           # Autopilot pathfinding, hazard evasion, AR HUD, and depot parameters
├── server-depots.yml       # Registered public server depots
├── garage/
│   ├── garage-slots.yml    # Slot unlock costs and permission requirements
│   ├── garage-upgrades.yml # Progressive vehicle upgrade configurations
│   └── playerdata/         # Local YAML storage for player vehicles
├── lang/
│   ├── en_us.yml           # English localization
│   ├── ta_in.yml           # Tamil localization
│   ├── de_de.yml           # German localization
│   └── zh_cn.yml           # Simplified Chinese localization
└── models/
    ├── fuelstation/        # BlockDisplay models for 3D gas pumps (.txt and .meta)
    └── carts/
        ├── models.yml        # Custom cart model registrations and CustomModelData mappings
        └── paint_colors.yml  # Paint color definitions, costs, and hex palettes
```

## Automatic Configuration Merging

FreeCarts includes an integrated configuration updater. When upgrading between versions:

* Existing customized values are preserved.
* New settings and newly added localization keys merge automatically into `config.yml`, `autopilot.yml`, and language files on startup.
* Server administrators do not need to delete or recreate configuration files manually when updating the plugin.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://mavenverse.gitbook.io/mavenverse-docs/freecarts/overview-and-installation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.